@kubb/ast 5.0.0-beta.30 → 5.0.0-beta.31

package/dist/index.d.ts

@@ -190,105 +190,6 @@ declare const mediaTypes: {
   readonly videoMp4: "video/mp4";
 };
 //#endregion
-//#region src/dialect.d.ts
-/**
- * The spec-specific decisions a schema parser makes while converting a source
- * document's schemas into Kubb AST nodes.
- *
- * Everything else in an adapter's schema pipeline is generic JSON Schema shared
- * across specs; the dialect is the one seam where a spec differs — the
- * "dialect layer" analogue of a database driver targeting Postgres vs MySQL.
- * Pair it with {@link dispatch}: the rule table decides *which* converter runs,
- * the dialect answers the spec-specific questions inside them.
- *
- * The guard methods (`isReference`, `isDiscriminator`) are type predicates so
- * converters narrow the schema after a check; the type parameters carry those
- * narrowed types through.
- *
- * Scope: this is the seam for the **JSON Schema family** — OpenAPI, AsyncAPI, and
- * plain JSON Schema all share `$ref`, `allOf`/`oneOf`, `enum`, and `format`, and
- * differ only in these few decisions. A spec built on a different type system
- * (e.g. GraphQL, with non-null wrappers, interfaces, and named-type references
- * instead of `$ref`) does not implement a `SchemaDialect`; it reuses the universal
- * layer directly — the `Adapter` port, the AST factories, and {@link dispatch}
- * with its own rule table — to emit the same nodes.
- *
- * @typeParam TSchema - The adapter's schema object type (e.g. an OpenAPI `SchemaObject`).
- * @typeParam TRef - The narrowed `$ref` pointer type `isReference` proves.
- * @typeParam TDiscriminated - The narrowed discriminated-schema type `isDiscriminator` proves.
- * @typeParam TDocument - The source document `resolveRef` resolves against.
- */
-type SchemaDialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
-  /** Identifies the dialect in logs and while debugging dispatch. */name: string; /** Whether a schema should be treated as nullable. */
-  isNullable: (schema?: TSchema) => boolean; /** Whether a value is a `$ref` pointer object. */
-  isReference: (value?: unknown) => value is TRef; /** Whether a schema carries a structured discriminator (polymorphism). */
-  isDiscriminator: (value?: unknown) => value is TDiscriminated; /** Whether a schema represents binary data (converted to a `blob` node). */
-  isBinary: (schema: TSchema) => boolean; /** Resolves a local `$ref` pointer against the document, or nullish when it cannot. */
-  resolveRef: <TResolved>(document: TDocument, ref: string) => TResolved | null | undefined;
-};
-/**
- * Identity helper that types a {@link SchemaDialect} for an adapter. Like
- * `defineParser`, it adds no runtime behavior — it pins the dialect's type for
- * inference and gives adapter authors a discoverable anchor.
- *
- * @example
- * ```ts
- * export const oasDialect = defineSchemaDialect({
- *   name: 'oas',
- *   isNullable,
- *   isReference,
- *   isDiscriminator,
- *   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
- *   resolveRef,
- * })
- * ```
- */
-declare function defineSchemaDialect<TSchema, TRef, TDiscriminated, TDocument>(dialect: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>): SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>;
-//#endregion
-//#region src/dispatch.d.ts
-/**
- * One entry in an ordered dispatch table: a predicate paired with a converter.
- *
- * @typeParam TContext - Per-input context handed to every rule. A spec adapter typically
- *   pre-computes this once per node (the source spec node plus derived fields like a
- *   normalized type or resolved options) so individual rules stay cheap predicates.
- * @typeParam TNode - The node a rule produces, e.g. a Kubb AST `SchemaNode`.
- */
-type DispatchRule<TContext, TNode> = {
-  /** Identifies the rule when reading the table or debugging which branch ran. */name: string; /** Returns `true` when this rule is responsible for the given context. */
-  match: (context: TContext) => boolean;
-  /**
-   * Produces a node for the context, or `null` to fall through to the next rule.
-   *
-   * Returning `null` lets a broad `match` defer: e.g. "has a `format`" matches many schemas,
-   * but only some formats are convertible — the rest fall through to plain `type` handling.
-   */
-  convert: (context: TContext) => TNode | null;
-};
-/**
- * Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
- *
- * This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
- * The contract an adapter follows is intentionally minimal:
- *
- *     context → [rule.match → rule.convert] → node
- *
- * An adapter derives a context from a source spec node, then declares an ordered table of
- * rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
- * context type and a new rules table — the traversal here is reused unchanged.
- *
- * Order is significant: earlier rules win, so list higher-precedence or more specific shapes
- * first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
- * may still `convert` to `null` to defer to later rules. When no rule produces a node this
- * returns `null`, leaving the caller to apply its own fallback.
- *
- * @example
- * ```ts
- * const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
- * ```
- */
-declare function dispatch<TContext, TNode>(rules: ReadonlyArray<DispatchRule<TContext, TNode>>, context: TContext): TNode | null;
-//#endregion
 //#region src/nodes/base.d.ts
 /**
  * `kind` values used by AST nodes.
@@ -2149,6 +2050,197 @@ type InputStreamNode = {
  */
 type Node = InputNode | OutputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | RequestBodyNode | ContentNode | FunctionParamNode | FileNode | ImportNode | ExportNode | SourceNode | ConstNode | TypeNode | ParamsTypeNode | FunctionNode | ArrowFunctionNode;
 //#endregion
+//#region src/dedupe.d.ts
+/**
+ * A canonical destination for a deduplicated shape: the shared schema name and
+ * the synthetic `$ref` path that points at it.
+ */
+type DedupeCanonical = {
+  /**
+   * Canonical schema name every duplicate occurrence refers to.
+   */
+  name: string;
+  /**
+   * `$ref` path stored on the generated `ref` nodes (for example `#/components/schemas/Status`).
+   */
+  ref: string;
+};
+/**
+ * The result of {@link buildDedupePlan}: a lookup from structural signature to its
+ * canonical target, plus the freshly hoisted definitions that must be added to
+ * the schema list.
+ */
+type DedupePlan = {
+  /**
+   * Maps a structural signature to the canonical schema that represents it.
+   */
+  canonicalBySignature: Map<string, DedupeCanonical>;
+  /**
+   * New top-level schema definitions created for inline shapes that had no existing
+   * named component. Nested duplicates inside each definition are already collapsed.
+   */
+  hoisted: Array<SchemaNode>;
+};
+/**
+ * Options that inject the naming and candidate policy into {@link buildDedupePlan}.
+ * The mechanics (grouping, counting, rewriting) live here; the policy lives in the caller.
+ */
+type BuildDedupePlanOptions = {
+  /**
+   * Returns `true` when a node should be deduplicated. This is the only gate, so it must
+   * reject both ineligible kinds (return `false` for anything other than, say, enums and
+   * objects) and unsafe shapes (e.g. nodes that reference a circular schema).
+   */
+  isCandidate: (node: SchemaNode) => boolean;
+  /**
+   * Produces the canonical name for an inline shape with no existing named component.
+   * Return `null` to leave the shape inline (for example when no contextual name exists).
+   */
+  nameFor: (node: SchemaNode, signature: string) => string | null;
+  /**
+   * Builds the `$ref` path for a canonical name.
+   */
+  refFor: (name: string) => string;
+  /**
+   * Minimum number of occurrences before a shape is deduplicated.
+   *
+   * @default 2
+   */
+  minOccurrences?: number;
+};
+/**
+ * Rewrites a node, replacing every candidate sub-schema whose signature has a canonical
+ * target with a `ref` to that target. Replacing a node with a `ref` prunes its subtree,
+ * so nested duplicates inside a replaced shape are not visited again.
+ *
+ * Pass `skipRootMatch` when rewriting a canonical definition so its own root is not
+ * turned into a reference to itself; nested duplicates are still collapsed.
+ *
+ * @example
+ * ```ts
+ * const next = applyDedupe(operationNode, plan.canonicalBySignature)
+ * ```
+ */
+declare function applyDedupe(node: SchemaNode, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch?: boolean): SchemaNode;
+declare function applyDedupe(node: OperationNode, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch?: boolean): OperationNode;
+/**
+ * Scans a forest of schema and operation nodes and produces a {@link DedupePlan}.
+ *
+ * A shape that occurs at least `minOccurrences` times is deduplicated: if any occurrence
+ * is a named top-level schema, that name becomes the canonical (so other top-level duplicates
+ * and inline copies turn into references to it); otherwise a new definition is hoisted using
+ * `nameFor`. The plan is then applied per node with {@link applyDedupe}.
+ *
+ * @example
+ * ```ts
+ * const plan = buildDedupePlan([...schemaNodes, ...operationNodes], {
+ *   isCandidate: (node) => node.type === 'enum' || node.type === 'object',
+ *   nameFor: (node) => node.name ?? null,
+ *   refFor: (name) => `#/components/schemas/${name}`,
+ * })
+ * ```
+ */
+declare function buildDedupePlan(roots: ReadonlyArray<Node>, options: BuildDedupePlanOptions): DedupePlan;
+//#endregion
+//#region src/dialect.d.ts
+/**
+ * The spec-specific decisions a schema parser makes while converting a source
+ * document's schemas into Kubb AST nodes.
+ *
+ * Everything else in an adapter's schema pipeline is generic JSON Schema shared
+ * across specs; the dialect is the one seam where a spec differs — the
+ * "dialect layer" analogue of a database driver targeting Postgres vs MySQL.
+ * Pair it with {@link dispatch}: the rule table decides *which* converter runs,
+ * the dialect answers the spec-specific questions inside them.
+ *
+ * The guard methods (`isReference`, `isDiscriminator`) are type predicates so
+ * converters narrow the schema after a check; the type parameters carry those
+ * narrowed types through.
+ *
+ * Scope: this is the seam for the **JSON Schema family** — OpenAPI, AsyncAPI, and
+ * plain JSON Schema all share `$ref`, `allOf`/`oneOf`, `enum`, and `format`, and
+ * differ only in these few decisions. A spec built on a different type system
+ * (e.g. GraphQL, with non-null wrappers, interfaces, and named-type references
+ * instead of `$ref`) does not implement a `SchemaDialect`; it reuses the universal
+ * layer directly — the `Adapter` port, the AST factories, and {@link dispatch}
+ * with its own rule table — to emit the same nodes.
+ *
+ * @typeParam TSchema - The adapter's schema object type (e.g. an OpenAPI `SchemaObject`).
+ * @typeParam TRef - The narrowed `$ref` pointer type `isReference` proves.
+ * @typeParam TDiscriminated - The narrowed discriminated-schema type `isDiscriminator` proves.
+ * @typeParam TDocument - The source document `resolveRef` resolves against.
+ */
+type SchemaDialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
+  /** Identifies the dialect in logs and while debugging dispatch. */name: string; /** Whether a schema should be treated as nullable. */
+  isNullable: (schema?: TSchema) => boolean; /** Whether a value is a `$ref` pointer object. */
+  isReference: (value?: unknown) => value is TRef; /** Whether a schema carries a structured discriminator (polymorphism). */
+  isDiscriminator: (value?: unknown) => value is TDiscriminated; /** Whether a schema represents binary data (converted to a `blob` node). */
+  isBinary: (schema: TSchema) => boolean; /** Resolves a local `$ref` pointer against the document, or nullish when it cannot. */
+  resolveRef: <TResolved>(document: TDocument, ref: string) => TResolved | null | undefined;
+};
+/**
+ * Identity helper that types a {@link SchemaDialect} for an adapter. Like
+ * `defineParser`, it adds no runtime behavior — it pins the dialect's type for
+ * inference and gives adapter authors a discoverable anchor.
+ *
+ * @example
+ * ```ts
+ * export const oasDialect = defineSchemaDialect({
+ *   name: 'oas',
+ *   isNullable,
+ *   isReference,
+ *   isDiscriminator,
+ *   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+ *   resolveRef,
+ * })
+ * ```
+ */
+declare function defineSchemaDialect<TSchema, TRef, TDiscriminated, TDocument>(dialect: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>): SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>;
+//#endregion
+//#region src/dispatch.d.ts
+/**
+ * One entry in an ordered dispatch table: a predicate paired with a converter.
+ *
+ * @typeParam TContext - Per-input context handed to every rule. A spec adapter typically
+ *   pre-computes this once per node (the source spec node plus derived fields like a
+ *   normalized type or resolved options) so individual rules stay cheap predicates.
+ * @typeParam TNode - The node a rule produces, e.g. a Kubb AST `SchemaNode`.
+ */
+type DispatchRule<TContext, TNode> = {
+  /** Identifies the rule when reading the table or debugging which branch ran. */name: string; /** Returns `true` when this rule is responsible for the given context. */
+  match: (context: TContext) => boolean;
+  /**
+   * Produces a node for the context, or `null` to fall through to the next rule.
+   *
+   * Returning `null` lets a broad `match` defer: e.g. "has a `format`" matches many schemas,
+   * but only some formats are convertible — the rest fall through to plain `type` handling.
+   */
+  convert: (context: TContext) => TNode | null;
+};
+/**
+ * Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
+ *
+ * This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
+ * The contract an adapter follows is intentionally minimal:
+ *
+ *     context → [rule.match → rule.convert] → node
+ *
+ * An adapter derives a context from a source spec node, then declares an ordered table of
+ * rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
+ * context type and a new rules table — the traversal here is reused unchanged.
+ *
+ * Order is significant: earlier rules win, so list higher-precedence or more specific shapes
+ * first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
+ * may still `convert` to `null` to defer to later rules. When no rule produces a node this
+ * returns `null`, leaving the caller to apply its own fallback.
+ *
+ * @example
+ * ```ts
+ * const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
+ * ```
+ */
+declare function dispatch<TContext, TNode>(rules: ReadonlyArray<DispatchRule<TContext, TNode>>, context: TContext): TNode | null;
+//#endregion
 //#region src/infer.d.ts
 /**
  * Shared parser options used by OAS-to-AST inference and parser flows.
@@ -3194,6 +3286,33 @@ declare function collectImports<TImport>({
   resolve: (schemaName: string) => TImport | null;
 }): Array<TImport>;
 //#endregion
+//#region src/signature.d.ts
+/**
+ * Computes a deterministic, shape-only signature (a fixed-length content hash) for a schema node.
+ *
+ * Two schemas share a signature when they are structurally identical, ignoring
+ * documentation (`name`, `title`, `description`, `example`, `default`, `deprecated`)
+ * and usage-slot flags (`optional`, `nullish`, `readOnly`, `writeOnly`). `nullable`
+ * is kept because it changes the produced type. `ref` nodes compare by target name,
+ * which also keeps the algorithm terminating on circular shapes.
+ *
+ * @example Two enums with different descriptions share a signature
+ * ```ts
+ * schemaSignature(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'], description: 'x' })) ===
+ *   schemaSignature(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'] }))
+ * ```
+ */
+declare function schemaSignature(node: SchemaNode): string;
+/**
+ * Returns `true` when two schema nodes are structurally identical under shape-only equality.
+ *
+ * @example
+ * ```ts
+ * isSchemaEqual(a, b) // a and b produce the same TypeScript type
+ * ```
+ */
+declare function isSchemaEqual(a: SchemaNode, b: SchemaNode): boolean;
+//#endregion
 //#region src/transformers.d.ts
 /**
  * Replaces a discriminator property's schema with a string enum of allowed values.
@@ -3754,5 +3873,5 @@ declare function containsCircularRef(node: SchemaNode | undefined, {
   excludeName?: string;
 }): boolean;
 //#endregion
-export { type ArraySchemaNode, type ArrowFunctionNode, AsyncVisitor, type BaseNode, type BreakNode, type CodeNode, CollectOptions, CollectVisitor, type ComplexSchemaType, type ConstNode, type DateSchemaNode, type DatetimeSchemaNode, DispatchRule, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type InputStreamNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type OperationNodeBase, OperationParamsResolver, type OperationProtocol, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, ParserOptions, type PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, SchemaDialect, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type SpecialSchemaType, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, TransformOptions, type TypeDeclarationNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, UserFileNode, Visitor, VisitorContext, VisitorDepth, WalkOptions, caseParams, childName, collect, collectImports, collectLazy, collectReferencedSchemaNames, collectUsedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createContent, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createRequestBody, createResponse, createSchema, createSource, createStreamInput, createText, createType, definePrinter, defineSchemaDialect, dispatch, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isHttpOperationNode, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, mergeAdjacentObjectsLazy, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, update, walk };
+export { type ArraySchemaNode, type ArrowFunctionNode, AsyncVisitor, type BaseNode, type BreakNode, BuildDedupePlanOptions, type CodeNode, CollectOptions, CollectVisitor, type ComplexSchemaType, type ConstNode, type DateSchemaNode, type DatetimeSchemaNode, DedupeCanonical, DedupePlan, DispatchRule, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type InputStreamNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type OperationNodeBase, OperationParamsResolver, type OperationProtocol, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, ParserOptions, type PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, SchemaDialect, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type SpecialSchemaType, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, TransformOptions, type TypeDeclarationNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, UserFileNode, Visitor, VisitorContext, VisitorDepth, WalkOptions, applyDedupe, buildDedupePlan, caseParams, childName, collect, collectImports, collectLazy, collectReferencedSchemaNames, collectUsedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createContent, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createRequestBody, createResponse, createSchema, createSource, createStreamInput, createText, createType, definePrinter, defineSchemaDialect, dispatch, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isHttpOperationNode, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaEqual, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, mergeAdjacentObjectsLazy, narrowSchema, nodeKinds, resolveRefName, schemaSignature, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, update, walk };
 //# sourceMappingURL=index.d.ts.map