@kubb/core 5.0.0-alpha.4 → 5.0.0-alpha.41

package/src/createStorage.ts

@@ -0,0 +1,58 @@
+export type Storage = {
+  /**
+   * Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`).
+   */
+  readonly name: string
+  /**
+   * Returns `true` when an entry for `key` exists in storage.
+   */
+  hasItem(key: string): Promise<boolean>
+  /**
+   * Returns the stored string value, or `null` when `key` does not exist.
+   */
+  getItem(key: string): Promise<string | null>
+  /**
+   * Persists `value` under `key`, creating any required structure.
+   */
+  setItem(key: string, value: string): Promise<void>
+  /**
+   *  Removes the entry for `key`. No-ops when the key does not exist.
+   */
+  removeItem(key: string): Promise<void>
+  /**
+   * Returns all keys, optionally filtered to those starting with `base`.
+   */
+  getKeys(base?: string): Promise<Array<string>>
+  /**
+   * Removes all entries, optionally scoped to those starting with `base`.
+   */
+  clear(base?: string): Promise<void>
+  /**
+   * Optional teardown hook called after the build completes.
+   */
+  dispose?(): Promise<void>
+}
+
+/**
+ * Creates a storage factory. Call the returned function with optional options to get the storage instance.
+ *
+ * @example
+ * export const memoryStorage = createStorage(() => {
+ *   const store = new Map<string, string>()
+ *   return {
+ *     name: 'memory',
+ *     async hasItem(key) { return store.has(key) },
+ *     async getItem(key) { return store.get(key) ?? null },
+ *     async setItem(key, value) { store.set(key, value) },
+ *     async removeItem(key) { store.delete(key) },
+ *     async getKeys(base) {
+ *       const keys = [...store.keys()]
+ *       return base ? keys.filter((k) => k.startsWith(base)) : keys
+ *     },
+ *     async clear(base) { if (!base) store.clear() },
+ *   }
+ * })
+ */
+export function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage {
+  return (options) => build(options ?? ({} as TOptions))
+}

package/src/defineGenerator.ts

@@ -1,106 +1,94 @@
-import type { OperationNode, SchemaNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { FabricReactNode } from '@kubb/react-fabric/types'
-import type { Adapter, Config, Plugin, PluginFactoryOptions } from './types.ts'
+import type { PossiblePromise } from '@internals/utils'
+import type { FileNode, OperationNode, SchemaNode } from '@kubb/ast'
+import type { RendererFactory } from './createRenderer.ts'
+import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
 
-export type Version = '1' | '2'
+export type { GeneratorContext } from './types.ts'
 
-// V2 props — fully typed with @kubb/ast (already a @kubb/core dependency)
-export type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  adapter: Adapter
-  options: Plugin<TPlugin>['options']
-  nodes: Array<OperationNode>
-}
-
-export type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  adapter: Adapter
-  options: Plugin<TPlugin>['options']
-  node: OperationNode
-}
-
-export type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  adapter: Adapter
-  options: Plugin<TPlugin>['options']
-  node: SchemaNode
-}
-
-type UserCoreGeneratorV2<TPlugin extends PluginFactoryOptions> = {
+/**
+ * A generator is a named object with optional `schema`, `operation`, and `operations`
+ * methods. Each method receives the AST node as the first argument and a typed
+ * `ctx` object as the second, giving access to `ctx.config`, `ctx.resolver`,
+ * `ctx.adapter`, `ctx.options`, `ctx.upsertFile`, etc.
+ *
+ * Generators that return renderer elements (e.g. JSX) must declare a `renderer`
+ * factory so that core knows how to process the output without coupling core
+ * to any specific renderer package.
+ *
+ * Return a renderer element, an array of `FileNode`, or `void` to handle file
+ * writing manually via `ctx.upsertFile`.
+ *
+ * @example
+ * ```ts
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator<PluginTs>({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     const { adapter, resolver, root, options } = ctx
+ *     return <File ...><Type node={node} resolver={resolver} /></File>
+ *   },
+ *   operation(node, ctx) {
+ *     const { options } = ctx
+ *     return <File ...><OperationType node={node} /></File>
+ *   },
+ * })
+ * ```
+ */
+export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
+  /**
+   * Used in diagnostic messages and debug output.
+   */
   name: string
-  type: 'core'
-  version?: '2'
-  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  operation?(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+  /**
+   * Optional renderer factory that produces a {@link Renderer} for each render cycle.
+   *
+   * Generators that return renderer elements (e.g. JSX via `@kubb/renderer-jsx`) must set this
+   * to the matching renderer factory (e.g. `jsxRenderer` from `@kubb/renderer-jsx`).
+   *
+   * Generators that only return `Array<FileNode>` or `void` do not need to set this.
+   *
+   * Set `renderer: null` to explicitly opt out of rendering even when the parent plugin
+   * declares a `renderer` (overrides the plugin-level fallback).
+   *
+   * @example
+   * ```ts
+   * import { jsxRenderer } from '@kubb/renderer-jsx'
+   * export const myGenerator = defineGenerator<PluginTs>({
+   *   renderer: jsxRenderer,
+   *   schema(node, ctx) { return <File ...>...</File> },
+   * })
+   * ```
+   */
+  renderer?: RendererFactory<TElement> | null
+  /**
+   * Called for each schema node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  /**
+   * Called for each operation node in the AST walk.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
+   */
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  /**
+   * Called once after all operations have been walked.
+   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * plus `ctx.options` with the plugin-level options for the batch call.
+   */
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
 }
 
-type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
-  name: string
-  type: 'react'
-  version?: '2'
-  Operations?(props: OperationsV2Props<TPlugin>): FabricReactNode
-  Operation?(props: OperationV2Props<TPlugin>): FabricReactNode
-  Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode
-}
-
-export type CoreGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  name: string
-  type: 'core'
-  version: '2'
-  operations(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  operation(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  schema(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-}
-
-export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
-  name: string
-  type: 'react'
-  version: '2'
-  Operations(props: OperationsV2Props<TPlugin>): FabricReactNode
-  Operation(props: OperationV2Props<TPlugin>): FabricReactNode
-  Schema(props: SchemaV2Props<TPlugin>): FabricReactNode
-}
-
-export type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>
-
-export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
-  generator: UserReactGeneratorV2<TPlugin>,
-): ReactGeneratorV2<TPlugin>
-
-export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserCoreGeneratorV2<TPlugin>): CoreGeneratorV2<TPlugin>
-
-export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
-  generator: UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>,
-): unknown {
-  if (generator.type === 'react') {
-    return {
-      version: '2',
-      Operations() {
-        return null
-      },
-      Operation() {
-        return null
-      },
-      Schema() {
-        return null
-      },
-      ...generator,
-    }
-  }
-
-  return {
-    version: '2',
-    async operations() {
-      return []
-    },
-    async operation() {
-      return []
-    },
-    async schema() {
-      return []
-    },
-    ...generator,
-  }
+/**
+ * Defines a generator. Returns the object as-is with correct `this` typings.
+ * `applyHookResult` handles renderer elements and `File[]` uniformly using
+ * the generator's declared `renderer` factory.
+ */
+export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(
+  generator: Generator<TOptions, TElement>,
+): Generator<TOptions, TElement> {
+  return generator
 }

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('kubb:info', (message) => console.log('ℹ', message))
+ *     context.on('kubb: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,45 @@
+import type { FileNode } from '@kubb/ast'
+
+type PrintOptions = {
+  extname?: FileNode['extname']
+}
+
+export type Parser<TMeta extends object = any> = {
+  name: string
+  /**
+   * File extensions this parser handles.
+   * Use `undefined` to create a catch-all fallback parser.
+   *
+   * @example Handled extensions
+   * `['.ts', '.js']`
+   */
+  extNames: Array<FileNode['extname']> | undefined
+  /**
+   * Convert a resolved file to a string.
+   */
+  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string
+}
+
+/**
+ * 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) {
+ *     const { extractStringsFromNodes } = await import('@kubb/ast')
+ *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+ *   },
+ * })
+ * ```
+ */
+export function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta> {
+  return parser
+}

package/src/definePlugin.ts

@@ -1,12 +1,95 @@
-import type { PluginFactoryOptions, UserPluginWithLifeCycle } from './types.ts'
+import type { KubbHooks } from './Kubb.ts'
+import type { KubbPluginSetupContext, PluginFactoryOptions } from './types.ts'
 
-type PluginBuilder<T extends PluginFactoryOptions = PluginFactoryOptions> = (options: T['options']) => UserPluginWithLifeCycle<T>
+/**
+ * Base hook handlers for all events except `kubb:plugin:setup`.
+ * These handlers have identical signatures regardless of the plugin's
+ * `PluginFactoryOptions` generic — they are split out so that the
+ * interface below only needs to override the one event that depends on
+ * the plugin type.
+ */
+type PluginHooksBase = {
+  [K in Exclude<keyof KubbHooks, 'kubb:plugin:setup'>]?: (...args: KubbHooks[K]) => void | Promise<void>
+}
+
+/**
+ * Plugin hook handlers.
+ *
+ * `kubb:plugin:setup` is typed with the plugin's own `PluginFactoryOptions` so
+ * `ctx.setResolver`, `ctx.setOptions`, `ctx.options` etc. use the correct types.
+ *
+ * Uses interface + method shorthand for `kubb:plugin:setup`
+ * checking, allowing `PluginHooks<PluginTs>` to be assignable to `PluginHooks`.
+ *
+ * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ */
+export interface PluginHooks<TFactory extends PluginFactoryOptions = PluginFactoryOptions> extends PluginHooksBase {
+  'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>
+}
+
+/**
+ * A hook-style plugin object produced by `definePlugin`.
+ * Instead of flat lifecycle methods, it groups all handlers under a `hooks:` property
+ * (matching Astro's integration naming convention).
+ *
+ * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ */
+export type HookStylePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Unique name for the plugin, following the same naming convention as `createPlugin`.
+   */
+  name: string
+  /**
+   * Plugins that must be registered before this plugin executes.
+   * An error is thrown at startup when any listed dependency is missing.
+   */
+  dependencies?: Array<string>
+  /**
+   * The options passed by the user when calling the plugin factory.
+   */
+  options?: TFactory['options']
+  /**
+   * Lifecycle event handlers for this plugin.
+   * Any event from the global `KubbHooks` map can be subscribed to here.
+   */
+  hooks: PluginHooks<TFactory>
+}
+
+/**
+ * Returns `true` when `plugin` is a hook-style plugin created with `definePlugin`.
+ *
+ * Used by `PluginDriver` to distinguish hook-style plugins from legacy `createPlugin` plugins
+ * so it can normalize them and register their handlers on the `AsyncEventEmitter`.
+ */
+export function isHookStylePlugin(plugin: unknown): plugin is HookStylePlugin {
+  return typeof plugin === 'object' && plugin !== null && 'hooks' in plugin
+}
 
 /**
- * Wraps a plugin builder to make the options parameter optional.
+ * Creates a plugin factory using the new hook-style (`hooks:`) API.
+ *
+ * The returned factory is called with optional options and produces a `HookStylePlugin`
+ * that coexists with plugins created via the legacy `createPlugin` API in the same
+ * `kubb.config.ts`.
+ *
+ * Lifecycle handlers are registered on the `PluginDriver`'s `AsyncEventEmitter`, enabling
+ * both the plugin's own handlers and external tooling (CLI, devtools) to observe every event.
+ *
+ * @example
+ * ```ts
+ * // With PluginFactoryOptions (recommended for real plugins)
+ * export const pluginTs = definePlugin<PluginTs>((options) => ({
+ *   name: 'plugin-ts',
+ *   hooks: {
+ *     'kubb:plugin:setup'(ctx) {
+ *       ctx.setResolver(resolverTs)  // typed as Partial<ResolverTs>
+ *     },
+ *   },
+ * }))
+ * ```
  */
-export function definePlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(
-  build: PluginBuilder<T>,
-): (options?: T['options']) => UserPluginWithLifeCycle<T> {
-  return (options) => build(options ?? ({} as T['options']))
+export function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(
+  factory: (options: TFactory['options']) => HookStylePlugin<TFactory>,
+): (options?: TFactory['options']) => HookStylePlugin<TFactory> {
+  return (options) => factory(options ?? ({} as TFactory['options']))
 }