@onebun/core 0.2.6 → 0.2.7

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:
@@ -175,6 +181,11 @@ export interface ModuleInstance {
    * 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;
 }
 
 /**
@@ -422,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)
    */
@@ -467,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 */
@@ -528,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