@daloyjs/core 0.36.0 → 0.38.0

package/dist/openapi-diff.js

@@ -0,0 +1,246 @@
+/**
+ * `@daloyjs/core/openapi-diff` — pure, dependency-free OpenAPI 3.x diffing.
+ *
+ * Compares two OpenAPI documents (a published *baseline* and a freshly
+ * generated *current* spec) and classifies every structural change as either
+ * **breaking** (a consumer relying on the baseline could now fail) or
+ * **non-breaking** (purely additive / informational). This is the engine
+ * behind the `daloy diff` CLI command and the `verify:breaking-changes` CI
+ * gate, answering the single question a contract-first framework should make
+ * trivial: *"did this change break my published API?"*
+ *
+ * The implementation walks plain JSON and never imports a schema validator or
+ * any runtime dependency, so it can run in any environment that can read two
+ * JSON files.
+ *
+ * @module
+ * @since 0.37.0
+ */
+/** HTTP methods recognized on an OpenAPI Path Item Object. */
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/** Narrow an unknown value to a plain object (non-null, non-array). */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Extract the `paths` object from a document, tolerating malformed input. */
+function pathsOf(doc) {
+    if (isObject(doc) && isObject(doc.paths))
+        return doc.paths;
+    return {};
+}
+/** Extract the OpenAPI Operation Objects keyed by HTTP method for a path item. */
+function operationsOf(pathItem) {
+    const ops = new Map();
+    if (!isObject(pathItem))
+        return ops;
+    for (const method of HTTP_METHODS) {
+        const op = pathItem[method];
+        if (isObject(op))
+            ops.set(method, op);
+    }
+    return ops;
+}
+/** Build a `${in}:${name}` keyed map of an operation's parameter objects. */
+function parametersOf(op) {
+    const out = new Map();
+    const params = op.parameters;
+    if (!Array.isArray(params))
+        return out;
+    for (const p of params) {
+        if (!isObject(p))
+            continue;
+        const name = typeof p.name === "string" ? p.name : "";
+        const loc = typeof p.in === "string" ? p.in : "";
+        if (name === "")
+            continue;
+        out.set(`${loc}:${name}`, p);
+    }
+    return out;
+}
+/** True when a parameter object is marked `required: true`. */
+function isRequiredParam(p) {
+    return p.required === true;
+}
+/** True when an operation's request body is marked `required: true`. */
+function requestBodyRequired(op) {
+    return isObject(op.requestBody) && op.requestBody.required === true;
+}
+/**
+ * Compare a baseline OpenAPI document against a current one and classify the
+ * differences. The comparison is intentionally conservative: anything that
+ * could cause a request that succeeded against the baseline to fail against
+ * the current spec is reported as **breaking**; additive and metadata-only
+ * changes are reported as **non-breaking**.
+ *
+ * Detected breaking changes:
+ * - a path or operation (HTTP method) present in the baseline is removed;
+ * - a documented response status code is removed from an operation;
+ * - a new `required` parameter is added to an existing operation;
+ * - an existing optional parameter becomes `required`;
+ * - an operation's request body becomes required when it was not.
+ *
+ * Detected non-breaking changes:
+ * - new paths, operations, response codes, or optional parameters;
+ * - a parameter is removed (the server no longer reads it);
+ * - an operation becomes `deprecated`;
+ * - the document `info.version` changes.
+ *
+ * @param baseline - The previously published OpenAPI document (JSON).
+ * @param current - The freshly generated OpenAPI document (JSON).
+ * @returns Structured lists of breaking and non-breaking changes.
+ * @since 0.37.0
+ */
+export function diffOpenAPI(baseline, current) {
+    const breaking = [];
+    const nonBreaking = [];
+    const basePaths = pathsOf(baseline);
+    const curPaths = pathsOf(current);
+    // info.version change (informational).
+    const baseVersion = isObject(baseline) && isObject(baseline.info) ? baseline.info.version : undefined;
+    const curVersion = isObject(current) && isObject(current.info) ? current.info.version : undefined;
+    if (baseVersion !== curVersion) {
+        nonBreaking.push({
+            severity: "non-breaking",
+            kind: "info.version.changed",
+            location: "info.version",
+            detail: `version changed from ${JSON.stringify(baseVersion)} to ${JSON.stringify(curVersion)}`,
+        });
+    }
+    for (const [path, baseItem] of Object.entries(basePaths)) {
+        const curItem = curPaths[path];
+        const baseOps = operationsOf(baseItem);
+        const curOps = operationsOf(curItem);
+        for (const [method, baseOp] of baseOps) {
+            const where = `${method.toUpperCase()} ${path}`;
+            const curOp = curOps.get(method);
+            if (!curOp) {
+                breaking.push({
+                    severity: "breaking",
+                    kind: "operation.removed",
+                    location: where,
+                    detail: `operation ${where} was removed`,
+                });
+                continue;
+            }
+            diffResponses(baseOp, curOp, where, breaking);
+            diffParameters(baseOp, curOp, where, breaking, nonBreaking);
+            diffRequestBody(baseOp, curOp, where, breaking);
+            if (curOp.deprecated === true && baseOp.deprecated !== true) {
+                nonBreaking.push({
+                    severity: "non-breaking",
+                    kind: "operation.deprecated",
+                    location: where,
+                    detail: `operation ${where} is now deprecated`,
+                });
+            }
+        }
+        // Operations added to an existing path.
+        for (const [method] of curOps) {
+            if (!baseOps.has(method)) {
+                nonBreaking.push({
+                    severity: "non-breaking",
+                    kind: "operation.added",
+                    location: `${method.toUpperCase()} ${path}`,
+                    detail: `operation ${method.toUpperCase()} ${path} was added`,
+                });
+            }
+        }
+    }
+    // Entirely new paths.
+    for (const [path, curItem] of Object.entries(curPaths)) {
+        if (path in basePaths)
+            continue;
+        for (const [method] of operationsOf(curItem)) {
+            nonBreaking.push({
+                severity: "non-breaking",
+                kind: "operation.added",
+                location: `${method.toUpperCase()} ${path}`,
+                detail: `operation ${method.toUpperCase()} ${path} was added`,
+            });
+        }
+    }
+    return { breaking, nonBreaking };
+}
+/** Report response status codes that existed in the baseline but were removed. */
+function diffResponses(baseOp, curOp, where, breaking) {
+    const baseResponses = isObject(baseOp.responses) ? baseOp.responses : {};
+    const curResponses = isObject(curOp.responses) ? curOp.responses : {};
+    for (const status of Object.keys(baseResponses)) {
+        if (!(status in curResponses)) {
+            breaking.push({
+                severity: "breaking",
+                kind: "response.removed",
+                location: `${where} → ${status}`,
+                detail: `response ${status} was removed from ${where}`,
+            });
+        }
+    }
+}
+/** Report parameter additions, removals, and requirement tightening. */
+function diffParameters(baseOp, curOp, where, breaking, nonBreaking) {
+    const baseParams = parametersOf(baseOp);
+    const curParams = parametersOf(curOp);
+    for (const [key, baseParam] of baseParams) {
+        const curParam = curParams.get(key);
+        if (!curParam) {
+            nonBreaking.push({
+                severity: "non-breaking",
+                kind: "parameter.removed",
+                location: `${where} (${key})`,
+                detail: `parameter ${key} was removed from ${where}`,
+            });
+            continue;
+        }
+        if (!isRequiredParam(baseParam) && isRequiredParam(curParam)) {
+            breaking.push({
+                severity: "breaking",
+                kind: "parameter.required.tightened",
+                location: `${where} (${key})`,
+                detail: `parameter ${key} on ${where} is now required`,
+            });
+        }
+    }
+    for (const [key, curParam] of curParams) {
+        if (baseParams.has(key))
+            continue;
+        if (isRequiredParam(curParam)) {
+            breaking.push({
+                severity: "breaking",
+                kind: "parameter.required.added",
+                location: `${where} (${key})`,
+                detail: `new required parameter ${key} was added to ${where}`,
+            });
+        }
+        else {
+            nonBreaking.push({
+                severity: "non-breaking",
+                kind: "parameter.added",
+                location: `${where} (${key})`,
+                detail: `new optional parameter ${key} was added to ${where}`,
+            });
+        }
+    }
+}
+/** Report a request body that became required when it previously was not. */
+function diffRequestBody(baseOp, curOp, where, breaking) {
+    if (!requestBodyRequired(baseOp) && requestBodyRequired(curOp)) {
+        breaking.push({
+            severity: "breaking",
+            kind: "requestBody.required.added",
+            location: where,
+            detail: `request body on ${where} is now required`,
+        });
+    }
+}
+/**
+ * Convenience predicate over {@link diffOpenAPI}: `true` when the current
+ * document introduces at least one breaking change versus the baseline.
+ *
+ * @param baseline - The previously published OpenAPI document (JSON).
+ * @param current - The freshly generated OpenAPI document (JSON).
+ * @returns `true` if any breaking change was detected.
+ * @since 0.37.0
+ */
+export function hasBreakingChanges(baseline, current) {
+    return diffOpenAPI(baseline, current).breaking.length > 0;
+}

package/dist/openapi.js

@@ -107,7 +107,10 @@ function buildOperation(route, path) {
             ? { description: route.description ?? meta?.description }
             : {}),
         ...(mergedTags.length ? { tags: mergedTags } : {}),
-        ...(route.deprecated ? { deprecated: true } : {}),
+        ...(route.deprecated || route.sunset ? { deprecated: true } : {}),
+        ...(route.sunset
+            ? { "x-sunset": route.sunset }
+            : {}),
     };
     const parameters = [];
     if (path) {

package/dist/pagination.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Cursor pagination helpers for DaloyJS.
+ *
+ * Contract-first list endpoints need three things the framework did not yet
+ * ship: an **opaque cursor** the client can echo back without depending on its
+ * internals, an **RFC 8288 `Link` header** advertising the `next` / `prev` /
+ * `first` pages, and **OpenAPI parameter wiring** so the `cursor` / `limit`
+ * query parameters appear in the generated spec and typed client. This module
+ * provides all three with zero runtime dependencies:
+ *
+ * - {@link encodeCursor} / {@link decodeCursor} — base64url-encode an arbitrary
+ *   JSON-serializable payload (typically the sort key of the last row) into an
+ *   opaque, URL-safe token, and decode it back with prototype-pollution-safe
+ *   parsing and a hard size cap.
+ * - {@link buildLinkHeader} / {@link buildPageLinks} — assemble a Web-standard
+ *   `Link` header, with CRLF / angle-bracket header-injection guards baked in.
+ * - {@link paginationQuery} — a Standard Schema validator for the `cursor` +
+ *   `limit` query parameters that both validates at runtime (clamping `limit`
+ *   to a safe range) **and** advertises itself to the OpenAPI generator via a
+ *   `toJSONSchema()` method, so `request: { query: paginationQuery() }` wires
+ *   the parameters into the contract with no extra code.
+ *
+ * Everything here is built on Web-standard `URL` / `Request` and `btoa` /
+ * `atob`, so it runs unchanged on Node, Bun, Deno, Cloudflare Workers, and
+ * Vercel Edge.
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { StandardSchemaV1 } from "./schema.js";
+/**
+ * Hard cap on the length of an encoded cursor string accepted by
+ * {@link decodeCursor}. Bounds the work an attacker can force by sending a
+ * giant `cursor` query parameter. 4 KiB is far larger than any legitimate
+ * sort-key payload.
+ */
+export declare const MAX_CURSOR_LENGTH = 4096;
+/**
+ * Encode an arbitrary JSON-serializable value into an opaque, URL-safe cursor
+ * token (base64url, no padding).
+ *
+ * The token is **opaque, not secret**: it is encoded, not encrypted or signed.
+ * Never trust a decoded cursor for authorization — always re-scope the
+ * underlying query by the authenticated principal on the server. Put only the
+ * data you need to resume a scan (e.g. `{ id, createdAt }`) inside it.
+ *
+ * @param payload - Any JSON-serializable value (object, array, string, …).
+ * @returns A base64url cursor string safe to place in a URL or `Link` header.
+ * @throws {TypeError} If `payload` cannot be JSON-serialized (e.g. a `BigInt`
+ *   or a circular structure).
+ * @since 0.37.0
+ */
+export declare function encodeCursor(payload: unknown): string;
+/**
+ * Decode an opaque cursor produced by {@link encodeCursor} back into its
+ * original value.
+ *
+ * Parsing is hardened: the input length is capped at {@link MAX_CURSOR_LENGTH},
+ * decoding rejects malformed base64url, and any `__proto__` / `constructor` /
+ * `prototype` keys in the decoded object graph are stripped (prototype-
+ * pollution defense, mirroring the core body parsers).
+ *
+ * @typeParam T - The expected shape of the decoded payload (caller-asserted).
+ * @param cursor - The opaque cursor string from the request.
+ * @returns The decoded payload.
+ * @throws {BadRequestError} If the cursor is missing, over-long, or malformed —
+ *   a `400` so a tampered cursor surfaces as a client error, not a `500`.
+ * @since 0.37.0
+ */
+export declare function decodeCursor<T = unknown>(cursor: string): T;
+/** A single web link for an RFC 8288 `Link` header. */
+export interface PaginationLink {
+    /** Target URI-Reference (the `<...>` portion). */
+    url: string;
+    /** Relation type, e.g. `"next"`, `"prev"`, `"first"`, `"last"`. */
+    rel: string;
+    /** Optional human-readable `title` parameter. */
+    title?: string;
+}
+/**
+ * Serialize a list of links into a single RFC 8288 `Link` header value.
+ *
+ * Each entry renders as `<url>; rel="rel"` (plus `; title="…"` when present).
+ * URLs containing control characters, `<`, or `>` and rel/title values
+ * containing control characters, `"`, or `\` are rejected — a structural
+ * defense against `Link`-header / response-splitting injection.
+ *
+ * @param links - The links to emit. An empty array yields an empty string.
+ * @returns The comma-joined `Link` header value.
+ * @throws {Error} If any URL or token contains forbidden characters.
+ * @since 0.37.0
+ */
+export declare function buildLinkHeader(links: readonly PaginationLink[]): string;
+/** Options for {@link buildPageLinks}. */
+export interface PageLinkOptions {
+    /** The current request URL (string or `URL`); other query params are kept. */
+    url: string | URL;
+    /** Query-parameter name carrying the cursor. Default: `"cursor"`. */
+    cursorParam?: string;
+    /** Opaque cursor for the next page, or `null`/`undefined` to omit `next`. */
+    next?: string | null;
+    /** Opaque cursor for the previous page, or `null`/`undefined` to omit `prev`. */
+    prev?: string | null;
+    /**
+     * Emit a `rel="first"` link (the current URL with the cursor param removed).
+     * Default: `false`.
+     */
+    first?: boolean;
+    /** Extra links appended verbatim (e.g. a `rel="last"`). */
+    extraLinks?: readonly PaginationLink[];
+}
+/** Result of {@link buildPageLinks}. */
+export interface PageLinks {
+    /** The structured links, ready for {@link buildLinkHeader} or a JSON body. */
+    links: PaginationLink[];
+    /** The serialized RFC 8288 `Link` header value (empty when no links). */
+    linkHeader: string;
+    /** Convenience map of the computed page URLs. */
+    urls: {
+        self: string;
+        next?: string;
+        prev?: string;
+        first?: string;
+    };
+}
+/**
+ * Build the `next` / `prev` / `first` page URLs for a list response by cloning
+ * the current request URL and swapping its cursor query parameter, then
+ * serialize them into an RFC 8288 `Link` header.
+ *
+ * All other query parameters (filters, `limit`, …) are preserved, so the
+ * generated links are drop-in "give me the same query, next page" URLs.
+ *
+ * @example
+ * ```ts
+ * const { linkHeader } = buildPageLinks({
+ *   url: ctx.request.url,
+ *   next: nextCursor,        // from encodeCursor(...)
+ *   prev: prevCursor,
+ *   first: true,
+ * });
+ * set.headers.set("Link", linkHeader);
+ * ```
+ *
+ * @param opts - Current URL plus the cursors to advertise.
+ * @returns The structured links, the `Link` header string, and the page URLs.
+ * @since 0.37.0
+ */
+export declare function buildPageLinks(opts: PageLinkOptions): PageLinks;
+/** Options for {@link paginationQuery}. */
+export interface PaginationQueryOptions {
+    /** Query-parameter name for the cursor. Default: `"cursor"`. */
+    cursorParam?: string;
+    /** Query-parameter name for the page size. Default: `"limit"`. */
+    limitParam?: string;
+    /** Default page size applied when `limit` is omitted. Default: `min(20, maxLimit)`. */
+    defaultLimit?: number;
+    /** Minimum accepted page size. Default: `1`. */
+    minLimit?: number;
+    /** Maximum accepted page size (also caps over-large requests). Default: `100`. */
+    maxLimit?: number;
+}
+/** Validated output of {@link paginationQuery}. */
+export interface PaginationParams {
+    /** The resolved page size, clamped to `[minLimit, maxLimit]`. */
+    limit: number;
+    /** The opaque cursor, if the client supplied one. */
+    cursor?: string;
+}
+/**
+ * A Standard Schema for cursor-pagination query parameters that also carries a
+ * `toJSONSchema()` method so the OpenAPI generator wires the `cursor` and
+ * `limit` parameters into the contract automatically.
+ */
+export interface PaginationQuerySchema extends StandardSchemaV1<Record<string, unknown>, PaginationParams> {
+    /** Used by the OpenAPI generator to emit the query parameters. */
+    toJSONSchema(): Record<string, unknown>;
+}
+/**
+ * Build a Standard Schema validator for cursor-pagination query parameters.
+ *
+ * Use it as a route's `request.query`. At runtime it parses and validates
+ * `limit` (coerced from its string query value to an integer and clamped to
+ * `[minLimit, maxLimit]`, defaulting to `defaultLimit` when absent) and passes
+ * `cursor` through as an optional opaque string. Because it also exposes
+ * `toJSONSchema()`, the same call wires both parameters into the generated
+ * OpenAPI document and typed client — no duplicate parameter declarations.
+ *
+ * @example
+ * ```ts
+ * app.route({
+ *   method: "GET",
+ *   path: "/books",
+ *   operationId: "listBooks",
+ *   request: { query: paginationQuery({ defaultLimit: 25, maxLimit: 100 }) },
+ *   responses: { 200: { description: "ok", body: pageSchema } },
+ *   handler: async ({ query }) => {
+ *     const { limit, cursor } = query; // fully typed + validated
+ *     // ...
+ *   },
+ * });
+ * ```
+ *
+ * @param opts - Parameter names and page-size bounds.
+ * @returns A Standard Schema usable as `request.query`.
+ * @throws {Error} If the configured bounds are not positive integers or are
+ *   inconsistent (`minLimit > maxLimit`, `defaultLimit` out of range).
+ * @since 0.37.0
+ */
+export declare function paginationQuery(opts?: PaginationQueryOptions): PaginationQuerySchema;