@onebun/core 0.2.5 → 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();
@@ -758,10 +815,14 @@ export class OneBunApplication {
         // Module-level middleware (already resolved bound functions)
         const moduleMiddleware = this.ensureModule().getModuleMiddleware?.(controllerClass) ?? [];
 
-        // Controller-level middleware — resolve class constructors via root module DI
+        // Resolve controller-level and route-level middleware with the owner module's DI
+        const ownerModule =
+          this.ensureModule().getOwnerModuleForController?.(controllerClass) ?? this.ensureModule();
+
+        // Controller-level middleware — resolve via owner module DI
         const ctrlMiddlewareClasses = getControllerMiddleware(controllerClass);
         const ctrlMiddleware: Function[] = ctrlMiddlewareClasses.length > 0
-          ? (this.ensureModule().resolveMiddleware?.(ctrlMiddlewareClasses) ?? [])
+          ? (ownerModule.resolveMiddleware?.(ctrlMiddlewareClasses) ?? [])
           : [];
 
         for (const route of controllerMetadata.routes) {
@@ -773,10 +834,10 @@ export class OneBunApplication {
             controller,
           );
 
-          // Route-level middleware — resolve class constructors via root module DI
+          // Route-level middleware — resolve via owner module DI
           const routeMiddlewareClasses = route.middleware ?? [];
           const routeMiddleware: Function[] = routeMiddlewareClasses.length > 0
-            ? (this.ensureModule().resolveMiddleware?.(routeMiddlewareClasses) ?? [])
+            ? (ownerModule.resolveMiddleware?.(routeMiddlewareClasses) ?? [])
             : [];
 
           // Merge middleware: global → module → controller → route
@@ -897,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,
@@ -916,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) {
@@ -928,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 });
         },
@@ -949,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}`,
@@ -1477,6 +1658,7 @@ export class OneBunApplication {
       await this.queueService.stop();
       this.queueService = null;
     }
+    this.queueServiceProxy?.setDelegate(null);
 
     // Disconnect queue adapter
     if (this.queueAdapter) {
@@ -1538,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);
@@ -1599,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/decorators/decorators.test.ts

@@ -52,6 +52,7 @@ import {
   Req,
   Res,
   UseMiddleware,
+  Middleware,
   Module,
   getModuleMetadata,
   ApiResponse,
@@ -301,6 +302,33 @@ describe('decorators', () => {
     });
   });
 
+  describe('Middleware decorator', () => {
+    test('should emit design:paramtypes for automatic DI', () => {
+      @Service()
+      class HelperService {
+        getValue() {
+          return 'ok';
+        }
+      }
+
+      @Middleware()
+      class TestMiddleware extends BaseMiddleware {
+        constructor(private readonly helper: HelperService) {
+          super();
+        }
+
+        async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+          return await next();
+        }
+      }
+
+      const deps = getConstructorParamTypes(TestMiddleware);
+      expect(deps).toBeDefined();
+      expect(deps).toHaveLength(1);
+      expect(deps?.[0]).toBe(HelperService);
+    });
+  });
+
   describe('HTTP method decorators', () => {
     test('should register GET route', () => {
       @Controller('test')

package/src/decorators/decorators.ts

@@ -240,6 +240,32 @@ export function Inject<T>(serviceType: new (...args: any[]) => T) {
   };
 }
 
+/**
+ * Class decorator for middleware. Apply to classes that extend BaseMiddleware so that
+ * TypeScript emits design:paramtypes and constructor dependencies are resolved automatically
+ * by the framework (no need for @Inject on each parameter). You can still use @Inject when needed.
+ *
+ * @example
+ * ```ts
+ * @Middleware()
+ * class AuthMiddleware extends BaseMiddleware {
+ *   constructor(private authService: AuthService) {
+ *     super();
+ *   }
+ *   async use(req, next) { ... }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Middleware(): ClassDecorator {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (target: any): any => {
+    injectable()(target);
+
+    return target;
+  };
+}
+
 /**
  * Register dependencies manually (fallback method)
  */

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