@e22m4u/js-trie-router-data-mapper 0.1.0

package/.c8rc

@@ -0,0 +1,9 @@
+{
+  "all": true,
+  "include": [
+    "src/**/*.js"
+  ],
+  "exclude": [
+    "src/**/*.spec.js"
+  ]
+}

package/.commitlintrc

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

package/.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2
+max_line_length = 80

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+npm run lint:fix
+npm run format
+npm run test
+npm run build:cjs
+
+git add -A

package/.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "extension": ["js"],
+  "spec": "src/**/*.spec.js"
+}

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "bracketSpacing": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "trailingComma": "all",
+  "arrowParens": "avoid"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2025 Mikhail Evstropov <e22m4u@yandex.ru>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+## @e22m4u/js-trie-router-data-mapper
+
+Парсинг, валидация и проекция данных для
+[@e22m4u/js-trie-router](https://www.npmjs.com/package/@e22m4u/js-trie-router).
+
+## Содержание
+
+- [Установка](#установка)
+- [Описание](#описание)
+- [Использование](#использование)
+- [Тесты](#тесты)
+- [Лицензия](#лицензия)
+
+## Установка
+
+```bash
+npm install @e22m4u/js-trie-router-data-mapper
+```
+
+Модуль поддерживает ESM и CommonJS стандарты.
+
+*ESM*
+
+```js
+import {TrieRouterDataMapper} from '@e22m4u/js-trie-router-data-mapper';
+```
+
+*CommonJS*
+
+```js
+const {TrieRouterDataMapper} = require('@e22m4u/js-trie-router-data-mapper');
+```
+
+## Описание
+
+Модуль позволяет определить разметку данных маршрута. На основе разметки
+выполняется автоматический парсинг, валидация и проекция данных HTTP-запроса
+и ответа сервера. Сформированные данные помещаются в контекст запроса
+или определяют структуру возвращаемого ответа.
+
+Используется синтаксис указанных ниже модулей (не требуют установки).
+
+- Схема данных [@e22m4u/js-data-schema](https://www.npmjs.com/package/@e22m4u/js-data-schema)
+- Схема проекции [@e22m4u/js-data-projector](https://www.npmjs.com/package/@e22m4u/js-data-projector)
+
+## Использование
+
+Для корректной работы требуется выполнить подключение модуля к маршрутизатору.
+В этот момент будут зарегистрированы два глобальных хука. Первый хук разбирает
+и проверяет входящие данные, а второй фильтрует ответ сервера.
+
+```js
+import {TrieRouter} from '@e22m4u/js-trie-router';
+import {TrieRouterDataMapper} from '@e22m4u/js-trie-router-data-mapper';
+
+const router = new TrieRouter(); // экземпляр маршрутизатора
+router.useService(TrieRouterDataMapper); // <= подключение модуля
+```
+
+Разметка данных задается в свойстве `dataMapper` метаданных маршрута. Ключи
+этого объекта определяют имена полей, добавляемых в контекст запроса, а значения
+описывают правила извлечения, валидации и проекции для каждого источника данных.
+
+```js
+import {HttpMethod} from '@e22m4u/js-trie-router';
+import {HttpData, DataType} from '@e22m4u/js-trie-router-data-mapper';
+
+router.defineRoute({
+  method: HttpMethod.POST,
+  path: '/createUser',
+  meta: {
+    dataMapper: {
+      userData: { // свойство "userData" будет добавлено в "ctx.state"
+        source: HttpData.REQUEST_BODY, // источник данных
+        schema: DataType.OBJECT,       // тип или схема данных
+        // property: ...   (извлечь свойство из источника)
+        // projection: ... (схема проекции)
+      },
+    },
+  },
+  handler: ({state: {userData}}) => {
+    // ...
+  },
+});
+```
+
+Параметры разметки (метаданные маршрута).
+
+- `source: HttpData` источник данных;
+- `property?: string` извлечение указанного свойства;
+- `schema?: DataType | DataSchema` тип или схема данных;
+- `projection?: DataProjection` схема проекции;
+
+Константы источников данных (параметр `source`).
+
+```js
+export const HttpData = {
+  REQUEST_PARAMS: 'requestParams',
+  REQUEST_QUERY: 'requestQuery',
+  REQUEST_HEADERS: 'requestHeaders',
+  REQUEST_COOKIES: 'requestCookies',
+  REQUEST_BODY: 'requestBody',
+  RESPONSE_BODY: 'responseBody',
+};
+```
+
+Константы типов данных (подробнее [@e22m4u/js-data-schema](https://www.npmjs.com/package/@e22m4u/js-data-schema)).
+
+```js
+export const DataType = {
+  ANY: 'any',
+  STRING: 'string',
+  NUMBER: 'number',
+  BOOLEAN: 'boolean',
+  ARRAY: 'array',
+  OBJECT: 'object',
+}
+```
+
+### Примеры
+
+Извлечение и разбор Query-параметра с JSON значением.
+
+```js
+import {HttpMethod} from '@e22m4u/js-trie-router';
+import {HttpData, DataType} from '@e22m4u/js-trie-router-data-mapper';
+
+// GET /parseQuery?filter={"foo":"bar"}
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/parseQuery',
+  meta: {
+    dataMapper: {
+      filter: { // свойство "filter" будет добавлено в "ctx.state"
+        source: HttpData.REQUEST_QUERY, // источник данных
+        property: 'filter',       // извлечь свойство из источника
+        schema: {                 // схема для парсинга и валидации
+          type: DataType.OBJECT,  // разобрать значение как объект
+          required: true,         // значение является обязательным
+        },
+        // подробнее о схеме данных (параметр "schema")
+        // см. модуль @e22m4u/js-data-schema
+      },
+    },
+  },
+  handler: ({state: {filter}}) => {
+    // для запроса GET /parseQuery?filter={"foo":"bar"}
+    // значение параметра "filter" будет следующим:
+    console.log(typeof filter); // "object"
+    console.log(filter);        // {foo: 'bar'}
+    // если значение разобрать не удалось,
+    // то будет выброшена ошибка
+    return filter;
+  },
+});
+```
+
+Фильтрация свойств возвращаемого объекта согласно схеме проекции.
+
+```js
+import {HttpMethod} from '@e22m4u/js-trie-router';
+import {HttpData} from '@e22m4u/js-trie-router-data-mapper';
+
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/responseProjection',
+  meta: {
+    dataMapper: {
+      response: {
+        // свойство "response" не будет добавлено в "ctx.state",
+        // так как в данном случае источником выступает возвращаемое
+        // значение обработчика маршрута, а не входящие данные
+        source: HttpData.RESPONSE_BODY, // источник данных
+        projection: {foo: true, bar: false}, // схема проекции
+        // подробнее о схеме проекции (параметр "projection")
+        // см. модуль @e22m4u/js-data-projector
+      },
+    },
+  },
+  handler: () => {
+    return {
+      foo: 10, // доступно, явное правило
+      bar: 20, // исключено, явное правило
+      baz: 30, // исключено, отсутствует в схеме проекции
+    };
+  },
+});
+// для запроса GET /responseProjection
+// ответ будет {"foo":10}
+```
+
+## Тесты
+
+```bash
+npm run test
+```
+
+## Лицензия
+
+MIT

package/build-cjs.js

@@ -0,0 +1,16 @@
+import * as esbuild from 'esbuild';
+import packageJson from './package.json' with {type: 'json'};
+
+await esbuild.build({
+  entryPoints: ['src/index.js'],
+  outfile: 'dist/cjs/index.cjs',
+  format: 'cjs',
+  platform: 'node',
+  target: ['node12'],
+  bundle: true,
+  keepNames: true,
+  external: [
+    ...Object.keys(packageJson.peerDependencies || {}),
+    ...Object.keys(packageJson.dependencies || {}),
+  ],
+});

package/dist/cjs/index.cjs

@@ -0,0 +1,245 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  DataSchemaRegistry: () => import_js_data_schema2.DataSchemaRegistry,
+  DataType: () => import_js_data_schema2.DataType,
+  HTTP_DATA_LIST: () => HTTP_DATA_LIST,
+  HttpData: () => HttpData,
+  ProjectionSchemaRegistry: () => import_js_data_projector2.ProjectionSchemaRegistry,
+  TrieRouterDataMapper: () => TrieRouterDataMapper,
+  validateDataMappingSchema: () => validateDataMappingSchema
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/data-mapping-schema.js
+var HttpData = {
+  REQUEST_PARAMS: "requestParams",
+  REQUEST_QUERY: "requestQuery",
+  REQUEST_HEADERS: "requestHeaders",
+  REQUEST_COOKIES: "requestCookies",
+  REQUEST_BODY: "requestBody",
+  RESPONSE_BODY: "responseBody"
+};
+var HTTP_DATA_LIST = Object.values(HttpData);
+
+// src/trie-router-data-mapper.js
+var import_js_service = require("@e22m4u/js-service");
+var import_js_format2 = require("@e22m4u/js-format");
+var import_js_data_projector = require("@e22m4u/js-data-projector");
+var import_js_trie_router = require("@e22m4u/js-trie-router");
+var import_js_data_schema = require("@e22m4u/js-data-schema");
+
+// src/validate-data-mapping-schema.js
+var import_js_format = require("@e22m4u/js-format");
+function validateDataMappingSchema(schema) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new import_js_format.InvalidArgumentError(
+      "Mapping schema must be an Object, but %v was given.",
+      schema
+    );
+  }
+  Object.keys(schema).forEach((propName) => {
+    const propOptions = schema[propName];
+    if (propOptions === void 0) {
+      return;
+    }
+    if (!propOptions || typeof propOptions !== "object" || Array.isArray(propOptions)) {
+      throw new import_js_format.InvalidArgumentError(
+        "Property options must be an Object, but %v was given.",
+        propOptions
+      );
+    }
+    if (!propOptions.source || typeof propOptions.source !== "string" || !HTTP_DATA_LIST.includes(propOptions.source)) {
+      throw new import_js_format.InvalidArgumentError(
+        "Data source %v is not supported.",
+        propOptions.source
+      );
+    }
+    if (propOptions.property !== void 0 && (!propOptions.property || typeof propOptions.property !== "string")) {
+      throw new import_js_format.InvalidArgumentError(
+        "Property name must be a non-empty String, but %v was given.",
+        propOptions.property
+      );
+    }
+  });
+}
+__name(validateDataMappingSchema, "validateDataMappingSchema");
+
+// src/trie-router-data-mapper.js
+var HTTP_DATA_TO_CONTEXT_PROPERTY_MAP = {
+  [HttpData.REQUEST_PARAMS]: "params",
+  [HttpData.REQUEST_QUERY]: "query",
+  [HttpData.REQUEST_HEADERS]: "headers",
+  [HttpData.REQUEST_COOKIES]: "cookies",
+  [HttpData.REQUEST_BODY]: "body"
+};
+var _TrieRouterDataMapper = class _TrieRouterDataMapper extends import_js_service.Service {
+  /**
+   * Constructor.
+   *
+   * @param {import('@e22m4u/js-service').ServiceContainer} container
+   */
+  constructor(container) {
+    super(container);
+    const router = this.getService(import_js_trie_router.TrieRouter);
+    if (!router.hasPreHandler(dataMappingPreHandler)) {
+      router.addPreHandler(dataMappingPreHandler);
+    }
+    if (!router.hasPostHandler(dataMappingPostHandler)) {
+      router.addPostHandler(dataMappingPostHandler);
+    }
+  }
+  /**
+   * Create state by mapping schema.
+   *
+   * @param {import('@e22m4u/js-trie-router').RequestContext} ctx
+   * @param {import('./data-mapping-schema.js').DataMappingSchema} schema
+   * @returns {object}
+   */
+  createStateByMappingSchema(ctx, schema) {
+    if (!(ctx instanceof import_js_trie_router.RequestContext)) {
+      throw new import_js_format2.InvalidArgumentError(
+        'Parameter "ctx" must be a RequestContext instance, but %v was given.',
+        ctx
+      );
+    }
+    validateDataMappingSchema(schema);
+    const res = {};
+    const dataParser = this.getService(import_js_data_schema.DataParser);
+    const dataProjector = this.getService(import_js_data_projector.DataProjector);
+    Object.keys(schema).forEach((propName) => {
+      const propOptions = schema[propName];
+      if (propOptions === void 0) {
+        return;
+      }
+      const ctxProp = HTTP_DATA_TO_CONTEXT_PROPERTY_MAP[propOptions.source];
+      if (ctxProp === void 0) {
+        return;
+      }
+      let value = ctx[ctxProp];
+      if (propOptions.property && typeof propOptions.property === "string") {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          value = value[propOptions.property];
+        } else {
+          throw new import_js_format2.InvalidArgumentError(
+            "Property %v does not exist in %v value from the property %v of the request context.",
+            propOptions.property,
+            value,
+            ctxProp
+          );
+        }
+      }
+      if (propOptions.schema !== void 0) {
+        const sourcePath = propOptions.property ? `request.${ctxProp}.${propOptions.property}` : `request.${ctxProp}`;
+        if (import_js_data_schema.DATA_TYPE_LIST.includes(propOptions.schema)) {
+          const dataSchema = { type: propOptions.schema };
+          value = dataParser.parse(value, dataSchema, { sourcePath });
+        } else {
+          value = dataParser.parse(value, propOptions.schema, { sourcePath });
+        }
+      }
+      if (propOptions.projection !== void 0) {
+        value = dataProjector.project(value, propOptions.projection);
+      }
+      res[propName] = value;
+    });
+    return res;
+  }
+  /**
+   * Filter response by mapping schema.
+   *
+   * @param {*} data
+   * @param {import('./data-mapping-schema.js').DataMappingSchema} schema
+   * @returns {*}
+   */
+  filterResponseByMappingSchema(data, schema) {
+    validateDataMappingSchema(schema);
+    let res = data;
+    const dataParser = this.getService(import_js_data_schema.DataParser);
+    const dataProjector = this.getService(import_js_data_projector.DataProjector);
+    Object.keys(schema).forEach((propName) => {
+      const propOptions = schema[propName];
+      if (propOptions === void 0) {
+        return;
+      }
+      if (propOptions.source !== HttpData.RESPONSE_BODY) {
+        return;
+      }
+      if (propOptions.property !== void 0) {
+        throw new import_js_format2.InvalidArgumentError(
+          'Option "property" is not supported for the %v source, but %v was given.',
+          propOptions.property
+        );
+      }
+      if (propOptions.schema !== void 0) {
+        const sourcePath = "response.body";
+        const parsingOptions = { sourcePath, noParsingErrors: true };
+        if (import_js_data_schema.DATA_TYPE_LIST.includes(propOptions.schema)) {
+          const dataSchema = { type: propOptions.schema };
+          res = dataParser.parse(res, dataSchema, parsingOptions);
+        } else {
+          res = dataParser.parse(res, propOptions.schema, parsingOptions);
+        }
+      }
+      if (propOptions.projection !== void 0) {
+        res = dataProjector.project(res, propOptions.projection);
+      }
+    });
+    return res;
+  }
+};
+__name(_TrieRouterDataMapper, "TrieRouterDataMapper");
+var TrieRouterDataMapper = _TrieRouterDataMapper;
+function dataMappingPreHandler(ctx) {
+  const schema = (ctx.meta || {}).dataMapper;
+  if (schema === void 0) {
+    return;
+  }
+  const mapper = ctx.container.get(TrieRouterDataMapper);
+  const state = mapper.createStateByMappingSchema(ctx, schema);
+  ctx.state = { ...ctx.state, ...state };
+}
+__name(dataMappingPreHandler, "dataMappingPreHandler");
+function dataMappingPostHandler(ctx, data) {
+  const schema = (ctx.meta || {}).dataMapper;
+  if (schema === void 0) {
+    return;
+  }
+  const mapper = ctx.container.get(TrieRouterDataMapper);
+  return mapper.filterResponseByMappingSchema(data, schema);
+}
+__name(dataMappingPostHandler, "dataMappingPostHandler");
+
+// src/index.js
+var import_js_data_projector2 = require("@e22m4u/js-data-projector");
+var import_js_data_schema2 = require("@e22m4u/js-data-schema");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DataSchemaRegistry,
+  DataType,
+  HTTP_DATA_LIST,
+  HttpData,
+  ProjectionSchemaRegistry,
+  TrieRouterDataMapper,
+  validateDataMappingSchema
+});

package/eslint.config.js

@@ -0,0 +1,41 @@
+import globals from 'globals';
+import eslintJs from '@eslint/js';
+import eslintJsdocPlugin from 'eslint-plugin-jsdoc';
+import eslintMochaPlugin from 'eslint-plugin-mocha';
+import eslintImportPlugin from 'eslint-plugin-import';
+import eslintPrettierConfig from 'eslint-config-prettier';
+import eslintChaiExpectPlugin from 'eslint-plugin-chai-expect';
+
+export default [{
+  languageOptions: {
+    globals: {
+      ...globals.node,
+      ...globals.es2021,
+      ...globals.mocha,
+    },
+  },
+  plugins: {
+    'jsdoc': eslintJsdocPlugin,
+    'mocha': eslintMochaPlugin,
+    'import': eslintImportPlugin,
+    'chai-expect': eslintChaiExpectPlugin,
+  },
+  rules: {
+    ...eslintJs.configs.recommended.rules,
+    ...eslintPrettierConfig.rules,
+    ...eslintImportPlugin.flatConfigs.recommended.rules,
+    ...eslintMochaPlugin.configs.recommended.rules,
+    ...eslintChaiExpectPlugin.configs['recommended-flat'].rules,
+    ...eslintJsdocPlugin.configs['flat/recommended-error'].rules,
+    "curly": "error",
+    'no-duplicate-imports': 'error',
+    'import/export': 0,
+    'jsdoc/reject-any-type': 0,
+    'jsdoc/reject-function-type': 0,
+    'jsdoc/require-param-description': 0,
+    'jsdoc/require-returns-description': 0,
+    'jsdoc/require-property-description': 0,
+    'jsdoc/tag-lines': ['error', 'any', {startLines: 1}],
+  },
+  files: ['src/**/*.js'],
+}];

package/examples/query-parsing-example.js

@@ -0,0 +1,52 @@
+import http from 'http';
+import {DataType} from '@e22m4u/js-data-schema';
+import {HttpMethod, TrieRouter} from '@e22m4u/js-trie-router';
+
+import {
+  HttpData,
+  TrieRouterDataMapper,
+} from '@e22m4u/js-trie-router-data-mapper';
+
+const router = new TrieRouter();
+router.useService(TrieRouterDataMapper);
+
+// регистрация маршрута для разбора
+// query параметра "filter"
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/parseQuery',
+  meta: {
+    dataMapper: {
+      filter: {
+        source: HttpData.REQUEST_QUERY,
+        property: 'filter',
+        schema: {
+          type: DataType.OBJECT,
+          required: true,
+        },
+      },
+    },
+  },
+  handler: ({state: {filter}}) => {
+    return filter;
+  },
+});
+
+// создание экземпляра 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}/parseQuery?filter={"foo":"bar"}`,
+  );
+});

package/examples/response-projection-example.js

@@ -0,0 +1,47 @@
+import http from 'http';
+import {HttpMethod, TrieRouter} from '@e22m4u/js-trie-router';
+
+import {
+  HttpData,
+  TrieRouterDataMapper,
+} from '@e22m4u/js-trie-router-data-mapper';
+
+const router = new TrieRouter();
+router.useService(TrieRouterDataMapper);
+
+// регистрация маршрута для проверки
+// проекции возвращаемого объекта
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/responseProjection',
+  meta: {
+    dataMapper: {
+      response: {
+        source: HttpData.RESPONSE_BODY,
+        projection: {foo: true, bar: false},
+      },
+    },
+  },
+  handler: () => {
+    return {foo: 10, bar: 20, baz: 30};
+  },
+});
+
+// создание экземпляра 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}/responseProjection`,
+  );
+});

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@e22m4u/js-trie-router-data-mapper",
+  "version": "0.1.0",
+  "description": "Парсинг, валидация и проекция данных для @e22m4u/js-trie-router",
+  "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
+  "license": "MIT",
+  "keywords": [
+    "data",
+    "trie",
+    "router",
+    "parsing",
+    "validation"
+  ],
+  "homepage": "https://gitrepos.ru/e22m4u/js-trie-router-data-mapper",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitrepos.ru/e22m4u/js-trie-router-data-mapper.git"
+  },
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "module": "./src/index.js",
+  "main": "./dist/cjs/index.cjs",
+  "exports": {
+    "types": "./src/index.d.ts",
+    "import": "./src/index.js",
+    "require": "./dist/cjs/index.cjs"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "scripts": {
+    "lint": "tsc && eslint ./src",
+    "lint:fix": "tsc && eslint ./src --fix",
+    "format": "prettier --write \"./src/**/*.js\"",
+    "test": "npm run lint && c8 --reporter=text-summary mocha --bail",
+    "test:coverage": "npm run lint && c8 --reporter=text mocha --bail",
+    "build:cjs": "rimraf ./dist/cjs && node build-cjs.js",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@e22m4u/js-data-projector": "~0.2.0",
+    "@e22m4u/js-data-schema": "~0.0.7",
+    "@e22m4u/js-format": "~0.3.2",
+    "@e22m4u/js-service": "~0.5.1"
+  },
+  "peerDependencies": {
+    "@e22m4u/js-trie-router": "~0.5.12"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "~20.3.1",
+    "@commitlint/config-conventional": "~20.3.1",
+    "@eslint/js": "~9.39.2",
+    "@types/chai": "~5.2.3",
+    "@types/mocha": "~10.0.10",
+    "c8": "~10.1.3",
+    "chai": "~6.2.2",
+    "esbuild": "~0.27.2",
+    "eslint": "~9.39.2",
+    "eslint-config-prettier": "~10.1.8",
+    "eslint-plugin-chai-expect": "~3.1.0",
+    "eslint-plugin-import": "~2.32.0",
+    "eslint-plugin-jsdoc": "~62.0.0",
+    "eslint-plugin-mocha": "~11.2.0",
+    "globals": "~17.0.0",
+    "husky": "~9.1.7",
+    "mocha": "~11.7.5",
+    "prettier": "~3.7.4",
+    "rimraf": "~6.1.2",
+    "typescript": "~5.9.3"
+  }
+}

package/src/data-mapping-schema.d.ts

@@ -0,0 +1,41 @@
+import {ProjectionSchema} from '@e22m4u/js-data-projector';
+import {DataSchema, DataType} from '@e22m4u/js-data-schema';
+
+/**
+ * Http data.
+ */
+export declare const HttpData: {
+  REQUEST_PARAMS: 'requestParams';
+  REQUEST_QUERY: 'requestQuery';
+  REQUEST_HEADERS: 'requestHeaders';
+  REQUEST_COOKIES: 'requestCookies';
+  REQUEST_BODY: 'requestBody';
+  RESPONSE_BODY: 'responseBody';
+};
+
+/**
+ * Http data.
+ */
+export type HttpData = (typeof HttpData)[keyof typeof HttpData];
+
+/**
+ * Http data list.
+ */
+export declare const HTTP_DATA_LIST: HttpData[];
+
+/**
+ * Data mapping schema.
+ */
+export type DataMappingSchema = {
+  [property: string]: DataMappingPropertyOptions | undefined;
+};
+
+/**
+ * Data mapping property options.
+ */
+export interface DataMappingPropertyOptions {
+  source: HttpData;
+  property?: string;
+  schema?: DataSchema | DataType;
+  projection?: ProjectionSchema;
+}

package/src/data-mapping-schema.js

@@ -0,0 +1,16 @@
+/**
+ * Http data.
+ */
+export const HttpData = {
+  REQUEST_PARAMS: 'requestParams',
+  REQUEST_QUERY: 'requestQuery',
+  REQUEST_HEADERS: 'requestHeaders',
+  REQUEST_COOKIES: 'requestCookies',
+  REQUEST_BODY: 'requestBody',
+  RESPONSE_BODY: 'responseBody',
+};
+
+/**
+ * Http data list.
+ */
+export const HTTP_DATA_LIST = Object.values(HttpData);

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './route-meta.js';
+export * from './data-mapping-schema.js';
+export * from './trie-router-data-mapper.js';
+export * from './validate-data-mapping-schema.js';
+export {ProjectionSchemaRegistry} from '@e22m4u/js-data-projector';
+export {DataType, DataSchemaRegistry} from '@e22m4u/js-data-schema';

package/src/index.js

@@ -0,0 +1,5 @@
+export * from './data-mapping-schema.js';
+export * from './trie-router-data-mapper.js';
+export * from './validate-data-mapping-schema.js';
+export {ProjectionSchemaRegistry} from '@e22m4u/js-data-projector';
+export {DataType, DataSchemaRegistry} from '@e22m4u/js-data-schema';

package/src/route-meta.d.ts

@@ -0,0 +1,8 @@
+import '@e22m4u/js-trie-router';
+import {DataMappingSchema} from './data-mapping-schema.js';
+
+declare module '@e22m4u/js-trie-router' {
+  export interface RouteMeta {
+    dataMapper?: DataMappingSchema,
+  }
+}

package/src/trie-router-data-mapper.d.ts

@@ -0,0 +1,37 @@
+import {RequestContext} from '@e22m4u/js-trie-router';
+import {DataMappingSchema} from './data-mapping-schema.js';
+import {Service, ServiceContainer} from '@e22m4u/js-service';
+
+/**
+ * Trie router data mapper.
+ */
+export declare class TrieRouterDataMapper extends Service {
+  /**
+   * Constructor.
+   *
+   * @param container
+   */
+  constructor(container?: ServiceContainer);
+
+  /**
+   * Create state by mapping schema.
+   *
+   * @param ctx
+   * @param schema
+   */
+  createStateByMappingSchema(
+    ctx: RequestContext,
+    schema: DataMappingSchema,
+  ): object;
+
+  /**
+   * Filter response by mapping schema.
+   *
+   * @param data
+   * @param schema
+   */
+  filterResponseByMappingSchema(
+    data: unknown,
+    schema: DataMappingSchema,
+  ): unknown;
+}

package/src/trie-router-data-mapper.js

@@ -0,0 +1,206 @@
+import {Service} from '@e22m4u/js-service';
+import {HttpData} from './data-mapping-schema.js';
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {DataProjector} from '@e22m4u/js-data-projector';
+import {RequestContext, TrieRouter} from '@e22m4u/js-trie-router';
+import {DATA_TYPE_LIST, DataParser} from '@e22m4u/js-data-schema';
+import {validateDataMappingSchema} from './validate-data-mapping-schema.js';
+
+/**
+ * Константа HttpData определяет какое свойство контекста
+ * запроса будет использовано для формирования данных.
+ * Этот объект связывает значения HttpData со свойствами
+ * контекста запроса.
+ */
+const HTTP_DATA_TO_CONTEXT_PROPERTY_MAP = {
+  [HttpData.REQUEST_PARAMS]: 'params',
+  [HttpData.REQUEST_QUERY]: 'query',
+  [HttpData.REQUEST_HEADERS]: 'headers',
+  [HttpData.REQUEST_COOKIES]: 'cookies',
+  [HttpData.REQUEST_BODY]: 'body',
+};
+
+/**
+ * Trie router data mapper.
+ */
+export class TrieRouterDataMapper extends Service {
+  /**
+   * Constructor.
+   *
+   * @param {import('@e22m4u/js-service').ServiceContainer} container
+   */
+  constructor(container) {
+    super(container);
+    const router = this.getService(TrieRouter);
+    if (!router.hasPreHandler(dataMappingPreHandler)) {
+      router.addPreHandler(dataMappingPreHandler);
+    }
+    if (!router.hasPostHandler(dataMappingPostHandler)) {
+      router.addPostHandler(dataMappingPostHandler);
+    }
+  }
+
+  /**
+   * Create state by mapping schema.
+   *
+   * @param {import('@e22m4u/js-trie-router').RequestContext} ctx
+   * @param {import('./data-mapping-schema.js').DataMappingSchema} schema
+   * @returns {object}
+   */
+  createStateByMappingSchema(ctx, schema) {
+    if (!(ctx instanceof RequestContext)) {
+      throw new InvalidArgumentError(
+        'Parameter "ctx" must be a RequestContext instance, but %v was given.',
+        ctx,
+      );
+    }
+    validateDataMappingSchema(schema);
+    const res = {};
+    const dataParser = this.getService(DataParser);
+    const dataProjector = this.getService(DataProjector);
+    // обход каждого свойства схемы
+    // для формирования объекта данных
+    Object.keys(schema).forEach(propName => {
+      // если параметры свойства не определены,
+      // то данное свойство пропускается
+      const propOptions = schema[propName];
+      if (propOptions === undefined) {
+        return;
+      }
+      // если свойство контекста не определено,
+      // то данное свойство пропускается
+      const ctxProp = HTTP_DATA_TO_CONTEXT_PROPERTY_MAP[propOptions.source];
+      if (ctxProp === undefined) {
+        return;
+      }
+      let value = ctx[ctxProp];
+      // если определено вложенное свойство,
+      // то выполняется попытка его извлечения
+      if (propOptions.property && typeof propOptions.property === 'string') {
+        // если свойство контекста содержит объект,
+        // то извлекается значение вложенного свойства
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+          value = value[propOptions.property];
+        }
+        // если свойство контекста не содержит
+        // объект, то выбрасывается ошибка
+        else {
+          throw new InvalidArgumentError(
+            'Property %v does not exist in %v value ' +
+              'from the property %v of the request context.',
+            propOptions.property,
+            value,
+            ctxProp,
+          );
+        }
+      }
+      // если определена схема данных,
+      // то выполняется разбор значения
+      if (propOptions.schema !== undefined) {
+        const sourcePath = propOptions.property
+          ? `request.${ctxProp}.${propOptions.property}`
+          : `request.${ctxProp}`;
+        if (DATA_TYPE_LIST.includes(propOptions.schema)) {
+          const dataSchema = {type: propOptions.schema};
+          value = dataParser.parse(value, dataSchema, {sourcePath});
+        } else {
+          value = dataParser.parse(value, propOptions.schema, {sourcePath});
+        }
+      }
+      // если определена схема проекции,
+      // то выполняется создание проекции
+      if (propOptions.projection !== undefined) {
+        value = dataProjector.project(value, propOptions.projection);
+      }
+      // значение присваивается
+      // результирующему объекту
+      res[propName] = value;
+    });
+    return res;
+  }
+
+  /**
+   * Filter response by mapping schema.
+   *
+   * @param {*} data
+   * @param {import('./data-mapping-schema.js').DataMappingSchema} schema
+   * @returns {*}
+   */
+  filterResponseByMappingSchema(data, schema) {
+    validateDataMappingSchema(schema);
+    let res = data;
+    const dataParser = this.getService(DataParser);
+    const dataProjector = this.getService(DataProjector);
+    // обход каждого свойства схемы
+    // для формирования данных ответа
+    Object.keys(schema).forEach(propName => {
+      // если параметры свойства не определены,
+      // то данное свойство пропускается
+      const propOptions = schema[propName];
+      if (propOptions === undefined) {
+        return;
+      }
+      // если источником не является тело ответа,
+      // то данное свойство пропускается
+      if (propOptions.source !== HttpData.RESPONSE_BODY) {
+        return;
+      }
+      // если определено вложенное свойство,
+      // то выбрасывается ошибка
+      if (propOptions.property !== undefined) {
+        throw new InvalidArgumentError(
+          'Option "property" is not supported for the %v source, ' +
+            'but %v was given.',
+          propOptions.property,
+        );
+      }
+      // если определена схема данных, то выполняется
+      // разбор значения без валидации данных
+      if (propOptions.schema !== undefined) {
+        const sourcePath = 'response.body';
+        const parsingOptions = {sourcePath, noParsingErrors: true};
+        if (DATA_TYPE_LIST.includes(propOptions.schema)) {
+          const dataSchema = {type: propOptions.schema};
+          res = dataParser.parse(res, dataSchema, parsingOptions);
+        } else {
+          res = dataParser.parse(res, propOptions.schema, parsingOptions);
+        }
+      }
+      // если определена схема проекции,
+      // то выполняется создание проекции
+      if (propOptions.projection !== undefined) {
+        res = dataProjector.project(res, propOptions.projection);
+      }
+    });
+    return res;
+  }
+}
+
+/**
+ * Data mapping pre-handler.
+ *
+ * @type {import('@e22m4u/js-trie-router').PreHandlerHook}
+ */
+function dataMappingPreHandler(ctx) {
+  const schema = (ctx.meta || {}).dataMapper;
+  if (schema === undefined) {
+    return;
+  }
+  const mapper = ctx.container.get(TrieRouterDataMapper);
+  const state = mapper.createStateByMappingSchema(ctx, schema);
+  ctx.state = {...ctx.state, ...state};
+}
+
+/**
+ * Data mapping post handler.
+ *
+ * @type {import('@e22m4u/js-trie-router').PostHandlerHook}
+ */
+function dataMappingPostHandler(ctx, data) {
+  const schema = (ctx.meta || {}).dataMapper;
+  if (schema === undefined) {
+    return;
+  }
+  const mapper = ctx.container.get(TrieRouterDataMapper);
+  return mapper.filterResponseByMappingSchema(data, schema);
+}

package/src/validate-data-mapping-schema.d.ts

@@ -0,0 +1,8 @@
+import {DataMappingSchema} from './data-mapping-schema.js';
+
+/**
+ * Validate data mapping schema.
+ *
+ * @param schema
+ */
+export function validateDataMappingSchema(schema: DataMappingSchema): void;

package/src/validate-data-mapping-schema.js

@@ -0,0 +1,54 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {HTTP_DATA_LIST} from './data-mapping-schema.js';
+
+/**
+ * Validate data mapping schema.
+ *
+ * @param {import('./data-mapping-schema.js').DataMappingSchema} schema
+ */
+export function validateDataMappingSchema(schema) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    throw new InvalidArgumentError(
+      'Mapping schema must be an Object, but %v was given.',
+      schema,
+    );
+  }
+  // schema[k]
+  Object.keys(schema).forEach(propName => {
+    const propOptions = schema[propName];
+    if (propOptions === undefined) {
+      return;
+    }
+    if (
+      !propOptions ||
+      typeof propOptions !== 'object' ||
+      Array.isArray(propOptions)
+    ) {
+      throw new InvalidArgumentError(
+        'Property options must be an Object, but %v was given.',
+        propOptions,
+      );
+    }
+    // schema[k].source
+    if (
+      !propOptions.source ||
+      typeof propOptions.source !== 'string' ||
+      !HTTP_DATA_LIST.includes(propOptions.source)
+    ) {
+      throw new InvalidArgumentError(
+        'Data source %v is not supported.',
+        propOptions.source,
+      );
+    }
+    // schema[k].property
+    if (
+      propOptions.property !== undefined &&
+      (!propOptions.property || typeof propOptions.property !== 'string')
+    ) {
+      throw new InvalidArgumentError(
+        'Property name must be a non-empty String, but %v was given.',
+        propOptions.property,
+      );
+    }
+  });
+}

package/src/validate-data-mapping-schema.spec.js

@@ -0,0 +1,75 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {HttpData} from './data-mapping-schema.js';
+import {validateDataMappingSchema} from './validate-data-mapping-schema.js';
+
+describe('validateDataMappingSchema', function () {
+  it('should require the "schema" parameter to be an Object', function () {
+    const throwable = v => () => validateDataMappingSchema(v);
+    const error = s =>
+      format('Mapping schema must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    expect(throwable(() => undefined)).to.throw(error('Function'));
+    throwable({})();
+  });
+
+  it('should require property options to be an Object', function () {
+    const throwable = v => () => validateDataMappingSchema({prop: v});
+    const error = s =>
+      format('Property options must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    expect(throwable(() => undefined)).to.throw(error('Function'));
+    throwable({source: HttpData.REQUEST_BODY})();
+    throwable(undefined)();
+  });
+
+  it('should require the "source" option to be a HttpData value', function () {
+    const throwable = v => () => validateDataMappingSchema({prop: {source: v}});
+    const error = s => format('Data source %s is not supported.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    expect(throwable(() => undefined)).to.throw(error('Function'));
+    throwable(HttpData.REQUEST_BODY)();
+  });
+
+  it('should require the "property" option to be a non-empty String', function () {
+    const throwable = v => () =>
+      validateDataMappingSchema({
+        prop: {source: HttpData.REQUEST_BODY, property: v},
+      });
+    const error = s =>
+      format('Property name must be a non-empty String, but %s was given.', s);
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    expect(throwable(() => undefined)).to.throw(error('Function'));
+    throwable('str')();
+    throwable(undefined)();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "es2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "allowJs": true
+  },
+  "include": [
+    "./src/**/*.ts",
+    "./src/**/*.js"
+  ]
+}