@nifrajs/schema 0.1.0-alpha.1

package/dist/t.js

@@ -0,0 +1,49 @@
+import { Type, } from "@sinclair/typebox";
+import { fromTypeBox } from "./adapter.js";
+/** Pull each property's raw TypeBox schema out of its `NifraSchema` wrapper. */
+function unwrap(props) {
+    const out = {};
+    // Object.entries → own enumerable string keys only (no prototype walk).
+    for (const [key, schema] of Object.entries(props))
+        out[key] = schema.jsonSchema;
+    return out;
+}
+/**
+ * The built-in schema builder. Each constructor returns a `NifraSchema` — a
+ * Standard Schema whose validated output type flows into `c.body`/`c.query`, and
+ * whose `jsonSchema` powers `toOpenAPI`. Options (min/max, length, pattern, …)
+ * pass straight through to TypeBox and so become JSON Schema constraints.
+ *
+ * Composite constructors are generic over the *inner* TypeBox schema `T extends
+ * TSchema` (not over `NifraSchema`): reading `.jsonSchema` off a value typed only as
+ * `NifraSchema` would erase to the `TSchema` constraint and collapse the output type
+ * to `unknown`. Capturing `T` keeps `Static<T>` precise (`string[]`, not
+ * `unknown[]`).
+ */
+export const t = {
+    string: (options) => fromTypeBox(Type.String(options)),
+    number: (options) => fromTypeBox(Type.Number(options)),
+    integer: (options) => fromTypeBox(Type.Integer(options)),
+    boolean: () => fromTypeBox(Type.Boolean()),
+    null: () => fromTypeBox(Type.Null()),
+    literal: (value) => fromTypeBox(Type.Literal(value)),
+    // `t.object` REJECTS unknown fields by default (`additionalProperties: false`) — the trust-boundary
+    // rule. A body with extra keys fails validation (a 400), so `c.body` never carries attacker-supplied
+    // properties (no mass-assignment). Use `t.looseObject` (or pass `{ additionalProperties: true }`) to
+    // opt into an open object; an explicit `options.additionalProperties` always wins over the default.
+    object: (props, options) => fromTypeBox(Type.Object(unwrap(props), { additionalProperties: false, ...options })),
+    /** Like `t.object` but ACCEPTS (and passes through) unknown fields — the explicit opt-out of the
+     * strict default. Prefer `t.object` unless you genuinely need an open object. */
+    looseObject: (props, options) => fromTypeBox(Type.Object(unwrap(props), { additionalProperties: true, ...options })),
+    array: (item, options) => fromTypeBox(Type.Array(item.jsonSchema, options)),
+    /** Marks a property optional inside `t.object`; standalone it is `T | undefined`. */
+    optional: (schema) => fromTypeBox(Type.Optional(schema.jsonSchema)),
+    // `const S` captures the argument as a tuple; the explicit return type then maps
+    // over that captured tuple (`S[K]["jsonSchema"]`) so the union's `Static` is
+    // `A | B`, not `unknown` — the value-level `.map` can't preserve per-element
+    // types, so the output type is derived from `S` and the result cast to match
+    // (order/length are preserved by `map`, so the tuple shape is sound).
+    union: (schemas) => fromTypeBox(Type.Union(schemas.map((schema) => schema.jsonSchema))),
+    record: (value, options) => fromTypeBox(Type.Record(Type.String(), value.jsonSchema, options)),
+};
+//# sourceMappingURL=t.js.map

package/dist/t.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"t.js","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,IAAI,GACL,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAA;AAI5D,gFAAgF;AAChF,SAAS,MAAM,CAAkB,KAAQ;IACvC,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,wEAAwE;IACxE,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,UAAU,CAAA;IAC/E,OAAO,GAA6C,CAAA;AACtD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,CAAC,GAAG;IACf,MAAM,EAAE,CAAC,OAAuB,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtE,MAAM,EAAE,CAAC,OAAuB,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtE,OAAO,EAAE,CAAC,OAAwB,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IAC1C,IAAI,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACpC,OAAO,EAAE,CAAgC,KAAQ,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAEtF,oGAAoG;IACpG,qGAAqG;IACrG,qGAAqG;IACrG,oGAAoG;IACpG,MAAM,EAAE,CAAkB,KAAQ,EAAE,OAAuB,EAAE,EAAE,CAC7D,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACtF;qFACiF;IACjF,WAAW,EAAE,CAAkB,KAAQ,EAAE,OAAuB,EAAE,EAAE,CAClE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrF,KAAK,EAAE,CAAoB,IAAoB,EAAE,OAAsB,EAAE,EAAE,CACzE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACnD,qFAAqF;IACrF,QAAQ,EAAE,CAAoB,MAAsB,EAAE,EAAE,CACtD,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/C,iFAAiF;IACjF,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,sEAAsE;IACtE,KAAK,EAAE,CAAyC,OAAU,EAAE,EAAE,CAC5D,WAAW,CACT,IAAI,CAAC,KAAK,CAAE,OAAkC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CACV;IAC5E,MAAM,EAAE,CAAoB,KAAqB,EAAE,OAAuB,EAAE,EAAE,CAC5E,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;CAC5D,CAAA"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@nifrajs/schema",
+  "version": "0.1.0-alpha.1",
+  "description": "Built-in schema builder `t` — TypeBox-backed (free JSON Schema + compiled validators), implements Standard Schema so nifra routes validate it natively.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr",
+    "validation",
+    "typebox",
+    "json-schema",
+    "standard-schema"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./openapi": {
+      "bun": "./src/openapi.ts",
+      "types": "./dist/openapi.d.ts",
+      "default": "./dist/openapi.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "comment:sideEffects": "formats.ts registers string formats into TypeBox's global FormatRegistry on import — that file must not be tree-shaken away, so it (not the package) is marked side-effectful.",
+  "sideEffects": [
+    "./src/formats.ts",
+    "./dist/formats.js"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49"
+  },
+  "peerDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*",
+    "@nifrajs/test-utils": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/schema"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/adapter.ts

@@ -0,0 +1,78 @@
+import type { StandardIssue, StandardResult, StandardSchemaV1, StandardTypes } from "@nifrajs/core"
+import type { Static, TSchema } from "@sinclair/typebox"
+import { type TypeCheck, TypeCompiler } from "@sinclair/typebox/compiler"
+import { Value } from "@sinclair/typebox/value"
+
+/**
+ * A `t` schema. It is a Standard Schema (so any nifra route validates it with no
+ * special-casing) whose raw TypeBox definition stays reachable as `jsonSchema` —
+ * and because a TypeBox schema *is* a JSON Schema, that field is exactly what lets
+ * `toOpenAPI` emit a real request/response schema for the route. BYO Standard
+ * Schemas (zod/valibot/arktype) validate too but expose no JSON Schema, so only
+ * `t`-based routes get full OpenAPI.
+ */
+export type NifraSchema<T extends TSchema = TSchema> = StandardSchemaV1<Static<T>, Static<T>> & {
+  readonly jsonSchema: T
+}
+
+/**
+ * Map a TypeBox validation error to a Standard Schema issue. TypeBox reports JSON
+ * Pointers (`"/name"`, `"/items/0"`); Standard Schema wants a segment array (`""` is
+ * the document root → no path). The compiled checker and the eval-free `Value`
+ * checker emit the same error shape, so both validation paths share this.
+ */
+function toIssue(error: { readonly message: string; readonly path: string }): StandardIssue {
+  return {
+    message: error.message,
+    path: error.path === "" ? undefined : error.path.slice(1).split("/"),
+  }
+}
+
+/**
+ * Wrap a TypeBox schema as a `NifraSchema`.
+ *
+ * **Validation is fast where it can be, and works everywhere.** The first `validate`
+ * builds a compiled `TypeCompiler` validator (codegen via `new Function`) and memoizes
+ * it — composing schemas (`t.object({ a: t.string() })`) never compiles the inner
+ * pieces; only a schema actually used to validate a request pays the one-time codegen
+ * cost. On Bun and Node this is the only path and it is untouched.
+ *
+ * Edge runtimes (Cloudflare Workers, Vercel Edge, Deno Deploy) **forbid dynamic code
+ * generation**, so that first compile throws there. We catch it once per schema and
+ * fall back to TypeBox's eval-free `Value` checker — same semantics (and same global
+ * `FormatRegistry`, so `t.string({ format })` behaves identically), no `new Function`.
+ * The branch is decided once and memoized, so the hot path is a single check either way.
+ *
+ * Exposed (not just used internally by `t`) so a TypeBox schema authored directly can
+ * be adapted without leaving the Standard Schema world.
+ */
+export function fromTypeBox<T extends TSchema>(schema: T): NifraSchema<T> {
+  let compiled: TypeCheck<T> | undefined
+  let evalFree = false
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "nifra",
+      validate: (value: unknown): StandardResult<Static<T>> => {
+        if (compiled === undefined && !evalFree) {
+          try {
+            compiled = TypeCompiler.Compile(schema)
+          } catch {
+            // Dynamic codegen disallowed (edge): take the eval-free path for this schema.
+            evalFree = true
+          }
+        }
+        if (compiled !== undefined) {
+          if (compiled.Check(value)) return { value }
+          return { issues: [...compiled.Errors(value)].map(toIssue) }
+        }
+        if (Value.Check(schema, value)) return { value }
+        return { issues: [...Value.Errors(schema, value)].map(toIssue) }
+      },
+      // Phantom: `types` carries no runtime value; this cast supplies the
+      // compile-time `Static<T>` that nifra's `InferOutput` reads to type `c.body`.
+      types: undefined as unknown as StandardTypes<Static<T>, Static<T>>,
+    },
+    jsonSchema: schema,
+  }
+}

package/src/formats.ts

@@ -0,0 +1,33 @@
+import { FormatRegistry } from "@sinclair/typebox"
+
+/**
+ * Standard JSON Schema string formats, registered with TypeBox so `t.string({
+ * format })` both **validates** and **annotates** the JSON Schema (the latter feeds
+ * OpenAPI). This registration is the reason it works at all: TypeBox treats an
+ * *unregistered* format as a hard failure, so without it `t.string({ format:
+ * "email" })` would reject every value.
+ *
+ * Patterns are pragmatic (not full RFC grammars) but reject obvious garbage. Need a
+ * stricter rule or a format not listed here (e.g. `ipv6`, `hostname`)? Register it
+ * with {@link registerFormat}. Importing this module performs the registration as a
+ * one-time side effect; the `Has` guard means an app that registered its own
+ * validator first wins.
+ */
+const DEFAULT_FORMATS: Readonly<Record<string, RegExp>> = {
+  email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+  uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+  "date-time": /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/,
+  date: /^\d{4}-\d{2}-\d{2}$/,
+  time: /^\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})?$/,
+  uri: /^[a-z][a-z0-9+.-]*:\S+$/i,
+  ipv4: /^(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/,
+}
+
+/** Register (or override) a string format usable as `t.string({ format: name })`. */
+export function registerFormat(name: string, validate: (value: string) => boolean): void {
+  FormatRegistry.Set(name, validate)
+}
+
+for (const [name, pattern] of Object.entries(DEFAULT_FORMATS)) {
+  if (!FormatRegistry.Has(name)) FormatRegistry.Set(name, (value) => pattern.test(value))
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * `@nifrajs/schema` — the optional, batteries-included schema builder for nifra.
+ *
+ * `t` is TypeBox-backed: validators are compiled (fast) and every schema is a JSON
+ * Schema (free OpenAPI). It implements Standard Schema, so `@nifrajs/core` validates
+ * it through the exact same path as any BYO library — `@nifrajs/core` never depends on
+ * a validator; this package is the opt-in default.
+ */
+export { fromTypeBox, type NifraSchema } from "./adapter.ts"
+// Re-exporting evaluates ./formats.ts, registering the standard string formats so
+// `t.string({ format })` validates instead of rejecting everything.
+export { registerFormat } from "./formats.ts"
+export { type OpenAPIDocument, type OpenAPIInfo, toOpenAPI } from "./openapi.ts"
+export { t } from "./t.ts"

package/src/openapi.ts

@@ -0,0 +1,358 @@
+import type { ContractShape, Server, StandardSchemaV1 } from "@nifrajs/core"
+
+/**
+ * OpenAPI 3.1 generation. We model a practical slice of the spec — enough to feed Swagger UI / codegen
+ * and to validate structurally: paths, parameters, request bodies, responses (incl. non-200 and
+ * non-JSON), tags, security, servers, and `$ref` reuse via `components.schemas`.
+ *
+ * Schemas carry full detail only for `t`/TypeBox inputs (they expose a JSON Schema); a BYO Standard
+ * Schema validates at runtime but exposes no JSON Schema, so its route is emitted without body/response
+ * detail. A **contract** is richest — its operations carry `response`, `tags`, `security`, additional
+ * `responses`, etc.; an **app** emits request shapes + a generic `200` (an inline handler has no
+ * response *schema* to serialize), enrichable via `options.operations`.
+ */
+export interface OpenAPIInfo {
+  readonly title: string
+  readonly version: string
+  readonly description?: string
+}
+
+export interface OpenAPIServer {
+  readonly url: string
+  readonly description?: string
+}
+
+export interface OpenAPITag {
+  readonly name: string
+  readonly description?: string
+}
+
+/** A document-wide / per-operation security requirement: scheme name → required scopes. */
+export type SecurityRequirement = Readonly<Record<string, readonly string[]>>
+
+export interface ToOpenAPIOptions {
+  readonly title?: string
+  readonly version?: string
+  readonly description?: string
+  /** Server URLs the API is served from (OpenAPI `servers`). */
+  readonly servers?: readonly OpenAPIServer[]
+  /** Tag definitions (OpenAPI top-level `tags`) — names referenced by an operation's `tags`. */
+  readonly tags?: readonly OpenAPITag[]
+  /** Reusable security schemes → `components.securitySchemes` (e.g. `{ bearer: { type: "http", scheme: "bearer" } }`). */
+  readonly securitySchemes?: Readonly<Record<string, Record<string, unknown>>>
+  /** Document-wide security requirement; a per-operation `security` (incl. `[]` for public) overrides it. */
+  readonly security?: readonly SecurityRequirement[]
+  /**
+   * Per-operation overrides, shallow-merged over the generated operation. Keyed by `operationId`
+   * (contract op name) or `"METHOD /path"` (e.g. `"GET /users/:id"`). The escape hatch for detail that
+   * can't be introspected — richer response bodies, examples, app-route tags/security.
+   */
+  readonly operations?: Readonly<Record<string, Record<string, unknown>>>
+}
+
+type JsonSchema = Record<string, unknown>
+
+interface OpenAPIParameter {
+  readonly name: string
+  readonly in: "path" | "query"
+  readonly required: boolean
+  readonly schema: JsonSchema
+}
+
+interface OpenAPIMediaType {
+  readonly schema: JsonSchema
+}
+
+interface OpenAPIRequestBody {
+  readonly required: boolean
+  readonly content: Record<string, OpenAPIMediaType>
+}
+
+interface OpenAPIResponse {
+  description: string
+  content?: Record<string, OpenAPIMediaType>
+}
+
+interface OpenAPIOperation {
+  operationId?: string
+  summary?: string
+  description?: string
+  tags?: readonly string[]
+  deprecated?: boolean
+  security?: readonly SecurityRequirement[]
+  parameters?: OpenAPIParameter[]
+  requestBody?: OpenAPIRequestBody
+  responses: Record<string, OpenAPIResponse>
+}
+
+interface OpenAPIComponents {
+  schemas?: Record<string, JsonSchema>
+  securitySchemes?: Readonly<Record<string, Record<string, unknown>>>
+}
+
+export interface OpenAPIDocument {
+  readonly openapi: "3.1.0"
+  readonly info: OpenAPIInfo
+  readonly paths: Record<string, Record<string, OpenAPIOperation>>
+  readonly servers?: readonly OpenAPIServer[]
+  readonly tags?: readonly OpenAPITag[]
+  readonly security?: readonly SecurityRequirement[]
+  readonly components?: OpenAPIComponents
+}
+
+/** A Standard Schema that also carries a raw JSON Schema (i.e. a `t`/TypeBox schema). */
+type WithJsonSchema = StandardSchemaV1 & { readonly jsonSchema: unknown }
+
+function hasJsonSchema(schema: StandardSchemaV1): schema is WithJsonSchema {
+  return (
+    "jsonSchema" in schema &&
+    (schema as { jsonSchema?: unknown }).jsonSchema !== undefined &&
+    (schema as { jsonSchema?: unknown }).jsonSchema !== null
+  )
+}
+
+/**
+ * Extract clean JSON Schema from a schema, or `undefined` for a BYO Standard Schema with no JSON
+ * Schema. The `JSON` round-trip strips TypeBox's Symbol-keyed metadata; a string `$id` survives it and
+ * drives `$ref` reuse.
+ */
+function toJsonSchema(schema: StandardSchemaV1): JsonSchema | undefined {
+  if (!hasJsonSchema(schema)) return undefined
+  return JSON.parse(JSON.stringify(schema.jsonSchema)) as JsonSchema
+}
+
+/**
+ * Collects schemas that carry a `$id` into `components.schemas`, returning a `$ref` in their place —
+ * so a schema used by N operations is emitted once. Schemas without a `$id` stay inline (the existing
+ * behavior). The first sighting of an id wins; later ones just `$ref` it.
+ */
+class SchemaStore {
+  readonly schemas: Record<string, JsonSchema> = {}
+
+  /** Hoist a schema with a `$id` into components + return a `$ref`; otherwise return it inline. */
+  collect(schema: JsonSchema | undefined): JsonSchema | undefined {
+    if (schema === undefined) return undefined
+    const id = typeof schema.$id === "string" ? schema.$id : undefined
+    if (id === undefined) return schema
+    if (this.schemas[id] === undefined) {
+      const hoisted = { ...schema }
+      delete hoisted.$id // the component key is the name; drop the redundant base-URI hint
+      this.schemas[id] = hoisted
+    }
+    return { $ref: `#/components/schemas/${id}` }
+  }
+}
+
+/** Name of a path segment's parameter, or `undefined` for a static segment. */
+function segmentParam(segment: string): string | undefined {
+  if (segment.startsWith(":")) return segment.slice(1)
+  if (segment.startsWith("*")) return segment.length > 1 ? segment.slice(1) : "wildcard"
+  return undefined
+}
+
+/** `/users/:id/*rest` → `/users/{id}/{rest}` (OpenAPI path templating). */
+function toTemplatedPath(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => {
+      const param = segmentParam(segment)
+      return param === undefined ? segment : `{${param}}`
+    })
+    .join("/")
+}
+
+function pathParameters(path: string): OpenAPIParameter[] {
+  const params: OpenAPIParameter[] = []
+  for (const segment of path.split("/")) {
+    const name = segmentParam(segment)
+    // Path params are always strings (decoded from the URL).
+    if (name !== undefined)
+      params.push({ name, in: "path", required: true, schema: { type: "string" } })
+  }
+  return params
+}
+
+function queryParameters(schema: StandardSchemaV1 | undefined): OpenAPIParameter[] {
+  if (schema === undefined) return []
+  const json = toJsonSchema(schema)
+  // Only an object schema decomposes into individual query parameters.
+  if (json === undefined || json.type !== "object" || typeof json.properties !== "object") return []
+  const properties = json.properties as Record<string, JsonSchema>
+  const required = Array.isArray(json.required) ? (json.required as string[]) : []
+  return Object.entries(properties).map(([name, propSchema]) => ({
+    name,
+    in: "query",
+    required: required.includes(name),
+    schema: propSchema,
+  }))
+}
+
+interface OperationInput {
+  readonly path: string
+  readonly body: StandardSchemaV1 | undefined
+  readonly query: StandardSchemaV1 | undefined
+  readonly response: StandardSchemaV1 | undefined
+  readonly operationId: string | undefined
+  // `| undefined` (not just `?`) so a contract op's optional fields — `string | undefined` etc. — are
+  // assignable under `exactOptionalPropertyTypes` when spread into this literal.
+  readonly summary?: string | undefined
+  readonly description?: string | undefined
+  readonly tags?: readonly string[] | undefined
+  readonly deprecated?: boolean | undefined
+  readonly security?: readonly SecurityRequirement[] | undefined
+  readonly requestContentType?: string | undefined
+  readonly responseContentType?: string | undefined
+  readonly responses?:
+    | Readonly<
+        Record<string, { description?: string; schema?: StandardSchemaV1; contentType?: string }>
+      >
+    | undefined
+}
+
+function buildResponses(
+  input: OperationInput,
+  store: SchemaStore,
+): Record<string, OpenAPIResponse> {
+  const responses: Record<string, OpenAPIResponse> = {}
+  if (input.response !== undefined) {
+    const schema = store.collect(toJsonSchema(input.response))
+    responses["200"] =
+      schema !== undefined
+        ? {
+            description: "OK",
+            content: { [input.responseContentType ?? "application/json"]: { schema } },
+          }
+        : { description: "OK" }
+  } else {
+    responses["200"] = { description: "OK" }
+  }
+  // Additional (or overriding) responses declared on the contract op.
+  if (input.responses !== undefined) {
+    for (const [status, def] of Object.entries(input.responses)) {
+      const response: OpenAPIResponse = { description: def.description ?? "" }
+      const schema = def.schema !== undefined ? store.collect(toJsonSchema(def.schema)) : undefined
+      if (schema !== undefined)
+        response.content = { [def.contentType ?? "application/json"]: { schema } }
+      responses[status] = response
+    }
+  }
+  return responses
+}
+
+function buildOperation(input: OperationInput, store: SchemaStore): OpenAPIOperation {
+  const operation: OpenAPIOperation = { responses: buildResponses(input, store) }
+  if (input.operationId !== undefined) operation.operationId = input.operationId
+  if (input.summary !== undefined) operation.summary = input.summary
+  if (input.description !== undefined) operation.description = input.description
+  if (input.tags !== undefined && input.tags.length > 0) operation.tags = input.tags
+  if (input.deprecated === true) operation.deprecated = true
+  if (input.security !== undefined) operation.security = input.security // `[]` ⇒ explicitly public
+
+  const parameters = [...pathParameters(input.path), ...queryParameters(input.query)]
+  if (parameters.length > 0) operation.parameters = parameters
+
+  if (input.body !== undefined) {
+    const schema = store.collect(toJsonSchema(input.body))
+    if (schema !== undefined) {
+      operation.requestBody = {
+        required: true,
+        content: { [input.requestContentType ?? "application/json"]: { schema } },
+      }
+    }
+  }
+  return operation
+}
+
+function addOperation(
+  paths: Record<string, Record<string, OpenAPIOperation>>,
+  method: string,
+  input: OperationInput,
+  store: SchemaStore,
+  operations: ToOpenAPIOptions["operations"],
+): void {
+  const templated = toTemplatedPath(input.path)
+  const pathItem = paths[templated] ?? {}
+  paths[templated] = pathItem
+  let operation = buildOperation(input, store)
+  // Shallow-merge an override keyed by operationId or "METHOD /path".
+  const override =
+    operations?.[input.operationId ?? ""] ?? operations?.[`${method.toUpperCase()} ${input.path}`]
+  if (override !== undefined) operation = { ...operation, ...override } as OpenAPIOperation
+  pathItem[method.toLowerCase()] = operation
+}
+
+function isApp(input: ContractShape | Server): input is Server {
+  // Duck-typed so @nifrajs/schema keeps @nifrajs/core a type-only dependency. A contract
+  // is a plain record of operations; only a Server exposes a `routes()` method.
+  return typeof (input as { routes?: unknown }).routes === "function"
+}
+
+/** Generate an OpenAPI 3.1 document from a contract or a running app. See the module doc for the detail model. */
+export function toOpenAPI(
+  input: ContractShape | Server,
+  options: ToOpenAPIOptions = {},
+): OpenAPIDocument {
+  const paths: Record<string, Record<string, OpenAPIOperation>> = {}
+  const store = new SchemaStore()
+
+  if (isApp(input)) {
+    for (const route of input.routes()) {
+      addOperation(
+        paths,
+        route.method,
+        {
+          path: route.path,
+          body: route.schema?.body,
+          query: route.schema?.query,
+          // A route may now declare a `response` contract — emit it as the 200 body schema.
+          response: route.schema?.response,
+          operationId: undefined,
+        },
+        store,
+        options.operations,
+      )
+    }
+  } else {
+    for (const [name, op] of Object.entries(input)) {
+      addOperation(
+        paths,
+        op.method,
+        {
+          path: op.path,
+          body: op.body,
+          query: op.query,
+          response: op.response,
+          operationId: name,
+          summary: op.summary,
+          description: op.description,
+          tags: op.tags,
+          deprecated: op.deprecated,
+          security: op.security,
+          requestContentType: op.requestContentType,
+          responseContentType: op.responseContentType,
+          responses: op.responses,
+        },
+        store,
+        options.operations,
+      )
+    }
+  }
+
+  const components: OpenAPIComponents = {}
+  if (Object.keys(store.schemas).length > 0) components.schemas = store.schemas
+  if (options.securitySchemes !== undefined) components.securitySchemes = options.securitySchemes
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: options.title ?? "API",
+      version: options.version ?? "1.0.0",
+      ...(options.description !== undefined ? { description: options.description } : {}),
+    },
+    paths,
+    ...(options.servers !== undefined ? { servers: options.servers } : {}),
+    ...(options.tags !== undefined ? { tags: options.tags } : {}),
+    ...(options.security !== undefined ? { security: options.security } : {}),
+    ...(Object.keys(components).length > 0 ? { components } : {}),
+  }
+}