expediate 1.0.5 → 1.0.6

package/docs/wiki.json

@@ -0,0 +1,123 @@
+{
+  "name": "expediate",
+  "title": "Expediate — Wiki",
+  "host": "expediate.axfab.net",
+  "npm": "expediate",
+  "github": "axfab/expediate",
+  "image": "img/expediate.png",
+  "colorHue": 55,
+  "top": [
+    {
+      "id": "index.html",
+      "label": "Home",
+      "src": "README.md",
+      "icon": "<path d=\"M8 1a7 7 0 100 14A7 7 0 008 1zM7 4h2v2H7V4zm0 3h2v5H7V7z\"/>",
+      "type": "SoftwareApplication",
+      "title": "Expediate — Routing framework for Node.js",
+      "description": "A lightweight, zero-dependency TypeScript HTTP routing framework for Node.js."
+    }
+  ],
+  "docs": [
+    {
+      "id": "api-builder.html",
+      "label": "API Builder",
+      "src": "docs/api-builder.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "API Builder — Expediate",
+      "description": ""
+    },
+    {
+      "id": "body-parsing.html",
+      "label": "Body request parsing",
+      "src": "docs/body-parsing.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "Body parsing — Expediate",
+      "description": ""
+    },
+    {
+      "id": "errors.html",
+      "label": "Error handling",
+      "src": "docs/errors.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "Error handling — Expediate",
+      "description": ""
+    },
+    {
+      "id": "git.html",
+      "label": "Git by http",
+      "src": "docs/git.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "Git-http — Expediate",
+      "description": ""
+    },
+    {
+      "id": "jwt-auth.html",
+      "label": "JWT auth",
+      "src": "docs/jwt-auth.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "JWT auth — Expediate",
+      "description": ""
+    },
+    {
+      "id": "middleware.html",
+      "label": "Middleware",
+      "src": "docs/middleware.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "Middleware — Expediate",
+      "description": ""
+    },
+    {
+      "id": "router.html",
+      "label": "Router",
+      "src": "docs/router.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "Router — Expediate",
+      "description": ""
+    },
+    {
+      "id": "static.html",
+      "label": "Static",
+      "src": "docs/static.md",
+      "icon": "<path d=\"M2 2h4v4H2V2zm0 8h4v4H2v-4zm8-8h4v4h-4V2zm0 8h4v4h-4v-4z\"/>",
+      "type": "TechArticle",
+      "title": "Static — Expediate",
+      "description": ""
+    }
+  ],
+  "bottom": [
+    {
+      "id": "license.html",
+      "label": "License",
+      "src": "LICENSE",
+      "icon": "<path d=\"M8 0a8 8 0 100 16A8 8 0 008 0zM4.5 7.5h7v1h-7v-1z\"/>",
+      "type": "WebPage",
+      "title": "MIT License — Expediate",
+      "description": "Expediate is released under the MIT License — free to use, modify, and distribute."
+    },
+    {
+      "id": "contributing.html",
+      "label": "Contributing",
+      "src": "CONTRIBUTING.md",
+      "icon": "<path d=\"M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38v-1.33c-2.23.48-2.7-1.07-2.7-1.07-.36-.92-.88-1.17-.88-1.17-.72-.49.05-.48.05-.48.8.06 1.22.82 1.22.82.7 1.2 1.85.86 2.3.65.07-.51.27-.86.5-1.06-1.78-.2-3.65-.89-3.65-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82a7.67 7.67 0 012 0c1.53-1.03 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48v2.2c0 .21.15.46.55.38A8 8 0 0016 8c0-4.42-3.58-8-8-8z\"/>",
+      "type": "WebPage",
+      "title": "Contributing — Expediate",
+      "description": "How to contribute to expediate: local setup, coding standards, and pull request guidelines."
+    }
+  ],
+  "extra": [
+    {
+      "id": "claude.html",
+      "label": "Claude instructions",
+      "src": "CLAUDE.md",
+      "title": "Claude instructions — Expediate",
+      "description": "Documentation for the npm expediate package"
+    }
+  ]
+}

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "expediate",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Web framework to create complete HTTP server.",
   "type": "module",
   "main": "dist/cjs/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist",
+    "dist/",
+    "docs/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "LICENSE",
     "README.md"
   ],
@@ -34,9 +37,22 @@
   ],
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist', {recursive:true,force:true})\"",
-    "build": "tsc && node scripts/build-cjs.cjs",
-    "test": "node --import tsx --test 'tests/*.test.ts'"
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc",
+    "build:cjs": "node scripts/build-cjs.cjs",
+    "test": "node --import tsx --test 'tests/*.test.ts'",
+    "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude='tests/**' 'tests/*.test.ts'",
+    "fuzz": "node --import tsx --test 'tests/*.fuzz.test.ts'",
+    "bench": "npm run bench --workspace benchmarks",
+    "bench:check": "npm run bench:check --workspace benchmarks",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepack": "npm run lint && npm run test && npm run build"
   },
+  "workspaces": [
+    "benchmarks",
+    "loadtest"
+  ],
   "homepage": "https://expediate.axfab.net/",
   "repository": {
     "type": "git",
@@ -45,11 +61,17 @@
   "author": "Fabien Bavent <fabien.bavent@gmail.com>",
   "contributors": [],
   "license": "MIT",
-  "dependencies": {},
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "esbuild": "^0.27.4",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.4",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.5.0",
+    "fast-check": "^3.23.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "tsx": "^4.21.0"
+    "typescript-eslint": "^8.61.1"
+  },
+  "engines": {
+    "node": ">=18.20.0"
   }
 }

package/dist/cjs/apis.js

@@ -1,327 +0,0 @@
-/* Copyright 2021 Fabien Bavent
- *
- * 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.
- */
-'use strict';
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.apiBuilder = apiBuilder;
-const router_js_1 = require("./router.js");
-const openapi_js_1 = require("./openapi.js");
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-/**
- * Instantiate a new service module for the given scope `key` and await its
- * setup lifecycle hook.
- *
- * The lifecycle is:
- * 1. **`data(key)`** — create the initial data object (`Partial<TInstance>`);
- *    methods are mixed in next to complete the shape.
- * 2. **Mix in methods** — each entry in `service.methods` is copied onto the
- *    instance as a regular function bound to `this = instance`.
- * 3. **`await setup()`** — if `setup` returns a `Promise`, it is fully
- *    awaited before the instance is returned.  Any rejection propagates to
- *    the caller.
- *
- * @param service - The service definition.
- * @param key     - The scope key (`'singleton'`, `null`, or a session ID).
- * @returns A Promise resolving to a fully initialised service instance.
- */
-async function buildModule(service, key) {
-    // `data()` returns Partial<TInstance>; methods are mixed in below to complete
-    // the instance shape.  The cast is intentional and safe — by the time this
-    // function returns the instance IS a full TInstance.
-    const instance = service.data
-        ? service.data(key)
-        : { $key: key };
-    // Mix service methods into the instance, bound to `this = instance`.
-    // Regular function expressions are used (not arrow functions) so that each
-    // method has its own `arguments` object and `this` binding works correctly.
-    if (service.methods) {
-        for (const methodName of Object.keys(service.methods)) {
-            const method = service.methods[methodName];
-            instance[methodName] = function (...args) {
-                return method.apply(instance, args);
-            };
-        }
-    }
-    // Await setup so that async initialisation (DB connections, config fetches,
-    // etc.) completes before the instance is considered ready.
-    if (service.setup)
-        await service.setup.apply(instance, []);
-    return instance;
-}
-/**
- * Resolve the correct service instance for an incoming request.
- *
- * Instance lifecycle by scope:
- * - **Singleton** (`scope` absent): always returns `modules['singleton']`.
- *   The singleton is guaranteed to be fully initialised before routes run,
- *   so this path is synchronous within the async wrapper.
- * - **Keyed** (`scope` returns a string): look up `modules[key]`; on first
- *   access, build and cache the instance (in-flight builds for the same key
- *   are deduplicated via `building` to avoid concurrent double-builds).
- * - **Ephemeral** (`scope` returns `null`): create a fresh, uncached instance
- *   for every request.
- *
- * @param service  - The service definition.
- * @param modules  - The resolved-instance cache (mutated on first keyed access).
- * @param building - In-flight build-promise cache; prevents duplicate builds
- *                   for the same key under concurrent requests.
- * @param req      - The incoming request.
- * @returns A Promise resolving to the service instance for this request.
- */
-async function resolveInstance(service, modules, building, req) {
-    if (typeof service.scope !== 'function') {
-        // Singleton — routes only run after setup is complete, so this is safe.
-        return modules['singleton'];
-    }
-    const key = service.scope(req);
-    if (key === null) {
-        // Ephemeral — create a fresh, uncached instance for every request.
-        return buildModule(service, null);
-    }
-    // Keyed — retrieve from resolved cache or initiate (and deduplicate) a build.
-    if (modules[key])
-        return modules[key];
-    if (!building[key]) {
-        building[key] = buildModule(service, key).then(instance => {
-            modules[key] = instance;
-            delete building[key];
-            return instance;
-        });
-    }
-    return building[key];
-}
-// ---------------------------------------------------------------------------
-// Response helpers
-// ---------------------------------------------------------------------------
-/**
- * Send a JSON response with the appropriate `Content-Type` header.
- *
- * @param res  - The outgoing response.
- * @param data - Any JSON-serialisable value.
- */
-function sendJson(res, data) {
-    res.setHeader('Content-Type', 'application/json; charset=utf-8');
-    res.send(JSON.stringify(data));
-}
-/**
- * Translate a caught error (thrown or rejected by a service method) into an
- * HTTP error response.
- *
- * Expected shape: `{ status?, data?, message? }` (see {@link ApiError}).
- * Any other thrown value is treated as an opaque 500 Internal Server Error.
- *
- * @param res - The outgoing response.
- * @param err - The caught value.
- */
-function sendError(res, err) {
-    const e = err;
-    const status = e?.status ?? 500;
-    if (e?.data !== undefined) {
-        res.setHeader('Content-Type', 'application/json; charset=utf-8');
-        res.status(status).send(JSON.stringify(e.data));
-    }
-    else {
-        res.status(status).send(e?.message ?? 'Internal error');
-    }
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Build an Express-compatible router from a service definition object.
- *
- * The returned router is suitable for mounting via `app.use()`:
- *
- * ```ts
- * import myService from './my-service.js';
- *
- * app.use('/api', apiBuilder(myService));
- * ```
- *
- * **Singleton setup lifecycle:**
- * When `service.scope` is absent the service is a singleton.  The framework
- * pre-builds the instance eagerly and registers a **503 Service not ready**
- * guard middleware on the router immediately.  Route handlers are registered
- * only once `setup()` resolves (or immediately, for sync setup).  Any request
- * that arrives before setup completes receives a 503 response.
- *
- * **Keyed / ephemeral setup lifecycle:**
- * Route handlers are registered immediately.  For each request,
- * `resolveInstance()` is awaited inside the handler, so `setup()` is always
- * complete before the service method is invoked.
- *
- * **Route handlers** declared in `service.GET`, `service.POST`, etc. are
- * called with `this` bound to the service instance.  They receive two
- * arguments:
- * 1. `params` — merged route + query-string parameters from `req.params`.
- * 2. `body`   — the parsed request body from `req.body` (requires a
- *    body-parsing middleware such as `json()` to run first).
- *
- * **Return values:**
- * - A **truthy value** (or a `Promise` resolving to one) → serialised as JSON
- *   with status `200 OK`.
- * - A **falsy value** (`undefined`, `null`, `false`, `0`, `''`) or a
- *   `Promise` resolving to one → `201 No Content` (useful for mutations).
- *
- * **Error handling:**
- * - Throwing or rejecting with `{ status, message }` sends the
- *   corresponding HTTP error.
- * - Throwing or rejecting with `{ status, data }` sends the `data` object
- *   as a JSON body.
- * - Any other thrown value produces `500 Internal Server Error`.
- *
- * @param service - The service definition (see {@link ServiceDefinition}).
- * @returns A router instance pre-configured with all declared routes.
- */
-function apiBuilder(service) {
-    const api = (0, router_js_1.default)();
-    /** Resolved instance cache: populated once setup completes for a given key. */
-    const modules = {};
-    /** In-flight build promises: deduplicates concurrent keyed instance builds. */
-    const building = {};
-    /**
-     * Register all route handlers from a route map for a given HTTP method.
-     *
-     * Each handler:
-     * 1. Resolves the correct service instance (awaiting setup when needed).
-     * 2. Invokes the service method with `(params, body)`.
-     * 3. Sends the return value as JSON (or 201 if falsy).
-     * 4. Catches thrown / rejected {@link ApiError} objects and translates them
-     *    into the appropriate HTTP error response.
-     *
-     * @param routeMap - Map of path patterns to service methods (`undefined` = skip).
-     * @param register - Registers a handler on the router for the current HTTP method.
-     */
-    function buildRoutes(routeMap, register) {
-        if (!routeMap)
-            return;
-        // Sort routes by decreasing specificity so that more precise patterns
-        // (more segments, fewer parameters) are registered first in the router.
-        // Without this, a plain path like '/items' would match '/items/1' as a
-        // prefix and steal requests intended for '/items/:id'.
-        // Specificity = (segment count * 100) - (parameter count * 10).
-        const sortedPaths = Object.keys(routeMap).sort((a, b) => {
-            const score = (p) => {
-                const segs = p.split('/').filter(s => s.length > 0);
-                return segs.length * 100 - segs.filter(s => s.startsWith(':')).length * 10;
-            };
-            return score(b) - score(a) || b.localeCompare(a);
-        });
-        for (const path of sortedPaths) {
-            const method = routeMap[path];
-            register(path, (req, res) => {
-                const params = req.params;
-                const body = req.body;
-                // Await instance resolution (no-op microtask for singletons; may
-                // trigger async buildModule for keyed / ephemeral instances).
-                resolveInstance(service, modules, building, req)
-                    .then(instance => {
-                    const ret = method.apply(instance, [params, body]);
-                    if (ret instanceof Promise) {
-                        return ret
-                            .then(val => {
-                            if (val !== undefined && val !== null && val !== false && val !== 0 && val !== '')
-                                sendJson(res, val);
-                            else
-                                res.status(201).end();
-                        })
-                            .catch(err => sendError(res, err));
-                    }
-                    if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
-                        sendJson(res, ret);
-                    else
-                        res.status(201).end();
-                })
-                    .catch(err => sendError(res, err));
-            });
-        }
-    }
-    /** Convenience wrapper to register routes for all five HTTP verbs. */
-    function registerAllRoutes() {
-        buildRoutes(service.GET, (path, h) => api.get(path, h));
-        buildRoutes(service.POST, (path, h) => api.post(path, h));
-        buildRoutes(service.PUT, (path, h) => api.put(path, h));
-        buildRoutes(service.DELETE, (path, h) => api.delete(path, h));
-        buildRoutes(service.PATCH, (path, h) => api.patch(path, h));
-    }
-    if (typeof service.scope !== 'function') {
-        // ── Singleton ─────────────────────────────────────────────────────────
-        // Register a "not ready" guard first so that requests arriving while
-        // setup is in progress receive 503 rather than 404.
-        let ready = false;
-        api.use('/', (_req, res, next) => {
-            if (!ready) {
-                res.statusCode = 503;
-                res.end('Service not ready');
-                return;
-            }
-            next();
-        });
-        // Build the singleton asynchronously, then flip the guard and register
-        // routes.  Even for synchronous setup() functions, buildModule() is async
-        // (it uses await internally), so route registration happens in a microtask
-        // that runs before any I/O callbacks — routes are always in place by the
-        // time the first HTTP request can be processed.
-        buildModule(service, 'singleton')
-            .then(instance => {
-            modules['singleton'] = instance;
-            ready = true;
-            registerAllRoutes();
-        })
-            .catch(err => {
-            // setup() rejected — log the error; the guard permanently returns 503.
-            console.error('[apiBuilder] singleton setup() rejected:', err);
-        });
-    }
-    else {
-        // ── Keyed / ephemeral ─────────────────────────────────────────────────
-        // Register routes immediately.  Each handler awaits resolveInstance(),
-        // which in turn awaits buildModule() for first-time keyed instances.
-        registerAllRoutes();
-    }
-    // ── OpenAPI introspection ──────────────────────────────────────────────────
-    /**
-     * Generate an OpenAPI 3.1.0 document from the service definition.
-     * Delegates to {@link openApiSpec} from `openapi.ts`.
-     */
-    api.spec = function (opts) {
-        return (0, openapi_js_1.openApiSpec)(service, opts);
-    };
-    /**
-     * Return a middleware handler that serves the OpenAPI spec as JSON or YAML.
-     * The spec is generated once and cached on the first call to the returned handler.
-     */
-    api.specHandler = function (opts, format = 'json') {
-        let cached = null;
-        const contentType = format === 'yaml'
-            ? 'application/yaml; charset=utf-8'
-            : 'application/json; charset=utf-8';
-        return function (_req, res) {
-            if (!cached)
-                cached = (0, openapi_js_1.serializeSpec)((0, openapi_js_1.openApiSpec)(service, opts), format);
-            res.setHeader('Content-Type', contentType);
-            res.end(cached);
-        };
-    };
-    return api;
-}
-exports.default = apiBuilder;