@e22m4u/js-trie-router 0.4.2 → 0.4.4

package/README.md

@@ -1,5 +1,8 @@
 ## @e22m4u/js-trie-router
 
+![npm version](https://badge.fury.io/js/@e22m4u%2Fjs-trie-router.svg)
+![license](https://img.shields.io/badge/license-mit-blue.svg)
+
 HTTP маршрутизатор для Node.js на основе
 [префиксного дерева](https://ru.wikipedia.org/wiki/Trie) (trie).
 
@@ -19,7 +22,8 @@ HTTP маршрутизатор для Node.js на основе
     - [preHandler](#prehandler)
     - [postHandler](#posthandler)
   - [Глобальные хуки](#глобальные-хуки)
-  - [Метаданные](#метаданные)
+  - [Метаданные маршрута](#метаданные-маршрута)
+  - [Состояние запроса](#состояние-запроса)
 - [Отладка](#отладка)
 - [Тестирование](#тестирование)
 - [Лицензия](#лицензия)
@@ -97,6 +101,7 @@ server.listen(3000, 'localhost');             // прослушивание за
 - `response: ServerResponse` нативный поток ответа сервера;
 - `route: Route` экземпляр текущего маршрута;
 - `meta: object` геттер для доступа к метаданным маршрута (`route.meta`);
+- `state: object` объект для обмена данными между хуками и обработчиком;
 
 Пример доступа к контексту из обработчика маршрута.
 
@@ -121,6 +126,7 @@ router.defineRoute({
     console.log(ctx.response);  // ServerResponse
     console.log(ctx.route);     // Route
     console.log(ctx.meta);      // {prop: 'value'}
+    console.log(ctx.state);     // {}
     // ...
   },
 });
@@ -262,7 +268,7 @@ router.addPostHandler((ctx, data) => {
 отличное от `undefined` и `null`, то такое значение будет использовано
 как ответ сервера.
 
-### Метаданные
+### Метаданные маршрута
 
 Иногда требуется связать с маршрутом дополнительные, статические данные, которые
 могут быть использованы хуками для расширения функционала. Например, это могут
@@ -290,7 +296,7 @@ router.addPreHandler((ctx) => {
 router.defineRoute({
   method: HttpMethod.GET,
   path: '/',
-  meta: {foo: 'bar'}, // <= мета-данные
+  meta: {foo: 'bar'}, // <= метаданные
   handler(ctx) {
     return 'Hello World!';
   },
@@ -300,6 +306,38 @@ server.on('request', router.requestListener);
 server.listen(3000, 'localhost');
 ```
 
+### Состояние запроса
+
+Объект `ctx.state` инициализируется как пустой объект `{}` для каждого нового
+запроса. Он предназначен для передачи динамических данных (например, профиля
+пользователя после авторизации) из `preHandler` хуков в основной обработчик
+маршрута или `postHandler` хуки.
+
+```js
+import http from 'http';
+import {TrieRouter, HttpMethod} from '@e22m4u/js-trie-router';
+
+const router = new TrieRouter();
+
+// глобальный хук авторизации
+router.addPreHandler((ctx) => {
+  // логика получения пользователя (например, из заголовков)
+  const user = {id: 1, name: 'John', role: 'admin'};
+  // сохранение данных в state
+  ctx.state.user = user;
+});
+
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/profile',
+  handler(ctx) {
+    // доступ к данным, установленным в хуке
+    const user = ctx.state.user;
+    return `Hello, ${user.name}!`;
+  },
+});
+```
+
 ## Отладка
 
 Установка переменной `DEBUG` включает вывод логов.

package/dist/cjs/index.cjs

@@ -1454,6 +1454,12 @@ var _RequestContext = class _RequestContext {
    * @type {*}
    */
   body;
+  /**
+   * State.
+   *
+   * @type {object}
+   */
+  state = {};
   /**
    * Route meta.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-trie-router",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "HTTP маршрутизатор для Node.js на основе префиксного дерева",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "@e22m4u/js-path-trie": "~0.0.13",
     "@e22m4u/js-service": "~0.4.6",
     "debug": "~4.4.3",
-    "http-errors": "~2.0.0",
+    "http-errors": "~2.0.1",
     "statuses": "~2.0.2"
   },
   "devDependencies": {
@@ -58,13 +58,13 @@
     "eslint": "~9.39.1",
     "eslint-config-prettier": "~10.1.8",
     "eslint-plugin-chai-expect": "~3.1.0",
-    "eslint-plugin-jsdoc": "~61.2.1",
+    "eslint-plugin-jsdoc": "~61.4.1",
     "eslint-plugin-mocha": "~11.2.0",
     "globals": "~16.5.0",
     "husky": "~9.1.7",
     "mocha": "~11.7.5",
     "prettier": "~3.6.2",
-    "rimraf": "~6.1.0",
+    "rimraf": "~6.1.2",
     "typescript": "~5.9.3"
   }
 }

package/src/request-context.d.ts

@@ -60,6 +60,11 @@ export declare class RequestContext {
    */
   body: unknown;
 
+  /**
+   * State.
+   */
+  state: Record<string, any>;
+
   /**
    * Route meta.
    */

package/src/request-context.js

@@ -111,6 +111,13 @@ export class RequestContext {
    */
   body;
 
+  /**
+   * State.
+   *
+   * @type {object}
+   */
+  state = {};
+
   /**
    * Route meta.
    *

package/src/request-context.spec.js

@@ -166,4 +166,15 @@ describe('RequestContext', function () {
       expect(ctx.pathname).to.be.eq('/overridden');
     });
   });
+
+  describe('state', function () {
+    it('has an empty object by default', function () {
+      const req = createRequestMock({path: '/pathname'});
+      const res = createResponseMock();
+      const route = createRouteMock();
+      const cont = new ServiceContainer();
+      const ctx = new RequestContext(cont, req, res, route);
+      expect(ctx.state).to.be.eql({});
+    });
+  });
 });

package/src/utils/create-route-mock.d.ts

@@ -13,7 +13,6 @@ type RouteMockOptions = {
 /**
  * Create route mock.
  *
- * @param {Route} options
- * @returns {Route}
+ * @param options
  */
-export function createRouteMock(options: RouteMockOptions): Route;
+export function createRouteMock(options?: RouteMockOptions): Route;

package/src/utils/create-route-mock.js

@@ -2,15 +2,15 @@ import {Route, HttpMethod} from '../route.js';
 
 /**
  * @typedef {object} RouteMockOptions
- * @property {HttpMethod} method
- * @property {string} path
- * @property {import('../route.js').RouteHandler} handler
+ * @property {string|undefined} method
+ * @property {string|undefined} path
+ * @property {Function|undefined} handler
  */
 
 /**
  * Create route mock.
  *
- * @param {Route} options
+ * @param {RouteMockOptions|undefined} options
  * @returns {Route}
  */
 export function createRouteMock(options = {}) {