@kubb/ast 5.13.0 → 5.13.1

package/dist/index.d.cts

@@ -368,6 +368,21 @@ type ObjectSchemaNode = SchemaNodeBase & {
    * Pattern-based property schemas.
    */
   patternProperties?: Record<string, SchemaNode>;
+  /**
+   * Schema that each property name must match.
+   *
+   * @example
+   * ```ts
+   * const objectSchema: ObjectSchemaNode = {
+   *   kind: 'Schema',
+   *   type: 'object',
+   *   primitive: 'object',
+   *   properties: [],
+   *   propertyNames: { kind: 'Schema', type: 'string', primitive: 'string', pattern: '^[a-z]+$' },
+   * }
+   * ```
+   */
+  propertyNames?: SchemaNode;
   /**
    * Minimum number of properties allowed.
    */
@@ -2103,6 +2118,42 @@ type TransformOptions = Visitor & TraversalOptions;
  * ```
  */
 type CollectOptions<T> = VisitorOf<T> & TraversalOptions;
+/**
+ * Visits each direct child node in the AST's traversal order.
+ *
+ * @example
+ * ```ts
+ * forEachChild(operationNode, (child) => {
+ *   console.log(child.kind)
+ * })
+ * ```
+ */
+export declare function forEachChild(node: Node, visit: (child: Node) => void): void;
+/**
+ * Visits each schema in a node's child tree in depth-first order. Includes `node` when it is a schema.
+ *
+ * @example
+ * ```ts
+ * forEachSchema(operationNode, (schema) => {
+ *   console.log(schema.type)
+ * })
+ * ```
+ */
+export declare function forEachSchema(node: Node, visit: (schema: SchemaNode) => void): void;
+/**
+ * Finds the first schema that matches `predicate` in depth-first order. Set `followRefs` to include resolved ref targets.
+ *
+ * @example
+ * ```ts
+ * const firstString = findSchema(operationNode, {
+ *   predicate: (schema) => schema.type === 'string',
+ * })
+ * ```
+ */
+export declare function findSchema(node: Node, { predicate, followRefs }: {
+  predicate: (schema: SchemaNode) => boolean;
+  followRefs?: boolean;
+}): SchemaNode | undefined;
 /**
  * Synchronous depth-first transform. Each visitor callback can return a
  * replacement node. Returning `undefined` keeps the original.
@@ -2465,6 +2516,15 @@ export declare function refName(ref: string): string;
  * `resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Order', targetName: 'OrderSchema' }) // 'OrderSchema'`
  */
 export declare function resolveRefName(node: SchemaNode | null | undefined): string | null;
+/**
+ * Follows a resolved ref chain to its target schema. Returns an unresolved or cyclic ref as is.
+ *
+ * @example
+ * ```ts
+ * const target = resolveRef(refSchema)
+ * ```
+ */
+export declare function resolveRef(node: SchemaNode): SchemaNode;
 /**
  * Merges a ref node with its resolved schema, giving the fields set at the usage site precedence.
  *
@@ -2690,7 +2750,7 @@ type ParserOptions = {
   enumSuffix: 'enum' | (string & {});
 };
 declare namespace index_d_exports {
-  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParentOf, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findCircularSchemasFromGraph, getSchemaLiteralValues, inferDiscriminatorPropertyName, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, optionality, refName, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
+  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParentOf, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findCircularSchemasFromGraph, findSchema, forEachChild, forEachSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
 }
 //#endregion
 export { type ArraySchemaNode, type ArrowFunctionNode, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type Enforce, type EnumSchemaNode, type ExportNode, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InputMeta, type InputNode, type InputSecurityScheme, type InputServer, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParentOf, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };

package/dist/index.d.ts

@@ -368,6 +368,21 @@ type ObjectSchemaNode = SchemaNodeBase & {
    * Pattern-based property schemas.
    */
   patternProperties?: Record<string, SchemaNode>;
+  /**
+   * Schema that each property name must match.
+   *
+   * @example
+   * ```ts
+   * const objectSchema: ObjectSchemaNode = {
+   *   kind: 'Schema',
+   *   type: 'object',
+   *   primitive: 'object',
+   *   properties: [],
+   *   propertyNames: { kind: 'Schema', type: 'string', primitive: 'string', pattern: '^[a-z]+$' },
+   * }
+   * ```
+   */
+  propertyNames?: SchemaNode;
   /**
    * Minimum number of properties allowed.
    */
@@ -2103,6 +2118,42 @@ type TransformOptions = Visitor & TraversalOptions;
  * ```
  */
 type CollectOptions<T> = VisitorOf<T> & TraversalOptions;
+/**
+ * Visits each direct child node in the AST's traversal order.
+ *
+ * @example
+ * ```ts
+ * forEachChild(operationNode, (child) => {
+ *   console.log(child.kind)
+ * })
+ * ```
+ */
+export declare function forEachChild(node: Node, visit: (child: Node) => void): void;
+/**
+ * Visits each schema in a node's child tree in depth-first order. Includes `node` when it is a schema.
+ *
+ * @example
+ * ```ts
+ * forEachSchema(operationNode, (schema) => {
+ *   console.log(schema.type)
+ * })
+ * ```
+ */
+export declare function forEachSchema(node: Node, visit: (schema: SchemaNode) => void): void;
+/**
+ * Finds the first schema that matches `predicate` in depth-first order. Set `followRefs` to include resolved ref targets.
+ *
+ * @example
+ * ```ts
+ * const firstString = findSchema(operationNode, {
+ *   predicate: (schema) => schema.type === 'string',
+ * })
+ * ```
+ */
+export declare function findSchema(node: Node, { predicate, followRefs }: {
+  predicate: (schema: SchemaNode) => boolean;
+  followRefs?: boolean;
+}): SchemaNode | undefined;
 /**
  * Synchronous depth-first transform. Each visitor callback can return a
  * replacement node. Returning `undefined` keeps the original.
@@ -2465,6 +2516,15 @@ export declare function refName(ref: string): string;
  * `resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Order', targetName: 'OrderSchema' }) // 'OrderSchema'`
  */
 export declare function resolveRefName(node: SchemaNode | null | undefined): string | null;
+/**
+ * Follows a resolved ref chain to its target schema. Returns an unresolved or cyclic ref as is.
+ *
+ * @example
+ * ```ts
+ * const target = resolveRef(refSchema)
+ * ```
+ */
+export declare function resolveRef(node: SchemaNode): SchemaNode;
 /**
  * Merges a ref node with its resolved schema, giving the fields set at the usage site precedence.
  *
@@ -2690,7 +2750,7 @@ type ParserOptions = {
   enumSuffix: 'enum' | (string & {});
 };
 declare namespace index_d_exports {
-  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParentOf, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findCircularSchemasFromGraph, getSchemaLiteralValues, inferDiscriminatorPropertyName, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, optionality, refName, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
+  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParentOf, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findCircularSchemasFromGraph, findSchema, forEachChild, forEachSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
 }
 //#endregion
 export { type ArraySchemaNode, type ArrowFunctionNode, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type Enforce, type EnumSchemaNode, type ExportNode, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InputMeta, type InputNode, type InputSecurityScheme, type InputServer, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParentOf, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };

package/dist/index.js

@@ -174,6 +174,7 @@ const VISITOR_KEYS = {
 		"members",
 		"additionalProperties",
 		"patternProperties",
+		"propertyNames",
 		"rest"
 	],
 	Property: ["schema"],
@@ -221,25 +222,101 @@ function isNodeRecord(value) {
 * ```
 */
 function getChildren(node, recurse) {
+	if (node.kind === "Schema" && !recurse) return [];
 	const children = [];
-	const keys = node.kind === "Schema" && !recurse ? void 0 : VISITOR_KEYS[node.kind];
-	if (!keys) return children;
+	visitChildNodes(node, (child) => {
+		children.push(child);
+		return false;
+	});
+	return children;
+}
+/**
+* Visits each direct child node in the AST's traversal order.
+*
+* @example
+* ```ts
+* forEachChild(operationNode, (child) => {
+*   console.log(child.kind)
+* })
+* ```
+*/
+function forEachChild(node, visit) {
+	visitChildNodes(node, (child) => {
+		visit(child);
+		return false;
+	});
+}
+function visitChildNodes(node, visit) {
+	const keys = VISITOR_KEYS[node.kind];
+	if (!keys) return false;
 	const record = node;
 	for (const key of keys) {
 		const value = record[key];
 		if (Array.isArray(value)) {
-			for (const item of value) if (isNode(item)) children.push(item);
+			for (const item of value) if (isNode(item) && visit(item)) return true;
 			continue;
 		}
 		if (isNode(value)) {
-			children.push(value);
+			if (visit(value)) return true;
 			continue;
 		}
-		if (isNodeRecord(value)) {
-			for (const item of Object.values(value)) if (isNode(item)) children.push(item);
+		if (isNodeRecord(value)) for (const name in value) {
+			if (!Object.hasOwn(value, name)) continue;
+			const item = value[name];
+			if (isNode(item) && visit(item)) return true;
 		}
 	}
-	return children;
+	return false;
+}
+/**
+* Visits each schema in a node's child tree in depth-first order. Includes `node` when it is a schema.
+*
+* @example
+* ```ts
+* forEachSchema(operationNode, (schema) => {
+*   console.log(schema.type)
+* })
+* ```
+*/
+function forEachSchema(node, visit) {
+	const walk = (current) => {
+		if (current.kind === "Schema") visit(current);
+		forEachChild(current, walk);
+	};
+	walk(node);
+}
+/**
+* Finds the first schema that matches `predicate` in depth-first order. Set `followRefs` to include resolved ref targets.
+*
+* @example
+* ```ts
+* const firstString = findSchema(operationNode, {
+*   predicate: (schema) => schema.type === 'string',
+* })
+* ```
+*/
+function findSchema(node, { predicate, followRefs = false }) {
+	const seen = followRefs ? /* @__PURE__ */ new WeakSet() : void 0;
+	const walk = (current) => {
+		if (current.kind === "Schema") {
+			if (predicate(current)) return current;
+			if (seen) {
+				if (seen.has(current)) return void 0;
+				seen.add(current);
+				if (current.type === "ref" && current.schema) {
+					const found = walk(current.schema);
+					if (found) return found;
+				}
+			}
+		}
+		let found;
+		visitChildNodes(current, (child) => {
+			found = walk(child);
+			return found !== void 0;
+		});
+		if (found) return found;
+	};
+	return walk(node);
 }
 /**
 * Runs the visitor callback that matches `node.kind` with the traversal
@@ -623,6 +700,25 @@ function resolveRefName(node) {
 	if (node.ref) return refName(node.ref);
 	return node.name ?? node.schema?.name ?? null;
 }
+/**
+* Follows a resolved ref chain to its target schema. Returns an unresolved or cyclic ref as is.
+*
+* @example
+* ```ts
+* const target = resolveRef(refSchema)
+* ```
+*/
+function resolveRef(node) {
+	if (node.type !== "ref" || !node.schema) return node;
+	const seen = /* @__PURE__ */ new WeakSet();
+	let current = node;
+	while (current.type === "ref" && current.schema) {
+		if (seen.has(current)) return current;
+		seen.add(current);
+		current = current.schema;
+	}
+	return current;
+}
 /** Fields of a ref node that describe the ref itself, so they never override the resolved schema. */
 const REF_OWN_KEYS = /* @__PURE__ */ new Set([
 	"kind",
@@ -1517,6 +1613,9 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	factory: () => nodes_exports,
 	findCircularSchemas: () => findCircularSchemas,
 	findCircularSchemasFromGraph: () => findCircularSchemasFromGraph,
+	findSchema: () => findSchema,
+	forEachChild: () => forEachChild,
+	forEachSchema: () => forEachSchema,
 	getSchemaLiteralValues: () => getSchemaLiteralValues,
 	inferDiscriminatorPropertyName: () => inferDiscriminatorPropertyName,
 	isBareRef: () => isBareRef,
@@ -1525,12 +1624,13 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	narrowSchema: () => narrowSchema,
 	optionality: () => optionality,
 	refName: () => refName,
+	resolveRef: () => resolveRef,
 	resolveRefName: () => resolveRefName,
 	resolveSchemaProperties: () => resolveSchemaProperties,
 	schemaTypes: () => schemaTypes,
 	transform: () => transform
 });
 //#endregion
-export { applyMacros, src_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, nodes_exports as factory, findCircularSchemas, findCircularSchemasFromGraph, getSchemaLiteralValues, inferDiscriminatorPropertyName, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, optionality, refName, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
+export { applyMacros, src_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, nodes_exports as factory, findCircularSchemas, findCircularSchemasFromGraph, findSchema, forEachChild, forEachSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
 
 //# sourceMappingURL=index.js.map