expediate 1.0.4 → 1.0.6

package/dist/apis.js

@@ -19,40 +19,394 @@
  * DEALINGS IN THE SOFTWARE.
  */
 'use strict';
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.apiBuilder = apiBuilder;
-const router_js_1 = __importDefault(require("./router.js"));
+import createRouter from './router.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
 // ---------------------------------------------------------------------------
 /**
- * Instantiate a new service module for the given scope `key`.
+ * 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 state object (or use `{ $key: key }`
- *    when `data` is not defined).
+ * 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`.
- * 3. **`setup()`** — called once on the new instance; may be async.
+ *    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 fully initialised service instance.
+ * @returns A Promise resolving to a fully initialised service instance.
  */
-function buildModule(service, key) {
+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`.
-    // BUG FIX: the original used arrow functions `() => method.apply(module, arguments)`.
-    // Arrow functions do NOT have their own `arguments` object — they inherit it
-    // from the enclosing `buildModule` scope (which holds `(service, key)`).
-    // Any arguments forwarded to the method were therefore silently dropped.
-    // Corrected to a regular function expression that captures its own `arguments`
-    // via a rest parameter spread.
+    // 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];
@@ -61,8 +415,10 @@ function buildModule(service, key) {
             };
         }
     }
+    // Await setup so that async initialisation (DB connections, config fetches,
+    // etc.) completes before the instance is considered ready.
     if (service.setup)
-        service.setup.apply(instance, []);
+        await service.setup.apply(instance, []);
     return instance;
 }
 /**
@@ -70,32 +426,40 @@ function buildModule(service, key) {
  *
  * Instance lifecycle by scope:
  * - **Singleton** (`scope` absent): always returns `modules['singleton']`.
- * - **Keyed** (`scope` returns a string): look up `modules[key]`; create and
- *   cache a new instance on first access.
- * - **Ephemeral** (`scope` returns `null`): create a fresh instance every time;
- *   never cached.
+ *   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 instance cache (mutated when a new keyed instance is created).
- * @param req     - The incoming request.
- * @returns The service instance to use for this 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.
  */
-function resolveInstance(service, modules, req) {
+async function resolveInstance(service, modules, building, req) {
     if (typeof service.scope !== 'function') {
-        // Singleton — always the same global instance.
-        return modules['singleton'];
+        // Singleton — routes only run after setup is complete, so this is safe.
+        return modules.singleton;
     }
-    // BUG FIX: the original called `service.key(req)` which does not exist on
-    // the service definition. The correct method is `service.scope(req)`.
     const key = service.scope(req);
     if (key === null) {
         // Ephemeral — create a fresh, uncached instance for every request.
         return buildModule(service, null);
     }
-    // Keyed — retrieve from cache or create and store.
-    if (!modules[key])
-        modules[key] = buildModule(service, key);
-    return modules[key];
+    // Keyed — retrieve from resolved cache or initiate (and deduplicate) a build.
+    if (modules[key])
+        return modules[key];
+    building[key] ??= buildModule(service, key).then(instance => {
+        modules[key] = instance;
+        delete building[key];
+        return instance;
+    });
+    return building[key];
 }
 // ---------------------------------------------------------------------------
 // Response helpers
@@ -107,9 +471,6 @@ function resolveInstance(service, modules, req) {
  * @param data - Any JSON-serialisable value.
  */
 function sendJson(res, data) {
-    // BUG FIX: the original called `res.send(JSON.stringify(val))` without
-    // setting a `Content-Type` header. Clients had no way to detect that the
-    // response body was JSON. Corrected by setting the header explicitly.
     res.setHeader('Content-Type', 'application/json; charset=utf-8');
     res.send(JSON.stringify(data));
 }
@@ -117,7 +478,7 @@ function sendJson(res, data) {
  * Translate a caught error (thrown or rejected by a service method) into an
  * HTTP error response.
  *
- * Expected shape: `{ httpStatus?, data?, message? }` (see {@link ApiError}).
+ * 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.
@@ -125,7 +486,7 @@ function sendJson(res, data) {
  */
 function sendError(res, err) {
     const e = err;
-    const status = e?.httpStatus ?? 500;
+    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));
@@ -148,11 +509,25 @@ function sendError(res, err) {
  * 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
+ * 1. `ctx`  — an {@link ApiContext} object containing `ctx.query.route`
+ *    (named route parameters), `ctx.query.url` (URL query-string parameters),
+ *    `ctx.path` (the request path), and `ctx.user` (optional auth data).
+ * 2. `body` — the parsed request body from `req.body` (requires a
  *    body-parsing middleware such as `json()` to run first).
  *
  * **Return values:**
@@ -162,89 +537,225 @@ function sendError(res, err) {
  *   `Promise` resolving to one → `201 No Content` (useful for mutations).
  *
  * **Error handling:**
- * - Throwing or rejecting with `{ httpStatus, message }` sends the
+ * - Throwing or rejecting with `{ status, message }` sends the
  *   corresponding HTTP error.
- * - Throwing or rejecting with `{ httpStatus, data }` sends the `data` object
+ * - Throwing or rejecting with `{ status, data }` sends the `data` object
  *   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.
  */
-function apiBuilder(service) {
-    const api = (0, router_js_1.default)();
+export function apiBuilder(service, options) {
+    const api = createRouter();
+    /** Resolved instance cache: populated once setup completes for a given key. */
     const modules = {};
-    // Pre-build the singleton instance eagerly so `setup()` runs at startup.
-    if (typeof service.scope !== 'function')
-        // BUG FIX: the original called `buildModule(service)` without a key,
-        // passing `undefined` to `data()` and leaving `$key` as `undefined`.
-        // Corrected to pass `'singleton'` as the canonical key.
-        modules['singleton'] = buildModule(service, 'singleton');
+    /** 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);
     /**
-     * Register all route handlers from a route map for a given HTTP method.
+     * 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 a set of collected routes for one HTTP verb.
      *
-     * Each handler:
-     * 1. Resolves the correct service instance (singleton / keyed / ephemeral).
-     * 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.
+     * 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
+     *    (`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) => {
-                const params = req.params;
+    function buildRoutes(verbRoutes, register) {
+        for (const route of verbRoutes) {
+            register(route.path, (req, res, next) => {
+                const routeParams = req.queries?.route ?? {};
+                const ctx = {
+                    query: {
+                        route: routeParams,
+                        url: req.queries?.url ?? {},
+                    },
+                    params: routeParams,
+                    path: req.path,
+                    user: req.user,
+                    state: {},
+                };
                 const body = req.body;
-                try {
-                    const instance = resolveInstance(service, modules, req);
-                    const ret = method.apply(instance, [params, body]);
-                    if (ret instanceof Promise) {
-                        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));
+                // Await instance resolution (no-op microtask for singletons; may
+                // trigger async buildModule for keyed / ephemeral instances).
+                resolveInstance(service, modules, building, req)
+                    .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);
+                    }
+                    // 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 {
-                        if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
-                            sendJson(res, ret);
-                        else
-                            res.status(201).end();
+                        res.status(201).end();
+                    }
+                })
+                    .catch(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;
+                        }
                     }
-                }
-                catch (err) {
                     sendError(res, err);
-                }
+                });
             });
         }
     }
-    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));
+    /** Convenience wrapper to register routes for all five HTTP verbs. */
+    function registerAllRoutes() {
+        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 ─────────────────────────────────────────────────────────
+        // 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 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) {
+            cached ??= serializeSpec(openApiSpec(service, opts), format);
+            res.setHeader('Content-Type', contentType);
+            res.end(cached);
+        };
+    };
     return api;
 }
-exports.default = apiBuilder;
+export default apiBuilder;
 //# sourceMappingURL=apis.js.map