@kubb/ast 5.0.0-alpha.24 → 5.0.0-alpha.25

package/dist/{visitor-DsdLcLjR.d.ts → visitor-C2XD9px4.d.ts}

@@ -105,6 +105,14 @@ declare const schemaTypes: {
    * URL value.
    */
   readonly url: "url";
+  /**
+   * IPv4 address value.
+   */
+  readonly ipv4: "ipv4";
+  /**
+   * IPv6 address value.
+   */
+  readonly ipv6: "ipv6";
   /**
    * Binary/blob value.
    */
@@ -472,7 +480,7 @@ type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum';
 /**
  * Schema types that need special handling in generators.
  */
-type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'blob';
+type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'ipv4' | 'ipv6' | 'blob';
 /**
  * All schema type strings.
  */
@@ -480,7 +488,7 @@ type SchemaType = PrimitiveSchemaType | ComplexSchemaType | SpecialSchemaType;
 /**
  * Scalar schema types without extra object/array/ref structure.
  */
-type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url'>;
+type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url' | 'uuid' | 'email'>;
 /**
  * Fields shared by all schema nodes.
  */
@@ -559,6 +567,10 @@ type ObjectSchemaNode = SchemaNodeBase & {
    * Schema type discriminator.
    */
   type: 'object';
+  /**
+   * Primitive type — always `'object'` for object schemas.
+   */
+  primitive: 'object';
   /**
    * Ordered object properties.
    */
@@ -566,14 +578,23 @@ type ObjectSchemaNode = SchemaNodeBase & {
   /**
    * Additional object properties behavior:
    * - `true`: allow any value
+   * - `false`: reject unknown properties (maps to `.strict()` in Zod)
    * - `SchemaNode`: allow values that match that schema
-   * - `undefined`: no additional properties
+   * - `undefined`: no additional properties constraint (open object)
    */
-  additionalProperties?: SchemaNode | true;
+  additionalProperties?: SchemaNode | boolean;
   /**
    * Pattern-based property schemas.
    */
   patternProperties?: Record<string, SchemaNode>;
+  /**
+   * Minimum number of properties allowed.
+   */
+  minProperties?: number;
+  /**
+   * Maximum number of properties allowed.
+   */
+  maxProperties?: number;
 };
 /**
  * Array-like schema (`array` or `tuple`).
@@ -736,6 +757,15 @@ type RefSchemaNode = SchemaNodeBase & {
    * Pattern copied from a sibling `pattern` field.
    */
   pattern?: string;
+  /**
+   * The fully-parsed schema that this ref resolves to.
+   * Populated during OAS parsing when the referenced definition can be resolved.
+   * `undefined` when the ref cannot be resolved or is part of a circular chain.
+   *
+   * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
+   * without following the reference manually.
+   */
+  schema?: SchemaNode;
 };
 /**
  * Datetime schema.
@@ -845,6 +875,10 @@ type NumberSchemaNode = SchemaNodeBase & {
    * Exclusive maximum value.
    */
   exclusiveMaximum?: number;
+  /**
+   * The value must be a multiple of this number.
+   */
+  multipleOf?: number;
 };
 /**
  * Scalar schema with no extra constraints.
@@ -878,6 +912,64 @@ type UrlSchemaNode = SchemaNodeBase & {
    * OpenAPI-style path template, for example, `'/pets/{petId}'`.
    */
   path?: string;
+  /**
+   * Minimum string length.
+   */
+  min?: number;
+  /**
+   * Maximum string length.
+   */
+  max?: number;
+};
+/**
+ * Format-string schema for string-based formats that support length constraints.
+ *
+ * @example
+ * ```ts
+ * const uuidSchema: FormatStringSchemaNode = { kind: 'Schema', type: 'uuid', min: 36, max: 36 }
+ * ```
+ */
+type FormatStringSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'uuid' | 'email';
+  /**
+   * Minimum string length.
+   */
+  min?: number;
+  /**
+   * Maximum string length.
+   */
+  max?: number;
+};
+/**
+ * IPv4 address schema node.
+ *
+ * @example
+ * ```ts
+ * const ipv4Schema: Ipv4SchemaNode = { kind: 'Schema', type: 'ipv4' }
+ * ```
+ */
+type Ipv4SchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'ipv4';
+};
+/**
+ * IPv6 address schema node.
+ *
+ * @example
+ * ```ts
+ * const ipv6Schema: Ipv6SchemaNode = { kind: 'Schema', type: 'ipv6' }
+ * ```
+ */
+type Ipv6SchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'ipv6';
 };
 /**
  * Mapping from schema type literals to concrete schema node types.
@@ -904,15 +996,17 @@ type SchemaNodeByType = {
   unknown: ScalarSchemaNode;
   void: ScalarSchemaNode;
   never: ScalarSchemaNode;
-  uuid: ScalarSchemaNode;
-  email: ScalarSchemaNode;
+  uuid: FormatStringSchemaNode;
+  email: FormatStringSchemaNode;
   url: UrlSchemaNode;
+  ipv4: Ipv4SchemaNode;
+  ipv6: Ipv6SchemaNode;
   blob: ScalarSchemaNode;
 };
 /**
  * Union of all schema node types.
  */
-type SchemaNode = ObjectSchemaNode | ArraySchemaNode | UnionSchemaNode | IntersectionSchemaNode | EnumSchemaNode | RefSchemaNode | DatetimeSchemaNode | DateSchemaNode | TimeSchemaNode | StringSchemaNode | NumberSchemaNode | UrlSchemaNode | ScalarSchemaNode;
+type SchemaNode = ObjectSchemaNode | ArraySchemaNode | UnionSchemaNode | IntersectionSchemaNode | EnumSchemaNode | RefSchemaNode | DatetimeSchemaNode | DateSchemaNode | TimeSchemaNode | StringSchemaNode | NumberSchemaNode | UrlSchemaNode | FormatStringSchemaNode | Ipv4SchemaNode | Ipv6SchemaNode | ScalarSchemaNode;
 //#endregion
 //#region src/nodes/parameter.d.ts
 type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
@@ -1350,8 +1444,9 @@ declare function syncOptionality(schema: SchemaNode, required: boolean): SchemaN
  * ```
  */
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
-type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties'> & {
+type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties' | 'primitive'> & {
   properties?: Array<PropertyNode>;
+  primitive?: 'object';
 };
 type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>;
 type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & {
@@ -1400,17 +1495,24 @@ declare function createOperation(props: Pick<OperationNode, 'operationId' | 'met
 /**
  * Creates a `SchemaNode`, narrowed to the variant of `props.type`.
  * For object schemas, `properties` defaults to an empty array.
+ * `primitive` is automatically inferred from `type` when not explicitly provided.
  *
  * @example
  * ```ts
  * const scalar = createSchema({ type: 'string' })
- * // { kind: 'Schema', type: 'string' }
+ * // { kind: 'Schema', type: 'string', primitive: 'string' }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const uuid = createSchema({ type: 'uuid' })
+ * // { kind: 'Schema', type: 'uuid', primitive: 'string' }
  * ```
  *
  * @example
  * ```ts
  * const object = createSchema({ type: 'object' })
- * // { kind: 'Schema', type: 'object', properties: [] }
+ * // { kind: 'Schema', type: 'object', primitive: 'object', properties: [] }
  * ```
  *
  * @example
@@ -2068,5 +2170,5 @@ declare function composeTransformers(...visitors: Array<Visitor>): Visitor;
  */
 declare function collect<T>(node: Node, options: CollectOptions<T>): Array<T>;
 //#endregion
-export { ObjectSchemaNode as $, syncOptionality as A, HttpStatusCode as B, createParameter as C, httpMethods as Ct, createRoot as D, createResponse as E, schemaTypes as Et, RootMeta as F, ArraySchemaNode as G, StatusCode as H, RootNode as I, DatetimeSchemaNode as J, ComplexSchemaType as K, HttpMethod as L, InferSchemaNode as M, ParserOptions as N, createSchema as O, Node as P, NumberSchemaNode as Q, OperationNode as R, createOperation as S, VisitorDepth as St, createProperty as T, mediaTypes as Tt, ParameterLocation as U, MediaType as V, ParameterNode as W, EnumValueNode as X, EnumSchemaNode as Y, IntersectionSchemaNode as Z, createPrinterFactory as _, ParameterGroupNode as _t, TransformOptions as a, SchemaNodeByType as at, createFunctionParameter as b, NodeKind as bt, WalkOptions as c, StringSchemaNode as ct, transform as d, UrlSchemaNode as dt, PrimitiveSchemaType as et, walk as f, PropertyNode as ft, PrinterFactoryOptions as g, FunctionParametersNode as gt, Printer as h, FunctionParameterNode as ht, ParentOf as i, SchemaNode as it, InferSchema as j, createTypeNode as k, collect as l, TimeSchemaNode as lt, extractRefName as m, FunctionNodeType as mt, CollectOptions as n, ScalarSchemaNode as nt, Visitor as o, SchemaType as ot, RefMap as p, FunctionNode as pt, DateSchemaNode as q, CollectVisitor as r, ScalarSchemaType as rt, VisitorContext as s, SpecialSchemaType as st, AsyncVisitor as t, RefSchemaNode as tt, composeTransformers as u, UnionSchemaNode as ut, definePrinter as v, TypeNode as vt, createParameterGroup as w, isScalarPrimitive as wt, createFunctionParameters as x, ScalarPrimitive as xt, DistributiveOmit as y, BaseNode as yt, ResponseNode as z };
-//# sourceMappingURL=visitor-DsdLcLjR.d.ts.map
+export { Ipv4SchemaNode as $, syncOptionality as A, HttpStatusCode as B, createParameter as C, NodeKind as Ct, createRoot as D, isScalarPrimitive as Dt, createResponse as E, httpMethods as Et, RootMeta as F, ArraySchemaNode as G, StatusCode as H, RootNode as I, DatetimeSchemaNode as J, ComplexSchemaType as K, HttpMethod as L, InferSchemaNode as M, ParserOptions as N, createSchema as O, mediaTypes as Ot, Node as P, IntersectionSchemaNode as Q, OperationNode as R, createOperation as S, BaseNode as St, createProperty as T, VisitorDepth as Tt, ParameterLocation as U, MediaType as V, ParameterNode as W, EnumValueNode as X, EnumSchemaNode as Y, FormatStringSchemaNode as Z, createPrinterFactory as _, FunctionNodeType as _t, TransformOptions as a, ScalarSchemaNode as at, createFunctionParameter as b, ParameterGroupNode as bt, WalkOptions as c, SchemaNodeByType as ct, transform as d, StringSchemaNode as dt, Ipv6SchemaNode as et, walk as f, TimeSchemaNode as ft, PrinterFactoryOptions as g, FunctionNode as gt, Printer as h, PropertyNode as ht, ParentOf as i, RefSchemaNode as it, InferSchema as j, createTypeNode as k, schemaTypes as kt, collect as l, SchemaType as lt, extractRefName as m, UrlSchemaNode as mt, CollectOptions as n, ObjectSchemaNode as nt, Visitor as o, ScalarSchemaType as ot, RefMap as p, UnionSchemaNode as pt, DateSchemaNode as q, CollectVisitor as r, PrimitiveSchemaType as rt, VisitorContext as s, SchemaNode as st, AsyncVisitor as t, NumberSchemaNode as tt, composeTransformers as u, SpecialSchemaType as ut, definePrinter as v, FunctionParameterNode as vt, createParameterGroup as w, ScalarPrimitive as wt, createFunctionParameters as x, TypeNode as xt, DistributiveOmit as y, FunctionParametersNode as yt, ResponseNode as z };
+//# sourceMappingURL=visitor-C2XD9px4.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-alpha.24",
+  "version": "5.0.0-alpha.25",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "kubb",

package/src/constants.ts

@@ -126,6 +126,14 @@ export const schemaTypes = {
    * URL value.
    */
   url: 'url',
+  /**
+   * IPv4 address value.
+   */
+  ipv4: 'ipv4',
+  /**
+   * IPv6 address value.
+   */
+  ipv6: 'ipv6',
   /**
    * Binary/blob value.
    */

package/src/factory.ts

@@ -6,6 +6,7 @@ import type {
   OperationNode,
   ParameterGroupNode,
   ParameterNode,
+  PrimitiveSchemaType,
   PropertyNode,
   ResponseNode,
   RootNode,
@@ -42,7 +43,7 @@ export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNo
  */
 export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
 
-type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties'> & { properties?: Array<PropertyNode> }
+type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties' | 'primitive'> & { properties?: Array<PropertyNode>; primitive?: 'object' }
 type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>
 type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & { kind: 'Schema' }
 
@@ -105,20 +106,53 @@ export function createOperation(
   }
 }
 
+/**
+ * Maps schema `type` to its underlying `primitive`.
+ * Primitive types map to themselves; special string formats map to `'string'`.
+ * Complex types (`ref`, `enum`, `union`, `intersection`, `tuple`, `blob`) are left unset.
+ */
+const TYPE_TO_PRIMITIVE: Partial<Record<SchemaNode['type'], PrimitiveSchemaType>> = {
+  string: 'string',
+  number: 'number',
+  integer: 'integer',
+  bigint: 'bigint',
+  boolean: 'boolean',
+  null: 'null',
+  any: 'any',
+  unknown: 'unknown',
+  void: 'void',
+  never: 'never',
+  object: 'object',
+  array: 'array',
+  date: 'date',
+  uuid: 'string',
+  email: 'string',
+  url: 'string',
+  datetime: 'string',
+  time: 'string',
+}
+
 /**
  * Creates a `SchemaNode`, narrowed to the variant of `props.type`.
  * For object schemas, `properties` defaults to an empty array.
+ * `primitive` is automatically inferred from `type` when not explicitly provided.
  *
  * @example
  * ```ts
  * const scalar = createSchema({ type: 'string' })
- * // { kind: 'Schema', type: 'string' }
+ * // { kind: 'Schema', type: 'string', primitive: 'string' }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const uuid = createSchema({ type: 'uuid' })
+ * // { kind: 'Schema', type: 'uuid', primitive: 'string' }
  * ```
  *
  * @example
  * ```ts
  * const object = createSchema({ type: 'object' })
- * // { kind: 'Schema', type: 'object', properties: [] }
+ * // { kind: 'Schema', type: 'object', primitive: 'object', properties: [] }
  * ```
  *
  * @example
@@ -133,11 +167,13 @@ export function createOperation(
 export function createSchema<T extends CreateSchemaInput>(props: T): CreateSchemaOutput<T>
 export function createSchema(props: CreateSchemaInput): SchemaNode
 export function createSchema(props: CreateSchemaInput): SchemaNode {
+  const inferredPrimitive = TYPE_TO_PRIMITIVE[props.type as keyof typeof TYPE_TO_PRIMITIVE]
+
   if (props['type'] === 'object') {
-    return { properties: [], ...props, kind: 'Schema' } as CreateSchemaOutput<typeof props>
+    return { properties: [], primitive: 'object', ...props, kind: 'Schema' } as CreateSchemaOutput<typeof props>
   }
 
-  return { ...props, kind: 'Schema' } as CreateSchemaOutput<typeof props>
+  return { primitive: inferredPrimitive, ...props, kind: 'Schema' } as CreateSchemaOutput<typeof props>
 }
 
 /**

package/src/index.ts

@@ -21,5 +21,5 @@ export { extractRefName } from './refs.ts'
 export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
 export { mergeAdjacentObjects, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
 export type { OperationParamsResolver } from './utils.ts'
-export { caseParams, createDiscriminantNode, createOperationParams, isStringType } from './utils.ts'
+export { caseParams, createDiscriminantNode, createOperationParams, isStringType, syncSchemaRef } from './utils.ts'
 export { collect, composeTransformers, transform, walk } from './visitor.ts'

package/src/nodes/index.ts

@@ -21,7 +21,10 @@ export type {
   DatetimeSchemaNode,
   EnumSchemaNode,
   EnumValueNode,
+  FormatStringSchemaNode,
   IntersectionSchemaNode,
+  Ipv4SchemaNode,
+  Ipv6SchemaNode,
   NumberSchemaNode,
   ObjectSchemaNode,
   PrimitiveSchemaType,

package/src/nodes/schema.ts

@@ -63,7 +63,7 @@ export type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum'
 /**
  * Schema types that need special handling in generators.
  */
-export type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'blob'
+export type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'ipv4' | 'ipv6' | 'blob'
 
 /**
  * All schema type strings.
@@ -75,7 +75,23 @@ export type SchemaType = PrimitiveSchemaType | ComplexSchemaType | SpecialSchema
  */
 export type ScalarSchemaType = Exclude<
   SchemaType,
-  'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url'
+  | 'object'
+  | 'array'
+  | 'tuple'
+  | 'union'
+  | 'intersection'
+  | 'enum'
+  | 'ref'
+  | 'datetime'
+  | 'date'
+  | 'time'
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'bigint'
+  | 'url'
+  | 'uuid'
+  | 'email'
 >
 
 /**
@@ -157,6 +173,10 @@ export type ObjectSchemaNode = SchemaNodeBase & {
    * Schema type discriminator.
    */
   type: 'object'
+  /**
+   * Primitive type — always `'object'` for object schemas.
+   */
+  primitive: 'object'
   /**
    * Ordered object properties.
    */
@@ -164,14 +184,23 @@ export type ObjectSchemaNode = SchemaNodeBase & {
   /**
    * Additional object properties behavior:
    * - `true`: allow any value
+   * - `false`: reject unknown properties (maps to `.strict()` in Zod)
    * - `SchemaNode`: allow values that match that schema
-   * - `undefined`: no additional properties
+   * - `undefined`: no additional properties constraint (open object)
    */
-  additionalProperties?: SchemaNode | true
+  additionalProperties?: SchemaNode | boolean
   /**
    * Pattern-based property schemas.
    */
   patternProperties?: Record<string, SchemaNode>
+  /**
+   * Minimum number of properties allowed.
+   */
+  minProperties?: number
+  /**
+   * Maximum number of properties allowed.
+   */
+  maxProperties?: number
 }
 
 /**
@@ -341,6 +370,15 @@ export type RefSchemaNode = SchemaNodeBase & {
    * Pattern copied from a sibling `pattern` field.
    */
   pattern?: string
+  /**
+   * The fully-parsed schema that this ref resolves to.
+   * Populated during OAS parsing when the referenced definition can be resolved.
+   * `undefined` when the ref cannot be resolved or is part of a circular chain.
+   *
+   * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
+   * without following the reference manually.
+   */
+  schema?: SchemaNode
 }
 
 /**
@@ -456,6 +494,10 @@ export type NumberSchemaNode = SchemaNodeBase & {
    * Exclusive maximum value.
    */
   exclusiveMaximum?: number
+  /**
+   * The value must be a multiple of this number.
+   */
+  multipleOf?: number
 }
 
 /**
@@ -491,6 +533,67 @@ export type UrlSchemaNode = SchemaNodeBase & {
    * OpenAPI-style path template, for example, `'/pets/{petId}'`.
    */
   path?: string
+  /**
+   * Minimum string length.
+   */
+  min?: number
+  /**
+   * Maximum string length.
+   */
+  max?: number
+}
+
+/**
+ * Format-string schema for string-based formats that support length constraints.
+ *
+ * @example
+ * ```ts
+ * const uuidSchema: FormatStringSchemaNode = { kind: 'Schema', type: 'uuid', min: 36, max: 36 }
+ * ```
+ */
+export type FormatStringSchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'uuid' | 'email'
+  /**
+   * Minimum string length.
+   */
+  min?: number
+  /**
+   * Maximum string length.
+   */
+  max?: number
+}
+
+/**
+ * IPv4 address schema node.
+ *
+ * @example
+ * ```ts
+ * const ipv4Schema: Ipv4SchemaNode = { kind: 'Schema', type: 'ipv4' }
+ * ```
+ */
+export type Ipv4SchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'ipv4'
+}
+
+/**
+ * IPv6 address schema node.
+ *
+ * @example
+ * ```ts
+ * const ipv6Schema: Ipv6SchemaNode = { kind: 'Schema', type: 'ipv6' }
+ * ```
+ */
+export type Ipv6SchemaNode = SchemaNodeBase & {
+  /**
+   * Schema type discriminator.
+   */
+  type: 'ipv6'
 }
 
 /**
@@ -518,9 +621,11 @@ export type SchemaNodeByType = {
   unknown: ScalarSchemaNode
   void: ScalarSchemaNode
   never: ScalarSchemaNode
-  uuid: ScalarSchemaNode
-  email: ScalarSchemaNode
+  uuid: FormatStringSchemaNode
+  email: FormatStringSchemaNode
   url: UrlSchemaNode
+  ipv4: Ipv4SchemaNode
+  ipv6: Ipv6SchemaNode
   blob: ScalarSchemaNode
 }
 
@@ -540,4 +645,7 @@ export type SchemaNode =
   | StringSchemaNode
   | NumberSchemaNode
   | UrlSchemaNode
+  | FormatStringSchemaNode
+  | Ipv4SchemaNode
+  | Ipv6SchemaNode
   | ScalarSchemaNode

package/src/types.ts

@@ -9,6 +9,7 @@ export type {
   DatetimeSchemaNode,
   EnumSchemaNode,
   EnumValueNode,
+  FormatStringSchemaNode,
   FunctionNode,
   FunctionNodeType,
   FunctionParameterNode,
@@ -16,6 +17,8 @@ export type {
   HttpMethod,
   HttpStatusCode,
   IntersectionSchemaNode,
+  Ipv4SchemaNode,
+  Ipv6SchemaNode,
   MediaType,
   Node,
   NodeKind,

package/src/utils.ts

@@ -7,6 +7,29 @@ import type { SchemaType } from './nodes/schema.ts'
 
 const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
 
+/**
+ * Returns a merged schema view for a ref node, combining the resolved `node.schema`
+ * (base from the referenced definition) with any usage-site sibling fields set directly
+ * on the ref node (description, readOnly, nullable, deprecated, etc.).
+ *
+ * Usage-site fields take precedence over the resolved schema's own fields when both are defined.
+ *
+ * For non-ref nodes the node itself is returned unchanged.
+ */
+export function syncSchemaRef(node: SchemaNode): SchemaNode {
+  const ref = narrowSchema(node, 'ref')
+
+  if (!ref) return node
+  if (!ref.schema) return node
+
+  const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = ref
+
+  // Filter out undefined override values so they don't shadow the resolved schema's fields.
+  const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))
+
+  return createSchema({ ...ref.schema, ...definedOverrides })
+}
+
 /**
  * Returns `true` when a schema is emitted as a plain `string` type.
  *

package/src/visitor.ts

@@ -11,11 +11,9 @@ import type { Node, OperationNode, ParameterNode, PropertyNode, ResponseNode, Ro
  * @example
  * ```ts
  * const limit = createLimit(2)
- * await Promise.all([
- *   limit(() => taskA()),
- *   limit(() => taskB()),
- *   limit(() => taskC()),
- * ])
+ * for (const task of [taskA, taskB, taskC]) {
+ *   await limit(() => task())
+ * }
  * // only 2 tasks run at the same time
  * ```
  */
@@ -349,7 +347,9 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
   }
 
   const children = getChildren(node, recurse)
-  await Promise.all(children.map((child) => _walk(child, visitor, recurse, limit, node)))
+  for (const child of children) {
+    await _walk(child, visitor, recurse, limit, node)
+  }
 }
 
 /**