@onebun/core 0.2.12 → 0.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "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.test.ts

@@ -3964,13 +3964,6 @@ describe('OneBunApplication', () => {
         };
       }
 
-      async addScheduledJob(): Promise<void> {}
-      async removeScheduledJob(): Promise<boolean> {
-        return false;
-      }
-      async getScheduledJobs(): Promise<import('../queue/types').ScheduledJobInfo[]> {
-        return [];
-      }
       supports(): boolean {
         return false;
       }

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/decorators/metadata.test.ts

@@ -14,6 +14,7 @@ import {
 
 import {
   defineMetadata,
+  diagnoseDecoratorMetadata,
   getMetadata,
   getConstructorParamTypes,
   setConstructorParamTypes,
@@ -731,6 +732,91 @@ describe('Metadata System', () => {
     });
   });
 
+  describe('diagnoseDecoratorMetadata', () => {
+    test('should return ok when no classes have constructor params', () => {
+      class NoParams {}
+
+      const result = diagnoseDecoratorMetadata([NoParams]);
+
+      expect(result.ok).toBe(true);
+      expect(result.classesWithParams).toBe(0);
+      expect(result.classesWithMetadata).toBe(0);
+    });
+
+    test('should return ok when classes with params have metadata', () => {
+      class DepA {}
+      class WithMeta {
+        constructor(_dep: DepA) {}
+      }
+
+      // Simulate Bun emitting design:paramtypes via Reflect polyfill
+      (globalThis as any).Reflect.defineMetadata('design:paramtypes', [DepA], WithMeta);
+
+      const result = diagnoseDecoratorMetadata([WithMeta]);
+
+      expect(result.ok).toBe(true);
+      expect(result.classesWithParams).toBe(1);
+      expect(result.classesWithMetadata).toBe(1);
+    });
+
+    test('should return not ok when classes with params have NO metadata', () => {
+      // Use a fresh class without any metadata set
+      class NoDep {}
+      class BrokenService {
+        constructor(_dep: NoDep) {}
+      }
+
+      const result = diagnoseDecoratorMetadata([BrokenService]);
+
+      expect(result.ok).toBe(false);
+      expect(result.classesWithParams).toBe(1);
+      expect(result.classesWithMetadata).toBe(0);
+    });
+
+    test('should return ok when at least one class has metadata', () => {
+      class DepA {}
+      class DepB {}
+
+      class ServiceA {
+        constructor(_dep: DepA) {}
+      }
+      class ServiceB {
+        constructor(_dep: DepB) {}
+      }
+
+      // Only one has metadata — still ok (metadata emission works in principle)
+      (globalThis as any).Reflect.defineMetadata('design:paramtypes', [DepA], ServiceA);
+
+      const result = diagnoseDecoratorMetadata([ServiceA, ServiceB]);
+
+      expect(result.ok).toBe(true);
+      expect(result.classesWithParams).toBe(2);
+      expect(result.classesWithMetadata).toBe(1);
+    });
+
+    test('should return ok for empty class list', () => {
+      const result = diagnoseDecoratorMetadata([]);
+
+      expect(result.ok).toBe(true);
+      expect(result.classesWithParams).toBe(0);
+    });
+
+    test('should handle mixed classes with and without params', () => {
+      class Dep {}
+      class NoParamsService {}
+      class WithParamsService {
+        constructor(_dep: Dep) {}
+      }
+
+      // No metadata for WithParamsService
+      const result = diagnoseDecoratorMetadata([NoParamsService, WithParamsService]);
+
+      expect(result.ok).toBe(false);
+      expect(result.classesWithParams).toBe(1);
+      expect(result.classesWithMetadata).toBe(0);
+    });
+  });
+
   describe('Metadata storage edge cases', () => {
     test('should handle metadata on object values', () => {
       const objectValue = { value: 42 };

package/src/decorators/metadata.ts

@@ -286,6 +286,205 @@ export function getConstructorParamTypes(target: Function): Function[] | undefin
   return undefined;
 }
 
+/**
+ * Diagnostic: check whether Bun is emitting decorator metadata (design:paramtypes).
+ *
+ * Scans an array of decorated classes. If at least one class has constructor
+ * parameters (target.length > 0) but NONE of them have design:paramtypes,
+ * then emitDecoratorMetadata is not working — typically because the setting
+ * is missing from the root tsconfig.json that Bun actually reads.
+ *
+ * @param decoratedClasses - Classes registered via @Service / @Controller / @Middleware
+ * @returns Object with diagnostic result and details
+ */
+export function diagnoseDecoratorMetadata(decoratedClasses: Function[]): {
+  ok: boolean;
+  classesWithParams: number;
+  classesWithMetadata: number;
+} {
+  let classesWithParams = 0;
+  let classesWithMetadata = 0;
+
+  for (const cls of decoratedClasses) {
+    if (cls.length > 0) {
+      classesWithParams++;
+      const types = (globalThis as any).Reflect?.getMetadata?.('design:paramtypes', cls);
+      if (types && Array.isArray(types) && types.length > 0) {
+        classesWithMetadata++;
+      }
+    }
+  }
+
+  return {
+    ok: classesWithParams === 0 || classesWithMetadata > 0,
+    classesWithParams,
+    classesWithMetadata,
+  };
+}
+
+/**
+ * Build a detailed diagnostic message by inspecting the project's tsconfig files.
+ *
+ * Walks up from `process.cwd()` looking for tsconfig.json files, reads them,
+ * and tells the user exactly which file to edit and what to add.
+ */
+export function buildDecoratorMetadataDiagnosticMessage(
+  classesWithParams: number,
+): string {
+  const fs = require('node:fs');
+  const pathModule = require('node:path');
+
+  const header =
+    `[OneBun] Dependency injection is broken: none of the ${classesWithParams} ` +
+    'service(s) with constructor parameters have design:paramtypes metadata.\n' +
+    'Bun is NOT emitting decorator metadata.\n';
+
+  type TsconfigInfo = { path: string; content: any; hasEmit: boolean; hasExperimental: boolean };
+
+  const readTsconfig = (tsconfigPath: string): TsconfigInfo | null => {
+    try {
+      if (!fs.existsSync(tsconfigPath)) {
+        return null;
+      }
+      const raw = fs.readFileSync(tsconfigPath, 'utf-8');
+      // Strip comments (single-line // and multi-line /* */) for JSON.parse
+      const stripped = raw.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
+      const parsed = JSON.parse(stripped);
+      const compilerOptions = parsed.compilerOptions || {};
+
+      return {
+        path: tsconfigPath,
+        content: parsed,
+        hasEmit: compilerOptions.emitDecoratorMetadata === true,
+        hasExperimental: compilerOptions.experimentalDecorators === true,
+      };
+    } catch {
+      return null;
+    }
+  };
+
+  // 1. Find tsconfig.json files walking UP from cwd to filesystem root
+  const tsconfigFiles: TsconfigInfo[] = [];
+  let dir = process.cwd();
+  const root = pathModule.parse(dir).root;
+
+  while (dir !== root) {
+    const info = readTsconfig(pathModule.join(dir, 'tsconfig.json'));
+    if (info) {
+      tsconfigFiles.push(info);
+    }
+    dir = pathModule.dirname(dir);
+  }
+
+  // 2. Also scan immediate subdirectories of cwd for child tsconfig.json files
+  //    (e.g. packages/backend/tsconfig.json in a monorepo)
+  const childTsconfigFiles: TsconfigInfo[] = [];
+  try {
+    const scanDirs = [process.cwd()];
+    // Scan up to 2 levels deep to find packages/*/tsconfig.json and similar
+    for (const scanDir of scanDirs) {
+      const entries = fs.readdirSync(scanDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          const subdir = pathModule.join(scanDir, entry.name);
+          const info = readTsconfig(pathModule.join(subdir, 'tsconfig.json'));
+          if (info) {
+            childTsconfigFiles.push(info);
+          }
+          // One level deeper (e.g. packages/backend/)
+          try {
+            const subEntries = fs.readdirSync(subdir, { withFileTypes: true });
+            for (const subEntry of subEntries) {
+              if (subEntry.isDirectory() && !subEntry.name.startsWith('.') && subEntry.name !== 'node_modules') {
+                const info2 = readTsconfig(pathModule.join(subdir, subEntry.name, 'tsconfig.json'));
+                if (info2) {
+                  childTsconfigFiles.push(info2);
+                }
+              }
+            }
+          } catch {
+            // Skip unreadable directories
+          }
+        }
+      }
+    }
+  } catch {
+    // Skip if directory scanning fails
+  }
+
+  if (tsconfigFiles.length === 0) {
+    return (
+      header +
+      '\nNo tsconfig.json found. Create one in your project root with:\n\n' +
+      '  {\n' +
+      '    "compilerOptions": {\n' +
+      '      "experimentalDecorators": true,\n' +
+      '      "emitDecoratorMetadata": true\n' +
+      '    }\n' +
+      '  }\n'
+    );
+  }
+
+  // The first (deepest / closest to cwd) tsconfig is what the user likely expects to work.
+  // The last (shallowest / closest to root) is what Bun actually reads.
+  const rootTsconfig = tsconfigFiles[tsconfigFiles.length - 1];
+
+  // Check if any child tsconfig has the settings but root does not
+  // Look in both parent chain and scanned subdirectories
+  const allConfigs = [...tsconfigFiles, ...childTsconfigFiles];
+  const childWithSettings = allConfigs.find(
+    (t) => t.path !== rootTsconfig.path && (t.hasEmit || t.hasExperimental),
+  );
+
+  const lines: string[] = [header];
+
+  if (rootTsconfig.hasEmit && rootTsconfig.hasExperimental) {
+    // Root has both settings — unusual, might be a different issue
+    lines.push(`\nRoot tsconfig (${rootTsconfig.path}) already has both settings.`);
+    lines.push('If DI is still broken, check that Bun is reading this file for your entry point.');
+
+    return lines.join('\n');
+  }
+
+  // Report what's missing from the root tsconfig
+  const missing: string[] = [];
+  if (!rootTsconfig.hasExperimental) {
+    missing.push('"experimentalDecorators": true');
+  }
+  if (!rootTsconfig.hasEmit) {
+    missing.push('"emitDecoratorMetadata": true');
+  }
+
+  lines.push(`\nRoot tsconfig: ${rootTsconfig.path}`);
+  lines.push(`Missing in "compilerOptions": ${missing.join(', ')}`);
+
+  if (childWithSettings) {
+    const childHas: string[] = [];
+    if (childWithSettings.hasExperimental) {
+      childHas.push('"experimentalDecorators": true');
+    }
+    if (childWithSettings.hasEmit) {
+      childHas.push('"emitDecoratorMetadata": true');
+    }
+    lines.push(
+      `\nNote: ${childWithSettings.path} has ${childHas.join(' and ')},` +
+      ' but Bun ignores these when they are only in a child tsconfig.',
+    );
+  }
+
+  lines.push(`\nFix: add the missing option(s) to ${rootTsconfig.path}:\n`);
+  lines.push('  "compilerOptions": {');
+  if (!rootTsconfig.hasExperimental) {
+    lines.push('    "experimentalDecorators": true,');
+  }
+  if (!rootTsconfig.hasEmit) {
+    lines.push('    "emitDecoratorMetadata": true');
+  }
+  lines.push('  }');
+
+  return lines.join('\n');
+}
+
 /**
  * Namespace for metadata functions to mimic Reflect API
  */

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/module/module.ts

@@ -22,6 +22,7 @@ import {
   isGlobalModule,
   registerControllerDependencies,
 } from '../decorators/decorators';
+import { buildDecoratorMetadataDiagnosticMessage, diagnoseDecoratorMetadata } from '../decorators/metadata';
 import { QueueService, QueueServiceTag } from '../queue';
 import { BaseWebSocketGateway } from '../websocket/ws-base-gateway';
 import { isWebSocketGateway } from '../websocket/ws-decorators';
@@ -70,6 +71,7 @@ const processedGlobalModules: Set<Function> = ((globalThis as any)[Symbol.for('o
 export function clearGlobalServicesRegistry(): void {
   globalServicesRegistry.clear();
   processedGlobalModules.clear();
+  OneBunModule.resetDecoratorMetadataDiagnosis();
 }
 
 /**
@@ -274,6 +276,20 @@ export class OneBunModule implements ModuleInstance {
    * Create services with automatic dependency injection
    * Services can depend on other services (including imported ones)
    */
+  /**
+   * Whether the decorator metadata diagnostic has already run (once per process).
+   * Prevents repeated checks across multiple module initializations.
+   */
+  private static decoratorMetadataDiagnosed = false;
+
+  /**
+   * Reset the diagnostic flag (for testing).
+   * @internal
+   */
+  static resetDecoratorMetadataDiagnosis(): void {
+    OneBunModule.decoratorMetadataDiagnosed = false;
+  }
+
   private createServicesWithDI(metadata: ReturnType<typeof getModuleMetadata>): void {
     if (!metadata?.providers) {
       return;
@@ -295,6 +311,26 @@ export class OneBunModule implements ModuleInstance {
       }
     }
 
+    // Run decorator metadata diagnostic once: check that Bun emits design:paramtypes.
+    // If emitDecoratorMetadata is missing from the root tsconfig.json, Bun silently
+    // skips metadata emission and ALL constructor-based DI breaks.
+    // Only mark as diagnosed when we actually found classes with constructor params
+    // (modules with only zero-arg services can't tell us anything).
+    if (!OneBunModule.decoratorMetadataDiagnosed) {
+      const providerClasses = metadata.providers.filter(
+        (p): p is Function => typeof p === 'function',
+      );
+      const diagnosis = diagnoseDecoratorMetadata(providerClasses);
+      if (diagnosis.classesWithParams > 0) {
+        OneBunModule.decoratorMetadataDiagnosed = true;
+        if (!diagnosis.ok) {
+          throw new Error(
+            buildDecoratorMetadataDiagnosticMessage(diagnosis.classesWithParams),
+          );
+        }
+      }
+    }
+
     // Create services in dependency order
     const pendingProviders = [...metadata.providers.filter((p) => typeof p === 'function')];
     const createdServices = new Set<string>();

package/src/queue/adapters/memory.adapter.test.ts

@@ -384,10 +384,6 @@ describe('InMemoryQueueAdapter', () => {
       expect(adapter.supports('priority')).toBe(true);
     });
 
-    it('should support scheduled-jobs', () => {
-      expect(adapter.supports('scheduled-jobs')).toBe(true);
-    });
-
     it('should not support consumer-groups', () => {
       expect(adapter.supports('consumer-groups')).toBe(false);
     });

package/src/queue/adapters/memory.adapter.ts

@@ -15,8 +15,6 @@ import type {
   PublishOptions,
   SubscribeOptions,
   Subscription,
-  ScheduledJobOptions,
-  ScheduledJobInfo,
   MessageHandler,
 } from '../types';
 
@@ -322,49 +320,6 @@ export class InMemoryQueueAdapter implements QueueAdapter {
     return subscription;
   }
 
-  // ============================================================================
-  // Scheduled Jobs
-  // ============================================================================
-
-  async addScheduledJob(name: string, options: ScheduledJobOptions): Promise<void> {
-    this.ensureConnected();
-
-    if (!this.scheduler) {
-      throw new Error('Scheduler not initialized');
-    }
-
-    if (options.schedule.cron) {
-      this.scheduler.addCronJob(name, options.schedule.cron, options.pattern, () => options.data, {
-        metadata: options.metadata,
-        overlapStrategy: options.overlapStrategy,
-      });
-    } else if (options.schedule.every) {
-      this.scheduler.addIntervalJob(name, options.schedule.every, options.pattern, () => options.data, {
-        metadata: options.metadata,
-      });
-    }
-  }
-
-  async removeScheduledJob(name: string): Promise<boolean> {
-    this.ensureConnected();
-
-    if (!this.scheduler) {
-      return false;
-    }
-
-    return this.scheduler.removeJob(name);
-  }
-
-  async getScheduledJobs(): Promise<ScheduledJobInfo[]> {
-    this.ensureConnected();
-
-    if (!this.scheduler) {
-      return [];
-    }
-
-    return this.scheduler.getJobs();
-  }
-
   // ============================================================================
   // Features
   // ============================================================================
@@ -373,7 +328,6 @@ export class InMemoryQueueAdapter implements QueueAdapter {
     switch (feature) {
       case 'delayed-messages':
       case 'priority':
-      case 'scheduled-jobs':
       case 'pattern-subscriptions':
         return true;
       case 'consumer-groups':