@kubb/plugin-faker 5.0.0-beta.10 → 5.0.0-beta.103

package/dist/index.d.ts

@@ -1,32 +1,293 @@
-import { t as __name } from "./chunk--u3MIqq1.js";
-import { a as Options, i as printerFaker, n as PrinterFakerNodes, o as PluginFaker, r as PrinterFakerOptions, s as ResolverFaker, t as PrinterFakerFactory } from "./printerFaker-W0pLunAj.js";
-import { t as Faker } from "./Faker-BMgoFj8b.js";
-import { t as fakerGenerator } from "./fakerGenerator-B-QnVz9o.js";
-import * as _$_kubb_core0 from "@kubb/core";
-
+import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
+import { Exclude, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ResolverPatch, ast } from "kubb/kit";
+import { KubbReactNode } from "kubb/jsx";
+//#region src/types.d.ts
+/**
+ * Resolver for Faker that provides naming methods for mock functions.
+ *
+ * The top-level `name` and `file` apply the plugin's `create` prefix. Composite
+ * operation naming is grouped into the `param` and `response` namespaces.
+ */
+type ResolverFaker = Resolver & {
+  /**
+   * Naming for operation parameters, keyed by their location.
+   */
+  param: {
+    /**
+     * Resolves the faker function name for an individual parameter.
+     *
+     * @example Individual parameter name
+     * `resolver.param.name(node, param) // -> 'showPetByIdPathPetId'`
+     */
+    name(node: ast.OperationNode, param: ast.ParameterNode): string;
+    /**
+     * Resolves the faker function name for an operation's grouped path parameters.
+     *
+     * @example Grouped path parameters name
+     * `resolver.param.path(node, param) // -> 'createShowPetByIdPath'`
+     */
+    path(node: ast.OperationNode, param: ast.ParameterNode): string;
+    /**
+     * Resolves the faker function name for an operation's grouped query parameters.
+     *
+     * @example Grouped query parameters name
+     * `resolver.param.query(node, param) // -> 'createListPetsQuery'`
+     */
+    query(node: ast.OperationNode, param: ast.ParameterNode): string;
+    /**
+     * Resolves the faker function name for an operation's grouped header parameters.
+     *
+     * @example Grouped header parameters name
+     * `resolver.param.headers(node, param) // -> 'createDeletePetHeaders'`
+     */
+    headers(node: ast.OperationNode, param: ast.ParameterNode): string;
+  };
+  /**
+   * Naming for operation request bodies and responses.
+   */
+  response: {
+    /**
+     * Resolves the faker function name for a response by status code.
+     *
+     * @example Response status name
+     * `resolver.response.status(node, 200) // -> 'listPetsStatus200'`
+     */
+    status(node: ast.OperationNode, statusCode: ast.StatusCode): string;
+    /**
+     * Resolves the faker function name for a request body.
+     *
+     * @example Request body name
+     * `resolver.response.body(node) // -> 'createPetsBody'`
+     */
+    body(node: ast.OperationNode): string;
+    /**
+     * Resolves the faker function name for the response union.
+     *
+     * @example Response union name
+     * `resolver.response.response(node) // -> 'listPetsResponse'`
+     */
+    response(node: ast.OperationNode): string;
+    /**
+     * Resolves the faker function name for the response collection.
+     *
+     * @example Responses collection name
+     * `resolver.response.responses(node) // -> 'listPetsResponses'`
+     */
+    responses(node: ast.OperationNode): string;
+  };
+};
+/**
+ * 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 & {
+  /**
+   * Skip operations matching at least one entry in the list.
+   */
+  exclude?: Array<Exclude>;
+  /**
+   * Restrict generation to operations matching at least one entry in the list.
+   */
+  include?: Array<Include>;
+  /**
+   * Apply a different options object to operations matching a pattern.
+   */
+  override?: Array<Override<ResolvedOptions>>;
+  /**
+   * 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 & {});
+  /**
+   * 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';
+  /**
+   * 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;
+  /**
+   * Value passed to `faker.seed(...)`. Set this for deterministic mock output,
+   * which is useful for snapshot tests.
+   */
+  seed?: number | Array<number>;
+  /**
+   * Override the naming of generated factory helpers. Common use: append `Mock` or
+   * `Factory` so helpers do not clash with imported types.
+   */
+  resolver?: ResolverPatch<ResolverFaker>;
+  /**
+   * Macros applied to schema and operation nodes before printing.
+   */
+  macros?: Array<ast.Macro>;
+  /**
+   * Replace the Faker handler for a specific schema type (`'integer'`, `'date'`, ...).
+   * Each handler returns the Faker expression as a string.
+   */
+  printer?: {
+    nodes?: PrinterFakerNodes;
+  };
+};
+type ResolvedOptions = {
+  output: Output;
+  group: Group | null;
+  exclude: NonNullable<Options['exclude']>;
+  include: Options['include'];
+  override: NonNullable<Options['override']>;
+  dateParser: NonNullable<Options['dateParser']>;
+  regexGenerator: NonNullable<Options['regexGenerator']>;
+  seed: NonNullable<Options['seed']> | undefined;
+  locale: Options['locale'];
+  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 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>;
+/**
+ * Options passed to the Faker printer at instantiation: the parser library
+ * for date strings, the regex generator, and the resolver used to compute
+ * identifiers.
+ */
+type PrinterFakerOptions = {
+  dateParser?: PluginFaker['resolvedOptions']['dateParser'];
+  regexGenerator?: PluginFaker['resolvedOptions']['regexGenerator'];
+  resolver: ResolverFaker;
+  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.
+   * 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
+//#region src/components/Faker.d.ts
+type Props = {
+  name: string;
+  typeName: string;
+  node: ast.SchemaNode;
+  printer: ast.Printer<PrinterFakerFactory>;
+  seed?: PluginFaker['options']['seed'];
+  description?: string;
+  canOverride: boolean;
+};
+declare function Faker({ node, description, name, typeName, printer, seed, canOverride }: Props): KubbReactNode;
+//#endregion
+//#region src/generators/fakerGenerator.d.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`.
+ */
+declare const fakerGenerator: import("kubb/kit").Generator<PluginFaker, unknown>;
+//#endregion
 //#region src/plugin.d.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.
  */
 declare const pluginFakerName = "plugin-faker";
 /**
- * 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/config'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginFaker } from '@kubb/plugin-faker'
+ *
+ * export default defineConfig({
+ *   input: './petStore.yaml',
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginFaker({
+ *       output: { path: './mocks' },
+ *       seed: [100],
+ *     }),
+ *   ],
+ * })
+ * ```
  */
-declare const pluginFaker: (options?: Options | undefined) => _$_kubb_core0.Plugin<PluginFaker>;
+declare const pluginFaker: (options?: Options | undefined) => import("kubb/kit").Plugin<PluginFaker>;
 //#endregion
 //#region src/resolvers/resolverFaker.d.ts
 /**
- * Naming convention resolver for Faker plugin.
+ * Default resolver used by `@kubb/plugin-faker`. Decides the names and file
+ * paths for every generated mock factory. Functions and files are prefixed
+ * with `create` so `Pet` becomes `createPet`.
  *
- * Provides default naming helpers using camelCase with a `create` prefix for factory functions and files.
+ * @example Resolve a factory name
+ * ```ts
+ * import { resolverFaker } from '@kubb/plugin-faker'
  *
- * @example
- * `resolverFaker.default('list pets', 'function')  // → 'createListPets'`
+ * resolverFaker.name('list pets') // 'createListPets'
+ * ```
  */
 declare const resolverFaker: ResolverFaker;
 //#endregion