@e22m4u/js-trie-router 0.5.6 → 0.5.8

package/README.md

@@ -26,6 +26,7 @@ HTTP маршрутизатор для Node.js на основе
   - [Метаданные маршрута](#метаданные-маршрута)
   - [Состояние запроса](#состояние-запроса)
   - [Ветвление маршрутов](#ветвление-маршрутов)
+  - [Обработка ошибок](#обработка-ошибок)
 - [Отладка](#отладка)
 - [Тестирование](#тестирование)
 - [Лицензия](#лицензия)
@@ -410,6 +411,72 @@ v1Branch.defineRoute({
 // GET /api/v1/status
 ```
 
+## Обработка ошибок
+
+Маршрутизатор автоматически перехватывает любые ошибки, выброшенные из хуков
+или обработчика маршрута. По умолчанию, любая ошибка приводит к ответу сервера
+со статусом *500 Internal Server Error*.
+
+Для более гибкого управления HTTP-статусами рекомендуется использовать
+библиотеку [http-errors](https://www.npmjs.com/package/http-errors).
+Стандартный обработчик ошибок спроектирован для работы с данной библиотекой
+и автоматически извлекает `statusCode`, `message` и другие свойства ошибки.
+
+```js
+import HttpErrors from 'http-errors';
+
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/users/:id',
+  handler(ctx) {
+    const {id} = ctx.params;
+    const user = findUserById(id); // логика поиска пользователя
+    if (!user) {
+      // выброс ошибки 404 Not Found
+      // маршрутизатор перехватит ее и отправит JSON-ответ
+      throw new HttpErrors.NotFound('Пользователь не найден');
+    }
+    if (!hasAccess(ctx.state.currentUser, user)) {
+      // ошибка 403 Forbidden с дополнительными данными
+      // свойства "code" и "details" будут добавлены к ответу
+      const error = new HttpErrors.Forbidden('Доступ запрещен');
+      error.code = 'ACCESS_DENIED';
+      error.details = {reason: 'Недостаточно прав'};
+      throw error;
+    }
+    return user;
+  },
+});
+```
+
+Структура ответа будет зависеть от данных, содержащихся в объекте ошибки.
+Например, первая ошибка из примера выше `HttpErrors.NotFound` приведет
+к ответу со статусом `404` и телом, содержащим указанное сообщение.
+
+```json
+{
+  "error": {
+    "message": "Пользователь не найден"
+  }
+}
+```
+
+Если объект ошибки содержит дополнительные поля (например, `details`
+или `code`), они автоматически включаются в ответ. Что позволяет
+передавать клиенту более детальную информацию.
+
+```json
+{
+  "error": {
+    "code": "ACCESS_DENIED",
+    "message": "Доступ запрещен",
+    "details": {
+      "reason": "Недостаточно прав"
+    }
+  }
+}
+```
+
 ## Отладка
 
 Установка переменной `DEBUG` включает вывод логов.

package/dist/cjs/index.cjs

@@ -70,6 +70,7 @@ __export(index_exports, {
   parseCookieString: () => parseCookieString,
   parseJsonBody: () => parseJsonBody,
   toCamelCase: () => toCamelCase,
+  toPascalCase: () => toPascalCase,
   validateRouteDefinition: () => validateRouteDefinition
 });
 module.exports = __toCommonJS(index_exports);
@@ -200,6 +201,15 @@ function toCamelCase(input) {
 }
 __name(toCamelCase, "toCamelCase");
 
+// src/utils/to-pascal-case.js
+function toPascalCase(input) {
+  if (!input) {
+    return "";
+  }
+  return input.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([0-9])([a-zA-Z])/g, "$1 $2").replace(/[-_]+|[^\p{L}\p{N}]/gu, " ").toLowerCase().replace(new RegExp("(?:^|\\s)(\\p{L})", "gu"), (_, letter) => letter.toUpperCase()).replace(/\s+/g, "");
+}
+__name(toPascalCase, "toPascalCase");
+
 // src/utils/normalize-path.js
 function normalizePath(value, noStartingSlash = false) {
   if (typeof value !== "string") {
@@ -885,7 +895,11 @@ var HookRegistry = _HookRegistry;
 // src/hooks/hook-invoker.js
 var _HookInvoker = class _HookInvoker extends DebuggableService {
   /**
-   * Invoke and continue until value received.
+   * Последовательно вызывает глобальные хуки и хуки маршрута указанного
+   * типа, пока один из них не вернет отличное от undefined и null значение
+   * или не отправит HTTP-ответ. Метод выполняет хуки в синхронном режиме
+   * для улучшения производительности. Если один из хуков возвращает Promise,
+   * выполнение оставшейся части цепочки переключается в асинхронный режим.
    *
    * @param {Route} route
    * @param {string} hookType
@@ -934,31 +948,53 @@ var _HookInvoker = class _HookInvoker extends DebuggableService {
       }
       if (result != null) {
         if (isPromise(result)) {
-          return (async () => {
-            let asyncResult = await result;
-            if (isResponseSent(response)) {
-              return response;
-            }
-            if (asyncResult != null) {
-              return asyncResult;
-            }
-            for (let j = i + 1; j < hooks.length; j++) {
-              asyncResult = await hooks[j](...args);
-              if (isResponseSent(response)) {
-                return response;
-              }
-              if (asyncResult != null) {
-                return asyncResult;
-              }
-            }
-            return;
-          })();
+          return this._continueHooksInvocationAsync(
+            hooks,
+            i + 1,
+            result,
+            response,
+            args
+          );
         }
         return result;
       }
     }
     return;
   }
+  /**
+   * Асинхронно продолжает выполнение цепочки хуков, начиная с указанного
+   * индекса. Данный метод вызывается, когда хук в основном синхронном цикле
+   * возвращает Promise. Метод ожидает разрешения начального Promise, а затем
+   * последовательно выполняет оставшиеся хуки в асинхронном режиме, следуя
+   * той же логике прерывания (при получении значения или отправке ответа),
+   * что и основной метод.
+   *
+   * @param {Function[]} hooks
+   * @param {number} startIndex
+   * @param {Promise} initialPromise
+   * @param {import('http').ServerResponse} response
+   * @param {*} args
+   * @returns {Promise<*>}
+   */
+  async _continueHooksInvocationAsync(hooks, startIndex, initialPromise, response, args) {
+    let result = await initialPromise;
+    if (isResponseSent(response)) {
+      return response;
+    }
+    if (result != null) {
+      return result;
+    }
+    for (let i = startIndex; i < hooks.length; i++) {
+      result = await hooks[i](...args);
+      if (isResponseSent(response)) {
+        return response;
+      }
+      if (result != null) {
+        return result;
+      }
+    }
+    return;
+  }
 };
 __name(_HookInvoker, "HookInvoker");
 var HookInvoker = _HookInvoker;
@@ -1043,6 +1079,7 @@ var HttpMethod = {
   PATCH: "PATCH",
   DELETE: "DELETE"
 };
+var DEFAULT_META = Object.freeze({});
 var _Route = class _Route extends import_js_debug.Debuggable {
   /**
    * Definition.
@@ -1094,7 +1131,7 @@ var _Route = class _Route extends import_js_debug.Debuggable {
    * @returns {object}
    */
   get meta() {
-    return this._definition.meta;
+    return this._definition.meta || DEFAULT_META;
   }
   /**
    * Getter of the handler.
@@ -1118,7 +1155,6 @@ var _Route = class _Route extends import_js_debug.Debuggable {
     validateRouteDefinition(routeDef);
     this._definition = cloneDeep(routeDef);
     this._definition.method = this._definition.method.toUpperCase();
-    this._definition.meta = this._definition.meta || {};
     if (routeDef.preHandler !== void 0) {
       const preHandlerHooks = [routeDef.preHandler].flat().filter(Boolean);
       preHandlerHooks.forEach((hook) => {
@@ -1131,7 +1167,7 @@ var _Route = class _Route extends import_js_debug.Debuggable {
         this._hookRegistry.addHook(RouterHookType.POST_HANDLER, hook);
       });
     }
-    this.ctorDebug("A new route %s %v was created.", this.method, this.path);
+    this.ctorDebug("Route %s %v created.", this.method, this.path);
   }
   /**
    * Handle request.
@@ -1142,11 +1178,7 @@ var _Route = class _Route extends import_js_debug.Debuggable {
   handle(context) {
     const debug = this.getDebuggerFor(this.handle);
     const requestPath = getRequestPathname(context.request);
-    debug(
-      "Invoking the Route handler for the request %s %v.",
-      this.method,
-      requestPath
-    );
+    debug("Invoking route handler for %s %v.", this.method, requestPath);
     return this.handler(context);
   }
 };
@@ -1280,7 +1312,7 @@ var _BodyParser = class _BodyParser extends DebuggableService {
     const debug = this.getDebuggerFor(this.parse);
     if (!METHODS_WITH_BODY.includes(request.method.toUpperCase())) {
       debug(
-        "Body parsing was skipped for the %s request.",
+        "Body parsing skipped for %s method.",
         request.method.toUpperCase()
       );
       return;
@@ -1290,9 +1322,7 @@ var _BodyParser = class _BodyParser extends DebuggableService {
       "$1"
     );
     if (!contentType) {
-      debug(
-        "Body parsing was skipped because the request had no content type."
-      );
+      debug("Body parsing skipped because no content type provided.");
       return;
     }
     const { mediaType } = parseContentType(contentType);
@@ -1305,7 +1335,7 @@ var _BodyParser = class _BodyParser extends DebuggableService {
     const parser = this._parsers[mediaType];
     if (!parser) {
       if (UNPARSABLE_MEDIA_TYPES.includes(mediaType)) {
-        debug("Body parsing was skipped for %v.", mediaType);
+        debug("Body parsing skipped for media type %v.", mediaType);
         return;
       }
       throw createError(
@@ -1315,10 +1345,14 @@ var _BodyParser = class _BodyParser extends DebuggableService {
       );
     }
     const bodyBytesLimit = this.getService(RouterOptions).requestBodyBytesLimit;
+    debug("Fetching request body.");
+    debug("Body limit %v bytes.", bodyBytesLimit);
     return fetchRequestBody(request, bodyBytesLimit).then((rawBody) => {
       if (rawBody != null) {
+        debug("Read %v bytes.", Buffer.byteLength(rawBody, "utf8"));
         return parser(rawBody);
       }
+      debug("No request body content.");
       return rawBody;
     });
   }
@@ -1353,11 +1387,11 @@ var _QueryParser = class _QueryParser extends DebuggableService {
     const queryKeys = Object.keys(query);
     if (queryKeys.length) {
       queryKeys.forEach((key) => {
-        debug("The query parameter %v had the value %v.", key, query[key]);
+        debug("Found query parameter %v with value %v.", key, query[key]);
       });
     } else {
       debug(
-        "The request %s %v had no query parameters.",
+        "Request %s %v had no query parameters.",
         request.method,
         getRequestPathname(request)
       );
@@ -1383,11 +1417,11 @@ var _CookiesParser = class _CookiesParser extends DebuggableService {
     const cookiesKeys = Object.keys(cookies);
     if (cookiesKeys.length) {
       cookiesKeys.forEach((key) => {
-        debug("The cookie %v had the value %v.", key, cookies[key]);
+        debug("Found cookie %v with value %v.", key, cookies[key]);
       });
     } else {
       debug(
-        "The request %s %v had no cookies.",
+        "Request %s %v had no cookies.",
         request.method,
         getRequestPathname(request)
       );
@@ -1473,11 +1507,7 @@ var _RouteRegistry = class _RouteRegistry extends DebuggableService {
     const route = new Route(routeDef);
     const triePath = `${route.method}/${route.path}`;
     this._trie.add(triePath, route);
-    debug(
-      "The route %s %v was registered.",
-      route.method.toUpperCase(),
-      route.path
-    );
+    debug("Route %s %v registered.", route.method.toUpperCase(), route.path);
     return route;
   }
   /**
@@ -1490,7 +1520,7 @@ var _RouteRegistry = class _RouteRegistry extends DebuggableService {
     const debug = this.getDebuggerFor(this.matchRouteByRequest);
     const requestPath = getRequestPathname(request);
     debug(
-      "Matching routes with the request %s %v.",
+      "Matching routes for %s %v.",
       request.method.toUpperCase(),
       requestPath
     );
@@ -1499,16 +1529,12 @@ var _RouteRegistry = class _RouteRegistry extends DebuggableService {
     const resolved = this._trie.match(triePath);
     if (resolved) {
       const route = resolved.value;
-      debug(
-        "The route %s %v was matched.",
-        route.method.toUpperCase(),
-        route.path
-      );
+      debug("Matched route %s %v.", route.method.toUpperCase(), route.path);
       const paramNames = Object.keys(resolved.params);
       if (paramNames.length) {
         paramNames.forEach((name) => {
           debug(
-            "The path parameter %v had the value %v.",
+            "Found path parameter %v with value %v.",
             name,
             resolved.params[name]
           );
@@ -1519,7 +1545,7 @@ var _RouteRegistry = class _RouteRegistry extends DebuggableService {
       return { route, params: resolved.params };
     }
     debug(
-      "No matched route for the request %s %v.",
+      "No matched route for %s %v.",
       request.method.toUpperCase(),
       requestPath
     );
@@ -1726,21 +1752,19 @@ var _DataSender = class _DataSender extends DebuggableService {
   send(response, data) {
     const debug = this.getDebuggerFor(this.send);
     if (data === response || response.headersSent) {
-      debug(
-        "Response sending was skipped because its headers where sent already."
-      );
+      debug("Response skipped because headers already sent.");
       return;
     }
     if (data == null) {
       response.statusCode = 204;
       response.end();
-      debug("The empty response was sent.");
+      debug("Empty response sent.");
       return;
     }
     if (isReadableStream(data)) {
       response.setHeader("Content-Type", "application/octet-stream");
       data.pipe(response);
-      debug("The stream response was sent.");
+      debug("Stream response sent.");
       return;
     }
     let debugMsg;
@@ -1750,16 +1774,16 @@ var _DataSender = class _DataSender extends DebuggableService {
       case "number":
         if (Buffer.isBuffer(data)) {
           response.setHeader("content-type", "application/octet-stream");
-          debugMsg = "The Buffer was sent as binary data.";
+          debugMsg = "Buffer sent as binary data.";
         } else {
           response.setHeader("content-type", "application/json");
-          debugMsg = (0, import_js_format18.format)("The %v was sent as JSON.", typeof data);
+          debugMsg = (0, import_js_format18.format)("%v sent as JSON.", toPascalCase(typeof data));
           data = JSON.stringify(data);
         }
         break;
       default:
         response.setHeader("content-type", "text/plain");
-        debugMsg = "The response data was sent as plain text.";
+        debugMsg = "Response data sent as plain text.";
         data = String(data);
         break;
     }
@@ -1827,7 +1851,7 @@ var _ErrorSender = class _ErrorSender extends DebuggableService {
     response.setHeader("content-type", "application/json; charset=utf-8");
     response.end(JSON.stringify(body, null, 2), "utf-8");
     debug(
-      "The %s error was sent for the request %s %v.",
+      "%s error sent for %s %v request.",
       statusCode,
       request.method,
       getRequestPathname(request)
@@ -1846,7 +1870,7 @@ var _ErrorSender = class _ErrorSender extends DebuggableService {
     response.setHeader("content-type", "text/plain; charset=utf-8");
     response.end("404 Not Found", "utf-8");
     debug(
-      "The 404 error was sent for the request %s %v.",
+      "404 error sent for %s %v.",
       request.method,
       getRequestPathname(request)
     );
@@ -2045,7 +2069,7 @@ var _RouterBranch = class _RouterBranch extends DebuggableService {
       this._definition = cloneDeep(branchDef);
     }
     this.ctorDebug("Branch %v created.", normalizePath(branchDef.path, true));
-    this.ctorDebug("Branch path was %v.", this._definition.path);
+    this.ctorDebug("Branch path set to %v.", this._definition.path);
   }
   /**
    * Define route.
@@ -2162,14 +2186,10 @@ var _TrieRouter = class _TrieRouter extends DebuggableService {
   async _handleRequest(request, response) {
     const debug = this.getDebuggerFor(this._handleRequest);
     const requestPath = getRequestPathname(request);
-    debug(
-      "Preparing to handle an incoming request %s %v.",
-      request.method,
-      requestPath
-    );
+    debug("Handling incoming request %s %v.", request.method, requestPath);
     const resolved = this.getService(RouteRegistry).matchRouteByRequest(request);
     if (!resolved) {
-      debug("No route for the request %s %v.", request.method, requestPath);
+      debug("No route found for %s %v.", request.method, requestPath);
       this.getService(ErrorSender).send404(request, response);
     } else {
       const { route, params } = resolved;
@@ -2322,5 +2342,6 @@ var TrieRouter = _TrieRouter;
   parseCookieString,
   parseJsonBody,
   toCamelCase,
+  toPascalCase,
   validateRouteDefinition
 });

package/examples/cookies-parsing-example.js

@@ -1,6 +1,5 @@
 import http from 'http';
-import {TrieRouter} from '../src/index.js';
-import {HttpMethod} from '../src/route.js';
+import {TrieRouter, HttpMethod} from '../src/index.js';
 
 const router = new TrieRouter();
 

package/examples/params-parsing-example.js

@@ -1,6 +1,5 @@
 import http from 'http';
-import {TrieRouter} from '../src/index.js';
-import {HttpMethod} from '../src/route.js';
+import {TrieRouter, HttpMethod} from '../src/index.js';
 
 const router = new TrieRouter();
 

package/examples/query-parsing-example.js

@@ -1,6 +1,5 @@
 import http from 'http';
-import {TrieRouter} from '../src/index.js';
-import {HttpMethod} from '../src/route.js';
+import {TrieRouter, HttpMethod} from '../src/index.js';
 
 const router = new TrieRouter();
 

package/examples/router-branch-example.js

@@ -0,0 +1,36 @@
+import http from 'http';
+import {TrieRouter, HttpMethod} from '../src/index.js';
+
+const router = new TrieRouter();
+
+// создание ветки маршрутизатора с адресом "api",
+// указанный путь будет использован как префикс
+// для маршрутов данной ветки
+const apiBranch = router.createBranch({path: 'api'});
+
+// определение маршрута в рамках ветки "api",
+// маршрут будет доступен по адресу "/api/status"
+apiBranch.defineRoute({
+  method: HttpMethod.GET,
+  path: '/status',
+  handler: () => 'API is working',
+});
+
+// создание экземпляра HTTP сервера
+// и подключение обработчика запросов
+const server = new http.Server();
+server.on('request', router.requestListener);
+
+// прослушивание входящих запросов
+// на указанный адрес и порт
+const port = 3000;
+const host = '0.0.0.0';
+server.listen(port, host, function () {
+  const cyan = '\x1b[36m%s\x1b[0m';
+  console.log(cyan, 'Server listening on port:', port);
+  console.log(
+    cyan,
+    'Open in browser:',
+    `http://${host}:${port}/api/status`,
+  );
+});

package/examples/uptime-example.js

@@ -1,6 +1,5 @@
 import http from 'http';
-import {TrieRouter} from '../src/index.js';
-import {HttpMethod} from '../src/route.js';
+import {TrieRouter, HttpMethod} from '../src/index.js';
 
 const router = new TrieRouter();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-trie-router",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "HTTP маршрутизатор для Node.js на основе префиксного дерева",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",

package/src/branch/router-branch.js

@@ -121,7 +121,7 @@ export class RouterBranch extends DebuggableService {
       this._definition = cloneDeep(branchDef);
     }
     this.ctorDebug('Branch %v created.', normalizePath(branchDef.path, true));
-    this.ctorDebug('Branch path was %v.', this._definition.path);
+    this.ctorDebug('Branch path set to %v.', this._definition.path);
   }
 
   /**

package/src/hooks/hook-invoker.js

@@ -9,7 +9,11 @@ import {HookRegistry, RouterHookType} from './hook-registry.js';
  */
 export class HookInvoker extends DebuggableService {
   /**
-   * Invoke and continue until value received.
+   * Последовательно вызывает глобальные хуки и хуки маршрута указанного
+   * типа, пока один из них не вернет отличное от undefined и null значение
+   * или не отправит HTTP-ответ. Метод выполняет хуки в синхронном режиме
+   * для улучшения производительности. Если один из хуков возвращает Promise,
+   * выполнение оставшейся части цепочки переключается в асинхронный режим.
    *
    * @param {Route} route
    * @param {string} hookType
@@ -87,41 +91,13 @@ export class HookInvoker extends DebuggableService {
         // выполнение переключается в асинхронный режим, начиная
         // с индекса следующего хука
         if (isPromise(result)) {
-          return (async () => {
-            // ожидание Promise, который был получен
-            // на предыдущем шаге (в синхронном режиме)
-            let asyncResult = await result;
-            // если ответ уже отправлен,
-            // то возвращается ServerResponse
-            if (isResponseSent(response)) {
-              return response;
-            }
-            // если Promise разрешился значением отличным
-            // от undefined и null, то данное значение
-            // возвращается в качестве результата
-            if (asyncResult != null) {
-              return asyncResult;
-            }
-            // продолжение вызова хуков начиная
-            // со следующего индекса (асинхронно)
-            for (let j = i + 1; j < hooks.length; j++) {
-              // с этого момента все синхронные
-              // хуки выполняются как асинхронные
-              asyncResult = await hooks[j](...args);
-              // если ответ уже отправлен,
-              // то возвращается ServerResponse
-              if (isResponseSent(response)) {
-                return response;
-              }
-              // если хук вернул значение отличное
-              // от undefined и null, то данное значение
-              // возвращается в качестве результата
-              if (asyncResult != null) {
-                return asyncResult;
-              }
-            }
-            return;
-          })();
+          return this._continueHooksInvocationAsync(
+            hooks,
+            i + 1,
+            result,
+            response,
+            args,
+          );
         }
         // если синхронный хук вернул значение отличное
         // от undefined и null, то данное значение
@@ -133,4 +109,61 @@ export class HookInvoker extends DebuggableService {
     // и не вернули значения
     return;
   }
+
+  /**
+   * Асинхронно продолжает выполнение цепочки хуков, начиная с указанного
+   * индекса. Данный метод вызывается, когда хук в основном синхронном цикле
+   * возвращает Promise. Метод ожидает разрешения начального Promise, а затем
+   * последовательно выполняет оставшиеся хуки в асинхронном режиме, следуя
+   * той же логике прерывания (при получении значения или отправке ответа),
+   * что и основной метод.
+   *
+   * @param {Function[]} hooks
+   * @param {number} startIndex
+   * @param {Promise} initialPromise
+   * @param {import('http').ServerResponse} response
+   * @param {*} args
+   * @returns {Promise<*>}
+   */
+  async _continueHooksInvocationAsync(
+    hooks,
+    startIndex,
+    initialPromise,
+    response,
+    args,
+  ) {
+    // ожидание Promise, который был получен
+    // на предыдущем шаге (в синхронном режиме)
+    let result = await initialPromise;
+    // если ответ уже отправлен,
+    // то возвращается ServerResponse
+    if (isResponseSent(response)) {
+      return response;
+    }
+    // если Promise разрешился значением отличным
+    // от undefined и null, то данное значение
+    // возвращается в качестве результата
+    if (result != null) {
+      return result;
+    }
+    // продолжение вызова хуков начиная
+    // со следующего индекса (асинхронно)
+    for (let i = startIndex; i < hooks.length; i++) {
+      // с этого момента все синхронные
+      // хуки выполняются как асинхронные
+      result = await hooks[i](...args);
+      // если ответ уже отправлен,
+      // то возвращается ServerResponse
+      if (isResponseSent(response)) {
+        return response;
+      }
+      // если хук вернул значение отличное
+      // от undefined и null, то данное значение
+      // возвращается в качестве результата
+      if (result != null) {
+        return result;
+      }
+    }
+    return;
+  }
 }