@daloyjs/core 0.35.2 → 0.37.0

package/dist/app.js

@@ -10,6 +10,8 @@ import { secureHeaders as secureHeadersMiddleware, CORS_HOOK_MARKER, CORS_ORIGIN
 import { COMPRESSION_HOOK_MARKER } from "./compression.js";
 import { SESSION_HOOK_MARKER, SESSION_SECRETS_MARKER, } from "./session.js";
 import { loadShedding as loadSheddingMiddleware } from "./load-shedding.js";
+import { httpMetrics, MetricsRegistry, PROMETHEUS_CONTENT_TYPE, } from "./metrics.js";
+import { Scheduler, } from "./scheduler.js";
 import { securitySchemeRequiresPayloadAuth } from "./security-schemes.js";
 import { assertBehindProxy } from "./conn-info.js";
 const AUTO_SECURE_HEADERS_MARKER = Symbol.for("daloyjs.app.autoSecureHeaders");
@@ -40,6 +42,36 @@ let insecureDefaultsLoggedThisProcess = false;
 export function _resetInsecureDefaultsLogForTests() {
     insecureDefaultsLoggedThisProcess = false;
 }
+/**
+ * The exact set of fields the `"internal-service"` preset flips off when
+ * the caller has not set them explicitly. Surfaced through the boot
+ * audit log entry so operators can see which guards the preset turned
+ * off without re-reading the framework source.
+ */
+const INTERNAL_SERVICE_PRESET_DISABLED = Object.freeze([
+    "secureHeaders auto-install",
+    "corsCrossOriginGuard (state-changing cross-origin write rejection)",
+    "csrf boot guard (session() + state-changing route)",
+    "unconfigured X-Forwarded-* / trustProxy guard",
+]);
+/**
+ * Defaults that the `"internal-service"` preset keeps on. Logged at boot
+ * alongside the disabled list so the audit entry shows the full posture.
+ */
+const INTERNAL_SERVICE_PRESET_KEPT = Object.freeze([
+    "bodyLimitBytes (1 MiB default)",
+    "requestTimeoutMs (30 s default)",
+    "crashOnUnhandledRejection (production)",
+    "weak session secret refuse-to-boot",
+    "cors({ origin: '*' }) refuse-to-boot",
+    "anonymous stateful plugin refuse-to-boot",
+    "stripServerHeaders",
+    "RFC 9457 problem+json prod redaction",
+    "JWT algorithm allowlist + timingSafeEqual credential comparison",
+    "prototype-pollution-safe parsers + isForbiddenObjectKey",
+    "fetchGuard() SSRF defaults",
+    "schema .strict() + response validation when enabled",
+]);
 /**
  * List of secure-by-default surfaces disabled when `secureDefaults: false`
  * is set. Surfaced through the once-per-process `error` log so the operator
@@ -74,6 +106,46 @@ const CANONICAL_HTTP_METHODS = new Set([
     "HEAD",
     "OPTIONS",
 ]);
+/**
+ * Apply a topology-aware security preset on top of caller-supplied
+ * options. Returns a new options object where preset defaults fill in
+ * any field the caller left `undefined`; explicit caller values always
+ * win. Pure / no side effects — the boot audit log is emitted
+ * separately by {@link App.logSecurityPresetIfApplied} so this helper is
+ * safe to call from `new App({ preset: ... })` in test setups.
+ *
+ * The `"internal-service"` preset turns off:
+ *  - `secureHeaders` auto-install (browser-only headers)
+ *  - `corsCrossOriginGuard` (no browser Origin to guard against)
+ *  - `csrf` (set to `"off"` — service-to-service callers aren't browsers)
+ *  - `trustProxy` (set to `false` — explicitly ignore `X-Forwarded-*`
+ *    and silence the unconfigured-proxy 500 guard; the immediate peer
+ *    inside the mesh *is* the caller)
+ *
+ * Everything else (body limits, request timeouts, JWT allowlist,
+ * `crashOnUnhandledRejection`, weak-secret refuse-to-boot, cors-wildcard
+ * refuse-to-boot, anonymous stateful plugin refuse-to-boot,
+ * `stripServerHeaders`, RFC 9457 prod redaction, schema strictness,
+ * `fetchGuard`, parser safety) stays at its standard secure-by-default
+ * value.
+ *
+ * @internal
+ */
+function applySecurityPreset(options) {
+    if (options.preset !== "internal-service")
+        return options;
+    const out = { ...options };
+    if (out.secureHeaders === undefined)
+        out.secureHeaders = false;
+    if (out.corsCrossOriginGuard === undefined)
+        out.corsCrossOriginGuard = false;
+    if (out.csrf === undefined)
+        out.csrf = "off";
+    if (out.trustProxy === undefined && out.behindProxy === undefined) {
+        out.trustProxy = false;
+    }
+    return out;
+}
 const DEFAULTS = {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 30_000,
@@ -191,6 +263,12 @@ export class App {
     installedPlugins = new Set();
     closeHooks = [];
     closeHooksRun = false;
+    /**
+     * Lazily-created in-process scheduler backing {@link App.cron}. Started on
+     * the first `cron()` call and stopped from an `onClose` hook so its lifecycle
+     * is tied to graceful shutdown.
+     */
+    scheduler;
     /** Idle-connection close hooks (adapter-registered, sync). */
     idleConnectionCloseHooks = [];
     pluginInstalledListeners = [];
@@ -245,11 +323,12 @@ export class App {
         return this._globalCorsAllowsCache;
     }
     constructor(options = {}) {
+        const resolved = applySecurityPreset(options);
         this.options = {
-            validateResponses: options.validateResponses ?? DEFAULTS.validateResponses,
-            bodyLimitBytes: options.bodyLimitBytes ?? DEFAULTS.bodyLimitBytes,
-            requestTimeoutMs: options.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs,
-            ...options,
+            validateResponses: resolved.validateResponses ?? DEFAULTS.validateResponses,
+            bodyLimitBytes: resolved.bodyLimitBytes ?? DEFAULTS.bodyLimitBytes,
+            requestTimeoutMs: resolved.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs,
+            ...resolved,
         };
         this.log =
             options.logger === false
@@ -264,6 +343,7 @@ export class App {
         if (this.options.hooks)
             this.assertSecureHookConfig(this.options.hooks);
         this.assertInsecureDefaultsAcknowledged();
+        this.logSecurityPresetIfApplied(options);
         this.installSecureDefaults();
         this.maybeInstallCrashHandlers();
         this.maybeMountDocs();
@@ -318,6 +398,68 @@ export class App {
             }, `app({ secureDefaults: false }) disables: ${DISABLED_BY_INSECURE_DEFAULTS.join(", ")}.`);
         }
     }
+    /**
+     * Emit the one-time boot audit entry for an applied security preset.
+     * Called from the constructor with the *original* (pre-preset) options
+     * so the log captures which fields the preset filled in vs. which the
+     * caller set explicitly. Logged at `info` so the line shows up in
+     * standard production log shipping without being noisy.
+     *
+     * Operators can audit the live posture at any time through
+     * {@link App.getSecurityPosture}.
+     *
+     * @since 0.34.0
+     */
+    logSecurityPresetIfApplied(originalOptions) {
+        if (originalOptions.preset !== "internal-service")
+            return;
+        const userOverrode = [];
+        if (originalOptions.secureHeaders !== undefined)
+            userOverrode.push("secureHeaders");
+        if (originalOptions.corsCrossOriginGuard !== undefined) {
+            userOverrode.push("corsCrossOriginGuard");
+        }
+        if (originalOptions.csrf !== undefined)
+            userOverrode.push("csrf");
+        if (originalOptions.trustProxy !== undefined)
+            userOverrode.push("trustProxy");
+        if (originalOptions.behindProxy !== undefined)
+            userOverrode.push("behindProxy");
+        this.log.info({
+            event: "security.preset.applied",
+            preset: "internal-service",
+            disabled: INTERNAL_SERVICE_PRESET_DISABLED,
+            kept: INTERNAL_SERVICE_PRESET_KEPT,
+            userOverrode,
+        }, `Applied security preset "internal-service": disabled ${INTERNAL_SERVICE_PRESET_DISABLED.length} topology-dependent guards; kept ${INTERNAL_SERVICE_PRESET_KEPT.length} input/credential/SSRF guards on. See app.getSecurityPosture() for the live snapshot.`);
+    }
+    /**
+     * Structured snapshot of the live security posture. Returns the same
+     * data the constructor logs under the `security.preset.applied` audit
+     * event plus the resolved values of every secure-by-default knob, so
+     * operators can build a `/__security` introspection route or a CI
+     * audit without parsing the framework source.
+     *
+     * @since 0.34.0
+     */
+    getSecurityPosture() {
+        const o = this.options;
+        return Object.freeze({
+            preset: o.preset,
+            secureDefaults: o.secureDefaults !== false,
+            secureHeaders: o.secureDefaults !== false && o.secureHeaders !== false,
+            corsCrossOriginGuard: o.secureDefaults !== false && o.corsCrossOriginGuard !== false,
+            csrf: o.csrf === "off" ? "off" : "on",
+            crashOnUnhandledRejection: o.crashOnUnhandledRejection === undefined
+                ? "default"
+                : o.crashOnUnhandledRejection,
+            trustProxy: o.trustProxy === undefined ? "unconfigured" : o.trustProxy,
+            bodyLimitBytes: this.options.bodyLimitBytes,
+            requestTimeoutMs: this.options.requestTimeoutMs,
+            stripServerHeaders: o.stripServerHeaders !== false,
+            production: this.isProduction(),
+        });
+    }
     /**
      * Install the secure-by-default global hooks. Currently:
      *  - {@link secureHeaders} as a group-level hook so every response carries
@@ -727,11 +869,16 @@ export class App {
             handler: async () => {
                 const title = opts.title ?? (await resolveInfo()).title;
                 const html = ui === "swagger"
-                    ? swaggerUiHtml({ specUrl: openapiPath, title })
+                    ? swaggerUiHtml({
+                        specUrl: openapiPath,
+                        title,
+                        assets: opts.assets,
+                    })
                     : scalarHtml({
                         specUrl: openapiPath,
                         title,
                         configuration: opts.scalar,
+                        assets: opts.assets,
                     });
                 return {
                     status: 200,
@@ -796,6 +943,13 @@ export class App {
             auth: def.auth ?? this.groupAuth,
         };
         this.assertRouteAuthPayloadConfig(merged);
+        // Normalize an optional RFC 8594 sunset date to a stable IMF-fixdate
+        // (HTTP date) string once, at registration time, so the hot response
+        // path can emit the `Sunset` header without re-parsing per request and
+        // a bad value fails fast rather than silently emitting garbage.
+        if (merged.sunset !== undefined) {
+            merged.sunset = normalizeSunset(merged.sunset, merged.method, fullPath);
+        }
         const sources = [...this.groupHooks, def.hooks ?? {}];
         const hooks = mergeHooks(sources);
         const corsOriginAllows = corsOriginAllowsFromHooks(sources);
@@ -948,6 +1102,166 @@ export class App {
         });
         return this;
     }
+    /**
+     * Register an opt-in, auth-guarded Prometheus / OpenMetrics scrape route
+     * and install RED (Rate / Errors / Duration) instrumentation for every
+     * route registered **after** this call. The third observability pillar
+     * alongside the structured logger and the OpenTelemetry tracer.
+     *
+     * Exposes, in the Prometheus text exposition format:
+     * - `<prefix>http_requests_total{method,route,status}` — request counter,
+     * - `<prefix>http_request_duration_seconds{method,route}` — latency histogram,
+     * - `<prefix>http_requests_in_flight` — concurrency gauge,
+     * - process gauges (resident memory, heap used, uptime) on Node-like runtimes.
+     *
+     * The scrape route inherits the same hardened posture as
+     * {@link App.healthcheck}: optional bearer token compared via
+     * {@link timingSafeEqual}, a per-IP fixed-window rate limit, and a
+     * refuse-to-boot guard in production (an unauthenticated `/metrics`
+     * endpoint leaks internal route names, latency, and traffic volume) unless
+     * a token is supplied or `acknowledgeUnauthenticated: true` is passed.
+     *
+     * Call this **before** registering the routes you want measured — like any
+     * `app.use(...)` middleware, the instrumentation only wraps routes added
+     * afterwards. Pass `opts.registry` to register custom application metrics
+     * that are rendered alongside the built-in HTTP series.
+     *
+     * @param opts - Path, auth, rate-limit, registry, and label configuration.
+     * @returns `this` for chaining.
+     * @since 0.37.0
+     */
+    metrics(opts = {}) {
+        const path = (opts.path ?? "/metrics");
+        const registry = opts.registry ?? new MetricsRegistry();
+        const rateLimitConfig = opts.rateLimit === false
+            ? null
+            : { limit: 60, windowMs: 60_000, ...(opts.rateLimit ?? {}) };
+        const token = opts.token;
+        // Refuse-to-boot: an unauthenticated metrics scrape in production is a
+        // documented info-disclosure surface (route inventory, latency
+        // distributions, request volume, process memory). Force an explicit
+        // acknowledgement, mirroring app.healthcheck().
+        if (this.options.secureDefaults !== false &&
+            this.isProduction() &&
+            token === undefined &&
+            opts.acknowledgeUnauthenticated !== true) {
+            throw new Error(`app.metrics() refused in production: provide opts.token to require ` +
+                `Authorization: Bearer <token>, or pass acknowledgeUnauthenticated: true ` +
+                `to acknowledge that this scrape endpoint is reachable without credentials.`);
+        }
+        // Install RED instrumentation as a group hook so it wraps every route
+        // registered after this call. Always exclude the scrape path itself, plus
+        // any caller-supplied predicate.
+        const exclude = (p) => p === path || (opts.exclude ? opts.exclude(p) : false);
+        this.groupHooks.push(httpMetrics({
+            registry,
+            route: opts.route,
+            maxRouteCardinality: opts.maxRouteCardinality,
+            buckets: opts.buckets,
+            exclude,
+        }));
+        const buckets = rateLimitConfig
+            ? new Map()
+            : null;
+        this.route({
+            method: "GET",
+            path,
+            operationId: "metrics",
+            tags: ["Observability"],
+            summary: "Prometheus metrics scrape endpoint",
+            handler: async ({ request }) => {
+                if (buckets && rateLimitConfig) {
+                    const key = healthRouteKey(request);
+                    const now = Date.now();
+                    const entry = buckets.get(key);
+                    if (!entry || entry.resetMs <= now) {
+                        buckets.set(key, { count: 1, resetMs: now + rateLimitConfig.windowMs });
+                    }
+                    else {
+                        entry.count++;
+                        if (entry.count > rateLimitConfig.limit) {
+                            throw new TooManyRequestsError(Math.ceil((entry.resetMs - now) / 1000));
+                        }
+                    }
+                }
+                if (token !== undefined) {
+                    const h = request.headers.get("authorization") ?? "";
+                    const m = /^Bearer\s+(.+)$/i.exec(h);
+                    if (!m) {
+                        throw new HttpError(401, {
+                            type: "https://daloyjs.dev/errors/unauthorized",
+                            title: "Unauthorized",
+                            detail: "Metrics scrape requires a bearer token.",
+                        }, { "www-authenticate": 'Bearer realm="metrics"' });
+                    }
+                    if (!timingSafeEqual(m[1], token)) {
+                        throw new ForbiddenError("Invalid metrics scrape token.");
+                    }
+                }
+                return {
+                    status: 200,
+                    body: registry.render(),
+                    headers: {
+                        "content-type": PROMETHEUS_CONTENT_TYPE,
+                        "cache-control": "no-store",
+                    },
+                };
+            },
+            responses: {
+                200: { description: "Prometheus metrics exposition." },
+                429: { description: "Too many scrape requests." },
+            },
+        });
+        return this;
+    }
+    /**
+     * Register an in-process scheduled task (cron). The first call lazily creates
+     * an app-managed {@link Scheduler}, wires it to the app logger, starts it,
+     * and registers an `onClose` hook so it is drained on graceful shutdown
+     * (in-flight runs are awaited, then aborted if they outlast the shutdown
+     * grace period).
+     *
+     * The schedule is **queue-agnostic** — it runs work in *this* process on a
+     * fixed interval or cron expression. Use it for periodic maintenance
+     * (cache sweeps, token refresh, reconciliation) rather than as a distributed
+     * job queue. Each task is **single-flight**: if a tick fires while the
+     * previous run is still in progress, the tick is skipped and counted, so a
+     * slow task can never pile up overlapping runs.
+     *
+     * @example
+     * ```ts
+     * app.cron({ name: "sweep", cron: "0 * * * *" }, async ({ signal }) => {
+     *   await purgeExpiredSessions({ signal });
+     * });
+     * ```
+     *
+     * @param def - The task definition. Exactly one of `intervalMs` or `cron`.
+     * @param handler - The function to run on each tick.
+     * @returns This `App` instance for chaining.
+     * @throws {RangeError} on invalid options (see {@link Scheduler.define}).
+     * @throws {@link CronParseError} if a `cron` expression is malformed.
+     */
+    cron(def, handler) {
+        if (this.scheduler === undefined) {
+            const scheduler = new Scheduler({ logger: this.log.child({ component: "scheduler" }) });
+            this.scheduler = scheduler;
+            scheduler.start();
+            // Drain the scheduler during the post-drain close phase so periodic
+            // work stops cleanly alongside database pools and other resources.
+            this.onClose(() => scheduler.stop());
+        }
+        this.scheduler.define(def, handler);
+        return this;
+    }
+    /**
+     * The app-managed {@link Scheduler} backing {@link App.cron}, or `undefined`
+     * if no scheduled task has been registered. Exposed for inspection
+     * (`getState()` / `list()`) and manual triggering (`runNow()`); the lifecycle
+     * is owned by the app.
+     */
+    get scheduledTasks() {
+        return this.scheduler;
+    }
     registerHealthRoute(kind, opts, handler) {
         const isHealth = kind === "healthcheck";
         const defaultPath = (isHealth ? "/healthz" : "/readyz");
@@ -1499,7 +1813,7 @@ export class App {
             });
         }
         this.inflight++;
-        const requestId = randomId();
+        let requestId = randomId();
         // Skip the per-request child-logger allocation when the app was
         // constructed with `{ logger: false }`. noopLogger.child() returns
         // itself, so the binding is wasted work on every request.
@@ -1662,6 +1976,13 @@ export class App {
             if (allHooks.beforeHandle !== undefined) {
                 const beforeResult = allHooks.beforeHandle(ctx);
                 const before = isPromiseLike(beforeResult) ? await beforeResult : beforeResult;
+                // Honor any request id override applied by middleware (e.g. the
+                // `requestId()` Hooks bundle replaces the framework-generated value
+                // with a trusted incoming header or a user-supplied generator).
+                const overriddenId = state.requestId;
+                if (typeof overriddenId === "string" && overriddenId.length > 0) {
+                    requestId = overriddenId;
+                }
                 if (before instanceof Response) {
                     copyContextHeaders(ctx, before);
                     if (!before.headers.has("x-request-id"))
@@ -1686,8 +2007,10 @@ export class App {
             const serializeResultRes = serializeResult(result, def, this.options.validateResponses ?? true);
             let response = isPromiseLike(serializeResultRes) ? await serializeResultRes : serializeResultRes;
             copyContextHeaders(ctx, response);
-            if (!response.headers.has("x-request-id"))
-                response.headers.set("x-request-id", requestId);
+            // `serializeResult` always builds a fresh Response with no request id —
+            // skip the `has()` probe and set directly. Saves one undici contains()
+            // call per request on the hot path.
+            response.headers.set("x-request-id", requestId);
             let finalized;
             if (hasFinalizeHook) {
                 const fin = finalizeResponse(response, ctx, allHooks, stripFingerprint);
@@ -2523,6 +2846,23 @@ async function readBody(req, ct, limit, multipart) {
     const bytes = await readBodyLimited(req, limit);
     return new TextDecoder().decode(bytes);
 }
+/**
+ * Validate and normalize a route's RFC 8594 `sunset` value to an IMF-fixdate
+ * (HTTP date) string. Accepts an ISO-8601/parseable string or a `Date`.
+ * Throws at registration time when the value cannot be parsed into a valid
+ * date so a typo never silently ships a malformed `Sunset` header.
+ *
+ * @internal
+ */
+function normalizeSunset(value, method, path) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new Error(`app.route(): invalid sunset date for ${method} ${path}: ` +
+            `${JSON.stringify(value)}. Provide an ISO-8601 string, an HTTP date, ` +
+            `or a Date instance.`);
+    }
+    return date.toUTCString();
+}
 function serializeResult(result, def, validateResponses) {
     const spec = def.responses[result.status];
     if (!spec) {
@@ -2534,6 +2874,16 @@ function serializeResult(result, def, validateResponses) {
         const treatAsJson = !explicitCt || explicitCt.includes("application/json");
         if (!explicitCt)
             headers.set("content-type", "application/json");
+        // RFC 8594 deprecation lifecycle headers. A route with an explicit
+        // `sunset` date is implicitly deprecated. Never overwrite a value the
+        // handler set deliberately.
+        if (def.deprecated === true || def.sunset !== undefined) {
+            if (!headers.has("deprecation"))
+                headers.set("deprecation", "true");
+            if (def.sunset !== undefined && !headers.has("sunset")) {
+                headers.set("sunset", def.sunset);
+            }
+        }
         let body;
         let rawBody = null;
         let isStream = false;

package/dist/asyncapi.d.ts

@@ -0,0 +1,98 @@
+/**
+ * AsyncAPI 3.0 document generator for WebSocket surfaces.
+ *
+ * Built-in, dependency-free, and a deliberate mirror of the OpenAPI 3.1
+ * generator in `./openapi.ts`: it turns every `app.ws()` route into an
+ * AsyncAPI **channel** (the socket address + path parameters) and one or more
+ * **operations** (`receive` for client→server messages, `send` for
+ * server→client messages). The RFC 6455 stack and its CSWSH defenses finally
+ * get a contract/doc artifact, extending the contract-first story past HTTP.
+ *
+ * If a message schema exposes a `toJSONSchema()` method (Zod 4, Valibot, ...)
+ * we use it; otherwise we emit a permissive `{}` placeholder rather than fail
+ * — docs and tooling still work, just with looser types for that payload.
+ */
+import type { App } from "./app.js";
+/** AsyncAPI [Info Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#infoObject) header fields. */
+export interface AsyncAPIInfo {
+    /** Human-readable API title shown by AsyncAPI Studio / docs. */
+    title: string;
+    /** Semantic API version (independent of your package version). */
+    version: string;
+    /** Optional CommonMark long description rendered at the top of the docs. */
+    description?: string;
+}
+/**
+ * AsyncAPI [Server Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject).
+ * Unlike OpenAPI's `servers` array, AsyncAPI keys servers by name.
+ */
+export interface AsyncAPIServer {
+    /** Host (and optional port) the socket is reachable at, e.g. `api.example.com`. */
+    host: string;
+    /** Transport protocol, typically `ws` or `wss`. */
+    protocol: string;
+    /** Optional protocol version. */
+    protocolVersion?: string;
+    /** Optional base path prefixing channel addresses, e.g. `/realtime`. */
+    pathname?: string;
+    /** Optional human-readable server description. */
+    description?: string;
+}
+/** Options for {@link generateAsyncAPI}. */
+export interface AsyncAPIOptions {
+    /** Required `info` block (title + version). */
+    info: AsyncAPIInfo;
+    /**
+     * Optional named servers exposed in the document. AsyncAPI keys servers by
+     * name (`{ production: { host, protocol } }`), not by an array.
+     */
+    servers?: Record<string, AsyncAPIServer>;
+}
+/**
+ * Generate an AsyncAPI 3.0 document from a registered {@link App}'s WebSocket
+ * routes.
+ *
+ * Every `app.ws()` route becomes one channel (its address + path parameters)
+ * and one or more operations:
+ *
+ * - a `receive` operation for client→server messages — payload taken from the
+ *   route's `meta.receive` schema, falling back to the handler's
+ *   `request.body` schema (the same schema used for payload-size checks).
+ * - a `send` operation for server→client messages — emitted only when the
+ *   route declares a `meta.send` schema.
+ *
+ * The output is a plain JSON-serializable object: hand it to AsyncAPI Studio,
+ * write it to disk for codegen, or serve it from a route. When the app has no
+ * WebSocket routes the document still validates, with empty `channels` and
+ * `operations` maps.
+ *
+ * @example
+ * ```ts
+ * import { generateAsyncAPI } from "@daloyjs/core/asyncapi";
+ * import { writeFileSync } from "node:fs";
+ *
+ * const doc = generateAsyncAPI(app, {
+ *   info: { title: "Realtime API", version: "1.0.0" },
+ *   servers: { production: { host: "api.example.com", protocol: "wss" } },
+ * });
+ * writeFileSync("./generated/asyncapi.json", JSON.stringify(doc, null, 2));
+ * ```
+ *
+ * @param app - The application whose WebSocket routes are documented.
+ * @param options - Document metadata and optional named servers.
+ * @returns A JSON-serializable AsyncAPI 3.0 document.
+ * @since 0.37.0
+ */
+export declare function generateAsyncAPI(app: App, options: AsyncAPIOptions): Record<string, unknown>;
+/**
+ * Serialize an AsyncAPI document to YAML.
+ *
+ * Thin alias over the dependency-free YAML 1.2 emitter shared with the
+ * OpenAPI generator ({@link openapiToYAML}) — AsyncAPI and OpenAPI documents
+ * are both plain JSON-compatible objects, so the same emitter applies.
+ *
+ * @param doc - The AsyncAPI document produced by {@link generateAsyncAPI}.
+ * @returns The document rendered as a YAML string.
+ * @since 0.37.0
+ */
+export declare function asyncapiToYAML(doc: Record<string, unknown>): string;