@e22m4u/js-trie-router 0.4.0 → 0.4.2

package/.mocharc.cjs

@@ -1,4 +1,5 @@
 module.exports = {
   extension: ['js'],
   spec: 'src/**/*.spec.js',
+  require: ['./mocha-setup.js'],
 }

package/README.md

@@ -53,15 +53,15 @@ const {TrieRouter} = require('@e22m4u/js-trie-router');
 
 ```js
 import http from 'http';
-import {TrieRouter} from '@e22m4u/js-trie-router';
+import {TrieRouter, HttpMethod} from '@e22m4u/js-trie-router';
 
 const server = new http.Server(); // создание экземпляра HTTP сервера
 const router = new TrieRouter();  // создание экземпляра роутера
 
 router.defineRoute({
-  method: 'GET',                  // метод запроса "GET", "POST" и т.д.
-  path: '/',                      // шаблон пути, пример "/user/:id"
-  handler(ctx) {                  // обработчик маршрута
+  method: HttpMethod.GET,   // метод запроса "GET", "POST" и т.д.
+  path: '/',                // шаблон пути, пример "/user/:id"
+  handler(ctx) {            // обработчик маршрута
     return 'Hello world!';
   },
 });
@@ -72,46 +72,55 @@ server.listen(3000, 'localhost');             // прослушивание за
 // Open in browser http://localhost:3000
 ```
 
+*i. Для указания метода запроса рекомендуется использовать
+константу `HttpMethod`, чтобы избежать опечаток.*
+
 ### Контекст запроса
 
 Первый параметр обработчика маршрута принимает экземпляр класса
 `RequestContext` с набором свойств, содержащих разобранные
 данные входящего запроса.
 
-- `cont: ServiceContainer` экземпляр [сервис-контейнера](https://npmjs.com/package/@e22m4u/js-service)
-- `req: IncomingMessage` нативный поток входящего запроса
-- `res: ServerResponse` нативный поток ответа сервера
-- `params: ParsedParams` объект ключ-значение с параметрами пути
-- `query: ParsedQuery` объект ключ-значение с параметрами строки запроса
-- `headers: ParsedHeaders` объект ключ-значение с заголовками запроса 
-- `cookies: ParsedCookies` объект ключ-значение разобранного заголовка `Cookie`
-- `method: string` метод запроса в верхнем регистре, например `GET`, `POST` и т.д.
-- `path: string` путь включающий строку запроса, например `/myPath?foo=bar`
-- `pathname: string` путь запроса, например `/myPath`
-- `body: unknown` тело запроса
-- `meta: object` мета-данные из определения маршрута
+- `params: ParsedParams` объект ключ-значение с параметрами пути;
+- `query: ParsedQuery` объект ключ-значение с параметрами строки запроса;
+- `headers: ParsedHeaders` объект ключ-значение с заголовками запроса;
+- `cookies: ParsedCookies` объект ключ-значение разобранного заголовка `Cookie`;
+- `method: HttpMethod` метод запроса в верхнем регистре, например `GET`, `POST` и т.д.;
+- `path: string` путь включающий строку запроса, например `/myPath?foo=bar`;
+- `pathname: string` путь запроса, например `/myPath`;
+- `body: unknown` тело запроса;
+
+Дополнительные свойства:
+
+- `container: ServiceContainer` экземпляр [сервис-контейнера](https://npmjs.com/package/@e22m4u/js-service);
+- `request: IncomingMessage` нативный поток входящего запроса;
+- `response: ServerResponse` нативный поток ответа сервера;
+- `route: Route` экземпляр текущего маршрута;
+- `meta: object` геттер для доступа к метаданным маршрута (`route.meta`);
 
 Пример доступа к контексту из обработчика маршрута.
 
 ```js
 router.defineRoute({
-  method: 'GET',
+  method: HttpMethod.GET,
   path: '/users/:id',
   meta: {prop: 'value'},
   handler(ctx) {
     // GET /users/10?include=city
     // Cookie: foo=bar; baz=qux;
-    console.log(ctx.req);      // IncomingMessage
-    console.log(ctx.res);      // ServerResponse
-    console.log(ctx.params);   // {id: 10}
-    console.log(ctx.query);    // {include: 'city'}
-    console.log(ctx.headers);  // {cookie: 'foo=bar; baz=qux;'}
-    console.log(ctx.cookies);  // {foo: 'bar', baz: 'qux'}
-    console.log(ctx.method);   // "GET"
-    console.log(ctx.path);     // "/users/10?include=city"
-    console.log(ctx.pathname); // "/users/10"
-    console.log(ctx.meta);     // {prop: 'value'}
-    console.log(ctx.cont);     // ServiceContainer
+    console.log(ctx.params);    // {id: 10}
+    console.log(ctx.query);     // {include: 'city'}
+    console.log(ctx.headers);   // {cookie: 'foo=bar; baz=qux;'}
+    console.log(ctx.cookies);   // {foo: 'bar', baz: 'qux'}
+    console.log(ctx.method);    // "GET"
+    console.log(ctx.path);      // "/users/10?include=city"
+    console.log(ctx.pathname);  // "/users/10"
+    // дополнительные свойства
+    console.log(ctx.container); // ServiceContainer
+    console.log(ctx.request);   // IncomingMessage
+    console.log(ctx.response);  // ServerResponse
+    console.log(ctx.route);     // Route
+    console.log(ctx.meta);      // {prop: 'value'}
     // ...
   },
 });
@@ -150,10 +159,13 @@ router.defineRoute({     // регистрация маршрута
 ```js
 router.defineRoute({
   // ...
-  handler(ctx) {
-    ctx.res.statusCode = 404;
-    ctx.res.setHeader('content-type', 'text/plain; charset=utf-8');
-    ctx.res.end('404 Not Found', 'utf-8');
+  // для доступа к свойству `response` (ServerResponse)
+  // используется деструктуризация контекста запроса,
+  // что аналогично записи handler(ctx) { ctx.response ... 
+  handler({response}) {
+    response.statusCode = 404;
+    response.setHeader('content-type', 'text/plain; charset=utf-8');
+    response.end('404 Not Found', 'utf-8');
   },
 });
 ```
@@ -257,12 +269,13 @@ router.addPostHandler((ctx, data) => {
 быть схемы для валидации данных, правила доступа или настройки кэширования.
 Для этой цели определение маршрута поддерживает необязательное свойство `meta`.
 
-Маршрутизатор лишь обеспечивает передачу мета-данных в контекст запроса,
-откуда его могут прочитать обработчики или хуки.
+Маршрутизатор передает в контекст запроса найденный маршрут. Контекст,
+в свою очередь, предоставляет доступ к мета-данным этого маршрута через
+свойство `meta`, откуда их могут прочитать обработчики или хуки.
 
 ```js
 import http from 'http';
-import {TrieRouter} from '@e22m4u/js-trie-router';
+import {TrieRouter, HttpMethod} from '@e22m4u/js-trie-router';
 
 const server = new http.Server();
 const router = new TrieRouter();
@@ -275,7 +288,7 @@ router.addPreHandler((ctx) => {
 });
 
 router.defineRoute({
-  method: 'GET',
+  method: HttpMethod.GET,
   path: '/',
   meta: {foo: 'bar'}, // <= мета-данные
   handler(ctx) {