# Talos

> Talos is a modular TypeScript framework built on the [Bun](https://bun.sh) runtime. It provides a rich ecosystem of 50+ independently versioned packages under the `@talos` namespace, covering dependency injection, routing, database management, caching, authentication, real-time communication, and more.

Key characteristics:

- **Modular** — Use only the packages you need. Each package is independently versioned and published to npm under `@talosjs/*`.
- **Dependency injection** — Built on [InversifyJS](https://inversify.io/) with decorator-driven service registration and lifecycle scopes (singleton, transient, request-scoped).
- **Decorator-driven** — Routes, services, repositories, and middlewares are defined with expressive decorators.
- **Type-safe** — Strict TypeScript with runtime validation via [ArkType](https://arktype.io/).
- **Bun-first** — Optimized for Bun with fast builds via [bunup](https://github.com/nicepkg/bunup) and the native Bun test runner. Managed as an [Nx](https://nx.dev) monorepo, linted/formatted with [Biome](https://biomejs.dev).

Naming conventions are enforced by decorators at registration time: services end in `Service`, repositories in `Repository`, middlewares in `Middleware`.

## Documentation

- [README](https://github.com/Talos/Talos/blob/main/README.md): Project overview, getting started, usage examples, and architecture.
- [AGENTS.md](https://github.com/Talos/Talos/blob/main/AGENTS.md): Conventions and guidance for AI agents and contributors working in the monorepo.

## Core packages

- `@talosjs/container`: Dependency injection container built on Inversify with singleton, transient, and request-scoped lifecycles and automatic dependency resolution.
- `@talosjs/exception`: Structured exception handling with HTTP status code mapping, typed error data, and JSON-formatted stack traces.
- `@talosjs/types`: Shared TypeScript type definitions, interfaces, and utility types used across the ecosystem.
- `@talosjs/http-status`: Complete HTTP status code library with TypeScript enums for 1xx–5xx and helper utilities for classification and messaging.
- `@talosjs/utils`: General-purpose utilities including nanoid-based unique ID generation, type guards, and common helpers.

## Application packages

- `@talosjs/app`: Full-featured application framework for Bun — orchestrates routing, middleware pipelines, dependency injection, caching, logging, and WebSocket support.
- `@talosjs/app-env`: Environment detection and configuration for development, staging, production, and testing.
- `@talosjs/routing`: Decorator-driven HTTP routing with path parameters, validation constraints, permission guards, and named route generation.
- `@talosjs/controller`: HTTP controller layer with decorator-based route binding and request/response handling.
- `@talosjs/middleware`: Middleware pipeline framework with decorator-based registration for HTTP requests, responses, and WebSocket events.
- `@talosjs/module`: Module system that groups controllers, entities, services, and middleware by domain.

## HTTP packages

- `@talosjs/http-request`: HTTP request abstraction with URL parsing, query parameters, language detection, header management, and multipart uploads.
- `@talosjs/http-request-file`: Multipart file upload handler with MIME validation, size constraints, and temporary file management.
- `@talosjs/http-response`: HTTP response builder with a fluent API for status codes, headers, cookies, and streaming or buffered content.
- `@talosjs/http-header`: HTTP header parser with user agent detection, browser fingerprinting, device identification, and content negotiation.
- `@talosjs/http-mimes`: MIME type registry with TypeScript constants and lookup utilities for content type negotiation and file detection.
- `@talosjs/url`: URL parsing and manipulation with query string handling, path normalization, and route parameter extraction.
- `@talosjs/fetcher`: Lightweight HTTP client with typed headers, response parsing, and configurable request handling for external APIs.

## Data packages

- `@talosjs/database`: Database abstraction layer with TypeORM integration — connection pooling, query building, and migration support.
- `@talosjs/entity`: Base entity classes and decorators for type-safe column mappings, relationships, and lifecycle hooks.
- `@talosjs/repository`: Data access layer with decorator-based repository registration, query abstraction, and dependency injection.
- `@talosjs/migrations`: Database migration runner with versioned schema changes, rollback support, and execution logging.
- `@talosjs/seeds`: Database seeding framework for initial data, fixtures, and test datasets with idempotent operations.
- `@talosjs/cache`: High-performance caching with filesystem and Redis backends — TTL expiration, auto-serialization, and configurable size limits.
- `@talosjs/validation`: Type-safe validation framework powered by ArkType with built-in constraints, custom rules, and JSON Schema generation.

## Security packages

- `@talosjs/auth`: Authentication framework with pluggable token-based and session-based strategies.
- `@talosjs/jwt`: JWT toolkit using JOSE — generate, sign, verify, and decode tokens with support for multiple algorithms.
- `@talosjs/permission`: Fine-grained access control using CASL — define, evaluate, and enforce ability-based permissions with role and resource scoping.
- `@talosjs/role`: Role-based authorization types and utilities for roles, hierarchies, and access levels in multi-tenant apps.
- `@talosjs/rate-limit`: API rate limiting with configurable throttling, sliding window counters, and per-client request quotas.
- `@talosjs/user`: User identity types and interfaces for profiles, credentials, roles, and account metadata.

## Service packages

- `@talosjs/service`: Service layer foundation with decorator-based registration and dependency injection for business logic.
- `@talosjs/logger`: Structured logging with multiple output targets, log level filtering, contextual metadata, and DI integration.
- `@talosjs/mailer`: Transactional email service supporting Nodemailer SMTP and the Resend API — templated emails with attachments and delivery tracking.
- `@talosjs/storage`: File storage abstraction over local filesystem and cloud providers with a unified bucket-based API.
- `@talosjs/cron`: Cron job scheduler with timezone-aware scheduling, task lifecycle management, and structured logging.
- `@talosjs/event`: Event messaging system for decoupled, event-driven communication with typed event channels.
- `@talosjs/analytics`: PostHog-powered analytics for tracking user behavior, product events, and feature usage with decorator-based registration.
- `@talosjs/queue`: Background job and message queue processing.
- `@talosjs/workflow`: Workflow orchestration utilities.
- `@talosjs/command`: Command framework for building CLI commands with dependency injection, argument parsing, and execution logging.
- `@talosjs/feature-flag`: Define and evaluate feature flags as injectable, named toggles with descriptions and dynamic enablement.

## Real-time & communication packages

- `@talosjs/socket`: WebSocket server with room management, event broadcasting, client tracking, and middleware integration.
- `@talosjs/socket-client`: WebSocket client with automatic reconnection, event handling, and typed message serialization.

## AI & content packages

- `@talosjs/ai`: AI toolkit integrating 300+ models via OpenRouter with a unified API for text generation, streaming, and content transformation.
- `@talosjs/rag`: Retrieval-Augmented Generation toolkit with vector database integration, document embedding, and semantic search.
- `@talosjs/pdf`: PDF toolkit for generating, editing, merging, splitting, and converting PDFs to images with page-level content extraction.
- `@talosjs/html`: HTML parsing and DOM manipulation powered by Cheerio — extract, transform, and query HTML with a jQuery-like API.
- `@talosjs/translation`: Internationalization framework with locale management, translation key resolution, and pluralization.
- `@talosjs/youtube`: YouTube video downloader and metadata extraction for video info, thumbnails, and media streams.
- `@talosjs/youtube-utils`: YouTube URL utilities for extracting video IDs and generating embed or watch URLs.

## Utility packages

- `@talosjs/fs`: Async file system utilities for reading, writing, copying, and watching files and directories with type-safe error handling.
- `@talosjs/country`: Country metadata with timezone data, ISO codes, and multi-language localization.
- `@talosjs/currencies`: Currency dataset with ISO 4217 codes, symbols, names, and TypeScript types for financial and e-commerce apps.
- `@talosjs/color`: Curated color palette with hex values, human-friendly names, and TypeScript types for UI theming.
- `@talosjs/csv`: CSV file loader and parser with streaming support and generator-based iteration.
- `@talosjs/json`: JSON file loader and parser with streaming support and generator-based iteration.
- `@talosjs/yml`: YAML file loader and parser using Bun's built-in YAML support with generator-based streaming.
- `@talosjs/hour-utils`: Time unit conversion utilities for hours, minutes, seconds, and milliseconds.
- `@talosjs/linear`: Linear project management integration — manage issues, teams, and projects via the Linear API with DI support.
- `@talosjs/payment`: Payment and pricing type definitions with currency handling, product categorization, and billing metadata.
- `@talosjs/cli`: Interactive CLI toolkit for scaffolding projects, modules, controllers, services, repositories, and more from customizable templates.

## Optional

- [GitHub repository](https://github.com/Talos/Talos): Source code, issues, and releases.
- [Bun](https://bun.sh): The runtime Talos targets.
- [InversifyJS](https://inversify.io/): The DI library underpinning the container.
- [ArkType](https://arktype.io/): Runtime validation library used across packages.