@kubb/core 2.0.0-alpha.3 → 2.0.0-alpha.5

package/src/build.ts

@@ -0,0 +1,207 @@
+import pc from 'picocolors'
+
+import { clean } from './utils/clean.ts'
+import { createLogger, LogLevel } from './utils/logger.ts'
+import { randomPicoColour } from './utils/randomColour.ts'
+import { read } from './utils/read.ts'
+import { URLPath } from './utils/URLPath.ts'
+import { isInputPath } from './config.ts'
+import { FileManager } from './FileManager.ts'
+import { PluginManager } from './PluginManager.ts'
+import { isPromise } from './PromiseManager.ts'
+
+import type { KubbFile } from './FileManager.ts'
+import type { KubbPlugin, PluginContext, PluginParameter, TransformResult } from './types.ts'
+import type { Logger } from './utils/logger.ts'
+import type { QueueJob } from './utils/Queue.ts'
+
+type BuildOptions = {
+  config: PluginContext['config']
+  /**
+   * @default Logger without the spinner
+   */
+  logger?: Logger
+}
+
+type BuildOutput = {
+  files: FileManager['files']
+  pluginManager: PluginManager
+  /**
+   * Only for safeBuild
+   */
+  error?: Error
+}
+
+async function transformReducer(
+  this: PluginContext,
+  _previousCode: string,
+  result: TransformResult | Promise<TransformResult>,
+  _plugin: KubbPlugin,
+): Promise<string | null> {
+  return result
+}
+
+async function setup(options: BuildOptions): Promise<PluginManager> {
+  const { config, logger = createLogger({ logLevel: LogLevel.silent }) } = options
+
+  try {
+    if (isInputPath(config) && !new URLPath(config.input.path).isURL) {
+      await read(config.input.path)
+    }
+  } catch (e) {
+    if (isInputPath(config)) {
+      throw new Error(
+        'Cannot read file/URL defined in `input.path` or set with `kubb generate PATH` in the CLI of your Kubb config ' + pc.dim(config.input.path),
+        {
+          cause: e,
+        },
+      )
+    }
+  }
+
+  if (config.output.clean) {
+    await clean(config.output.path)
+  }
+
+  const queueTask = async (file: KubbFile.File) => {
+    const { path } = file
+
+    let code: string | null = FileManager.getSource(file)
+
+    const { result: loadedResult } = await pluginManager.hookFirst({
+      hookName: 'load',
+      parameters: [path],
+    })
+    if (loadedResult && isPromise(loadedResult)) {
+      code = await loadedResult
+    }
+    if (loadedResult && !isPromise(loadedResult)) {
+      code = loadedResult
+    }
+
+    if (code) {
+      const transformedCode = await pluginManager.hookReduceArg0({
+        hookName: 'transform',
+        parameters: [code, path],
+        reduce: transformReducer,
+      })
+
+      if (config.output.write || config.output.write === undefined) {
+        if (file.meta?.pluginKey) {
+          // run only for pluginKey defined in the meta of the file
+          return pluginManager.hookForPlugin({
+            pluginKey: file.meta?.pluginKey,
+            hookName: 'writeFile',
+            parameters: [transformedCode, path],
+          })
+        }
+
+        return pluginManager.hookFirst({
+          hookName: 'writeFile',
+          parameters: [transformedCode, path],
+        })
+      }
+    }
+  }
+
+  const pluginManager = new PluginManager(config, { logger, task: queueTask as QueueJob<KubbFile.ResolvedFile>, writeTimeout: 0 })
+
+  pluginManager.on('execute', (executer) => {
+    const { hookName, parameters, plugin } = executer
+
+    if (hookName === 'writeFile' && logger.spinner) {
+      const [code] = parameters as PluginParameter<'writeFile'>
+
+      if (logger.logLevel === LogLevel.info) {
+        logger.spinner.start(`💾 Writing`)
+      }
+
+      if (logger.logLevel === 'debug') {
+        logger.info(`PluginKey ${pc.dim(JSON.stringify(plugin.key))} \nwith source\n\n${code}`)
+      }
+    }
+  })
+
+  pluginManager.on('executed', (executer) => {
+    const { hookName, plugin, output, parameters } = executer
+    const messsage = `${randomPicoColour(plugin.name)} Executing ${hookName}`
+
+    if (logger.logLevel === LogLevel.info && logger.spinner) {
+      if (hookName === 'writeFile') {
+        const [_code, path] = parameters as PluginParameter<'writeFile'>
+
+        logger.spinner.suffixText = pc.dim(path)
+      } else {
+        logger.spinner.suffixText = messsage
+      }
+    }
+
+    if (logger.logLevel === LogLevel.debug) {
+      logger.info(messsage)
+      const logs = [
+        parameters && `${pc.bgWhite(`Parameters`)} ${randomPicoColour(plugin.name)} ${hookName}`,
+        JSON.stringify(parameters, undefined, 2),
+        output && `${pc.bgWhite('Output')} ${randomPicoColour(plugin.name)} ${hookName}`,
+        output,
+      ].filter(Boolean)
+
+      console.log(logs.join('\n'))
+    }
+  })
+
+  return pluginManager
+}
+
+export async function build(options: BuildOptions): Promise<BuildOutput> {
+  const pluginManager = await setup(options)
+
+  const { fileManager, logger } = pluginManager
+
+  await pluginManager.hookParallel<'validate', true>({
+    hookName: 'validate',
+    parameters: [pluginManager.plugins],
+  })
+
+  await pluginManager.hookParallel({
+    hookName: 'buildStart',
+    parameters: [options.config],
+  })
+
+  await pluginManager.hookParallel({ hookName: 'buildEnd' })
+
+  if (!fileManager.isExecuting && logger.spinner) {
+    logger.spinner.suffixText = ''
+    logger.spinner.succeed(`💾 Writing completed`)
+  }
+
+  return { files: fileManager.files.map((file) => ({ ...file, source: FileManager.getSource(file) })), pluginManager }
+}
+
+export async function safeBuild(options: BuildOptions): Promise<BuildOutput> {
+  const pluginManager = await setup(options)
+
+  const { fileManager, logger } = pluginManager
+
+  try {
+    await pluginManager.hookParallel<'validate', true>({
+      hookName: 'validate',
+      parameters: [pluginManager.plugins],
+    })
+
+    await pluginManager.hookParallel({
+      hookName: 'buildStart',
+      parameters: [options.config],
+    })
+
+    await pluginManager.hookParallel({ hookName: 'buildEnd' })
+
+    if (!fileManager.isExecuting && logger.spinner) {
+      logger.spinner.suffixText = ''
+      logger.spinner.succeed(`💾 Writing completed`)
+    }
+  } catch (e) {
+    return { files: fileManager.files.map((file) => ({ ...file, source: FileManager.getSource(file) })), pluginManager, error: e as Error }
+  }
+
+  return { files: fileManager.files.map((file) => ({ ...file, source: FileManager.getSource(file) })), pluginManager }
+}

package/src/config.ts

@@ -0,0 +1,22 @@
+import type { PossiblePromise } from '@kubb/types'
+import type { CLIOptions, InputPath, KubbConfig, KubbUserConfig } from './types.ts'
+
+/**
+ * Type helper to make it easier to use kubb.config.js
+ * accepts a direct {@link KubbConfig} object, or a function that returns it.
+ * The function receives a {@link ConfigEnv} object that exposes two properties:
+ */
+export function defineConfig(
+  options:
+    | PossiblePromise<KubbUserConfig | Array<KubbUserConfig>>
+    | ((
+      /** The options derived from the CLI flags */
+      cliOptions: CLIOptions,
+    ) => PossiblePromise<KubbUserConfig | Array<KubbUserConfig>>),
+): typeof options {
+  return options
+}
+
+export function isInputPath(result: KubbConfig | undefined): result is KubbConfig<InputPath> {
+  return !!result && 'path' in (result as any)
+}

package/src/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * Behaves as an Error to log a warning in the console(still stops the execution)
+ */
+export class Warning extends Error {
+  constructor(message?: string, options?: { cause: Error }) {
+    super(message, { cause: options?.cause })
+
+    this.name = 'Warning'
+  }
+}
+
+export class ValidationPluginError extends Error {}

package/src/index.ts

@@ -0,0 +1,28 @@
+import { build } from './build.ts'
+
+import type { ObjValueTuple, TupleToUnion } from '@kubb/types'
+
+export { build, safeBuild } from './build.ts'
+export * from './config.ts'
+export * from './errors.ts'
+export * from './FileManager.ts'
+export { Generator } from './Generator.ts'
+export { PackageManager } from './PackageManager.ts'
+// dprint-ignore
+export { createPlugin, pluginName as name, pluginName } from './plugin.ts'
+export { PluginManager } from './PluginManager.ts'
+export { PromiseManager } from './PromiseManager.ts'
+export { SchemaGenerator } from './SchemaGenerator.ts'
+export * from './types.ts'
+
+export interface _Register {}
+export type Plugins = _Register
+export type OptionsPlugins = { [K in keyof Plugins]: Plugins[K]['options'] }
+
+export type OptionsOfPlugin<K extends keyof Plugins> = Plugins[K]['options']
+
+export type PluginUnion = TupleToUnion<ObjValueTuple<OptionsPlugins>>
+
+export type Plugin = keyof Plugins
+
+export default build

package/src/plugin.ts

@@ -0,0 +1,80 @@
+import path from 'node:path'
+
+import { createPluginCache } from './utils/cache.ts'
+
+import type { FileManager } from './FileManager.ts'
+import type { PluginManager } from './PluginManager.ts'
+import type { KubbPlugin, KubbUserPluginWithLifeCycle, PluginContext, PluginFactoryOptions } from './types.ts'
+
+type KubbPluginFactory<T extends PluginFactoryOptions = PluginFactoryOptions> = (options: T['options']) => KubbUserPluginWithLifeCycle<T>
+
+export function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(factory: KubbPluginFactory<T>) {
+  return (options: T['options']): ReturnType<KubbPluginFactory<T>> => {
+    return factory(options)
+  }
+}
+
+type Options = {
+  config: PluginContext['config']
+  fileManager: FileManager
+  pluginManager: PluginManager
+  resolvePath: PluginContext['resolvePath']
+  resolveName: PluginContext['resolveName']
+  logger: PluginContext['logger']
+  getPlugins: () => KubbPlugin[]
+  plugin?: PluginContext['plugin']
+}
+
+// not publicly exported
+export type CorePluginOptions = PluginFactoryOptions<'core', 'controller', Options, Options, PluginContext, never>
+
+export const pluginName = 'core' satisfies CorePluginOptions['name']
+export const pluginKey: CorePluginOptions['key'] = ['controller', pluginName] satisfies CorePluginOptions['key']
+
+export const definePlugin = createPlugin<CorePluginOptions>((options) => {
+  const { fileManager, pluginManager, resolvePath, resolveName, logger } = options
+
+  return {
+    name: pluginName,
+    options,
+    key: ['controller', 'core'],
+    kind: 'controller',
+    api() {
+      return {
+        get config() {
+          return options.config
+        },
+        get plugins() {
+          return options.getPlugins()
+        },
+        get plugin() {
+          // see pluginManger.#execute where we override with `.call` the this with the correct plugin
+          return options.plugin as NonNullable<Options['plugin']>
+        },
+        logger,
+        fileManager,
+        pluginManager,
+        async addFile(...files) {
+          const resolvedFiles = await fileManager.add(...files)
+
+          if (!Array.isArray(resolvedFiles)) {
+            return [resolvedFiles]
+          }
+
+          return resolvedFiles
+        },
+        resolvePath,
+        resolveName,
+        cache: createPluginCache(),
+      }
+    },
+    resolvePath(baseName) {
+      const root = path.resolve(this.config.root, this.config.output.path)
+
+      return path.resolve(root, baseName)
+    },
+    resolveName(name) {
+      return name
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,346 @@
+import type { PossiblePromise } from '@kubb/types'
+import type { FileManager, KubbFile } from './FileManager.ts'
+import type { OptionsPlugins, PluginUnion } from './index.ts'
+import type { PluginManager } from './PluginManager.ts'
+import type { Cache } from './utils/cache.ts'
+import type { Logger, LogLevel } from './utils/logger.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 KubbPluginKind = 'schema' | 'controller'
+
+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,
+  /**
+   * @type "schema" | "controller"
+   */
+  TKind extends KubbPluginKind = KubbPluginKind,
+  /**
+   * 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
+  kind: TKind
+  /**
+   * Same behaviour like what has been done with `QueryKey` in `@tanstack/react-query`
+   */
+  key: [kind: TKind | undefined, name: TName | string, identifier?: string | number]
+  options: TOptions
+  resolvedOptions: TResolvedOptions
+  api: TAPI
+  resolvePathOptions: TResolvePathOptions
+  appMeta: {
+    pluginManager: PluginManager
+    plugin: KubbPlugin<PluginFactoryOptions<TName, TKind, 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
+     * @example @kubb/typescript
+     */
+    name: TOptions['name']
+    /**
+     * Internal key used when a developer uses more than one of the same plugin
+     * @private
+     */
+    key?: TOptions['key']
+    /**
+     * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+     */
+    options: TOptions['resolvedOptions']
+  }
+  & (TOptions['api'] extends never ? {
+      api?: never
+    }
+    : {
+      api: (this: TOptions['name'] extends 'core' ? null : Omit<PluginContext<TOptions>, 'addFile'>) => TOptions['api']
+    })
+  & (TOptions['kind'] extends never ? {
+      kind?: never
+    }
+    : {
+      /**
+       * Kind/type for the plugin
+       * Type 'schema' can be used for JSON schema's, TypeScript types, ...
+       * Type 'controller' can be used to create generate API calls, React-Query hooks, Axios controllers, ...
+       * @default undefined
+       */
+      kind: TOptions['kind']
+    })
+
+export type KubbUserPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = KubbUserPlugin<TOptions> & PluginLifecycle<TOptions>
+
+type UnknownKubbUserPlugin = KubbUserPlugin<PluginFactoryOptions<any, 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']
+    /**
+     * Options set for a specific plugin(see kubb.config.js), passthrough of options.
+     */
+    options: TOptions['resolvedOptions']
+    /**
+     * Kind/type for the plugin
+     * Type 'schema' can be used for JSON schema's, TypeScript types, ...
+     * Type 'controller' can be used to create generate API calls, React-Query hooks, Axios controllers, ...
+     * @default undefined
+     */
+    kind?: TOptions['kind']
+    /**
+     * 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> = {
+  /**
+   * Valdiate all plugins to see if their depended plugins are installed and configured.
+   * @type hookParallel
+   */
+  validate?: (this: Omit<PluginContext<TOptions>, 'addFile'>, plugins: NonNullable<KubbConfig['plugins']>) => PossiblePromise<true>
+  /**
+   * 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']
+  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