@znight/openapi 0.0.0-stage → 0.1.0

package/dist/build-BTUC96mY.d.mts

@@ -0,0 +1,174 @@
+import { A as SecuritySchemeObject, P as TagObject, _ as OpenApiObject, a as ExternalDocumentationObject, c as InfoObject, g as OpenApiMethod, j as ServerObject, k as SecurityRequirementObject, l as JsonSchema, u as JsonValue, y as OperationObjectOf } from "./types-VzBexMKj.mjs";
+import { ErrorCode, Token, ZnightMetadata } from "@znight/core";
+import { StandardSchemaV1 } from "@znight/http";
+/** What a converter receives next to the schema. */
+interface SchemaConverterContext {
+  /** `input` for requests (what clients send), `output` for responses (what the server sends). */
+  readonly io: "input" | "output";
+  readonly target: "draft-2020-12";
+  /** Retry after a failure with `unrepresentable: 'warn'`: approximate instead of throwing. */
+  readonly lenient: boolean;
+}
+/** Converts Standard Schemas of one library to JSON Schema 2020-12. */
+interface SchemaConverter {
+  readonly name: string;
+  /** `undefined`: not supported, the next converter is tried. Throwing reports ZNIGHT037. */
+  convert(schema: StandardSchemaV1, context: SchemaConverterContext): JsonSchema | undefined | Promise<JsonSchema | undefined>;
+}
+/**
+ * Standard JSON Schema (`schema['~standard'].jsonSchema[io]({ target: 'draft-2020-12' })`): Zod ≥ 4.2,
+ * ArkType ≥ 2.1.28 and every library implementing the interface.
+ */
+declare const standardJsonSchemaConverter: SchemaConverter;
+/** Valibot schemas (no `~standard.jsonSchema`) through `toStandardJsonSchema()` of `@valibot/to-json-schema`. */
+declare const valibotConverter: SchemaConverter;
+/** Built-in converters, tried after the user's. */
+declare const BUILT_IN_CONVERTERS: readonly SchemaConverter[];
+/** Format version of {@link OpenApiMetadata}. */
+declare const OPENAPI_METADATA_VERSION = 1;
+/** A Standard Schema converted at assembly: `{ $ref }` to its component once replaced. */
+interface SchemaPlaceholder {
+  readonly $znight: "schema";
+  /** Slot name ({@link OpenApiSchemaSlot.name}). */
+  readonly name: string;
+  readonly io: "input" | "output";
+}
+/**
+ * In `parameters` arrays: one parameter per property of the (input) object schema of a slot
+ * (`@Query(SearchQuery)`), `required` from its `required` list.
+ */
+interface ParametersPlaceholder {
+  readonly $znight: "parameters";
+  readonly in: "path" | "query" | "header" | "cookie";
+  /** Slot name. */
+  readonly name: string;
+  readonly io: "input";
+}
+/** JSON Schema, or a placeholder of a Standard Schema. */
+type SchemaTemplate = JsonSchema | SchemaPlaceholder;
+/** An Operation Object whose schemas are {@link SchemaTemplate}s and whose parameters may be {@link ParametersPlaceholder}s. */
+type OperationTemplate = OperationObjectOf<SchemaTemplate, ParametersPlaceholder>;
+/** Root fields of the document known at build time. */
+interface OpenApiDocumentTemplate {
+  readonly openapi: string;
+  readonly info: InfoObject;
+  readonly servers?: readonly ServerObject[];
+  readonly tags?: readonly TagObject[];
+  readonly externalDocs?: ExternalDocumentationObject;
+  readonly security?: readonly SecurityRequirementObject[];
+  readonly [extension: `x-${string}`]: JsonValue | undefined;
+}
+/** A documented operation. */
+interface OpenApiOperationDefinition {
+  /** Controller token. */
+  readonly controller: Token;
+  readonly handler: string;
+  /** The compiled route method (`'ALL'` gives one definition per documented method). */
+  readonly route: string;
+  readonly method: OpenApiMethod;
+  /** OpenAPI path template, without the HTTP prefix (`/books/{id}`). */
+  readonly path: string;
+  readonly operation: OperationTemplate;
+}
+/** A Standard Schema converted when the document is assembled. */
+interface OpenApiSchemaSlot {
+  /** Component name (export name of the binding: `CreateBook`). */
+  readonly name: string;
+  /** The imported schema value. */
+  readonly schema: StandardSchemaV1;
+  /** The JSON Schemas needed: `input` for requests, `output` for responses. */
+  readonly io: readonly ("input" | "output")[];
+  /** Where the schema is declared (relative path), for messages. */
+  readonly source?: {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+  };
+}
+/** `metadata.extensions.openapi`. */
+interface OpenApiMetadata {
+  readonly version: 1;
+  /** SHA-256 (base64url) of the section, schema values replaced by their names (stale-file detection). */
+  readonly fingerprint: string;
+  readonly document: OpenApiDocumentTemplate;
+  /** Sorted by path, then by method (get, put, post, delete, options, head, patch). */
+  readonly operations: readonly OpenApiOperationDefinition[];
+  /** JSON Schemas computed by the compiler from TypeScript declarations, by component name (sorted). */
+  readonly components: Readonly<Record<string, SchemaTemplate>>;
+  readonly securitySchemes: Readonly<Record<string, SecuritySchemeObject>>;
+  /** Standard Schemas converted at assembly, sorted by name. */
+  readonly schemas: readonly OpenApiSchemaSlot[];
+  /** Standard error components; absent with `errors: false`. */
+  readonly errors?: {
+    readonly contentType: string;
+    readonly schema?: string;
+  };
+  /** Descriptions of the default tags (JSDoc of the controllers), by tag name; absent when empty. */
+  readonly tagDescriptions?: Readonly<Record<string, string>>;
+}
+declare module "@znight/core" {
+  interface ZnightExtensionsMetadata {
+    readonly openapi?: OpenApiMetadata;
+  }
+}
+/** A static view of an operation (no schema conversion), used by `filter` and `OpenApi.operations`. */
+interface OpenApiOperationView {
+  readonly method: OpenApiMethod;
+  /** Path template without the HTTP prefix (`/books/{id}`). */
+  readonly path: string;
+  readonly operationId: string;
+  readonly tags: readonly string[];
+  /** Controller display name. */
+  readonly controller: string;
+  readonly handler: string;
+  /** Effective route metadata (`createRouteDecorator` values, the nearest decision of each group). */
+  readonly meta: Readonly<Record<string, unknown>>;
+}
+/** Options of {@link buildOpenApiDocument}. */
+interface BuildOpenApiOptions {
+  /** The HTTP prefix: `servers` defaults to `[{ url: prefix }]` when nothing declares servers. */
+  readonly prefix?: string;
+  /** Merged over the static `info`. */
+  readonly info?: Partial<InfoObject>;
+  /** Replaces the declared `servers`. */
+  readonly servers?: readonly ServerObject[];
+  /** Hides operations; unreferenced components are pruned. */
+  readonly filter?: (operation: OpenApiOperationView) => boolean;
+  /** Last-resort escape hatch, applied before freezing. */
+  readonly transform?: (document: OpenApiObject) => OpenApiObject;
+  /** Extra converters, tried before the built-in ones. */
+  readonly converters?: readonly SchemaConverter[];
+  /** `'warn'`: a schema that cannot be converted becomes `{}` with a ZNIGHT037 warning. Default `'error'`. */
+  readonly unrepresentable?: "error" | "warn";
+}
+/** A warning of the assembly. */
+interface OpenApiWarning {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly hints: readonly string[];
+}
+/** Result of {@link buildOpenApiDocument}. */
+interface OpenApiBuildResult {
+  /** The document, deep-frozen. */
+  readonly document: OpenApiObject;
+  /** `JSON.stringify(document, null, 2)` and a final newline. */
+  readonly json: string;
+  readonly warnings: readonly OpenApiWarning[];
+  readonly stats: {
+    readonly operations: number;
+    readonly schemas: number;
+    readonly durationMs: number;
+  };
+}
+/**
+ * Assembles the OpenAPI 3.1 document of an application from its generated metadata: converts the
+ * Standard Schemas (user converters, Standard JSON Schema, Valibot), hoists their `$defs`, names
+ * the components, fills the placeholders of the compiler, applies `filter`, prunes the unused
+ * components, applies `transform`, deep-freezes and serialises once.
+ *
+ * @throws ZnightError ZNIGHT030 (no OpenAPI section), ZNIGHT018 (another format version), ZNIGHT034
+ *   (component name conflict), ZNIGHT037 (schema conversion, unless `unrepresentable: 'warn'`).
+ */
+declare function buildOpenApiDocument(metadata: ZnightMetadata, options?: BuildOpenApiOptions): Promise<OpenApiBuildResult>;
+export { SchemaConverterContext as _, buildOpenApiDocument as a, OpenApiMetadata as c, OperationTemplate as d, ParametersPlaceholder as f, SchemaConverter as g, BUILT_IN_CONVERTERS as h, OpenApiWarning as i, OpenApiOperationDefinition as l, SchemaTemplate as m, OpenApiBuildResult as n, OPENAPI_METADATA_VERSION as o, SchemaPlaceholder as p, OpenApiOperationView as r, OpenApiDocumentTemplate as s, BuildOpenApiOptions as t, OpenApiSchemaSlot as u, standardJsonSchemaConverter as v, valibotConverter as y };
+//# sourceMappingURL=build-BTUC96mY.d.mts.map