@kubb/core 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/{config.ts → defineConfig.ts}

@@ -1,16 +1,18 @@
 import type { PossiblePromise } from '@internals/utils'
-import type { InputPath, UserConfig } from './types.ts'
+import type { UserConfig } from './types.ts'
 
 /**
  * CLI options derived from command-line flags.
  */
 export type CLIOptions = {
-  /** Path to `kubb.config.js` */
+  /**
+   * Path to `kubb.config.js`.
+   */
   config?: string
-
-  /** Enable watch mode for input files */
+  /**
+   * Enable watch mode for input files.
+   */
   watch?: boolean
-
   /**
    * Logging verbosity for CLI usage.
    *
@@ -20,12 +22,11 @@ export type CLIOptions = {
    * @default 'silent'
    */
   logLevel?: 'silent' | 'info' | 'debug'
-
-  /** Run Kubb with Bun */
-  bun?: boolean
 }
 
-/** All accepted forms of a Kubb configuration. */
+/**
+ * All accepted forms of a Kubb configuration.
+ */
 export type ConfigInput = PossiblePromise<UserConfig | UserConfig[]> | ((cli: CLIOptions) => PossiblePromise<UserConfig | UserConfig[]>)
 
 /**
@@ -41,16 +42,10 @@ export type ConfigInput = PossiblePromise<UserConfig | UserConfig[]> | ((cli: CL
  *   root: 'src',
  *   plugins: [myPlugin()],
  * }))
+ * @deprecated as of Kubb v5, @kubb/core will not expose `defineConfig` anymore. use the `kubb` package instead
  */
 export function defineConfig(config: (cli: CLIOptions) => PossiblePromise<UserConfig | UserConfig[]>): typeof config
 export function defineConfig(config: PossiblePromise<UserConfig | UserConfig[]>): typeof config
 export function defineConfig(config: ConfigInput): ConfigInput {
   return config
 }
-
-/**
- * Type guard to check if a given config has an `input.path`.
- */
-export function isInputPath(config: UserConfig | undefined): config is UserConfig<InputPath> {
-  return typeof config?.input === 'object' && config.input !== null && 'path' in config.input
-}

package/src/defineGenerator.ts

@@ -0,0 +1,126 @@
+import type { PossiblePromise } from '@internals/utils'
+import type { OperationNode, SchemaNode } from '@kubb/ast/types'
+import type { FabricReactNode } from '@kubb/react-fabric/types'
+import type * as KubbFile from './KubbFile.ts'
+import { applyHookResult } from './renderNode.tsx'
+import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
+
+export type { GeneratorContext } from './types.ts'
+
+/**
+ * A generator is a named object with optional `schema`, `operation`, and `operations`
+ * methods. Each method is called with `this = PluginContext` of the parent plugin,
+ * giving full access to `this.config`, `this.resolver`, `this.adapter`, `this.fabric`,
+ * `this.driver`, etc.
+ *
+ * Return a React element, an array of `KubbFile.File`, or `void` to handle file
+ * writing manually via `this.upsertFile`. Both React and core (non-React) generators
+ * use the same method signatures — the return type determines how output is handled.
+ *
+ * @example
+ * ```ts
+ * export const typeGenerator = defineGenerator<PluginTs>({
+ *   name: 'typescript',
+ *   schema(node, options) {
+ *     const { adapter, resolver, root } = this
+ *     return <File ...><Type node={node} resolver={resolver} /></File>
+ *   },
+ *   operation(node, options) {
+ *     return <File ...><OperationType node={node} /></File>
+ *   },
+ * })
+ * ```
+ */
+export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /** Used in diagnostic messages and debug output. */
+  name: string
+  /**
+   * Called for each schema node in the AST walk.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   * `options` contains the per-node resolved options (after exclude/include/override).
+   */
+  schema?: (
+    this: GeneratorContext<TOptions>,
+    node: SchemaNode,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<KubbFile.File> | void>
+  /**
+   * Called for each operation node in the AST walk.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   */
+  operation?: (
+    this: GeneratorContext<TOptions>,
+    node: OperationNode,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<KubbFile.File> | void>
+  /**
+   * Called once after all operations have been walked.
+   * `this` is the parent plugin's context with `adapter` and `rootNode` guaranteed present.
+   */
+  operations?: (
+    this: GeneratorContext<TOptions>,
+    nodes: Array<OperationNode>,
+    options: TOptions['resolvedOptions'],
+  ) => PossiblePromise<FabricReactNode | Array<KubbFile.File> | void>
+}
+
+/**
+ * Defines a generator. Returns the object as-is with correct `this` typings.
+ * No type discrimination (`type: 'react' | 'core'`) needed — `applyHookResult`
+ * handles React elements and `File[]` uniformly.
+ */
+export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generator: Generator<TOptions>): Generator<TOptions> {
+  return generator
+}
+
+/**
+ * Merges an array of generators into a single generator.
+ *
+ * The merged generator's `schema`, `operation`, and `operations` methods run
+ * the corresponding method from each input generator in sequence, applying each
+ * result via `applyHookResult`. This eliminates the need to write the loop
+ * manually in each plugin.
+ *
+ * @param generators - Array of generators to merge into a single generator.
+ *
+ * @example
+ * ```ts
+ * const merged = mergeGenerators(generators)
+ *
+ * return {
+ *   name: pluginName,
+ *   schema: merged.schema,
+ *   operation: merged.operation,
+ *   operations: merged.operations,
+ * }
+ * ```
+ */
+export function mergeGenerators<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(generators: Array<Generator<TOptions>>): Generator<TOptions> {
+  return {
+    name: generators.length > 0 ? generators.map((g) => g.name).join('+') : 'merged',
+    async schema(node, options) {
+      for (const gen of generators) {
+        if (!gen.schema) continue
+        const result = await gen.schema.call(this, node, options)
+
+        await applyHookResult(result, this.fabric)
+      }
+    },
+    async operation(node, options) {
+      for (const gen of generators) {
+        if (!gen.operation) continue
+        const result = await gen.operation.call(this, node, options)
+
+        await applyHookResult(result, this.fabric)
+      }
+    },
+    async operations(nodes, options) {
+      for (const gen of generators) {
+        if (!gen.operations) continue
+        const result = await gen.operations.call(this, nodes, options)
+
+        await applyHookResult(result, this.fabric)
+      }
+    },
+  }
+}

package/src/defineLogger.ts

@@ -1,7 +1,17 @@
 import type { Logger, LoggerOptions, UserLogger } from './types.ts'
 
+/**
+ * Wraps a logger definition into a typed {@link Logger}.
+ *
+ * @example
+ * export const myLogger = defineLogger({
+ *   name: 'my-logger',
+ *   install(context, options) {
+ *     context.on('info', (message) => console.log('ℹ', message))
+ *     context.on('error', (error) => console.error('✗', error.message))
+ *   },
+ * })
+ */
 export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
-  return {
-    ...logger,
-  }
+  return logger
 }

package/src/defineParser.ts

@@ -0,0 +1,57 @@
+import type * as KubbFile from './KubbFile.ts'
+
+type PrintOptions = {
+  extname?: KubbFile.Extname
+}
+
+export type Parser<TMeta extends object = any> = {
+  name: string
+  type: 'parser'
+  /**
+   * File extensions this parser handles.
+   * Use `undefined` to create a catch-all fallback parser.
+   *
+   * @example ['.ts', '.js']
+   */
+  extNames: Array<KubbFile.Extname> | undefined
+  /**
+   * @deprecated Will be removed once Fabric no longer requires it.
+   * @default () => {}
+   */
+  install(...args: unknown[]): void | Promise<void>
+  /**
+   * Convert a resolved file to a string.
+   */
+  parse(file: KubbFile.ResolvedFile<TMeta>, options?: PrintOptions): Promise<string> | string
+}
+
+export type UserParser<TMeta extends object = any> = Omit<Parser<TMeta>, 'type' | 'install'> & {
+  install?(...args: unknown[]): void | Promise<void>
+}
+
+/**
+ * Defines a parser with type safety.
+ *
+ * Use this function to create parsers that transform generated files to strings
+ * based on their extension.
+ *
+ * @example
+ * ```ts
+ * import { defineParser } from '@kubb/core'
+ *
+ * export const jsonParser = defineParser({
+ *   name: 'json',
+ *   extNames: ['.json'],
+ *   parse(file) {
+ *     return file.sources.map((s) => s.value).join('\n')
+ *   },
+ * })
+ * ```
+ */
+export function defineParser<TMeta extends object = any>(parser: UserParser<TMeta>): Parser<TMeta> {
+  return {
+    install() {},
+    type: 'parser',
+    ...parser,
+  }
+}

package/src/definePresets.ts

@@ -0,0 +1,16 @@
+import type { Preset, Presets, Resolver } from './types.ts'
+
+/**
+ * Creates a typed presets registry object — a named collection of {@link Preset} entries.
+ *
+ * @example
+ * import { definePreset, definePresets } from '@kubb/core'
+ * import { resolverTsLegacy } from '@kubb/plugin-ts'
+ *
+ * export const myPresets = definePresets({
+ *   kubbV4: definePreset('kubbV4', { resolvers: [resolverTsLegacy] }),
+ * })
+ */
+export function definePresets<TResolver extends Resolver = Resolver>(presets: Presets<TResolver>): Presets<TResolver> {
+  return presets
+}