@onebun/core 0.2.11 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.2.11",
+  "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,7 +39,7 @@ 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 { CronExpression } from '../queue/cron-expression';
 import {
@@ -2706,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 {
@@ -4311,4 +4348,291 @@ describe('OneBunApplication', () => {
       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

@@ -156,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: [],
     };
 

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/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();