@e22m4u/js-trie-router 0.5.12 → 0.5.13

package/README.md

@@ -16,7 +16,8 @@ HTTP маршрутизатор для Node.js на основе
 ## Содержание
 
 - [Установка](#установка)
-- [Обзор](#обзор)
+- [Расширения](#расширения)
+- [Использование](#использование)
   - [Контекст запроса](#контекст-запроса)
   - [Отправка ответа](#отправка-ответа)
   - [Хуки маршрута](#хуки-маршрута)
@@ -53,7 +54,7 @@ import {TrieRouter} from '@e22m4u/js-trie-router';
 const {TrieRouter} = require('@e22m4u/js-trie-router');
 ```
 
-## Обзор
+## Использование
 
 Базовый пример создания экземпляра роутера, объявления маршрута
 и передачи слушателя запросов HTTP серверу.
@@ -255,16 +256,28 @@ router.defineRoute({
 
 - `preHandler` выполняется перед вызовом обработчика каждого маршрута;
 - `postHandler` выполняется после вызова обработчика каждого маршрута;
+- `onDefineRoute` выполняется в момент регистрации маршрута;
 
 Добавить глобальные хуки можно методами экземпляра `TrieRouter`.
 
 ```js
-router.addPreHandler((ctx) => {
+import {RouterHookType} form '@e22m4u/js-trie-router';
+
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
   // перед обработчиком маршрута
 });
-router.addPostHandler((ctx, data) => {
+
+router.addHook(RouterHookType.POST_HANDLER, (ctx, data) => {
   // после обработчика маршрута
 });
+
+router.addHook(RouterHookType.ON_DEFINE_ROUTE, (routeDef) => {
+  // позволяет модифицировать определение
+  // маршрута в момент регистрации
+  routeDef.method = HttpMethod.POST;
+  routeDef.path = '/myPath';
+  routeDef.handler = () => 'OK';
+});
 ```
 
 Аналогично хукам маршрута, если глобальный хук возвращает значение
@@ -284,14 +297,19 @@ router.addPostHandler((ctx, data) => {
 
 ```js
 import http from 'http';
-import {TrieRouter, HttpMethod} from '@e22m4u/js-trie-router';
+
+import {
+  TrieRouter,
+  HttpMethod,
+  RouterHookType,
+} from '@e22m4u/js-trie-router';
 
 const server = new http.Server();
 const router = new TrieRouter();
 
 // глобальный pre-handler хук, который срабатывает
 // перед основным обработчиком каждого маршрута
-router.addPreHandler((ctx) => {
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
   // доступ к метаданным текущего маршрута
   console.log(ctx.meta); // {foo: 'bar'}
 });
@@ -318,12 +336,17 @@ server.listen(3000, 'localhost');
 
 ```js
 import http from 'http';
-import {TrieRouter, HttpMethod} from '@e22m4u/js-trie-router';
+
+import {
+  TrieRouter,
+  HttpMethod,
+  RouterHookType,
+} from '@e22m4u/js-trie-router';
 
 const router = new TrieRouter();
 
 // глобальный хук авторизации
-router.addPreHandler((ctx) => {
+router.addHook(RouterHookType.PRE_HANDLER, (ctx) => {
   // логика получения пользователя (например, из заголовков)
   const user = {id: 1, name: 'John', role: 'admin'};
   // сохранение данных в state

package/dist/cjs/index.cjs

@@ -794,7 +794,8 @@ var import_js_format11 = require("@e22m4u/js-format");
 var import_js_format10 = require("@e22m4u/js-format");
 var RouterHookType = {
   PRE_HANDLER: "preHandler",
-  POST_HANDLER: "postHandler"
+  POST_HANDLER: "postHandler",
+  ON_DEFINE_ROUTE: "onDefineRoute"
 };
 var ROUTER_HOOK_TYPES = Object.values(RouterHookType);
 var _RouterHookRegistry = class _RouterHookRegistry {
@@ -1500,6 +1501,26 @@ var _RouteRegistry = class _RouteRegistry extends DebuggableService {
         routeDef
       );
     }
+    const hookRegistry = this.getService(RouterHookRegistry);
+    const onDefineRouteHooks = hookRegistry.getHooks(
+      RouterHookType.ON_DEFINE_ROUTE
+    );
+    if (onDefineRouteHooks.length) {
+      debug('Invoking %v "onDefineRoute" hook(s).', onDefineRouteHooks.length);
+      for (const hook of onDefineRouteHooks) {
+        const hookResult = hook({ ...routeDef });
+        if (hookResult !== void 0 && !(hookResult !== null && typeof hookResult === "object" && !Array.isArray(hookResult))) {
+          throw new import_js_format16.InvalidArgumentError(
+            'Hook "onDefineRoute" must return an Object or undefined, but %v was given.',
+            hookResult
+          );
+        }
+        if (hookResult !== void 0) {
+          routeDef = hookResult;
+        }
+      }
+      debug("Hooks invoked.");
+    }
     const route = new Route(routeDef);
     const triePath = `${route.method}/${route.path}`;
     this._trie.add(triePath, route);
@@ -2250,54 +2271,25 @@ var _TrieRouter = class _TrieRouter extends DebuggableService {
     }
   }
   /**
-   * Add pre-handler hook.
-   *
-   * @param {import('./hooks/index.js').PreHandlerHook} hook
-   * @returns {this}
-   */
-  addPreHandler(hook) {
-    this.getService(RouterHookRegistry).addHook(
-      RouterHookType.PRE_HANDLER,
-      hook
-    );
-    return this;
-  }
-  /**
-   * Has pre-handler hook.
-   *
-   * @param {import('./hooks/index.js').PreHandlerHook} hook
-   * @returns {boolean}
-   */
-  hasPreHandler(hook) {
-    return this.getService(RouterHookRegistry).hasHook(
-      RouterHookType.PRE_HANDLER,
-      hook
-    );
-  }
-  /**
-   * Add post-handler hook.
+   * Add hook.
    *
-   * @param {import('./hooks/index.js').PostHandlerHook} hook
+   * @param {import('./hooks/index.js').RouterHookType} type
+   * @param {import('./hooks/index.js').RouterHook} hook
    * @returns {this}
    */
-  addPostHandler(hook) {
-    this.getService(RouterHookRegistry).addHook(
-      RouterHookType.POST_HANDLER,
-      hook
-    );
+  addHook(type, hook) {
+    this.getService(RouterHookRegistry).addHook(type, hook);
     return this;
   }
   /**
-   * Has post-handler hook.
+   * Has hook.
    *
-   * @param {import('./hooks/index.js').PostHandlerHook} hook
+   * @param {import('./hooks/index.js').RouterHookType} type
+   * @param {import('./hooks/index.js').RouterHook} hook
    * @returns {boolean}
    */
-  hasPostHandler(hook) {
-    return this.getService(RouterHookRegistry).hasHook(
-      RouterHookType.POST_HANDLER,
-      hook
-    );
+  hasHook(type, hook) {
+    return this.getService(RouterHookRegistry).hasHook(type, hook);
   }
 };
 __name(_TrieRouter, "TrieRouter");

package/eslint.config.js

@@ -27,7 +27,7 @@ export default [{
     ...eslintMochaPlugin.configs.recommended.rules,
     ...eslintChaiExpectPlugin.configs['recommended-flat'].rules,
     ...eslintJsdocPlugin.configs['flat/recommended-error'].rules,
-    "curly": "error",
+    'curly': 'error',
     'no-duplicate-imports': 'error',
     'import/export': 0,
     'jsdoc/reject-any-type': 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-trie-router",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "HTTP маршрутизатор для Node.js на основе префиксного дерева",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -47,8 +47,8 @@
     "statuses": "~2.0.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "~20.3.0",
-    "@commitlint/config-conventional": "~20.3.0",
+    "@commitlint/cli": "~20.4.1",
+    "@commitlint/config-conventional": "~20.4.1",
     "@eslint/js": "~9.39.2",
     "@types/chai": "~5.2.3",
     "@types/chai-as-promised": "~8.0.2",
@@ -61,12 +61,12 @@
     "eslint-config-prettier": "~10.1.8",
     "eslint-plugin-chai-expect": "~3.1.0",
     "eslint-plugin-import": "~2.32.0",
-    "eslint-plugin-jsdoc": "~61.5.0",
+    "eslint-plugin-jsdoc": "~62.5.2",
     "eslint-plugin-mocha": "~11.2.0",
-    "globals": "~17.0.0",
+    "globals": "~17.3.0",
     "husky": "~9.1.7",
     "mocha": "~11.7.5",
-    "prettier": "~3.7.4",
+    "prettier": "~3.8.1",
     "rimraf": "~6.1.2",
     "typescript": "~5.9.3"
   }

package/src/hooks/router-hook-invoker.spec.js

@@ -9,10 +9,10 @@ import {RouterHookRegistry, RouterHookType} from './router-hook-registry.js';
 describe('RouterHookInvoker', function () {
   describe('invokeAndContinueUntilValueReceived', function () {
     it('requires the parameter "route" to be a Route instance', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const res = createResponseMock();
       const throwable = v => () =>
-        s.invokeAndContinueUntilValueReceived(
+        S.invokeAndContinueUntilValueReceived(
           v,
           RouterHookType.PRE_HANDLER,
           res,
@@ -42,7 +42,7 @@ describe('RouterHookInvoker', function () {
     });
 
     it('requires the parameter "hookType" to be a non-empty String', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const route = new Route({
         method: HttpMethod.GET,
         path: ROOT_PATH,
@@ -50,7 +50,7 @@ describe('RouterHookInvoker', function () {
       });
       const res = createResponseMock();
       const throwable = v => () =>
-        s.invokeAndContinueUntilValueReceived(route, v, res);
+        S.invokeAndContinueUntilValueReceived(route, v, res);
       const error = v =>
         format(
           'Parameter "hookType" must be a non-empty String, but %s was given.',
@@ -69,7 +69,7 @@ describe('RouterHookInvoker', function () {
     });
 
     it('requires the parameter "hookType" to be a supported hook', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const route = new Route({
         method: HttpMethod.GET,
         path: ROOT_PATH,
@@ -77,22 +77,22 @@ describe('RouterHookInvoker', function () {
       });
       const res = createResponseMock();
       Object.values(RouterHookType).forEach(type =>
-        s.invokeAndContinueUntilValueReceived(route, type, res),
+        S.invokeAndContinueUntilValueReceived(route, type, res),
       );
       const throwable = () =>
-        s.invokeAndContinueUntilValueReceived(route, 'unknown', res);
+        S.invokeAndContinueUntilValueReceived(route, 'unknown', res);
       expect(throwable).to.throw('Hook type "unknown" is not supported.');
     });
 
     it('requires the parameter "response" to be an instance of ServerResponse', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const route = new Route({
         method: HttpMethod.GET,
         path: ROOT_PATH,
         handler: () => undefined,
       });
       const throwable = v => () =>
-        s.invokeAndContinueUntilValueReceived(
+        S.invokeAndContinueUntilValueReceived(
           route,
           RouterHookType.PRE_HANDLER,
           v,
@@ -117,15 +117,15 @@ describe('RouterHookInvoker', function () {
     });
 
     it('invokes global hooks in priority', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook2');
@@ -144,7 +144,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      s.invokeAndContinueUntilValueReceived(
+      S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         createResponseMock(),
@@ -158,23 +158,23 @@ describe('RouterHookInvoker', function () {
     });
 
     it('stops global hooks invocation if any of them returns a value', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
       const ret = 'OK';
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook2');
           return ret;
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook3');
@@ -193,7 +193,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const result = s.invokeAndContinueUntilValueReceived(
+      const result = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         createResponseMock(),
@@ -203,16 +203,16 @@ describe('RouterHookInvoker', function () {
     });
 
     it('stops route hooks invocation if any of them returns a value', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
       const ret = 'OK';
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook2');
@@ -235,7 +235,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const result = s.invokeAndContinueUntilValueReceived(
+      const result = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         createResponseMock(),
@@ -250,10 +250,10 @@ describe('RouterHookInvoker', function () {
     });
 
     it('returns the given response and should not call hooks if the response is already sent', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const res = createResponseMock();
       res._headersSent = true;
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           throw new Error('Should not be called');
@@ -269,7 +269,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const result = s.invokeAndContinueUntilValueReceived(
+      const result = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         res,
@@ -278,23 +278,23 @@ describe('RouterHookInvoker', function () {
     });
 
     it('stops global hooks invocation and returns the given response if it is already sent', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
       const res = createResponseMock();
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook2');
           res._headersSent = true;
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook3');
@@ -313,7 +313,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const result = s.invokeAndContinueUntilValueReceived(
+      const result = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         res,
@@ -323,16 +323,16 @@ describe('RouterHookInvoker', function () {
     });
 
     it('stops route hooks invocation and returns the given response if it is already sent', function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
       const res = createResponseMock();
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook2');
@@ -355,7 +355,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const result = s.invokeAndContinueUntilValueReceived(
+      const result = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         res,
@@ -370,21 +370,21 @@ describe('RouterHookInvoker', function () {
     });
 
     it('returns a Promise if any global hook is asynchronous', async function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         async () => {
           order.push('globalHook2');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook3');
@@ -403,7 +403,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const promise = s.invokeAndContinueUntilValueReceived(
+      const promise = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         createResponseMock(),
@@ -420,15 +420,15 @@ describe('RouterHookInvoker', function () {
     });
 
     it('returns a Promise if entire global hooks are asynchronous', async function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         async () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         async () => {
           order.push('globalHook2');
@@ -447,7 +447,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const promise = s.invokeAndContinueUntilValueReceived(
+      const promise = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         createResponseMock(),
@@ -463,15 +463,15 @@ describe('RouterHookInvoker', function () {
     });
 
     it('returns a Promise if any route hook is asynchronous', async function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook2');
@@ -493,7 +493,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const promise = s.invokeAndContinueUntilValueReceived(
+      const promise = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         createResponseMock(),
@@ -510,15 +510,15 @@ describe('RouterHookInvoker', function () {
     });
 
     it('returns a Promise if entire route hooks are asynchronous', async function () {
-      const s = new RouterHookInvoker();
+      const S = new RouterHookInvoker();
       const order = [];
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook1');
         },
       );
-      s.getService(RouterHookRegistry).addHook(
+      S.getService(RouterHookRegistry).addHook(
         RouterHookType.PRE_HANDLER,
         () => {
           order.push('globalHook2');
@@ -537,7 +537,7 @@ describe('RouterHookInvoker', function () {
         ],
         handler: () => undefined,
       });
-      const promise = s.invokeAndContinueUntilValueReceived(
+      const promise = S.invokeAndContinueUntilValueReceived(
         route,
         RouterHookType.PRE_HANDLER,
         createResponseMock(),

package/src/hooks/router-hook-registry.d.ts

@@ -1,4 +1,5 @@
 import {Callable} from '../types.js';
+import {RouteDefinition} from '../route/index.js';
 import {RequestContext} from '../request-context.js';
 import {DebuggableService} from '../debuggable-service.js';
 
@@ -8,6 +9,7 @@ import {DebuggableService} from '../debuggable-service.js';
 export declare const RouterHookType: {
   PRE_HANDLER: 'preHandler';
   POST_HANDLER: 'postHandler';
+  ON_DEFINE_ROUTE: 'onDefineRoute';
 };
 
 /**
@@ -36,29 +38,17 @@ export type PreHandlerHook = (ctx: RequestContext) => unknown;
  */
 export type PostHandlerHook = (ctx: RequestContext, data: unknown) => unknown;
 
+/**
+ * On defined route hook.
+ */
+export type OnDefineRouteHook = (
+  routeDef: RouteDefinition,
+) => RouteDefinition | undefined;
+
 /**
  * Router hook registry.
  */
 export declare class RouterHookRegistry extends DebuggableService {
-  /**
-   * Add hook.
-   *
-   * @param type
-   * @param hook
-   */
-  addHook(type: typeof RouterHookType.PRE_HANDLER, hook: PreHandlerHook): this;
-
-  /**
-   * Add hook.
-   *
-   * @param type
-   * @param hook
-   */
-  addHook(
-    type: typeof RouterHookType.POST_HANDLER,
-    hook: PostHandlerHook,
-  ): this;
-
   /**
    * Add hook.
    *
@@ -75,20 +65,6 @@ export declare class RouterHookRegistry extends DebuggableService {
    */
   hasHook(type: RouterHookType, hook: RouterHook): boolean;
 
-  /**
-   * Get hooks.
-   *
-   * @param type
-   */
-  getHooks(type: typeof RouterHookType.PRE_HANDLER): PreHandlerHook[];
-
-  /**
-   * Get hooks.
-   *
-   * @param type
-   */
-  getHooks(type: typeof RouterHookType.POST_HANDLER): PostHandlerHook[];
-
   /**
    * Get hooks.
    *

package/src/hooks/router-hook-registry.js

@@ -6,11 +6,13 @@ import {InvalidArgumentError} from '@e22m4u/js-format';
  * @type {{
  *   PRE_HANDLER: 'preHandler',
  *   POST_HANDLER: 'postHandler',
+ *   ON_DEFINE_ROUTE: 'onDefineRoute',
  * }}
  */
 export const RouterHookType = {
   PRE_HANDLER: 'preHandler',
   POST_HANDLER: 'postHandler',
+  ON_DEFINE_ROUTE: 'onDefineRoute',
 };
 
 /**