# OneBun Framework

> A complete, batteries-included TypeScript backend framework for Bun.js

One framework. One runtime. Everything you need for production backend services.

## Table of Contents

### Introduction

- [OneBun Framework — Complete Documentation](/features.md): Complete overview of OneBun Framework capabilities — DI, WebSocket, microservices, validation, database, queue, cache, observability, and production features.
- [Getting Started with OneBun](/getting-started.md): Installation and basic setup guide for OneBun framework. Prerequisites, project structure, modules, controllers, services.
- [OneBun Architecture](/architecture.md): System architecture overview. Module hierarchy, DI container, request lifecycle, Effect.js integration patterns.

### Core Framework

- [Core Package API](/api/core.md): OneBunApplication, MultiServiceApplication classes. Bootstrap options, graceful shutdown, metrics and tracing configuration.
- [Decorators API](/api/decorators.md): @Module, @Controller, @Service decorators. HTTP method decorators (@Get, @Post, etc). Parameter decorators (@Param, @Query, @Body).
- [Controllers API](/api/controllers.md): BaseController class, response methods (success/error), routing patterns, middleware integration, service injection.
- [Services API](/api/services.md): BaseService class, @Service decorator, dependency injection patterns, service lifecycle, Effect.js integration.
- [Validation API](/api/validation.md): Schema validation with ArkType. validate(), validateOrThrow(), toJsonSchema(). Built-in schema helpers.
- [HTTP Guards](/api/guards.md): HTTP Guards — authorization and access control for routes and controllers.
- [Exception Filters](/api/exception-filters.md): Exception Filters — centralized, type-safe error handling for HTTP routes.
- [Security Middleware](/api/security.md): Built-in security middleware — CORS, rate limiting, and HTTP security headers.

### Communication

- [WebSocket Gateway API](/api/websocket.md): @WebSocketGateway decorator, message handlers (@OnMessage, @OnConnect), rooms, guards, native WebSocket and Socket.IO.
- [HTTP Client API](/api/requests.md): HTTP client with createHttpClient(). Retries, timeouts, error handling. Promise and Effect API. Authentication helpers.
- [API Documentation (OpenAPI)](/api/docs.md): Automatic OpenAPI 3.1 documentation generation from decorators and ArkType schemas. Swagger UI, @ApiTags, @ApiOperation setup.

### Data & State

- [Database (Drizzle) API](/api/drizzle.md): DrizzleModule for SQLite and PostgreSQL. DrizzleService, BaseRepository, @Entity decorator. Migrations, type-safe queries.
- [Cache API](/api/cache.md): CacheModule for in-memory and Redis caching. CacheService methods, TTL configuration, cache statistics.
- [Queue API](/api/queue.md): Message queues with @Subscribe, @Cron, @Interval decorators. In-memory, Redis, NATS, JetStream backends. Message guards.

### Observability

- [Logger API](/api/logger.md): Structured logging with SyncLogger. Log levels, JSON/pretty output, trace context, child loggers with context inheritance.
- [Metrics API](/api/metrics.md): Prometheus-compatible metrics. @MeasureTime, @CountCalls decorators. HTTP, system, GC metrics. Custom counters, gauges, histograms.
- [Tracing API](/api/trace.md): Distributed tracing with @Span decorator. TraceService, W3C trace context, span attributes, OpenTelemetry-compatible export.

### Configuration

- [Environment Configuration API](/api/envs.md): Type-safe environment configuration. Env.string(), Env.number(), Env.boolean(). Validation, defaults, sensitive data handling.

### Testing

- [Testing](/testing.md): Testing utilities for OneBun applications — unit testing helpers, integration testing module, fake timers, mock loggers, and testcontainers.

### Examples

- [Basic Application Example](/examples/basic-app.md): Minimal OneBun application example. Single controller and service, project structure, running and testing.
- [CRUD API Example](/examples/crud-api.md): Complete CRUD API example with database, validation, error handling. REST endpoints, repository pattern.
- [Multi-Service Application Example](/examples/multi-service.md): Running multiple microservices from single process. MultiServiceApplication, shared config, service communication.
- [WebSocket Chat Application](/examples/websocket-chat.md): Real-time chat application with WebSocket Gateway. Rooms, message broadcasting, connection handling.

### AI Documentation

- [AI Documentation](/ai-docs.md): How to use OneBun documentation with AI assistants and coding agents.

### Project

- [Roadmap](/roadmap.md)