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

package/src/plugin.ts

@@ -1,149 +1,88 @@
-import path from 'node:path'
 import { camelCase } from '@internals/utils'
-import { createPlugin, type Group, getBarrelFiles, getMode } from '@kubb/core'
-import { OperationGenerator, pluginOasName, SchemaGenerator } from '@kubb/plugin-oas'
+import { definePlugin, type Group } 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.
+ */
 export const pluginFakerName = 'plugin-faker' satisfies PluginFaker['name']
 
-export const pluginFaker = createPlugin<PluginFaker>((options) => {
+/**
+ * Generates Faker mock data factories from OpenAPI/AST specification.
+ *
+ * Creates randomized test data and mock helpers from schema definitions.
+ *
+ * @example
+ * `import pluginFaker from '@kubb/plugin-faker'; export default defineConfig({ plugins: [pluginFaker({ output: { path: 'mocks' } })], })`
+ */
+export const pluginFaker = definePlugin<PluginFaker>((options) => {
   const {
     output = { path: 'mocks', barrelType: 'named' },
     seed,
+    locale,
     group,
     exclude = [],
     include,
     override = [],
-    transformers = {},
     mapper = {},
-    unknownType = 'any',
-    emptySchemaType = unknownType,
-    dateType = 'string',
-    integerType = 'number',
     dateParser = 'faker',
-    generators = [fakerGenerator].filter(Boolean),
+    generators: userGenerators = [],
     regexGenerator = 'faker',
     paramsCasing,
-    contentType,
+    printer,
+    resolver: userResolver,
+    transformer: userTransformer,
   } = options
 
-  // @deprecated Will be removed in v5 when collisionDetection defaults to true
-  const usedEnumNames = {}
-
-  return {
-    name: pluginFakerName,
-    options: {
-      output,
-      transformers,
-      seed,
-      dateType,
-      integerType,
-      unknownType,
-      emptySchemaType,
-      dateParser,
-      mapper,
-      override,
-      regexGenerator,
-      paramsCasing,
-      group,
-      usedEnumNames,
-    },
-    pre: [pluginOasName, pluginTsName],
-    resolvePath(baseName, pathMode, options) {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = pathMode ?? getMode(path.resolve(root, output.path))
-
-      if (mode === 'single') {
-        /**
-         * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
-         * Other plugins then need to call addOrAppend instead of just add from the fileManager class
-         */
-        return path.resolve(root, output.path)
-      }
-
-      if (group && (options?.group?.path || options?.group?.tag)) {
-        const groupName: Group['name'] = group?.name
+  const groupConfig = group
+    ? ({
+        ...group,
+        name: group.name
           ? group.name
-          : (ctx) => {
-              if (group?.type === 'path') {
+          : (ctx: { group: string }) => {
+              if (group.type === 'path') {
                 return `${ctx.group.split('/')[1]}`
               }
-              return `${camelCase(ctx.group)}Controller`
-            }
-
-        return path.resolve(
-          root,
-          output.path,
-          groupName({
-            group: group.type === 'path' ? options.group.path! : options.group.tag!,
-          }),
-          baseName,
-        )
-      }
-
-      return path.resolve(root, output.path, baseName)
-    },
-    resolveName(name, type) {
-      const resolvedName = camelCase(name, {
-        prefix: type ? 'create' : undefined,
-        isFile: type === 'file',
-      })
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
-      }
 
-      return resolvedName
-    },
-    async install() {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = getMode(path.resolve(root, output.path))
-      const oas = await this.getOas()
-
-      const schemaGenerator = new SchemaGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        include: undefined,
-        override,
-        mode,
-        output: output.path,
-      })
-
-      const schemaFiles = await schemaGenerator.build(...generators)
-      await this.upsertFile(...schemaFiles)
-
-      const operationGenerator = new OperationGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        exclude,
-        include,
-        override,
-        mode,
-      })
-
-      const operationFiles = await operationGenerator.build(...generators)
-      await this.upsertFile(...operationFiles)
-
-      const barrelFiles = await getBarrelFiles(this.fabric.files, {
-        type: output.barrelType ?? 'named',
-        root,
-        output,
-        meta: {
-          pluginName: this.plugin.name,
-        },
-      })
+              return `${camelCase(ctx.group)}Controller`
+            },
+      } satisfies Group)
+    : undefined
 
-      await this.upsertFile(...barrelFiles)
+  return {
+    name: pluginFakerName,
+    options,
+    dependencies: [pluginTsName],
+    hooks: {
+      'kubb:plugin:setup'(ctx) {
+        ctx.setOptions({
+          output,
+          seed,
+          locale,
+          exclude,
+          include,
+          override,
+          group: groupConfig,
+          mapper,
+          dateParser,
+          regexGenerator,
+          paramsCasing,
+          printer,
+        })
+        ctx.setResolver(userResolver ? { ...resolverFaker, ...userResolver } : resolverFaker)
+        if (userTransformer) {
+          ctx.setTransformer(userTransformer)
+        }
+        ctx.addGenerator(fakerGenerator)
+        for (const generator of userGenerators) {
+          ctx.addGenerator(generator)
+        }
+      },
     },
   }
 })
+
+export default pluginFaker

package/src/printers/printerFaker.ts

@@ -0,0 +1,341 @@
+import { stringify, toRegExpString } from '@internals/utils'
+import { ast } from '@kubb/core'
+import type { PluginFaker, ResolverFaker } from '../types.ts'
+
+/**
+ * Partial printer nodes for Faker generation, mapping schema types to output strings.
+ */
+export type PrinterFakerNodes = ast.PrinterPartial<string, PrinterFakerOptions>
+
+/**
+ * Configuration options for the Faker printer, including resolvers, mappers, and cyclic schema tracking.
+ */
+export 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.
+ */
+export type PrinterFakerFactory = ast.PrinterFactoryOptions<'faker', PrinterFakerOptions, string, string>
+
+const fakerKeywordMapper = {
+  any: () => 'undefined',
+  unknown: () => 'undefined',
+  void: () => 'undefined',
+  number: (min?: number, max?: number) => {
+    if (max !== undefined && min !== undefined) {
+      return `faker.number.float({ min: ${min}, max: ${max} })`
+    }
+
+    if (max !== undefined) {
+      return `faker.number.float({ max: ${max} })`
+    }
+
+    if (min !== undefined) {
+      return `faker.number.float({ min: ${min} })`
+    }
+
+    return 'faker.number.float()'
+  },
+  integer: (min?: number, max?: number) => {
+    if (max !== undefined && min !== undefined) {
+      return `faker.number.int({ min: ${min}, max: ${max} })`
+    }
+
+    if (max !== undefined) {
+      return `faker.number.int({ max: ${max} })`
+    }
+
+    if (min !== undefined) {
+      return `faker.number.int({ min: ${min} })`
+    }
+
+    return 'faker.number.int()'
+  },
+  bigint: () => 'faker.number.bigInt()',
+  string: (min?: number, max?: number) => {
+    if (max !== undefined && min !== undefined) {
+      return `faker.string.alpha({ length: { min: ${min}, max: ${max} } })`
+    }
+
+    if (max !== undefined) {
+      return `faker.string.alpha({ length: ${max} })`
+    }
+
+    if (min !== undefined) {
+      return `faker.string.alpha({ length: ${min} })`
+    }
+
+    return 'faker.string.alpha()'
+  },
+  boolean: () => 'faker.datatype.boolean()',
+  null: () => 'null',
+  array: (items: string[] = [], min?: number, max?: number) => {
+    if (items.length > 1) {
+      return `faker.helpers.arrayElements([${items.join(', ')}])`
+    }
+
+    const item = items.at(0)
+
+    if (min !== undefined && max !== undefined) {
+      return `faker.helpers.multiple(() => (${item}), { count: { min: ${min}, max: ${max} }})`
+    }
+
+    if (min !== undefined) {
+      return `faker.helpers.multiple(() => (${item}), { count: ${min} })`
+    }
+
+    if (max !== undefined) {
+      return `faker.helpers.multiple(() => (${item}), { count: { min: 0, max: ${max} }})`
+    }
+
+    return `faker.helpers.multiple(() => (${item}))`
+  },
+  tuple: (items: string[] = []) => `[${items.join(', ')}]`,
+  enum: (items: Array<string | number | boolean | undefined> = [], type = 'any') => `faker.helpers.arrayElement<${type}>([${items.join(', ')}])`,
+  union: (items: string[] = []) => `faker.helpers.arrayElement<any>([${items.join(', ')}])`,
+  datetime: () => 'faker.date.anytime().toISOString()',
+  date: (representation: 'date' | 'string' = 'string', parser: PluginFaker['resolvedOptions']['dateParser'] = 'faker') => {
+    if (representation === 'string') {
+      if (parser !== 'faker') {
+        return `${parser}(faker.date.anytime()).format("YYYY-MM-DD")`
+      }
+
+      return 'faker.date.anytime().toISOString().substring(0, 10)'
+    }
+
+    if (parser !== 'faker') {
+      throw new Error(`type '${representation}' and parser '${parser}' can not work together`)
+    }
+
+    return 'faker.date.anytime()'
+  },
+  time: (representation: 'date' | 'string' = 'string', parser: PluginFaker['resolvedOptions']['dateParser'] = 'faker') => {
+    if (representation === 'string') {
+      if (parser !== 'faker') {
+        return `${parser}(faker.date.anytime()).format("HH:mm:ss")`
+      }
+
+      return 'faker.date.anytime().toISOString().substring(11, 19)'
+    }
+
+    if (parser !== 'faker') {
+      throw new Error(`type '${representation}' and parser '${parser}' can not work together`)
+    }
+
+    return 'faker.date.anytime()'
+  },
+  uuid: () => 'faker.string.uuid()',
+  url: () => 'faker.internet.url()',
+  and: (items: string[] = []) => {
+    if (items.length === 0) {
+      return '{}'
+    }
+
+    if (items.length === 1) {
+      return items[0] ?? '{}'
+    }
+
+    return `{...${items.join(', ...')}}`
+  },
+  matches: (value = '', regexGenerator: 'faker' | 'randexp' = 'faker') => {
+    if (regexGenerator === 'randexp') {
+      return `${toRegExpString(value, 'RandExp')}.gen()`
+    }
+
+    return `faker.helpers.fromRegExp("${value}")`
+  },
+  email: () => 'faker.internet.email()',
+  blob: () => 'faker.image.url() as unknown as Blob',
+} as const
+
+function getEnumValues(node: ast.EnumSchemaNode): Array<string | number | boolean | undefined> {
+  if (node.namedEnumValues?.length) {
+    return node.namedEnumValues.map((item) => item.value as string | number | boolean | undefined)
+  }
+
+  return (node.enumValues ?? []) as Array<string | number | boolean | undefined>
+}
+
+function parseEnumValue(value: string | number | boolean | undefined) {
+  if (typeof value === 'string') {
+    return stringify(value)
+  }
+
+  return value
+}
+
+/**
+ * Creates a Faker printer that generates mock data generation code from schema nodes.
+ * Handles circular references gracefully by emitting memoizing getters for cyclic properties.
+ */
+export const printerFaker: (options: PrinterFakerOptions) => ast.Printer<PrinterFakerFactory> = ast.definePrinter<PrinterFakerFactory>((options) => {
+  const printNested = (node: ast.SchemaNode, overrideOptions: Partial<PrinterFakerOptions> = {}): string => {
+    return (
+      printerFaker({
+        ...options,
+        ...overrideOptions,
+        nodes: options.nodes,
+      }).print(node) ?? 'undefined'
+    )
+  }
+
+  return {
+    name: 'faker',
+    options,
+    nodes: {
+      any: () => fakerKeywordMapper.any(),
+      unknown: () => fakerKeywordMapper.unknown(),
+      void: () => fakerKeywordMapper.void(),
+      boolean: () => fakerKeywordMapper.boolean(),
+      null: () => fakerKeywordMapper.null(),
+      string(node) {
+        if (node.pattern) {
+          return fakerKeywordMapper.matches(node.pattern, this.options.regexGenerator)
+        }
+
+        return fakerKeywordMapper.string(node.min, node.max)
+      },
+      email: () => fakerKeywordMapper.email(),
+      url: () => fakerKeywordMapper.url(),
+      uuid: () => fakerKeywordMapper.uuid(),
+      number(node) {
+        return fakerKeywordMapper.number(node.min, node.max)
+      },
+      integer(node) {
+        return fakerKeywordMapper.integer(node.min, node.max)
+      },
+      bigint: () => fakerKeywordMapper.bigint(),
+      blob: () => fakerKeywordMapper.blob(),
+      datetime: () => fakerKeywordMapper.datetime(),
+      date(node) {
+        return fakerKeywordMapper.date(node.representation ?? 'string', this.options.dateParser)
+      },
+      time(node) {
+        return fakerKeywordMapper.time(node.representation ?? 'string', this.options.dateParser)
+      },
+      ref(node) {
+        // Parser-generated refs (with $ref) carry raw schema names that need resolving.
+        // Use the canonical name from the $ref path — node.name may have been overridden
+        // (e.g. by single-member allOf flatten using the property-derived child name).
+        // Inline refs (without $ref) from faker utils already carry resolved helper names.
+        const refName = node.ref ? (ast.extractRefName(node.ref) ?? node.name ?? node.schema?.name) : (node.name ?? node.schema?.name)
+
+        if (!refName) {
+          throw new Error('Name not defined for ref node')
+        }
+
+        if (this.options.schemaName && refName === this.options.schemaName) {
+          return 'undefined as any'
+        }
+
+        // Internal helper refs (for generated response/data helpers) are already
+        // emitted with resolver output and should not be transformed twice.
+        const resolvedName = node.ref ? this.options.resolver.resolveName(refName) : refName
+
+        if (!this.options.nestedInObject) {
+          return `${resolvedName}(data)`
+        }
+
+        return `${resolvedName}()`
+      },
+      enum(node) {
+        return fakerKeywordMapper.enum(getEnumValues(node).map(parseEnumValue), this.options.typeName)
+      },
+      union(node): string {
+        const items: string[] = (node.members ?? [])
+          .map((member) =>
+            printNested(member, {
+              nestedInObject: true,
+            }),
+          )
+          .filter((item): item is string => Boolean(item))
+
+        return fakerKeywordMapper.union(items)
+      },
+      intersection(node): string {
+        const items: string[] = (node.members ?? [])
+          .map((member) =>
+            printNested(member, {
+              nestedInObject: true,
+            }),
+          )
+          .filter((item): item is string => Boolean(item))
+
+        return fakerKeywordMapper.and(items)
+      },
+      array(node): string {
+        const items: string[] = (node.items ?? [])
+          .map((member) =>
+            printNested(member, {
+              typeName: this.options.typeName ? `NonNullable<${this.options.typeName}>[number]` : undefined,
+              nestedInObject: true,
+            }),
+          )
+          .filter((item): item is string => Boolean(item))
+
+        return fakerKeywordMapper.array(items, node.min, node.max)
+      },
+      tuple(node): string {
+        const items: string[] = (node.items ?? [])
+          .map((member, index) =>
+            printNested(member, {
+              typeName: this.options.typeName ? `NonNullable<${this.options.typeName}>[${index}]` : undefined,
+              nestedInObject: true,
+            }),
+          )
+          .filter((item): item is string => Boolean(item))
+
+        return fakerKeywordMapper.tuple(items)
+      },
+      object(node): string {
+        const cyclicSchemas = this.options.cyclicSchemas
+        const properties = (node.properties ?? [])
+          .map((property): string => {
+            if (this.options.mapper && Object.hasOwn(this.options.mapper, property.name)) {
+              return `"${property.name}": ${this.options.mapper[property.name]}`
+            }
+
+            const value: string =
+              printNested(property.schema, {
+                typeName: this.options.typeName ? `NonNullable<${this.options.typeName}>[${JSON.stringify(property.name)}]` : undefined,
+                nestedInObject: true,
+              }) ?? 'undefined'
+
+            // When the property's schema transitively references a schema that is
+            // part of a circular dependency (other than the current schema itself),
+            // emit a memoizing lazy getter. On first access it computes the value,
+            // replaces itself with a plain data property via Object.defineProperty,
+            // and returns the cached value – so every subsequent read is stable.
+            if (cyclicSchemas && ast.containsCircularRef(property.schema, { circularSchemas: cyclicSchemas, excludeName: this.options.schemaName })) {
+              return `get ${property.name}() { const _value = ${value}; Object.defineProperty(this, ${JSON.stringify(property.name)}, { value: _value, configurable: true, writable: true, enumerable: true }); return _value }`
+            }
+
+            return `"${property.name}": ${value}`
+          })
+          .join(',')
+
+        return `{${properties}}`
+      },
+      ...options.nodes,
+    },
+    print(node) {
+      return this.transform(node) ?? null
+    },
+  }
+})

package/src/resolvers/resolverFaker.ts

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { camelCase, isValidVarName } from '@internals/utils'
+import { defineResolver, PluginDriver } from '@kubb/core'
+import type { PluginFaker } from '../types.ts'
+
+/**
+ * Naming convention resolver for Faker plugin.
+ *
+ * Provides default naming helpers using camelCase with a `create` prefix for factory functions and files.
+ *
+ * @example
+ * `resolverFaker.default('list pets', 'function')  // → 'createListPets'`
+ */
+export const resolverFaker = defineResolver<PluginFaker>(() => {
+  return {
+    name: 'default',
+    pluginName: 'plugin-faker',
+    default(name, type) {
+      const resolvedName = camelCase(name, { isFile: type === 'file', prefix: 'create' })
+
+      if (type === 'file' || isValidVarName(resolvedName)) {
+        return resolvedName
+      }
+
+      return `_${resolvedName}`
+    },
+    resolveName(name, type) {
+      return this.default(name, type)
+    },
+    resolvePathName(name, type) {
+      return this.default(name, type)
+    },
+    resolveFile({ name, extname, tag, path: groupPath }, context) {
+      const pathMode = PluginDriver.getMode(path.resolve(context.root, context.output.path))
+      const baseName = `${pathMode === 'single' ? '' : this.resolveName(name, 'file')}${extname}` as `${string}.${string}`
+      const filePath = this.resolvePath(
+        {
+          baseName,
+          pathMode,
+          tag,
+          path: groupPath,
+        },
+        context,
+      )
+
+      return {
+        kind: 'File',
+        id: createHash('sha256').update(filePath).digest('hex'),
+        name: path.basename(filePath, extname),
+        path: filePath,
+        baseName,
+        extname,
+        meta: { pluginName: this.pluginName },
+        sources: [],
+        imports: [],
+        exports: [],
+      }
+    },
+    resolveParamName(node, param) {
+      return this.resolveName(`${node.operationId} ${param.in} ${param.name}`)
+    },
+    resolveDataName(node) {
+      return this.resolveName(`${node.operationId} Data`)
+    },
+    resolveResponseStatusName(node, statusCode) {
+      return this.resolveName(`${node.operationId} Status ${statusCode}`)
+    },
+    resolveResponseName(node) {
+      return this.resolveName(`${node.operationId} Response`)
+    },
+    resolveResponsesName(node) {
+      return this.resolveName(`${node.operationId} Responses`)
+    },
+    resolvePathParamsName(node, param) {
+      return this.resolveParamName(node, param)
+    },
+    resolveQueryParamsName(node, param) {
+      return this.resolveParamName(node, param)
+    },
+    resolveHeaderParamsName(node, param) {
+      return this.resolveParamName(node, param)
+    },
+  }
+})