@kubb/plugin-faker 3.0.0-alpha.0

package/src/parser/index.ts

@@ -0,0 +1,313 @@
+import transformers from '@kubb/core/transformers'
+import { SchemaGenerator, isKeyword, schemaKeywords } from '@kubb/plugin-oas'
+
+import type { Schema, SchemaKeywordBase, SchemaKeywordMapper, SchemaMapper } from '@kubb/plugin-oas'
+import type { Options } from '../types.ts'
+
+export const fakerKeywordMapper = {
+  any: () => 'undefined',
+  unknown: () => 'unknown',
+  number: (min?: number, max?: number) => {
+    if (max !== undefined && min !== undefined) {
+      return `faker.number.float({ min: ${min}, max: ${max} })`
+    }
+
+    if (min !== undefined) {
+      return `faker.number.float({ min: ${min} })`
+    }
+
+    if (max !== undefined) {
+      return `faker.number.float({ max: ${max} })`
+    }
+
+    return 'faker.number.float()'
+  },
+  integer: (min?: number, max?: number) => {
+    if (max !== undefined && min !== undefined) {
+      return `faker.number.int({ min: ${min}, max: ${max} })`
+    }
+
+    if (min !== undefined) {
+      return `faker.number.int({ min: ${min} })`
+    }
+
+    if (max !== undefined) {
+      return `faker.number.int({ max: ${max} })`
+    }
+
+    return 'faker.number.int()'
+  },
+  string: (min?: number, max?: number) => {
+    if (max !== undefined && min !== undefined) {
+      return `faker.string.alpha({ length: { min: ${min}, max: ${max} } })`
+    }
+
+    if (min !== undefined) {
+      return `faker.string.alpha({ length: { min: ${min} } })`
+    }
+
+    if (max !== undefined) {
+      return `faker.string.alpha({ length: { max: ${max} } })`
+    }
+
+    return 'faker.string.alpha()'
+  },
+  boolean: () => 'faker.datatype.boolean()',
+  undefined: () => 'undefined',
+  null: () => 'null',
+  array: (items: string[] = []) => `faker.helpers.arrayElements([${items.join(', ')}]) as any`,
+  tuple: (items: string[] = []) => `faker.helpers.arrayElements([${items.join(', ')}]) as any`,
+  enum: (items: Array<string | number> = []) => `faker.helpers.arrayElement<any>([${items.join(', ')}])`,
+  union: (items: string[] = []) => `faker.helpers.arrayElement<any>([${items.join(', ')}])`,
+  /**
+   * ISO 8601
+   */
+  datetime: () => 'faker.date.anytime().toISOString()',
+  /**
+   * Type `'date'` Date
+   * Type `'string'` ISO date format (YYYY-MM-DD)
+   * @default ISO date format (YYYY-MM-DD)
+   */
+  date: (type: 'date' | 'string' = 'string', parser?: string) => {
+    if (type === 'string') {
+      if (parser) {
+        return `${parser}(faker.date.anytime()).format("YYYY-MM-DD")`
+      }
+      return 'faker.date.anytime().toString()'
+    }
+    return 'faker.date.anytime()'
+  },
+  /**
+   * Type `'date'` Date
+   * Type `'string'` ISO time format (HH:mm:ss[.SSSSSS])
+   * @default ISO time format (HH:mm:ss[.SSSSSS])
+   */
+  time: (type: 'date' | 'string' = 'string', parser?: string) => {
+    if (type === 'string') {
+      if (parser) {
+        return `${parser}(faker.date.anytime()).format("HH:mm:ss")`
+      }
+      return 'faker.date.anytime().toString()'
+    }
+    return 'faker.date.anytime()'
+  },
+  uuid: () => 'faker.string.uuid()',
+  url: () => 'faker.internet.url()',
+  and: (items: string[] = []) => `Object.assign({}, ${items.join(', ')})`,
+  object: () => 'object',
+  ref: () => 'ref',
+  matches: (value = '', regexGenerator: 'faker' | 'randexp' = 'faker') => {
+    if (regexGenerator === 'randexp') {
+      return `${transformers.toRegExpString(value, 'RandExp')}.gen()`
+    }
+    return `faker.helpers.fromRegExp(${transformers.toRegExpString(value)})`
+  },
+  email: () => 'faker.internet.email()',
+  firstName: () => 'faker.person.firstName()',
+  lastName: () => 'faker.person.lastName()',
+  password: () => 'faker.internet.password()',
+  phone: () => 'faker.phone.number()',
+  blob: () => 'faker.image.imageUrl() as unknown as Blob',
+  default: undefined,
+  describe: undefined,
+  const: (value?: string | number) => (value as string) ?? '',
+  max: undefined,
+  min: undefined,
+  nullable: undefined,
+  nullish: undefined,
+  optional: undefined,
+  readOnly: undefined,
+  strict: undefined,
+  deprecated: undefined,
+  example: undefined,
+  schema: undefined,
+  catchall: undefined,
+  name: undefined,
+} satisfies SchemaMapper<string | null | undefined>
+
+/**
+ * @link based on https://github.com/cellular/oazapfts/blob/7ba226ebb15374e8483cc53e7532f1663179a22c/src/codegen/generate.ts#L398
+ */
+
+function schemaKeywordsorter(a: Schema, b: Schema) {
+  if (b.keyword === 'null') {
+    return -1
+  }
+
+  return 0
+}
+
+export function joinItems(items: string[]): string {
+  switch (items.length) {
+    case 0:
+      return 'undefined'
+    case 1:
+      return items[0]!
+    default:
+      return fakerKeywordMapper.union(items)
+  }
+}
+
+type ParserOptions = {
+  name: string
+  typeName?: string
+  description?: string
+
+  seed?: number | number[]
+  regexGenerator?: 'faker' | 'randexp'
+  withData?: boolean
+  dateParser?: Options['dateParser']
+  mapper?: Record<string, string>
+}
+
+export function parse(parent: Schema | undefined, current: Schema, options: ParserOptions): string | null | undefined {
+  const value = fakerKeywordMapper[current.keyword as keyof typeof fakerKeywordMapper]
+
+  if (!value) {
+    return undefined
+  }
+
+  if (isKeyword(current, schemaKeywords.union)) {
+    return fakerKeywordMapper.union(current.args.map((schema) => parse(current, schema, { ...options, withData: false })).filter(Boolean))
+  }
+
+  if (isKeyword(current, schemaKeywords.and)) {
+    return fakerKeywordMapper.and(current.args.map((schema) => parse(current, schema, { ...options, withData: false })).filter(Boolean))
+  }
+
+  if (isKeyword(current, schemaKeywords.array)) {
+    return fakerKeywordMapper.array(current.args.items.map((schema) => parse(current, schema, { ...options, withData: false })).filter(Boolean))
+  }
+
+  if (isKeyword(current, schemaKeywords.enum)) {
+    return fakerKeywordMapper.enum(
+      current.args.items.map((schema) => {
+        if (schema.format === 'number') {
+          return schema.name
+        }
+        return transformers.stringify(schema.name)
+      }),
+    )
+  }
+
+  if (isKeyword(current, schemaKeywords.ref)) {
+    if (!current.args?.name) {
+      throw new Error(`Name not defined for keyword ${current.keyword}`)
+    }
+
+    if (options.withData) {
+      return `${current.args.name}(data)`
+    }
+
+    return `${current.args.name}()`
+  }
+
+  if (isKeyword(current, schemaKeywords.object)) {
+    const argsObject = Object.entries(current.args?.properties || {})
+      .filter((item) => {
+        const schema = item[1]
+        return schema && typeof schema.map === 'function'
+      })
+      .map(([name, schemas]) => {
+        const nameSchema = schemas.find((schema) => schema.keyword === schemaKeywords.name) as SchemaKeywordMapper['name']
+        const mappedName = nameSchema?.args || name
+
+        // custom mapper(pluginOptions)
+        if (options.mapper?.[mappedName]) {
+          return `"${name}": ${options.mapper?.[mappedName]}`
+        }
+
+        return `"${name}": ${joinItems(
+          schemas
+            .sort(schemaKeywordsorter)
+            .map((schema) => parse(current, schema, { ...options, withData: false }))
+            .filter(Boolean),
+        )}`
+      })
+      .join(',')
+
+    return `{${argsObject}}`
+  }
+
+  if (isKeyword(current, schemaKeywords.tuple)) {
+    if (Array.isArray(current.args.items)) {
+      return fakerKeywordMapper.tuple(current.args.items.map((schema) => parse(current, schema, { ...options, withData: false })).filter(Boolean))
+    }
+
+    return parse(current, current.args.items, { ...options, withData: false })
+  }
+
+  if (isKeyword(current, schemaKeywords.const)) {
+    if (current.args.format === 'number' && current.args.name !== undefined) {
+      return fakerKeywordMapper.const(current.args.name?.toString())
+    }
+    return fakerKeywordMapper.const(transformers.stringify(current.args.value))
+  }
+
+  if (isKeyword(current, schemaKeywords.matches) && current.args) {
+    return fakerKeywordMapper.matches(current.args, options.regexGenerator)
+  }
+
+  if (isKeyword(current, schemaKeywords.null) || isKeyword(current, schemaKeywords.undefined) || isKeyword(current, schemaKeywords.any)) {
+    return value() || ''
+  }
+
+  if (isKeyword(current, schemaKeywords.string)) {
+    if (parent) {
+      const minSchema = SchemaGenerator.find([parent], schemaKeywords.min)
+      const maxSchema = SchemaGenerator.find([parent], schemaKeywords.max)
+
+      return fakerKeywordMapper.string(minSchema?.args, maxSchema?.args)
+    }
+
+    return fakerKeywordMapper.string()
+  }
+
+  if (isKeyword(current, schemaKeywords.number)) {
+    if (parent) {
+      const minSchema = SchemaGenerator.find([parent], schemaKeywords.min)
+      const maxSchema = SchemaGenerator.find([parent], schemaKeywords.max)
+
+      return fakerKeywordMapper.number(minSchema?.args, maxSchema?.args)
+    }
+
+    return fakerKeywordMapper.number()
+  }
+
+  if (isKeyword(current, schemaKeywords.integer)) {
+    if (parent) {
+      const minSchema = SchemaGenerator.find([parent], schemaKeywords.min)
+      const maxSchema = SchemaGenerator.find([parent], schemaKeywords.max)
+
+      return fakerKeywordMapper.integer(minSchema?.args, maxSchema?.args)
+    }
+
+    return fakerKeywordMapper.integer()
+  }
+
+  if (isKeyword(current, schemaKeywords.datetime)) {
+    return fakerKeywordMapper.datetime()
+  }
+
+  if (isKeyword(current, schemaKeywords.date)) {
+    return fakerKeywordMapper.date(current.args.type, options.dateParser)
+  }
+
+  if (isKeyword(current, schemaKeywords.time)) {
+    return fakerKeywordMapper.time(current.args.type, options.dateParser)
+  }
+
+  if (current.keyword in fakerKeywordMapper && 'args' in current) {
+    const value = fakerKeywordMapper[current.keyword as keyof typeof fakerKeywordMapper] as (typeof fakerKeywordMapper)['const']
+
+    const options = JSON.stringify((current as SchemaKeywordBase<unknown>).args)
+
+    return value(options)
+  }
+
+  if (current.keyword in fakerKeywordMapper) {
+    return value()
+  }
+
+  return undefined
+}

package/src/plugin.ts

@@ -0,0 +1,153 @@
+import path from 'node:path'
+
+import { FileManager, PluginManager, createPlugin } from '@kubb/core'
+import { camelCase } from '@kubb/core/transformers'
+import { renderTemplate } from '@kubb/core/utils'
+import { pluginOasName } from '@kubb/plugin-oas'
+import { getGroupedByTagFiles } from '@kubb/plugin-oas/utils'
+import { pluginTsName } from '@kubb/plugin-ts'
+
+import { OperationGenerator } from './OperationGenerator.tsx'
+import { SchemaGenerator } from './SchemaGenerator.tsx'
+
+import type { Plugin } from '@kubb/core'
+import type { PluginOas } from '@kubb/plugin-oas'
+import type { PluginFaker } from './types.ts'
+
+export const pluginFakerName = 'plugin-faker' satisfies PluginFaker['name']
+
+export const pluginFaker = createPlugin<PluginFaker>((options) => {
+  const {
+    output = { path: 'mocks' },
+    seed,
+    group,
+    exclude = [],
+    include,
+    override = [],
+    transformers = {},
+    mapper = {},
+    dateType = 'string',
+    unknownType = 'any',
+    dateParser,
+    regexGenerator = 'faker',
+  } = options
+  const template = group?.output ? group.output : `${output.path}/{{tag}}Controller`
+
+  return {
+    name: pluginFakerName,
+    options: {
+      extName: output.extName,
+      transformers,
+      dateType,
+      seed,
+      unknownType,
+      dateParser,
+      mapper,
+      override,
+      regexGenerator,
+    },
+    pre: [pluginOasName, pluginTsName],
+    resolvePath(baseName, pathMode, options) {
+      const root = path.resolve(this.config.root, this.config.output.path)
+      const mode = pathMode ?? FileManager.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 (options?.tag && group?.type === 'tag') {
+        const tag = camelCase(options.tag)
+
+        return path.resolve(root, renderTemplate(template, { 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 writeFile(path, source) {
+      if (!path.endsWith('.ts') || !source) {
+        return
+      }
+
+      return this.fileManager.write(path, source, { sanity: false })
+    },
+    async buildStart() {
+      const [swaggerPlugin]: [Plugin<PluginOas>] = PluginManager.getDependedPlugins<PluginOas>(this.plugins, [pluginOasName])
+
+      const oas = await swaggerPlugin.api.getOas()
+      const root = path.resolve(this.config.root, this.config.output.path)
+      const mode = FileManager.getMode(path.resolve(root, output.path))
+
+      const schemaGenerator = new SchemaGenerator(this.plugin.options, {
+        oas,
+        pluginManager: this.pluginManager,
+        plugin: this.plugin,
+        contentType: swaggerPlugin.api.contentType,
+        include: undefined,
+        override,
+        mode,
+        output: output.path,
+      })
+
+      const schemaFiles = await schemaGenerator.build()
+      await this.addFile(...schemaFiles)
+
+      const operationGenerator = new OperationGenerator(this.plugin.options, {
+        oas,
+        pluginManager: this.pluginManager,
+        plugin: this.plugin,
+        contentType: swaggerPlugin.api.contentType,
+        exclude,
+        include,
+        override,
+        mode,
+      })
+
+      const operationFiles = await operationGenerator.build()
+      await this.addFile(...operationFiles)
+    },
+    async buildEnd() {
+      if (this.config.output.write === false) {
+        return
+      }
+
+      const root = path.resolve(this.config.root, this.config.output.path)
+
+      if (group?.type === 'tag') {
+        const rootFiles = await getGroupedByTagFiles({
+          logger: this.logger,
+          files: this.fileManager.files,
+          plugin: this.plugin,
+          template,
+          exportAs: group.exportAs || '{{tag}}Mocks',
+          root,
+          output,
+        })
+
+        await this.addFile(...rootFiles)
+      }
+
+      await this.fileManager.addIndexes({
+        root,
+        output,
+        meta: { pluginKey: this.plugin.key },
+        logger: this.logger,
+      })
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,136 @@
+import type { Plugin, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type * as KubbFile from '@kubb/fs/types'
+
+import type { SchemaObject } from '@kubb/oas'
+import type { Exclude, Include, Override, ResolvePathOptions, Schema } from '@kubb/plugin-oas'
+
+export type Options = {
+  output?: {
+    /**
+     * Relative path to save the Faker mocks.
+     * When output is a file it will save all models inside that file else it will create a file per schema item.
+     * @default 'mocks'
+     */
+    path: string
+    /**
+     * Name to be used for the `export * as {{exportAs}} from './'`
+     */
+    exportAs?: string
+    /**
+     * Add an extension to the generated imports and exports, default it will not use an extension
+     */
+    extName?: KubbFile.Extname
+    /**
+     * Define what needs to exported, here you can also disable the export of barrel files
+     * @default `'barrel'`
+     */
+    exportType?: 'barrel' | 'barrelNamed' | false
+  }
+
+  /**
+   * Group the Faker mocks based on the provided name.
+   */
+  group?: {
+    /**
+     * Tag will group based on the operation tag inside the Swagger file
+     */
+    type: 'tag'
+    /**
+     * Relative path to save the grouped Faker mocks.
+     *
+     * `{{tag}}` will be replaced by the current tagName.
+     * @example `${output}/{{tag}}Controller` => `mocks/PetController`
+     * @default `${output}/{{tag}}Controller`
+     */
+    output?: string
+    /**
+     * Name to be used for the `export * as {{exportAs}} from './`
+     * @default `"{{tag}}Mocks"`
+     */
+    exportAs?: string
+  }
+  /**
+   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   */
+  exclude?: Array<Exclude>
+  /**
+   * Array containing include parameters to include tags/operations/methods/paths.
+   */
+  include?: Array<Include>
+  /**
+   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   */
+  override?: Array<Override<ResolvedOptions>>
+  /**
+   * Choose to use `date` or `datetime` as JavaScript `Date` instead of `string`.
+   * @default 'string'
+   */
+  dateType?: 'string' | 'date'
+  /**
+   * Which parser should be used when dateType is set to 'string'.
+   * - Schema with format 'date' will use ISO date format (YYYY-MM-DD)
+   *   - `'dayjs'` will use `dayjs(faker.date.anytime()).format("YYYY-MM-DD")`.
+   *   - `undefined` will use `faker.date.anytime().toString()`
+   * - Schema with format 'time' will use ISO time format (HH:mm:ss[.SSSSSS])
+   *   - `'dayjs'` will use `dayjs(faker.date.anytime()).format("HH:mm:ss")`.
+   *   - `undefined` will use `faker.date.anytime().toString()`
+   * * @default undefined
+   */
+  dateParser?: 'dayjs' | 'moment' | (string & {})
+  /**
+   * Which type to use when the Swagger/OpenAPI file is not providing more information
+   * @default 'any'
+   */
+  unknownType?: 'any' | 'unknown'
+  transformers?: {
+    /**
+     * Customize the names based on the type that is provided by the plugin.
+     */
+    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
+    /**
+     * Receive schema and baseName(propertName) and return FakerMeta array
+     * TODO TODO add docs
+     * @beta
+     */
+    schema?: (props: { schema?: SchemaObject; name?: string; parentName?: string }, defaultSchemas: Schema[]) => Schema[] | undefined
+  }
+  /**
+   * Choose which generator to use when using Regexp.
+   *
+   * `'faker'` will use `faker.helpers.fromRegExp(new RegExp(/test/))`
+   * `'randexp'` will use `new RandExp(/test/).gen()`
+   * @default 'faker'
+   */
+  regexGenerator?: 'faker' | 'randexp'
+
+  mapper?: Record<string, string>
+  /**
+   * The use of Seed is intended to allow for consistent values in a test.
+   */
+  seed?: number | number[]
+}
+
+type ResolvedOptions = {
+  extName: KubbFile.Extname | undefined
+  dateType: NonNullable<Options['dateType']>
+  dateParser: Options['dateParser']
+  unknownType: NonNullable<Options['unknownType']>
+  transformers: NonNullable<Options['transformers']>
+  override: NonNullable<Options['override']>
+  seed: NonNullable<Options['seed']> | undefined
+  mapper: NonNullable<Options['mapper']>
+  regexGenerator: NonNullable<Options['regexGenerator']>
+}
+
+export type FileMeta = {
+  pluginKey?: Plugin['key']
+  tag?: string
+}
+
+export type PluginFaker = PluginFactoryOptions<'plugin-faker', Options, ResolvedOptions, never, ResolvePathOptions>
+
+declare module '@kubb/core' {
+  export interface _Register {
+    ['@kubb/plugin-faker']: PluginFaker
+  }
+}