Features Overview

OneBun is a complete, batteries-included backend framework for Bun.js. It provides everything needed to build production-grade TypeScript services — from HTTP routing to database integration, from message queues to observability.

At a Glance

• NestJS-style architecture — modules, controllers and services with full dependency injection via Effect.ts
• ArkType validation — one schema is the TypeScript type, the runtime check and the OpenAPI spec, wired end to end
• Built-in Prometheus metrics and OpenTelemetry tracing — no community packages needed
• Redis / in-memory caching with decorator-driven TTL
• Typed environment variables with validation and defaults
• WebSocket support — Socket.IO protocol, rooms, guards, and a client for Bun
• Queue system — @Cron, @Interval, @Timeout and @Subscribe decorators
• Drizzle ORM integration — database access with migrations
• NATS / JetStream — message bus for microservices
• OpenAPI / Swagger — generated from ArkType schemas and route decorators

Each of these is broken down below, and compared against other frameworks in Framework Comparison.

Core Framework (@onebun/core)

Dependency Injection & Modules

NestJS-inspired module system with automatic constructor-based DI, module imports/exports, and service scoping. → API Reference

Controllers & Routing

Decorator-based HTTP controllers with @Get, @Post, @Put, @Delete, @Patch. Path parameters, query parameters, body parsing, header extraction. Standardized ApiResponse format across the application. → API Reference

Guards

One @UseGuards() across HTTP routes, WebSocket @OnMessage handlers and queue @Subscribe consumers — class-level or method-level, with constructor DI on all three. Denial per transport: HTTP 403 (200 with httpEnvelope), a WebSocket error frame that leaves the socket open, a queue nack(false) with no redelivery. → API Reference

Interceptors

Universal handler wrapping across HTTP, WebSocket, and Queue transports. Use @UseInterceptors() at any level. Built-in: LoggingInterceptor, TimeoutInterceptor, CacheInterceptor. → API Reference

Middleware

Request/response middleware with @UseMiddleware decorator. Supports middleware chaining on individual routes. → API Reference

File Upload

Built-in multipart/form-data and JSON+base64 file upload support. @UploadedFile() for single files, @UploadedFiles() for multiple, @FormField() for non-file form fields — all with automatic content type detection. → API Reference

Cookie Handling

Extract cookie values directly with @Cookie() decorator. Works alongside @Header(), @Query(), and other parameter decorators. → API Reference

Static file serving

Serve a static directory (e.g. SPA build) from the same host and port as the API. Configure static.root, optional pathPrefix and fallbackFile (e.g. index.html) for client-side routing. → API Reference

WebSocket (@onebun/core)

WebSocket Gateway

Decorator-based WebSocket handlers with @WebSocketGateway, @OnMessage. Built on Bun's native WebSocket support for maximum performance.

Socket.IO Support

Optional Socket.IO adapter for browser compatibility, rooms and broadcasting.

WebSocket Client

createWsClient (gateways found by name from your module's definition) and createNativeWsClient (no definition) speak the native and Socket.IO protocols, with reconnection and acknowledgements. Event names and payloads are not type-checked. The clients run in Bun; @onebun/core cannot currently be bundled for a browser, which uses WebSocket or socket.io-client instead. → API Reference

Microservices (@onebun/core)

OneBunApplication Multi-Service Mode

Run multiple services from a single codebase and Docker image:

• Development: all services in one process (bun run src/index.ts)
• Production: one service per process (ONEBUN_SERVICES=users bun run src/index.ts)
• Flexible: any combination via environment variables

Inter-Service Communication

HTTP clients built from the callee's module with createServiceDefinition + createServiceClient. HMAC authentication for service-to-service calls.

Kubernetes-Ready

Environment-based service selection, external service URL configuration, single Docker image for all services. → Multi-Service Example

Validation (@onebun/core + ArkType)

Out-of-the-Box Validation

ArkType is re-exported from @onebun/core — no additional packages, no bridge libraries, no Swagger patches. One schema gives you:

• TypeScript type (compile-time safety)
• Runtime validation (request body, query params)
• OpenAPI 3.1 schema (auto-generated documentation)

Install the framework — validation and OpenAPI work. No nestjs-zod, no patchNestJsSwagger(), no setup.

@Body() Validation

Pass ArkType schema to @Body decorator for automatic validation with typed error responses. → API Reference

API Documentation (@onebun/docs)

OpenAPI Auto-Generation

Automatic OpenAPI 3.1 spec from decorators and ArkType schemas. Install @onebun/docs and get Swagger UI with zero configuration.

Documentation Decorators

@ApiTags, @ApiOperation, @ApiResponse for additional metadata. → API Reference

Database (@onebun/drizzle)

Drizzle ORM Integration

Schema-first approach with full type inference. Supports PostgreSQL and SQLite (via bun:sqlite).

Migrations

• CLI: bunx onebun-drizzle generate / push / studio
• Programmatic: generateMigrations(), pushSchema()
• Auto-migrate on startup (enabled by default — no configuration needed)
• A configured database is required at boot: an unreachable server or a failing migration makes app.start() reject before the HTTP server binds. Opt out with allowDegradedStart: true in forRoot(), or DB_ALLOW_DEGRADED_START=true on the environment path. → Startup Contract

Repository Pattern

BaseRepository with built-in CRUD operations, custom queries via Drizzle query builder. → API Reference

Queue & Scheduler (@onebun/core + @onebun/nats)

Queue System

Background job processing with multiple backends:

• In-memory — zero config, for development and simple use cases
• Redis Pub/Sub — distributed queues via Redis
• NATS — high-performance messaging (via @onebun/nats)
• JetStream — persistent, at-least-once delivery (via @onebun/nats)

Scheduler

Cron-like task scheduling with the same backend options. → API Reference

Caching (@onebun/cache)

CacheModule

• In-memory cache — with TTL, max size, cleanup intervals
• Redis cache — with shared connection pool support. Choosing it makes Redis a startup dependency: unreachable within connectTimeout (default 5000ms) and app.start() fails without the listener ever opening, unless allowDegradedStart: true / CACHE_ALLOW_DEGRADED_START=true accepts a process-local cache instead. getBackendStatus() reports which backend is actually serving.
• Batch operations: mget, mset
• Cache-aside, invalidation, and warming patterns → API Reference

HTTP Client (@onebun/requests)

createHttpClient()

Full-featured HTTP client with:

• Authentication: Bearer, API Key, Basic, HMAC (inter-service)
• Retries: fixed, linear, exponential backoff — idempotent methods only by default; POST and PATCH must opt in via retries.methods. See the defaults table.
• Typed responses: ApiResponse<T> with success/error discrimination; a success carries the upstream statusCode and response headers (see Success Response)
• Bounded responses: maxResponseBytes caps the decoded body while it is read, so a gzip bomb or an oversized error body stops at the limit (see Limiting the response size)
• Redirects: followed by the client with no credential crossing to another origin, refused with redirect: 'error', or handed back with redirect: 'manual' (see Redirect policy)
• Binary and streamed bodies: responseType: 'bytes' hands a body over as a Uint8Array, and responseType: 'stream' resolves at the headers with a ReadableStream, so a server-sent event stream or a long download is read as it arrives (see Response types)
• Validated addresses: connectAddress connects a request to an IP address the application looked up and checked itself, so a second lookup cannot answer differently; Host, the TLS SNI and the certificate check keep the URL's host name (see Connecting to a validated address)

Service Clients

createServiceDefinition() + createServiceClient() call another OneBun service by controller and method name, with the routes reflected from its module at run time. The names are checked when they are read; arguments and results are untyped (any). → API Reference

Observability

Prometheus Metrics (@onebun/metrics)

• Automatic HTTP request metrics (duration, count, status codes)
• System metrics (CPU, memory, event loop, GC)
• Custom metrics: Counter, Gauge, Histogram
• Decorator-based: @Timed(), @Counted(), @Gauged()
• Endpoint: GET /metrics → API Reference

OpenTelemetry Tracing (@onebun/trace)

• Automatic HTTP request tracing
• @Span() decorator for custom spans
• Trace context propagation in logs
• Configurable sampling, export to external collectors → API Reference

Structured Logging (@onebun/logger)

• JSON (production) and pretty (development) output
• Log levels: trace, debug, info, warn, error, fatal
• Child loggers with context inheritance
• Automatic trace context in log entries → API Reference

Configuration (@onebun/envs)

Type-Safe Environment Variables

• Schema definition with Env.string(), Env.number(), Env.boolean(), Env.array()
• Validation, defaults, transforms
• Sensitive value masking in logs
• .env file support
• Per-service overrides in OneBunApplication multi-service mode → API Reference

Production Features

Graceful Shutdown

Enabled by default. On SIGTERM/SIGINT the application first refuses new requests with 503 while the listener stays open, drains the requests already being served, and only then closes the listener and runs the destroy hooks — so a rolling deploy does not cut responses that are mid-flight. Bounded by shutdownTimeout (default 15s), idempotent, and in multi-service mode a single parent handler stops every service.

Shared Redis Connection

Single Redis connection pool shared between Cache, WebSocket, and Queue modules. Reduced memory footprint and connection count.

Effect.js Integration

Internal architecture built on Effect.js for type-safe side effect management. Optional Effect API for advanced use cases.

For NestJS Developers

If you're coming from NestJS, here's what to expect:

Same patterns

• @Module, @Controller, @Service decorators
• Constructor-based dependency injection
• Module imports/exports for service sharing
• Guards for route protection — and in OneBun the same decorator covers WebSocket and queue handlers too
• Middleware support

Improved in OneBun

• Validation: ArkType schema = TypeScript type = OpenAPI spec = runtime validation, wired out of the box (NestJS teams can achieve similar workflows with nestjs-zod — OneBun ships it without extra packages)
• Microservices: Single Docker image, env-based service selection (vs separate entry points in NestJS)
• Observability: Prometheus metrics + OpenTelemetry tracing built-in (vs community packages in NestJS)
• Performance: Bun.js native, no Express/Fastify adapter layer
• Configuration: Type-safe env schema with sensitive value masking (vs @nestjs/config)

Different approach

• ArkType instead of class-validator/class-transformer
• Drizzle ORM instead of TypeORM (schema-first, not entity-first)
• Effect.js internally (optional for application code)
• Bun.js runtime only (not Node.js compatible)

Not yet available

• GraphQL integration (post-1.0 consideration)
• CQRS module
• Extensive third-party ecosystem

Feature Comparison

How OneBun compares to other TypeScript backend frameworks.

Legend: ✅ built-in · 🔌 plugin/adapter · 👥 community · ❌ none

Feature	OneBun	NestJS	Hono	Elysia
DI / IoC container	✅ Effect.Context	✅ Custom container	❌	❌
Module system	✅ @Module	✅ @Module	❌	❌
Decorator routing	✅	✅	❌	✅
Guards / Auth	✅	✅	👥	👥
Middleware	✅	✅	✅	✅
Validation	✅ ArkType	🔌 class-validator	👥	✅ TypeBox
OpenAPI generation	✅ Auto from schemas	🔌 @nestjs/swagger	👥	✅
WebSocket	✅ Native + Socket.IO	🔌 @nestjs/websockets	👥	✅
File upload	✅	🔌 multer	👥	✅
Queue / Scheduler	✅ In-memory, Redis, NATS	🔌 @nestjs/bull	❌	❌
Prometheus metrics	✅ @onebun/metrics	👥	❌	❌
OpenTelemetry tracing	✅ @onebun/trace	👥	👥	👥
Structured logging	✅ @onebun/logger	👥	👥	👥
Database (ORM)	✅ Drizzle	🔌 TypeORM/Prisma	❌	❌
Caching	✅ In-memory + Redis	🔌 @nestjs/cache-manager	❌	❌
Env validation	✅ @onebun/envs	🔌 @nestjs/config	❌	❌
Multi-service	✅ Single image	❌	❌	❌
Graceful shutdown	✅	🔌	❌	❌
GraphQL	❌ (post-1.0)	🔌 @nestjs/graphql	👥	👥
Interceptors / Pipes	✅	✅	❌	✅ hooks
CQRS	❌	🔌 @nestjs/cqrs	❌	❌
Node.js support	❌ Bun only	✅	✅	❌ Bun only
Third-party ecosystem	🆕 Growing	✅ Mature	✅ Growing	👥 Growing