@kubb/plugin-faker 5.0.0-beta.3 → 5.0.0-beta.31

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "@kubb/plugin-faker",
-  "version": "5.0.0-beta.3",
-  "description": "Faker.js data generator plugin for Kubb, creating realistic mock data from OpenAPI specifications for development and testing.",
+  "version": "5.0.0-beta.31",
+  "description": "Generate Faker.js mock data factories from your OpenAPI schemas. Produces realistic seed data, test fixtures, and datasets for development and testing.",
   "keywords": [
-    "code-generator",
+    "code-generation",
     "codegen",
-    "data-generation",
-    "development",
     "faker",
     "faker.js",
     "fakerjs",
@@ -14,11 +12,8 @@
     "kubb",
     "mock-data",
     "mocks",
-    "oas",
     "openapi",
-    "plugins",
     "swagger",
-    "testing",
     "typescript"
   ],
   "license": "MIT",
@@ -31,7 +26,7 @@
   "files": [
     "src",
     "dist",
-    "plugin.json",
+    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -71,15 +66,16 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.3",
-    "@kubb/renderer-jsx": "5.0.0-beta.3",
-    "@kubb/plugin-ts": "5.0.0-beta.3"
+    "@kubb/core": "5.0.0-beta.31",
+    "@kubb/renderer-jsx": "5.0.0-beta.31",
+    "@kubb/plugin-ts": "5.0.0-beta.31"
   },
   "devDependencies": {
+    "@internals/shared": "0.0.0",
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.3"
+    "@kubb/renderer-jsx": "5.0.0-beta.31"
   },
   "size-limit": [
     {

package/src/components/Faker.tsx

@@ -44,71 +44,17 @@ export function Faker({ node, description, name, typeName, printer, seed, canOve
   const isTuple = node.type === 'tuple'
   const isScalar = SCALAR_TYPES.has(node.type)
 
-  let fakerTextWithOverride = fakerText
-  let useGenericOverride = false
-
-  if (canOverride && isObject) {
-    useGenericOverride = true
-  }
-
-  if (canOverride && isTuple) {
-    fakerTextWithOverride = `data || ${fakerText}`
-  }
-
-  if (canOverride && isArray) {
-    fakerTextWithOverride = `[
-  ...${fakerText},
-  ...(data || [])
-]`
-  }
-
-  if (canOverride && isScalar) {
-    fakerTextWithOverride = `data ?? ${fakerText}`
-  }
+  const useGenericOverride = canOverride && isObject
+  const fakerTextWithOverride = (() => {
+    if (canOverride && isTuple) return `data || ${fakerText}`
+    if (canOverride && isArray) return `[\n  ...${fakerText},\n  ...(data || [])\n]`
+    if (canOverride && isScalar) return `data ?? ${fakerText}`
+    return fakerText
+  })()
 
   const { dataType, returnType: resolvedReturnType } = resolveFakerTypeUsage(node, typeName, canOverride)
 
-  let functionSignature = ''
-  let functionBody = ''
-
-  if (useGenericOverride) {
-    // Generate function with defaultFakeData structure
-    const jsdoc = description ? `/**\n   * @description ${jsStringEscape(description)}\n   */\n  ` : ''
-    functionSignature = `${jsdoc}export function ${name}(data?: Partial<${typeName}>): Required<${typeName}>`
-
-    const seedCode = seed ? `faker.seed(${JSON.stringify(seed)})\n  ` : ''
-
-    // When the object node has properties that transitively reference a cyclic schema,
-    // the printer emits memoizing getters for those properties. Spreading the object
-    // literal would immediately invoke those getters, triggering recursive faker calls
-    // and causing a stack overflow. Detect this upfront via ast helpers so we can
-    // use Object.defineProperty-based merging instead of spread.
-    const { cyclicSchemas, schemaName } = printer.options
-    const hasGetters =
-      node.type === 'object' &&
-      !!cyclicSchemas &&
-      (node.properties ?? []).some((p) => ast.containsCircularRef(p.schema, { circularSchemas: cyclicSchemas, excludeName: schemaName }))
-
-    if (hasGetters) {
-      functionBody = `{
-  ${seedCode}const defaultFakeData = ${fakerText}
-  if (data) {
-    for (const [key, value] of Object.entries(data)) {
-      Object.defineProperty(defaultFakeData, key, { value, configurable: true, writable: true, enumerable: true })
-    }
-  }
-  return defaultFakeData as Required<${typeName}>
-}`
-    } else {
-      functionBody = `{
-  ${seedCode}const defaultFakeData = ${fakerText}
-  return {
-    ...defaultFakeData,
-    ...(data || {}),
-  } as Required<${typeName}>
-}`
-    }
-  } else {
+  if (!useGenericOverride) {
     const usesData = /\bdata\b/.test(fakerTextWithOverride)
     const dataParamName = usesData ? 'data' : '_data'
     const params = ast.createFunctionParameters({
@@ -123,6 +69,11 @@ export function Faker({ node, description, name, typeName, printer, seed, canOve
     const paramsSignature = declarationPrinter.print(params) ?? ''
     const returnType = resolvedReturnType
 
+    // A `ref` wrapper delegates to another faker. Object fakers are now generic and
+    // widen to `Partial<T>` when called with a `Partial<T>`-typed argument, so cast
+    // back to the wrapper's declared return type to keep it assignable.
+    const returnExpression = node.type === 'ref' && canOverride && returnType ? `${fakerTextWithOverride} as ${returnType}` : fakerTextWithOverride
+
     return (
       <File.Source name={name} isExportable isIndexable>
         <Function
@@ -130,7 +81,7 @@ export function Faker({ node, description, name, typeName, printer, seed, canOve
           name={name}
           JSDoc={{ comments: description ? [`@description ${jsStringEscape(description)}`] : [] }}
           params={canOverride ? paramsSignature : undefined}
-          returnType={returnType}
+          returnType={returnType ?? undefined}
         >
           {seed ? (
             <>
@@ -138,12 +89,47 @@ export function Faker({ node, description, name, typeName, printer, seed, canOve
               <br />
             </>
           ) : undefined}
-          {`return ${fakerTextWithOverride}`}
+          {`return ${returnExpression}`}
         </Function>
       </File.Source>
     )
   }
 
+  // Generate function with defaultFakeData structure
+  const jsdoc = description ? `/**\n   * @description ${jsStringEscape(description)}\n   */\n  ` : ''
+  const functionSignature = `${jsdoc}export function ${name}<TData extends Partial<${typeName}> = object>(data?: TData)`
+
+  const seedCode = seed ? `faker.seed(${JSON.stringify(seed)})\n  ` : ''
+
+  // When the object node has properties that transitively reference a cyclic schema,
+  // the printer emits memoizing getters for those properties. Spreading the object
+  // literal would immediately invoke those getters, triggering recursive faker calls
+  // and causing a stack overflow. Detect this upfront via ast helpers so we can
+  // use Object.defineProperty-based merging instead of spread.
+  const { cyclicSchemas, schemaName } = printer.options
+  const hasGetters =
+    node.type === 'object' &&
+    !!cyclicSchemas &&
+    (node.properties ?? []).some((p) => ast.containsCircularRef(p.schema, { circularSchemas: cyclicSchemas, excludeName: schemaName }))
+
+  const functionBody = hasGetters
+    ? `{
+  ${seedCode}const defaultFakeData = ${fakerText}
+  if (data) {
+    for (const [key, value] of Object.entries(data)) {
+      Object.defineProperty(defaultFakeData, key, { value, configurable: true, writable: true, enumerable: true })
+    }
+  }
+  return defaultFakeData as Omit<typeof defaultFakeData, keyof TData> & TData
+}`
+    : `{
+  ${seedCode}const defaultFakeData = ${fakerText}
+  return {
+    ...defaultFakeData,
+    ...(data || {}),
+  } as Omit<typeof defaultFakeData, keyof TData> & TData
+}`
+
   return (
     <File.Source name={name} isExportable isIndexable>
       {functionSignature}

package/src/generators/fakerGenerator.tsx

@@ -1,49 +1,53 @@
+import { getPerContentTypeName, resolveContentTypeVariants } from '@internals/shared'
+import { aliasConflictingImports, filterUsedImports, rewriteAliasedImports } from '@internals/utils'
 import { ast, defineGenerator } from '@kubb/core'
 import { pluginTsName } from '@kubb/plugin-ts'
-import { File, jsxRenderer } from '@kubb/renderer-jsx'
+import { File, jsxRendererSync } from '@kubb/renderer-jsx'
 import { Faker } from '../components/Faker.tsx'
 import { printerFaker } from '../printers/printerFaker.ts'
 import type { PluginFaker } from '../types.ts'
-import {
-  aliasConflictingImports,
-  buildResponseUnionSchema,
-  canOverrideSchema,
-  filterUsedImports,
-  localeToFakerImport,
-  resolveParamNameByLocation,
-  resolveSchemaRef,
-  resolveTypeReference,
-  rewriteAliasedImports,
-} from '../utils.ts'
+import { buildResponseUnionSchema, canOverrideSchema, localeToFakerImport, resolveParamNameByLocation, resolveTypeReference } from '../utils.ts'
 
+/**
+ * Built-in generator for `@kubb/plugin-faker`. Emits one `createX` factory
+ * per schema in the spec plus per-operation request/response factories. Each
+ * factory returns a value matching the corresponding TypeScript type from
+ * `@kubb/plugin-ts`.
+ */
 export const fakerGenerator = defineGenerator<PluginFaker>({
   name: 'faker',
-  renderer: jsxRenderer,
+  renderer: jsxRendererSync,
   schema(node, ctx) {
     const { adapter, config, resolver, root } = ctx
     const { output, group, dateParser, regexGenerator, mapper, seed, locale, printer } = ctx.options
     const pluginTs = ctx.driver.getPlugin(pluginTsName)
 
-    if (!node.name || !pluginTs || !adapter.inputNode) {
+    if (!node.name || !pluginTs) {
       return
     }
 
     const tsResolver = ctx.driver.getResolver(pluginTsName)
 
-    const schemaNode = resolveSchemaRef(node, adapter.inputNode.schemas)
-    const schemaName = schemaNode.name ?? node.name
+    const schemaName = node.name
     const mode = ctx.getMode(output)
+    const isEnumSchema = !!ast.narrowSchema(node, ast.schemaTypes.enum)
+    const tsEnumType = pluginTs.options?.enumType
+    const tsEnumTypeSuffix = pluginTs.options?.enumTypeSuffix ?? 'Key'
+    const schemaTypeName =
+      isEnumSchema && (tsEnumType === 'asConst' || tsEnumType === 'asPascalConst')
+        ? tsResolver.resolveEnumKeyName({ name: schemaName }, tsEnumTypeSuffix)
+        : tsResolver.resolveTypeName(schemaName)
     const meta = {
       name: resolver.resolveName(schemaName),
-      file: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }),
-      typeName: tsResolver.resolveTypeName(schemaName),
+      file: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group: group ?? undefined }),
+      typeName: schemaTypeName,
       typeFile: tsResolver.resolveFile(
         { name: schemaName, extname: '.ts' },
-        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group },
+        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group ?? undefined },
       ),
     } as const
-    const canOverride = canOverrideSchema(schemaNode)
-    const cyclicSchemas = adapter.inputNode ? ast.findCircularSchemas(adapter.inputNode.schemas) : undefined
+    const canOverride = canOverrideSchema(node)
+    const cyclicSchemas = new Set<string>(ctx.meta.circularNames)
     const printerInstance = printerFaker({
       resolver,
       schemaName,
@@ -54,9 +58,9 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
       nodes: printer?.nodes,
       cyclicSchemas,
     })
-    const fakerText = printerInstance.print(schemaNode) ?? 'undefined'
+    const fakerText = printerInstance.print(node) ?? 'undefined'
     const typeReference = resolveTypeReference({
-      node: schemaNode,
+      node,
       canOverride,
       name: meta.name,
       typeName: meta.typeName,
@@ -65,9 +69,9 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
     })
 
     const imports = adapter
-      .getImports(schemaNode, (schemaName) => ({
+      .getImports(node, (schemaName) => ({
         name: resolver.resolveName(schemaName),
-        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group: group ?? undefined }).path,
       }))
       .filter((entry) => entry.path !== meta.file.path)
     const usedImports = filterUsedImports(imports, fakerText)
@@ -77,8 +81,8 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
         baseName={meta.file.baseName}
         path={meta.file.path}
         meta={meta.file.meta}
-        banner={resolver.resolveBanner(adapter.inputNode, { output, config })}
-        footer={resolver.resolveFooter(adapter.inputNode, { output, config })}
+        banner={resolver.resolveBanner(ctx.meta, { output, config, file: { path: meta.file.path, baseName: meta.file.baseName } })}
+        footer={resolver.resolveFooter(ctx.meta, { output, config, file: { path: meta.file.path, baseName: meta.file.baseName } })}
       >
         <File.Import name={locale ? [{ propertyName: localeToFakerImport(locale), name: 'faker' }] : ['faker']} path="@faker-js/faker" />
         {regexGenerator === 'randexp' && <File.Import name={'RandExp'} path={'randexp'} />}
@@ -89,8 +93,8 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
         <Faker
           name={meta.name}
           typeName={typeReference.typeName}
-          description={schemaNode.description}
-          node={schemaNode}
+          description={node.description}
+          node={node}
           printer={printerInstance}
           seed={seed}
           canOverride={canOverride}
@@ -115,31 +119,66 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
       name: resolveParamNameByLocation(resolver, node, param),
       typeName: resolveParamNameByLocation(tsResolver, node, param),
     }))
-    const responseEntries = node.responses.map((response) => ({
-      response,
-      name: resolver.resolveResponseStatusName(node, response.statusCode),
-      typeName: tsResolver.resolveResponseStatusName(node, response.statusCode),
-    }))
-    const dataEntry = node.requestBody?.content?.[0]?.schema
-      ? {
-          schema: {
-            ...node.requestBody.content![0]!.schema!,
-            description: node.requestBody.description ?? node.requestBody.content![0]!.schema!.description,
-          },
-          name: resolver.resolveDataName(node),
-          typeName: tsResolver.resolveDataName(node),
-          description: node.requestBody.description ?? node.requestBody.content![0]!.schema!.description,
-        }
-      : null
+    type RenderUnit = { schema: ast.SchemaNode | null; name: string; typeName: string; description?: string; skipImportNames: Array<string> }
+
+    // Expands a content array into render units: one faker per content type plus a union faker
+    // (named `baseName`) when more than one content type carries a schema, else a single faker.
+    function expandContentUnits(
+      entries: Array<{ contentType: string; schema?: ast.SchemaNode | null }>,
+      baseName: string,
+      tsBaseName: string,
+      description: string | undefined,
+      decorate?: (schema: ast.SchemaNode) => ast.SchemaNode,
+    ): Array<RenderUnit> {
+      const withSchema = entries.filter((entry) => entry.schema)
+      if (withSchema.length <= 1) {
+        const primary = withSchema[0] ?? entries[0]
+        if (!primary?.schema) return []
+        return [{ schema: decorate ? decorate(primary.schema) : primary.schema, name: baseName, typeName: tsBaseName, description, skipImportNames: [] }]
+      }
+      const variants = resolveContentTypeVariants(entries, baseName)
+      const unionSchema = ast.createSchema({ type: 'union', members: variants.map((variant) => ast.createSchema({ type: 'ref', name: variant.name })) })
+      return [
+        ...variants.map((variant) => ({
+          schema: decorate ? decorate(variant.schema) : variant.schema,
+          name: variant.name,
+          typeName: getPerContentTypeName(tsBaseName, variant.suffix),
+          description,
+          skipImportNames: [],
+        })),
+        { schema: unionSchema, name: baseName, typeName: tsBaseName, description, skipImportNames: variants.map((variant) => variant.name) },
+      ]
+    }
+
+    const responseUnits = node.responses.flatMap((response) =>
+      expandContentUnits(
+        response.content ?? [],
+        resolver.resolveResponseStatusName(node, response.statusCode),
+        tsResolver.resolveResponseStatusName(node, response.statusCode),
+        response.description,
+      ),
+    )
+    const dataUnits = expandContentUnits(
+      node.requestBody?.content ?? [],
+      resolver.resolveDataName(node),
+      tsResolver.resolveDataName(node),
+      node.requestBody?.description,
+      (schema) => ({ ...schema, description: node.requestBody?.description ?? schema.description }),
+    )
     const responseName = resolver.resolveResponseName(node)
     const localHelperNames = new Set([
       ...paramEntries.map((entry) => entry.name),
-      ...responseEntries.map((entry) => entry.name),
-      ...(dataEntry ? [dataEntry.name] : []),
+      ...responseUnits.map((unit) => unit.name),
+      ...dataUnits.map((unit) => unit.name),
       responseName,
     ])
+    const cyclicSchemas = new Set<string>(ctx.meta.circularNames)
+
     const meta = {
-      file: resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
       typeFile: tsResolver.resolveFile(
         {
           name: node.operationId,
@@ -150,7 +189,7 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
         {
           root,
           output: pluginTs.options?.output ?? output,
-          group: pluginTs.options?.group,
+          group: pluginTs.options?.group ?? undefined,
         },
       ),
     } as const
@@ -159,7 +198,7 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
       return adapter
         .getImports(schema, (schemaName) => ({
           name: resolver.resolveName(schemaName),
-          path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+          path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group: group ?? undefined }).path,
         }))
         .filter((entry) => entry.path !== meta.file.path)
     }
@@ -182,7 +221,6 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
       }
 
       const canOverride = canOverrideSchema(schema)
-      const cyclicSchemas = adapter.inputNode ? ast.findCircularSchemas(adapter.inputNode.schemas) : undefined
       const printerInstance = printerFaker({
         resolver,
         schemaName: name,
@@ -230,8 +268,8 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
         baseName={meta.file.baseName}
         path={meta.file.path}
         meta={meta.file.meta}
-        banner={resolver.resolveBanner(adapter.inputNode, { output, config })}
-        footer={resolver.resolveFooter(adapter.inputNode, { output, config })}
+        banner={resolver.resolveBanner(ctx.meta, { output, config, file: { path: meta.file.path, baseName: meta.file.baseName } })}
+        footer={resolver.resolveFooter(ctx.meta, { output, config, file: { path: meta.file.path, baseName: meta.file.baseName } })}
       >
         <File.Import name={locale ? [{ propertyName: localeToFakerImport(locale), name: 'faker' }] : ['faker']} path="@faker-js/faker" />
         {regexGenerator === 'randexp' && <File.Import name={'RandExp'} path={'randexp'} />}
@@ -243,27 +281,29 @@ export const fakerGenerator = defineGenerator<PluginFaker>({
             typeName,
           }),
         )}
-        {responseEntries.map(({ response, name, typeName }) =>
+        {responseUnits.map((unit) =>
           renderEntry({
-            schema: response.schema,
-            name,
-            typeName,
-            description: response.description,
+            schema: unit.schema,
+            name: unit.name,
+            typeName: unit.typeName,
+            description: unit.description,
+            skipImportNames: unit.skipImportNames,
+          }),
+        )}
+        {dataUnits.map((unit) =>
+          renderEntry({
+            schema: unit.schema,
+            name: unit.name,
+            typeName: unit.typeName,
+            description: unit.description,
+            skipImportNames: unit.skipImportNames,
           }),
         )}
-        {dataEntry
-          ? renderEntry({
-              schema: dataEntry.schema,
-              name: dataEntry.name,
-              typeName: dataEntry.typeName,
-              description: dataEntry.description,
-            })
-          : null}
         {renderEntry({
           schema: buildResponseUnionSchema(node, resolver),
           name: responseName,
           typeName: tsResolver.resolveResponseName(node),
-          skipImportNames: responseEntries.map(({ name }) => name),
+          skipImportNames: responseUnits.map((unit) => unit.name),
         })}
       </File>
     )

package/src/plugin.ts

@@ -1,22 +1,39 @@
-import { camelCase } from '@internals/utils'
-import { definePlugin, type Group } from '@kubb/core'
+import { createGroupConfig } from '@internals/shared'
+import { definePlugin } from '@kubb/core'
 import { pluginTsName } from '@kubb/plugin-ts'
 import { fakerGenerator } from './generators/fakerGenerator.tsx'
 import { resolverFaker } from './resolvers/resolverFaker.ts'
 import type { PluginFaker } from './types.ts'
 
 /**
- * Canonical plugin name for `@kubb/plugin-faker`, used in driver lookups and warnings.
+ * Canonical plugin name for `@kubb/plugin-faker`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 export const pluginFakerName = 'plugin-faker' satisfies PluginFaker['name']
 
 /**
- * Generates Faker mock data factories from OpenAPI/AST specification.
- *
- * Creates randomized test data and mock helpers from schema definitions.
+ * Generates one mock-data factory per OpenAPI schema using Faker.js. Call
+ * `createPet()` to get a realistic `Pet` object. Useful for tests, Storybook,
+ * and local development without a running backend.
  *
  * @example
- * `import pluginFaker from '@kubb/plugin-faker'; export default defineConfig({ plugins: [pluginFaker({ output: { path: 'mocks' } })], })`
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginFaker } from '@kubb/plugin-faker'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginFaker({
+ *       output: { path: './mocks' },
+ *       seed: [100],
+ *     }),
+ *   ],
+ * })
+ * ```
  */
 export const pluginFaker = definePlugin<PluginFaker>((options) => {
   const {
@@ -37,20 +54,7 @@ export const pluginFaker = definePlugin<PluginFaker>((options) => {
     transformer: userTransformer,
   } = options
 
-  const groupConfig = group
-    ? ({
-        ...group,
-        name: group.name
-          ? group.name
-          : (ctx: { group: string }) => {
-              if (group.type === 'path') {
-                return `${ctx.group.split('/')[1]}`
-              }
-
-              return `${camelCase(ctx.group)}Controller`
-            },
-      } satisfies Group)
-    : undefined
+  const groupConfig = createGroupConfig(group, { suffix: 'Controller', honorName: true })
 
   return {
     name: pluginFakerName,