@e22m4u/js-trie-router 0.7.7 → 0.7.9

package/README.md

@@ -969,7 +969,7 @@ v1Branch.defineRoute({
 // GET /api/v1/status
 ```
 
-## Обработка ошибок
+### Обработка ошибок
 
 Маршрутизатор автоматически перехватывает любые ошибки, выброшенные из хуков
 или обработчика маршрута. По умолчанию, любая ошибка приводит к ответу сервера
@@ -1035,6 +1035,42 @@ router.defineRoute({
 }
 ```
 
+#### Перехват и логирование ошибок
+
+По умолчанию маршрутизатор не выводит информацию об ошибках в консоль,
+чтобы не нарушать формат логов приложения и не допускать утечки чувствительных
+данных (например, токенов из заголовков запроса).
+
+Если требуется реализовать собственное логирование, то можно переопределить
+встроенный сервис `RouterErrorSender`. Для этого потребуется унаследовать
+класс данного сервиса и подменить стандартную реализацию в контейнере
+маршрутизатора.
+
+```js
+import {TrieRouter, RouterErrorSender} from '@e22m4u/js-trie-router';
+
+// создание собственного сервиса обработки ошибок
+class CustomErrorSender extends RouterErrorSender {
+  send(request, response, error) {
+    // логирование ошибки удобным способом
+    console.error(`[Error on ${request.method} ${request.url}]:`, error);
+    // вызов родительского метода для стандартной
+    // отправки JSON-ответа с ошибкой клиенту
+    super.send(request, response, error);
+  }
+}
+
+const router = new TrieRouter();
+// подмена стандартного сервиса новым экземпляром,
+// передавая текущий контейнер в конструктор (обязательно)
+router.setService(RouterErrorSender, new CustomErrorSender(router.container));
+// ... регистрация маршрутов и запуск сервера
+```
+
+*При необходимости можно переопределить метод `send404(request, response)`,
+чтобы отслеживать запросы к несуществующим маршрутам или изменять формат
+ответа.*
+
 ## Отладка
 
 Установка переменной `DEBUG` включает вывод логов.

package/dist/cjs/index.cjs

@@ -98,7 +98,7 @@ var DebuggableService = class extends import_js_service.DebuggableService {
   constructor(container = void 0) {
     super(container, {
       namespace: MODULE_DEBUG_NAMESPACE,
-      noEnvironmentNamespace: true
+      noGlobalNamespace: true
     });
   }
 };
@@ -1670,7 +1670,7 @@ var Route = class extends import_js_debug.Debuggable {
   constructor(routeDef) {
     super({
       namespace: MODULE_DEBUG_NAMESPACE,
-      noEnvironmentNamespace: true,
+      noGlobalNamespace: true,
       noInstantiationMessage: true
     });
     validateRouteDefinition(routeDef);
@@ -1688,7 +1688,7 @@ var Route = class extends import_js_debug.Debuggable {
         this._hookRegistry.addHook(RouterHookType.POST_HANDLER, hook);
       });
     }
-    this.ctorDebug("Created a route %s %v.", this.method, this.path);
+    this.ctorDebug("Route %s %v created.", this.method, this.path);
   }
   /**
    * Handle request.
@@ -1758,7 +1758,7 @@ var RouteRegistry = class extends DebuggableService {
     const route = new Route(routeDef);
     const triePath = `${route.method}/${route.path}`;
     this._trie.add(triePath, route);
-    debug("Registered a route %s %v.", route.method.toUpperCase(), route.path);
+    debug("Route %s %v registered.", route.method.toUpperCase(), route.path);
     return route;
   }
   /**
@@ -2460,7 +2460,6 @@ var RouterDataSender = class extends DebuggableService {
 };
 
 // src/senders/router-error-sender.js
-var import_util = require("util");
 var import_statuses = __toESM(require("statuses"), 1);
 var EXPOSED_ERROR_PROPERTIES = ["code", "details"];
 var RouterErrorSender = class extends DebuggableService {
@@ -2497,24 +2496,6 @@ var RouterErrorSender = class extends DebuggableService {
         body.error[name] = safeError[name];
       }
     });
-    const requestData = {
-      url: request.url,
-      method: request.method,
-      headers: request.headers
-    };
-    const inspectOptions = {
-      showHidden: false,
-      depth: null,
-      colors: true,
-      compact: false
-    };
-    console.warn((0, import_util.inspect)(requestData, inspectOptions));
-    console.warn((0, import_util.inspect)(body, inspectOptions));
-    if (error.stack) {
-      console.log(error.stack);
-    } else {
-      console.error(error);
-    }
     response.statusCode = statusCode;
     response.setHeader("Content-Type", "application/json; charset=utf-8");
     response.end(JSON.stringify(body, null, 2), "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-trie-router",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "HTTP маршрутизатор для Node.js на основе префиксного дерева",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -38,17 +38,17 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@e22m4u/js-debug": "~0.4.1",
+    "@e22m4u/js-debug": "~0.5.0",
     "@e22m4u/js-format": "~0.4.0",
-    "@e22m4u/js-path-trie": "~0.2.0",
-    "@e22m4u/js-service": "~0.6.1",
+    "@e22m4u/js-path-trie": "~0.2.1",
+    "@e22m4u/js-service": "~0.6.2",
     "debug": "~4.4.3",
     "http-errors": "~2.0.1",
     "statuses": "~2.0.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "~20.4.3",
-    "@commitlint/config-conventional": "~20.4.3",
+    "@commitlint/cli": "~20.4.4",
+    "@commitlint/config-conventional": "~20.4.4",
     "@eslint/js": "~9.39.2",
     "@types/chai": "~5.2.3",
     "@types/chai-as-promised": "~8.0.2",
@@ -56,12 +56,12 @@
     "c8": "~11.0.0",
     "chai": "~6.2.2",
     "chai-as-promised": "~8.0.2",
-    "esbuild": "~0.27.3",
+    "esbuild": "~0.27.4",
     "eslint": "~9.39.2",
     "eslint-config-prettier": "~10.1.8",
-    "eslint-plugin-chai-expect": "~3.1.0",
+    "eslint-plugin-chai-expect": "~4.0.0",
     "eslint-plugin-import": "~2.32.0",
-    "eslint-plugin-jsdoc": "~62.7.1",
+    "eslint-plugin-jsdoc": "~62.8.0",
     "eslint-plugin-mocha": "~11.2.0",
     "globals": "~17.4.0",
     "husky": "~9.1.7",

package/src/debuggable-service.js

@@ -21,7 +21,7 @@ export class DebuggableService extends BaseDebuggableService {
   constructor(container = undefined) {
     super(container, {
       namespace: MODULE_DEBUG_NAMESPACE,
-      noEnvironmentNamespace: true,
+      noGlobalNamespace: true,
     });
   }
 }

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

@@ -1,7 +1,8 @@
-import {Callable} from '../types.js';
 import {RouteDefinition} from '../route/index.js';
 import {ServiceContainer} from '@e22m4u/js-service';
 import {RequestContext} from '../request-context.js';
+import {Callable, ValueOrPromise} from '../types.js';
+import {IncomingMessage, ServerResponse} from 'http';
 import {DebuggableService} from '../debuggable-service.js';
 
 /**
@@ -30,6 +31,23 @@ export const ROUTER_HOOK_TYPES: RouterHookType[];
  */
 export type RouterHook = Callable;
 
+/**
+ * On defined route hook.
+ */
+export type OnDefineRouteHook = (
+  routeDef: RouteDefinition,
+  container: ServiceContainer,
+) => RouteDefinition | undefined;
+
+/**
+ * On request hook.
+ */
+export type OnRequestHook = (
+  request: IncomingMessage,
+  response: ServerResponse,
+  container: ServiceContainer,
+) => ValueOrPromise<boolean | undefined>;
+
 /**
  * Pre handler hook.
  */
@@ -40,18 +58,48 @@ export type PreHandlerHook = (ctx: RequestContext) => unknown;
  */
 export type PostHandlerHook = (ctx: RequestContext, data: unknown) => unknown;
 
-/**
- * On defined route hook.
- */
-export type OnDefineRouteHook = (
-  routeDef: RouteDefinition,
-  container: ServiceContainer,
-) => RouteDefinition | undefined;
-
 /**
  * Router hook registry.
  */
 export declare class RouterHookRegistry extends DebuggableService {
+  /**
+   * Add hook (overload for "onDefineRoute" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(
+    type: typeof RouterHookType.ON_DEFINE_ROUTE,
+    hook: OnDefineRouteHook,
+  ): this;
+
+  /**
+   * Add hook (overload for "onRequest" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(type: typeof RouterHookType.ON_REQUEST, hook: OnRequestHook): this;
+
+  /**
+   * Add hook (overload for "preHandler" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(type: typeof RouterHookType.PRE_HANDLER, hook: PreHandlerHook): this;
+
+  /**
+   * Add hook (overload for "postHandler" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(
+    type: typeof RouterHookType.POST_HANDLER,
+    hook: PostHandlerHook,
+  ): this;
+
   /**
    * Add hook.
    *
@@ -68,6 +116,34 @@ export declare class RouterHookRegistry extends DebuggableService {
    */
   hasHook(type: RouterHookType, hook: RouterHook): boolean;
 
+  /**
+   * Get hooks (overload for "onDefineRoute").
+   *
+   * @param type
+   */
+  getHooks(type: typeof RouterHookType.ON_DEFINE_ROUTE): OnDefineRouteHook[];
+
+  /**
+   * Get hooks (overload for "onRequest").
+   *
+   * @param type
+   */
+  getHooks(type: typeof RouterHookType.ON_REQUEST): OnRequestHook[];
+
+  /**
+   * Get hooks (overload for "preHandler").
+   *
+   * @param type
+   */
+  getHooks(type: typeof RouterHookType.PRE_HANDLER): PreHandlerHook[];
+
+  /**
+   * Get hooks (overload for "postHandler").
+   *
+   * @param type
+   */
+  getHooks(type: typeof RouterHookType.POST_HANDLER): PostHandlerHook[];
+
   /**
    * Get hooks.
    *

package/src/route/route-registry.js

@@ -78,7 +78,7 @@ export class RouteRegistry extends DebuggableService {
     const route = new Route(routeDef);
     const triePath = `${route.method}/${route.path}`;
     this._trie.add(triePath, route);
-    debug('Registered a route %s %v.', route.method.toUpperCase(), route.path);
+    debug('Route %s %v registered.', route.method.toUpperCase(), route.path);
     return route;
   }
 

package/src/route/route.js

@@ -127,7 +127,7 @@ export class Route extends Debuggable {
   constructor(routeDef) {
     super({
       namespace: MODULE_DEBUG_NAMESPACE,
-      noEnvironmentNamespace: true,
+      noGlobalNamespace: true,
       noInstantiationMessage: true,
     });
     validateRouteDefinition(routeDef);
@@ -151,7 +151,7 @@ export class Route extends Debuggable {
         this._hookRegistry.addHook(RouterHookType.POST_HANDLER, hook);
       });
     }
-    this.ctorDebug('Created a route %s %v.', this.method, this.path);
+    this.ctorDebug('Route %s %v created.', this.method, this.path);
   }
 
   /**

package/src/senders/router-error-sender.js

@@ -1,4 +1,3 @@
-import {inspect} from 'util';
 import getStatusMessage from 'statuses';
 import {getRequestPathname} from '../utils/index.js';
 import {DebuggableService} from '../debuggable-service.js';
@@ -44,24 +43,6 @@ export class RouterErrorSender extends DebuggableService {
         body.error[name] = safeError[name];
       }
     });
-    const requestData = {
-      url: request.url,
-      method: request.method,
-      headers: request.headers,
-    };
-    const inspectOptions = {
-      showHidden: false,
-      depth: null,
-      colors: true,
-      compact: false,
-    };
-    console.warn(inspect(requestData, inspectOptions));
-    console.warn(inspect(body, inspectOptions));
-    if (error.stack) {
-      console.log(error.stack);
-    } else {
-      console.error(error);
-    }
     response.statusCode = statusCode;
     response.setHeader('Content-Type', 'application/json; charset=utf-8');
     response.end(JSON.stringify(body, null, 2), 'utf-8');

package/src/trie-router.d.ts

@@ -3,10 +3,18 @@ import {RouteDefinition} from './route/index.js';
 import {ServiceContainer} from '@e22m4u/js-service';
 import {IncomingMessage, ServerResponse} from 'http';
 import {DebuggableService} from './debuggable-service.js';
-import {RouterHook, RouterHookType} from './hooks/index.js';
 import {TrieRouterOptionsInput} from './trie-router-options.js';
 import {RouterBranch, RouterBranchDefinition} from './branch/index.js';
 
+import {
+  RouterHook,
+  OnRequestHook,
+  RouterHookType,
+  PreHandlerHook,
+  PostHandlerHook,
+  OnDefineRouteHook,
+} from './hooks/index.js';
+
 /**
  * Trie router.
  */
@@ -105,6 +113,44 @@ export declare class TrieRouter extends DebuggableService {
     response: ServerResponse,
   ): Promise<void>;
 
+  /**
+   * Add hook (overload for "onDefineRoute" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(
+    type: typeof RouterHookType.ON_DEFINE_ROUTE,
+    hook: OnDefineRouteHook,
+  ): this;
+
+  /**
+   * Add hook (overload for "onRequest" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(type: typeof RouterHookType.ON_REQUEST, hook: OnRequestHook): this;
+
+  /**
+   * Add hook (overload for "preHandler" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(type: typeof RouterHookType.PRE_HANDLER, hook: PreHandlerHook): this;
+
+  /**
+   * Add hook (overload for "postHandler" hook).
+   *
+   * @param type
+   * @param hook
+   */
+  addHook(
+    type: typeof RouterHookType.POST_HANDLER,
+    hook: PostHandlerHook,
+  ): this;
+
   /**
    * Add hook.
    *

package/src/utils/create-request-mock.spec.js

@@ -7,7 +7,7 @@ import {createRequestMock} from './create-request-mock.js';
 import {CHARACTER_ENCODING_LIST} from './fetch-request-body.js';
 
 describe('createRequestMock', function () {
-  it('should require the option "options" to be an Object', function () {
+  it('should require the parameter "options" to be an Object', function () {
     const throwable = v => () => createRequestMock(v);
     const error = v =>
       format('Parameter "options" must be an Object, but %s was given.', v);
@@ -496,24 +496,24 @@ describe('createRequestMock', function () {
     expect(data).to.be.eql(body);
   });
 
-  it('should pass a value form the "url" option to the request url', function () {
+  it('should pass a value from the "url" option to the request url', function () {
     const req = createRequestMock({url: '/test'});
     expect(req.url).to.be.eq('/test');
   });
 
-  it('should pass a value form the "path" option to the request url', function () {
+  it('should pass a value from the "path" option to the request url', function () {
     const req = createRequestMock({path: '/test'});
     expect(req.url).to.be.eq('/test');
   });
 
-  it('should pass a string form the "query" option to the request url', async function () {
+  it('should pass a string from the "query" option to the request url', async function () {
     const req1 = createRequestMock({query: 'p1=foo&p2=bar'});
     const req2 = createRequestMock({query: '?p1=foo&p2=bar'});
     expect(req1.url).to.be.eq('/?p1=foo&p2=bar');
     expect(req2.url).to.be.eq('/?p1=foo&p2=bar');
   });
 
-  it('should pass an object form the "query" option to the request url', async function () {
+  it('should pass an object from the "query" option to the request url', async function () {
     const req = createRequestMock({query: {foo: 'bar', baz: 'qux'}});
     expect(req.url).to.be.eq('/?foo=bar&baz=qux');
   });

package/src/utils/create-response-mock.spec.js

@@ -139,7 +139,7 @@ describe('createResponseMock', function () {
   });
 
   describe('Stream', function () {
-    it('should set the property "headerSent" to true when the stream ends', function () {
+    it('should set the property "headersSent" to true when the stream ends', function () {
       const res = createResponseMock();
       expect(res.headersSent).to.be.false;
       res.end('test');

package/src/utils/fetch-request-body.d.ts

@@ -23,4 +23,4 @@ export const CHARACTER_ENCODING_LIST: (
 export declare function fetchRequestBody(
   request: IncomingMessage,
   bodyBytesLimit?: number,
-): Promise<string>;
+): Promise<string | undefined>;

package/src/utils/fetch-request-body.spec.js

@@ -123,7 +123,7 @@ describe('fetchRequestBody', function () {
       );
     });
 
-    it('should not throw an error if the body length does match with the header', async function () {
+    it('should not throw an error if the body length matches the header', async function () {
       const body = 'Lorem Ipsum is simply dummy text.';
       const contentLength = String(Buffer.from(body).byteLength);
       const req = createRequestMock({