@kubb/plugin-faker 5.0.0-beta.4 → 5.0.0-beta.56

package/dist/{printerFaker-CJiwzoto.d.ts → printerFaker-CMCJT3FB.d.ts}

@@ -1,5 +1,5 @@
-import { t as __name } from "./chunk--u3MIqq1.js";
-import { Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
+import { t as __name } from "./chunk-C0LytTxp.js";
+import { Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
 
 //#region src/types.d.ts
 /**
@@ -41,6 +41,13 @@ type ResolverFaker = Resolver & ast.OperationParamsResolver & {
    * `resolver.resolveResponseName(node) // -> 'listPetsResponse'`
    */
   resolveResponseName(this: ResolverFaker, node: ast.OperationNode): string;
+  /**
+   * Resolves the faker function name for the response collection.
+   *
+   * @example Responses collection names
+   * `resolver.resolveResponsesName(node) // -> 'listPetsResponses'`
+   */
+  resolveResponsesName(this: ResolverFaker, node: ast.OperationNode): string;
   /**
    * Resolves the faker function name for path parameters.
    *
@@ -63,82 +70,84 @@ type ResolverFaker = Resolver & ast.OperationParamsResolver & {
    */
   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;
+/**
+ * Where the generated mock factories are written and how they are exported, plus the optional
+ * `group` strategy. The `group` option organizes `output.mode: 'directory'` output into per-tag or per-path subdirectories.
+ *
+ * @default { path: 'mocks', barrel: { type: 'named' } }
+ */
+type Options = OutputOptions & {
   /**
-   * Tags, operations, or paths to exclude from generation.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>;
   /**
-   * Tags, operations, or paths to include in generation.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>;
   /**
-   * Override options for specific tags, operations, or paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>;
   /**
-   * Parser to use when formatting date/time values as strings.
+   * Library used to format string-represented date, time, and datetime fields.
+   * Any library exporting a default function works; Kubb adds the import for you.
    *
    * @default 'faker'
    */
   dateParser?: 'faker' | 'dayjs' | 'moment' | (string & {});
   /**
-   * Generator to use for RegExp patterns.
+   * Library used to generate strings that satisfy a regex `pattern` keyword.
+   * - `'faker'` uses `faker.helpers.fromRegExp`. No extra dependency.
+   * - `'randexp'` uses the `randexp` package. Supports a wider regex grammar.
    *
    * @default 'faker'
    */
   regexGenerator?: 'faker' | 'randexp';
   /**
-   * Provide per-property faker expressions keyed by property name.
+   * Map a schema name to a custom Faker expression. Use this when the schema name
+   * does not give Faker enough context (`'email'`, `'avatarUrl'`, `'phoneNumber'`).
    */
   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.
+   * Faker locale code. Switches the named import to `fakerXX` from `@faker-js/faker`
+   * 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.
+   * Value passed to `faker.seed(...)`. Set this for deterministic mock output,
+   * which is useful for snapshot tests.
    */
-  seed?: number | number[];
+  seed?: number | Array<number>;
   /**
-   * Apply casing to parameter names to match your configuration.
+   * Rename properties inside path/query/header mocks. Body mocks are unaffected.
+   *
+   * @note Must match the value of `paramsCasing` on `@kubb/plugin-ts`.
    */
   paramsCasing?: 'camelcase';
   /**
-   * Additional generators alongside the default generators.
+   * Custom generators that run alongside the built-in Faker generators.
    */
   generators?: Array<Generator<PluginFaker>>;
   /**
-   * Override naming conventions for function names and types.
+   * Override the naming of generated factory helpers. Common use: append `Mock` or
+   * `Factory` so helpers do not clash with imported types.
    */
   resolver?: Partial<ResolverFaker> & ThisType<ResolverFaker>;
   /**
-   * AST visitor to transform generated nodes.
+   * AST visitor applied to schema and operation nodes before printing.
    */
   transformer?: ast.Visitor;
   /**
-   * Override individual faker printer node handlers.
+   * Replace the Faker handler for a specific schema type (`'integer'`, `'date'`, ...).
+   * Each handler returns the Faker expression as a string.
    */
   printer?: {
     nodes?: PrinterFakerNodes;
@@ -146,7 +155,7 @@ type Options = {
 };
 type ResolvedOptions = {
   output: Output;
-  group: Group | undefined;
+  group: Group | null;
   exclude: NonNullable<Options['exclude']>;
   include: Options['include'];
   override: NonNullable<Options['override']>;
@@ -169,11 +178,29 @@ declare global {
 //#endregion
 //#region src/printers/printerFaker.d.ts
 /**
- * Partial printer nodes for Faker generation, mapping schema types to output strings.
+ * Partial map of node-type overrides for the Faker printer. Each key is a
+ * `SchemaType` (`'string'`, `'date'`, ...) and each handler returns the
+ * Faker expression for that schema as a string. Use `this.transform` to
+ * recurse into nested schema nodes and `this.options` to read printer options.
+ *
+ * @example Override the integer handler
+ * ```ts
+ * pluginFaker({
+ *   printer: {
+ *     nodes: {
+ *       integer() {
+ *         return 'faker.number.float()'
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
  */
 type PrinterFakerNodes = ast.PrinterPartial<string, PrinterFakerOptions>;
 /**
- * Configuration options for the Faker printer, including resolvers, mappers, and cyclic schema tracking.
+ * Options passed to the Faker printer at instantiation: the parser library
+ * for date strings, the regex generator, the user-supplied schema-name
+ * mapper, and the resolver used to compute identifiers.
  */
 type PrinterFakerOptions = {
   dateParser?: PluginFaker['resolvedOptions']['dateParser'];
@@ -183,6 +210,12 @@ type PrinterFakerOptions = {
   typeName?: string;
   schemaName?: string;
   nestedInObject?: boolean;
+  /**
+   * Set while printing the members of a union (`oneOf`). Object properties then index their
+   * type as `(NonNullable<T> & Record<K, unknown>)[K]` instead of `NonNullable<T>[K]`, so a key
+   * carried by only some branches stays valid (a plain index would be a TS2339).
+   */
+  nestedInUnion?: boolean;
   nodes?: PrinterFakerNodes;
   /**
    * Names of schemas that participate in a circular dependency chain.
@@ -203,4 +236,4 @@ type PrinterFakerFactory = ast.PrinterFactoryOptions<'faker', PrinterFakerOption
 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
+//# sourceMappingURL=printerFaker-CMCJT3FB.d.ts.map

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "@kubb/plugin-faker",
-  "version": "5.0.0-beta.4",
-  "description": "Faker.js data generator plugin for Kubb, creating realistic mock data from OpenAPI specifications for development and testing.",
+  "version": "5.0.0-beta.56",
+  "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,6 @@
   "files": [
     "src",
     "dist",
-    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -71,33 +65,29 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.4",
-    "@kubb/renderer-jsx": "5.0.0-beta.4",
-    "@kubb/plugin-ts": "5.0.0-beta.4"
+    "@kubb/ast": "5.0.0-beta.55",
+    "@kubb/core": "5.0.0-beta.55",
+    "@kubb/renderer-jsx": "5.0.0-beta.55",
+    "@kubb/plugin-ts": "5.0.0-beta.56"
   },
   "devDependencies": {
+    "@internals/shared": "0.0.0",
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.4"
+    "@kubb/renderer-jsx": "5.0.0-beta.55"
   },
-  "size-limit": [
-    {
-      "path": "./dist/*.js",
-      "limit": "510 KiB",
-      "gzip": true
-    }
-  ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsdown && size-limit",
-    "clean": "npx rimraf ./dist",
+    "build": "tsdown",
+    "clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
     "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",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/components/Faker.tsx

@@ -1,4 +1,4 @@
-import { jsStringEscape } from '@internals/utils'
+import { jsStringEscape } from '@kubb/ast/utils'
 import { ast } from '@kubb/core'
 import { functionPrinter } from '@kubb/plugin-ts'
 import { File, Function } from '@kubb/renderer-jsx'
@@ -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}