@onebun/core 0.2.13 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",
@@ -46,7 +46,7 @@
     "effect": "^3.13.10",
     "arktype": "^2.0.0",
     "@onebun/logger": "^0.2.1",
-    "@onebun/envs": "^0.2.1",
+    "@onebun/envs": "^0.2.2",
     "@onebun/metrics": "^0.2.2",
     "@onebun/requests": "^0.2.1",
     "@onebun/trace": "^0.2.1"

package/src/application/application.ts

@@ -246,7 +246,8 @@ function resolvePathUnderRoot(rootDir: string, relativePath: string): string | n
 /**
  * OneBun Application
  */
-export class OneBunApplication {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class OneBunApplication<QA extends import('../queue/types').QueueAdapterConstructor<any> = import('../queue/types').QueueAdapterConstructor> {
   private rootModule: ModuleInstance | null = null;
   private server: ReturnType<typeof Bun.serve> | null = null;
   private options: ApplicationOptions;
@@ -272,7 +273,7 @@ export class OneBunApplication {
    */
   constructor(
     moduleClass: new (...args: unknown[]) => object,
-    options?: Partial<ApplicationOptions>,
+    options?: Partial<ApplicationOptions<QA>>,
   ) {
     this.moduleClass = moduleClass;
 

package/src/docs-examples.test.ts

@@ -37,6 +37,7 @@ import type {
   OnApplicationDestroy,
 } from './';
 import type { ExceptionFilter } from './exception-filters/exception-filters';
+import type { QueueAdapter, QueueAdapterConstructor } from './queue/types';
 import type {
   SseEvent,
   SseGenerator,
@@ -44,6 +45,7 @@ import type {
   OneBunResponse,
   MiddlewareClass,
   OnModuleConfigure,
+  QueueApplicationOptions,
 } from './types';
 import type { HttpExecutionContext } from './types';
 import type { ServerWebSocket } from 'bun';
@@ -5706,3 +5708,96 @@ describe('docs/api/security.md', () => {
     expect(res.headers.get('Strict-Transport-Security')).toBeNull();
   });
 });
+
+// ============================================================================
+// docs/api/queue.md — Type-safe queue adapter configuration
+// ============================================================================
+describe('docs/api/queue.md — type-safe adapter options', () => {
+  // Minimal custom adapter for type-checking purposes
+  interface CustomAdapterOptions {
+    servers: string;
+    streams?: Array<{ name: string; subjects: string[] }>;
+  }
+
+  class CustomAdapter implements QueueAdapter {
+    readonly name = 'custom';
+    readonly type = 'jetstream' as const;
+    constructor(private opts: CustomAdapterOptions) {}
+    async connect() { /* noop */ }
+    async disconnect() { /* noop */ }
+    isConnected() {
+      return true; 
+    }
+    async publish() {
+      return ''; 
+    }
+    async publishBatch() {
+      return []; 
+    }
+    async subscribe() {
+      return {
+        async unsubscribe() { /* noop */ },
+        pause() { /* noop */ },
+        resume() { /* noop */ },
+        pattern: '',
+        isActive: true,
+      };
+    }
+    supports() {
+      return false; 
+    }
+    on() { /* noop */ }
+    off() { /* noop */ }
+  }
+
+  it('QueueApplicationOptions infers options type from adapter constructor', () => {
+    // When adapter is a specific class, options should be typed as its constructor argument
+    const queueOpts: QueueApplicationOptions<typeof CustomAdapter> = {
+      adapter: CustomAdapter,
+      options: {
+        servers: 'nats://localhost:4222',
+        streams: [{ name: 'EVENTS', subjects: ['events.>'] }],
+      },
+    };
+
+    expect(queueOpts.adapter).toBe(CustomAdapter);
+    expect(queueOpts.options?.servers).toBe('nats://localhost:4222');
+  });
+
+  it('QueueApplicationOptions works with string adapter type (backward compatibility)', () => {
+    const queueOpts: QueueApplicationOptions = {
+      adapter: 'memory',
+      enabled: true,
+    };
+
+    expect(queueOpts.adapter).toBe('memory');
+  });
+
+  it('QueueAdapterConstructor is compatible with custom adapter classes', () => {
+    // Verify that a custom adapter class satisfies QueueAdapterConstructor
+    const ctor: QueueAdapterConstructor<CustomAdapterOptions> = CustomAdapter;
+    const instance = new ctor({ servers: 'nats://localhost:4222' });
+
+    expect(instance.name).toBe('custom');
+    expect(instance.type).toBe('jetstream');
+  });
+
+  it('OneBunApplication accepts typed adapter options without type assertion', () => {
+    // This is the main desired usage — no `as SomeOptions` needed
+    @Module({ controllers: [] })
+    class TestModule {}
+
+    const app = new OneBunApplication(TestModule, {
+      loggerLayer: makeMockLoggerLayer(),
+      queue: {
+        adapter: CustomAdapter,
+        options: {
+          servers: 'nats://localhost:4222',
+          streams: [{ name: 'EVENTS', subjects: ['events.>'] }],
+        },
+      },
+    });
+
+    expect(app).toBeDefined();
+  });
+});

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   Env,
   type EnvSchema,
   EnvValidationError,
+  getConfig,
   type InferConfigType,
   type EnvVariableConfig,
 } from '@onebun/envs';

package/src/queue/decorators.test.ts

@@ -189,6 +189,48 @@ describe('queue-decorators', () => {
       expect(handlers[0].propertyKey).toBe('handleReady');
     });
 
+    it('should support multiple @OnQueueReady handlers in one class', () => {
+      class TestService {
+        @OnQueueReady()
+        handleReady1() {}
+
+        @OnQueueReady()
+        handleReady2() {}
+      }
+
+      const handlers = getLifecycleHandlers(TestService, 'ON_READY');
+      expect(handlers.length).toBe(2);
+      expect(handlers[0].propertyKey).toBe('handleReady1');
+      expect(handlers[1].propertyKey).toBe('handleReady2');
+    });
+
+    it('should return empty array when no @OnQueueReady handlers', () => {
+      class TestService {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        handle() {}
+      }
+
+      const handlers = getLifecycleHandlers(TestService, 'ON_READY');
+      expect(handlers.length).toBe(0);
+    });
+
+    it('should not mix @OnQueueReady with other lifecycle metadata', () => {
+      class TestService {
+        @OnQueueReady()
+        handleReady() {}
+
+        @OnQueueError()
+        handleError(_error: Error) {}
+      }
+
+      const readyHandlers = getLifecycleHandlers(TestService, 'ON_READY');
+      const errorHandlers = getLifecycleHandlers(TestService, 'ON_ERROR');
+      expect(readyHandlers.length).toBe(1);
+      expect(readyHandlers[0].propertyKey).toBe('handleReady');
+      expect(errorHandlers.length).toBe(1);
+      expect(errorHandlers[0].propertyKey).toBe('handleError');
+    });
+
     it('should register @OnQueueError handler', () => {
       class TestService {
         @OnQueueError()

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

@@ -13,6 +13,7 @@ import {
 import type { Message } from './types';
 
 import { InMemoryQueueAdapter } from './adapters/memory.adapter';
+import { OnQueueReady, Subscribe } from './decorators';
 import { QueueService } from './queue.service';
 
 describe('QueueService', () => {
@@ -341,6 +342,161 @@ describe('QueueService', () => {
     });
   });
 
+  describe('registerService lifecycle', () => {
+    test('should call @OnQueueReady handler when queue starts', async () => {
+      let readyCalled = false;
+
+      class TestService {
+        @OnQueueReady()
+        handleReady() {
+          readyCalled = true;
+        }
+      }
+
+      const instance = new TestService();
+      await service.registerService(instance, TestService);
+      expect(readyCalled).toBe(false);
+
+      await service.start();
+      expect(readyCalled).toBe(true);
+    });
+
+    test('should allow publishing from @OnQueueReady handler', async () => {
+      const received: Message[] = [];
+
+      class TestService {
+        @OnQueueReady()
+        handleReady() {
+          service.publish('init.ready', { status: 'ok' });
+        }
+
+        @Subscribe('init.ready')
+        handleInit(_message: Message) {}
+      }
+
+      const instance = new TestService();
+
+      // Subscribe before start so the handler is in place
+      await service.subscribe('init.ready', async (message) => {
+        received.push(message);
+      });
+
+      await service.registerService(instance, TestService);
+      await service.start();
+
+      expect(received.length).toBe(1);
+      expect(received[0].data).toEqual({ status: 'ok' });
+    });
+
+    test('should call multiple @OnQueueReady handlers in order', async () => {
+      const callOrder: string[] = [];
+
+      class TestService {
+        @OnQueueReady()
+        handleReady1() {
+          callOrder.push('first');
+        }
+
+        @OnQueueReady()
+        handleReady2() {
+          callOrder.push('second');
+        }
+      }
+
+      const instance = new TestService();
+      await service.registerService(instance, TestService);
+      await service.start();
+
+      expect(callOrder).toEqual(['first', 'second']);
+    });
+
+    test('should call @OnQueueReady with correct this binding', async () => {
+      let capturedValue: string | null = null as string | null;
+
+      class TestService {
+        readonly name = 'test-service';
+
+        @OnQueueReady()
+        handleReady() {
+          capturedValue = this.name;
+        }
+      }
+
+      const instance = new TestService();
+      await service.registerService(instance, TestService);
+      await service.start();
+
+      expect(capturedValue).toBe('test-service');
+    });
+
+    test('should call @OnQueueReady again after stop() and start()', async () => {
+      let readyCount = 0;
+
+      class TestService {
+        @OnQueueReady()
+        handleReady() {
+          readyCount++;
+        }
+      }
+
+      const instance = new TestService();
+      await service.registerService(instance, TestService);
+
+      await service.start();
+      expect(readyCount).toBe(1);
+
+      await service.stop();
+      await service.start();
+      expect(readyCount).toBe(2);
+    });
+
+    test('should call @OnQueueReady on adapter reconnect', async () => {
+      let readyCount = 0;
+
+      class TestService {
+        @OnQueueReady()
+        handleReady() {
+          readyCount++;
+        }
+      }
+
+      const instance = new TestService();
+      await service.registerService(instance, TestService);
+
+      await service.start();
+      expect(readyCount).toBe(1);
+
+      // Simulate reconnect without stopping the service
+      await adapter.disconnect();
+      await adapter.connect();
+      expect(readyCount).toBe(2);
+    });
+
+    test('should not call @OnQueueReady on adapter reconnect when service is stopped', async () => {
+      let readyCount = 0;
+
+      class TestService {
+        @OnQueueReady()
+        handleReady() {
+          readyCount++;
+        }
+      }
+
+      const instance = new TestService();
+      await service.registerService(instance, TestService);
+
+      await service.start();
+      expect(readyCount).toBe(1);
+
+      await service.stop();
+
+      // Reconnect while service is stopped — handler should NOT fire
+      await adapter.connect();
+      expect(readyCount).toBe(1);
+    });
+
+  });
+
   describe('error handling', () => {
     test('should handle subscription errors gracefully', async () => {
       await service.start();

package/src/queue/queue.service.ts

@@ -56,6 +56,8 @@ export class QueueService {
   private subscriptions: Subscription[] = [];
   private started = false;
   private config: QueueConfig;
+  private onReadyHandlers: Array<() => void> = [];
+  private adapterOnReadyRegistered = false;
 
   constructor(config: QueueConfig) {
     this.config = config;
@@ -86,11 +88,28 @@ export class QueueService {
       await this.adapter.connect();
     }
 
+    // Register adapter-level onReady listener once for reconnection scenarios
+    if (!this.adapterOnReadyRegistered) {
+      this.adapter.on('onReady', () => {
+        if (this.started) {
+          for (const handler of this.onReadyHandlers) {
+            handler();
+          }
+        }
+      });
+      this.adapterOnReadyRegistered = true;
+    }
+
     if (this.scheduler) {
       this.scheduler.start();
     }
 
     this.started = true;
+
+    // Call @OnQueueReady handlers — queue is fully ready at this point
+    for (const handler of this.onReadyHandlers) {
+      handler();
+    }
   }
 
   /**
@@ -359,7 +378,7 @@ export class QueueService {
     const onReadyHandlers = getMetadata(QUEUE_METADATA.ON_READY, serviceClass) || [];
     for (const handler of onReadyHandlers) {
       const method = serviceInstance[handler.propertyKey].bind(serviceInstance);
-      this.on('onReady', method);
+      this.onReadyHandlers.push(method);
     }
 
     const onErrorHandlers = getMetadata(QUEUE_METADATA.ON_ERROR, serviceClass) || [];

package/src/queue/types.ts

@@ -433,11 +433,12 @@ export interface QueueAdapter {
 export type BuiltInAdapterType = 'memory' | 'redis';
 
 /**
- * Queue adapter constructor
+ * Queue adapter constructor — generic over the options type.
+ * When used as a generic constraint (e.g. `QueueApplicationOptions<typeof MyAdapter>`),
+ * TypeScript infers the correct options type automatically.
  */
-export interface QueueAdapterConstructor {
-  new (options?: unknown): QueueAdapter;
-}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type QueueAdapterConstructor<TOptions = any> = new (options: TOptions) => QueueAdapter;
 
 /**
  * Queue configuration options

package/src/types.ts

@@ -198,7 +198,8 @@ export interface TypedEnvSchema {
 /**
  * Application options
  */
-export interface ApplicationOptions {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ApplicationOptions<QA extends QueueAdapterConstructor<any> = QueueAdapterConstructor> {
   /**
    * Application name (used for metrics and tracing labels)
    */
@@ -431,7 +432,7 @@ export interface ApplicationOptions {
   /**
    * Queue configuration
    */
-  queue?: QueueApplicationOptions;
+  queue?: QueueApplicationOptions<QA>;
 
   /**
    * Static file serving: serve files from a directory for requests not matched by API routes.
@@ -544,15 +545,18 @@ export interface ApplicationOptions {
 export type QueueAdapterType = 'memory' | 'redis';
 
 /**
- * Queue configuration for OneBunApplication
+ * Queue configuration for OneBunApplication.
+ * Generic parameter `A` infers the adapter constructor type, so `options`
+ * is automatically typed to match the adapter's constructor argument.
  */
-export interface QueueApplicationOptions {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface QueueApplicationOptions<A extends QueueAdapterConstructor<any> = QueueAdapterConstructor> {
   /** Enable/disable queue (default: auto - enabled if handlers exist) */
   enabled?: boolean;
   /** Adapter type, or custom adapter constructor (e.g. for NATS JetStream) */
-  adapter?: QueueAdapterType | QueueAdapterConstructor;
+  adapter?: QueueAdapterType | A;
   /** Options passed to the custom adapter constructor when adapter is a class */
-  options?: unknown;
+  options?: A extends QueueAdapterConstructor<infer O> ? O : never;
   /** Redis-specific options (only used when adapter is 'redis') */
   redis?: {
     /** Use shared Redis provider instead of dedicated connection */