@kubb/core 2.0.0-canary.20231030T124958 → 2.0.1

package/src/transformers/escape.ts

@@ -0,0 +1,31 @@
+export function escape(text?: string): string {
+  return text ? text.replaceAll('`', '\\`') : ''
+}
+
+/**
+ * Escape all characters not included in SingleStringCharacters and DoubleStringCharacters on
+ * @link http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4
+ * @link https://github.com/joliss/js-string-escape/blob/master/index.js
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export function jsStringEscape(input: any): string {
+  return `${input}`.replace(/["'\\\n\r\u2028\u2029]/g, (character) => {
+    switch (character) {
+      case '"':
+      case "'":
+      case '\\':
+        return '\\' + character
+      // Four possible LineTerminator characters need to be escaped:
+      case '\n':
+        return '\\n'
+      case '\r':
+        return '\\r'
+      case '\u2028':
+        return '\\u2028'
+      case '\u2029':
+        return '\\u2029'
+      default:
+        return ''
+    }
+  })
+}

package/src/transformers/indent.ts

@@ -0,0 +1,3 @@
+export function createIndent(size: number): string {
+  return Array.from({ length: size + 1 }).join(' ')
+}

package/src/transformers/index.ts

@@ -0,0 +1,36 @@
+import { camelCase, pascalCase } from './casing.ts'
+import { combineCodes } from './combineCodes.ts'
+import { createJSDocBlockText } from './createJSDocBlockText.ts'
+import { escape, jsStringEscape } from './escape.ts'
+import { createIndent } from './indent.ts'
+import { nameSorter } from './nameSorter.ts'
+import { searchAndReplace } from './searchAndReplace.ts'
+import { transformReservedWord } from './transformReservedWord.ts'
+import { trim, trimExtName } from './trim.ts'
+
+export { camelCase, pascalCase } from './casing.ts'
+export { combineCodes } from './combineCodes.ts'
+export { createJSDocBlockText } from './createJSDocBlockText.ts'
+export { escape, jsStringEscape } from './escape.ts'
+export { createIndent } from './indent.ts'
+export { nameSorter } from './nameSorter.ts'
+export { searchAndReplace } from './searchAndReplace.ts'
+export { transformReservedWord } from './transformReservedWord.ts'
+export { trim, trimExtName } from './trim.ts'
+
+export default {
+  combineCodes,
+  escape,
+  jsStringEscape,
+  createIndent,
+  transformReservedWord,
+  nameSorter,
+  searchAndReplace,
+  trim,
+  trimExtName,
+  JSDoc: {
+    createJSDocBlockText,
+  },
+  camelCase,
+  pascalCase,
+} as const

package/src/transformers/nameSorter.ts

@@ -0,0 +1,9 @@
+export function nameSorter<T extends { name: string }>(a: T, b: T): 0 | 1 | -1 {
+  if (a.name < b.name) {
+    return -1
+  }
+  if (a.name > b.name) {
+    return 1
+  }
+  return 0
+}

package/src/transformers/searchAndReplace.ts

@@ -0,0 +1,25 @@
+type Options = {
+  text: string
+  replaceBy: string
+  prefix?: string
+  key: string
+  searchValues?: (prefix: string, key: string) => Array<RegExp | string>
+}
+
+export function searchAndReplace(options: Options): string {
+  const { text, replaceBy, prefix = '', key } = options
+
+  const searchValues = options.searchValues?.(prefix, key) || [
+    `${prefix}["${key}"]`,
+    `${prefix}['${key}']`,
+    `${prefix}[\`${key}\`]`,
+    `${prefix}"${key}"`,
+    `${prefix}'${key}'`,
+    `${prefix}\`${key}\``,
+    new RegExp(`${prefix}${key}`, 'g'),
+  ]
+
+  return searchValues.reduce((prev, searchValue) => {
+    return prev.toString().replaceAll(searchValue, replaceBy)
+  }, text) as string
+}

package/src/transformers/transformReservedWord.ts

@@ -0,0 +1,97 @@
+/**
+ * @link https://github.com/jonschlinkert/reserved/blob/master/index.js
+ */
+const reservedWords = [
+  'abstract',
+  'arguments',
+  'boolean',
+  'break',
+  'byte',
+  'case',
+  'catch',
+  'char',
+  'class',
+  'const',
+  'continue',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'double',
+  'else',
+  'enum',
+  'eval',
+  'export',
+  'extends',
+  'false',
+  'final',
+  'finally',
+  'float',
+  'for',
+  'function',
+  'goto',
+  'if',
+  'implements',
+  'import',
+  'in',
+  'instanceof',
+  'int',
+  'interface',
+  'let',
+  'long',
+  'native',
+  'new',
+  'null',
+  'package',
+  'private',
+  'protected',
+  'public',
+  'return',
+  'short',
+  'static',
+  'super',
+  'switch',
+  'synchronized',
+  'this',
+  'throw',
+  'throws',
+  'transient',
+  'true',
+  'try',
+  'typeof',
+  'var',
+  'void',
+  'volatile',
+  'while',
+  'with',
+  'yield',
+
+  'Array',
+  'Date',
+  'eval',
+  'function',
+  'hasOwnProperty',
+  'Infinity',
+  'isFinite',
+  'isNaN',
+  'isPrototypeOf',
+  'length',
+  'Math',
+  'name',
+  'NaN',
+  'Number',
+  'Object',
+  'prototype',
+  'String',
+  'toString',
+  'undefined',
+  'valueOf',
+]
+
+export function transformReservedWord(word: string): string {
+  if ((word && reservedWords.includes(word)) || word?.match(/^\d/)) {
+    return `_${word}`
+  }
+
+  return word
+}

package/src/transformers/trim.ts

@@ -0,0 +1,7 @@
+export function trim(text: string): string {
+  return text.replaceAll(/\n/g, '').trim()
+}
+
+export function trimExtName(text: string): string {
+  return text.replace(/\.[^/.]+$/, '')
+}

package/src/types.ts

@@ -0,0 +1,334 @@
+import type { PossiblePromise } from '@kubb/types'
+import type { FileManager, KubbFile } from './FileManager.ts'
+import type { OptionsPlugins, PluginUnion } from './index.ts'
+import type { Logger, LogLevel } from './logger.ts'
+import type { PluginManager } from './PluginManager.ts'
+import type { Cache } from './utils/cache.ts'
+
+// config
+
+/**
+ * Config used in `kubb.config.js`
+ *
+ * @example import { defineConfig } from '@kubb/core'
+ * export default defineConfig({
+ * ...
+ * })
+ */
+export type KubbUserConfig =
+  & Omit<KubbConfig, 'root' | 'plugins'>
+  & {
+    /**
+     * Project root directory. Can be an absolute path, or a path relative from
+     * the location of the config file itself.
+     * @default process.cwd()
+     */
+    root?: string
+    /**
+     * Plugin type can be KubbJSONPlugin or KubbPlugin
+     * Example: ['@kubb/swagger', { output: false }]
+     * Or: createSwagger({ output: false })
+     */
+    plugins?: Array<Omit<UnknownKubbUserPlugin, 'api'> | KubbUnionPlugins | [name: string, options: object]>
+  }
+
+export type InputPath = {
+  /**
+   * Path to be used as the input. This can be an absolute path or a path relative to the `root`.
+   */
+  path: string
+}
+
+export type InputData = {
+  /**
+   * `string` or `object` containing the data.
+   */
+  data: string | unknown
+}
+
+type Input = InputPath | InputData
+
+/**
+ * @private
+ */
+export type KubbConfig<TInput = Input> = {
+  /**
+   * Optional config name to show in CLI output
+   */
+  name?: string
+  /**
+   * Project root directory. Can be an absolute path, or a path relative from
+   * the location of the config file itself.
+   * @default process.cwd()
+   */
+  root: string
+  input: TInput
+  output: {
+    /**
+     * Path to be used to export all generated files.
+     * This can be an absolute path, or a path relative based of the defined `root` option.
+     */
+    path: string
+    /**
+     * Clean output directory before each build.
+     */
+    clean?: boolean
+    /**
+     * Write files to the fileSystem
+     * This is being used for the playground.
+     * @default true
+     */
+    write?: boolean
+  }
+  /**
+   * Array of Kubb plugins to use.
+   * The plugin/package can forsee some options that you need to pass through.
+   * Sometimes a plugin is depended on another plugin, if that's the case you will get an error back from the plugin you installed.
+   */
+  plugins?: Array<KubbPlugin>
+  /**
+   * Hooks that will be called when a specific action is triggered in Kubb.
+   */
+  hooks?: {
+    /**
+     * Hook that will be triggered at the end of all executions.
+     * Useful for running Prettier or ESLint to format/lint your code.
+     */
+    done?: string | Array<string>
+  }
+}
+
+export type CLIOptions = {
+  /**
+   * Path to `kubb.config.js`
+   */
+  config?: string
+  /**
+   * Watch changes on input
+   */
+  watch?: string
+
+  /**
+   * Log level to report when using the CLI
+   *
+   * `silent` will hide all information that is not relevant
+   *
+   * `info` will show all information possible(not related to the PluginManager)
+   *
+   * `debug` will show all information possible(related to the PluginManager), handy for seeing logs
+   * @default `silent`
+   */
+  logLevel?: LogLevel
+}
+
+// plugin
+
+export type KubbUnionPlugins = PluginUnion
+
+export type KubbObjectPlugin = keyof OptionsPlugins
+
+export type PluginFactoryOptions<
+  /**
+   * Name to be used for the plugin, this will also be used for they key.
+   */
+  TName extends string = string,
+  /**
+   * Options of the plugin.
+   */
+  TOptions extends object = object,
+  /**
+   * Options of the plugin that can be used later on, see `options` inside your plugin config.
+   */
+  TResolvedOptions extends object = TOptions,
+  /**
+   * API that you want to expose to other plugins.
+   */
+  TAPI = any,
+  /**
+   * When calling `resolvePath` you can specify better types.
+   */
+  TResolvePathOptions extends object = object,
+  /**
+   * When using @kubb/react(based on React) you can specify here which types should be used when calling render.
+   * Always extend from `AppMeta` of the core.
+   */
+  TAppMeta = unknown,
+> = {
+  name: TName
+  /**
+   * Same behaviour like what has been done with `QueryKey` in `@tanstack/react-query`
+   */
+  key: [name: TName | string, identifier?: string | number]
+  options: TOptions
+  resolvedOptions: TResolvedOptions
+  api: TAPI
+  resolvePathOptions: TResolvePathOptions
+  appMeta: {
+    pluginManager: PluginManager
+    plugin: KubbPlugin<PluginFactoryOptions<TName, TOptions, TResolvedOptions, TAPI, TResolvePathOptions, TAppMeta>>
+  } & TAppMeta
+}
+
+export type GetPluginFactoryOptions<TPlugin extends KubbUserPlugin> = TPlugin extends KubbUserPlugin<infer X> ? X : never
+
+export type KubbUserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> =
+  & {
+    /**
+     * Unique name used for the plugin
+     * The name of the plugin follows the format scope:foo-bar or foo-bar, adding scope: can avoid naming conflicts with other plugins.
+     * @example @kubb/typescript
+     */
+    name: TOptions['name']
+    /**
+     * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+     */
+    options: TOptions['resolvedOptions']
+    /**
+     * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin will be executed after these plugins.
+     * Can be used to validate depended plugins.
+     */
+    pre?: Array<string>
+    /**
+     * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin will be executed before these plugins.
+     */
+    post?: Array<string>
+  }
+  & (TOptions['api'] extends never ? {
+      api?: never
+    }
+    : {
+      api: (this: TOptions['name'] extends 'core' ? null : Omit<PluginContext<TOptions>, 'addFile'>) => TOptions['api']
+    })
+
+export type KubbUserPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = KubbUserPlugin<TOptions> & PluginLifecycle<TOptions>
+
+type UnknownKubbUserPlugin = KubbUserPlugin<PluginFactoryOptions<any, any, any, any, any, any>>
+
+export type KubbPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> =
+  & {
+    /**
+     * Unique name used for the plugin
+     * @example @kubb/typescript
+     */
+    name: TOptions['name']
+    /**
+     * Internal key used when a developer uses more than one of the same plugin
+     * @private
+     */
+    key: TOptions['key']
+    /**
+     * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin will be executed after these plugins.
+     * Can be used to validate depended plugins.
+     */
+    pre?: Array<string>
+    /**
+     * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin will be executed before these plugins.
+     */
+    post?: Array<string>
+    /**
+     * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+     */
+    options: TOptions['resolvedOptions']
+    /**
+     * Define an api that can be used by other plugins, see `PluginManager' where we convert from `KubbUserPlugin` to `KubbPlugin`(used when calling `createPlugin`).
+     */
+  }
+  & (TOptions['api'] extends never ? {
+      api?: never
+    }
+    : {
+      api: TOptions['api']
+    })
+
+export type KubbPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = KubbPlugin<TOptions> & PluginLifecycle<TOptions>
+
+export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Start of the lifecycle of a plugin.
+   * @type hookParallel
+   */
+  buildStart?: (this: PluginContext<TOptions>, kubbConfig: KubbConfig) => PossiblePromise<void>
+  /**
+   * Resolve to a Path based on a baseName(example: `./Pet.ts`) and directory(example: `./models`).
+   * Options can als be included.
+   * @type hookFirst
+   * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
+   */
+  resolvePath?: (this: PluginContext<TOptions>, baseName: string, directory?: string, options?: TOptions['resolvePathOptions']) => KubbFile.OptionalPath
+  /**
+   * Resolve to a name based on a string.
+   * Useful when converting to PascalCase or camelCase.
+   * @type hookFirst
+   * @example ('pet') => 'Pet'
+   */
+  resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
+  /**
+   * Makes it possible to run async logic to override the path defined previously by `resolvePath`.
+   * @type hookFirst
+   */
+  load?: (this: Omit<PluginContext<TOptions>, 'addFile'>, path: KubbFile.Path) => PossiblePromise<TransformResult | null>
+  /**
+   * Transform the source-code.
+   * @type hookReduceArg0
+   */
+  transform?: (this: Omit<PluginContext<TOptions>, 'addFile'>, source: string, path: KubbFile.Path) => PossiblePromise<TransformResult>
+  /**
+   * Write the result to the file-system based on the id(defined by `resolvePath` or changed by `load`).
+   * @type hookParallel
+   */
+  writeFile?: (this: Omit<PluginContext<TOptions>, 'addFile'>, source: string | undefined, path: KubbFile.Path) => PossiblePromise<string | void>
+  /**
+   * End of the plugin lifecycle.
+   * @type hookParallel
+   */
+  buildEnd?: (this: PluginContext<TOptions>) => PossiblePromise<void>
+}
+
+export type PluginLifecycleHooks = keyof PluginLifecycle
+
+export type PluginParameter<H extends PluginLifecycleHooks> = Parameters<Required<PluginLifecycle>[H]>
+
+export type PluginCache = Record<string, [number, unknown]>
+
+export type ResolvePathParams<TOptions = object> = {
+  pluginKey?: KubbPlugin['key']
+  baseName: string
+  directory?: string | undefined
+  /**
+   * Options to be passed to 'resolvePath' 3th parameter
+   */
+  options?: TOptions
+}
+
+export type ResolveNameParams = {
+  name: string
+  pluginKey?: KubbPlugin['key']
+  /**
+   * `file` will be used to customize the name of the created file(use of camelCase)
+   * `function` can be used used to customize the exported functions(use of camelCase)
+   * `type` is a special type for TypeScript(use of PascalCase)
+   */
+  type?: 'file' | 'function' | 'type'
+}
+
+export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: KubbConfig
+  cache: Cache<PluginCache>
+  fileManager: FileManager
+  pluginManager: PluginManager
+  addFile: (...file: Array<KubbFile.File>) => Promise<Array<KubbFile.File>>
+  resolvePath: (params: ResolvePathParams<TOptions['resolvePathOptions']>) => KubbFile.OptionalPath
+  resolveName: (params: ResolveNameParams) => string
+  logger: Logger
+  /**
+   * All plugins
+   */
+  plugins: KubbPlugin[]
+  /**
+   * Current plugin
+   */
+  plugin: KubbPlugin<TOptions>
+}
+
+// null will mean clear the watcher for this key
+export type TransformResult = string | null

package/src/utils/EventEmitter.ts

@@ -0,0 +1,24 @@
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+import { EventEmitter as NodeEventEmitter } from 'node:events'
+
+export class EventEmitter<TEvents extends Record<string, any>> {
+  constructor() {
+    this.#emitter.setMaxListeners(100)
+  }
+  #emitter = new NodeEventEmitter()
+
+  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArg: TEvents[TEventName]): void {
+    this.#emitter.emit(eventName, ...(eventArg as []))
+  }
+
+  on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void {
+    this.#emitter.on(eventName, handler as any)
+  }
+
+  off<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void {
+    this.#emitter.off(eventName, handler as any)
+  }
+  removeAll(): void {
+    this.#emitter.removeAllListeners()
+  }
+}

package/src/utils/FunctionParams.ts

@@ -0,0 +1,86 @@
+import { orderBy } from 'natural-orderby'
+
+import { camelCase } from '../transformers/casing.ts'
+
+type FunctionParamsASTWithoutType = {
+  name?: string
+  type?: string
+  /**
+   * @default true
+   */
+  required?: boolean
+  /**
+   * @default true
+   */
+  enabled?: boolean
+  default?: string
+}
+
+type FunctionParamsASTWithType = {
+  name?: never
+  type: string
+  /**
+   * @default true
+   */
+  required?: boolean
+  /**
+   * @default true
+   */
+  enabled?: boolean
+  default?: string
+}
+
+export type FunctionParamsAST = FunctionParamsASTWithoutType | FunctionParamsASTWithType
+export class FunctionParams {
+  public type?: 'generics' | 'typed'
+  public items: FunctionParamsAST[] = []
+  constructor(type?: 'generics' | 'typed') {
+    this.type = type
+
+    return this
+  }
+
+  add(item: FunctionParamsAST | Array<FunctionParamsAST | undefined> | undefined): FunctionParams {
+    if (!item) {
+      return this
+    }
+
+    if (Array.isArray(item)) {
+      item.filter(Boolean).forEach((it) => this.items.push(it))
+      return this
+    }
+    this.items.push(item)
+
+    return this
+  }
+
+  toString(): string {
+    const sortedData = orderBy(this.items.filter(Boolean), [(v) => !v.default, (v) => v.required ?? true], ['desc', 'desc'])
+
+    return sortedData
+      .filter(({ enabled = true }) => enabled)
+      .reduce((acc, { name, type, required = true, ...rest }) => {
+        if (!name) {
+          // when name is not se we will use TypeScript generics
+          acc.push(`${type}${rest.default ? ` = ${rest.default}` : ''}`)
+
+          return acc
+        }
+        // TODO check whey we still need the camelcase here
+        const parameterName = name.startsWith('{') ? name : camelCase(name)
+
+        if (type) {
+          if (required) {
+            acc.push(`${parameterName}: ${type}${rest.default ? ` = ${rest.default}` : ''}`)
+          } else {
+            acc.push(`${parameterName}?: ${type}`)
+          }
+        } else {
+          acc.push(`${parameterName}`)
+        }
+
+        return acc
+      }, [] as string[])
+      .join(', ')
+  }
+}