@kubb/ast 5.0.0-alpha.66 → 5.0.0-alpha.69

package/dist/index.d.ts

@@ -3362,6 +3362,77 @@ declare function createOperationParams(node: OperationNode, options: CreateOpera
  * Used by `createFile` to build the full source string for import filtering.
  */
 declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): string;
+/**
+ * Resolves the referenced schema name of a `ref` node, falling back through
+ * `ref` → `name` → nested `schema.name`. Returns `undefined` for non-ref
+ * nodes or when no name can be resolved.
+ *
+ * @example
+ * ```ts
+ * resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' })
+ * // => 'Pet'
+ * ```
+ */
+declare function resolveRefName(node: SchemaNode | undefined): string | undefined;
+/**
+ * Recursively collects every named schema referenced (transitively) from
+ * `node` via `ref` edges. Refs are followed by name only — the resolved
+ * `node.schema` of a ref is not traversed inline.
+ *
+ * @example
+ * ```ts
+ * const refs = collectReferencedSchemaNames(petSchema)
+ * // => Set { 'Cat', 'Dog' }
+ * ```
+ */
+declare function collectReferencedSchemaNames(node: SchemaNode | undefined, out?: Set<string>): Set<string>;
+/**
+ * Identifies every named schema that participates in a circular dependency
+ * chain — including direct self-loops (e.g. `TreeNode → TreeNode`) and indirect
+ * cycles spanning multiple schemas (e.g. `Pet → Cat → Pet`).
+ *
+ * The returned set contains schema names. Plugins that translate schemas into
+ * a host language can use this to wrap recursive positions in a deferred
+ * construct (lazy getter, `z.lazy(() => …)`, etc.) and avoid runtime stack
+ * overflows when the generated code is executed.
+ *
+ * Refs are followed by name only — `node.schema` (the resolved referent) is
+ * not traversed inline, which keeps the algorithm linear in the size of the
+ * schema graph.
+ *
+ * @example
+ * ```ts
+ * const circular = findCircularSchemas(inputNode.schemas)
+ * if (circular.has('Pet')) {
+ *   // emit lazy wrapper for any property whose schema references Pet
+ * }
+ * ```
+ */
+declare function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string>;
+/**
+ * Returns true when `node` (or anything nested within it) carries a `ref`
+ * whose resolved name belongs to `circularSchemas`.
+ *
+ * When `excludeName` is provided, refs to that name are ignored — useful
+ * when self-references are already handled separately from cross-schema
+ * cycles (e.g. the faker plugin emits `undefined as any` for direct
+ * self-recursion but a lazy getter for indirect cycles).
+ *
+ * @example
+ * ```ts
+ * const circular = findCircularSchemas(schemas)
+ * if (containsCircularRef(property.schema, { circularSchemas: circular, excludeName: 'Pet' })) {
+ *   // emit `get foo() { return fakeCat() }` instead of eager call
+ * }
+ * ```
+ */
+declare function containsCircularRef(node: SchemaNode | undefined, {
+  circularSchemas,
+  excludeName
+}: {
+  circularSchemas: ReadonlySet<string>;
+  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, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type HttpMethod, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type OperationParamsResolver, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, type ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, 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, Visitor, VisitorContext, VisitorDepth, WalkOptions, caseParams, childName, collect, collectImports, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
+export { type ArraySchemaNode, type ArrowFunctionNode, AsyncVisitor, type BaseNode, type BreakNode, type CodeNode, CollectOptions, CollectVisitor, type ComplexSchemaType, type ConstNode, type DateSchemaNode, type DatetimeSchemaNode, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type HttpMethod, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type OperationParamsResolver, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, type ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, 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, Visitor, VisitorContext, VisitorDepth, WalkOptions, caseParams, childName, collect, collectImports, collectReferencedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
 //# sourceMappingURL=index.d.ts.map