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

Парсинг, валидация и проекция данных для
[@e22m4u/js-trie-router](https://www.npmjs.com/package/@e22m4u/js-trie-router).

Модуль позволяет определить разметку данных для маршрутизатора. На основе
разметки выполняется автоматическое извлечение, парсинг, валидация и проекция
данных HTTP-запроса и ответа сервера. Сформированные данные помещаются
в контекст запроса или определяют структуру возвращаемого результата.

## Установка

```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');
```

## Использование

Подключение модуля к маршрутизатору.

```js
import {TrieRouter} from '@e22m4u/js-trie-router';
import {TrieRouterDataMapper} from '@e22m4u/js-trie-router-data-mapper';

const router = new TrieRouter();
router.useService(TrieRouterDataMapper);
```

Пример парсинга Query-параметра.

```js
router.defineRoute({
  method: HttpMethod.GET,
  path: '/parseQuery',
  meta: {
    // в объекте "dataMap" определяется набор свойств, которые
    // будут переданы в состояние текущего запроса "ctx.state",
    // свойства будут содержать данные согласно указанной схеме
    dataMap: {
      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
export const HttpData = {
  REQUEST_PARAMS: 'requestParams',
  REQUEST_QUERY: 'requestQuery',
  REQUEST_HEADERS: 'requestHeaders',
  REQUEST_COOKIES: 'requestCookies',
  REQUEST_BODY: 'requestBody',
  RESPONSE_BODY: 'responseBody',
};
```

Описание параметров `dataMap` (метаданные маршрута).

- `source: HttpData` источник данных;
- `property?: string` извлечение указанного свойства;
- `schema?: DataSchema` схема для парсинга и валидации;
- `projection?: DataProjection` схема проекции данных;

Пример проекции ответа.

```js
router.defineRoute({
  method: HttpMethod.GET,
  path: '/responseProjection',
  meta: {
    dataMap: {
      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}
```

Структура схемы данных и схемы проекции.

- Схема данных см. описание [@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, {
  // игнорировать опцию "schema"
  // для источника HttpData.RESPONSE_BODY
  ignoreResponseDataSchema: true,
});
```

## Тесты

```bash
npm run test
```

## Лицензия

MIT