@onebun/core 0.2.5 → 0.2.7

package/src/module/module.test.ts

@@ -24,7 +24,11 @@ import type {
 } from '../types';
 
 
-import { Controller as CtrlDeco, Module } from '../decorators/decorators';
+import {
+  Controller as CtrlDeco,
+  Middleware,
+  Module,
+} from '../decorators/decorators';
 import { makeMockLoggerLayer } from '../testing/test-utils';
 import { BaseWebSocketGateway } from '../websocket/ws-base-gateway';
 import { WebSocketGateway } from '../websocket/ws-decorators';
@@ -685,7 +689,7 @@ describe('OneBunModule', () => {
 
   describe('Controller DI with @Inject decorator', () => {
     const {
-      Inject, getConstructorParamTypes, Controller: ControllerDecorator, clearGlobalModules,
+      Inject: InjectDecorator, getConstructorParamTypes, Controller: ControllerDecorator, clearGlobalModules,
     } = require('../decorators/decorators');
     const { Controller: BaseController } = require('./controller');
     const { clearGlobalServicesRegistry: clearRegistry } = require('./module');
@@ -716,7 +720,7 @@ describe('OneBunModule', () => {
 
       // Define controller with @Inject BEFORE @Controller
       class OriginalController extends BaseController {
-        constructor(@Inject(SimpleService) private svc: SimpleService) {
+        constructor(@InjectDecorator(SimpleService) private svc: SimpleService) {
           super();
         }
       }
@@ -1189,6 +1193,55 @@ describe('OneBunModule', () => {
     });
   });
 
+  describe('Middleware with service injection', () => {
+    test('should resolve middleware with injected service and use it in use()', async () => {
+      @Service()
+      class HelperService {
+        getValue(): string {
+          return 'injected';
+        }
+      }
+
+      @Middleware()
+      class MiddlewareWithService extends BaseMiddleware {
+        constructor(private readonly helper: HelperService) {
+          super();
+        }
+
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>): Promise<OneBunResponse> {
+          const res = await next();
+          res.headers.set('X-Injected-Value', this.helper.getValue());
+
+          return res;
+        }
+      }
+
+      @CtrlDeco('/test')
+      class TestCtrl extends CtrlBase {}
+
+      @Module({
+        controllers: [TestCtrl],
+        providers: [HelperService],
+      })
+      class TestModule {}
+
+      const module = new OneBunModule(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      const resolved = module.resolveMiddleware([MiddlewareWithService]);
+      expect(resolved).toHaveLength(1);
+
+      const mockReq = Object.assign(new Request('http://localhost/'), {
+        params: {},
+        cookies: new Map(),
+      }) as unknown as OneBunRequest;
+      const next = async (): Promise<OneBunResponse> => new Response('ok');
+      const response = await resolved[0](mockReq, next);
+
+      expect(response.headers.get('X-Injected-Value')).toBe('injected');
+    });
+  });
+
   describe('Lifecycle hooks', () => {
     const { clearGlobalModules } = require('../decorators/decorators');
     const { clearGlobalServicesRegistry: clearRegistry, OneBunModule: ModuleClass } = require('./module');
@@ -1375,7 +1428,7 @@ describe('OneBunModule', () => {
     const {
       Controller: ControllerDecorator,
       Get,
-      Inject,
+      Inject: InjectDecorator,
       clearGlobalModules,
     } = require('../decorators/decorators');
     const { Controller: BaseController } = require('./controller');
@@ -1404,7 +1457,7 @@ describe('OneBunModule', () => {
       }
 
       class CounterController extends BaseController {
-        constructor(@Inject(CounterService) private readonly counterService: CounterService) {
+        constructor(@InjectDecorator(CounterService) private readonly counterService: CounterService) {
           super();
         }
         getCount() {
@@ -1439,7 +1492,7 @@ describe('OneBunModule', () => {
       }
 
       class ChildController extends BaseController {
-        constructor(@Inject(ChildService) private readonly childService: ChildService) {
+        constructor(@InjectDecorator(ChildService) private readonly childService: ChildService) {
           super();
         }
         getValue() {
@@ -1486,7 +1539,7 @@ describe('OneBunModule', () => {
       class SharedModule {}
 
       class AppController extends BaseController {
-        constructor(@Inject(SharedService) private readonly sharedService: SharedService) {
+        constructor(@InjectDecorator(SharedService) private readonly sharedService: SharedService) {
           super();
         }
         getLabel() {

package/src/module/module.ts

@@ -22,6 +22,7 @@ import {
   isGlobalModule,
   registerControllerDependencies,
 } from '../decorators/decorators';
+import { QueueService, QueueServiceTag } from '../queue';
 import { BaseWebSocketGateway } from '../websocket/ws-base-gateway';
 import { isWebSocketGateway } from '../websocket/ws-decorators';
 
@@ -616,6 +617,16 @@ export class OneBunModule implements ModuleInstance {
    * Resolve dependency by type (constructor function)
    */
   private resolveDependencyByType(type: Function): unknown {
+    // QueueService is registered by tag (QueueServiceTag) before setup(); resolve by tag
+    if (type === QueueService) {
+      const byTag = this.serviceInstances.get(
+        QueueServiceTag as Context.Tag<unknown, unknown>,
+      );
+      if (byTag !== undefined) {
+        return byTag;
+      }
+    }
+
     // Find service instance that matches the type
     const serviceInstance = Array.from(this.serviceInstances.values()).find((instance) => {
       if (!instance) {
@@ -974,6 +985,24 @@ export class OneBunModule implements ModuleInstance {
     return [];
   }
 
+  /**
+   * Get the module instance that owns the given controller.
+   * Used to resolve controller-level and route-level middleware with the owner module's DI.
+   */
+  getOwnerModuleForController(controllerClass: Function): ModuleInstance | undefined {
+    if (this.controllers.includes(controllerClass)) {
+      return this;
+    }
+    for (const childModule of this.childModules) {
+      const owner = childModule.getOwnerModuleForController(controllerClass);
+      if (owner) {
+        return owner;
+      }
+    }
+
+    return undefined;
+  }
+
   /**
    * Get all controller instances from this module and child modules (recursive).
    */
@@ -1023,6 +1052,13 @@ export class OneBunModule implements ModuleInstance {
     return this.rootLayer;
   }
 
+  /**
+   * Register a service instance by tag (e.g. before setup() for application-provided services like QueueService proxy).
+   */
+  registerService<T>(tag: Context.Tag<unknown, T>, instance: T): void {
+    this.serviceInstances.set(tag as Context.Tag<unknown, unknown>, instance);
+  }
+
   /**
    * Create a module from class
    * @param moduleClass - The module class

package/src/queue/docs-examples.test.ts

@@ -35,6 +35,7 @@ import {
   MessageAnyGuard,
   createMessageGuard,
   type Message,
+  type QueueAdapter,
   CronExpression,
   parseCronExpression,
   getNextRun,
@@ -113,9 +114,9 @@ describe('Setup Section Examples (docs/api/queue.md)', () => {
  * @source docs/api/queue.md#quick-start
  */
 describe('Quick Start Example (docs/api/queue.md)', () => {
-  it('should define service with queue decorators', () => {
-    // From docs/api/queue.md: Quick Start
-    class OrderService {
+  it('should define controller with queue decorators', () => {
+    // From docs/api/queue.md: Quick Start (queue handlers must be in controllers)
+    class EventProcessor {
       @OnQueueReady()
       onReady() {
         // console.log('Queue connected');
@@ -134,19 +135,19 @@ describe('Quick Start Example (docs/api/queue.md)', () => {
     }
 
     // Verify decorators are registered
-    expect(hasQueueDecorators(OrderService)).toBe(true);
+    expect(hasQueueDecorators(EventProcessor)).toBe(true);
 
-    const subscriptions = getSubscribeMetadata(OrderService);
+    const subscriptions = getSubscribeMetadata(EventProcessor);
     expect(subscriptions.length).toBe(1);
     expect(subscriptions[0].pattern).toBe('orders.created');
 
-    const cronJobs = getCronMetadata(OrderService);
+    const cronJobs = getCronMetadata(EventProcessor);
     expect(cronJobs.length).toBe(1);
     expect(cronJobs[0].expression).toBe(CronExpression.EVERY_HOUR);
     expect(cronJobs[0].options.pattern).toBe('cleanup.expired');
   });
 
-  it('should define service with interval decorator', () => {
+  it('should define controller with interval decorator', () => {
     // From docs/api/queue.md: Quick Start - Interval example
     class EventProcessor {
       @Subscribe('orders.created')
@@ -389,9 +390,9 @@ describe('Message Guards Examples (docs/api/queue.md)', () => {
  * @source docs/api/queue.md#lifecycle-decorators
  */
 describe('Lifecycle Decorators Examples (docs/api/queue.md)', () => {
-  it('should define lifecycle handlers', () => {
-    // From docs/api/queue.md: Lifecycle Decorators section
-    class EventService {
+  it('should define lifecycle handlers on controller', () => {
+    // From docs/api/queue.md: Lifecycle Decorators (handlers must be in controllers)
+    class EventProcessor {
       @OnQueueReady()
       handleReady() {
         // console.log('Queue connected');
@@ -418,8 +419,67 @@ describe('Lifecycle Decorators Examples (docs/api/queue.md)', () => {
       }
     }
 
-    // Class should be defined without errors
-    expect(EventService).toBeDefined();
+    // Class with lifecycle handlers only; hasQueueDecorators checks Subscribe/Cron/Interval/Timeout only
+    expect(EventProcessor).toBeDefined();
+  });
+});
+
+/**
+ * @source docs/api/queue.md#custom-adapter-nats-jetstream
+ */
+describe('Custom adapter NATS JetStream (docs/api/queue.md)', () => {
+  it('should use custom adapter constructor with options', async () => {
+    // From docs/api/queue.md: Custom adapter: NATS JetStream
+    // Minimal adapter class that implements QueueAdapter for use with queue: { adapter, options }
+    /* eslint-disable @typescript-eslint/no-empty-function */
+    class NatsJetStreamAdapter implements QueueAdapter {
+      readonly name = 'nats-jetstream';
+      readonly type = 'jetstream';
+      constructor(private opts: { servers: string; stream?: string }) {}
+      async connect(): Promise<void> {}
+      async disconnect(): Promise<void> {}
+      isConnected(): boolean {
+        return true;
+      }
+      async publish(): Promise<string> {
+        return '';
+      }
+      async publishBatch(): Promise<string[]> {
+        return [];
+      }
+      async subscribe(): Promise<import('./types').Subscription> {
+        return {
+          async unsubscribe() {},
+          pause() {},
+          resume() {},
+          pattern: '',
+          isActive: true,
+        };
+      }
+      async addScheduledJob(): Promise<void> {}
+      async removeScheduledJob(): Promise<boolean> {
+        return false;
+      }
+      async getScheduledJobs(): Promise<import('./types').ScheduledJobInfo[]> {
+        return [];
+      }
+      supports(): boolean {
+        return false;
+      }
+      on(): void {}
+      off(): void {}
+    }
+    /* eslint-enable @typescript-eslint/no-empty-function */
+
+    const adapter = new NatsJetStreamAdapter({
+      servers: 'nats://localhost:4222',
+      stream: 'EVENTS',
+    });
+    await adapter.connect();
+    expect(adapter.name).toBe('nats-jetstream');
+    expect(adapter.type).toBe('jetstream');
+    expect(adapter.isConnected()).toBe(true);
+    await adapter.disconnect();
   });
 });
 

package/src/queue/index.ts

@@ -113,6 +113,10 @@ export {
   createQueueService,
   resolveAdapterType,
 } from './queue.service';
+export {
+  QueueServiceProxy,
+  QUEUE_NOT_ENABLED_ERROR_MESSAGE,
+} from './queue-service-proxy';
 
 // Adapters (re-export from adapters folder)
 export * from './adapters';

package/src/queue/queue-service-proxy.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Tests for QueueServiceProxy
+ */
+
+import {
+  describe,
+  test,
+  expect,
+} from 'bun:test';
+
+
+import { InMemoryQueueAdapter } from './adapters/memory.adapter';
+import { QueueServiceProxy, QUEUE_NOT_ENABLED_ERROR_MESSAGE } from './queue-service-proxy';
+import { QueueService } from './queue.service';
+
+describe('QueueServiceProxy', () => {
+  test('throws with expected message when delegate is null', async () => {
+    const proxy = new QueueServiceProxy();
+    expect(() => proxy.getAdapter()).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.getScheduler()).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    await expect(proxy.publish('e', {})).rejects.toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    await expect(proxy.publishBatch([{ pattern: 'e', data: {} }])).rejects.toThrow(
+      QUEUE_NOT_ENABLED_ERROR_MESSAGE,
+    );
+    await expect(
+      proxy.subscribe('e', async () => {
+        /* no-op for throw test */
+      }),
+    ).rejects.toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    await expect(proxy.addScheduledJob('j', { pattern: 'e', schedule: { every: 1000 } })).rejects.toThrow(
+      QUEUE_NOT_ENABLED_ERROR_MESSAGE,
+    );
+    await expect(proxy.removeScheduledJob('j')).rejects.toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    await expect(proxy.getScheduledJobs()).rejects.toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() => proxy.supports('pattern-subscriptions')).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() =>
+      proxy.on('onReady', () => {
+        /* no-op */
+      }),
+    ).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+    expect(() =>
+      proxy.off('onReady', () => {
+        /* no-op */
+      }),
+    ).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+  });
+
+  test('delegates to real QueueService after setDelegate', async () => {
+    const adapter = new InMemoryQueueAdapter();
+    const real = new QueueService({ adapter: 'memory' as const });
+    await real.initialize(adapter);
+    await real.start();
+
+    const proxy = new QueueServiceProxy();
+    proxy.setDelegate(real);
+
+    expect(proxy.getAdapter()).toBe(adapter);
+    expect(proxy.getScheduler()).toBe(real.getScheduler());
+    expect(proxy.supports('pattern-subscriptions')).toBe(true);
+
+    const ids = await proxy.publish('test.event', { x: 1 });
+    expect(ids).toBeDefined();
+    expect(typeof ids).toBe('string');
+
+    const received: unknown[] = [];
+    const sub = await proxy.subscribe('test.event', async (msg) => {
+      received.push(msg.data);
+    });
+    expect(sub.isActive).toBe(true);
+
+    await proxy.publish('test.event', { y: 2 });
+    // Allow microtask for handler
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 10));
+    expect(received.length).toBe(1);
+    expect(received[0]).toEqual({ y: 2 });
+
+    await real.stop();
+    proxy.setDelegate(null);
+    expect(() => proxy.getAdapter()).toThrow(QUEUE_NOT_ENABLED_ERROR_MESSAGE);
+  });
+});

package/src/queue/queue-service-proxy.ts

@@ -0,0 +1,114 @@
+/**
+ * QueueServiceProxy — placeholder for DI when the real QueueService is created after setup().
+ * When the queue is enabled, the application sets the real QueueService via setDelegate().
+ * When the queue is not enabled, any method call throws a clear error.
+ */
+
+import type { QueueService } from './queue.service';
+import type { QueueScheduler } from './scheduler';
+import type { QueueAdapter } from './types';
+import type {
+  MessageHandler,
+  PublishOptions,
+  QueueEvents,
+  ScheduledJobInfo,
+  ScheduledJobOptions,
+  SubscribeOptions,
+  Subscription,
+  QueueFeature,
+} from './types';
+
+const QUEUE_NOT_ENABLED_MESSAGE =
+  'Queue is not enabled. Enable it via `queue.enabled: true` in application options or register at least one controller with queue decorators (@Subscribe, @Cron, @Interval, @Timeout).';
+
+function throwIfNoDelegate(delegate: QueueService | null): asserts delegate is QueueService {
+  if (delegate === null) {
+    throw new Error(QUEUE_NOT_ENABLED_MESSAGE);
+  }
+}
+
+/**
+ * Proxy for QueueService used in DI before the real service is created.
+ * After initializeQueue(), the application calls setDelegate(realQueueService) when the queue is enabled.
+ */
+export class QueueServiceProxy {
+  private delegate: QueueService | null = null;
+
+  setDelegate(service: QueueService | null): void {
+    this.delegate = service;
+  }
+
+  getAdapter(): QueueAdapter {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.getAdapter();
+  }
+
+  getScheduler(): QueueScheduler {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.getScheduler();
+  }
+
+  async publish<T>(pattern: string, data: T, options?: PublishOptions): Promise<string> {
+    throwIfNoDelegate(this.delegate);
+
+    return await this.delegate.publish(pattern, data, options);
+  }
+
+  async publishBatch<T>(
+    messages: Array<{ pattern: string; data: T; options?: PublishOptions }>,
+  ): Promise<string[]> {
+    throwIfNoDelegate(this.delegate);
+
+    return await this.delegate.publishBatch(messages);
+  }
+
+  async subscribe<T>(
+    pattern: string,
+    handler: MessageHandler<T>,
+    options?: SubscribeOptions,
+  ): Promise<Subscription> {
+    throwIfNoDelegate(this.delegate);
+
+    return await this.delegate.subscribe(pattern, handler, options);
+  }
+
+  async addScheduledJob(name: string, options: ScheduledJobOptions): Promise<void> {
+    throwIfNoDelegate(this.delegate);
+
+    return await this.delegate.addScheduledJob(name, options);
+  }
+
+  async removeScheduledJob(name: string): Promise<boolean> {
+    throwIfNoDelegate(this.delegate);
+
+    return await this.delegate.removeScheduledJob(name);
+  }
+
+  async getScheduledJobs(): Promise<ScheduledJobInfo[]> {
+    throwIfNoDelegate(this.delegate);
+
+    return await this.delegate.getScheduledJobs();
+  }
+
+  supports(feature: QueueFeature): boolean {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.supports(feature);
+  }
+
+  on<E extends keyof QueueEvents>(event: E, handler: NonNullable<QueueEvents[E]>): void {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.on(event, handler);
+  }
+
+  off<E extends keyof QueueEvents>(event: E, handler: NonNullable<QueueEvents[E]>): void {
+    throwIfNoDelegate(this.delegate);
+
+    return this.delegate.off(event, handler);
+  }
+}
+
+export const QUEUE_NOT_ENABLED_ERROR_MESSAGE = QUEUE_NOT_ENABLED_MESSAGE;

package/src/queue/types.ts

@@ -395,8 +395,8 @@ export interface QueueAdapterConstructor {
  * Queue configuration options
  */
 export interface QueueConfig {
-  /** Adapter type or custom adapter class */
-  adapter: BuiltInAdapterType | QueueAdapterConstructor;
+  /** Adapter type (built-in or custom, e.g. 'jetstream') or custom adapter class */
+  adapter: QueueAdapterType | QueueAdapterConstructor;
 
   /** Adapter-specific options */
   options?: Record<string, unknown>;

package/src/types.ts

@@ -1,9 +1,15 @@
 import type { BaseMiddleware } from './module/middleware';
+import type { QueueAdapterConstructor } from './queue/types';
 import type { Type } from 'arktype';
-import type { Effect, Layer } from 'effect';
+import type {
+  Context,
+  Effect,
+  Layer,
+} from 'effect';
 
 import type { Logger, LoggerOptions } from '@onebun/logger';
 
+
 /**
  * HTTP Request type used in OneBun controllers.
  * Extends standard Web API Request with:
@@ -163,11 +169,23 @@ export interface ModuleInstance {
    */
   getModuleMiddleware?(controllerClass: Function): Function[];
 
+  /**
+   * Get the module instance that owns the given controller (the module in whose
+   * `controllers` array the controller is declared). Returns this module or a
+   * child module, or undefined if the controller is not in this module tree.
+   */
+  getOwnerModuleForController?(controllerClass: Function): ModuleInstance | undefined;
+
   /**
    * Resolve middleware class constructors into bound `use()` functions
    * using this module's DI scope (services + logger + config).
    */
   resolveMiddleware?(classes: Function[]): Function[];
+
+  /**
+   * Register a service instance by tag (e.g. before setup() for application-provided services like QueueService proxy).
+   */
+  registerService?<T>(tag: Context.Tag<unknown, T>, instance: T): void;
 }
 
 /**
@@ -415,6 +433,12 @@ export interface ApplicationOptions {
    */
   queue?: QueueApplicationOptions;
 
+  /**
+   * Static file serving: serve files from a directory for requests not matched by API routes.
+   * Optional path prefix and fallback file (e.g. index.html) for SPA-style routing.
+   */
+  static?: StaticApplicationOptions;
+
   /**
    * Documentation configuration (OpenAPI/Swagger)
    */
@@ -460,8 +484,10 @@ export type QueueAdapterType = 'memory' | 'redis';
 export interface QueueApplicationOptions {
   /** Enable/disable queue (default: auto - enabled if handlers exist) */
   enabled?: boolean;
-  /** Adapter type or custom adapter instance */
-  adapter?: QueueAdapterType;
+  /** Adapter type, or custom adapter constructor (e.g. for NATS JetStream) */
+  adapter?: QueueAdapterType | QueueAdapterConstructor;
+  /** Options passed to the custom adapter constructor when adapter is a class */
+  options?: unknown;
   /** Redis-specific options (only used when adapter is 'redis') */
   redis?: {
     /** Use shared Redis provider instead of dedicated connection */
@@ -521,6 +547,39 @@ export interface WebSocketApplicationOptions {
   maxPayload?: number;
 }
 
+/**
+ * Static file serving configuration for OneBunApplication.
+ * Serves files from a directory for requests not matched by API/ws/docs/metrics routes.
+ */
+export interface StaticApplicationOptions {
+  /**
+   * Filesystem path to the directory to serve (static root).
+   * Can be absolute or relative to the process cwd.
+   */
+  root: string;
+
+  /**
+   * URL path prefix under which static files are served.
+   * Empty or '/' means "everything not matched by API routes".
+   * Example: '/app' — only paths starting with /app are served from static root
+   * (the prefix is stripped when resolving the file path).
+   */
+  pathPrefix?: string;
+
+  /**
+   * Fallback file name (e.g. 'index.html') for SPA-style client-side routing.
+   * When the requested file is not found, this file under static root is returned instead.
+   */
+  fallbackFile?: string;
+
+  /**
+   * TTL in milliseconds for caching file existence checks.
+   * Reduces disk I/O for repeated requests. Use 0 to disable caching.
+   * @defaultValue 60000
+   */
+  fileExistenceCacheTtlMs?: number;
+}
+
 /**
  * Documentation configuration for OneBunApplication
  * Enables automatic OpenAPI spec generation and Swagger UI