Merge pull request #92 from Ecube-Labs/fix-method-all-catch-all

fix: register method: 'all' route specs as catch-all

Author: selenehyun

README.md

@@ -121,6 +121,25 @@ app.listen(3000, () => {
 You can also implement your custom adapter by implementing the `XRouterAdaptor` interface.
 This allows you to use your preferred validation library for route validation.
 
+### Catch-all routes (`method: 'all'`)
+
+Use `method: 'all'` (case-insensitive) to register a catch-all route that matches every
+HTTP verb the router supports, mirroring `@koa/router`'s `router.all()` and keeping
+compatibility with `koa-joi-router`. This is handy for proxy or fallback handlers:
+
+```ts
+router.add({
+    method: 'all',
+    path: '/hubspot/:path(.*)',
+    handler: async (ctx) => {
+        // handles GET, POST, PUT, PATCH, DELETE, ... on /hubspot/*
+    },
+});
+```
+
+In the generated OpenAPI spec, an `'all'` route is expanded into one operation per
+supported verb.
+
 ### CommonJS
 
 ```js

package.json

@@ -1,6 +1,6 @@
 {
     "name": "koa-x-router",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "`koa-x-router` is a library that extends the functionality of `koa-router` by providing validation and automatic API documentation features. It simplifies the process of defining routes, validating request data, and generating API documentation.",
     "type": "module",
     "main": "./dist/cjs/index.js",

src/libs/Router.test.ts

@@ -1120,3 +1120,104 @@ describe('koa-x-router API work with Joi', () => {
         });
     });
 });
+
+describe("koa-x-router API work with method: 'all'", () => {
+    it('should register a catch-all route that matches every HTTP verb', async () => {
+        const app = getApp();
+        const router = new Router();
+        app.use(router.routes());
+
+        router.add({
+            method: 'all',
+            path: '/proxy/:path(.*)',
+            handler: async (ctx) => {
+                ctx.body = `matched ${ctx.method}`;
+            },
+        });
+
+        const getResponse = await request(app.callback()).get('/proxy/foo');
+        expect(getResponse.status).toBe(200);
+        expect(getResponse.text).toBe('matched GET');
+
+        const postResponse = await request(app.callback()).post('/proxy/foo');
+        expect(postResponse.status).toBe(200);
+        expect(postResponse.text).toBe('matched POST');
+
+        const deleteResponse = await request(app.callback()).delete('/proxy/foo/bar');
+        expect(deleteResponse.status).toBe(200);
+        expect(deleteResponse.text).toBe('matched DELETE');
+    });
+
+    it("should treat method: 'ALL' (uppercase) the same as 'all'", async () => {
+        const app = getApp();
+        const router = new Router();
+        app.use(router.routes());
+
+        router.add({
+            method: 'ALL',
+            path: '/any/:path(.*)',
+            handler: async (ctx) => {
+                ctx.body = 'ok';
+            },
+        });
+
+        const putResponse = await request(app.callback()).put('/any/thing');
+        expect(putResponse.status).toBe(200);
+        expect(putResponse.text).toBe('ok');
+    });
+
+    it('should run the middleware chain for a catch-all route', async () => {
+        const app = getApp();
+        const router = new Router();
+        app.use(router.routes());
+
+        let middlewareRan = false;
+        router.use('/guarded/:path(.*)', async (_ctx, next) => {
+            middlewareRan = true;
+            await next();
+        });
+
+        router.add({
+            method: 'all',
+            path: '/guarded/:path(.*)',
+            handler: async (ctx) => {
+                ctx.body = 'guarded';
+            },
+        });
+
+        const response = await request(app.callback()).get('/guarded/foo');
+        expect(response.status).toBe(200);
+        expect(response.text).toBe('guarded');
+        expect(middlewareRan).toBe(true);
+    });
+
+    it('should expand a catch-all route into per-verb operations in the OpenAPI spec', () => {
+        const router = new Router();
+
+        router.add({
+            method: 'all',
+            path: '/proxy',
+            meta: {
+                document: {
+                    summary: 'Proxy everything',
+                },
+            },
+            handler: async (ctx) => {
+                ctx.body = {};
+            },
+        });
+
+        const spec = JSON.parse(
+            router.generateOpenApiSpecJson({
+                info: {
+                    title: 'koa-x-router',
+                    version: '1.0.0',
+                },
+            }),
+        );
+
+        const operations = Object.keys(spec.paths['/proxy']);
+        expect(operations).toEqual(expect.arrayContaining(['get', 'post', 'put', 'patch', 'delete', 'options']));
+        expect(spec.paths['/proxy'].get.summary).toBe('Proxy everything');
+    });
+});

src/libs/Router.ts

@@ -43,6 +43,8 @@ export interface SchemaLike {}
 
 type SupportMethod = 'get' | 'post' | 'delete' | 'put' | 'options' | 'head' | 'patch' | 'trace';
 
+type AllMethod = 'all' | 'ALL';
+
 type SchemaMetadata = {
     summary: string;
     description?: string;
@@ -52,7 +54,7 @@ type SchemaMetadata = {
 };
 
 export interface RouteLayerSpec<StateT = any, CustomT = {}> {
-    method: SupportMethod | Uppercase<SupportMethod>;
+    method: SupportMethod | Uppercase<SupportMethod> | AllMethod;
     path: string;
     meta?: {
         // compatible for `koa-joi-router-docs`
@@ -93,7 +95,11 @@ export class Router<StateT = any, CustomT = {}> extends KoaRouter<StateT, Custom
         specs.forEach((spec) => {
             const { validate, meta } = spec;
 
-            const layer = super.register(spec.path, [spec.method], [spec.handler], {
+            // `method: 'all'`(대소문자 무관)은 koa-joi-router의 `router.all()`처럼
+            // 라우터가 지원하는 모든 verb에 매칭되는 catch-all로 등록한다.
+            const methods = String(spec.method).toLowerCase() === 'all' ? this.methods : [spec.method];
+
+            const layer = super.register(spec.path, methods, [spec.handler], {
                 name: spec.path,
             });