@onebun/core 0.2.6 → 0.2.7

package/src/application/application.ts

@@ -1,4 +1,10 @@
-import { Effect, type Layer } from 'effect';
+import path from 'node:path';
+
+import {
+  type Context,
+  Effect,
+  type Layer,
+} from 'effect';
 
 import type { Controller } from '../module/controller';
 import type { WsClientData } from '../websocket/ws.types';
@@ -45,7 +51,13 @@ import {
   DEFAULT_SSE_TIMEOUT,
 } from '../module/controller';
 import { OneBunModule } from '../module/module';
-import { QueueService, type QueueAdapter } from '../queue';
+import {
+  QueueService,
+  QueueServiceProxy,
+  QueueServiceTag,
+  type QueueAdapter,
+  type QueueConfig,
+} from '../queue';
 import { InMemoryQueueAdapter } from '../queue/adapters/memory.adapter';
 import { RedisQueueAdapter } from '../queue/adapters/redis.adapter';
 import { hasQueueDecorators } from '../queue/decorators';
@@ -88,6 +100,17 @@ try {
   // Docs module not available - this is optional
 }
 
+// Optional CacheService for static file existence caching
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let cacheServiceClass: new (...args: unknown[]) => any = null as any;
+try {
+  // eslint-disable-next-line import/no-extraneous-dependencies
+  const cacheModule = require('@onebun/cache');
+  cacheServiceClass = cacheModule.CacheService;
+} catch {
+  // @onebun/cache not available - use in-memory Map fallback
+}
+
 // Import tracing modules directly
 
 // Global trace context for current request
@@ -113,12 +136,12 @@ function clearGlobalTraceContext(): void {
  * normalizePath('/')       // => '/'
  * normalizePath('/api/v1/') // => '/api/v1'
  */
-function normalizePath(path: string): string {
-  if (path === '/' || path.length <= 1) {
-    return path;
+function normalizePath(pathStr: string): string {
+  if (pathStr === '/' || pathStr.length <= 1) {
+    return pathStr;
   }
 
-  return path.endsWith('/') ? path.slice(0, -1) : path;
+  return pathStr.endsWith('/') ? pathStr.slice(0, -1) : pathStr;
 }
 
 /**
@@ -191,6 +214,29 @@ function resolveHost(explicitHost: string | undefined): string {
   return '0.0.0.0';
 }
 
+/** Default TTL for static file existence cache (ms) when not specified */
+const DEFAULT_STATIC_FILE_EXISTENCE_CACHE_TTL_MS = 60_000;
+
+/** Cache key prefix for static file existence in CacheService */
+const STATIC_EXISTS_CACHE_PREFIX = 'onebun:static:exists:';
+
+/**
+ * Resolve a relative path under a root directory and ensure the result stays inside the root (path traversal protection).
+ * @param rootDir - Absolute path to the static root directory
+ * @param relativePath - URL path segment (e.g. from request path after prefix); must not contain '..' that escapes root
+ * @returns Absolute path if under root, otherwise null
+ */
+function resolvePathUnderRoot(rootDir: string, relativePath: string): string | null {
+  const normalized = path.join(rootDir, relativePath.startsWith('/') ? relativePath.slice(1) : relativePath);
+  const resolved = path.resolve(normalized);
+  const rootResolved = path.resolve(rootDir);
+  if (resolved === rootResolved || resolved.startsWith(rootResolved + path.sep)) {
+    return resolved;
+  }
+
+  return null;
+}
+
 /**
  * OneBun Application
  */
@@ -210,6 +256,7 @@ export class OneBunApplication {
   private wsHandler: WsHandler | null = null;
   private queueService: QueueService | null = null;
   private queueAdapter: QueueAdapter | null = null;
+  private queueServiceProxy: QueueServiceProxy | null = null;
   // Docs (OpenAPI/Swagger) - generated on start()
   private openApiSpec: Record<string, unknown> | null = null;
   private swaggerHtml: string | null = null;
@@ -364,11 +411,11 @@ export class OneBunApplication {
    * const port = app.getConfigValue('server.port'); // number
    * const host = app.getConfigValue('server.host'); // string
    */
-  getConfigValue<P extends DeepPaths<OneBunAppConfig>>(path: P): DeepValue<OneBunAppConfig, P>;
+  getConfigValue<P extends DeepPaths<OneBunAppConfig>>(pathKey: P): DeepValue<OneBunAppConfig, P>;
   /** Fallback for dynamic paths */
-  getConfigValue<T = unknown>(path: string): T;
-  getConfigValue(path: string): unknown {
-    return this.getConfig().get(path);
+  getConfigValue<T = unknown>(pathKey: string): T;
+  getConfigValue(pathKey: string): unknown {
+    return this.getConfig().get(pathKey);
   }
 
   /**
@@ -441,6 +488,16 @@ export class OneBunApplication {
       // so services can safely use this.config.get() in their constructors
       this.rootModule = OneBunModule.create(this.moduleClass, this.loggerLayer, this.config);
 
+      // Register QueueService proxy in DI so controllers/providers/middleware can inject QueueService.
+      // After initializeQueue(), setDelegate(real) is called when queue is enabled.
+      this.queueServiceProxy = new QueueServiceProxy();
+      if (this.ensureModule().registerService) {
+        this.ensureModule().registerService!(
+          QueueServiceTag as Context.Tag<unknown, QueueService>,
+          this.queueServiceProxy as unknown as QueueService,
+        );
+      }
+
       // Start metrics collection if enabled
       if (this.metricsService && this.metricsService.startSystemMetricsCollection) {
         this.metricsService.startSystemMetricsCollection();
@@ -901,6 +958,69 @@ export class OneBunApplication {
          
         drain() { /* no-op */ },
       };
+
+      // Static file serving: resolve root and setup existence cache (CacheService or in-memory Map)
+      const staticOpts = this.options.static;
+      let staticRootResolved: string | null = null;
+      let staticPathPrefix: string | undefined;
+      let staticFallbackFile: string | undefined;
+      let staticCacheTtlMs = 0;
+      // Cache interface: get(key) => value | undefined, set(key, value, ttlMs)
+      type StaticExistsCache = {
+        get(key: string): Promise<boolean | undefined>;
+        set(key: string, value: boolean, ttlMs: number): Promise<void>;
+      };
+      let staticExistsCache: StaticExistsCache | null = null;
+
+      if (staticOpts?.root) {
+        staticRootResolved = path.resolve(staticOpts.root);
+        staticPathPrefix = staticOpts.pathPrefix;
+        staticFallbackFile = staticOpts.fallbackFile;
+        staticCacheTtlMs = staticOpts.fileExistenceCacheTtlMs ?? DEFAULT_STATIC_FILE_EXISTENCE_CACHE_TTL_MS;
+
+        if (staticCacheTtlMs > 0) {
+          if (cacheServiceClass) {
+            try {
+              const cacheService = this.ensureModule().getServiceByClass?.(cacheServiceClass);
+              if (cacheService && typeof cacheService.get === 'function' && typeof cacheService.set === 'function') {
+                staticExistsCache = {
+                  get: (key: string) => cacheService.get(STATIC_EXISTS_CACHE_PREFIX + key),
+                  set: (key: string, value: boolean, ttlMs: number) =>
+                    cacheService.set(STATIC_EXISTS_CACHE_PREFIX + key, value, { ttl: ttlMs }),
+                };
+                this.logger.debug('Static file existence cache using CacheService');
+              }
+            } catch {
+              // CacheService not in module, use fallback
+            }
+          }
+          if (!staticExistsCache) {
+            const map = new Map<string, { exists: boolean; expiresAt: number }>();
+            staticExistsCache = {
+              async get(key: string): Promise<boolean | undefined> {
+                const entry = map.get(key);
+                if (!entry) {
+                  return undefined;
+                }
+                if (staticCacheTtlMs > 0 && Date.now() > entry.expiresAt) {
+                  map.delete(key);
+
+                  return undefined;
+                }
+
+                return entry.exists;
+              },
+              async set(key: string, value: boolean, ttlMs: number): Promise<void> {
+                map.set(key, {
+                  exists: value,
+                  expiresAt: ttlMs > 0 ? Date.now() + ttlMs : Number.MAX_SAFE_INTEGER,
+                });
+              },
+            };
+            this.logger.debug('Static file existence cache using in-memory Map');
+          }
+        }
+      }
       
       this.server = Bun.serve<WsClientData>({
         port: this.options.port,
@@ -920,8 +1040,8 @@ export class OneBunApplication {
             const socketioPath = app.options.websocket?.socketio?.path ?? '/socket.io';
 
             const url = new URL(req.url);
-            const path = normalizePath(url.pathname);
-            const isSocketIoPath = socketioEnabled && path.startsWith(socketioPath);
+            const requestPath = normalizePath(url.pathname);
+            const isSocketIoPath = socketioEnabled && requestPath.startsWith(socketioPath);
             if (upgradeHeader === 'websocket' || isSocketIoPath) {
               const response = await app.wsHandler.handleUpgrade(req, server);
               if (response === undefined) {
@@ -932,6 +1052,60 @@ export class OneBunApplication {
             }
           }
 
+          // Static file serving (GET/HEAD only)
+          if (staticRootResolved && (req.method === 'GET' || req.method === 'HEAD')) {
+            const requestPath = normalizePath(new URL(req.url).pathname);
+            const prefix = staticPathPrefix ?? '/';
+            const hasPrefix = prefix !== '' && prefix !== '/';
+            if (hasPrefix && !requestPath.startsWith(prefix)) {
+              return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+            }
+            const relativePath = hasPrefix ? requestPath.slice(prefix.length) || '/' : requestPath;
+            const resolvedPath = resolvePathUnderRoot(staticRootResolved, relativePath);
+            if (resolvedPath === null) {
+              return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+            }
+
+            const cache = staticCacheTtlMs > 0 ? staticExistsCache : null;
+            const cacheKey = resolvedPath;
+            if (cache) {
+              const cached = await cache.get(cacheKey);
+              if (cached === true) {
+                return new Response(Bun.file(resolvedPath));
+              }
+              if (cached === false) {
+                if (staticFallbackFile) {
+                  const fallbackResolved = resolvePathUnderRoot(staticRootResolved, staticFallbackFile);
+                  if (fallbackResolved !== null) {
+                    return new Response(Bun.file(fallbackResolved));
+                  }
+                }
+
+                return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+              }
+            }
+
+            const file = Bun.file(resolvedPath);
+            const exists = await file.exists();
+            if (cache && staticCacheTtlMs > 0) {
+              await cache.set(cacheKey, exists, staticCacheTtlMs);
+            }
+            if (exists) {
+              return new Response(file);
+            }
+            if (staticFallbackFile) {
+              const fallbackResolved = resolvePathUnderRoot(staticRootResolved, staticFallbackFile);
+              if (fallbackResolved !== null) {
+                const fallbackFile = Bun.file(fallbackResolved);
+                if (await fallbackFile.exists()) {
+                  return new Response(fallbackFile);
+                }
+              }
+            }
+
+            return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+          }
+
           // 404 for everything not matched by routes
           return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
         },
@@ -953,6 +1127,9 @@ export class OneBunApplication {
       }
 
       this.logger.info(`Server started on http://${this.options.host}:${this.options.port}`);
+      if (staticRootResolved) {
+        this.logger.info(`Static files served from ${staticRootResolved}`);
+      }
       if (this.metricsService) {
         this.logger.info(
           `Metrics available at http://${this.options.host}:${this.options.port}${metricsPath}`,
@@ -1481,6 +1658,7 @@ export class OneBunApplication {
       await this.queueService.stop();
       this.queueService = null;
     }
+    this.queueServiceProxy?.setDelegate(null);
 
     // Disconnect queue adapter
     if (this.queueAdapter) {
@@ -1542,43 +1720,57 @@ export class OneBunApplication {
     }
 
     // Create the appropriate adapter
-    const adapterType = queueOptions?.adapter ?? 'memory';
-    
-    if (adapterType === 'memory') {
-      this.queueAdapter = new InMemoryQueueAdapter();
-      this.logger.info('Queue system initialized with in-memory adapter');
-    } else if (adapterType === 'redis') {
-      const redisOptions = queueOptions?.redis ?? {};
-      if (redisOptions.useSharedProvider !== false) {
-        // Use shared Redis provider
-        this.queueAdapter = new RedisQueueAdapter({
-          useSharedClient: true,
-          keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
-        });
-        this.logger.info('Queue system initialized with Redis adapter (shared provider)');
-      } else if (redisOptions.url) {
-        // Create dedicated Redis connection
-        this.queueAdapter = new RedisQueueAdapter({
-          useSharedClient: false,
-          url: redisOptions.url,
-          keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
-        });
-        this.logger.info('Queue system initialized with Redis adapter (dedicated connection)');
+    const adapterOpt = queueOptions?.adapter ?? 'memory';
+
+    if (typeof adapterOpt === 'function') {
+      // Custom adapter constructor (e.g. NATS JetStream)
+      const adapterCtor = adapterOpt;
+      this.queueAdapter = new adapterCtor(queueOptions?.options);
+      await this.queueAdapter.connect();
+      this.logger.info(`Queue system initialized with custom adapter: ${this.queueAdapter.name}`);
+    } else {
+      const adapterType = adapterOpt;
+      if (adapterType === 'memory') {
+        this.queueAdapter = new InMemoryQueueAdapter();
+        this.logger.info('Queue system initialized with in-memory adapter');
+      } else if (adapterType === 'redis') {
+        const redisOptions = queueOptions?.redis ?? {};
+        if (redisOptions.useSharedProvider !== false) {
+          // Use shared Redis provider
+          this.queueAdapter = new RedisQueueAdapter({
+            useSharedClient: true,
+            keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
+          });
+          this.logger.info('Queue system initialized with Redis adapter (shared provider)');
+        } else if (redisOptions.url) {
+          // Create dedicated Redis connection
+          this.queueAdapter = new RedisQueueAdapter({
+            useSharedClient: false,
+            url: redisOptions.url,
+            keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
+          });
+          this.logger.info('Queue system initialized with Redis adapter (dedicated connection)');
+        } else {
+          throw new Error('Redis queue adapter requires either useSharedProvider: true or a url');
+        }
       } else {
-        throw new Error('Redis queue adapter requires either useSharedProvider: true or a url');
+        throw new Error(`Unknown queue adapter type: ${adapterType}`);
       }
-    } else {
-      throw new Error(`Unknown queue adapter type: ${adapterType}`);
-    }
 
-    // Connect the adapter
-    await this.queueAdapter.connect();
+      // Connect the adapter
+      await this.queueAdapter.connect();
+    }
 
     // Create queue service with config
-    this.queueService = new QueueService({
-      adapter: adapterType,
-      options: queueOptions?.redis,
-    });
+    const queueServiceConfig: QueueConfig = {
+      adapter:
+        typeof adapterOpt === 'function' ? this.queueAdapter.type : adapterOpt,
+      options:
+        typeof adapterOpt === 'function'
+          ? (queueOptions?.options as Record<string, unknown> | undefined)
+          : queueOptions?.redis,
+    };
+    this.queueService = new QueueService(queueServiceConfig);
     
     // Initialize with the adapter
     await this.queueService.initialize(this.queueAdapter);
@@ -1603,6 +1795,9 @@ export class OneBunApplication {
     // Start the queue service
     await this.queueService.start();
     this.logger.info('Queue service started');
+
+    // Wire the real QueueService into the DI proxy so injected consumers use it
+    this.queueServiceProxy?.setDelegate(this.queueService);
   }
 
   /**

package/src/application/multi-service-application.test.ts

@@ -181,6 +181,21 @@ describe('MultiServiceApplication', () => {
     });
   });
 
+  describe('queue option', () => {
+    test('should accept queue option and pass it to child applications', () => {
+      const app = new MultiServiceApplication({
+        services: {
+          serviceA: { module: TestModuleA, port: 3001 },
+        },
+        queue: {
+          enabled: true,
+          adapter: 'memory',
+        },
+      });
+      expect(app).toBeDefined();
+    });
+  });
+
   describe('filtering configuration', () => {
     test('should accept enabledServices option', () => {
       const app = new MultiServiceApplication({

package/src/application/multi-service-application.ts

@@ -219,6 +219,8 @@ export class MultiServiceApplication<TServices extends ServicesMap = ServicesMap
           ...mergedOptions.tracing,
           serviceName: name,
         },
+        queue: this.options.queue,
+        static: mergedOptions.static ?? serviceConfig.static,
       });
 
       this.applications.set(name, app);

package/src/application/multi-service.types.ts

@@ -30,7 +30,7 @@ export type TracingOptions = NonNullable<ApplicationOptions['tracing']>;
  * Any new shared options should be added to ApplicationOptions first.
  */
 export interface BaseServiceOptions
-  extends Pick<ApplicationOptions, 'host' | 'basePath' | 'metrics' | 'tracing' | 'middleware'> {
+  extends Pick<ApplicationOptions, 'host' | 'basePath' | 'metrics' | 'tracing' | 'middleware' | 'static'> {
   /**
    * Add service name as prefix to all routes.
    * When true, the service name will be used as routePrefix.
@@ -132,4 +132,10 @@ export interface MultiServiceApplicationOptions<TServices extends ServicesMap =
    * ```
    */
   externalServiceUrls?: Partial<Record<keyof TServices, string>>;
+
+  /**
+   * Queue configuration applied to all services.
+   * When set, each service's OneBunApplication receives this queue config.
+   */
+  queue?: ApplicationOptions['queue'];
 }

package/src/docs-examples.test.ts

@@ -1648,7 +1648,7 @@ describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', ()
 
   describe('Controller Lifecycle Hooks', () => {
     /**
-     * @source docs/api/controllers.md#lifecycle-hooks
+     * @source docs/api/services.md#lifecycle-hooks (controllers support the same hooks)
      */
     it('should implement lifecycle hooks in controllers', () => {
       // From docs: Controller lifecycle hooks example
@@ -2406,6 +2406,34 @@ describe('OneBunApplication (docs/api/core.md)', () => {
     const app = new OneBunApplication(AppModule, { tracing: tracingOptions, loggerLayer: makeMockLoggerLayer() });
     expect(app).toBeDefined();
   });
+
+  /**
+   * @source docs/api/core.md#staticapplicationoptions
+   */
+  it('should accept static file serving configuration (SPA on same host)', async () => {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const os = await import('node:os');
+
+    const tmpDir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'onebun-docs-static-'));
+    try {
+      fs.writeFileSync(path.join(tmpDir, 'index.html'), '<!DOCTYPE html><html><body>SPA</body></html>', 'utf8');
+
+      @Module({ controllers: [] })
+      class AppModule {}
+
+      // From docs: Static files (SPA on same host)
+      const app = new OneBunApplication(AppModule, {
+        loggerLayer: makeMockLoggerLayer(),
+        static: { root: tmpDir, fallbackFile: 'index.html' },
+      });
+      expect(app).toBeDefined();
+      await app.start();
+      await app.stop();
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('MultiServiceApplication (docs/api/core.md)', () => {

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   type WsStorageType,
   type WsStorageOptions,
   type WebSocketApplicationOptions,
+  type StaticApplicationOptions,
   // Docs types
   type DocsApplicationOptions,
   // SSE types

package/src/module/module.ts

@@ -22,6 +22,7 @@ import {
   isGlobalModule,
   registerControllerDependencies,
 } from '../decorators/decorators';
+import { QueueService, QueueServiceTag } from '../queue';
 import { BaseWebSocketGateway } from '../websocket/ws-base-gateway';
 import { isWebSocketGateway } from '../websocket/ws-decorators';
 
@@ -616,6 +617,16 @@ export class OneBunModule implements ModuleInstance {
    * Resolve dependency by type (constructor function)
    */
   private resolveDependencyByType(type: Function): unknown {
+    // QueueService is registered by tag (QueueServiceTag) before setup(); resolve by tag
+    if (type === QueueService) {
+      const byTag = this.serviceInstances.get(
+        QueueServiceTag as Context.Tag<unknown, unknown>,
+      );
+      if (byTag !== undefined) {
+        return byTag;
+      }
+    }
+
     // Find service instance that matches the type
     const serviceInstance = Array.from(this.serviceInstances.values()).find((instance) => {
       if (!instance) {
@@ -1041,6 +1052,13 @@ export class OneBunModule implements ModuleInstance {
     return this.rootLayer;
   }
 
+  /**
+   * 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 {
+    this.serviceInstances.set(tag as Context.Tag<unknown, unknown>, instance);
+  }
+
   /**
    * Create a module from class
    * @param moduleClass - The module class

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

@@ -35,6 +35,7 @@ import {
   MessageAnyGuard,
   createMessageGuard,
   type Message,
+  type QueueAdapter,
   CronExpression,
   parseCronExpression,
   getNextRun,
@@ -113,9 +114,9 @@ describe('Setup Section Examples (docs/api/queue.md)', () => {
  * @source docs/api/queue.md#quick-start
  */
 describe('Quick Start Example (docs/api/queue.md)', () => {
-  it('should define service with queue decorators', () => {
-    // From docs/api/queue.md: Quick Start
-    class OrderService {
+  it('should define controller with queue decorators', () => {
+    // From docs/api/queue.md: Quick Start (queue handlers must be in controllers)
+    class EventProcessor {
       @OnQueueReady()
       onReady() {
         // console.log('Queue connected');
@@ -134,19 +135,19 @@ describe('Quick Start Example (docs/api/queue.md)', () => {
     }
 
     // Verify decorators are registered
-    expect(hasQueueDecorators(OrderService)).toBe(true);
+    expect(hasQueueDecorators(EventProcessor)).toBe(true);
 
-    const subscriptions = getSubscribeMetadata(OrderService);
+    const subscriptions = getSubscribeMetadata(EventProcessor);
     expect(subscriptions.length).toBe(1);
     expect(subscriptions[0].pattern).toBe('orders.created');
 
-    const cronJobs = getCronMetadata(OrderService);
+    const cronJobs = getCronMetadata(EventProcessor);
     expect(cronJobs.length).toBe(1);
     expect(cronJobs[0].expression).toBe(CronExpression.EVERY_HOUR);
     expect(cronJobs[0].options.pattern).toBe('cleanup.expired');
   });
 
-  it('should define service with interval decorator', () => {
+  it('should define controller with interval decorator', () => {
     // From docs/api/queue.md: Quick Start - Interval example
     class EventProcessor {
       @Subscribe('orders.created')
@@ -389,9 +390,9 @@ describe('Message Guards Examples (docs/api/queue.md)', () => {
  * @source docs/api/queue.md#lifecycle-decorators
  */
 describe('Lifecycle Decorators Examples (docs/api/queue.md)', () => {
-  it('should define lifecycle handlers', () => {
-    // From docs/api/queue.md: Lifecycle Decorators section
-    class EventService {
+  it('should define lifecycle handlers on controller', () => {
+    // From docs/api/queue.md: Lifecycle Decorators (handlers must be in controllers)
+    class EventProcessor {
       @OnQueueReady()
       handleReady() {
         // console.log('Queue connected');
@@ -418,8 +419,67 @@ describe('Lifecycle Decorators Examples (docs/api/queue.md)', () => {
       }
     }
 
-    // Class should be defined without errors
-    expect(EventService).toBeDefined();
+    // Class with lifecycle handlers only; hasQueueDecorators checks Subscribe/Cron/Interval/Timeout only
+    expect(EventProcessor).toBeDefined();
+  });
+});
+
+/**
+ * @source docs/api/queue.md#custom-adapter-nats-jetstream
+ */
+describe('Custom adapter NATS JetStream (docs/api/queue.md)', () => {
+  it('should use custom adapter constructor with options', async () => {
+    // From docs/api/queue.md: Custom adapter: NATS JetStream
+    // Minimal adapter class that implements QueueAdapter for use with queue: { adapter, options }
+    /* eslint-disable @typescript-eslint/no-empty-function */
+    class NatsJetStreamAdapter implements QueueAdapter {
+      readonly name = 'nats-jetstream';
+      readonly type = 'jetstream';
+      constructor(private opts: { servers: string; stream?: string }) {}
+      async connect(): Promise<void> {}
+      async disconnect(): Promise<void> {}
+      isConnected(): boolean {
+        return true;
+      }
+      async publish(): Promise<string> {
+        return '';
+      }
+      async publishBatch(): Promise<string[]> {
+        return [];
+      }
+      async subscribe(): Promise<import('./types').Subscription> {
+        return {
+          async unsubscribe() {},
+          pause() {},
+          resume() {},
+          pattern: '',
+          isActive: true,
+        };
+      }
+      async addScheduledJob(): Promise<void> {}
+      async removeScheduledJob(): Promise<boolean> {
+        return false;
+      }
+      async getScheduledJobs(): Promise<import('./types').ScheduledJobInfo[]> {
+        return [];
+      }
+      supports(): boolean {
+        return false;
+      }
+      on(): void {}
+      off(): void {}
+    }
+    /* eslint-enable @typescript-eslint/no-empty-function */
+
+    const adapter = new NatsJetStreamAdapter({
+      servers: 'nats://localhost:4222',
+      stream: 'EVENTS',
+    });
+    await adapter.connect();
+    expect(adapter.name).toBe('nats-jetstream');
+    expect(adapter.type).toBe('jetstream');
+    expect(adapter.isConnected()).toBe(true);
+    await adapter.disconnect();
   });
 });
 

package/src/queue/index.ts

@@ -113,6 +113,10 @@ export {
   createQueueService,
   resolveAdapterType,
 } from './queue.service';
+export {
+  QueueServiceProxy,
+  QUEUE_NOT_ENABLED_ERROR_MESSAGE,
+} from './queue-service-proxy';
 
 // Adapters (re-export from adapters folder)
 export * from './adapters';