expediate 1.0.4 → 1.0.5

package/dist/apis.d.ts

@@ -1,16 +1,68 @@
-import type { RouterRequest, Router } from './router.js';
+import type { RouterRequest, RouterResponse, Router } from './router.js';
+import './openapi.js';
+import type { SpecOptions, SpecFormat, OpenApiDocument } 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.query.route.id;   // ':id' from the path pattern
+ *     const fmt = ctx.query.url.format; // '?format=json' from the query string
+ *     return getItem(id, fmt);
+ *   },
+ * }
+ * ```
+ */
+export interface ApiContext {
+    /** 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[]>;
+    };
+    /**
+     * 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?: any;
+}
 /**
  * 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 +73,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). */
@@ -57,6 +111,46 @@ export type ServiceMethods<TInstance extends ServiceInstance = ServiceInstance>
 export type RouteMap<TInstance extends ServiceInstance = ServiceInstance> = {
     [path: string]: ServiceMethod<TInstance>;
 };
+/**
+ * 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 +184,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 +197,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>;
     /**
@@ -138,11 +241,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 +269,15 @@ 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`.
  *
  * @param service - The service definition (see {@link ServiceDefinition}).
  * @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>): 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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"}

package/dist/apis.js

@@ -19,40 +19,38 @@
  * 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 } from './openapi.js';
 // ---------------------------------------------------------------------------
 // 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 +59,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 +70,42 @@ 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.
+        // 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];
+    if (!building[key]) {
+        building[key] = buildModule(service, key).then(instance => {
+            modules[key] = instance;
+            delete building[key];
+            return instance;
+        });
+    }
+    return building[key];
 }
 // ---------------------------------------------------------------------------
 // Response helpers
@@ -107,9 +117,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,15 +124,16 @@ 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.
  * @param err - The caught value.
  */
 function sendError(res, err) {
+    // console.error('Api Err', 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 +156,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,32 +184,30 @@ 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`.
  *
  * @param service - The service definition (see {@link ServiceDefinition}).
  * @returns A router instance pre-configured with all declared routes.
  */
-function apiBuilder(service) {
-    const api = (0, router_js_1.default)();
+export function apiBuilder(service) {
+    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 = {};
     /**
      * Register all route handlers from a route map for a given HTTP method.
      *
      * 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
+     * 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.
      *
      * @param routeMap - Map of path patterns to service methods (`undefined` = skip).
@@ -211,40 +231,113 @@ function apiBuilder(service) {
         for (const path of sortedPaths) {
             const method = routeMap[path];
             register(path, (req, res) => {
-                const params = req.params;
+                const ctx = {
+                    query: {
+                        route: req.queries?.route ?? {},
+                        url: req.queries?.url ?? {},
+                    },
+                    path: req.path,
+                    user: req.user,
+                };
                 const body = req.body;
-                try {
-                    const instance = resolveInstance(service, modules, req);
-                    const ret = method.apply(instance, [params, 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) {
-                        ret
-                            .then((val) => {
+                        return ret
+                            .then(val => {
                             if (val !== undefined && val !== null && val !== false && val !== 0 && val !== '')
                                 sendJson(res, val);
                             else
                                 res.status(201).end();
                         })
-                            .catch((err) => sendError(res, err));
+                            .catch(err => {
+                            // console.error(err)
+                            sendError(res, err);
+                        });
                     }
-                    else {
-                        if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
-                            sendJson(res, ret);
-                        else
-                            res.status(201).end();
-                    }
-                }
-                catch (err) {
+                    if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
+                        sendJson(res, ret);
+                    else
+                        res.status(201).end();
+                })
+                    .catch(err => {
+                    // console.error(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(service.GET, (path, h) => api.get(path, h));
+        buildRoutes(service.POST, (path, h) => api.post(path, h));
+        buildRoutes(service.PUT, (path, h) => api.put(path, h));
+        buildRoutes(service.DELETE, (path, h) => api.delete(path, h));
+        buildRoutes(service.PATCH, (path, h) => api.patch(path, h));
+    }
+    if (typeof service.scope !== 'function') {
+        // ── Singleton ─────────────────────────────────────────────────────────
+        // Register a "not ready" guard first so that requests arriving while
+        // setup is in progress receive 503 rather than 404.
+        let ready = false;
+        api.use('/', (_req, res, next) => {
+            if (!ready) {
+                res.statusCode = 503;
+                res.end('Service not ready');
+                return;
+            }
+            next();
+        });
+        // Build the singleton asynchronously, then flip the guard and register
+        // routes.  Even for synchronous setup() functions, buildModule() is async
+        // (it uses await internally), so route registration happens in a microtask
+        // that runs before any I/O callbacks — routes are always in place by the
+        // time the first HTTP request can be processed.
+        buildModule(service, 'singleton')
+            .then(instance => {
+            modules['singleton'] = instance;
+            ready = true;
+            registerAllRoutes();
+        })
+            .catch(err => {
+            // setup() rejected — log the error; the guard permanently returns 503.
+            console.error('[apiBuilder] singleton setup() rejected:', err);
+        });
+    }
+    else {
+        // ── Keyed / ephemeral ─────────────────────────────────────────────────
+        // Register routes immediately.  Each handler awaits resolveInstance(),
+        // which in turn awaits buildModule() for first-time keyed instances.
+        registerAllRoutes();
+    }
+    // ── OpenAPI introspection ──────────────────────────────────────────────────
+    /**
+     * Generate an OpenAPI 3.1.0 document from the service definition.
+     * Delegates to {@link openApiSpec} from `openapi.ts`.
+     */
+    api.spec = function (opts) {
+        return openApiSpec(service, opts);
+    };
+    /**
+     * Return a middleware handler that serves the OpenAPI spec as JSON or YAML.
+     * The spec is generated once and cached on the first call to the returned handler.
+     */
+    api.specHandler = function (opts, format = 'json') {
+        let cached = null;
+        const contentType = format === 'yaml'
+            ? 'application/yaml; charset=utf-8'
+            : 'application/json; charset=utf-8';
+        return function (_req, res) {
+            if (!cached)
+                cached = 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

package/dist/apis.js.map

@@ -1 +1 @@
-{"version":3,"file":"apis.js","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apis.js","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"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"}