npm - @onebun/core - Versions diffs - 0.2.5 → 0.2.7 - Mend

@onebun/core 0.2.5 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/package.json +6 -6
package/src/application/application.test.ts +865 -1
package/src/application/application.ts +247 -48
package/src/application/multi-service-application.test.ts +15 -0
package/src/application/multi-service-application.ts +2 -0
package/src/application/multi-service.types.ts +7 -1
package/src/decorators/decorators.test.ts +28 -0
package/src/decorators/decorators.ts +26 -0
package/src/docs-examples.test.ts +29 -1
package/src/index.ts +1 -0
package/src/module/module.test.ts +60 -7
package/src/module/module.ts +36 -0
package/src/queue/docs-examples.test.ts +72 -12
package/src/queue/index.ts +4 -0
package/src/queue/queue-service-proxy.test.ts +82 -0
package/src/queue/queue-service-proxy.ts +114 -0
package/src/queue/types.ts +2 -2
package/src/types.ts +62 -3

package/src/application/application.test.ts CHANGED Viewed

@@ -1,3 +1,6 @@
+import fs from 'node:fs';
+import os from 'node:os';
 import { type as arktype } from 'arktype';
 import {
   describe,
@@ -10,7 +13,14 @@ import {
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { register } from 'prom-client';
-import type { ApplicationOptions } from '../types';
+import type { QueueAdapter, Subscription } from '../queue/types';
+import type { ApplicationOptions, ModuleInstance } from '../types';
+import type {
+  MiddlewareClass,
+  OneBunRequest,
+  OneBunResponse,
+} from '../types';
+import type { OnModuleConfigure } from '../types';
 import {
   Module,
@@ -23,10 +33,17 @@ import {
   Header,
   Cookie,
   Req,
+  UseMiddleware,
+  Middleware,
 } from '../decorators/decorators';
 import { Controller as BaseController } from '../module/controller';
+import { BaseMiddleware } from '../module/middleware';
+import { Service } from '../module/service';
+import { QueueService, QUEUE_NOT_ENABLED_ERROR_MESSAGE } from '../queue';
+import { Subscribe } from '../queue/decorators';
 import { makeMockLoggerLayer } from '../testing/test-utils';
 import { OneBunApplication } from './application';
 // Helper function to create app with mock logger to suppress logs in tests
@@ -2079,6 +2096,179 @@ describe('OneBunApplication', () => {
       expect(response.status).toBe(404);
     });
+    describe('Static file serving', () => {
+      test('should serve file from static root when static.root is set', async () => {
+        const pathMod = await import('node:path');
+        const tmpDir = fs.mkdtempSync(pathMod.join(fs.realpathSync(os.tmpdir()), 'onebun-static-'));
+        try {
+          const indexPath = pathMod.join(tmpDir, 'index.html');
+          fs.writeFileSync(indexPath, '<html>Hello</html>', 'utf8');
+          @Module({})
+          class TestModule {}
+          const app = createTestApp(TestModule, {
+            static: { root: tmpDir },
+          });
+          await app.start();
+          const request = new Request('http://localhost:3000/index.html', { method: 'GET' });
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const response = await (mockServer as any).fetchHandler(request);
+          expect(response.status).toBe(200);
+          expect(await response.text()).toBe('<html>Hello</html>');
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      });
+      test('should return 404 when static is not configured', async () => {
+        @Module({})
+        class TestModule {}
+        const app = createTestApp(TestModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        expect(response.status).toBe(404);
+      });
+      test('should respect pathPrefix and serve only under prefix', async () => {
+        const pathMod = await import('node:path');
+        const tmpDir = fs.mkdtempSync(pathMod.join(fs.realpathSync(os.tmpdir()), 'onebun-static-'));
+        try {
+          fs.writeFileSync(pathMod.join(tmpDir, 'foo.html'), '<html>Foo</html>', 'utf8');
+          @Module({})
+          class TestModule {}
+          const app = createTestApp(TestModule, {
+            static: { root: tmpDir, pathPrefix: '/app' },
+          });
+          await app.start();
+          const reqUnderPrefix = new Request('http://localhost:3000/app/foo.html', { method: 'GET' });
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const resUnder = await (mockServer as any).fetchHandler(reqUnderPrefix);
+          expect(resUnder.status).toBe(200);
+          expect(await resUnder.text()).toBe('<html>Foo</html>');
+          const reqOutsidePrefix = new Request('http://localhost:3000/foo.html', { method: 'GET' });
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const resOutside = await (mockServer as any).fetchHandler(reqOutsidePrefix);
+          expect(resOutside.status).toBe(404);
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      });
+      test('should return fallbackFile for missing path when fallbackFile is set', async () => {
+        const pathMod = await import('node:path');
+        const tmpDir = fs.mkdtempSync(pathMod.join(fs.realpathSync(os.tmpdir()), 'onebun-static-'));
+        try {
+          fs.writeFileSync(pathMod.join(tmpDir, 'index.html'), '<html>SPA</html>', 'utf8');
+          @Module({})
+          class TestModule {}
+          const app = createTestApp(TestModule, {
+            static: { root: tmpDir, fallbackFile: 'index.html' },
+          });
+          await app.start();
+          const request = new Request('http://localhost:3000/any/client/route', { method: 'GET' });
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const response = await (mockServer as any).fetchHandler(request);
+          expect(response.status).toBe(200);
+          expect(await response.text()).toBe('<html>SPA</html>');
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      });
+      test('should reject path traversal and return 404', async () => {
+        const pathMod = await import('node:path');
+        const tmpDir = fs.mkdtempSync(pathMod.join(fs.realpathSync(os.tmpdir()), 'onebun-static-'));
+        try {
+          fs.writeFileSync(pathMod.join(tmpDir, 'safe.txt'), 'safe', 'utf8');
+          @Module({})
+          class TestModule {}
+          const app = createTestApp(TestModule, {
+            static: { root: tmpDir },
+          });
+          await app.start();
+          const request = new Request('http://localhost:3000/../etc/passwd', { method: 'GET' });
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const response = await (mockServer as any).fetchHandler(request);
+          expect(response.status).toBe(404);
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      });
+      test('should cache file existence and serve from cache on second request', async () => {
+        const pathMod = await import('node:path');
+        const tmpDir = fs.mkdtempSync(pathMod.join(fs.realpathSync(os.tmpdir()), 'onebun-static-'));
+        try {
+          const filePath = pathMod.join(tmpDir, 'cached.html');
+          fs.writeFileSync(filePath, '<html>Cached</html>', 'utf8');
+          @Module({})
+          class TestModule {}
+          const app = createTestApp(TestModule, {
+            static: { root: tmpDir, fileExistenceCacheTtlMs: 60_000 },
+          });
+          await app.start();
+          const request = new Request('http://localhost:3000/cached.html', { method: 'GET' });
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const response1 = await (mockServer as any).fetchHandler(request);
+          expect(response1.status).toBe(200);
+          expect(await response1.text()).toBe('<html>Cached</html>');
+          // Second request should still return the file (cache hit; no extra disk read for existence)
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const response2 = await (mockServer as any).fetchHandler(request);
+          expect(response2.status).toBe(200);
+          expect(await response2.text()).toBe('<html>Cached</html>');
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      });
+      test('should not serve static for POST', async () => {
+        const pathMod = await import('node:path');
+        const tmpDir = fs.mkdtempSync(pathMod.join(fs.realpathSync(os.tmpdir()), 'onebun-static-'));
+        try {
+          fs.writeFileSync(pathMod.join(tmpDir, 'index.html'), '<html>Hi</html>', 'utf8');
+          @Module({})
+          class TestModule {}
+          const app = createTestApp(TestModule, { static: { root: tmpDir } });
+          await app.start();
+          const request = new Request('http://localhost:3000/index.html', { method: 'POST' });
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const response = await (mockServer as any).fetchHandler(request);
+          expect(response.status).toBe(404);
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      });
+    });
     test('should handle method not allowed', async () => {
       @Controller('/api')
       class ApiController extends BaseController {
@@ -2562,6 +2752,517 @@ describe('OneBunApplication', () => {
       // Verify they are the same (no duplication due to trailing slash)
       expect(recordedMetrics[0].route).toBe(recordedMetrics[1].route);
     });
+    describe('Middleware composition (docs: controllers.md#middleware-execution-order)', () => {
+      test('should run route-level middlewares left-to-right then handler', async () => {
+        const order: string[] = [];
+        class MwA extends BaseMiddleware {
+          async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('MwA');
+            const res = await next();
+            order.push('MwA-after');
+            return res;
+          }
+        }
+        class MwB extends BaseMiddleware {
+          async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('MwB');
+            const res = await next();
+            order.push('MwB-after');
+            return res;
+          }
+        }
+        @Controller('/api')
+        class ApiController extends BaseController {
+          @Get('/chain')
+          @UseMiddleware(MwA, MwB)
+          getChain() {
+            order.push('handler');
+            return this.success({ ok: true });
+          }
+        }
+        @Module({ controllers: [ApiController] })
+        class TestModule {}
+        const app = createTestApp(TestModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/api/chain', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        const body = await response.json();
+        expect(response.status).toBe(200);
+        expect(body.result).toEqual({ ok: true });
+        expect(order).toEqual(['MwA', 'MwB', 'handler', 'MwB-after', 'MwA-after']);
+      });
+      test('should run controller-level then route-level middleware', async () => {
+        const order: string[] = [];
+        class CtrlMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('CtrlMw');
+            return await next();
+          }
+        }
+        class RouteMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('RouteMw');
+            return await next();
+          }
+        }
+        @Controller('/api')
+        @UseMiddleware(CtrlMw)
+        class ApiController extends BaseController {
+          @Get('/dashboard')
+          getDashboard() {
+            order.push('handler');
+            return this.success({ stats: {} });
+          }
+          @Get('/settings')
+          @UseMiddleware(RouteMw)
+          getSettings() {
+            order.push('handler-settings');
+            return this.success({ updated: false });
+          }
+        }
+        @Module({ controllers: [ApiController] })
+        class TestModule {}
+        const app = createTestApp(TestModule);
+        await app.start();
+        order.length = 0;
+        const req1 = new Request('http://localhost:3000/api/dashboard', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res1 = await (mockServer as any).fetchHandler(req1);
+        expect(res1.status).toBe(200);
+        expect(order).toEqual(['CtrlMw', 'handler']);
+        order.length = 0;
+        const req2 = new Request('http://localhost:3000/api/settings', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res2 = await (mockServer as any).fetchHandler(req2);
+        expect(res2.status).toBe(200);
+        expect(order).toEqual(['CtrlMw', 'RouteMw', 'handler-settings']);
+      });
+      test('should run module-level then controller-level then route-level middleware', async () => {
+        const order: string[] = [];
+        class ModuleMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('ModuleMw');
+            return await next();
+          }
+        }
+        class CtrlMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('CtrlMw');
+            return await next();
+          }
+        }
+        class RouteMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('RouteMw');
+            return await next();
+          }
+        }
+        @Controller('/admin')
+        @UseMiddleware(CtrlMw)
+        class AdminController extends BaseController {
+          @Get('/users')
+          @UseMiddleware(RouteMw)
+          getUsers() {
+            order.push('handler');
+            return this.success({ users: [] });
+          }
+        }
+        @Module({ controllers: [AdminController] })
+        class TestModule implements OnModuleConfigure {
+          configureMiddleware(): MiddlewareClass[] {
+            return [ModuleMw];
+          }
+        }
+        const app = createTestApp(TestModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/admin/users', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        const body = await response.json();
+        expect(response.status).toBe(200);
+        expect(body.result).toEqual({ users: [] });
+        expect(order).toEqual(['ModuleMw', 'CtrlMw', 'RouteMw', 'handler']);
+      });
+      test('should run application-wide then module then controller then route middleware', async () => {
+        const order: string[] = [];
+        class GlobalMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('GlobalMw');
+            return await next();
+          }
+        }
+        class ModuleMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('ModuleMw');
+            return await next();
+          }
+        }
+        class CtrlMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('CtrlMw');
+            return await next();
+          }
+        }
+        class RouteMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('RouteMw');
+            return await next();
+          }
+        }
+        @Controller('/admin')
+        @UseMiddleware(CtrlMw)
+        class AdminController extends BaseController {
+          @Get('/stats')
+          @UseMiddleware(RouteMw)
+          getStats() {
+            order.push('handler');
+            return this.success({ stats: {} });
+          }
+        }
+        @Module({ controllers: [AdminController] })
+        class TestModule implements OnModuleConfigure {
+          configureMiddleware(): MiddlewareClass[] {
+            return [ModuleMw];
+          }
+        }
+        const app = createTestApp(TestModule, { middleware: [GlobalMw] });
+        await app.start();
+        const request = new Request('http://localhost:3000/admin/stats', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        const body = await response.json();
+        expect(response.status).toBe(200);
+        expect(body.result).toEqual({ stats: {} });
+        expect(order).toEqual(['GlobalMw', 'ModuleMw', 'CtrlMw', 'RouteMw', 'handler']);
+      });
+      test('should short-circuit when middleware returns without calling next()', async () => {
+        const order: string[] = [];
+        class AuthMw extends BaseMiddleware {
+          async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            order.push('AuthMw');
+            const token = req.headers.get('X-Test-Token');
+            if (token !== 'secret') {
+              return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+                status: 403,
+                // eslint-disable-next-line @typescript-eslint/naming-convention
+                headers: { 'Content-Type': 'application/json' },
+              });
+            }
+            return await next();
+          }
+        }
+        @Controller('/api')
+        class ApiController extends BaseController {
+          @Get('/protected')
+          @UseMiddleware(AuthMw)
+          getProtected() {
+            order.push('handler');
+            return { data: 'secret' };
+          }
+        }
+        @Module({ controllers: [ApiController] })
+        class TestModule {}
+        const app = createTestApp(TestModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/api/protected', {
+          method: 'GET',
+          // eslint-disable-next-line @typescript-eslint/naming-convention
+          headers: { 'X-Test-Token': 'wrong' },
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        const body = await response.json();
+        expect(response.status).toBe(403);
+        expect(body.error).toBe('Unauthorized');
+        expect(order).toEqual(['AuthMw']);
+      });
+      test('should allow middleware to modify response after next() (onion model)', async () => {
+        class AddHeaderAfterNextMw extends BaseMiddleware {
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            const res = await next();
+            res.headers.set('X-After-Next', 'true');
+            return res;
+          }
+        }
+        @Controller('/api')
+        class ApiController extends BaseController {
+          @Get('/onion')
+          @UseMiddleware(AddHeaderAfterNextMw)
+          getOnion() {
+            return this.success({ value: 1 });
+          }
+        }
+        @Module({ controllers: [ApiController] })
+        class TestModule {}
+        const app = createTestApp(TestModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/api/onion', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        const body = await response.json();
+        expect(response.status).toBe(200);
+        expect(body.result).toEqual({ value: 1 });
+        expect(response.headers.get('X-After-Next')).toBe('true');
+      });
+    });
+    describe('Middleware DI (service injection)', () => {
+      test('should inject service into application-wide middleware', async () => {
+        @Service()
+        class RootService {
+          getValue(): string {
+            return 'global';
+          }
+        }
+        @Middleware()
+        class GlobalMw extends BaseMiddleware {
+          constructor(private readonly svc: RootService) {
+            super();
+          }
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            const res = await next();
+            res.headers.set('X-Injected-Value', this.svc.getValue());
+            return res;
+          }
+        }
+        @Controller('/api')
+        class ApiController extends BaseController {
+          @Get('/ping')
+          ping() {
+            return this.success({ pong: true });
+          }
+        }
+        @Module({ controllers: [ApiController], providers: [RootService] })
+        class TestModule {}
+        const app = createTestApp(TestModule, { middleware: [GlobalMw] });
+        await app.start();
+        const request = new Request('http://localhost:3000/api/ping', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('X-Injected-Value')).toBe('global');
+      });
+      test('should inject service into module-level middleware', async () => {
+        @Service()
+        class FeatureService {
+          getValue(): string {
+            return 'module';
+          }
+        }
+        @Middleware()
+        class FeatureModuleMw extends BaseMiddleware {
+          constructor(private readonly svc: FeatureService) {
+            super();
+          }
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            const res = await next();
+            res.headers.set('X-Injected-Value', this.svc.getValue());
+            return res;
+          }
+        }
+        @Controller('/feature')
+        class FeatureController extends BaseController {
+          @Get('/data')
+          getData() {
+            return this.success({ data: true });
+          }
+        }
+        @Module({ controllers: [FeatureController], providers: [FeatureService] })
+        class FeatureModule implements OnModuleConfigure {
+          configureMiddleware(): MiddlewareClass[] {
+            return [FeatureModuleMw];
+          }
+        }
+        @Module({ imports: [FeatureModule], controllers: [] })
+        class RootModule {}
+        const app = createTestApp(RootModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/feature/data', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('X-Injected-Value')).toBe('module');
+      });
+      test('should inject service into controller-level middleware from owner module', async () => {
+        @Service()
+        class FeatureService {
+          getValue(): string {
+            return 'controller';
+          }
+        }
+        @Middleware()
+        class FeatureCtrlMw extends BaseMiddleware {
+          constructor(private readonly svc: FeatureService) {
+            super();
+          }
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            const res = await next();
+            res.headers.set('X-Injected-Value', this.svc.getValue());
+            return res;
+          }
+        }
+        @Controller('/feature')
+        @UseMiddleware(FeatureCtrlMw)
+        class FeatureController extends BaseController {
+          @Get('/ctrl')
+          getCtrl() {
+            return this.success({ ok: true });
+          }
+        }
+        @Module({ controllers: [FeatureController], providers: [FeatureService] })
+        class FeatureModule {}
+        @Module({ imports: [FeatureModule], controllers: [] })
+        class RootModule {}
+        const app = createTestApp(RootModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/feature/ctrl', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('X-Injected-Value')).toBe('controller');
+      });
+      test('should inject service into route-level middleware from owner module', async () => {
+        @Service()
+        class FeatureService {
+          getValue(): string {
+            return 'route';
+          }
+        }
+        @Middleware()
+        class FeatureRouteMw extends BaseMiddleware {
+          constructor(private readonly svc: FeatureService) {
+            super();
+          }
+          async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+            const res = await next();
+            res.headers.set('X-Injected-Value', this.svc.getValue());
+            return res;
+          }
+        }
+        @Controller('/feature')
+        class FeatureController extends BaseController {
+          @Get('/route')
+          @UseMiddleware(FeatureRouteMw)
+          getRoute() {
+            return this.success({ ok: true });
+          }
+        }
+        @Module({ controllers: [FeatureController], providers: [FeatureService] })
+        class FeatureModule {}
+        @Module({ imports: [FeatureModule], controllers: [] })
+        class RootModule {}
+        const app = createTestApp(RootModule);
+        await app.start();
+        const request = new Request('http://localhost:3000/feature/route', { method: 'GET' });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const response = await (mockServer as any).fetchHandler(request);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('X-Injected-Value')).toBe('route');
+      });
+    });
   });
   describe('Tracing integration', () => {
@@ -3173,4 +3874,167 @@ describe('OneBunApplication', () => {
       await app.stop();
     });
   });
+  describe('queue custom adapter', () => {
+    /** Mock adapter that records constructor options for testing */
+    /* eslint-disable @typescript-eslint/no-empty-function */
+    class MockCustomAdapter implements QueueAdapter {
+      static receivedOptions: unknown = null;
+      readonly name = 'mock-custom';
+      readonly type = 'jetstream';
+      private connected = false;
+      constructor(options?: unknown) {
+        (this.constructor as typeof MockCustomAdapter).receivedOptions = options;
+      }
+      async connect(): Promise<void> {
+        this.connected = true;
+      }
+      async disconnect(): Promise<void> {
+        this.connected = false;
+      }
+      isConnected(): boolean {
+        return this.connected;
+      }
+      async publish(): Promise<string> {
+        return 'mock-id';
+      }
+      async publishBatch(): Promise<string[]> {
+        return [];
+      }
+      async subscribe(): Promise<Subscription> {
+        return {
+          async unsubscribe() {},
+          pause() {},
+          resume() {},
+          pattern: '',
+          isActive: true,
+        };
+      }
+      async addScheduledJob(): Promise<void> {}
+      async removeScheduledJob(): Promise<boolean> {
+        return false;
+      }
+      async getScheduledJobs(): Promise<import('../queue/types').ScheduledJobInfo[]> {
+        return [];
+      }
+      supports(): boolean {
+        return false;
+      }
+      on(): void {}
+      off(): void {}
+    }
+    /* eslint-enable @typescript-eslint/no-empty-function */
+    @Controller('/q')
+    class QueueTestController extends BaseController {
+      @Subscribe('test.event')
+      async handle(): Promise<void> {}
+    }
+    @Module({
+      controllers: [QueueTestController],
+      providers: [],
+    })
+    class QueueTestModule {}
+    beforeEach(() => {
+      MockCustomAdapter.receivedOptions = null;
+    });
+    test('should initialize queue with custom adapter constructor and options', async () => {
+      const app = createTestApp(QueueTestModule, {
+        port: 0,
+        queue: {
+          enabled: true,
+          adapter: MockCustomAdapter,
+          options: { servers: 'nats://localhost:4222' },
+        },
+      });
+      await app.start();
+      const queueService = app.getQueueService();
+      expect(queueService).not.toBeNull();
+      expect(MockCustomAdapter.receivedOptions).toEqual({
+        servers: 'nats://localhost:4222',
+      });
+      await app.stop();
+    });
+  });
+  describe('QueueService DI injection', () => {
+    @Controller('/queue-di')
+    class QueueDiTestController extends BaseController {
+      constructor(private queueService: QueueService) {
+        super();
+      }
+      /** Exposed for tests: call publish on injected QueueService */
+      publishTest(pattern: string, data: unknown) {
+        return this.queueService.publish(pattern, data);
+      }
+    }
+    @Controller('/q')
+    class QueueSubscribeController extends BaseController {
+      @Subscribe('di.test')
+      async handle(): Promise<void> {}
+    }
+    @Module({
+      controllers: [QueueDiTestController],
+      providers: [],
+    })
+    class QueueDisabledModule {}
+    @Module({
+      controllers: [QueueDiTestController, QueueSubscribeController],
+      providers: [],
+    })
+    class QueueEnabledModule {}
+    test('when queue is enabled, controller with injected QueueService gets working instance', async () => {
+      const app = createTestApp(QueueEnabledModule, {
+        port: 0,
+        queue: {
+          enabled: true,
+          adapter: 'memory',
+        },
+      });
+      await app.start();
+      const rootModule = (app as unknown as { rootModule: ModuleInstance }).rootModule;
+      const controller = rootModule.getControllerInstance?.(QueueDiTestController) as
+        | QueueDiTestController
+        | undefined;
+      expect(controller).toBeDefined();
+      await expect(controller!.publishTest('di.test', {})).resolves.toBeDefined();
+      await app.stop();
+    });
+    test('when queue is disabled, injected QueueService throws on first method call', async () => {
+      const app = createTestApp(QueueDisabledModule, { port: 0 });
+      await app.start();
+      const rootModule = (app as unknown as { rootModule: ModuleInstance }).rootModule;
+      const controller = rootModule.getControllerInstance?.(QueueDiTestController) as
+        | QueueDiTestController
+        | undefined;
+      expect(controller).toBeDefined();
+      await expect(controller!.publishTest('e', {})).rejects.toThrow(
+        QUEUE_NOT_ENABLED_ERROR_MESSAGE,
+      );
+      await app.stop();
+    });
+  });
 });