@e22m4u/js-trie-router 0.0.1

package/.c8rc

@@ -0,0 +1,9 @@
+{
+  "all": true,
+  "include": [
+    "src/**/*.js"
+  ],
+  "exclude": [
+    "src/**/*.spec.js"
+  ]
+}

package/.commitlintrc

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

package/.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2
+max_line_length = 80

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit $1

package/.husky/pre-commit

@@ -0,0 +1,5 @@
+npm run lint:fix
+npm run format
+npm run test
+
+git add -A

package/.mocharc.cjs

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

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "bracketSpacing": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "trailingComma": "all",
+  "arrowParens": "avoid"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 e22m4u@yandex.ru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+## @e22m4u/js-trie-router
+
+A pure ES-module of the Node.js HTTP router that uses the
+[Trie](https://en.wikipedia.org/wiki/Trie) for routing.
+
+- Uses [path-to-regexp](https://github.com/pillarjs/path-to-regexp) syntax.
+- Supports path parameters.
+- Parses JSON-body automatically.
+- Parses a query string and the Cookie header.
+- Supports `preHandler` and `postHandler` hooks.
+- Asynchronous request handler.
+
+## Installation
+
+```bash
+npm install @e22m4u/js-trie-router
+```
+
+## Overview
+
+A basic "Hello world." example.
+
+```js
+import http from 'http';
+import {TrieRouter} from '../src/index.js';
+import {HTTP_METHOD} from '../src/route.js';
+
+const server = new http.Server(); // A Node.js HTTP server.
+const router = new TrieRouter();  // A TrieRouter instance.
+
+router.defineRoute({
+  method: HTTP_METHOD.GET,        // Request method.
+  path: '/',                      // Path template like "/user/:id".
+  handler(ctx) {                  // Request handler.
+    return 'Hello world!';
+  },
+});
+
+server.on('request', router.requestHandler);
+server.listen(3000, 'localhost');
+
+// Open in browser http://localhost:3000
+```
+
+### RequestContext
+
+The first parameter of the `Router` handler is the `RequestContext` instance.
+
+- `container: ServiceContainer`
+- `req: IncomingMessage`
+- `res: ServerResponse`
+- `query: ParsedQuery`
+- `headers: ParsedHeaders`
+- `cookie: ParsedCookie`
+
+The `RequestContext` can be destructured.
+
+```js
+router.defineRoute({
+  // ...
+  handler({req, res, query, headers, cookie}) {
+    console.log(req);     // IncomingMessage
+    console.log(res);     // ServerResponse
+    console.log(query);   // {id: '10', ...}
+    console.log(headers); // {'cookie': 'foo=bar', ...}
+    console.log(cookie);  // {foo: 'bar', ...}
+    // ...
+  },
+});
+```
+
+### Sending response
+
+Return values of the `Route` handler will be sent as described below.
+
+| type    | content-type             |
+|---------|--------------------------|
+| `string`  | text/plain               |
+| `number`  | application/json         |
+| `boolean` | application/json         |
+| `object`  | application/json         |
+| `Buffer`  | application/octet-stream |
+| `Stream`  | application/octet-stream |
+
+Here is an example of a JSON response.
+
+```js
+router.defineRoute({
+  // ...
+  handler(ctx) {
+    // sends "application/json"
+    return {foo: 'bar'};
+  },
+});
+```
+
+If the `ServerResponse` has been sent manually, then the return
+value will be ignored.
+
+```js
+router.defineRoute({
+  // ...
+  handler(ctx) {
+    res.statusCode = 404;
+    res.setHeader('content-type', 'text/plain; charset=utf-8');
+    res.end('404 Not Found', 'utf-8');
+  },
+});
+```
+
+## Debug
+
+Set environment variable `DEBUG=jsTrieRouter*` before start.
+
+```bash
+DEBUG=jsPathTrie* npm run test
+```
+
+## Testing
+
+```bash
+npm run test
+```
+
+## License
+
+MIT

package/eslint.config.js

@@ -0,0 +1,34 @@
+import globals from 'globals';
+import eslintJs from '@eslint/js';
+import eslintJsdocPlugin from 'eslint-plugin-jsdoc';
+import eslintMochaPlugin from 'eslint-plugin-mocha';
+import eslintPrettierConfig from 'eslint-config-prettier';
+import eslintChaiExpectPlugin from 'eslint-plugin-chai-expect';
+
+export default [{
+  languageOptions: {
+    globals: {
+      ...globals.node,
+      ...globals.es2021,
+      ...globals.mocha,
+    },
+  },
+  plugins: {
+    'jsdoc': eslintJsdocPlugin,
+    'mocha': eslintMochaPlugin,
+    'chai-expect': eslintChaiExpectPlugin,
+  },
+  rules: {
+    ...eslintJs.configs.recommended.rules,
+    ...eslintPrettierConfig.rules,
+    ...eslintJsdocPlugin.configs['flat/recommended-error'].rules,
+    ...eslintMochaPlugin.configs.flat.recommended.rules,
+    ...eslintChaiExpectPlugin.configs['recommended-flat'].rules,
+    'no-unused-vars': ['error', {'caughtErrors': 'none'}],
+    'jsdoc/require-param-description': 0,
+    'jsdoc/require-returns-description': 0,
+    'jsdoc/require-property-description': 0,
+    'jsdoc/tag-lines': ['error', 'any', {startLines: 1}],
+  },
+  files: ['src/**/*.js'],
+}];

package/examples/cookie-parsing-example.js

@@ -0,0 +1,28 @@
+import http from 'http';
+import {TrieRouter} from '../src/index.js';
+import {HTTP_METHOD} from '../src/route.js';
+
+const router = new TrieRouter();
+
+// регистрация роута для вывода
+// переданных Cookie
+router.defineRoute({
+  method: HTTP_METHOD.GET,
+  path: '/showCookie',
+  handler: ({cookie}) => cookie,
+});
+
+// создаем экземпляр HTTP сервера
+// и подключаем обработчик запросов
+const server = new http.Server();
+server.on('request', router.requestHandler);
+
+// слушаем входящие запросы
+// на указанный адрес и порт
+const port = 3000;
+const host = '0.0.0.0';
+server.listen(port, host, function () {
+  const cyan = '\x1b[36m%s\x1b[0m';
+  console.log(cyan, 'Server listening on port:', port);
+  console.log(cyan, 'Open in browser:', `http://${host}:${port}/showCookie`);
+});

package/examples/params-parsing-example.js

@@ -0,0 +1,28 @@
+import http from 'http';
+import {TrieRouter} from '../src/index.js';
+import {HTTP_METHOD} from '../src/route.js';
+
+const router = new TrieRouter();
+
+// регистрация роута для вывода
+// переданных параметров пути
+router.defineRoute({
+  method: HTTP_METHOD.GET,
+  path: '/showParams/:p1/:p2',
+  handler: ({params}) => params,
+});
+
+// создаем экземпляр HTTP сервера
+// и подключаем обработчик запросов
+const server = new http.Server();
+server.on('request', router.requestHandler);
+
+// слушаем входящие запросы
+// на указанный адрес и порт
+const port = 3000;
+const host = '0.0.0.0';
+server.listen(port, host, function () {
+  const cyan = '\x1b[36m%s\x1b[0m';
+  console.log(cyan, 'Server listening on port:', port);
+  console.log(cyan, 'Open in browser:', `http://${host}:${port}/showParams/foo/bar`);
+});

package/examples/query-parsing-example.js

@@ -0,0 +1,28 @@
+import http from 'http';
+import {TrieRouter} from '../src/index.js';
+import {HTTP_METHOD} from '../src/route.js';
+
+const router = new TrieRouter();
+
+// регистрация роута для вывода
+// переданных "query" параметров
+router.defineRoute({
+  method: HTTP_METHOD.GET,
+  path: '/showQuery',
+  handler: ({query}) => query,
+});
+
+// создаем экземпляр HTTP сервера
+// и подключаем обработчик запросов
+const server = new http.Server();
+server.on('request', router.requestHandler);
+
+// слушаем входящие запросы
+// на указанный адрес и порт
+const port = 3000;
+const host = '0.0.0.0';
+server.listen(port, host, function () {
+  const cyan = '\x1b[36m%s\x1b[0m';
+  console.log(cyan, 'Server listening on port:', port);
+  console.log(cyan, 'Open in browser:', `http://${host}:${port}/showQuery?foo=bar&baz=qux`);
+});

package/examples/uptime-example.js

@@ -0,0 +1,40 @@
+import http from 'http';
+import {TrieRouter} from '../src/index.js';
+import {HTTP_METHOD} from '../src/route.js';
+
+const router = new TrieRouter();
+
+// регистрация роута для вывода
+// времени работы сервера
+router.defineRoute({
+  method: HTTP_METHOD.GET,
+  path: '/',
+  handler() {
+    const uptimeSec = process.uptime();
+    const days = Math.floor(uptimeSec / (60 * 60 * 24));
+    const hours = Math.floor((uptimeSec / (60 * 60)) % 24);
+    const mins = Math.floor((uptimeSec / 60) % 60);
+    const secs = Math.floor(uptimeSec % 60);
+    let res = 'Uptime';
+    if (days) res += ` ${days}d`;
+    if (days || hours) res += ` ${hours}h`;
+    if (days || hours || mins) res += ` ${mins}m`;
+    res += ` ${secs}s`;
+    return res;
+  },
+})
+
+// создаем экземпляр HTTP сервера
+// и подключаем обработчик запросов
+const server = new http.Server();
+server.on('request', router.requestHandler);
+
+// слушаем входящие запросы
+// на указанный адрес и порт
+const port = 3000;
+const host = '0.0.0.0';
+server.listen(port, host, function () {
+  const cyan = '\x1b[36m%s\x1b[0m';
+  console.log(cyan, 'Server listening on port:', port);
+  console.log(cyan, 'Open in browser:', `http://${host}:${port}`);
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@e22m4u/js-trie-router",
+  "version": "0.0.1",
+  "description": "Trie-based router for Node.js",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "lint": "tsc && eslint .",
+    "lint:fix": "tsc && eslint . --fix",
+    "format": "prettier --write \"./src/**/*.{js,ts}\"",
+    "test": "npm run lint && c8 --reporter=text-summary mocha --bail",
+    "test:coverage": "npm run lint && c8 --reporter=text mocha",
+    "prepare": "husky"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/e22m4u/js-trie-router.git"
+  },
+  "keywords": [
+    "router",
+    "trie",
+    "http",
+    "server",
+    "nodejs"
+  ],
+  "author": "e22m4u <e22m4u@yandex.ru>",
+  "license": "MIT",
+  "homepage": "https://github.com/e22m4u/js-trie-router",
+  "devDependencies": {
+    "@commitlint/cli": "~19.4.0",
+    "@commitlint/config-conventional": "~19.2.2",
+    "@eslint/js": "~9.9.0",
+    "@types/chai-as-promised": "^8.0.0",
+    "c8": "~10.1.2",
+    "chai": "~5.1.1",
+    "chai-as-promised": "^8.0.0",
+    "eslint": "~9.9.0",
+    "eslint-config-prettier": "~9.1.0",
+    "eslint-plugin-chai-expect": "~3.1.0",
+    "eslint-plugin-jsdoc": "^50.2.2",
+    "eslint-plugin-mocha": "~10.5.0",
+    "globals": "~15.9.0",
+    "husky": "~9.1.4",
+    "mocha": "~10.7.3",
+    "prettier": "~3.3.3",
+    "typescript": "~5.5.4"
+  },
+  "dependencies": {
+    "@e22m4u/js-format": "^0.1.0",
+    "@e22m4u/js-path-trie": "^0.0.1",
+    "@e22m4u/js-service": "^0.0.12",
+    "debug": "^4.3.6",
+    "http-errors": "^2.0.0",
+    "path-to-regexp": "^7.1.0",
+    "statuses": "^2.0.1"
+  }
+}

package/src/chai.js

@@ -0,0 +1,7 @@
+import * as chaiModule from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+const chai = {...chaiModule};
+
+chaiAsPromised(chai, chai.util);
+
+export const expect = chai.expect;

package/src/hooks/hook-invoker.d.ts

@@ -0,0 +1,25 @@
+import {Route} from '../route.js';
+import {ServerResponse} from 'http';
+import {Service} from '../service.js';
+import {ValueOrPromise} from '../types.js';
+import {HOOK_NAME} from './hook-registry.js';
+
+/**
+ * Hook invoker.
+ */
+export declare class HookInvoker extends Service {
+  /**
+   * Invoke and continue until value received.
+   *
+   * @param route
+   * @param hookName
+   * @param response
+   * @param args
+   */
+  invokeAndContinueUntilValueReceived(
+    route: Route,
+    hookName: HOOK_NAME,
+    response: ServerResponse,
+    ...args: unknown[]
+  ): ValueOrPromise<unknown>;
+}

package/src/hooks/hook-invoker.js

@@ -0,0 +1,104 @@
+import {Route} from '../route.js';
+import {Service} from '../service.js';
+import {Errorf} from '@e22m4u/js-format';
+import {isPromise} from '../utils/index.js';
+import {HOOK_NAME} from './hook-registry.js';
+import {HookRegistry} from './hook-registry.js';
+import {isResponseSent} from '../utils/index.js';
+
+/**
+ * Hook invoker.
+ */
+export class HookInvoker extends Service {
+  /**
+   * Invoke and continue until value received.
+   *
+   * @param {Route} route
+   * @param {string} hookName
+   * @param {import('http').ServerResponse} response
+   * @param {*[]} args
+   * @returns {Promise<*>|*}
+   */
+  invokeAndContinueUntilValueReceived(route, hookName, response, ...args) {
+    if (!route || !(route instanceof Route))
+      throw new Errorf(
+        'The parameter "route" of ' +
+          'the HookInvoker.invokeAndContinueUntilValueReceived ' +
+          'should be a Route instance, but %v given.',
+        route,
+      );
+    if (!hookName || typeof hookName !== 'string')
+      throw new Errorf(
+        'The parameter "hookName" of ' +
+          'the HookInvoker.invokeAndContinueUntilValueReceived ' +
+          'should be a non-empty String, but %v given.',
+        hookName,
+      );
+    if (!Object.values(HOOK_NAME).includes(hookName))
+      throw new Errorf('The hook name %v is not supported.', hookName);
+    if (
+      !response ||
+      typeof response !== 'object' ||
+      Array.isArray(response) ||
+      typeof response.headersSent !== 'boolean'
+    ) {
+      throw new Errorf(
+        'The parameter "response" of ' +
+          'the HookInvoker.invokeAndContinueUntilValueReceived ' +
+          'should be a ServerResponse instance, but %v given.',
+        response,
+      );
+    }
+    // так как хуки роута выполняются
+    // после глобальных, то объединяем
+    // их в данной последовательности
+    const hooks = [
+      ...this.getService(HookRegistry).getHooks(hookName),
+      ...route.hookRegistry.getHooks(hookName),
+    ];
+    // последовательный вызов хуков будет прерван,
+    // если один из них вернет значение (или Promise)
+    // отличное от "undefined" и "null"
+    let result = undefined;
+    for (const hook of hooks) {
+      // если ответ уже был отправлен,
+      // то завершаем обход
+      if (isResponseSent(response)) {
+        result = response;
+        break;
+      }
+      // если выполняется первый хук, или предыдущий
+      // хук вернул пустое значение, то выполняем
+      // следующий, записывая возвращаемое
+      // значение в результат
+      if (result == null) {
+        result = hook(...args);
+      }
+      // если какой-то из предыдущих хуков вернул
+      // Promise, то последующие значения будут
+      // оборачиваться именно им
+      else if (isPromise(result)) {
+        result = result.then(prevVal => {
+          // если ответ уже был отправлен,
+          // то останавливаем выполнение
+          if (isResponseSent(response)) {
+            result = response;
+            return;
+          }
+          // если предыдущий Promise вернул значение
+          // отличное от "undefined" и "null",
+          // то завершаем обход
+          if (prevVal != null) return prevVal;
+          return hook(...args);
+        });
+      }
+      // если предыдущий хук вернул значение
+      // отличное от "undefined" и "null",
+      // то завершаем обход
+      else {
+        break;
+      }
+    }
+    return result;
+  }
+}