@e22m4u/js-trie-router 0.7.3 → 0.7.5

package/README.md

@@ -20,6 +20,7 @@ HTTP маршрутизатор для Node.js на основе
   - [Параметры маршрутизатора](#параметры-маршрутизатора)
   - [Контекст запроса](#контекст-запроса)
   - [Отправка ответа](#отправка-ответа)
+  - [Парсинг тела запроса](#парсинг-тела-запроса)
   - [Жизненный цикл](#жизненный-цикл)
   - [Хуки маршрута](#хуки-маршрута)
   - [Глобальные хуки](#глобальные-хуки)
@@ -219,6 +220,99 @@ router.defineRoute({
 });
 ```
 
+### Парсинг тела запроса
+
+Для разбора тела входящего запроса отслеживается заголовок `Content-Type`,
+определяющий формат передаваемых данных. По умолчанию маршрутизатор включает
+парсеры для следующих форматов:
+
+- `application/json` разбирается как *JSON*;
+- `text/plain` преобразуется в строку;
+
+Если входящий запрос содержит данные, но для его формата не найден подходящий
+парсер, маршрутизатор прервет обработку запроса и вернет ошибку
+*415 Unsupported Media Type*.
+
+```json
+{
+  "error": {
+    "message": "Media type \"application/octet-stream\" is not supported."
+  }
+}
+```
+
+Чтобы избежать появления ошибки для форматов, которые предполагается
+обрабатывать особым способом, предусмотрен параметр маршрутизатора
+`ignoredMediaTypes` для игнорирования указанных медиа-типов. Параметр
+позволяет пропустить встроенный парсинг, как это сделано в примере ниже.
+
+```js
+import {TrieRouter, HttpMethod} from '@e22m4u/js-trie-router';
+
+// создание экземпляра маршрутизатора
+// с указанием исключаемых медиа-типов
+const router = new TrieRouter({
+  ignoredMediaTypes: [
+    'application/octet-stream',
+    'multipart/form-data'
+  ],
+});
+
+// регистрация маршрута для обработки файлов
+router.defineRoute({
+  method: HttpMethod.POST,
+  path: '/upload',
+  handler(ctx) {
+    // свойство body остается пустым, далее
+    // выполняется доступ к нативному потоку
+    const stream = ctx.request;
+    return 'OK';
+  }
+});
+```
+
+#### Регистрация пользовательского парсера
+
+Для расширения поддерживаемых форматов предусмотрена возможность регистрации
+пользовательской функции парсинга для определенного медиа-типа. Управление
+такими функциями выполняется сервисом `RequestBodyParser`, который доступен
+через глобальный контейнер маршрутизатора.
+
+```js
+// доступ к сервису через маршрутизатор
+const bodyParser = router.getService(RequestBodyParser);
+// bodyParser.defineParser(mediaType, parserFn); см. далее
+```
+
+Регистрируемая функция принимает извлеченные данные в виде строки и возвращает
+преобразованный результат. Итоговое значение впоследствии будет доступно
+в контексте обработки запроса.
+
+```js
+import queryString from 'querystring';
+import {TrieRouter, HttpMethod, RequestBodyParser} from '@e22m4u/js-trie-router';
+
+const router = new TrieRouter();
+const bodyParser = router.getService(RequestBodyParser);
+
+// регистрация парсера для обработки данных формы
+bodyParser.defineParser(
+  'application/x-www-form-urlencoded',
+  (input) => queryString.parse(input),
+);
+
+// определение маршрута
+router.defineRoute({
+  method: HttpMethod.POST,
+  path: '/submit',
+  handler(ctx) {
+    // свойство содержит результат
+    // работы новой парсер-функции
+    return ctx.body;
+  }
+});
+```
+
 ### Жизненный цикл
 
 Для понимания того, как маршрутизатор обрабатывает входящий запрос, ниже

package/dist/cjs/index.cjs

@@ -881,7 +881,7 @@ function patchHeaders(response) {
         );
       }
       const key = name.toLowerCase();
-      this._headers[key] = String(value);
+      this._headers[key] = Array.isArray(value) ? [...value.map(String)] : String(value);
       return this;
     }, "value")
   });
@@ -2156,23 +2156,23 @@ var _RequestBodyParser = class _RequestBodyParser extends DebuggableService {
    * Set parser.
    *
    * @param {string} mediaType
-   * @param {Function} parser
+   * @param {Function} parserFn
    * @returns {this}
    */
-  defineParser(mediaType, parser) {
+  defineParser(mediaType, parserFn) {
     if (!mediaType || typeof mediaType !== "string") {
       throw new import_js_format19.InvalidArgumentError(
         'Parameter "mediaType" must be a non-empty String, but %v was given.',
         mediaType
       );
     }
-    if (!parser || typeof parser !== "function") {
+    if (!parserFn || typeof parserFn !== "function") {
       throw new import_js_format19.InvalidArgumentError(
-        'Parameter "parser" must be a Function, but %v was given.',
-        parser
+        'Parameter "parserFn" must be a Function, but %v was given.',
+        parserFn
       );
     }
-    this._parsers[mediaType.toLowerCase()] = parser;
+    this._parsers[mediaType.toLowerCase()] = parserFn;
     return this;
   }
   /**
@@ -2203,14 +2203,14 @@ var _RequestBodyParser = class _RequestBodyParser extends DebuggableService {
         mediaType
       );
     }
-    const parser = this._parsers[mediaType.toLowerCase()];
-    if (!parser) {
+    const parserFn = this._parsers[mediaType.toLowerCase()];
+    if (!parserFn) {
       throw new import_js_format19.InvalidArgumentError(
         "Media type %v does not have a parser.",
         mediaType
       );
     }
-    return parser;
+    return parserFn;
   }
   /**
    * Remove parser.
@@ -2264,8 +2264,8 @@ var _RequestBodyParser = class _RequestBodyParser extends DebuggableService {
       debug("Media type %v is ignored.", mediaType);
       return;
     }
-    const parser = this._parsers[mediaTypeLc];
-    if (!parser) {
+    const parserFn = this._parsers[mediaTypeLc];
+    if (!parserFn) {
       throw createError(
         import_http_errors2.default.UnsupportedMediaType,
         "Media type %v is not supported.",
@@ -2278,7 +2278,7 @@ var _RequestBodyParser = class _RequestBodyParser extends DebuggableService {
     return fetchRequestBody(request, bodyBytesLimit).then((rawBody) => {
       if (rawBody != null) {
         debug("Read %v bytes.", Buffer.byteLength(rawBody, "utf8"));
-        return parser(rawBody);
+        return parserFn(rawBody);
       }
       debug("Request body has no content.");
       return rawBody;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-trie-router",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "HTTP маршрутизатор для Node.js на основе префиксного дерева",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",

package/src/parsers/request-body-parser.d.ts

@@ -15,9 +15,9 @@ export declare class RequestBodyParser extends DebuggableService {
    * Define parser.
    *
    * @param mediaType
-   * @param parser
+   * @param parserFn
    */
-  defineParser(mediaType: string, parser: BodyParserFunction): this;
+  defineParser(mediaType: string, parserFn: BodyParserFunction): this;
 
   /**
    * Has parser.

package/src/parsers/request-body-parser.js

@@ -29,10 +29,10 @@ export class RequestBodyParser extends DebuggableService {
    * Set parser.
    *
    * @param {string} mediaType
-   * @param {Function} parser
+   * @param {Function} parserFn
    * @returns {this}
    */
-  defineParser(mediaType, parser) {
+  defineParser(mediaType, parserFn) {
     if (!mediaType || typeof mediaType !== 'string') {
       throw new InvalidArgumentError(
         'Parameter "mediaType" must be a non-empty String, ' +
@@ -40,13 +40,13 @@ export class RequestBodyParser extends DebuggableService {
         mediaType,
       );
     }
-    if (!parser || typeof parser !== 'function') {
+    if (!parserFn || typeof parserFn !== 'function') {
       throw new InvalidArgumentError(
-        'Parameter "parser" must be a Function, but %v was given.',
-        parser,
+        'Parameter "parserFn" must be a Function, but %v was given.',
+        parserFn,
       );
     }
-    this._parsers[mediaType.toLowerCase()] = parser;
+    this._parsers[mediaType.toLowerCase()] = parserFn;
     return this;
   }
 
@@ -81,14 +81,14 @@ export class RequestBodyParser extends DebuggableService {
         mediaType,
       );
     }
-    const parser = this._parsers[mediaType.toLowerCase()];
-    if (!parser) {
+    const parserFn = this._parsers[mediaType.toLowerCase()];
+    if (!parserFn) {
       throw new InvalidArgumentError(
         'Media type %v does not have a parser.',
         mediaType,
       );
     }
-    return parser;
+    return parserFn;
   }
 
   /**
@@ -155,8 +155,8 @@ export class RequestBodyParser extends DebuggableService {
     }
     // если парсер для текущего медиа типа
     // не определен, то выбрасывается ошибка
-    const parser = this._parsers[mediaTypeLc];
-    if (!parser) {
+    const parserFn = this._parsers[mediaTypeLc];
+    if (!parserFn) {
       throw createError(
         HttpErrors.UnsupportedMediaType,
         'Media type %v is not supported.',
@@ -173,7 +173,7 @@ export class RequestBodyParser extends DebuggableService {
     return fetchRequestBody(request, bodyBytesLimit).then(rawBody => {
       if (rawBody != null) {
         debug('Read %v bytes.', Buffer.byteLength(rawBody, 'utf8'));
-        return parser(rawBody);
+        return parserFn(rawBody);
       }
       debug('Request body has no content.');
       return rawBody;

package/src/parsers/request-body-parser.spec.js

@@ -30,11 +30,11 @@ describe('RequestBodyParser', function () {
       throwable('text/plain')();
     });
 
-    it('should require the parameter "parser" to be a Function', function () {
+    it('should require the parameter "parserFn" to be a Function', function () {
       const S = new RequestBodyParser();
       const throwable = v => () => S.defineParser('str', v);
       const error = v =>
-        format('Parameter "parser" must be a Function, but %s was given.', v);
+        format('Parameter "parserFn" must be a Function, but %s was given.', v);
       expect(throwable('str')).to.throw(error('"str"'));
       expect(throwable('')).to.throw(error('""'));
       expect(throwable(10)).to.throw(error('10'));

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

@@ -72,7 +72,9 @@ function patchHeaders(response) {
         );
       }
       const key = name.toLowerCase();
-      this._headers[key] = String(value);
+      this._headers[key] = Array.isArray(value)
+        ? [...value.map(String)]
+        : String(value);
       return this;
     },
   });

package/src/utils/create-response-mock.spec.js

@@ -79,6 +79,22 @@ describe('createResponseMock', function () {
       expect(ret).to.be.eq(res);
       expect(res._headers['num']).to.be.eq('10');
     });
+
+    it('should not stringify an array value', function () {
+      const res = createResponseMock();
+      expect(res._headers['key']).to.be.eq(undefined);
+      const ret = res.setHeader('key', ['foo', 'bar']);
+      expect(ret).to.be.eq(res);
+      expect(res._headers['key']).to.be.eql(['foo', 'bar']);
+    });
+
+    it('should stringify an array elements', function () {
+      const res = createResponseMock();
+      expect(res._headers['key']).to.be.eq(undefined);
+      const ret = res.setHeader('key', [1, 2]);
+      expect(ret).to.be.eq(res);
+      expect(res._headers['key']).to.be.eql(['1', '2']);
+    });
   });
 
   describe('getHeader', function () {