@kubb/ast 5.0.0-alpha.3 → 5.0.0-alpha.5

package/dist/{visitor-oFfdU8QA.d.ts → visitor-CE4-xBHW.d.ts}

@@ -46,6 +46,7 @@ declare const schemaTypes: {
   readonly email: "email";
   readonly url: "url";
   readonly blob: "blob";
+  readonly never: "never";
 };
 declare const httpMethods: {
   readonly get: "GET";
@@ -103,14 +104,14 @@ type PropertyNode = BaseNode & {
 };
 //#endregion
 //#region src/nodes/schema.d.ts
-type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'object' | 'array' | 'date';
+type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'never' | 'object' | 'array' | 'date';
 type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum';
 /**
  * Semantic types requiring special handling in code generation (e.g. generating a `Date` object or a branded type).
  */
 type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'blob';
 type SchemaType = PrimitiveSchemaType | ComplexSchemaType | SpecialSchemaType;
-type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint'>;
+type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url'>;
 /**
  * Base fields shared by every schema variant. Does not include spec-specific fields.
  */
@@ -284,6 +285,16 @@ type NumberSchemaNode = SchemaNodeBase & {
 type ScalarSchemaNode = SchemaNodeBase & {
   type: ScalarSchemaType;
 };
+/**
+ * URL schema, optionally carrying an Express-style path template for template literal generation.
+ */
+type UrlSchemaNode = SchemaNodeBase & {
+  type: 'url';
+  /**
+   * Express-style path (e.g. `'/pets/:petId'`). When set, printers may emit a template literal type.
+   */
+  path?: string;
+};
 /**
  * Maps each schema type string to its `SchemaNode` variant. Used by `narrowSchema`.
  */
@@ -307,15 +318,16 @@ type SchemaNodeByType = {
   any: ScalarSchemaNode;
   unknown: ScalarSchemaNode;
   void: ScalarSchemaNode;
+  never: ScalarSchemaNode;
   uuid: ScalarSchemaNode;
   email: ScalarSchemaNode;
-  url: ScalarSchemaNode;
+  url: UrlSchemaNode;
   blob: ScalarSchemaNode;
 };
 /**
  * Discriminated union of all schema variants.
  */
-type SchemaNode = ObjectSchemaNode | ArraySchemaNode | UnionSchemaNode | IntersectionSchemaNode | EnumSchemaNode | RefSchemaNode | DatetimeSchemaNode | DateSchemaNode | TimeSchemaNode | StringSchemaNode | NumberSchemaNode | ScalarSchemaNode;
+type SchemaNode = ObjectSchemaNode | ArraySchemaNode | UnionSchemaNode | IntersectionSchemaNode | EnumSchemaNode | RefSchemaNode | DatetimeSchemaNode | DateSchemaNode | TimeSchemaNode | StringSchemaNode | NumberSchemaNode | UrlSchemaNode | ScalarSchemaNode;
 //#endregion
 //#region src/nodes/parameter.d.ts
 type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
@@ -396,7 +408,13 @@ type OperationNode = BaseNode & {
  * Adapters populate whichever fields are available in their source format.
  */
 type RootMeta = {
-  /** API title (from `info.title` in OAS/AsyncAPI). */title?: string; /** API version string (from `info.version` in OAS/AsyncAPI). */
+  /**
+   * API title (from `info.title` in OAS/AsyncAPI).
+   */
+  title?: string;
+  /**
+   * API version string (from `info.version` in OAS/AsyncAPI).
+   */
   version?: string;
   /**
    * Resolved base URL for the API.
@@ -412,7 +430,10 @@ type RootMeta = {
 type RootNode = BaseNode & {
   kind: 'Root';
   schemas: Array<SchemaNode>;
-  operations: Array<OperationNode>; /** Format-agnostic document metadata populated by the adapter. */
+  operations: Array<OperationNode>;
+  /**
+   * Format-agnostic document metadata populated by the adapter.
+   */
   meta?: RootMeta;
 };
 //#endregion
@@ -649,5 +670,5 @@ declare function transform(node: Node, visitor: Visitor, options?: VisitorOption
  */
 declare function collect<T>(node: Node, visitor: CollectVisitor<T>, options?: VisitorOptions): Array<T>;
 //#endregion
-export { UnionSchemaNode as $, MediaType as A, IntersectionSchemaNode as B, Node as C, OperationNode as D, HttpMethod as E, ComplexSchemaType as F, ScalarSchemaNode as G, ObjectSchemaNode as H, DateSchemaNode as I, SchemaNodeByType as J, ScalarSchemaType as K, DatetimeSchemaNode as L, ParameterLocation as M, ParameterNode as N, ResponseNode as O, ArraySchemaNode as P, TimeSchemaNode as Q, EnumSchemaNode as R, createSchema as S, RootNode as T, PrimitiveSchemaType as U, NumberSchemaNode as V, RefSchemaNode as W, SpecialSchemaType as X, SchemaType as Y, StringSchemaNode as Z, createOperation as _, transform as a, mediaTypes as at, createResponse as b, buildRefMap as c, Printer as d, PropertyNode as et, PrinterFactoryOptions as f, DistributiveOmit as g, definePrinter as h, collect as i, httpMethods as it, StatusCode as j, HttpStatusCode as k, refMapToObject as l, PrinterHandlerContext as m, CollectVisitor as n, NodeKind as nt, walk as o, nodeKinds as ot, PrinterHandler as p, SchemaNode as q, Visitor as r, VisitorDepth as rt, RefMap as s, schemaTypes as st, AsyncVisitor as t, BaseNode as tt, resolveRef as u, createParameter as v, RootMeta as w, createRoot as x, createProperty as y, EnumValueNode as z };
-//# sourceMappingURL=visitor-oFfdU8QA.d.ts.map
+export { UnionSchemaNode as $, MediaType as A, IntersectionSchemaNode as B, Node as C, OperationNode as D, HttpMethod as E, ComplexSchemaType as F, ScalarSchemaNode as G, ObjectSchemaNode as H, DateSchemaNode as I, SchemaNodeByType as J, ScalarSchemaType as K, DatetimeSchemaNode as L, ParameterLocation as M, ParameterNode as N, ResponseNode as O, ArraySchemaNode as P, TimeSchemaNode as Q, EnumSchemaNode as R, createSchema as S, RootNode as T, PrimitiveSchemaType as U, NumberSchemaNode as V, RefSchemaNode as W, SpecialSchemaType as X, SchemaType as Y, StringSchemaNode as Z, createOperation as _, transform as a, httpMethods as at, createResponse as b, buildRefMap as c, schemaTypes as ct, Printer as d, UrlSchemaNode as et, PrinterFactoryOptions as f, DistributiveOmit as g, definePrinter as h, collect as i, VisitorDepth as it, StatusCode as j, HttpStatusCode as k, refMapToObject as l, PrinterHandlerContext as m, CollectVisitor as n, BaseNode as nt, walk as o, mediaTypes as ot, PrinterHandler as p, SchemaNode as q, Visitor as r, NodeKind as rt, RefMap as s, nodeKinds as st, AsyncVisitor as t, PropertyNode as tt, resolveRef as u, createParameter as v, RootMeta as w, createRoot as x, createProperty as y, EnumValueNode as z };
+//# sourceMappingURL=visitor-CE4-xBHW.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-alpha.3",
+  "version": "5.0.0-alpha.5",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "kubb",
@@ -45,7 +45,8 @@
     "!/**/__snapshots__/**"
   ],
   "devDependencies": {
-    "@types/node": "^22.19.15"
+    "@types/node": "^22.19.15",
+    "@internals/utils": "0.0.0"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/constants.ts

@@ -56,6 +56,7 @@ export const schemaTypes = {
   email: 'email',
   url: 'url',
   blob: 'blob',
+  never: 'never',
 } as const satisfies Record<SchemaType, SchemaType>
 
 export const httpMethods = {

package/src/index.ts

@@ -3,5 +3,5 @@ export { createOperation, createParameter, createProperty, createResponse, creat
 export { isOperationNode, isParameterNode, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, narrowSchema } from './guards.ts'
 export { definePrinter } from './printer.ts'
 export { buildRefMap, refMapToObject, resolveRef } from './refs.ts'
-export { isPlainStringType } from './utils.ts'
+export { applyParamsCasing, isPlainStringType } from './utils.ts'
 export { collect, transform, walk } from './visitor.ts'

package/src/nodes/index.ts

@@ -33,6 +33,7 @@ export type {
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './schema.ts'
 
 /**

package/src/nodes/root.ts

@@ -7,9 +7,13 @@ import type { SchemaNode } from './schema.ts'
  * Adapters populate whichever fields are available in their source format.
  */
 export type RootMeta = {
-  /** API title (from `info.title` in OAS/AsyncAPI). */
+  /**
+   * API title (from `info.title` in OAS/AsyncAPI).
+   */
   title?: string
-  /** API version string (from `info.version` in OAS/AsyncAPI). */
+  /**
+   * API version string (from `info.version` in OAS/AsyncAPI).
+   */
   version?: string
   /**
    * Resolved base URL for the API.
@@ -27,6 +31,8 @@ export type RootNode = BaseNode & {
   kind: 'Root'
   schemas: Array<SchemaNode>
   operations: Array<OperationNode>
-  /** Format-agnostic document metadata populated by the adapter. */
+  /**
+   * Format-agnostic document metadata populated by the adapter.
+   */
   meta?: RootMeta
 }

package/src/nodes/schema.ts

@@ -1,7 +1,20 @@
 import type { BaseNode } from './base.ts'
 import type { PropertyNode } from './property.ts'
 
-export type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'object' | 'array' | 'date'
+export type PrimitiveSchemaType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'bigint'
+  | 'boolean'
+  | 'null'
+  | 'any'
+  | 'unknown'
+  | 'void'
+  | 'never'
+  | 'object'
+  | 'array'
+  | 'date'
 
 export type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum'
 
@@ -14,7 +27,7 @@ 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'
+  'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url'
 >
 
 /**
@@ -206,6 +219,17 @@ export type ScalarSchemaNode = SchemaNodeBase & {
   type: ScalarSchemaType
 }
 
+/**
+ * URL schema, optionally carrying an Express-style path template for template literal generation.
+ */
+export type UrlSchemaNode = SchemaNodeBase & {
+  type: 'url'
+  /**
+   * Express-style path (e.g. `'/pets/:petId'`). When set, printers may emit a template literal type.
+   */
+  path?: string
+}
+
 /**
  * Maps each schema type string to its `SchemaNode` variant. Used by `narrowSchema`.
  */
@@ -229,9 +253,10 @@ export type SchemaNodeByType = {
   any: ScalarSchemaNode
   unknown: ScalarSchemaNode
   void: ScalarSchemaNode
+  never: ScalarSchemaNode
   uuid: ScalarSchemaNode
   email: ScalarSchemaNode
-  url: ScalarSchemaNode
+  url: UrlSchemaNode
   blob: ScalarSchemaNode
 }
 
@@ -250,4 +275,5 @@ export type SchemaNode =
   | TimeSchemaNode
   | StringSchemaNode
   | NumberSchemaNode
+  | UrlSchemaNode
   | ScalarSchemaNode

package/src/types.ts

@@ -35,6 +35,7 @@ export type {
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './nodes/index.ts'
 export type { Printer, PrinterFactoryOptions, PrinterHandler, PrinterHandlerContext } from './printer.ts'
 export type { RefMap } from './refs.ts'

package/src/utils.ts

@@ -1,5 +1,7 @@
+import { camelCase, isValidVarName } from '@internals/utils'
+
 import { narrowSchema } from './guards.ts'
-import type { SchemaNode } from './nodes/index.ts'
+import type { ParameterNode, SchemaNode } from './nodes/index.ts'
 import type { SchemaType } from './nodes/schema.ts'
 
 const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'])
@@ -22,3 +24,25 @@ export function isPlainStringType(node: SchemaNode): boolean {
 
   return false
 }
+
+/**
+ * Transforms the `name` field of each parameter node according to the given casing strategy.
+ *
+ * The original `params` array is never mutated — a new array of cloned nodes is returned.
+ * When no `casing` is provided the original array is returned as-is.
+ *
+ * Use this before passing parameters to schema builders so that property keys
+ * in the generated output match the desired casing while the original
+ * `OperationNode.parameters` array remains untouched for other consumers.
+ */
+export function applyParamsCasing(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
+  if (!casing) {
+    return params
+  }
+
+  return params.map((param) => {
+    const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
+
+    return { ...param, name: transformed }
+  })
+}

package/src/visitor.ts

@@ -2,6 +2,10 @@ import type { VisitorDepth } from './constants.ts'
 import { visitorDepths, WALK_CONCURRENCY } from './constants.ts'
 import type { Node, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode } from './nodes/index.ts'
 
+/**
+ * Creates a concurrency-limiting wrapper. At most `concurrency` promises may be
+ * in-flight simultaneously; additional calls are queued and dispatched as slots free.
+ */
 function createLimit(concurrency: number) {
   let active = 0
   const queue: Array<() => void> = []
@@ -81,7 +85,10 @@ export type CollectVisitor<T> = {
 }
 
 /**
- * Traversable children of `node`, respecting `recurse` for schema nodes.
+ * Returns the immediate traversable children of `node`.
+ *
+ * For `Schema` nodes, children (properties, items, members) are only included
+ * when `recurse` is `true`; shallow traversal omits them entirely.
  */
 function getChildren(node: Node, recurse: boolean): Array<Node> {
   switch (node.kind) {
@@ -119,6 +126,9 @@ export async function walk(node: Node, visitor: AsyncVisitor, options: VisitorOp
   return _walk(node, visitor, recurse, limit)
 }
 
+/**
+ * Internal recursive walk implementation — calls visitor then recurses into children.
+ */
 async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit: LimitFn): Promise<void> {
   switch (node.kind) {
     case 'Root':