@kubb/adapter-oas 5.0.0-alpha.1 → 5.0.0-alpha.11

package/src/types.ts

@@ -2,6 +2,32 @@ import type { AdapterFactoryOptions } from '@kubb/core'
 import type { Oas as OasClass } from './oas/Oas.ts'
 import type { contentType } from './oas/types.ts'
 
+/**
+ * Controls how various OAS constructs are mapped to Kubb AST nodes.
+ */
+export type ParserOptions = {
+  /**
+   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   */
+  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
+  /**
+   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   */
+  integerType?: 'number' | 'bigint'
+  /**
+   * AST type used when no schema type can be inferred.
+   */
+  unknownType: 'any' | 'unknown' | 'void'
+  /**
+   * AST type used for completely empty schemas (`{}`).
+   */
+  emptySchemaType: 'any' | 'unknown' | 'void'
+  /**
+   * Suffix appended to derived enum names when building property schema names.
+   */
+  enumSuffix: 'enum' | (string & {})
+}
+
 export type OasAdapterOptions = {
   /**
    * Validate the OpenAPI spec before parsing.
@@ -41,8 +67,13 @@ export type OasAdapterOptions = {
    */
   discriminator?: 'strict' | 'inherit'
   /**
-   * Automatically resolve name collisions across schema components.
-   * @default false
+   * Enable collision detection for inline enum and schema type names.
+   * When `true` (default), full-path names are used and name collisions
+   * across schema components are automatically resolved (e.g. `OrderParamsStatusEnum`).
+   * When `false`, enum names use only the immediate property context
+   * (e.g. `ParamsStatusEnum`) matching the v4 naming conventions, with numeric
+   * suffixes for deduplication (e.g. `ParamsStatusEnum2`).
+   * @default true
    */
   collisionDetection?: boolean
   /**
@@ -52,23 +83,7 @@ export type OasAdapterOptions = {
    * - `false` falls through to a plain `string` node.
    * @default 'string'
    */
-  dateType?: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
-  /**
-   * Whether `type: 'integer'` / `format: 'int64'` produces `number` or `bigint` nodes.
-   * @default 'number'
-   */
-  integerType?: 'number' | 'bigint'
-  /**
-   * AST type used when no schema type can be inferred.
-   * @default 'any'
-   */
-  unknownType?: 'any' | 'unknown' | 'void'
-  /**
-   * AST type used for completely empty schemas (`{}`).
-   * @default `unknownType`
-   */
-  emptySchemaType?: 'any' | 'unknown' | 'void'
-}
+} & Partial<ParserOptions>
 
 export type OasAdapterResolvedOptions = {
   validate: boolean
@@ -82,6 +97,13 @@ export type OasAdapterResolvedOptions = {
   integerType: NonNullable<OasAdapterOptions['integerType']>
   unknownType: NonNullable<OasAdapterOptions['unknownType']>
   emptySchemaType: NonNullable<OasAdapterOptions['emptySchemaType']>
+  enumSuffix: OasAdapterOptions['enumSuffix']
+  /**
+   * Map from original `$ref` paths to their collision-resolved schema names.
+   * Populated by the adapter after each `parse()` call.
+   * e.g. `'#/components/schemas/Order'` → `'OrderSchema'`
+   */
+  nameMapping: Map<string, string>
 }
 
 export type OasAdapter = AdapterFactoryOptions<'oas', OasAdapterOptions, OasAdapterResolvedOptions>

package/src/utils.ts

@@ -0,0 +1,168 @@
+import { collect, createProperty, createSchema, narrowSchema } from '@kubb/ast'
+import type { SchemaNode } from '@kubb/ast/types'
+import type { KubbFile } from '@kubb/fabric-core/types'
+import { SCALAR_PRIMITIVE_TYPES } from './constants.ts'
+
+/**
+ * Extracts the schema name from a `$ref` string.
+ * For `#/components/schemas/Order` this returns `'Order'`.
+ * Falls back to the full ref string when no slash is present.
+ */
+export function extractRefName($ref: string): string {
+  return $ref.split('/').at(-1) ?? $ref
+}
+
+/**
+ * Replaces the discriminator property's schema inside an `ObjectSchemaNode`
+ * with an enum of the given `values`.
+ *
+ * - When `enumName` is provided the enum is named, which lets printers emit a
+ *   standalone enum declaration + type reference (e.g. `PetTypeEnum`).
+ * - When `enumName` is omitted the enum stays anonymous, so printers inline it
+ *   as a literal union (e.g. `'dog'`).
+ *
+ * Returns the node unchanged when it is not an object or lacks the target property.
+ */
+export function applyDiscriminatorEnum({
+  node,
+  propertyName,
+  values,
+  enumName,
+}: {
+  node: SchemaNode
+  propertyName: string
+  values: Array<string>
+  enumName?: string
+}): SchemaNode {
+  if (node.type !== 'object' || !node.properties?.length) return node
+
+  const hasProperty = node.properties.some((prop) => prop.name === propertyName)
+  if (!hasProperty) return node
+
+  return createSchema({
+    ...node,
+    properties: node.properties.map((prop) => {
+      if (prop.name !== propertyName) return prop
+
+      const enumSchema: SchemaNode = createSchema({
+        type: 'enum' as const,
+        primitive: 'string' as const,
+        enumValues: values,
+        name: enumName,
+        readOnly: prop.schema.readOnly,
+        writeOnly: prop.schema.writeOnly,
+      })
+
+      return createProperty({
+        ...prop,
+        schema: enumSchema,
+      })
+    }),
+  })
+}
+
+/**
+ * Merges consecutive anonymous (`name`-less) `ObjectSchemaNode`s in `members` into a
+ * single object by combining their `properties` arrays.
+ *
+ * Only adjacent pairs are merged — non-object or named nodes act as boundaries.
+ * This collapses patterns like `Address & { streetNumber } & { streetName }` into
+ * `Address & { streetNumber; streetName }`.
+ */
+export function mergeAdjacentAnonymousObjects(members: Array<SchemaNode>): Array<SchemaNode> {
+  return members.reduce<Array<SchemaNode>>((acc, member) => {
+    const obj = narrowSchema(member, 'object')
+    if (obj && !obj.name) {
+      const prev = acc[acc.length - 1]
+      const prevObj = prev ? narrowSchema(prev, 'object') : null
+      if (prevObj && !prevObj.name) {
+        acc[acc.length - 1] = createSchema({
+          ...prevObj,
+          properties: [...(prevObj.properties ?? []), ...(obj.properties ?? [])],
+        }) as SchemaNode
+        return acc
+      }
+    }
+    acc.push(member)
+    return acc
+  }, [])
+}
+
+/**
+ * Simplifies a union member list by removing `enum` nodes whose `primitive` type is
+ * already represented by a broader scalar node in the same union.
+ *
+ * For example `['placed', 'approved'] | string` collapses to `string` because
+ * `string` subsumes all string literals.  `'' | string` similarly becomes `string`.
+ *
+ * Only scalar primitives (`string`, `number`, `integer`, `bigint`, `boolean`) are
+ * considered — object, array, and ref members are left untouched.
+ *
+ * Const-derived enums (those without an `enumType`, produced from an OpenAPI `const`
+ * keyword) are **never** removed — `'accepted' | string` must stay as-is because the
+ * literal is intentional.
+ */
+export function simplifyUnionMembers(members: Array<SchemaNode>): Array<SchemaNode> {
+  const scalarPrimitives = new Set(members.filter((m) => SCALAR_PRIMITIVE_TYPES.has(m.type as 'string')).map((m) => m.type as string))
+  if (!scalarPrimitives.size) return members
+
+  return members.filter((m) => {
+    if (m.type !== 'enum') return true
+    const prim = m.primitive
+    // Keep the enum if its primitive isn't fully subsumed.
+    if (!prim) return true
+    // Const-derived enums have no `enumType`; keep them as intentional literals.
+    if (!m.enumType) return true
+    // `number` subsumes `integer` literals and vice-versa for our purposes.
+    if (scalarPrimitives.has(prim)) return false
+    if ((prim === 'integer' || prim === 'number') && (scalarPrimitives.has('integer') || scalarPrimitives.has('number'))) return false
+    return true
+  })
+}
+
+/**
+ * `nameMapping`, and calls `resolve` to obtain the `{ name, path }` pair for
+ * each import. When `oas` is supplied, only `$ref`s that are resolvable in the
+ * spec are included; omit it to skip the existence check.
+ *
+ * This function is the pure, state-free alternative to `OasParser.getImports`.
+ * Because it receives `nameMapping` explicitly it can be called without holding
+ * a reference to the parser or the OAS instance.
+ *
+ * @example
+ * ```ts
+ * // Use adapter state directly — no parser reference needed
+ * const imports = getImports({
+ *   node: schemaNode,
+ *   nameMapping: adapter.options.nameMapping,
+ *   resolve: (schemaName) => ({
+ *     name: schemaManager.getName(schemaName, { type: 'type' }),
+ *     path: schemaManager.getFile(schemaName).path,
+ *   }),
+ * })
+ * ```
+ */
+export function getImports({
+  node,
+  nameMapping,
+  resolve,
+}: {
+  node: SchemaNode
+  nameMapping: Map<string, string>
+  resolve: (schemaName: string) => { name: string; path: string } | undefined
+}): Array<KubbFile.Import> {
+  return collect<KubbFile.Import>(node, {
+    schema(schemaNode): KubbFile.Import | undefined {
+      if (schemaNode.type !== 'ref' || !schemaNode.ref) return
+
+      const rawName = extractRefName(schemaNode.ref)
+
+      // Apply collision-resolved name if available.
+      const schemaName = nameMapping.get(rawName) ?? rawName
+      const result = resolve(schemaName)
+      if (!result) return
+
+      return { name: [result.name], path: result.path }
+    },
+  })
+}