@kubb/plugin-faker 5.0.0-alpha.9 → 5.0.0-beta.3

package/dist/printerFaker-CJiwzoto.d.ts

@@ -0,0 +1,206 @@
+import { t as __name } from "./chunk--u3MIqq1.js";
+import { Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
+
+//#region src/types.d.ts
+/**
+ * Resolver for Faker that provides naming methods for mock functions.
+ */
+type ResolverFaker = Resolver & ast.OperationParamsResolver & {
+  /**
+   * Resolves the faker function name for a schema.
+   *
+   * @example Resolving faker function names
+   * `resolver.resolveName('show pet by id') // -> 'showPetById'`
+   */
+  resolveName(this: ResolverFaker, name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  /**
+   * Resolves the output file name for a faker module.
+   *
+   * @example Resolving faker file names
+   * `resolver.resolvePathName('show pet by id', 'file') // -> 'showPetById'`
+   */
+  resolvePathName(this: ResolverFaker, name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
+  /**
+   * Resolves the faker function name for a request body.
+   *
+   * @example Resolving data function names
+   * `resolver.resolveDataName(node) // -> 'createPetsData'`
+   */
+  resolveDataName(this: ResolverFaker, node: ast.OperationNode): string;
+  /**
+   * Resolves the faker function name for a response by status code.
+   *
+   * @example Response status names
+   * `resolver.resolveResponseStatusName(node, 200) // -> 'listPetsStatus200'`
+   */
+  resolveResponseStatusName(this: ResolverFaker, node: ast.OperationNode, statusCode: ast.StatusCode): string;
+  /**
+   * Resolves the faker function name for the response union.
+   *
+   * @example Response union names
+   * `resolver.resolveResponseName(node) // -> 'listPetsResponse'`
+   */
+  resolveResponseName(this: ResolverFaker, node: ast.OperationNode): string;
+  /**
+   * Resolves the faker function name for path parameters.
+   *
+   * @example Path parameters names
+   * `resolver.resolvePathParamsName(node, param) // -> 'showPetByIdPathPetId'`
+   */
+  resolvePathParamsName(this: ResolverFaker, node: ast.OperationNode, param: ast.ParameterNode): string;
+  /**
+   * Resolves the faker function name for query parameters.
+   *
+   * @example Query parameters names
+   * `resolver.resolveQueryParamsName(node, param) // -> 'listPetsQueryLimit'`
+   */
+  resolveQueryParamsName(this: ResolverFaker, node: ast.OperationNode, param: ast.ParameterNode): string;
+  /**
+   * Resolves the faker function name for header parameters.
+   *
+   * @example Header parameters names
+   * `resolver.resolveHeaderParamsName(node, param) // -> 'deletePetHeaderApiKey'`
+   */
+  resolveHeaderParamsName(this: ResolverFaker, node: ast.OperationNode, param: ast.ParameterNode): string;
+};
+type Options = {
+  /**
+   * Specify the export location for the files and define the behavior of the output.
+   * @default { path: 'mocks', barrelType: 'named' }
+   */
+  output?: Output;
+  /**
+   * Group the Faker mocks based on the provided name.
+   */
+  group?: Group;
+  /**
+   * Tags, operations, or paths to exclude from generation.
+   */
+  exclude?: Array<Exclude>;
+  /**
+   * Tags, operations, or paths to include in generation.
+   */
+  include?: Array<Include>;
+  /**
+   * Override options for specific tags, operations, or paths.
+   */
+  override?: Array<Override<ResolvedOptions>>;
+  /**
+   * Parser to use when formatting date/time values as strings.
+   *
+   * @default 'faker'
+   */
+  dateParser?: 'faker' | 'dayjs' | 'moment' | (string & {});
+  /**
+   * Generator to use for RegExp patterns.
+   *
+   * @default 'faker'
+   */
+  regexGenerator?: 'faker' | 'randexp';
+  /**
+   * Provide per-property faker expressions keyed by property name.
+   */
+  mapper?: Record<string, string>;
+  /**
+   * Locale for generating mock data.
+   * Imports the matching localized `@faker-js/faker` instance so names, addresses,
+   * and phone numbers reflect the target region.
+   *
+   * @default 'en'
+   *
+   * @example German
+   * `locale: 'de'`
+   *
+   * @example Austrian German
+   * `locale: 'de_AT'`
+   *
+   * @see https://fakerjs.dev/api/localization.html
+   */
+  locale?: string;
+  /**
+   * Seed faker for deterministic output.
+   */
+  seed?: number | number[];
+  /**
+   * Apply casing to parameter names to match your configuration.
+   */
+  paramsCasing?: 'camelcase';
+  /**
+   * Additional generators alongside the default generators.
+   */
+  generators?: Array<Generator<PluginFaker>>;
+  /**
+   * Override naming conventions for function names and types.
+   */
+  resolver?: Partial<ResolverFaker> & ThisType<ResolverFaker>;
+  /**
+   * AST visitor to transform generated nodes.
+   */
+  transformer?: ast.Visitor;
+  /**
+   * Override individual faker printer node handlers.
+   */
+  printer?: {
+    nodes?: PrinterFakerNodes;
+  };
+};
+type ResolvedOptions = {
+  output: Output;
+  group: Group | undefined;
+  exclude: NonNullable<Options['exclude']>;
+  include: Options['include'];
+  override: NonNullable<Options['override']>;
+  dateParser: NonNullable<Options['dateParser']>;
+  regexGenerator: NonNullable<Options['regexGenerator']>;
+  mapper: NonNullable<Options['mapper']>;
+  seed: NonNullable<Options['seed']> | undefined;
+  locale: Options['locale'];
+  paramsCasing: Options['paramsCasing'];
+  printer: Options['printer'];
+};
+type PluginFaker = PluginFactoryOptions<'plugin-faker', Options, ResolvedOptions, ResolverFaker>;
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-faker': PluginFaker;
+    }
+  }
+}
+//#endregion
+//#region src/printers/printerFaker.d.ts
+/**
+ * Partial printer nodes for Faker generation, mapping schema types to output strings.
+ */
+type PrinterFakerNodes = ast.PrinterPartial<string, PrinterFakerOptions>;
+/**
+ * Configuration options for the Faker printer, including resolvers, mappers, and cyclic schema tracking.
+ */
+type PrinterFakerOptions = {
+  dateParser?: PluginFaker['resolvedOptions']['dateParser'];
+  regexGenerator?: PluginFaker['resolvedOptions']['regexGenerator'];
+  mapper?: PluginFaker['resolvedOptions']['mapper'];
+  resolver: ResolverFaker;
+  typeName?: string;
+  schemaName?: string;
+  nestedInObject?: boolean;
+  nodes?: PrinterFakerNodes;
+  /**
+   * Names of schemas that participate in a circular dependency chain.
+   * Properties whose schema transitively references one of these are emitted
+   * as lazy getters so that user overrides via the `data` parameter prevent
+   * the recursive faker call from ever executing (avoiding stack overflow).
+   */
+  cyclicSchemas?: ReadonlySet<string>;
+};
+/**
+ * Factory options for the Faker printer, defining input/output types and configuration.
+ */
+type PrinterFakerFactory = ast.PrinterFactoryOptions<'faker', PrinterFakerOptions, string, string>;
+/**
+ * Creates a Faker printer that generates mock data generation code from schema nodes.
+ * Handles circular references gracefully by emitting memoizing getters for cyclic properties.
+ */
+declare const printerFaker: (options: PrinterFakerOptions) => ast.Printer<PrinterFakerFactory>;
+//#endregion
+export { Options as a, printerFaker as i, PrinterFakerNodes as n, PluginFaker as o, PrinterFakerOptions as r, ResolverFaker as s, PrinterFakerFactory as t };
+//# sourceMappingURL=printerFaker-CJiwzoto.d.ts.map

package/package.json

@@ -1,35 +1,56 @@
 {
   "name": "@kubb/plugin-faker",
-  "version": "5.0.0-alpha.9",
+  "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.",
   "keywords": [
+    "code-generator",
+    "codegen",
+    "data-generation",
+    "development",
     "faker",
     "faker.js",
     "fakerjs",
+    "fixtures",
+    "kubb",
     "mock-data",
     "mocks",
-    "data-generation",
-    "fixtures",
-    "testing",
-    "development",
-    "typescript",
-    "openapi",
-    "swagger",
     "oas",
-    "code-generator",
-    "codegen",
+    "openapi",
     "plugins",
-    "kubb"
+    "swagger",
+    "testing",
+    "typescript"
   ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kubb-labs/kubb.git",
+    "url": "git+https://github.com/kubb-labs/plugins.git",
     "directory": "packages/plugin-faker"
   },
-  "license": "MIT",
-  "author": "stijnvanhulle",
-  "sideEffects": false,
+  "files": [
+    "src",
+    "dist",
+    "plugin.json",
+    "!/**/**.test.**",
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
+  ],
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "components": [
+        "./dist/components.d.ts"
+      ],
+      "generators": [
+        "./dist/generators.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -45,24 +66,21 @@
     },
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "components": [
-        "./dist/components.d.ts"
-      ],
-      "generators": [
-        "./dist/generators.d.ts"
-      ]
-    }
+  "publishConfig": {
+    "access": "public",
+    "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"
+  },
+  "devDependencies": {
+    "@internals/utils": "0.0.0"
+  },
+  "peerDependencies": {
+    "@kubb/renderer-jsx": "5.0.0-beta.3"
   },
-  "files": [
-    "src",
-    "dist",
-    "!/**/**.test.**",
-    "!/**/__tests__/**",
-    "!/**/__snapshots__/**"
-  ],
   "size-limit": [
     {
       "path": "./dist/*.js",
@@ -70,30 +88,14 @@
       "gzip": true
     }
   ],
-  "dependencies": {
-    "@kubb/react-fabric": "0.14.0",
-    "@kubb/oas": "5.0.0-alpha.9",
-    "@kubb/core": "5.0.0-alpha.9",
-    "@kubb/plugin-oas": "5.0.0-alpha.9",
-    "@kubb/plugin-ts": "5.0.0-alpha.9"
-  },
   "engines": {
     "node": ">=22"
   },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "devDependencies": {
-    "@internals/utils": "0.0.0"
-  },
   "scripts": {
     "build": "tsdown && size-limit",
     "clean": "npx rimraf ./dist",
-    "lint": "bun biome lint .",
-    "lint:fix": "bun biome lint --fix --unsafe .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
     "start": "tsdown --watch",

package/src/components/Faker.tsx

@@ -1,107 +1,153 @@
 import { jsStringEscape } from '@internals/utils'
-import type { Schema } from '@kubb/plugin-oas'
-import { isKeyword, schemaKeywords } from '@kubb/plugin-oas'
-import { File, Function, FunctionParams } from '@kubb/react-fabric'
-import type { FabricReactNode } from '@kubb/react-fabric/types'
-import * as parserFaker from '../parser.ts'
+import { ast } from '@kubb/core'
+import { functionPrinter } from '@kubb/plugin-ts'
+import { File, Function } from '@kubb/renderer-jsx'
+import type { KubbReactNode } from '@kubb/renderer-jsx/types'
+import type { PrinterFakerFactory } from '../printers/printerFaker.ts'
 import type { PluginFaker } from '../types.ts'
+import { resolveFakerTypeUsage } from '../utils.ts'
 
 type Props = {
   name: string
   typeName: string
-  tree: Array<Schema>
+  node: ast.SchemaNode
+  printer: ast.Printer<PrinterFakerFactory>
   seed?: PluginFaker['options']['seed']
   description?: string
-  regexGenerator?: PluginFaker['options']['regexGenerator']
-  mapper?: PluginFaker['options']['mapper']
-  dateParser?: PluginFaker['options']['dateParser']
   canOverride: boolean
 }
 
-export function Faker({ tree, description, name, typeName, seed, regexGenerator, canOverride, mapper, dateParser }: Props): FabricReactNode {
-  const fakerText = parserFaker.joinItems(
-    tree
-      .map((schema, _index, siblings) =>
-        parserFaker.parse(
-          { name, schema, parent: undefined, current: schema, siblings },
-          {
-            typeName,
-            rootTypeName: name,
-            regexGenerator,
-            mapper,
-            canOverride,
-            dateParser,
-          },
-        ),
-      )
-      .filter((x): x is string => Boolean(x)),
-  )
-
-  const isArray = fakerText.startsWith('faker.helpers.arrayElements') || fakerText.startsWith('faker.helpers.multiple')
-  const isRefToArray = tree.some((s) => isKeyword(s, schemaKeywords.schema) && s.args.type === 'array')
-  const isObject = fakerText.startsWith('{')
-  const isTuple = fakerText.startsWith('faker.helpers.arrayElement')
-
-  const isSimpleString = name === 'string'
-  const isSimpleInt = name === 'integer'
-  const isSimpleFloat = name === 'float'
+const OBJECT_TYPES = new Set<ast.SchemaNode['type']>(['object', 'intersection'])
+const ARRAY_TYPES = new Set<ast.SchemaNode['type']>(['array'])
+const SCALAR_TYPES = new Set<ast.SchemaNode['type']>([
+  'string',
+  'email',
+  'url',
+  'uuid',
+  'number',
+  'integer',
+  'bigint',
+  'boolean',
+  'date',
+  'time',
+  'datetime',
+  'blob',
+  'enum',
+])
+const declarationPrinter = functionPrinter({ mode: 'declaration' })
+
+export function Faker({ node, description, name, typeName, printer, seed, canOverride }: Props): KubbReactNode {
+  const fakerText = printer.print(node) ?? 'undefined'
+
+  const isArray = ARRAY_TYPES.has(node.type)
+  const isObject = OBJECT_TYPES.has(node.type)
+  const isTuple = node.type === 'tuple'
+  const isScalar = SCALAR_TYPES.has(node.type)
 
   let fakerTextWithOverride = fakerText
+  let useGenericOverride = false
 
   if (canOverride && isObject) {
-    fakerTextWithOverride = `{
-  ...${fakerText},
-  ...data || {}
-}`
+    useGenericOverride = true
   }
 
-  if (canOverride && isTuple) fakerTextWithOverride = `data || ${fakerText}`
+  if (canOverride && isTuple) {
+    fakerTextWithOverride = `data || ${fakerText}`
+  }
 
   if (canOverride && isArray) {
     fakerTextWithOverride = `[
-      ...${fakerText},
-      ...data || []
-    ]`
+  ...${fakerText},
+  ...(data || [])
+]`
   }
 
-  if (canOverride && isSimpleString) fakerTextWithOverride = 'data ?? faker.string.alpha()'
-
-  if (canOverride && isSimpleInt) fakerTextWithOverride = 'data ?? faker.number.int()'
-
-  if (canOverride && isSimpleFloat) fakerTextWithOverride = 'data ?? faker.number.float()'
-
-  let type = `Partial<${typeName}>`
-
-  if (isArray) type = typeName
-  if (isRefToArray) type = typeName
-  if (isSimpleString) type = name
-  if (isSimpleInt || isSimpleFloat) type = 'number'
-
-  const params = FunctionParams.factory({
-    data: {
-      // making a partial out of an array does not make sense
-      type,
-      optional: true,
-    },
-  })
-
-  let returnType = canOverride ? typeName : undefined
+  if (canOverride && isScalar) {
+    fakerTextWithOverride = `data ?? ${fakerText}`
+  }
 
-  if (isSimpleString || isSimpleInt || isSimpleFloat) returnType = type
+  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 {
+    const usesData = /\bdata\b/.test(fakerTextWithOverride)
+    const dataParamName = usesData ? 'data' : '_data'
+    const params = ast.createFunctionParameters({
+      params: [
+        ast.createFunctionParameter({
+          name: dataParamName,
+          type: ast.createParamsType({ variant: 'reference', name: dataType }),
+          optional: true,
+        }),
+      ],
+    })
+    const paramsSignature = declarationPrinter.print(params) ?? ''
+    const returnType = resolvedReturnType
+
+    return (
+      <File.Source name={name} isExportable isIndexable>
+        <Function
+          export
+          name={name}
+          JSDoc={{ comments: description ? [`@description ${jsStringEscape(description)}`] : [] }}
+          params={canOverride ? paramsSignature : undefined}
+          returnType={returnType}
+        >
+          {seed ? (
+            <>
+              {`faker.seed(${JSON.stringify(seed)})`}
+              <br />
+            </>
+          ) : undefined}
+          {`return ${fakerTextWithOverride}`}
+        </Function>
+      </File.Source>
+    )
+  }
 
   return (
     <File.Source name={name} isExportable isIndexable>
-      <Function
-        export
-        name={name}
-        JSDoc={{ comments: [description ? `@description ${jsStringEscape(description)}` : undefined].filter(Boolean) }}
-        params={canOverride ? params.toConstructor() : undefined}
-        returnType={returnType}
-      >
-        {seed ? `faker.seed(${JSON.stringify(seed)})` : undefined}
-        <br />
-        {`return ${fakerTextWithOverride}`}
-      </Function>
+      {functionSignature}
+      {functionBody}
     </File.Source>
   )
 }