@kubb/ast 5.0.0-beta.43 → 5.0.0-beta.45

package/src/types.ts

@@ -1,5 +1,4 @@
-export type { VisitorDepth } from './constants.ts'
-export type { BuildDedupePlanOptions, DedupeCanonical, DedupePlan } from './dedupe.ts'
+export type { DedupePlan } from './dedupe.ts'
 export type { SchemaDialect } from './dialect.ts'
 export type { DispatchRule } from './dispatch.ts'
 export type { DistributiveOmit } from './factory.ts'
@@ -7,44 +6,32 @@ export type { InferSchemaNode, ParserOptions } from './infer.ts'
 export type {
   ArraySchemaNode,
   ArrowFunctionNode,
-  BaseNode,
-  BreakNode,
   CodeNode,
-  ComplexSchemaType,
   ConstNode,
   DateSchemaNode,
   DatetimeSchemaNode,
   EnumSchemaNode,
-  EnumValueNode,
   ExportNode,
   FileNode,
-  FormatStringSchemaNode,
   FunctionNode,
   FunctionNodeType,
   FunctionParameterNode,
   FunctionParametersNode,
   FunctionParamNode,
-  GenericOperationNode,
   HttpMethod,
   HttpOperationNode,
-  HttpStatusCode,
   ImportNode,
   InputMeta,
   InputNode,
   InputStreamNode,
   IntersectionSchemaNode,
-  Ipv4SchemaNode,
-  Ipv6SchemaNode,
   JSDocNode,
   JsxNode,
-  MediaType,
   Node,
   NodeKind,
   NumberSchemaNode,
   ObjectSchemaNode,
   OperationNode,
-  OperationNodeBase,
-  OperationProtocol,
   OutputNode,
   ParameterGroupNode,
   ParameterLocation,
@@ -54,24 +41,20 @@ export type {
   PropertyNode,
   RefSchemaNode,
   ResponseNode,
-  ScalarSchemaNode,
   ScalarSchemaType,
   SchemaNode,
   SchemaNodeByType,
   SchemaType,
   SourceNode,
-  SpecialSchemaType,
   StatusCode,
   StringSchemaNode,
   TextNode,
   TimeSchemaNode,
-  TypeDeclarationNode,
   TypeNode,
   UnionSchemaNode,
   UrlSchemaNode,
 } from './nodes/index.ts'
-export type { AsyncVisitor, CollectOptions, CollectVisitor, ParentOf, TransformOptions, Visitor, VisitorContext, WalkOptions } from './visitor.ts'
+export type { ParentOf, Visitor, VisitorContext } from './visitor.ts'
 export type { Printer, PrinterFactoryOptions, PrinterPartial } from './printer.ts'
-export type { ScalarPrimitive } from './constants.ts'
-export type { OperationParamsResolver } from './utils.ts'
+export type { OperationParamsResolver } from './utils/ast.ts'
 export type { UserFileNode } from './factory.ts'

package/src/{utils.ts → utils/ast.ts}

@@ -1,8 +1,7 @@
 import { camelCase, isValidVarName, memoize } from '@internals/utils'
 
-import { INDENT } from './constants.ts'
-import { createFunctionParameter, createFunctionParameters, createParameterGroup, createParamsType, createProperty, createSchema } from './factory.ts'
-import { narrowSchema } from './guards.ts'
+import { createFunctionParameter, createFunctionParameters, createParameterGroup, createParamsType, createProperty, createSchema } from '../factory.ts'
+import { narrowSchema } from '../guards.ts'
 import type {
   CodeNode,
   ExportNode,
@@ -15,10 +14,10 @@ import type {
   ParamsTypeNode,
   SchemaNode,
   SourceNode,
-} from './nodes/index.ts'
-import type { SchemaType } from './nodes/schema.ts'
-import { extractRefName } from './refs.ts'
-import { collect, collectLazy } from './visitor.ts'
+} from '../nodes/index.ts'
+import type { SchemaType } from '../nodes/schema.ts'
+import { extractRefName } from './index.ts'
+import { collect, collectLazy } from '../visitor.ts'
 
 const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
 
@@ -119,7 +118,7 @@ export function createDiscriminantNode({ propertyName, value }: { propertyName:
 /**
  * Named type for a group of parameters (query or header) emitted as a single typed parameter.
  */
-export type ParamGroupType = {
+type ParamGroupType = {
   /**
    * TypeNode for the group type.
    */
@@ -762,68 +761,6 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
     .join('\n')
 }
 
-/**
- * Indents every non-empty line of `text` by one indent level, leaving blank lines empty.
- */
-function indentLines(text: string): string {
-  if (!text) return ''
-  return text
-    .split('\n')
-    .map((line) => (line.trim() ? `${INDENT}${line}` : ''))
-    .join('\n')
-}
-
-/**
- * Renders an object key, quoting it only when it is not a valid variable name.
- *
- * @example
- * ```ts
- * objectKey('id')      // 'id'
- * objectKey('x-total') // '"x-total"'
- * ```
- */
-export function objectKey(name: string): string {
-  return isValidVarName(name) ? name : JSON.stringify(name)
-}
-
-/**
- * Assembles a multi-line object literal from already-rendered `entries`, indenting each entry one
- * level and closing the brace at column zero. Nested objects built the same way indent cumulatively,
- * so callers never re-parse the generated code. A trailing comma is added per entry to match the
- * formatter's multi-line style.
- *
- * @example
- * ```ts
- * buildObject(['id: z.number()', 'name: z.string()'])
- * // '{\n  id: z.number(),\n  name: z.string(),\n}'
- * ```
- */
-export function buildObject(entries: Array<string>): string {
-  if (entries.length === 0) return '{}'
-  const body = entries.map((entry) => `${indentLines(entry)},`).join('\n')
-  return `{\n${body}\n}`
-}
-
-/**
- * Assembles a bracketed list (array by default) from already-rendered `items`. Keeps everything on
- * one line when no item spans multiple lines, and otherwise puts each item on its own line, indented
- * one level with a trailing comma and the closing bracket at column zero. Use it for `z.union([…])`,
- * `z.array([…])`, and similar member lists so objects inside them nest correctly.
- *
- * @example
- * ```ts
- * buildList(['z.string()', 'z.number()'])
- * // '[z.string(), z.number()]'
- * ```
- */
-export function buildList(items: Array<string>, brackets: [open: string, close: string] = ['[', ']']): string {
-  const [open, close] = brackets
-  if (items.length === 0) return `${open}${close}`
-  if (!items.some((item) => item.includes('\n'))) return `${open}${items.join(', ')}${close}`
-  const body = items.map((item) => `${indentLines(item)},`).join('\n')
-  return `${open}\n${body}\n${close}`
-}
-
 /**
  * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
  *

package/src/utils/index.ts

@@ -0,0 +1,295 @@
+import { isIdentifier, pascalCase, singleQuote } from '@internals/utils'
+import { INDENT } from '../constants.ts'
+
+export { ensureValidVarName, isValidVarName } from '@internals/utils'
+
+/**
+ * Strips a single matching pair of `"..."`, `'...'`, or `` `...` `` from both ends of `text`.
+ * Returns the string unchanged when no balanced quote pair is found.
+ *
+ * @example
+ * ```ts
+ * trimQuotes('"hello"') // 'hello'
+ * trimQuotes('hello')   // 'hello'
+ * ```
+ */
+export function trimQuotes(text: string): string {
+  if (text.length >= 2) {
+    const first = text[0]
+    const last = text[text.length - 1]
+    if ((first === '"' && last === '"') || (first === "'" && last === "'") || (first === '`' && last === '`')) {
+      return text.slice(1, -1)
+    }
+  }
+  return text
+}
+
+/**
+ * Serializes a primitive value to a single-quoted string literal, stripping any surrounding quote
+ * characters first. Escaping comes from `JSON.stringify`, then the quote style switches to single
+ * quotes so generated code matches the repo style without a formatter.
+ *
+ * @example
+ * ```ts
+ * stringify('hello')   // "'hello'"
+ * stringify('"hello"') // "'hello'"
+ * ```
+ */
+export function stringify(value: string | number | boolean | undefined): string {
+  if (value === undefined || value === null) return "''"
+  const json = JSON.stringify(trimQuotes(value.toString()))
+  const inner = json.slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'")
+  return `'${inner}'`
+}
+
+/**
+ * Escapes characters that are not allowed inside JS string literals, covering quotes, backslashes,
+ * and the Unicode line terminators U+2028 and U+2029.
+ *
+ * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4
+ *
+ * @example
+ * ```ts
+ * jsStringEscape('say "hi"\nbye') // 'say \\"hi\\"\\nbye'
+ * ```
+ */
+export function jsStringEscape(input: unknown): string {
+  return `${input}`.replace(/["'\\\n\r\u2028\u2029]/g, (character) => {
+    switch (character) {
+      case '"':
+      case "'":
+      case '\\':
+        return `\\${character}`
+      case '\n':
+        return '\\n'
+      case '\r':
+        return '\\r'
+      case '\u2028':
+        return '\\u2028'
+      case '\u2029':
+        return '\\u2029'
+      default:
+        return ''
+    }
+  })
+}
+
+/**
+ * Converts a pattern string into a `new RegExp(...)` constructor call or a regex literal string.
+ * Inline flags expressed as a `^(?im)` prefix are extracted and applied to the resulting expression.
+ * Pass `null` as the second argument to emit a `/pattern/flags` literal instead.
+ *
+ * @example
+ * ```ts
+ * toRegExpString('^(?im)foo')       // 'new RegExp("^foo", "im")'
+ * toRegExpString('^(?im)foo', null) // '/^foo/im'
+ * ```
+ */
+export function toRegExpString(text: string, func: string | null = 'RegExp'): string {
+  const raw = trimQuotes(text)
+
+  const match = raw.match(/^\^(\(\?([igmsuy]+)\))/i)
+  const replacementTarget = match?.[1] ?? ''
+  const matchedFlags = match?.[2]
+  const cleaned = raw
+    .replace(/^\\?\//, '')
+    .replace(/\\?\/$/, '')
+    .replace(replacementTarget, '')
+
+  const { source, flags } = new RegExp(cleaned, matchedFlags)
+
+  if (func === null) return `/${source}/${flags}`
+
+  return `new ${func}(${JSON.stringify(source)}${flags ? `, ${JSON.stringify(flags)}` : ''})`
+}
+
+/**
+ * Renders a plain object as multi-line `key: value` source for embedding in generated code. Nested
+ * objects recurse with fixed indentation, so the result drops straight into an object literal
+ * without re-parsing.
+ *
+ * @example
+ * ```ts
+ * stringifyObject({ foo: 'bar', nested: { a: 1 } })
+ * // 'foo: bar,\nnested: {\n        a: 1\n      }'
+ * ```
+ */
+export function stringifyObject(value: Record<string, unknown>): string {
+  const items = Object.entries(value)
+    .map(([key, val]) => {
+      if (val !== null && typeof val === 'object') {
+        return `${key}: {\n        ${stringifyObject(val as Record<string, unknown>)}\n      }`
+      }
+      return `${key}: ${val}`
+    })
+    .filter(Boolean)
+  return items.join(',\n')
+}
+
+/**
+ * Renders a dotted path or string array as an optional-chaining accessor expression rooted at
+ * `accessor`. Returns `null` for an empty path.
+ *
+ * @example
+ * ```ts
+ * getNestedAccessor('pagination.next.id', 'lastPage')
+ * // "lastPage?.['pagination']?.['next']?.['id']"
+ * ```
+ */
+export function getNestedAccessor(param: string | Array<string>, accessor: string): string | null {
+  const parts = Array.isArray(param) ? param : param.split('.')
+  if (parts.length === 0 || (parts.length === 1 && parts[0] === '')) return null
+  return `${accessor}?.['${`${parts.join("']?.['")}']`}`
+}
+
+/**
+ * Builds a JSDoc comment block from an array of lines, returning `fallback` when there are no
+ * comments so callers always get a usable string.
+ *
+ * @example
+ * ```ts
+ * buildJSDoc(['@type string', '@example hello'])
+ * // '/**\n   * @type string\n   * @example hello\n   *\/\n  '
+ * ```
+ */
+export function buildJSDoc(
+  comments: Array<string>,
+  options: {
+    /**
+     * String used to indent each comment line.
+     * @default '   * '
+     */
+    indent?: string
+    /**
+     * String appended after the closing tag.
+     * @default '\n  '
+     */
+    suffix?: string
+    /**
+     * Returned as-is when `comments` is empty.
+     * @default '  '
+     */
+    fallback?: string
+  } = {},
+): string {
+  const { indent = '   * ', suffix = '\n  ', fallback = '  ' } = options
+
+  if (comments.length === 0) return fallback
+
+  return `/**\n${comments.map((c) => `${indent}${c}`).join('\n')}\n   */${suffix}`
+}
+
+/**
+ * Indents every non-empty line of `text` by one indent level, leaving blank lines empty.
+ */
+function indentLines(text: string): string {
+  if (!text) return ''
+  return text
+    .split('\n')
+    .map((line) => (line.trim() ? `${INDENT}${line}` : ''))
+    .join('\n')
+}
+
+/**
+ * Renders an object key, quoting it with single quotes only when it is not a valid identifier.
+ * Reserved words and globals (`name`, `class`, …) are valid bare keys and stay unquoted.
+ *
+ * @example
+ * ```ts
+ * objectKey('name')    // 'name'
+ * objectKey('x-total') // "'x-total'"
+ * ```
+ */
+export function objectKey(name: string): string {
+  return isIdentifier(name) ? name : singleQuote(name)
+}
+
+/**
+ * Assembles a multi-line object literal from already-rendered `entries`, indenting each entry one
+ * level and closing the brace at column zero. Nested objects built the same way indent cumulatively,
+ * so callers never re-parse the generated code. A trailing comma is added per entry to match the
+ * formatter's multi-line style.
+ *
+ * @example
+ * ```ts
+ * buildObject(['id: z.number()', 'name: z.string()'])
+ * // '{\n  id: z.number(),\n  name: z.string(),\n}'
+ * ```
+ */
+export function buildObject(entries: Array<string>): string {
+  if (entries.length === 0) return '{}'
+  const body = entries.map((entry) => `${indentLines(entry)},`).join('\n')
+  return `{\n${body}\n}`
+}
+
+/**
+ * Assembles a bracketed list (array by default) from already-rendered `items`. Keeps everything on
+ * one line when no item spans multiple lines, and otherwise puts each item on its own line, indented
+ * one level with a trailing comma and the closing bracket at column zero. Use it for `z.union([…])`,
+ * `z.array([…])`, and similar member lists so objects inside them nest correctly.
+ *
+ * @example
+ * ```ts
+ * buildList(['z.string()', 'z.number()'])
+ * // '[z.string(), z.number()]'
+ * ```
+ */
+export function buildList(items: Array<string>, brackets: [open: string, close: string] = ['[', ']']): string {
+  const [open, close] = brackets
+  if (items.length === 0) return `${open}${close}`
+  if (!items.some((item) => item.includes('\n'))) return `${open}${items.join(', ')}${close}`
+  const body = items.map((item) => `${indentLines(item)},`).join('\n')
+  return `${open}\n${body}\n${close}`
+}
+
+/**
+ * Returns the last path segment of a reference string.
+ *
+ * @example
+ * ```ts
+ * extractRefName('#/components/schemas/Pet') // 'Pet'
+ * ```
+ */
+export function extractRefName(ref: string): string {
+  return ref.split('/').at(-1) ?? ref
+}
+
+/**
+ * Builds a PascalCase child schema name by joining a parent name and property name.
+ * Returns `null` when there is no parent to nest under.
+ *
+ * @example
+ * ```ts
+ * childName('Order', 'shipping_address') // 'OrderShippingAddress'
+ * childName(undefined, 'params')         // null
+ * ```
+ */
+export function childName(parentName: string | null | undefined, propName: string): string | null {
+  return parentName ? pascalCase([parentName, propName].join(' ')) : null
+}
+
+/**
+ * Builds a PascalCase enum name from the parent name, property name, and a suffix, skipping any
+ * empty parts.
+ *
+ * @example
+ * ```ts
+ * enumPropName('Order', 'status', 'enum') // 'OrderStatusEnum'
+ * ```
+ */
+export function enumPropName(parentName: string | null | undefined, propName: string, enumSuffix: string): string {
+  return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
+}
+
+/**
+ * Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
+ *
+ * @example
+ * ```ts
+ * findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
+ * ```
+ */
+export function findDiscriminator(mapping: Record<string, string> | undefined, ref: string | undefined): string | null {
+  if (!mapping || !ref) return null
+  return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null
+}

package/src/visitor.ts

@@ -182,7 +182,7 @@ type MaybePromise<T> = T | Promise<T>
  * }
  * ```
  */
-export type AsyncVisitor = {
+type AsyncVisitor = {
   input?(node: InputNode, context: VisitorContext<InputNode>): MaybePromise<undefined | null | InputNode>
   output?(node: OutputNode, context: VisitorContext<OutputNode>): MaybePromise<undefined | null | OutputNode>
   operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<undefined | null | OperationNode>
@@ -204,7 +204,7 @@ export type AsyncVisitor = {
  * }
  * ```
  */
-export type CollectVisitor<T> = {
+type CollectVisitor<T> = {
   input?(node: InputNode, context: VisitorContext<InputNode>): T | null | undefined
   output?(node: OutputNode, context: VisitorContext<OutputNode>): T | null | undefined
   operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | null | undefined

package/src/refs.ts

@@ -1,13 +0,0 @@
-/**
- * Returns the last path segment of a reference string.
- *
- * Example: `#/components/schemas/Pet` becomes `Pet`.
- *
- * @example
- * ```ts
- * extractRefName('#/components/schemas/Pet') // 'Pet'
- * ```
- */
-export function extractRefName(ref: string): string {
-  return ref.split('/').at(-1) ?? ref
-}