@kubb/ast 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/transformers.ts

@@ -0,0 +1,196 @@
+import { SCALAR_PRIMITIVE_TYPES } from './constants.ts'
+import { createProperty, createSchema } from './factory.ts'
+import { narrowSchema } from './guards.ts'
+import type { SchemaNode } from './nodes/schema.ts'
+import { enumPropName } from './resolvers.ts'
+import { transform } from './visitor.ts'
+
+/**
+ * Replaces a discriminator property's schema with a string enum of allowed values.
+ *
+ * If `node` is not an object schema, or if the property does not exist, the input
+ * node is returned as-is.
+ *
+ * @example
+ * ```ts
+ * const schema = createSchema({
+ *   type: 'object',
+ *   properties: [createProperty({ name: 'type', required: true, schema: createSchema({ type: 'string' }) })],
+ * })
+ * const result = setDiscriminatorEnum({ node: schema, propertyName: 'type', values: ['dog', 'cat'] })
+ * ```
+ */
+export function setDiscriminatorEnum({
+  node,
+  propertyName,
+  values,
+  enumName,
+}: {
+  node: SchemaNode
+  propertyName: string
+  values: Array<string>
+  enumName?: string
+}): SchemaNode {
+  const objectNode = narrowSchema(node, 'object')
+  if (!objectNode?.properties?.length) {
+    return node
+  }
+
+  const hasProperty = objectNode.properties.some((prop) => prop.name === propertyName)
+  if (!hasProperty) {
+    return node
+  }
+
+  return createSchema({
+    ...objectNode,
+    properties: objectNode.properties.map((prop) => {
+      if (prop.name !== propertyName) {
+        return prop
+      }
+
+      return createProperty({
+        ...prop,
+        schema: createSchema({
+          type: 'enum',
+          primitive: 'string',
+          enumValues: values,
+          name: enumName,
+          readOnly: prop.schema.readOnly,
+          writeOnly: prop.schema.writeOnly,
+        }),
+      })
+    }),
+  })
+}
+
+/**
+ * Merges adjacent anonymous object members into a single anonymous object member.
+ *
+ * @example
+ * ```ts
+ * const merged = mergeAdjacentObjects([
+ *   createSchema({ type: 'object', properties: [createProperty({ name: 'a', schema: createSchema({ type: 'string' }) })] }),
+ *   createSchema({ type: 'object', properties: [createProperty({ name: 'b', schema: createSchema({ type: 'number' }) })] }),
+ * ])
+ * ```
+ */
+export function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode> {
+  return members.reduce<Array<SchemaNode>>((acc, member) => {
+    const objectMember = narrowSchema(member, 'object')
+    if (objectMember && !objectMember.name) {
+      const previous = acc.at(-1)
+      const previousObject = previous ? narrowSchema(previous, 'object') : undefined
+
+      if (previousObject && !previousObject.name) {
+        acc[acc.length - 1] = createSchema({
+          ...previousObject,
+          properties: [...(previousObject.properties ?? []), ...(objectMember.properties ?? [])],
+        })
+        return acc
+      }
+    }
+
+    acc.push(member)
+    return acc
+  }, [])
+}
+
+/**
+ * Removes enum members that are covered by broader scalar primitives in the same union.
+ *
+ * @example
+ * ```ts
+ * const simplified = simplifyUnion([
+ *   createSchema({ type: 'enum', primitive: 'string', enumValues: ['active'] }),
+ *   createSchema({ type: 'string' }),
+ * ])
+ * // keeps only string member
+ * ```
+ */
+export function simplifyUnion(members: Array<SchemaNode>): Array<SchemaNode> {
+  const scalarPrimitives = new Set(
+    members.filter((member) => SCALAR_PRIMITIVE_TYPES.has(member.type as typeof SCALAR_PRIMITIVE_TYPES extends Set<infer T> ? T : never)).map((m) => m.type),
+  )
+
+  if (!scalarPrimitives.size) {
+    return members
+  }
+
+  return members.filter((member) => {
+    const enumNode = narrowSchema(member, 'enum')
+    if (!enumNode) {
+      return true
+    }
+
+    const primitive = enumNode.primitive
+    if (!primitive) {
+      return true
+    }
+
+    const enumValueCount = enumNode.namedEnumValues?.length ?? enumNode.enumValues?.length ?? 0
+    if (enumValueCount <= 1) {
+      return true
+    }
+
+    if (scalarPrimitives.has(primitive)) {
+      return false
+    }
+
+    if ((primitive === 'integer' || primitive === 'number') && (scalarPrimitives.has('integer') || scalarPrimitives.has('number'))) {
+      return false
+    }
+
+    return true
+  })
+}
+
+export function setEnumName(propNode: SchemaNode, parentName: string | null | undefined, propName: string, enumSuffix: string): SchemaNode {
+  const enumNode = narrowSchema(propNode, 'enum')
+
+  if (enumNode?.primitive === 'boolean') {
+    return { ...propNode, name: undefined }
+  }
+
+  if (enumNode) {
+    return { ...propNode, name: enumPropName(parentName, propName, enumSuffix) }
+  }
+
+  return propNode
+}
+
+/**
+ * Walks a schema tree and resolves `ref`/`enum` names through callbacks.
+ */
+export function resolveNames({
+  node,
+  nameMapping,
+  resolveName,
+  resolveEnumName,
+}: {
+  node: SchemaNode
+  nameMapping: Map<string, string>
+  resolveName: (ref: string) => string | undefined
+  resolveEnumName?: (name: string) => string | undefined
+}): SchemaNode {
+  return transform(node, {
+    schema(schemaNode) {
+      const schemaRef = narrowSchema(schemaNode, 'ref')
+
+      if (schemaRef && (schemaRef.ref || schemaRef.name)) {
+        const rawRef = schemaRef.ref ?? schemaRef.name!
+        const resolved = resolveName(nameMapping.get(rawRef) ?? rawRef)
+        if (resolved) {
+          return { ...schemaNode, name: resolved }
+        }
+      }
+
+      const schemaEnum = narrowSchema(schemaNode, 'enum')
+      if (schemaEnum?.name) {
+        const resolved = (resolveEnumName ?? resolveName)(schemaEnum.name)
+        if (resolved) {
+          return { ...schemaNode, name: resolved }
+        }
+      }
+    },
+  }) as SchemaNode
+}

package/src/types.ts

@@ -1,5 +1,6 @@
 export type { VisitorDepth } from './constants.ts'
 export type { DistributiveOmit } from './factory.ts'
+export type { InferSchema, InferSchemaNode, ParserOptions } from './infer.ts'
 export type {
   ArraySchemaNode,
   BaseNode,
@@ -8,6 +9,10 @@ export type {
   DatetimeSchemaNode,
   EnumSchemaNode,
   EnumValueNode,
+  FunctionNode,
+  FunctionNodeType,
+  FunctionParameterNode,
+  FunctionParametersNode,
   HttpMethod,
   HttpStatusCode,
   IntersectionSchemaNode,
@@ -15,6 +20,7 @@ export type {
   Node,
   NodeKind,
   NumberSchemaNode,
+  ObjectBindingParameterNode,
   ObjectSchemaNode,
   OperationNode,
   ParameterLocation,
@@ -35,7 +41,8 @@ export type {
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './nodes/index.ts'
-export type { Printer, PrinterFactoryOptions, PrinterHandler, PrinterHandlerContext } from './printer.ts'
+export type { Printer, PrinterFactoryOptions } from './printers/printer.ts'
 export type { RefMap } from './refs.ts'
-export type { AsyncVisitor, CollectVisitor, Visitor } from './visitor.ts'
+export type { AsyncVisitor, CollectOptions, CollectVisitor, ParentOf, TransformOptions, Visitor, VisitorContext, WalkOptions } from './visitor.ts'

package/src/utils.ts

@@ -0,0 +1,77 @@
+import { camelCase, isValidVarName } from '@internals/utils'
+
+import { narrowSchema } from './guards.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'] as const)
+
+/**
+ * Returns `true` when a schema is emitted as a plain TypeScript `string`.
+ *
+ * - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
+ * - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+ *
+ * @example
+ * ```ts
+ * isStringType(createSchema({ type: 'uuid' })) // true
+ * isStringType(createSchema({ type: 'date', representation: 'date' })) // false
+ * ```
+ */
+export function isStringType(node: SchemaNode): boolean {
+  if (plainStringTypes.has(node.type)) {
+    return true
+  }
+
+  const temporal = narrowSchema(node, 'date') ?? narrowSchema(node, 'time')
+  if (temporal) {
+    return temporal.representation !== 'date'
+  }
+
+  return false
+}
+
+/**
+ * Applies casing rules to parameter names and returns a new parameter array.
+ *
+ * The input array is not mutated.
+ * If `casing` is not set, the original array is returned unchanged.
+ *
+ * Use this before passing parameters to schema builders so that property keys
+ * in generated output match the desired casing while preserving
+ * `OperationNode.parameters` for other consumers.
+ *
+ * @example
+ * ```ts
+ * const params = [createParameter({ name: 'pet_id', in: 'query', schema: createSchema({ type: 'string' }) })]
+ * const cased = caseParams(params, 'camelcase')
+ * // cased[0].name === 'petId'
+ * ```
+ */
+export function caseParams(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 }
+  })
+}
+
+/**
+ * Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
+ *
+ * - `optional` is set for non-required, non-nullable schemas.
+ * - `nullish` is set for non-required, nullable schemas.
+ */
+export function syncOptionality(required: boolean, schema: SchemaNode): SchemaNode {
+  const nullable = schema.nullable ?? false
+
+  return {
+    ...schema,
+    optional: !required && !nullable ? true : undefined,
+    nullish: !required && nullable ? true : undefined,
+  }
+}