@kubb/core 1.0.0-alpha.6 → 1.0.0-alpha.8

package/src/managers/fileManager/TreeNode.ts

@@ -0,0 +1,111 @@
+import dirTree from 'directory-tree'
+
+import type { DirectoryTree, DirectoryTreeOptions } from 'directory-tree'
+
+export type TreeNodeOptions = DirectoryTreeOptions
+
+export class TreeNode<T = unknown> {
+  public data: T
+
+  public parent?: TreeNode<T>
+
+  public children: Array<TreeNode<T>> = []
+
+  constructor(data: T, parent?: TreeNode<T>) {
+    this.data = data
+    this.parent = parent
+    return this
+  }
+
+  addChild(data: T): TreeNode<T> {
+    const child = new TreeNode(data, this)
+    if (!this.children) {
+      this.children = []
+    }
+    this.children.push(child)
+    return child
+  }
+
+  find(data: T) {
+    if (data === this.data) {
+      return this
+    }
+
+    if (this.children) {
+      for (let i = 0, { length } = this.children, target: unknown = null; i < length; i++) {
+        target = this.children[i].find(data)
+        if (target) {
+          return target
+        }
+      }
+    }
+
+    return null
+  }
+
+  leaves(): TreeNode<T>[] {
+    if (!this.children || this.children.length === 0) {
+      // this is a leaf
+      return [this]
+    }
+
+    // if not a leaf, return all children's leaves recursively
+    const leaves: TreeNode<T>[] = []
+    if (this.children) {
+      for (let i = 0, { length } = this.children; i < length; i++) {
+        // eslint-disable-next-line prefer-spread
+        leaves.push.apply(leaves, this.children[i].leaves())
+      }
+    }
+    return leaves
+  }
+
+  root(): TreeNode<T> {
+    if (!this.parent) {
+      return this
+    }
+    return this.parent.root()
+  }
+
+  forEach(callback: (treeNode: TreeNode<T>) => void): this {
+    if (typeof callback !== 'function') {
+      throw new TypeError('forEach() callback must be a function')
+    }
+
+    // run this node through function
+    callback(this)
+
+    // do the same for all children
+    if (this.children) {
+      for (let i = 0, { length } = this.children; i < length; i++) {
+        this.children[i].forEach(callback)
+      }
+    }
+
+    return this
+  }
+
+  public static build<T = unknown>(path: string, options: TreeNodeOptions = {}): TreeNode<T> | null {
+    const filteredTree = dirTree(path, { extensions: options?.extensions, exclude: options.exclude })
+
+    if (!filteredTree) {
+      return null
+    }
+
+    const treeNode = new TreeNode({ name: filteredTree.name, path: filteredTree.path, type: filteredTree.type })
+
+    const recurse = (node: typeof treeNode, item: DirectoryTree) => {
+      const subNode = node.addChild({ name: item.name, path: item.path, type: item.type })
+
+      if (item.children?.length) {
+        item.children?.forEach((child) => {
+          recurse(subNode, child)
+        })
+      }
+    }
+
+    filteredTree.children?.forEach((child) => recurse(treeNode, child))
+
+    return treeNode as TreeNode<T>
+  }
+}

package/src/managers/fileManager/index.ts

@@ -0,0 +1,3 @@
+export * from './FileManager'
+export * from './types'
+export * from './TreeNode'

package/src/managers/fileManager/types.ts

@@ -0,0 +1,24 @@
+type Import = {
+  name: string | string[]
+  path: string
+  isTypeOnly?: boolean
+}
+
+export type File = {
+  /**
+   * Name to be used to dynamicly create the fileName(based on input.path)
+   */
+  fileName: string
+  /**
+   * Path will be full qualified path to a specified file
+   */
+  path: string
+  source: string
+  imports?: Import[]
+}
+
+export type UUID = string
+
+export type CacheStore = { id: UUID; file: File; status: Status }
+
+export type Status = 'new' | 'success' | 'removed'

package/src/managers/index.ts

@@ -0,0 +1,2 @@
+export * from './fileManager'
+export * from './pluginManager'

package/src/managers/pluginManager/PluginManager.ts

@@ -0,0 +1,249 @@
+/* eslint-disable no-await-in-loop */
+/* eslint-disable no-restricted-syntax */
+
+import { definePlugin } from '../../plugin'
+import { FileManager } from '../fileManager'
+import { Queue } from '../../utils/queue'
+
+import type { QueueTask } from '../../utils/queue'
+import type { Argument0, Strategy } from './types'
+import type { KubbConfig, KubbPlugin, PluginLifecycleHooks, PluginLifecycle, MaybePromise, ResolveIdParams } from '../../types'
+import type { Logger } from '../../build'
+import type { CorePluginOptions } from '../../plugin'
+
+// inspired by: https://github.com/rollup/rollup/blob/master/src/utils/PluginDriver.ts#
+
+// This will make sure no input hook is omitted
+const hookNames: {
+  [P in PluginLifecycleHooks]: 1
+} = {
+  validate: 1,
+  buildStart: 1,
+  resolveId: 1,
+  load: 1,
+  transform: 1,
+  writeFile: 1,
+  buildEnd: 1,
+}
+export const hooks = Object.keys(hookNames) as [PluginLifecycleHooks]
+
+export class PluginManager {
+  public plugins: KubbPlugin[]
+
+  public readonly fileManager: FileManager
+
+  private readonly logger?: Logger
+
+  private readonly config: KubbConfig
+
+  public readonly core: KubbPlugin<CorePluginOptions>
+
+  public queue: Queue
+
+  constructor(config: KubbConfig, options: { logger?: Logger; task: QueueTask }) {
+    this.logger = options.logger
+    this.config = config
+    this.queue = new Queue(10)
+
+    this.fileManager = new FileManager({ task: options.task, queue: this.queue })
+    this.core = definePlugin({
+      config,
+      fileManager: this.fileManager,
+      load: this.load,
+      resolveId: this.resolveId,
+    }) as KubbPlugin<CorePluginOptions> & {
+      api: CorePluginOptions['api']
+    }
+    this.plugins = [this.core, ...(config.plugins || [])]
+  }
+
+  resolveId = (params: ResolveIdParams) => {
+    if (params.pluginName) {
+      return this.hookForPlugin(params.pluginName, 'resolveId', [params.fileName, params.directory, params.options])
+    }
+    return this.hookFirst('resolveId', [params.fileName, params.directory, params.options])
+  }
+
+  load = async (id: string) => {
+    return this.hookFirst('load', [id])
+  }
+
+  // run only hook for a specific plugin name
+  hookForPlugin<H extends PluginLifecycleHooks>(
+    pluginName: string,
+    hookName: H,
+    parameters: Parameters<PluginLifecycle[H]>,
+    skipped?: ReadonlySet<KubbPlugin> | null
+  ): Promise<ReturnType<PluginLifecycle[H]> | null> {
+    let promise: Promise<ReturnType<PluginLifecycle[H]> | null> = Promise.resolve(null)
+    for (const plugin of this.getSortedPlugins(hookName, pluginName)) {
+      if (skipped && skipped.has(plugin)) continue
+      promise = promise.then((result) => {
+        if (result != null) return result
+        return this.run('hookFirst', hookName, parameters, plugin) as typeof result
+      })
+    }
+    return promise
+  }
+
+  // chains, first non-null result stops and returns
+  hookFirst<H extends PluginLifecycleHooks>(
+    hookName: H,
+    parameters: Parameters<PluginLifecycle[H]>,
+    skipped?: ReadonlySet<KubbPlugin> | null
+  ): Promise<ReturnType<PluginLifecycle[H]> | null> {
+    let promise: Promise<ReturnType<PluginLifecycle[H]> | null> = Promise.resolve(null)
+    for (const plugin of this.getSortedPlugins(hookName)) {
+      if (skipped && skipped.has(plugin)) continue
+      promise = promise.then((result) => {
+        if (result != null) return result
+        return this.run('hookFirst', hookName, parameters, plugin) as typeof result
+      })
+    }
+    return promise
+  }
+
+  // parallel
+  async hookParallel<H extends PluginLifecycleHooks, TOuput = void>(hookName: H, parameters?: Parameters<PluginLifecycle[H]> | undefined) {
+    const parallelPromises: Promise<TOuput>[] = []
+
+    for (const plugin of this.getSortedPlugins(hookName)) {
+      if ((plugin[hookName] as { sequential?: boolean })?.sequential) {
+        await Promise.all(parallelPromises)
+        parallelPromises.length = 0
+        await this.run('hookParallel', hookName, parameters, plugin)
+      } else {
+        const promise: Promise<TOuput> = this.run('hookParallel', hookName, parameters, plugin)
+
+        parallelPromises.push(promise)
+      }
+    }
+    return Promise.all(parallelPromises)
+  }
+
+  // chains, reduces returned value, handling the reduced value as the first hook argument
+  hookReduceArg0<H extends PluginLifecycleHooks>(
+    hookName: H,
+    [argument0, ...rest]: Parameters<PluginLifecycle[H]>,
+    reduce: (reduction: Argument0<H>, result: ReturnType<PluginLifecycle[H]>, plugin: KubbPlugin) => MaybePromise<Argument0<H> | null>
+  ): Promise<Argument0<H>> {
+    let promise: Promise<Argument0<H>> = Promise.resolve(argument0)
+    for (const plugin of this.getSortedPlugins(hookName)) {
+      promise = promise.then((argument0) =>
+        this.run('hookReduceArg0', hookName, [argument0, ...rest] as Parameters<PluginLifecycle[H]>, plugin).then((result) =>
+          reduce.call(this.core.api, argument0, result as ReturnType<PluginLifecycle[H]>, plugin)
+        )
+      ) as Promise<Argument0<H>>
+    }
+    return promise
+  }
+
+  // chains
+
+  hookSeq<H extends PluginLifecycleHooks>(hookName: H, parameters?: Parameters<PluginLifecycle[H]>) {
+    let promise: Promise<void> = Promise.resolve()
+    for (const plugin of this.getSortedPlugins(hookName)) {
+      promise = promise.then(() => this.run('hookSeq', hookName, parameters, plugin))
+    }
+    return promise.then(noReturn)
+  }
+
+  private getSortedPlugins(hookName: keyof PluginLifecycle, pluginName?: string): KubbPlugin[] {
+    const plugins = [...this.plugins]
+
+    if (pluginName) {
+      const pluginsByPluginName = plugins.filter((item) => item.name === pluginName && item[hookName])
+      if (pluginsByPluginName.length === 0) {
+        // fallback on the core plugin when there is no match
+        if (this.config.logLevel === 'warn' && this.logger?.spinner) {
+          this.logger.spinner.info(`Plugin hook with ${hookName} not found for plugin ${pluginName}`)
+        }
+        return [this.core]
+      }
+      return pluginsByPluginName
+    }
+
+    return plugins
+  }
+
+  /**
+   * Run an async plugin hook and return the result.
+   * @param hookName Name of the plugin hook. Must be either in `PluginHooks` or `OutputPluginValueHooks`.
+   * @param args Arguments passed to the plugin hook.
+   * @param plugin The actual pluginObject to run.
+   */
+  // Implementation signature
+  private run<H extends PluginLifecycleHooks, TResult = void>(
+    strategy: Strategy,
+    hookName: H,
+    parameters: unknown[] | undefined,
+    plugin: KubbPlugin
+  ): Promise<TResult> {
+    const hook = plugin[hookName]!
+
+    return Promise.resolve()
+      .then(() => {
+        if (typeof hook !== 'function') {
+          return hook
+        }
+
+        if (this.config.logLevel === 'info' && this.logger?.spinner) {
+          this.logger.spinner.text = `[${strategy}] ${hookName}: Excecuting task for plugin ${plugin.name} \n`
+        }
+
+        const hookResult = (hook as Function).apply(this.core.api, parameters)
+
+        if (!(hookResult as Promise<unknown>)?.then) {
+          // short circuit for non-thenables and non-Promises
+          if (this.config.logLevel === 'info' && this.logger?.spinner) {
+            this.logger.spinner.succeed(`[${strategy}] ${hookName}: Excecuting task for plugin ${plugin.name} \n`)
+          }
+          return hookResult
+        }
+
+        return Promise.resolve(hookResult).then((result) => {
+          // action was fulfilled
+          if (this.config.logLevel === 'info' && this.logger?.spinner) {
+            this.logger.spinner.succeed(`[${strategy}] ${hookName}: Excecuting task for plugin ${plugin.name} \n`)
+          }
+          return result
+        })
+      })
+      .catch((e: Error) => {
+        this.catcher<H>(e, plugin, hookName)
+      }) as Promise<TResult>
+  }
+
+  /**
+   * Run a sync plugin hook and return the result.
+   * @param hookName Name of the plugin hook. Must be in `PluginHooks`.
+   * @param args Arguments passed to the plugin hook.
+   * @param plugin The acutal plugin
+   * @param replaceContext When passed, the plugin context can be overridden.
+   */
+  private runSync<H extends PluginLifecycleHooks>(
+    hookName: H,
+    parameters: Parameters<PluginLifecycle[H]>,
+    plugin: KubbPlugin
+  ): ReturnType<PluginLifecycle[H]> | Error {
+    const hook = plugin[hookName]!
+
+    // const context = this.pluginContexts.get(plugin)!;
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/ban-types
+      return (hook as Function).apply(this.core.api, parameters)
+    } catch (error) {
+      return error as Error
+    }
+  }
+
+  private catcher<H extends PluginLifecycleHooks>(e: Error, plugin: KubbPlugin, hookName: H) {
+    const text = `${e.message} (plugin: ${plugin.name}, hook: ${hookName})\n`
+
+    throw new Error(text, { cause: e })
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+function noReturn() {}

package/src/managers/pluginManager/index.ts

@@ -0,0 +1,3 @@
+export * from './PluginManager'
+export * from './types'
+export * from './validate'

package/src/managers/pluginManager/types.ts

@@ -0,0 +1,8 @@
+import type { PluginLifecycle } from '../../types'
+/**
+ * Get the type of the first argument in a function.
+ * @example Arg0<(a: string, b: number) => void> -> string
+ */
+export type Argument0<H extends keyof PluginLifecycle> = Parameters<PluginLifecycle[H]>[0]
+
+export type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookReduceArg0' | 'hookSeq'

package/src/managers/pluginManager/validate.ts

@@ -0,0 +1,21 @@
+import type { KubbPlugin } from '../../types'
+
+export class ValidationPluginError extends Error {}
+
+export function validatePlugins(plugins: KubbPlugin[], dependedPluginNames: string | string[]): true {
+  let pluginNames: string[] = []
+  if (typeof dependedPluginNames === 'string') {
+    pluginNames = [dependedPluginNames]
+  } else {
+    pluginNames = dependedPluginNames
+  }
+
+  pluginNames.forEach((pluginName) => {
+    const exists = plugins.some((plugin) => plugin.name === pluginName)
+    if (!exists) {
+      throw new ValidationPluginError(`This plugin depends on the ${pluginName} plugin.`)
+    }
+  })
+
+  return true
+}

package/src/plugin.ts

@@ -0,0 +1,69 @@
+import pathParser from 'path'
+
+import { createPluginCache } from './utils'
+
+import type { FileManager } from './managers/fileManager'
+import type { PluginContext, KubbPlugin, PluginFactoryOptions } from './types'
+
+type KubbPluginFactory<T extends PluginFactoryOptions = PluginFactoryOptions> = (
+  options: T['options']
+) => T['nested'] extends true ? Array<KubbPlugin<T>> : KubbPlugin<T>
+
+export function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(factory: KubbPluginFactory<T>) {
+  return (options: T['options']) => {
+    const plugin = factory(options)
+    if (Array.isArray(plugin)) {
+      throw new Error('Not implemented')
+    }
+
+    // default transform
+    if (!plugin.transform) {
+      plugin.transform = function transform(code) {
+        return code
+      }
+    }
+
+    return plugin
+  }
+}
+
+type Options = {
+  config: PluginContext['config']
+  fileManager: FileManager
+  resolveId: PluginContext['resolveId']
+  load: PluginContext['load']
+}
+
+// not publicly exported
+export type CorePluginOptions = PluginFactoryOptions<Options, false, PluginContext>
+
+export const name = 'core' as const
+
+export const definePlugin = createPlugin<CorePluginOptions>((options) => {
+  const { fileManager, resolveId, load } = options
+
+  const api: PluginContext = {
+    get config() {
+      return options.config
+    },
+    fileManager,
+    async addFile(file) {
+      return fileManager.addOrAppend(file)
+    },
+    resolveId,
+    load,
+    cache: createPluginCache(Object.create(null)),
+  }
+
+  return {
+    name,
+    options,
+    api,
+    resolveId(fileName, directory) {
+      if (!directory) {
+        return null
+      }
+      return pathParser.resolve(directory, fileName)
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,193 @@
+import type { FileManager, File } from './managers/fileManager'
+import type { Cache } from './utils/cache'
+
+export type MaybePromise<T> = Promise<T> | T
+
+export type KubbUserConfig = Omit<KubbConfig, 'root'> & {
+  /**
+   * 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<unknown>
+}
+
+/**
+ * Global/internal config used through out the full generation.
+ */
+export type KubbConfig = {
+  /**
+   * 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: {
+    /**
+     * Path to be used as the input. Can be an absolute path, or a path relative from
+     * the defined root option.
+     */
+    path: string
+  }
+  output: {
+    /**
+     * Path to be used to export all generated files. Can be an absolute path, or a path relative based of the defined root option.
+     */
+    path: string
+    /**
+     * Remove previous generated files and folders.
+     */
+    clean?: boolean
+    /**
+     * Enabled or disable the writing 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?: KubbPlugin[]
+  /**
+   * Hooks that will be called when a specific action is triggered in Kubb.
+   */
+  hooks?: {
+    /**
+     * Hook that will be triggerend at the end of all executions.
+     * Useful for running Prettier or Eslint to use your own linting structure.
+     */
+    done?: string | string[]
+  }
+  /**
+   * Log level to report when using the CLI
+   */
+  logLevel?: LogLevel
+}
+
+export type CLIOptions = {
+  config?: string
+  debug?: boolean
+  watch?: string
+}
+
+// plugin
+
+export type KubbPluginKind = 'schema' | 'controller'
+
+export type KubbJSONPlugin = [string, Record<string, any>]
+
+export type KubbPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Unique name used for the plugin
+   * @example @kubb/typescript
+   */
+  name: string
+  /**
+   * 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?: KubbPluginKind
+  /**
+   * Defined an api that can be used by other plugins
+   */
+  api?: TOptions['api']
+  /**
+   * Options set for a specific plugin(see kubb.config.ts)
+   */
+  options?: TOptions['options']
+} & Partial<PluginLifecycle<TOptions>>
+
+// use of type objects
+export type PluginFactoryOptions<Options = unknown, Nested extends boolean = false, Api = any, ResolveIdOptions = Record<string, any>> = {
+  options: Options
+  resolveIdOptions: ResolveIdOptions
+  nested: Nested
+  api: Api
+}
+
+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, 'addFile'>, plugins: KubbPlugin[]) => MaybePromise<true>
+  /**
+   * Start of the lifecycle of a plugin.
+   * @type hookParallel
+   */
+  buildStart: (this: PluginContext, kubbConfig: KubbConfig) => MaybePromise<void>
+  /**
+   * Resolve to an id based on importee(example: `./Pet.ts`) and directory(example: `./models`).
+   * @type hookFirst
+   * @example ('./Pet.ts', './src/gen/')
+   */
+  resolveId: (this: Omit<PluginContext, 'addFile'>, fileName: string, directory?: string, options?: TOptions['resolveIdOptions']) => OptionalPath
+  /**
+   * Makes it possible to run async logic to override the path defined previously by `resolveId`.
+   * @type hookFirst
+   */
+  load: (this: Omit<PluginContext, 'addFile'>, path: Path) => MaybePromise<TransformResult | null>
+  /**
+   * Transform the source-code.
+   * @type hookReduceArg0
+   */
+  transform: (this: Omit<PluginContext, 'addFile'>, source: string, path: Path) => MaybePromise<TransformResult>
+  /**
+   * Write the result to the file-system based on the id(defined by `resolveId` or changed by `load`).
+   * @type hookParallel
+   */
+  writeFile: (this: Omit<PluginContext, 'addFile'>, source: string | undefined, path: Path) => MaybePromise<void>
+  /**
+   * End of the plugin lifecycle.
+   * @type hookParallel
+   */
+  buildEnd: (this: Omit<PluginContext, 'addFile'>) => MaybePromise<void>
+}
+
+export type PluginLifecycleHooks = keyof PluginLifecycle
+
+export type ResolveIdParams<TOptions = Record<string, any>> = {
+  fileName: string
+  directory?: string | undefined
+  /**
+   * When set, resolveId will only call resolveId of the name of the plugin set here.
+   * If not defined it will fall back on the resolveId of the core plugin.
+   */
+  pluginName?: string
+  /**
+   * Options to be passed to 'resolveId' 3th parameter
+   */
+  options?: TOptions
+}
+
+export type PluginContext<TOptions = Record<string, any>> = {
+  config: KubbConfig
+  cache: Cache
+  fileManager: FileManager
+  addFile: (file: File) => Promise<File>
+  resolveId: (params: ResolveIdParams<TOptions>) => MaybePromise<OptionalPath>
+  load: (id: string) => MaybePromise<TransformResult | void>
+}
+
+// null will mean clear the watcher for this key
+export type TransformResult = string | null
+
+/**
+ * @description Computing the name of a file or directory together with its position in relation to other directories traced back in a line to the root
+ */
+export type Path = string
+export type OptionalPath = Path | null | undefined
+export type FileName = string | null | undefined
+
+export type LogType = 'error' | 'warn' | 'info'
+export type LogLevel = LogType | 'silent'