expediate 1.0.5 → 1.0.6

package/dist/apis.js

@@ -20,7 +20,363 @@
  */
 'use strict';
 import createRouter from './router.js';
-import { openApiSpec, serializeSpec } from './openapi.js';
+import { openApiSpec, serializeSpec, DESCRIBE_META } from './openapi.js';
+/**
+ * Identity helper for type inference and discoverability when declaring a
+ * {@link ControllerDefinition} in its own file.
+ *
+ * @example
+ * ```ts
+ * export const wikiController = defineController({
+ *   prefix: '/p/:proj/wiki',
+ *   tags: ['Wiki'],
+ *   permission: 'wiki.read',
+ *   GET: { '/tree': (ctx) => listPages(ctx.params.proj) },
+ * });
+ * ```
+ */
+export function defineController(c) { return c; }
+// ---------------------------------------------------------------------------
+// Route collection (controller merge)
+// ---------------------------------------------------------------------------
+/** The five HTTP verbs supported by `apiBuilder`. */
+const VERBS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+/**
+ * Join a controller prefix and a route path into a single normalised pattern.
+ *
+ * Duplicate slashes are collapsed and a trailing slash is stripped (except
+ * for the root path), so `joinPath('/p/:proj/wiki', '/')` → `'/p/:proj/wiki'`.
+ *
+ * Exported for use by `openapi.ts` (multi-definition spec merging); not part
+ * of the public package API.
+ *
+ * @param prefix - The controller prefix (may be empty).
+ * @param path   - The route path relative to the prefix.
+ */
+export function joinPath(prefix, path) {
+    const joined = `/${prefix}/${path}`.replace(/\/+/g, '/');
+    return joined.length > 1 ? joined.replace(/\/$/, '') : joined;
+}
+/**
+ * Compute the specificity score of a route pattern.
+ *
+ * `score = (segment count × 100) − (parameter count × 10)`.  Higher scores
+ * are registered first so that more precise patterns (more segments, fewer
+ * parameters) cannot be shadowed by prefix matches.
+ *
+ * Exported for use by `openapi.ts` (multi-definition spec merging); not part
+ * of the public package API.
+ */
+export function routeScore(path) {
+    const segs = path.split('/').filter(s => s.length > 0);
+    return segs.length * 100 - segs.filter(s => s.startsWith(':')).length * 10;
+}
+/**
+ * Normalise a `permission` declaration (`string | string[]`) to an array,
+ * or `undefined` when absent.
+ *
+ * Exported for use by `openapi.ts` (multi-definition spec merging); not part
+ * of the public package API.
+ */
+export function normalizePermission(permission) {
+    if (permission === undefined)
+        return undefined;
+    return Array.isArray(permission) ? permission : [permission];
+}
+/**
+ * Build the merged route table for a service definition.
+ *
+ * The algorithm (see `docs/api-builder-v2-design.md` §4):
+ * 1. Normalises the root-level route maps into an anonymous controller
+ *    (`prefix: ''`) so v1 single-definition services keep working.
+ * 2. Rewrites each controller route to `joinPath(prefix, path)`.
+ * 3. Concatenates all routes of all controllers, then sorts them by
+ *    decreasing specificity **globally** (the score is computed on the
+ *    joined path, so prefix parameters are accounted for).
+ * 4. **Throws** on a duplicate `(verb, joined path)` pair, naming both
+ *    declaring controllers.
+ * 5. Records per-route provenance (tags, guards, permission) consumed by
+ *    both the request pipeline and `openApiSpec()`.
+ *
+ * Exported for use by `openapi.ts`; not part of the public package API.
+ *
+ * @param service - The service definition to collect routes from.
+ * @returns The merged, globally sorted route table.
+ * @throws  Error on duplicate `(verb, path)` declarations.
+ */
+export function collectRoutes(service) {
+    // 1. Root route maps form an implicit, anonymous controller.
+    const rootController = {
+        prefix: '',
+        GET: service.GET,
+        POST: service.POST,
+        PUT: service.PUT,
+        DELETE: service.DELETE,
+        PATCH: service.PATCH,
+    };
+    const controllers = [rootController, ...(service.controllers ?? [])];
+    /** Human-readable controller name for diagnostics. */
+    const nameOf = (c, index) => index === 0 ? '<root>' : (c.tags?.[0] ?? c.prefix ?? `#${index}`);
+    const routes = [];
+    /** Duplicate detection: `"VERB /joined/path"` → declaring controller name. */
+    const seen = new Map();
+    controllers.forEach((controller, index) => {
+        const controllerName = nameOf(controller, index);
+        const prefix = controller.prefix ?? '';
+        for (const verb of VERBS) {
+            const routeMap = controller[verb];
+            if (!routeMap)
+                continue;
+            for (const [pattern, handler] of Object.entries(routeMap)) {
+                const path = joinPath(prefix, pattern);
+                // 4. Loud failure on duplicates — silent shadowing is unacceptable
+                // with multi-file composition.
+                const dupKey = `${verb} ${path}`;
+                const declarer = seen.get(dupKey);
+                if (declarer !== undefined) {
+                    throw new Error(`apiBuilder: duplicate route ${verb} ${path}\n` +
+                        `  declared by controllers '${declarer}' and '${controllerName}'`);
+                }
+                seen.set(dupKey, controllerName);
+                const meta = handler[DESCRIBE_META];
+                routes.push({
+                    verb,
+                    path,
+                    handler,
+                    meta,
+                    tags: meta?.tags ?? controller.tags,
+                    guards: [
+                        ...(service.guards ?? []),
+                        ...(controller.guards ?? []),
+                        ...(meta?.guards ?? []),
+                    ],
+                    permission: normalizePermission(meta?.permission ?? controller.permission),
+                    controller: controllerName,
+                });
+            }
+        }
+    });
+    // 3. Global specificity sort across all controllers.
+    routes.sort((a, b) => routeScore(b.path) - routeScore(a.path) || b.path.localeCompare(a.path));
+    return routes;
+}
+// ---------------------------------------------------------------------------
+// Request-body validation (JSON Schema subset)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a `$ref` of the form `#/components/schemas/Name` against the
+ * service's schema components, following chained references with a small
+ * depth guard against accidental reference cycles.
+ *
+ * Unknown references resolve to the empty schema `{}` (accepts anything),
+ * mirroring the permissive behaviour of the spec generator.
+ */
+function resolveRef(schema, components) {
+    let current = schema;
+    for (let depth = 0; depth < 16 && current.$ref; depth++) {
+        const match = /^#\/components\/schemas\/(.+)$/.exec(current.$ref);
+        const next = match ? components[match[1]] : undefined;
+        if (!next)
+            return {};
+        current = next;
+    }
+    return current;
+}
+/** Append a field error, keeping the first message reported for each path. */
+function addError(errors, path, message) {
+    const key = path || '$';
+    if (!(key in errors))
+        errors[key] = message;
+}
+/** Join a parent path and a child key into a dotted field-error path. */
+function childPath(path, key) {
+    return path ? `${path}.${key}` : String(key);
+}
+/** Map a runtime value to its JSON Schema type name. */
+function jsonTypeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * Validate a value against a JSON Schema subset, collecting field errors.
+ *
+ * Supported keywords: `type`, `required`, `properties`, `items`, `enum`,
+ * `pattern`, `minLength` / `maxLength`, `minimum` / `maximum`,
+ * `additionalProperties`, `allOf` / `anyOf` / `oneOf`, and `$ref` (resolved
+ * against `components`, i.e. `ServiceDefinition.schemas`).
+ *
+ * Field-error paths are dotted (`name`, `address.city`, `tags.0`); errors on
+ * the value itself are keyed `'$'`.
+ *
+ * Exported for testing; not part of the public package API.
+ *
+ * @param value      - The value to validate.
+ * @param schema     - The schema to validate against.
+ * @param components - Reusable schemas for `$ref` resolution.
+ * @param path       - Current field path (used in recursion; omit at the root).
+ * @param errors     - Accumulator (used in recursion; omit at the root).
+ * @returns A map of field path → first error message (empty when valid).
+ */
+export function validateSchema(value, schema, components = {}, path = '', errors = {}) {
+    const s = resolveRef(schema, components);
+    // ── Combinators ───────────────────────────────────────────────────────────
+    if (s.allOf) {
+        for (const sub of s.allOf)
+            validateSchema(value, sub, components, path, errors);
+    }
+    if (s.anyOf) {
+        const passes = s.anyOf.some(sub => Object.keys(validateSchema(value, sub, components, path, {})).length === 0);
+        if (!passes)
+            addError(errors, path, 'does not match any of the expected schemas (anyOf)');
+    }
+    if (s.oneOf) {
+        const matches = s.oneOf.filter(sub => Object.keys(validateSchema(value, sub, components, path, {})).length === 0).length;
+        if (matches !== 1)
+            addError(errors, path, `must match exactly one schema (oneOf), matched ${matches}`);
+    }
+    // ── type ─────────────────────────────────────────────────────────────────
+    if (s.type !== undefined) {
+        const actual = jsonTypeOf(value);
+        const ok = s.type === 'integer'
+            ? actual === 'number' && Number.isInteger(value)
+            : actual === s.type;
+        if (!ok) {
+            addError(errors, path, `must be of type ${s.type}`);
+            return errors; // further keyword checks would be meaningless
+        }
+    }
+    // ── enum ─────────────────────────────────────────────────────────────────
+    if (s.enum && !s.enum.some(e => e === value ||
+        (typeof e === 'object' && JSON.stringify(e) === JSON.stringify(value)))) {
+        addError(errors, path, `must be one of: ${s.enum.map(e => JSON.stringify(e)).join(', ')}`);
+    }
+    // ── string keywords ──────────────────────────────────────────────────────
+    if (typeof value === 'string') {
+        if (typeof s.pattern === 'string' && !new RegExp(s.pattern).test(value))
+            addError(errors, path, `does not match pattern ${s.pattern}`);
+        if (typeof s.minLength === 'number' && value.length < s.minLength)
+            addError(errors, path, `must be at least ${s.minLength} characters`);
+        if (typeof s.maxLength === 'number' && value.length > s.maxLength)
+            addError(errors, path, `must be at most ${s.maxLength} characters`);
+    }
+    // ── number keywords ──────────────────────────────────────────────────────
+    if (typeof value === 'number') {
+        if (typeof s.minimum === 'number' && value < s.minimum)
+            addError(errors, path, `must be >= ${s.minimum}`);
+        if (typeof s.maximum === 'number' && value > s.maximum)
+            addError(errors, path, `must be <= ${s.maximum}`);
+    }
+    // ── array keywords ───────────────────────────────────────────────────────
+    if (Array.isArray(value) && s.items) {
+        value.forEach((item, i) => validateSchema(item, s.items, components, childPath(path, i), errors));
+    }
+    // ── object keywords ──────────────────────────────────────────────────────
+    if (jsonTypeOf(value) === 'object') {
+        const obj = value;
+        if (s.required) {
+            for (const prop of s.required) {
+                if (obj[prop] === undefined)
+                    addError(errors, childPath(path, prop), 'is required');
+            }
+        }
+        if (s.properties) {
+            for (const [prop, sub] of Object.entries(s.properties)) {
+                if (obj[prop] !== undefined)
+                    validateSchema(obj[prop], sub, components, childPath(path, prop), errors);
+            }
+        }
+        if (s.additionalProperties !== undefined && s.additionalProperties !== true) {
+            const known = new Set(Object.keys(s.properties ?? {}));
+            for (const prop of Object.keys(obj)) {
+                if (known.has(prop))
+                    continue;
+                if (s.additionalProperties === false)
+                    addError(errors, childPath(path, prop), 'unknown property');
+                else
+                    validateSchema(obj[prop], s.additionalProperties, components, childPath(path, prop), errors);
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Validate a request body against a route's declared `requestBody` schema.
+ *
+ * - Missing body + `requestBody.required` → `400`.
+ * - Missing body, not required → skipped.
+ * - Schema violations → `400` with `{ message, fieldErrors }` (see
+ *   {@link validateSchema} for the `fieldErrors` shape).
+ *
+ * The `application/json` content entry is preferred; the first declared
+ * content entry is used as a fallback.
+ *
+ * @throws An {@link ApiError} (`status: 400`) on validation failure.
+ */
+function validateRequestBody(requestBody, body, components) {
+    const content = requestBody.content?.['application/json']
+        ?? Object.values(requestBody.content ?? {})[0];
+    const schema = content?.schema;
+    if (body === undefined || body === null) {
+        if (requestBody.required) {
+            throw {
+                status: 400,
+                data: {
+                    message: 'Request body validation failed',
+                    fieldErrors: { $: 'request body is required' },
+                },
+            };
+        }
+        return;
+    }
+    if (!schema)
+        return;
+    const fieldErrors = validateSchema(body, schema, components);
+    if (Object.keys(fieldErrors).length > 0) {
+        throw {
+            status: 400,
+            data: { message: 'Request body validation failed', fieldErrors },
+        };
+    }
+}
+/**
+ * Validate a handler's return value against the route's declared response
+ * schema for `status`.
+ *
+ * Only acts when the route declares a response for that status with a content
+ * schema (the `application/json` entry is preferred, otherwise the first
+ * declared content entry). A violation means the server is about to emit a body
+ * that breaks its own published contract:
+ *
+ * - `mode === true`  → raise a `500` {@link ApiError} (the off-spec body is not
+ *   sent).
+ * - `mode === 'warn'` → log via `console.warn` and return so the response is
+ *   sent unchanged.
+ *
+ * @throws An {@link ApiError} (`status: 500`) when `mode === true` and the
+ *   value fails validation.
+ */
+function validateResponseBody(responses, status, value, components, mode) {
+    const response = responses[String(status)] ?? responses.default;
+    const content = response?.content?.['application/json']
+        ?? Object.values(response?.content ?? {})[0];
+    const schema = content?.schema;
+    if (!schema)
+        return;
+    const fieldErrors = validateSchema(value, schema, components);
+    if (Object.keys(fieldErrors).length === 0)
+        return;
+    if (mode === 'warn') {
+        console.warn('[apiBuilder] response body validation failed:', fieldErrors);
+        return;
+    }
+    throw {
+        status: 500,
+        data: { message: 'Response body validation failed', fieldErrors },
+    };
+}
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -88,7 +444,7 @@ async function buildModule(service, key) {
 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'];
+        return modules.singleton;
     }
     const key = service.scope(req);
     if (key === null) {
@@ -98,13 +454,11 @@ async function resolveInstance(service, modules, building, req) {
     // 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;
-        });
-    }
+    building[key] ??= buildModule(service, key).then(instance => {
+        modules[key] = instance;
+        delete building[key];
+        return instance;
+    });
     return building[key];
 }
 // ---------------------------------------------------------------------------
@@ -131,7 +485,6 @@ function sendJson(res, data) {
  * @param err - The caught value.
  */
 function sendError(res, err) {
-    // console.error('Api Err', err)
     const e = err;
     const status = e?.status ?? 500;
     if (e?.data !== undefined) {
@@ -190,81 +543,147 @@ function sendError(res, err) {
  *   as a JSON body.
  * - Any other thrown value produces `500 Internal Server Error`.
  *
+ * **Validation:**
+ * - With no `options`, validation follows the {@link ServiceDefinition.validate}
+ *   field.
+ * - With `options`, request validation defaults **on** (cancel via
+ *   `{ validateRequests: false }`) and response validation can be enabled with
+ *   `{ validateResponses: true }` (500 on mismatch) or `{ validateResponses:
+ *   'warn' }` (log only). See {@link ApiBuilderOptions}.
+ *
  * @param service - The service definition (see {@link ServiceDefinition}).
+ * @param options - Optional validation controls (see {@link ApiBuilderOptions}).
+ *   When provided, it overrides the legacy `service.validate` field.
  * @returns A router instance pre-configured with all declared routes.
  */
-export function apiBuilder(service) {
+export function apiBuilder(service, options) {
     const api = createRouter();
     /** Resolved instance cache: populated once setup completes for a given key. */
     const modules = {};
     /** In-flight build promises: deduplicates concurrent keyed instance builds. */
     const building = {};
+    // Merge controllers and root route maps into the global route table.
+    // Throws here — at build time — on duplicate (verb, path) declarations.
+    const routes = collectRoutes(service);
+    // ── Auth binding ─────────────────────────────────────────────────────────
+    // Register the authenticate middleware first so it runs before the 503
+    // readiness guard, every guard, and every handler.
+    if (service.auth?.authenticate)
+        api.use('/', service.auth.authenticate);
+    /**
+     * Default permission check: mirrors `jwtPlugin.requirePermission` semantics
+     * in the `ctx` world — `401` when unauthenticated, `403` when any required
+     * permission is missing from `ctx.user.permissions`.
+     */
+    const defaultCheck = (ctx, required) => {
+        const user = ctx.user;
+        if (!user)
+            throw { status: 401, message: 'Authentication required' };
+        const perms = user.permissions ?? [];
+        if (!required.every(p => perms.includes(p))) {
+            throw {
+                status: 403,
+                message: `Insufficient permissions. Required: ${required.join(', ')}`,
+            };
+        }
+    };
+    const check = service.auth?.check ?? defaultCheck;
+    // ── Validation configuration ─────────────────────────────────────────────
+    // The second argument, when given, is authoritative; otherwise fall back to
+    // the `service.validate` field. Both share the ApiBuilderOptions shape:
+    // request validation defaults ON for an options object, responses default OFF.
+    // A bare `service.validate: true` enables requests only; absent means neither.
+    const validation = options ?? service.validate;
+    const validateRequests = validation === true ||
+        (typeof validation === 'object' && validation.validateRequests !== false);
+    const validateResponses = typeof validation === 'object' ? validation.validateResponses ?? false : false;
+    /** Schema components shared by the validator and the spec generator. */
+    const schemaComponents = {
+        ...service.openapi?.schemas,
+        ...service.schemas,
+    };
     /**
-     * Register all route handlers from a route map for a given HTTP method.
+     * Register a set of collected routes for one HTTP verb.
      *
-     * Each handler:
+     * Each registered handler runs the full pipeline:
      * 1. Resolves the correct service instance (awaiting setup when needed).
-     * 2. Builds an {@link ApiContext} from the incoming request.
-     * 3. Invokes the service method with `(ctx, body)`.
-     * 4. Sends the return value as JSON (or 201 if falsy).
-     * 5. Catches thrown / rejected {@link ApiError} objects and translates them
-     *    into the appropriate HTTP error response.
+     * 2. Builds an {@link ApiContext} from the incoming request
+     *    (`params` aliases `query.route`; `state` starts empty).
+     * 3. Runs `auth.check(ctx, required)` when the route declares a `permission`.
+     * 4. Validates the request body against the declared schema (when enabled).
+     * 5. Runs the guard chain (API → controller → route), shallow-merging any
+     *    returned objects into `ctx.state`.
+     * 6. Invokes the service method with `(ctx, body)`.
+     * 7. Sends the return value as JSON (or 201 if falsy).
+     * 8. Catches thrown / rejected {@link ApiError} objects from any stage 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.
+     * @param verbRoutes - Pre-sorted routes for the verb being registered.
+     * @param register   - Registers a handler on the router for that verb.
      */
-    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) => {
+    function buildRoutes(verbRoutes, register) {
+        for (const route of verbRoutes) {
+            register(route.path, (req, res, next) => {
+                const routeParams = req.queries?.route ?? {};
                 const ctx = {
                     query: {
-                        route: req.queries?.route ?? {},
+                        route: routeParams,
                         url: req.queries?.url ?? {},
                     },
+                    params: routeParams,
                     path: req.path,
                     user: req.user,
+                    state: {},
                 };
                 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, [ctx, 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 => {
-                            // console.error(err)
-                            sendError(res, err);
-                        });
+                    .then(async (instance) => {
+                    // 3. Declarative authorization (opt-in per route / controller).
+                    if (route.permission)
+                        await check(ctx, route.permission);
+                    // 4. Request-body validation from the declared schema.
+                    if (validateRequests && route.meta?.requestBody)
+                        validateRequestBody(route.meta.requestBody, body, schemaComponents);
+                    // 5. Guard chain — outermost first; returned objects accumulate
+                    // into ctx.state for downstream guards and the handler.
+                    for (const guard of route.guards) {
+                        const produced = await guard(ctx, req);
+                        if (produced && typeof produced === 'object')
+                            Object.assign(ctx.state, produced);
                     }
-                    if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
-                        sendJson(res, ret);
-                    else
+                    // 6 + 7. Handler invocation and response conventions.
+                    const val = await route.handler.apply(instance, [ctx, body]);
+                    if (val !== undefined && val !== null && val !== false && val !== 0 && val !== '') {
+                        // Optional response-schema validation (server-contract check).
+                        if (validateResponses && route.meta?.responses)
+                            validateResponseBody(route.meta.responses, 200, val, schemaComponents, validateResponses);
+                        sendJson(res, val);
+                    }
+                    else {
                         res.status(201).end();
+                    }
                 })
                     .catch(err => {
-                    // console.error(err)
+                    // Optional service-level hook: inspect/log and optionally remap the
+                    // error before the default ApiError → HTTP translation.
+                    if (service.onError) {
+                        let override;
+                        try {
+                            override = service.onError(err, ctx, req);
+                        }
+                        catch (hookErr) {
+                            // The hook re-threw → escalate to the surrounding app's error
+                            // channel (router.error() / onError) instead of answering here.
+                            next(hookErr);
+                            return;
+                        }
+                        if (override !== undefined) {
+                            sendError(res, override);
+                            return;
+                        }
+                    }
                     sendError(res, err);
                 });
             });
@@ -272,11 +691,11 @@ export function apiBuilder(service) {
     }
     /** 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));
+        buildRoutes(routes.filter(r => r.verb === 'GET'), (path, h) => api.get(path, h));
+        buildRoutes(routes.filter(r => r.verb === 'POST'), (path, h) => api.post(path, h));
+        buildRoutes(routes.filter(r => r.verb === 'PUT'), (path, h) => api.put(path, h));
+        buildRoutes(routes.filter(r => r.verb === 'DELETE'), (path, h) => api.delete(path, h));
+        buildRoutes(routes.filter(r => r.verb === 'PATCH'), (path, h) => api.patch(path, h));
     }
     if (typeof service.scope !== 'function') {
         // ── Singleton ─────────────────────────────────────────────────────────
@@ -298,7 +717,7 @@ export function apiBuilder(service) {
         // time the first HTTP request can be processed.
         buildModule(service, 'singleton')
             .then(instance => {
-            modules['singleton'] = instance;
+            modules.singleton = instance;
             ready = true;
             registerAllRoutes();
         })
@@ -331,8 +750,7 @@ export function apiBuilder(service) {
             ? 'application/yaml; charset=utf-8'
             : 'application/json; charset=utf-8';
         return function (_req, res) {
-            if (!cached)
-                cached = serializeSpec(openApiSpec(service, opts), format);
+            cached ??= serializeSpec(openApiSpec(service, opts), format);
             res.setHeader('Content-Type', contentType);
             res.end(cached);
         };