@daloyjs/core 1.0.0-beta.6 → 1.0.0-rc.0

package/dist/app.d.ts

@@ -51,7 +51,9 @@ export type SecurityPreset = "internal-service";
 export interface AppOptions {
     /** OpenAPI document metadata */
     title?: string;
+    /** OpenAPI `info.version`. Falls back to the host package manifest version, then `"0.0.0"`. */
     version?: string;
+    /** OpenAPI `info.description`. Falls back to the host package manifest description. */
     description?: string;
     /**
      * Topology-aware security posture preset. See {@link SecurityPreset}.
@@ -350,9 +352,13 @@ export interface AppOptions {
  * @since 0.3.0
  */
 export interface AppOpenAPIOptions {
+    /** OpenAPI `info` object. `title`/`version` fall back to {@link AppOptions.title} / {@link AppOptions.version}, then the host package manifest. */
     info?: Partial<OpenAPIInfo>;
+    /** `servers` array published in the generated document. */
     servers?: OpenAPIOptions["servers"];
+    /** Security schemes stitched into `components.securitySchemes`. */
     securitySchemes?: OpenAPIOptions["securitySchemes"];
+    /** OpenAPI 3.1 top-level `webhooks` operations, keyed by webhook name. */
     webhooks?: OpenAPIOptions["webhooks"];
 }
 /**
@@ -684,18 +690,31 @@ export interface CspReportRouteOptions {
  * @since 0.1.0
  */
 export interface IntrospectedRoute {
+    /** HTTP method the route responds to (e.g. `"GET"`). */
     method: HttpMethod;
+    /** Route path pattern as registered, including any group prefix (e.g. `/users/:id`). */
     path: string;
+    /** OpenAPI operationId, when declared on the route. */
     operationId?: string;
+    /** OpenAPI tags, when declared on the route or inherited from a group. */
     tags?: string[];
+    /** One-line OpenAPI summary, when declared. */
     summary?: string;
+    /** Longer OpenAPI description, when declared. */
     description?: string;
+    /** `true` when the route is marked deprecated in OpenAPI. */
     deprecated?: boolean;
+    /** Whether the route declares a request body schema. */
     hasBody: boolean;
+    /** Whether the route declares a query-string schema. */
     hasQuery: boolean;
+    /** Whether the route declares a path-params schema. */
     hasParams: boolean;
+    /** Whether the route declares a request-headers schema. */
     hasHeaders: boolean;
+    /** Declared response status codes (e.g. `[200, 404]`). */
     responses: number[];
+    /** Security scheme name and required scopes, when the route declares `auth`. */
     auth?: {
         scheme: string;
         scopes?: string[];
@@ -737,6 +756,17 @@ export declare const DALOY_REQUEST_RAW_BODY: unique symbol;
  * opt in; userland code should not depend on it.
  */
 export declare const DALOY_RAW_STREAM: unique symbol;
+/**
+ * Internal Symbol an adapter sets (once, on its request shim's prototype) to
+ * declare: "the object that ultimately consumes this request's `Response`
+ * only reads `status` / `headers` / {@link DALOY_RAW_BODY} — it never needs a
+ * branded WHATWG `Response`". When present on the incoming request,
+ * {@link serializeResult} may return a {@link LightResponse} and skip the
+ * ~2µs undici `Response` construction per request. Requests without the
+ * marker (Bun / Deno / Workers adapters, tests, direct `app.fetch()` callers)
+ * always get a real `Response`, so the public contract is unchanged.
+ */
+export declare const DALOY_LIGHT_RESPONSE_OK: unique symbol;
 /**
  * Contract-first HTTP application.
  *
@@ -799,10 +829,28 @@ export declare const DALOY_RAW_STREAM: unique symbol;
  */
 type AppendRoute<Routes extends readonly RouteDefinition<any, any, any, any>[], R extends RouteDefinition<any, any, any, any>> = readonly RouteDefinition<any, any, any, any>[] extends Routes ? readonly [R] : readonly [...Routes, R];
 /**
+ * The DaloyJS application: a contract-first router plus a web-standard
+ * `fetch(Request): Promise<Response>` handler that runs unchanged on Node,
+ * Bun, Deno, Cloudflare Workers, and Vercel via the adapters.
+ *
+ * Routes registered with {@link App.route} are validated against their
+ * declared schemas on the way in and out, accumulate in the typed
+ * {@link App.routes} tuple (powering OpenAPI generation and the typed
+ * client), and are served with secure defaults: body limits, request
+ * timeouts, security headers, and prod-mode error redaction.
+ *
+ * @typeParam Routes - Compile-time tuple of registered route definitions,
+ * grown by each {@link App.route} call.
  * @since 0.1.0
  */
 export declare class App<Routes extends readonly RouteDefinition<any, any, any, any>[] = readonly RouteDefinition<any, any, any, any>[]> {
+    /**
+     * Resolved constructor options. The security-relevant trio is always
+     * populated: `validateResponses` (default `true`), `bodyLimitBytes`
+     * (default 1 MiB), and `requestTimeoutMs` (default 30_000 ms).
+     */
     readonly options: Required<Pick<AppOptions, "validateResponses" | "bodyLimitBytes" | "requestTimeoutMs">> & AppOptions;
+    /** Structured logger for the app. Defaults to a JSON-lines console logger; override via `options.logger`. */
     readonly log: Logger;
     /**
      * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
@@ -1312,6 +1360,14 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * @returns This `App` instance for chaining.
      */
     use(hooks: Hooks): this;
+    /**
+     * Apply an ordered list of plugin extensions to the
+     * group-level hook chain. Each extension's `handler` is wrapped into a
+     * single-event {@link Hooks} bundle so subsequent route registrations
+     * pick it up via the normal hook composition path.
+     * @internal
+     */
+    private applyExtensions;
     /**
      * Decorate `ctx.state` with a value available inside every handler and hook.
      *
@@ -1334,16 +1390,10 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      *
      * @param key - Property name on `ctx.state`.
      * @param value - Value bound to that property on every request.
+     * @param opts - Pass `{ override: true }` to replace an existing decoration (logged as a warning).
      * @returns This `App` instance for chaining.
+     * @throws Error if `key` is already decorated and `opts.override` is not `true`.
      */
-    /**
-     * Apply an ordered list of plugin extensions to the
-     * group-level hook chain. Each extension's `handler` is wrapped into a
-     * single-event {@link Hooks} bundle so subsequent route registrations
-     * pick it up via the normal hook composition path.
-     * @internal
-     */
-    private applyExtensions;
     decorate<K extends string, V>(key: K, value: V, opts?: {
         override?: boolean;
     }): this;
@@ -1474,13 +1524,6 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * @returns Fulfills with the `Response` produced by the matching handler.
      */
     request(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-    /**
-     * Return a JSON-serializable summary of every registered route. Useful for
-     * dead-route detection, dashboards, and tests that want to assert against
-     * the route table without parsing the OpenAPI document.
-     *
-     * @returns Array of one {@link IntrospectedRoute} per registered route.
-     */
     /**
      * Emit a one-time development warning when any route declares a `2xx`
      * response without a body schema, because response-field stripping
@@ -1490,6 +1533,13 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
      * `secureDefaults: false`. See {@link findRoutesMissingResponseBodySchema}.
      */
     private warnMissingResponseBodySchemas;
+    /**
+     * Return a JSON-serializable summary of every registered route. Useful for
+     * dead-route detection, dashboards, and tests that want to assert against
+     * the route table without parsing the OpenAPI document.
+     *
+     * @returns Array of one {@link IntrospectedRoute} per registered route.
+     */
     introspect(): IntrospectedRoute[];
     /**
      * Begin graceful shutdown.
@@ -1532,6 +1582,12 @@ export declare class App<Routes extends readonly RouteDefinition<any, any, any,
 /**
  * Topological sort of plugin extensions. Refuses-at-call
  * on cyclic ordering with a structured error naming the cycle.
+ *
+ * @param exts - Extensions to order by their `before` / `after` constraints (Kahn's algorithm).
+ * @returns The extensions in a valid execution order.
+ * @throws Error on duplicate extension names, on a `before`/`after` cycle
+ * (naming the members), or when two extensions mutate the same response
+ * header without declaring an ordering between each other.
  * @internal
  */
 export declare function topoSortExtensions(exts: ReadonlyArray<PluginExtension>): PluginExtension[];
@@ -1550,13 +1606,16 @@ export declare function topoSortExtensions(exts: ReadonlyArray<PluginExtension>)
  * It powers both the `daloy doctor` `audit.response.bodySchema` finding and
  * the development-mode boot warning emitted on the first request. The result
  * is advisory — a route may legitimately return no body — so callers treat
- * it as a `warn`, never a hard error.
+ * it as a `warn`, never a hard error. Routes that set
+ * `acknowledgeNoResponseBodySchema: true` (including the framework-mounted
+ * docs, AsyncAPI, health, and metrics routes, whose bodies DaloyJS itself
+ * serializes) are skipped: the missing schema is declared intentional.
  *
  * @param routes - Route definitions to inspect (typically `app.routes`).
  * @returns One entry per offending route with the affected `2xx` status codes.
  * @since 0.40.0
  */
-export declare function findRoutesMissingResponseBodySchema(routes: readonly Pick<RouteDefinition<any, any, any, any>, "method" | "path" | "responses">[]): Array<{
+export declare function findRoutesMissingResponseBodySchema(routes: readonly Pick<RouteDefinition<any, any, any, any>, "method" | "path" | "responses" | "acknowledgeNoResponseBodySchema">[]): Array<{
     method: string;
     path: string;
     statuses: number[];
@@ -1575,6 +1634,8 @@ export declare function findRoutesMissingResponseBodySchema(routes: readonly Pic
  * for ergonomics and matches the factory pattern used by Express, Fastify,
  * and Hono adapters.
  *
+ * @param options - Same {@link AppOptions} accepted by the `App` constructor. Default: `{}`.
+ * @returns A new {@link App} instance.
  * @since 0.3.0
  */
 export declare function createApp(options?: AppOptions): App;