## @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