expediate 1.0.4 → 1.0.6

package/dist/apis.d.ts

@@ -1,16 +1,87 @@
-import type { RouterRequest, Router } from './router.js';
+import type { RouterRequest, RouterResponse, Router, Middleware } from './router.js';
+import './openapi.js';
+import type { SpecOptions, SpecFormat, OpenApiDocument, OperationMeta, JsonSchema } from './openapi.js';
+/**
+ * Context object passed as the first argument to every service method handler.
+ *
+ * Replaces the old flat `params` map: route parameters, URL query parameters,
+ * and other request-scoped data are now namespaced to avoid collisions and to
+ * make each data source explicit.
+ *
+ * @example
+ * ```ts
+ * GET: {
+ *   '/items/:id': function (ctx: ApiContext) {
+ *     const id  = ctx.params.id;        // ':id' from the path pattern
+ *     const fmt = ctx.query.url.format; // '?format=json' from the query string
+ *     return getItem(id, fmt);
+ *   },
+ * }
+ * ```
+ *
+ * @template TUser  - The shape of the authenticated user payload (e.g.
+ *                    `TokenPayload` from the JWT plugin). Defaults to
+ *                    `unknown`, forcing explicit typing for safe access.
+ * @template TState - The shape of the guard-produced `state` bag.
+ */
+export interface ApiContext<TUser = unknown, TState = Record<string, unknown>> {
+    /** Route and URL query parameters, separated by origin. */
+    query: {
+        /**
+         * Named parameters captured from the route pattern.
+         *
+         * For example, a route registered as `/items/:id` matched against
+         * `/items/42` produces `{ id: '42' }`.
+         */
+        route: Record<string, string>;
+        /**
+         * Parameters decoded from the URL query string.
+         *
+         * Repeated keys are preserved as string arrays.
+         * For example, `?q=hello&tag=a&tag=b` → `{ q: 'hello', tag: ['a', 'b'] }`.
+         */
+        url: Record<string, string | string[]>;
+    };
+    /**
+     * Shorthand alias for {@link ApiContext.query}.route — the named parameters
+     * captured from the route pattern.  This is the dominant access pattern;
+     * the namespaced form remains available for collision cases.
+     */
+    params: Record<string, string>;
+    /**
+     * The request path as seen by this API router, after any prefix stripping
+     * performed by a parent `use()` mount.
+     */
+    path: string;
+    /**
+     * Authentication data attached to the request, if present.
+     *
+     * Populated when a middleware (e.g. a JWT `authenticate` middleware) sets
+     * `req.user` before the service method is called.  `undefined` when no
+     * authentication data has been attached.
+     */
+    user?: TUser;
+    /**
+     * Values produced by guards (loaded resources, resolved roles, …).
+     *
+     * Each guard that returns an object has that object shallow-merged into
+     * this bag before the next guard (or the handler) runs.  Starts as `{}`
+     * for every request.
+     */
+    state: TState;
+}
 /**
  * An API error thrown (or rejected) by a service method.
  *
  * When a service method throws or rejects with an object of this shape, the
  * framework translates it into an HTTP error response automatically:
- * - `httpStatus` → HTTP status code (defaults to `500`).
+ * - `status` → HTTP status code (defaults to `500`).
  * - `data`       → JSON-serialised response body (takes precedence over `message`).
  * - `message`    → Plain-text response body.
  */
 export interface ApiError {
     /** HTTP status code to send (e.g. `404`, `503`). Defaults to `500`. */
-    httpStatus?: number;
+    status?: number;
     /** Structured error payload; serialised to JSON when present. */
     data?: unknown;
     /** Human-readable error message used when `data` is absent. */
@@ -21,21 +92,23 @@ export interface ApiError {
  *
  * Called with `this` bound to the current service instance.
  *
- * @param params - Route parameters extracted from the URL (e.g. `{ uid: '42' }`),
- *                 merged with URL query-string parameters.
- * @param body   - Parsed request body (populated by a body-parsing middleware
- *                 such as `json()`).
+ * @param ctx  - Request context containing route parameters, URL query
+ *               parameters, the request path, and optional auth data.
+ *               See {@link ApiContext}.
+ * @param body - Parsed request body (populated by a body-parsing middleware
+ *               such as `json()`).
  * @returns The value to send as the JSON response body, a `Promise` of the
  *          same, or `undefined` / `null` / any falsy value to send **201 No
  *          Content** (useful for mutations that produce no response body).
  */
-export type ServiceMethod<TInstance = ServiceInstance> = (this: TInstance, params: Record<string, string>, body?: unknown) => unknown | Promise<unknown>;
+export type ServiceMethod<TInstance = ServiceInstance, TResponse = any, TBody = any> = (this: TInstance, ctx: ApiContext, body?: TBody) => TResponse | Promise<TResponse>;
 /**
  * The runtime state object that backs a service instance.
  *
- * Produced by `service.data()` and extended with the methods from
- * `service.methods` before `service.setup()` is called.  A hidden `$key`
- * property carries the scope key when `data()` is not supplied.
+ * Produced by `service.data()` (which returns `Partial<TInstance>`) and
+ * extended with the methods from `service.methods` before `service.setup()`
+ * is called.  A hidden `$key` property carries the scope key when `data()` is
+ * not supplied.
  */
 export type ServiceInstance = Record<string, unknown> & {
     /** The scope key used to identify this instance (set by the framework). */
@@ -47,16 +120,222 @@ export type ServiceInstance = Record<string, unknown> & {
  * Methods declared here are copied onto the instance object, bound to `this`,
  * so they can call each other and read/write instance state naturally.
  */
-export type ServiceMethods<TInstance extends ServiceInstance = ServiceInstance> = {
-    [name: string]: (this: TInstance, ...args: unknown[]) => unknown;
-};
+export type ServiceMethods<TInstance extends ServiceInstance = ServiceInstance> = Record<string, (this: TInstance, ...args: unknown[]) => unknown>;
 /**
  * A route map: keys are Express-style path patterns, values are handler
  * functions that are invoked with `this` bound to the service instance.
  */
-export type RouteMap<TInstance extends ServiceInstance = ServiceInstance> = {
-    [path: string]: ServiceMethod<TInstance>;
-};
+export type RouteMap<TInstance extends ServiceInstance = ServiceInstance> = Record<string, ServiceMethod<TInstance>>;
+/**
+ * A pre-handler hook running in the `ctx` world.
+ *
+ * Guards attach at three levels — API (`ServiceDefinition.guards`),
+ * controller (`ControllerDefinition.guards`), and route
+ * (`OperationMeta.guards` via `describe()`) — and run outermost-first:
+ *
+ * ```
+ * auth.authenticate → auth.check → api guards → controller guards → route guards → handler
+ * ```
+ *
+ * A guard may:
+ * - **throw / reject** an {@link ApiError} → translated to an HTTP error response;
+ * - **return an object** → shallow-merged into `ctx.state`;
+ * - **return void** → pure check.
+ *
+ * Guards are loosely typed on purpose (`ctx.user` is `any` here); declare
+ * `ApiContext<TUser, TState>` explicitly in handlers for strict typing.
+ *
+ * @example
+ * ```ts
+ * const requireAdmin: Guard = (ctx) => {
+ *   if (!ctx.user?.isAdmin) throw { status: 403, message: 'Admin access required' };
+ *   return { admin: true };   // → ctx.state.admin
+ * };
+ * ```
+ */
+export type Guard = (ctx: ApiContext<any, Record<string, unknown>>, req: RouterRequest) => void | Record<string, unknown> | Promise<void | Record<string, unknown>>;
+/**
+ * A group of routes sharing a path prefix, default OpenAPI tags, guards, and
+ * a default permission requirement.
+ *
+ * Controllers are *route organisation*, not isolation boundaries: handlers in
+ * every controller run with `this` bound to the same service instance (the
+ * instance lifecycle — `scope` / `data` / `setup` / `methods` — stays at the
+ * {@link ServiceDefinition} level).
+ *
+ * @template TInstance - The shape of the service's state object.
+ */
+export interface ControllerDefinition<TInstance extends ServiceInstance = ServiceInstance> {
+    /** Path prefix prepended to every route in this controller (may contain params). */
+    prefix?: string;
+    /** Default OpenAPI tags applied to routes that do not declare their own. */
+    tags?: string[];
+    /** Guards run before every handler of this controller (see {@link Guard}). */
+    guards?: Guard[];
+    /**
+     * Default permission requirement for every route of this controller.
+     * Route-level `OperationMeta.permission` overrides it.  When set, the
+     * pipeline runs `auth.check(ctx, required)` before the guards.
+     */
+    permission?: string | string[];
+    /** Route handlers for `GET` requests (paths relative to `prefix`). */
+    GET?: RouteMap<TInstance>;
+    /** Route handlers for `POST` requests (paths relative to `prefix`). */
+    POST?: RouteMap<TInstance>;
+    /** Route handlers for `PUT` requests (paths relative to `prefix`). */
+    PUT?: RouteMap<TInstance>;
+    /** Route handlers for `DELETE` requests (paths relative to `prefix`). */
+    DELETE?: RouteMap<TInstance>;
+    /** Route handlers for `PATCH` requests (paths relative to `prefix`). */
+    PATCH?: RouteMap<TInstance>;
+}
+/**
+ * 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 declare function defineController<TInstance extends ServiceInstance = ServiceInstance>(c: ControllerDefinition<TInstance>): ControllerDefinition<TInstance>;
+/**
+ * Authentication / authorization binding connecting an auth layer (typically
+ * the JWT plugin) to the API Builder pipeline.
+ *
+ * @example
+ * ```ts
+ * const jwt = createJwtPlugin({ accessTokenSecret: SECRET });
+ * const api = apiBuilder({
+ *   auth: { authenticate: jwt.authenticate },  // default check() reads ctx.user.permissions
+ *   controllers: [ ... ],
+ * });
+ * ```
+ *
+ * @template TUser - The shape of the authenticated user payload.
+ */
+export interface AuthBinding<TUser = unknown> {
+    /**
+     * Router middleware run before any guard or handler — typically
+     * `jwtPlugin.authenticate`.  Registered by `apiBuilder` on its internal
+     * router, so the client no longer wires it per-mount.
+     */
+    authenticate?: Middleware;
+    /**
+     * Enforce a permission requirement for the current request.
+     *
+     * Default implementation: require `ctx.user` (else `401`) and check that
+     * `ctx.user.permissions` contains **all** required entries (else `403`) —
+     * i.e. the exact semantics of `jwtPlugin.requirePermission`, but in the
+     * `ctx` world.  Override for resource-scoped models (per-project roles,
+     * ownership, …); the override may load resources and share them through
+     * `ctx.state`.
+     *
+     * Failure is signalled by throwing / rejecting an {@link ApiError}.
+     */
+    check?: (ctx: ApiContext<TUser>, required: string[]) => void | Promise<void>;
+    /**
+     * OpenAPI security scheme emitted into `components.securitySchemes.bearerAuth`
+     * when at least one route declares a `permission`.
+     *
+     * Default: `{ type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }`.
+     */
+    scheme?: Record<string, unknown>;
+    /**
+     * Name of the vendor extension listing the required permissions on each
+     * secured operation in the generated OpenAPI document.
+     *
+     * Default: `'x-required-permissions'`.
+     */
+    permissionsExtension?: string;
+}
+/**
+ * Validation controls for {@link apiBuilder}.
+ *
+ * Used both as the factory's optional second argument and as the object form of
+ * the {@link ServiceDefinition.validate} field. When passed as the second
+ * argument it is authoritative and overrides `service.validate`:
+ *
+ * ```ts
+ * apiBuilder(service);                                 // follows service.validate
+ * apiBuilder(service, {});                              // validate requests (default), not responses
+ * apiBuilder(service, { validateRequests: false });    // validate nothing
+ * apiBuilder(service, { validateResponses: true });    // requests + responses (500 on mismatch)
+ * apiBuilder(service, { validateResponses: 'warn' });  // requests + responses (log only, no 500)
+ * ```
+ */
+export interface ApiBuilderOptions {
+    /**
+     * Validate incoming request bodies against each route's declared
+     * `OperationMeta.requestBody` schema. Failures produce `400` with
+     * `{ message, fieldErrors }`.
+     *
+     * @default true — pass `false` to cancel the incoming-data check.
+     */
+    validateRequests?: boolean;
+    /**
+     * Validate each handler's return value against the route's declared
+     * `OperationMeta.responses['200']` schema before it is sent.
+     *
+     * - `true`  — a mismatch is a server-contract breach: the off-spec body is
+     *   **not** sent; instead a `500` with `{ message, fieldErrors }` is returned.
+     * - `'warn'` — a mismatch is logged server-side via `console.warn` and the
+     *   response is sent unchanged (handy in development).
+     * - `false` — no response checking.
+     *
+     * Only truthy returns (sent as `200` JSON) are checked; falsy returns
+     * (`201 No Content`) and routes without a declared `200` response schema are
+     * skipped.
+     *
+     * @default false
+     */
+    validateResponses?: boolean | 'warn';
+}
+/**
+ * Extra methods attached to the router returned by {@link apiBuilder}.
+ *
+ * These allow the service's route definitions to be introspected and
+ * serialised as an OpenAPI 3.1.0 document.
+ */
+export interface ApiRouterExtensions {
+    /**
+     * Generate an OpenAPI 3.1.0 document from the service definition.
+     *
+     * @param opts - Top-level spec options (title, version, basePath, …).
+     * @returns A plain-object OpenAPI document ready to be serialised with
+     *          `JSON.stringify`.
+     */
+    spec(opts: SpecOptions): OpenApiDocument;
+    /**
+     * Return a request handler that serves the OpenAPI spec on `GET`.
+     *
+     * The spec is generated once and cached as a serialised string on the first
+     * call to the returned handler.
+     *
+     * ```ts
+     * // JSON (default)
+     * app.get('/openapi.json', itemsApi.specHandler({ title: 'Items API', version: '1.0.0' }));
+     *
+     * // YAML
+     * app.get('/openapi.yaml', itemsApi.specHandler({ title: 'Items API', version: '1.0.0' }, 'yaml'));
+     * ```
+     *
+     * @param opts   - Top-level spec options (title, version, basePath, …).
+     * @param format - Output format: `'json'` (default) or `'yaml'`.
+     * @returns An Express-compatible middleware handler.
+     */
+    specHandler(opts: SpecOptions, format?: SpecFormat): (req: RouterRequest, res: RouterResponse) => void;
+}
+/**
+ * The return type of {@link apiBuilder}: a standard {@link Router} augmented
+ * with OpenAPI introspection helpers ({@link ApiRouterExtensions}).
+ */
+export type ApiRouter = Router & ApiRouterExtensions;
 /**
  * A service definition object — the single argument to {@link apiBuilder}.
  *
@@ -90,7 +369,12 @@ export interface ServiceDefinition<TInstance extends ServiceInstance = ServiceIn
      */
     scope?: (req: RouterRequest) => string | null;
     /**
-     * Factory that returns the initial state object for a new instance.
+     * Factory that returns the **initial data** portion of a new instance.
+     *
+     * The return type is `Partial<TInstance>` because the methods declared in
+     * {@link ServiceDefinition.methods} are mixed in *after* `data()` is called,
+     * completing the instance shape.  By the time any route handler or
+     * `setup()` runs the instance is fully initialised.
      *
      * When omitted, the instance is initialised as `{ $key: key }`.
      *
@@ -98,14 +382,18 @@ export interface ServiceDefinition<TInstance extends ServiceInstance = ServiceIn
      *              global instances, `null` for ephemeral ones, or the string
      *              returned by `scope()`).
      */
-    data?: (key: string | null) => TInstance;
+    data?: (key: string | null) => Partial<TInstance>;
     /**
      * Lifecycle hook called once after an instance is created and its methods
      * are mixed in.
      *
-     * May be synchronous or asynchronous.  When asynchronous, the returned
-     * `Promise` is not awaited by the framework — use a `throwIfNotReady()`
-     * pattern in your methods to guard against premature access.
+     * May be synchronous or **asynchronous**.  When asynchronous, the framework
+     * now awaits the returned `Promise` before marking the instance as ready:
+     * - For **singleton** services, route handlers are only registered (and
+     *   requests served) once setup resolves.  Requests that arrive while setup
+     *   is in progress receive **503 Service not ready**.
+     * - For **keyed / ephemeral** services, the route handler awaits instance
+     *   creation (including setup) per request before invoking the method.
      */
     setup?: (this: TInstance) => void | Promise<void>;
     /**
@@ -116,6 +404,65 @@ export interface ServiceDefinition<TInstance extends ServiceInstance = ServiceIn
      * objects to trigger HTTP error responses.
      */
     methods?: ServiceMethods<TInstance>;
+    /**
+     * Sub-controllers merged into this API.
+     *
+     * Each controller's routes are rewritten to `joinPath(prefix, path)`, then
+     * all routes of all controllers (plus the root-level route maps below) are
+     * concatenated and sorted by specificity **globally**.  A duplicate
+     * `(verb, joined path)` pair across controllers **throws at build time**.
+     *
+     * All controllers share the single service instance lifecycle declared at
+     * this level — controllers organise routes, they do not isolate state.
+     */
+    controllers?: ControllerDefinition<TInstance>[];
+    /** Guards run before every handler of the whole API (see {@link Guard}). */
+    guards?: Guard[];
+    /** Authentication / authorization binding (see {@link AuthBinding}). */
+    auth?: AuthBinding;
+    /**
+     * Enable runtime validation of declared schemas.
+     *
+     * - `true` — validate request bodies against each route's
+     *   `OperationMeta.requestBody` schema (`400` with `{ message, fieldErrors }`
+     *   on failure).
+     * - An {@link ApiBuilderOptions} object — fine-grained control over request
+     *   and response validation.
+     *
+     * Overridden when an {@link ApiBuilderOptions} object is passed as the second
+     * argument to {@link apiBuilder}.
+     */
+    validate?: boolean | ApiBuilderOptions;
+    /**
+     * Reusable JSON Schema components, shared by request validation and spec
+     * generation.  `$ref: '#/components/schemas/Name'` references in operation
+     * metadata are resolved against this map by the validator, and the map is
+     * merged into `components.schemas` of the generated OpenAPI document
+     * (taking precedence over `SpecOptions.schemas`).
+     */
+    schemas?: Record<string, JsonSchema>;
+    /**
+     * Hook invoked whenever a handler, guard, auth check, or validation step
+     * throws or rejects — before the default {@link ApiError} → HTTP translation.
+     *
+     * Use it to log the failure and/or shape a better response:
+     * - **Return nothing** (`undefined`) → the error is left untouched and the
+     *   built-in translation runs (`{ status, message | data }`, else `500`).
+     *   Ideal for log-only use.
+     * - **Return an {@link ApiError}** → that value is sent instead of the
+     *   original (e.g. to hide internals behind a generic message, or attach a
+     *   correlation id).
+     * - **Throw** → the thrown value is escalated to the surrounding app's error
+     *   channel (`router.error()` / `onError`) instead of being answered here,
+     *   letting a process-wide handler take over.
+     *
+     * @param err - The caught value (thrown or rejected).
+     * @param ctx - The {@link ApiContext} for the failing request.
+     * @param req - The underlying request.
+     * @returns An {@link ApiError} to override the response, or nothing to keep
+     *   the default translation.
+     */
+    onError?(err: unknown, ctx: ApiContext<any>, req: RouterRequest): void | ApiError;
     /** Route handlers for `GET` requests. */
     GET?: RouteMap<TInstance>;
     /** Route handlers for `POST` requests. */
@@ -127,6 +474,112 @@ export interface ServiceDefinition<TInstance extends ServiceInstance = ServiceIn
     /** Route handlers for `PATCH` requests. */
     PATCH?: RouteMap<TInstance>;
 }
+/** The five HTTP verbs supported by `apiBuilder`. */
+declare const VERBS: readonly ["GET", "POST", "PUT", "DELETE", "PATCH"];
+/** One of the five HTTP verbs supported by `apiBuilder`. */
+export type ApiVerb = typeof VERBS[number];
+/**
+ * One merged route entry produced by {@link collectRoutes}.
+ *
+ * Records per-route provenance — effective tags, composed guard chain, and
+ * permission requirement — consumed by both the request pipeline
+ * (`apiBuilder`) and the spec generator (`openApiSpec`).
+ *
+ * @template TInstance - The shape of the service's state object.
+ */
+export interface CollectedRoute<TInstance extends ServiceInstance = ServiceInstance> {
+    /** HTTP verb of the route. */
+    verb: ApiVerb;
+    /** Full path after joining the controller prefix (Express-style pattern). */
+    path: string;
+    /** The route handler (possibly `describe()`-wrapped). */
+    handler: ServiceMethod<TInstance>;
+    /** Operation metadata attached via `describe()`, when present. */
+    meta?: OperationMeta;
+    /** Effective tags: route-level `meta.tags`, else the controller's `tags`. */
+    tags?: string[];
+    /** Composed guard chain: API guards, then controller guards, then route guards. */
+    guards: Guard[];
+    /** Normalised permission requirement (route-level overrides controller-level). */
+    permission?: string[];
+    /** Human-readable controller identifier used in diagnostics. */
+    controller: string;
+}
+/**
+ * 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 declare function joinPath(prefix: string, path: string): string;
+/**
+ * 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 declare function routeScore(path: string): number;
+/**
+ * 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 declare function normalizePermission(permission: string | string[] | undefined): string[] | undefined;
+/**
+ * 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 declare function collectRoutes<TInstance extends ServiceInstance = ServiceInstance>(service: ServiceDefinition<TInstance>): CollectedRoute<TInstance>[];
+/**
+ * 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 declare function validateSchema(value: unknown, schema: JsonSchema, components?: Record<string, JsonSchema>, path?: string, errors?: Record<string, string>): Record<string, string>;
 /**
  * Build an Express-compatible router from a service definition object.
  *
@@ -138,11 +591,25 @@ export interface ServiceDefinition<TInstance extends ServiceInstance = ServiceIn
  * 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:**
@@ -152,15 +619,25 @@ export interface ServiceDefinition<TInstance extends ServiceInstance = ServiceIn
  *   `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.
  */
-export declare function apiBuilder<TInstance extends ServiceInstance = ServiceInstance>(service: ServiceDefinition<TInstance>): Router;
+export declare function apiBuilder<TInstance extends ServiceInstance = ServiceInstance>(service: ServiceDefinition<TInstance>, options?: ApiBuilderOptions): ApiRouter;
 export default apiBuilder;
 //# sourceMappingURL=apis.d.ts.map

package/dist/apis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apis.d.ts","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,EAAE,MAAM,aAAa,CAAC;AAMzE;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,CAAC,SAAS,GAAG,eAAe,IAAI,CACvD,IAAI,EAAI,SAAS,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAG,OAAO,KACZ,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACtD,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,IAAI;IAChF,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CAClE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,IAAI;IAC1E,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe;IACpF;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,CAAC;IAE9C;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,SAAS,CAAC;IAEzC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAEpC,yCAAyC;IACzC,GAAG,CAAC,EAAK,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,0CAA0C;IAC1C,IAAI,CAAC,EAAI,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,yCAAyC;IACzC,GAAG,CAAC,EAAK,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,2CAA2C;IAC3C,KAAK,CAAC,EAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;CAC9B;AAyID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,UAAU,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,EAC5E,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,GACpC,MAAM,CAmFR;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"apis.d.ts","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"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"}