@kubb/plugin-faker 5.1.3 → 5.1.4

package/docs/options.md

@@ -0,0 +1,205 @@
+# Options
+
+Pass these options to `pluginFaker()`, all of them optional. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options).
+
+## Options overview
+
+| Option                                                                    | Purpose                                                                     | Default                                        |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------- |
+| [`output`](https://kubb.dev/docs/5.x/reference/plugin-options#output)     | Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`.      | `{ path: 'mocks', barrel: { type: 'named' } }` |
+| [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group)       | Split output by tag or path: `type`, `name`.                                | None                                           |
+| [`typeMode`](#typemode)                                                   | Whether factory types come from the generated values or the declared model. | `'inferred'`                                   |
+| [`dateParser`](#dateparser)                                               | Library that formats string date and time fields.                           | `'faker'`                                      |
+| [`regexGenerator`](#regexgenerator)                                       | Library that turns a regex `pattern` into a string.                         | `'faker'`                                      |
+| [`locale`](#locale)                                                       | Faker locale code for the generated values.                                 | `'en'`                                         |
+| [`seed`](#seed)                                                           | Value passed to `faker.seed(...)` for deterministic output.                 | None                                           |
+| [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include)   | Keep only operations and schemas that match.                                | None                                           |
+| [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude)   | Skip operations and schemas that match.                                     | `[]`                                           |
+| [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern.                                        | `[]`                                           |
+| [`resolver`](#resolver)                                                   | Customize generated names and file paths.                                   | `resolverFaker`                                |
+| [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros)     | Rewrite AST nodes before printing.                                          | `[]`                                           |
+| [`printer`](#printer)                                                     | Replace the handler for a schema type.                                      | None                                           |
+
+## Option details
+
+### typeMode
+
+Controls the input and return types of object and intersection factories. Both modes generate the same values and apply overrides with a shallow merge.
+
+|          |                          |
+| -------- | ------------------------ |
+| Type     | `'inferred' \| 'schema'` |
+| Required | `false`                  |
+| Default  | `'inferred'`             |
+
+::field-group
+
+:::field{name="'inferred'"}
+Default value. Derives return types from generated values and supplied overrides. Optional and nullable fields retain their concrete value types, and overrides preserve literal types.
+:::
+
+:::field{name="'schema'"}
+Accepts `Partial<Model>` and returns the declared model type, including optional and nullable fields. Use it for fixtures you modify after creation.
+:::
+
+::
+
+::code-group
+
+```typescript ['inferred' (default)]
+// export function createOrder<TData extends Partial<Order> = object>(data?: TData)
+const order = createOrder({ quantity: 2, complete: true })
+const complete: true = order.complete
+
+// TypeScript error: false is not assignable to true.
+order.complete = false
+```
+
+```typescript ['schema']
+// export function createOrder(data?: Partial<Order>): Order
+const order = createOrder({ quantity: 2, complete: true })
+order.complete = false
+
+// TypeScript error: foo does not exist in Partial<Order>.
+createOrder({ quantity: 2, foo: '' })
+```
+
+::
+
+Use [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) to select a mode for matching schemas. String patterns are regular expressions, so `'^Order$'` matches only the `Order` schema:
+
+```typescript [kubb.config.ts]
+pluginFaker({
+  override: [{ type: 'schemaName', pattern: '^Order$', options: { typeMode: 'schema' } }],
+})
+```
+
+### dateParser
+
+Library used to format `date` and `time` fields represented as strings. Pick a value other than `'faker'` when your project already uses a date library, and install that library in the consuming app. Generated `date` and `time` strings use `YYYY-MM-DD` and `HH:mm:ss`, and `date-time` values keep the ISO string.
+
+|          |                                            |
+| -------- | ------------------------------------------ |
+| Type     | `'faker' \| 'dayjs' \| 'moment' \| string` |
+| Required | `false`                                    |
+| Default  | `'faker'`                                  |
+
+::field-group
+
+:::field{name="'faker'"}
+Default value. Renders a `date` field as `faker.date.anytime().toISOString().substring(0, 10)`.
+:::
+
+:::field{name="'dayjs'"}
+Renders it as `dayjs(faker.date.anytime()).format('YYYY-MM-DD')`.
+:::
+
+:::field{name="'moment'"}
+Renders it as `moment(faker.date.anytime()).format('YYYY-MM-DD')`.
+:::
+
+:::field{name="Custom module"}
+Pass a module name that exports a default formatting function. Kubb adds the import to generated files.
+:::
+
+::
+
+### regexGenerator
+
+Library used to generate strings that satisfy a regex `pattern` in the spec.
+
+|          |                        |
+| -------- | ---------------------- |
+| Type     | `'faker' \| 'randexp'` |
+| Required | `false`                |
+| Default  | `'faker'`              |
+
+::field-group
+
+:::field{name="'faker'"}
+Default value. Generates `faker.helpers.fromRegExp(pattern)` without an extra dependency.
+:::
+
+:::field{name="'randexp'"}
+Generates `new RandExp(pattern).gen()`. Supports a wider regex grammar and requires the `randexp` runtime dependency.
+:::
+
+::
+
+### locale
+
+Faker locale code. It switches the named import to `fakerXX` from `@faker-js/faker`, so generated values reflect the target region. The default `'en'` imports `fakerEN`, `'de'` imports `fakerDE`, and `'de_AT'` imports `fakerDE_AT`. See [Faker.js localization](https://fakerjs.dev/api/localization.html) for all locale codes.
+
+|          |          |
+| -------- | -------- |
+| Type     | `string` |
+| Required | `false`  |
+| Default  | `'en'`   |
+
+### seed
+
+Kubb passes this value to `faker.seed(...)` at the top of each factory, so every run returns the same data. Use it for snapshot tests. Pass a single number or an array of numbers. Factories still accept overrides, such as `createPet({ name: 'Rex' })`.
+
+|          |                      |
+| -------- | -------------------- |
+| Type     | `number \| number[]` |
+| Required | `false`              |
+
+### resolver
+
+Overrides generated file and symbol names. Omitted members keep `resolverFaker`. The shared members (`name`, `file`, `imports`) and the `this` context are described under [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver).
+
+|          |                                |
+| -------- | ------------------------------ |
+| Type     | `ResolverPatch<ResolverFaker>` |
+| Required | `false`                        |
+
+::code-collapse{name="ResolverFaker patch members"}
+
+```typescript [Partial override]
+type ResolverFakerPatch = {
+  name?(name: string): string
+  file?: {
+    baseName?(params: { name: string; extname: string }): string
+    path?(params: { baseName: string; output: Output }): string
+  }
+  imports?(options: ResolveImportsOptions): Array<ImportNode>
+  param?: {
+    name?(node: OperationNode, param: ParameterNode): string    // → 'showPetByIdPathPetId'
+    path?(node: OperationNode, param: ParameterNode): string     // → 'createShowPetByIdPath'
+    query?(node: OperationNode, param: ParameterNode): string    // → 'createListPetsQuery'
+    headers?(node: OperationNode, param: ParameterNode): string  // → 'createDeletePetHeaders'
+  }
+  response?: {
+    status?(node: OperationNode, statusCode: StatusCode): string // → 'listPetsStatus200'
+    body?(node: OperationNode): string                           // → 'createPetsBody'
+    response?(node: OperationNode): string                       // → 'listPetsResponse'
+    responses?(node: OperationNode): string                      // → 'listPetsResponses'
+  }
+}
+```
+
+::
+
+### printer
+
+Replaces the Faker node handler for a specific schema type, such as `'integer'`, `'date'`, or `'string'`. Each handler returns the Faker expression as a string. Use `this.transform` to recurse into nested nodes and `this.options` to read printer options. The [printer guide](https://kubb.dev/docs/5.x/how-to/printers) covers how overrides compose with macros.
+
+|          |                                 |
+| -------- | ------------------------------- |
+| Type     | `{ nodes?: PrinterFakerNodes }` |
+| Required | `false`                         |
+
+```typescript [Map integer schemas to a float]
+import { pluginFaker } from '@kubb/plugin-faker'
+
+pluginFaker({
+  printer: {
+    nodes: {
+      integer() {
+        return 'faker.number.float()'
+      },
+    },
+  },
+})
+```

package/{OVERVIEW.md → docs/overview.md}

@@ -15,4 +15,27 @@ Generates a Faker.js mock-data factory for every schema in your OpenAPI spec. Us
 - `locale` sets the Faker locale. The default is `en`.
 - `dateParser` formats date and time strings with `faker` (default), `dayjs`, or `moment`. Install the library you pick.
 - `regexGenerator` turns a `pattern` into a string with `faker` (default) or `randexp`.
-- `typeMode` sets the factory types: `inferred` (default) derives them from the generated values, `schema` uses the declared model type.
+- `typeMode` sets the factory types: `inferred` (default) derives them from the generated values. `schema` uses the declared model type.
+
+## Example
+
+```typescript [kubb.config.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({ seed: [100] }),
+  ],
+})
+```
+
+## See also
+
+- [Faker.js](https://fakerjs.dev/)
+- [@kubb/plugin-ts](https://kubb.dev/extensions/kubb-labs/plugin-ts)
+- [@kubb/plugin-msw](https://kubb.dev/extensions/kubb-labs/plugin-msw)

package/kubb-extension.json

@@ -10,9 +10,16 @@
     "light": "https://kubb.dev/feature/faker.svg"
   },
   "tags": ["faker", "mock-data", "mocks", "fixtures", "testing", "codegen", "openapi"],
-  "docs": "https://kubb.dev/plugins/plugin-faker",
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-faker",
+  "maintainers": [
+    {
+      "name": "Stijn Van Hulle",
+      "github": "stijnvanhulle"
+    }
+  ],
+  "dependencies": ["plugin-ts"],
   "compatibility": {
-    "kubb": ">=5.8.0",
+    "kubb": ">=5.8.3",
     "node": ">=22"
   },
   "options": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-faker",
-  "version": "5.1.3",
+  "version": "5.1.4",
   "description": "Generate Faker.js mock data factories with Kubb. Produces realistic seed data and fixtures for development and testing.",
   "keywords": [
     "code-generation",
@@ -15,7 +15,7 @@
     "mocks",
     "typescript"
   ],
-  "homepage": "https://kubb.dev/plugins/plugin-faker",
+  "homepage": "https://kubb.dev/extensions/kubb-labs/plugin-faker",
   "license": "MIT",
   "author": "stijnvanhulle",
   "repository": {
@@ -40,7 +40,7 @@
   "files": [
     "dist",
     "kubb-extension.json",
-    "OVERVIEW.md",
+    "docs",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -74,17 +74,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.0.8"
+    "@kubb/plugin-ts": "^5.0.9"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.6.0",
     "@internals/shared": "0.0.0",
     "@internals/utils": "0.0.0",
-    "kubb": "^5.8.1"
+    "kubb": "^5.8.3"
   },
   "peerDependencies": {
     "@faker-js/faker": "^10.0.0",
-    "kubb": "^5.8.1"
+    "kubb": "^5.8.3"
   },
   "peerDependenciesMeta": {
     "@faker-js/faker": {