js-trie-router-data-mapper/README.md

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

Парсинг, валидация и проекция данных для @e22m4u/js-trie-router.

Содержание

• Установка
• Описание
• Использование
• Примеры
• Тесты
• Лицензия

Установка

npm install @e22m4u/js-trie-router-data-mapper

Модуль поддерживает ESM и CommonJS стандарты.

ESM

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

CommonJS

const {TrieRouterDataMapper} = require('@e22m4u/js-trie-router-data-mapper');

Описание

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

Используется синтаксис указанных ниже модулей (не требуют установки).

• Схема данных @e22m4u/js-data-schema
• Схема проекции @e22m4u/js-data-projector

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

Для корректной работы требуется выполнить подключение модуля к маршрутизатору. В этот момент будут зарегистрированы два глобальных хука. Первый хук разбирает и проверяет входящие данные, а второй и фильтрует ответ сервера.

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

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

Разметка данных задается в свойстве dataMapper метаданных маршрута. Ключи этого объекта определяют имена полей, добавляемых в контекст запроса, а значения описывают правила извлечения, валидации и проекции для каждого источника данных.

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).

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).

export const DataType = {
  ANY: 'any',
  STRING: 'string',
  NUMBER: 'number',
  BOOLEAN: 'boolean',
  ARRAY: 'array',
  OBJECT: 'object',
}

Примеры

Извлечение и разбор Query-параметра с JSON значением.

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;
  },
});

Фильтрация свойств возвращаемого объекта согласно схеме проекции.

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}

Тесты

npm run test

Лицензия

MIT