@onebun/core 0.2.10 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",
@@ -32,6 +32,10 @@
     "src",
     "README.md"
   ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./testing": "./src/testing/index.ts"
+  },
   "main": "src/index.ts",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -43,7 +47,7 @@
     "arktype": "^2.0.0",
     "@onebun/logger": "^0.2.1",
     "@onebun/envs": "^0.2.1",
-    "@onebun/metrics": "^0.2.1",
+    "@onebun/metrics": "^0.2.2",
     "@onebun/requests": "^0.2.1",
     "@onebun/trace": "^0.2.1"
   },

package/src/application/application.test.ts

@@ -39,9 +39,16 @@ import {
 import { Controller as BaseController } from '../module/controller';
 import { BaseMiddleware } from '../module/middleware';
 import { clearGlobalServicesRegistry } from '../module/module';
-import { Service } from '../module/service';
+import { BaseService, Service } from '../module/service';
 import { QueueService, QUEUE_NOT_ENABLED_ERROR_MESSAGE } from '../queue';
-import { Subscribe } from '../queue/decorators';
+import { CronExpression } from '../queue/cron-expression';
+import {
+  Cron,
+  Interval,
+  OnQueueReady,
+  Subscribe,
+  Timeout,
+} from '../queue/decorators';
 import { makeMockLoggerLayer } from '../testing/test-utils';
 
 
@@ -2699,6 +2706,43 @@ describe('OneBunApplication', () => {
       expect(bodyListWithSlash.result).toEqual({ tasks: ['t1', 't2'], status: 'all' });
     });
 
+    test('should not produce double slash when @Controller() has no path prefix', async () => {
+      @Controller()
+      class NoPrefixController extends BaseController {
+        @Get('/users')
+        async listUsers(): Promise<OneBunResponse> {
+          return this.success({ users: ['u1'] });
+        }
+
+        @Get('/')
+        async root(): Promise<OneBunResponse> {
+          return this.success({ root: true });
+        }
+      }
+
+      @Module({ controllers: [NoPrefixController] })
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Route should be /users, not //users
+      const responseUsers = await (mockServer as /* eslint-disable-line @typescript-eslint/no-explicit-any */ any).fetchHandler(
+        new Request('http://localhost:3000/users', { method: 'GET' }),
+      );
+      expect(responseUsers.status).toBe(200);
+      const bodyUsers = await responseUsers.json();
+      expect(bodyUsers.result).toEqual({ users: ['u1'] });
+
+      // Route should be /, not empty
+      const responseRoot = await (mockServer as /* eslint-disable-line @typescript-eslint/no-explicit-any */ any).fetchHandler(
+        new Request('http://localhost:3000/', { method: 'GET' }),
+      );
+      expect(responseRoot.status).toBe(200);
+      const bodyRoot = await responseRoot.json();
+      expect(bodyRoot.result).toEqual({ root: true });
+    });
+
     test('should normalize metrics route labels - trailing slash requests use same label as non-trailing', async () => {
       @Controller('/api')
       class ApiController extends BaseController {
@@ -4083,4 +4127,512 @@ describe('OneBunApplication', () => {
       await app.stop();
     });
   });
+
+  describe('queue auto-detection', () => {
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    const noop = () => {};
+
+    afterEach(async () => {
+      clearGlobalServicesRegistry();
+      register.clear();
+    });
+
+    test('auto-enables queue when controller has @Subscribe', async () => {
+      @Controller('/auto-sub')
+      class AutoSubController extends BaseController {
+        @Subscribe('auto.test')
+        async handle(): Promise<void> {}
+      }
+
+      @Module({ controllers: [AutoSubController] })
+      class AutoSubModule {}
+
+      const app = createTestApp(AutoSubModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).not.toBeNull();
+
+      await app.stop();
+    });
+
+    test('auto-enables queue when controller has @Cron', async () => {
+      @Controller('/auto-cron')
+      class AutoCronController extends BaseController {
+        @Cron(CronExpression.EVERY_MINUTE, { pattern: 'cron.test' })
+        getData() {
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [AutoCronController] })
+      class AutoCronModule {}
+
+      const app = createTestApp(AutoCronModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).not.toBeNull();
+
+      await app.stop();
+    });
+
+    test('auto-enables queue when controller has @Interval', async () => {
+       
+      const intervalMs = 5000;
+
+      @Controller('/auto-interval')
+      class AutoIntervalController extends BaseController {
+        @Interval(intervalMs, { pattern: 'interval.test' })
+        getData() {
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [AutoIntervalController] })
+      class AutoIntervalModule {}
+
+      const app = createTestApp(AutoIntervalModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).not.toBeNull();
+
+      await app.stop();
+    });
+
+    test('auto-enables queue when controller has @Timeout', async () => {
+       
+      const timeoutMs = 1000;
+
+      @Controller('/auto-timeout')
+      class AutoTimeoutController extends BaseController {
+        @Timeout(timeoutMs, { pattern: 'timeout.test' })
+        getData() {
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [AutoTimeoutController] })
+      class AutoTimeoutModule {}
+
+      const app = createTestApp(AutoTimeoutModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).not.toBeNull();
+
+      await app.stop();
+    });
+
+    test('does not enable queue when no queue decorators present', async () => {
+      @Controller('/plain')
+      class PlainController extends BaseController {
+        @Get('/')
+        async index(): Promise<OneBunResponse> {
+          return this.success({ ok: true });
+        }
+      }
+
+      @Module({ controllers: [PlainController] })
+      class PlainModule {}
+
+      const app = createTestApp(PlainModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).toBeNull();
+
+      await app.stop();
+    });
+
+    test('does not enable queue when only lifecycle decorators present', async () => {
+      @Controller('/lifecycle-only')
+      class LifecycleOnlyController extends BaseController {
+        @OnQueueReady()
+        onReady() {
+          noop();
+        }
+      }
+
+      @Module({ controllers: [LifecycleOnlyController] })
+      class LifecycleOnlyModule {}
+
+      const app = createTestApp(LifecycleOnlyModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).toBeNull();
+
+      await app.stop();
+    });
+
+    test('enabled: false overrides auto-detection', async () => {
+      @Controller('/force-off')
+      class ForceOffController extends BaseController {
+        @Subscribe('force.off')
+        async handle(): Promise<void> {}
+      }
+
+      @Module({ controllers: [ForceOffController] })
+      class ForceOffModule {}
+
+      const app = createTestApp(ForceOffModule, {
+        port: 0,
+        queue: { enabled: false },
+      });
+      await app.start();
+
+      expect(app.getQueueService()).toBeNull();
+
+      await app.stop();
+    });
+
+    test('auto-detects from nested child module', async () => {
+      @Controller('/child-auto')
+      class ChildAutoController extends BaseController {
+        @Subscribe('child.auto')
+        async handle(): Promise<void> {}
+      }
+
+      @Module({ controllers: [ChildAutoController] })
+      class ChildAutoModule {}
+
+      @Module({ imports: [ChildAutoModule] })
+      class ParentAutoModule {}
+
+      const app = createTestApp(ParentAutoModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).not.toBeNull();
+
+      await app.stop();
+    });
+
+    test('auto-detects from deeply nested module (grandchild)', async () => {
+      @Controller('/grandchild')
+      class GrandchildController extends BaseController {
+        @Subscribe('grandchild.event')
+        async handle(): Promise<void> {}
+      }
+
+      @Module({ controllers: [GrandchildController] })
+      class GrandchildModule {}
+
+      @Module({ imports: [GrandchildModule] })
+      class MiddleModule {}
+
+      @Module({ imports: [MiddleModule] })
+      class TopModule {}
+
+      const app = createTestApp(TopModule, { port: 0 });
+      await app.start();
+
+      expect(app.getQueueService()).not.toBeNull();
+
+      await app.stop();
+    });
+
+    test('getQueueService() returns null when queue not enabled', async () => {
+      @Controller('/no-queue')
+      class NoQueueController extends BaseController {
+        @Get('/')
+        async index(): Promise<OneBunResponse> {
+          return this.success({});
+        }
+      }
+
+      @Module({ controllers: [NoQueueController] })
+      class NoQueueModule {}
+
+      const app = createTestApp(NoQueueModule, { port: 0 });
+      await app.start();
+
+      const queueService = app.getQueueService();
+      expect(queueService).toBeNull();
+
+      await app.stop();
+    });
+  });
+
+  describe('queue handler execution', () => {
+    afterEach(async () => {
+      clearGlobalServicesRegistry();
+      register.clear();
+    });
+
+    test('@Interval handler fires immediately on start (auto-detected, no explicit queue config)', async () => {
+      let callCount = 0;
+      const intervalMs = 60000;
+
+      @Controller('/interval-fire')
+      class IntervalFireController extends BaseController {
+        @Interval(intervalMs, { pattern: 'test.interval' })
+        getData() {
+          callCount++;
+
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [IntervalFireController] })
+      class IntervalFireModule {}
+
+      const app = createTestApp(IntervalFireModule, { port: 0 });
+      await app.start();
+
+      // scheduler.startIntervalJob calls executeJob immediately (fire-and-forget async)
+      await new Promise(r => setTimeout(r, 50));
+
+      expect(app.getQueueService()).not.toBeNull();
+      expect(callCount).toBe(1);
+
+      await app.stop();
+    });
+
+    test('@Interval handler fires with explicit queue: { enabled: true }', async () => {
+      let callCount = 0;
+      const intervalMs = 60000;
+
+      @Controller('/interval-explicit')
+      class IntervalExplicitController extends BaseController {
+        @Interval(intervalMs, { pattern: 'test.explicit' })
+        getData() {
+          callCount++;
+
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [IntervalExplicitController] })
+      class IntervalExplicitModule {}
+
+      const app = createTestApp(IntervalExplicitModule, {
+        port: 0,
+        queue: { enabled: true },
+      });
+      await app.start();
+
+      await new Promise(r => setTimeout(r, 50));
+
+      expect(callCount).toBe(1);
+
+      await app.stop();
+    });
+
+    test('@Interval handler fires with injected service dependency', async () => {
+      let callCount = 0;
+      const intervalMs = 60000;
+
+      @Service()
+      class WorkerService extends BaseService {
+        async doWork(): Promise<string> {
+          return 'done';
+        }
+      }
+
+      @Controller('/interval-di')
+      class IntervalDIController extends BaseController {
+        constructor(private readonly worker: WorkerService) {
+          super();
+        }
+
+        @Interval(intervalMs, { pattern: 'test.di' })
+        async getData(): Promise<Record<string, unknown>> {
+          callCount++;
+
+          return { result: await this.worker.doWork() };
+        }
+      }
+
+      @Module({ controllers: [IntervalDIController], providers: [WorkerService] })
+      class IntervalDIModule {}
+
+      const app = createTestApp(IntervalDIModule, { port: 0 });
+      await app.start();
+
+      await new Promise(r => setTimeout(r, 50));
+
+      expect(callCount).toBe(1);
+
+      await app.stop();
+    });
+
+    test('@Cron handler registers job in scheduler (auto-detected)', async () => {
+      @Controller('/cron-register')
+      class CronRegisterController extends BaseController {
+        @Cron(CronExpression.EVERY_HOUR, { pattern: 'cron.hourly' })
+        getData() {
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [CronRegisterController] })
+      class CronRegisterModule {}
+
+      const app = createTestApp(CronRegisterModule, { port: 0 });
+      await app.start();
+
+      const scheduler = app.getQueueService()!.getScheduler();
+      const jobs = scheduler.getJobs();
+      expect(jobs.length).toBe(1);
+      expect(jobs[0].pattern).toBe('cron.hourly');
+
+      await app.stop();
+    });
+
+    test('@Timeout handler registers and fires once (auto-detected)', async () => {
+      let callCount = 0;
+      const timeoutMs = 10;
+
+      @Controller('/timeout-fire')
+      class TimeoutFireController extends BaseController {
+        @Timeout(timeoutMs, { pattern: 'test.timeout' })
+        getData() {
+          callCount++;
+
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [TimeoutFireController] })
+      class TimeoutFireModule {}
+
+      const app = createTestApp(TimeoutFireModule, { port: 0 });
+      await app.start();
+
+      // Wait for timeout to fire
+      await new Promise(r => setTimeout(r, 100));
+
+      expect(callCount).toBe(1);
+
+      await app.stop();
+    });
+
+    test('scheduled decorators in nested child module auto-init queue and fire', async () => {
+      let callCount = 0;
+      const intervalMs = 60000;
+
+      @Controller('/nested-interval')
+      class NestedIntervalController extends BaseController {
+        @Interval(intervalMs, { pattern: 'nested.interval' })
+        getData() {
+          callCount++;
+
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [NestedIntervalController] })
+      class ChildModule {}
+
+      @Module({ imports: [ChildModule] })
+      class ParentModule {}
+
+      const app = createTestApp(ParentModule, { port: 0 });
+      await app.start();
+
+      await new Promise(r => setTimeout(r, 50));
+
+      expect(app.getQueueService()).not.toBeNull();
+      expect(callCount).toBe(1);
+
+      await app.stop();
+    });
+
+    test('scheduled decorators in deeply nested module auto-init queue and fire', async () => {
+      let callCount = 0;
+      const intervalMs = 60000;
+
+      @Controller('/deep-interval')
+      class DeepIntervalController extends BaseController {
+        @Interval(intervalMs, { pattern: 'deep.interval' })
+        getData() {
+          callCount++;
+
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [DeepIntervalController] })
+      class GrandchildModule {}
+
+      @Module({ imports: [GrandchildModule] })
+      class MiddleModule {}
+
+      @Module({ imports: [MiddleModule] })
+      class TopModule {}
+
+      const app = createTestApp(TopModule, { port: 0 });
+      await app.start();
+
+      await new Promise(r => setTimeout(r, 50));
+
+      expect(app.getQueueService()).not.toBeNull();
+      expect(callCount).toBe(1);
+
+      await app.stop();
+    });
+
+    test('handler error does not break scheduler', async () => {
+      let errorCallCount = 0;
+      let successCallCount = 0;
+      const intervalMs = 60000;
+
+      @Controller('/error-handler')
+      class ErrorHandlerController extends BaseController {
+        @Interval(intervalMs, { pattern: 'error.handler' })
+        getErrorData() {
+          errorCallCount++;
+          throw new Error('Handler failed');
+        }
+
+        @Interval(intervalMs, { pattern: 'success.handler' })
+        getSuccessData() {
+          successCallCount++;
+
+          return { ok: true };
+        }
+      }
+
+      @Module({ controllers: [ErrorHandlerController] })
+      class ErrorHandlerModule {}
+
+      const app = createTestApp(ErrorHandlerModule, { port: 0 });
+      await app.start();
+
+      await new Promise(r => setTimeout(r, 50));
+
+      // Both handlers should have been called despite one throwing
+      expect(errorCallCount).toBe(1);
+      expect(successCallCount).toBe(1);
+
+      await app.stop();
+    });
+
+    test('only scheduled decorators (no @Subscribe) implicitly use in-memory adapter', async () => {
+      @Controller('/scheduled-only')
+      class ScheduledOnlyController extends BaseController {
+        @Interval(60000, { pattern: 'scheduled.only' })
+        getData() {
+          return { ts: Date.now() };
+        }
+
+        @Cron(CronExpression.EVERY_HOUR, { pattern: 'scheduled.cron' })
+        getCronData() {
+          return { ts: Date.now() };
+        }
+      }
+
+      @Module({ controllers: [ScheduledOnlyController] })
+      class ScheduledOnlyModule {}
+
+      // No queue config at all — should auto-detect and use in-memory
+      const app = createTestApp(ScheduledOnlyModule, { port: 0 });
+      await app.start();
+
+      const qs = app.getQueueService();
+      expect(qs).not.toBeNull();
+
+      const scheduler = qs!.getScheduler();
+      const jobs = scheduler.getJobs();
+      expect(jobs.length).toBe(2);
+
+      await app.stop();
+    });
+  });
 });

package/src/application/application.ts

@@ -1777,7 +1777,7 @@ export class OneBunApplication {
         return false;
       }
 
-      return hasQueueDecorators(instance.constructor);
+      return hasQueueDecorators(controller) || hasQueueDecorators(instance.constructor);
     });
 
     // Determine if queue should be enabled
@@ -1840,24 +1840,41 @@ export class OneBunApplication {
           : queueOptions?.redis,
     };
     this.queueService = new QueueService(queueServiceConfig);
-    
+
     // Initialize with the adapter
     await this.queueService.initialize(this.queueAdapter);
 
+    // Wire scheduler error handler so failed jobs are logged
+    this.queueService.getScheduler().setErrorHandler((jobName, error) => {
+      this.logger.warn(`Scheduled job "${jobName}" failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+
     // Register handlers from controllers using registerService
     for (const controllerClass of controllers) {
       const instance = this.ensureModule().getControllerInstance?.(controllerClass);
       if (!instance) {
+        this.logger.debug(`Queue: skipping controller ${controllerClass.name} (no instance found)`);
         continue;
       }
-      
-      // Only register if the controller has queue decorators
-      if (hasQueueDecorators(controllerClass)) {
+
+      // Check both controllerClass and instance.constructor for queue decorators
+      // These should be identical, but if @Controller wrapping produces a different reference,
+      // we check both to be safe
+      const hasDecorators =
+        hasQueueDecorators(controllerClass) || hasQueueDecorators(instance.constructor);
+
+      if (hasDecorators) {
+        // Use whichever reference has the metadata for registration
+        const registrationClass = hasQueueDecorators(controllerClass)
+          ? controllerClass
+          : instance.constructor;
         await this.queueService.registerService(
           instance,
-          controllerClass as new (...args: unknown[]) => unknown,
+          registrationClass as new (...args: unknown[]) => unknown,
         );
         this.logger.debug(`Registered queue handlers for controller: ${controllerClass.name}`);
+      } else {
+        this.logger.debug(`Queue: controller ${controllerClass.name} has no queue decorators`);
       }
     }
 

package/src/decorators/decorators.test.ts

@@ -104,7 +104,7 @@ describe('decorators', () => {
 
       const metadata = getControllerMetadata(TestController);
       expect(metadata).toBeDefined();
-      expect(metadata?.path).toBe('/');
+      expect(metadata?.path).toBe('');
       expect(metadata?.routes).toEqual([]);
     });
 

package/src/decorators/decorators.ts

@@ -15,7 +15,11 @@ import {
   type RouteOptions,
 } from '../types';
 
-import { getConstructorParamTypes as getDesignParamTypes, Reflect } from './metadata';
+import {
+  copyAllMetadata,
+  getConstructorParamTypes as getDesignParamTypes,
+  Reflect,
+} from './metadata';
 
 /**
  * Metadata storage for controllers
@@ -152,7 +156,7 @@ export function controllerDecorator(basePath: string = '') {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return <T extends new (...args: any[]) => any>(target: T): T => {
     const metadata: ControllerMetadata = {
-      path: basePath.startsWith('/') ? basePath : `/${basePath}`,
+      path: basePath === '' ? '' : (basePath.startsWith('/') ? basePath : `/${basePath}`),
       routes: [],
     };
 
@@ -174,6 +178,9 @@ export function controllerDecorator(basePath: string = '') {
       }
     }
 
+    // Copy all method-decorator metadata (queue decorators, etc.) from original to wrapped class
+    copyAllMetadata(target, WrappedController);
+
     // Copy metadata and static properties
     META_CONTROLLERS.set(WrappedController, metadata);
     META_CONTROLLERS.set(target, metadata); // Keep original for compatibility

package/src/decorators/metadata.ts

@@ -43,6 +43,31 @@ export function defineMetadata(
   keyMetadata.set(propertyKey || '', metadataValue);
 }
 
+/**
+ * Copy all metadata from one target to another.
+ * Used by @Controller to preserve method-decorator metadata (e.g. queue decorators)
+ * when wrapping the original class.
+ */
+export function copyAllMetadata(source: object, destination: object): void {
+  const sourceMetadata = metadataStorage.get(source);
+  if (!sourceMetadata) {
+    return;
+  }
+
+  let destMetadata = metadataStorage.get(destination);
+  if (!destMetadata) {
+    destMetadata = new Map<string, Map<string | symbol, any>>();
+    metadataStorage.set(destination, destMetadata);
+  }
+
+  for (const [metadataKey, keyMap] of sourceMetadata) {
+    // Only copy if destination doesn't already have this key
+    if (!destMetadata.has(metadataKey)) {
+      destMetadata.set(metadataKey, new Map(keyMap));
+    }
+  }
+}
+
 /**
  * Get metadata from a target object
  * @param metadataKey - The key for the metadata

package/src/docs-examples.test.ts

@@ -48,6 +48,8 @@ import type {
 import type { HttpExecutionContext } from './types';
 import type { ServerWebSocket } from 'bun';
 
+import { makeMockLoggerLayer } from './testing';
+
 import {
   Controller,
   Get,
@@ -109,7 +111,6 @@ import {
   createWsClient,
   createNativeWsClient,
   matchPattern,
-  makeMockLoggerLayer,
   hasOnModuleInit,
   hasOnApplicationInit,
   hasOnModuleDestroy,

package/src/index.ts

@@ -130,8 +130,8 @@ export * from './queue';
 // Validation
 export * from './validation';
 
-// Testing Utilities
-export * from './testing';
+// Testing Utilities are available via '@onebun/core/testing' subpath import
+// to avoid requiring testcontainers as a mandatory dependency
 
 // HTTP Guards
 export * from './http-guards';

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

@@ -49,6 +49,7 @@ import {
   getIntervalMetadata,
   getTimeoutMetadata,
   hasQueueDecorators,
+  QueueScheduler,
 } from './index';
 
 /**
@@ -593,3 +594,92 @@ describe('Feature Support Matrix (docs/api/queue.md)', () => {
     expect(adapter.supports('retry')).toBe(false);
   });
 });
+
+/**
+ * @source docs/api/queue.md#setup (scheduled-only tip)
+ */
+describe('Scheduled-only Controllers (docs/api/queue.md)', () => {
+  it('should auto-detect queue decorators on controller with only @Interval', () => {
+    // From docs/api/queue.md: Scheduled-only Controllers tip
+    class ScheduledOnlyController {
+      @Interval(60000, { pattern: 'metrics.collect' })
+      getMetrics() {
+        return { cpu: process.cpuUsage() };
+      }
+    }
+
+    // No @Subscribe — only scheduling decorators
+    expect(hasQueueDecorators(ScheduledOnlyController)).toBe(true);
+    expect(getSubscribeMetadata(ScheduledOnlyController).length).toBe(0);
+    expect(getIntervalMetadata(ScheduledOnlyController).length).toBe(1);
+  });
+
+  it('should auto-detect queue decorators on controller with only @Cron', () => {
+    class CronOnlyController {
+      @Cron(CronExpression.EVERY_HOUR, { pattern: 'cleanup.expired' })
+      getCleanupData() {
+        return { timestamp: Date.now() };
+      }
+    }
+
+    expect(hasQueueDecorators(CronOnlyController)).toBe(true);
+    expect(getSubscribeMetadata(CronOnlyController).length).toBe(0);
+    expect(getCronMetadata(CronOnlyController).length).toBe(1);
+  });
+
+  it('should auto-detect queue decorators on controller with only @Timeout', () => {
+    class TimeoutOnlyController {
+      @Timeout(5000, { pattern: 'startup.warmup' })
+      getWarmupData() {
+        return { type: 'warmup' };
+      }
+    }
+
+    expect(hasQueueDecorators(TimeoutOnlyController)).toBe(true);
+    expect(getSubscribeMetadata(TimeoutOnlyController).length).toBe(0);
+    expect(getTimeoutMetadata(TimeoutOnlyController).length).toBe(1);
+  });
+});
+
+/**
+ * @source docs/api/queue.md#setup (error handling info)
+ */
+describe('Scheduled Job Error Handling (docs/api/queue.md)', () => {
+  let adapter: InMemoryQueueAdapter;
+
+  beforeEach(async () => {
+    adapter = new InMemoryQueueAdapter();
+    await adapter.connect();
+  });
+
+  afterEach(async () => {
+    await adapter.disconnect();
+  });
+
+  it('should continue scheduler after handler error via setErrorHandler', async () => {
+    // From docs/api/queue.md: Scheduled Job Error Handling info
+    const scheduler = new QueueScheduler(adapter);
+
+    const errors: Array<{ name: string; error: unknown }> = [];
+    scheduler.setErrorHandler((name: string, error: unknown) => {
+      errors.push({ name, error });
+    });
+
+    // Add a job that will fail
+    scheduler.addIntervalJob('failing-job', 60000, 'test.fail', () => {
+      throw new Error('Job failed');
+    });
+
+    scheduler.start();
+
+    // executeJob is async fire-and-forget, wait for it
+    await new Promise(r => setTimeout(r, 50));
+
+    // Error handler should have been called (immediate execution)
+    expect(errors.length).toBe(1);
+    expect(errors[0].name).toBe('failing-job');
+    expect((errors[0].error as Error).message).toBe('Job failed');
+
+    scheduler.stop();
+  });
+});

package/src/queue/scheduler.ts

@@ -64,9 +64,17 @@ export class QueueScheduler {
   private running = false;
   private cronCheckInterval?: ReturnType<typeof setInterval>;
   private readonly cronCheckIntervalMs = 1000; // Check cron jobs every second
+  private onJobError?: (jobName: string, error: unknown) => void;
 
   constructor(private readonly adapter: QueueAdapter) {}
 
+  /**
+   * Set error handler for scheduled job failures
+   */
+  setErrorHandler(handler: (jobName: string, error: unknown) => void): void {
+    this.onJobError = handler;
+  }
+
   /**
    * Start the scheduler
    */
@@ -363,8 +371,11 @@ export class QueueScheduler {
       await this.adapter.publish(job.pattern, data, {
         metadata: job.metadata,
       });
-    } catch {
-      // Error executing job - silently continue (error handling should be done via events)
+    } catch (error) {
+      // Report error via handler if set, otherwise silently continue
+      if (this.onJobError) {
+        this.onJobError(job.name, error);
+      }
     } finally {
       job.isRunning = false;
     }

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

@@ -22,7 +22,11 @@ import { Controller as BaseController } from '../module/controller';
 import { BaseService, Service } from '../module/service';
 
 import { createTestController, createTestService } from './service-helpers';
-import { createMockConfig, useFakeTimers } from './test-utils';
+import {
+  createMockConfig,
+  createMockLogger,
+  useFakeTimers,
+} from './test-utils';
 import { TestingModule } from './testing-module';
 
 // ============================================================================
@@ -161,6 +165,50 @@ describe('docs/testing.md — TestingModule', () => {
       await module?.close();
     }
   });
+
+  /**
+   * @source docs/testing.md#overrideproviderserviceclass
+   */
+  it('overrideProvider — replaces service with mock value', async () => {
+    const mockUser = { id: '1', name: 'MockUser' };
+    let module: CompiledTestingModule | undefined;
+
+    try {
+      module = await TestingModule
+        .create({ controllers: [UserController], providers: [UserService] })
+        .overrideProvider(UserService).useValue({ findById: () => mockUser })
+        .compile();
+
+      const response = await module.inject('GET', '/users/1');
+
+      expect(response.status).toBe(200);
+
+      const body = await response.json() as { result: { id: string; name: string } };
+      expect(body.result.name).toBe('MockUser');
+    } finally {
+      await module?.close();
+    }
+  });
+
+  /**
+   * @source docs/testing.md#setoptionsoptions
+   */
+  it('setOptions — applies basePath to routes', async () => {
+    let module: CompiledTestingModule | undefined;
+
+    try {
+      module = await TestingModule
+        .create({ controllers: [UserController], providers: [UserService] })
+        .setOptions({ basePath: '/api' })
+        .compile();
+
+      const response = await module.inject('GET', '/api/users/1');
+
+      expect(response.status).toBe(200);
+    } finally {
+      await module?.close();
+    }
+  });
 });
 
 // ============================================================================
@@ -191,6 +239,24 @@ describe('docs/testing.md — useFakeTimers', () => {
   });
 });
 
+// ============================================================================
+// createMockLogger — docs/testing.md
+// ============================================================================
+
+describe('docs/testing.md — createMockLogger', () => {
+  /**
+   * @source docs/testing.md#createmocklogger
+   */
+  it('basic usage — creates silent async logger', () => {
+    const logger = createMockLogger();
+
+    expect(logger).toBeDefined();
+    expect(typeof logger.info).toBe('function');
+    expect(typeof logger.child).toBe('function');
+    expect(logger.child({ context: 'test' })).toBe(logger);
+  });
+});
+
 // ============================================================================
 // createMockConfig — docs/testing.md
 // ============================================================================

package/src/testing/test-utils.ts

@@ -232,7 +232,7 @@ export const fakeTimers = new FakeTimers();
  * 
  * @example
  * ```typescript
- * import { useFakeTimers } from '@onebun/core';
+ * import { useFakeTimers } from '@onebun/core/testing';
  * 
  * describe('My tests', () => {
  *   const { advanceTime, restore } = useFakeTimers();