@kubb/core 5.0.0-alpha.2 → 5.0.0-alpha.21

package/src/types.ts

@@ -1,11 +1,12 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { RootNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Fabric } from '@kubb/react-fabric'
+import type { Node, RootNode, SchemaNode, Visitor } from '@kubb/ast/types'
+import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+import type { HttpMethod } from '@kubb/oas'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
-import type { DefineStorage } from './defineStorage.ts'
+import type { Storage } from './createStorage.ts'
+import type { Generator } from './defineGenerator.ts'
 import type { KubbEvents } from './Kubb.ts'
-import type { PluginManager } from './PluginManager.ts'
+import type { PluginDriver } from './PluginDriver.ts'
 
 export type { Printer, PrinterFactoryOptions } from '@kubb/ast/types'
 
@@ -33,7 +34,7 @@ export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins'
   /**
    * An array of Kubb plugins used for generation. Each plugin may have additional configurable options (defined within the plugin itself). If a plugin relies on another plugin, an error will occur if the required dependency is missing. Refer to “pre” for more details.
    */
-  // inject needs to be omitted because else we have a clash with the PluginManager instance
+  // inject needs to be omitted because else we have a clash with the PluginDriver instance
   plugins?: Array<Omit<UnknownUserPlugin, 'inject'>>
 }
 
@@ -66,11 +67,18 @@ export type AdapterSource = { type: 'path'; path: string } | { type: 'data'; dat
  * - `TName` — unique string identifier (e.g. `'oas'`, `'asyncapi'`)
  * - `TOptions` — raw user-facing options passed to the adapter factory
  * - `TResolvedOptions` — defaults applied; what the adapter stores as `options`
+ * - `TDocument` — type of the raw source document exposed by the adapter after `parse()`
  */
-export type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions> = {
+export type AdapterFactoryOptions<
+  TName extends string = string,
+  TOptions extends object = object,
+  TResolvedOptions extends object = TOptions,
+  TDocument = unknown,
+> = {
   name: TName
   options: TOptions
   resolvedOptions: TResolvedOptions
+  document: TDocument
 }
 
 /**
@@ -92,12 +100,32 @@ export type AdapterFactoryOptions<TName extends string = string, TOptions extend
  * ```
  */
 export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
-  /** Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`. */
+  /**
+   * Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`.
+   */
   name: TOptions['name']
-  /** Resolved options (after defaults have been applied). */
+  /**
+   * Resolved options (after defaults have been applied).
+   */
   options: TOptions['resolvedOptions']
-  /** Convert the raw source into a universal `RootNode`. */
+  /**
+   * The raw source document produced after the first `parse()` call.
+   * `undefined` before parsing; typed by the adapter's `TDocument` generic.
+   */
+  document: TOptions['document'] | null
+  rootNode: RootNode | null
+  /**
+   * Convert the raw source into a universal `RootNode`.
+   */
   parse: (source: AdapterSource) => PossiblePromise<RootNode>
+  /**
+   * Extracts `KubbFile.Import` entries needed by a `SchemaNode` tree.
+   * Populated after the first `parse()` call. Returns an empty array before that.
+   *
+   * The `resolve` callback receives the collision-corrected schema name and must
+   * return the `{ name, path }` pair for the import, or `undefined` to skip it.
+   */
+  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<KubbFile.Import>
 }
 
 export type BarrelType = 'all' | 'named' | 'propagate'
@@ -165,16 +193,16 @@ export type Config<TInput = Input> = {
     /**
      * Storage backend for generated files.
      * Defaults to `fsStorage()` — the built-in filesystem driver.
-     * Accepts any object implementing the {@link DefineStorage} interface.
+     * Accepts any object implementing the {@link Storage} interface.
      * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
      * @default fsStorage()
      * @example
      * ```ts
-     * import { defineStorage, fsStorage } from '@kubb/core'
-     * storage: defineStorage(fsStorage())
+     * import { memoryStorage } from '@kubb/core'
+     * storage: memoryStorage()
      * ```
      */
-    storage?: DefineStorage
+    storage?: Storage
     /**
      * Specifies the formatting tool to be used.
      * - 'auto' automatically detects and uses biome or prettier (in that order of preference).
@@ -204,7 +232,7 @@ export type Config<TInput = Input> = {
      * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
      * @default 'named'
      */
-    barrelType?: Exclude<BarrelType, 'propagate'> | false
+    barrelType?: 'all' | 'named' | false
     /**
      * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
      * - 'simple' adds banner with link to Kubb.
@@ -253,6 +281,73 @@ export type Config<TInput = Input> = {
 
 // plugin
 
+type PatternFilter = {
+  type: string
+  pattern: string | RegExp
+}
+
+type PatternOverride<TOptions> = PatternFilter & {
+  options: Omit<Partial<TOptions>, 'override'>
+}
+
+export type ResolveOptionsContext<TOptions> = {
+  options: TOptions
+  exclude?: Array<PatternFilter>
+  include?: Array<PatternFilter>
+  override?: Array<PatternOverride<TOptions>>
+}
+
+/**
+ * Base constraint for all plugin resolver objects.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, and `resolveFile` are injected automatically
+ * by `defineResolver` — plugin authors may override them but never need to implement them
+ * from scratch.
+ *
+ * @example
+ * ```ts
+ * type MyResolver = Resolver & {
+ *   resolveName(node: SchemaNode): string
+ *   resolveTypedName(node: SchemaNode): string
+ * }
+ * ```
+ */
+export type Resolver = {
+  name: string
+  pluginName: Plugin['name']
+  default(name: ResolveNameParams['name'], type?: ResolveNameParams['type']): string
+  resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null
+  resolvePath(params: ResolverPathParams, context: ResolverContext): KubbFile.Path
+  resolveFile(params: ResolverFileParams, context: ResolverContext): KubbFile.File
+  resolveBanner(node: RootNode | null, context: ResolveBannerContext): string | undefined
+  resolveFooter(node: RootNode | null, context: ResolveBannerContext): string | undefined
+}
+
+/**
+ * The user-facing subset of a `Resolver` — everything except the four methods injected by
+ * `defineResolver` (`default`, `resolveOptions`, `resolvePath`, and `resolveFile`).
+ *
+ * All four injected methods can still be overridden by providing them explicitly in the builder.
+ *
+ * @example
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(node) { return this.default(node.name, 'function') },
+ * }))
+ * ```
+ */
+export type UserResolver = Omit<Resolver, 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>
+
+/**
+ * Base type for plugin builder objects.
+ * Concrete plugin builder types extend this with their own schema-building helpers.
+ * Use `defineBuilder` to define a builder object and export it alongside the plugin.
+ */
+export type Builder = {
+  name: string
+}
+
 export type PluginFactoryOptions<
   /**
    * Name to be used for the plugin.
@@ -274,16 +369,26 @@ export type PluginFactoryOptions<
    * When calling `resolvePath` you can specify better types.
    */
   TResolvePathOptions extends object = object,
+  /**
+   * Resolver object that encapsulates the naming and path-resolution helpers used by this plugin.
+   * Use `defineResolver` to define the resolver object and export it alongside the plugin.
+   */
+  TResolver extends Resolver = Resolver,
+  /**
+   * Builder object that encapsulates the schema-building helpers used by this plugin.
+   * Use `defineBuilder` to define the builder object and export it alongside the plugin.
+   */
+  TBuilder extends Builder = Builder,
 > = {
   name: TName
   options: TOptions
   resolvedOptions: TResolvedOptions
   context: TContext
   resolvePathOptions: TResolvePathOptions
+  resolver: TResolver
+  builder: TBuilder
 }
 
-export type GetPluginFactoryOptions<TPlugin extends UserPlugin> = TPlugin extends UserPlugin<infer X> ? X : never
-
 export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
    * Unique name used for the plugin
@@ -309,7 +414,7 @@ export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOpti
 
 export type UserPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = UserPlugin<TOptions> & PluginLifecycle<TOptions>
 
-export type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<any, any, any, any, any>>
+type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<string, object, object, unknown, object>>
 
 export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
   /**
@@ -333,7 +438,7 @@ export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
 
   install: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => PossiblePromise<void>
   /**
-   * Define a context that can be used by other plugins, see `PluginManager' where we convert from `UserPlugin` to `Plugin`(used when calling `definePlugin`).
+   * Defines a context that can be used by other plugins, see `PluginDriver` where we convert from `UserPlugin` to `Plugin` (used when calling `createPlugin`).
    */
   inject: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context']
 }
@@ -351,6 +456,7 @@ export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactor
    * Options can als be included.
    * @type hookFirst
    * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
+   * @deprecated this will be replaced by resolvers
    */
   resolvePath?: (this: PluginContext<TOptions>, baseName: KubbFile.BaseName, mode?: KubbFile.Mode, options?: TOptions['resolvePathOptions']) => KubbFile.Path
   /**
@@ -358,6 +464,7 @@ export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactor
    * Useful when converting to PascalCase or camelCase.
    * @type hookFirst
    * @example ('pet') => 'Pet'
+   * @deprecated this will be replaced by resolvers
    */
   resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
 }
@@ -391,9 +498,9 @@ export type ResolveNameParams = {
 }
 
 export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  fabric: Fabric
+  fabric: FabricType
   config: Config
-  pluginManager: PluginManager
+  driver: PluginDriver
   /**
    * Only add when the file does not exist yet
    */
@@ -408,22 +515,35 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
    * Current plugin
    */
   plugin: Plugin<TOptions>
-  /**
-   * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
-   * Returns `undefined` when no adapter was set (legacy OAS-only usage).
-   */
-  rootNode: RootNode | undefined
+
   /**
    * Opens the Kubb Studio URL for the current `rootNode` in the default browser.
    * Falls back to printing the URL if the browser cannot be launched.
    * No-ops silently when no adapter has set a `rootNode`.
    */
   openInStudio: (options?: DevtoolsOptions) => Promise<void>
-} & Kubb.PluginContext
+} & (
+  | {
+      /**
+       * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
+       * Returns `undefined` when no adapter was set (legacy OAS-only usage).
+       */
+      rootNode: RootNode
+      /**
+       * Return the adapter from `@kubb/ast`
+       */
+      adapter: Adapter
+    }
+  | {
+      rootNode?: never
+      adapter?: never
+    }
+) &
+  Kubb.PluginContext
 /**
  * Specify the export location for the files and define the behavior of the output
  */
-export type Output<TOptions> = {
+export type Output<_TOptions = unknown> = {
   /**
    * Path to the output folder or file that will contain the generated code
    */
@@ -436,11 +556,11 @@ export type Output<TOptions> = {
   /**
    * Add a banner text in the beginning of every file
    */
-  banner?: string | ((options: TOptions) => string)
+  banner?: string | ((node: RootNode) => string)
   /**
    * Add a footer text in the beginning of every file
    */
-  footer?: string | ((options: TOptions) => string)
+  footer?: string | ((node: RootNode) => string)
   /**
    * Whether to override existing external files if they already exist.
    * @default false
@@ -448,10 +568,6 @@ export type Output<TOptions> = {
   override?: boolean
 }
 
-type GroupContext = {
-  group: string
-}
-
 export type Group = {
   /**
    * Defines the type where to group the files.
@@ -461,9 +577,9 @@ export type Group = {
    */
   type: 'tag' | 'path'
   /**
-   * Return the name of a group based on the group name, this used for the file and name generation
+   * Return the name of a group based on the group name, this is used for the file and name generation.
    */
-  name?: (context: GroupContext) => string
+  name?: (context: { group: string }) => string
 }
 
 export type LoggerOptions = {
@@ -476,16 +592,200 @@ export type LoggerOptions = {
 /**
  * Shared context passed to all plugins, parsers, and Fabric internals.
  */
-export interface LoggerContext extends AsyncEventEmitter<KubbEvents> {}
-
-type Install<TOptions = unknown> = (context: LoggerContext, options?: TOptions) => void | Promise<void>
+export type LoggerContext = AsyncEventEmitter<KubbEvents>
 
 export type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
   name: string
-  install: Install<TOptions>
+  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>
 }
 
-export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>
+export type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>
 
-export type { DefineStorage } from './defineStorage.ts'
+/**
+ * Compatibility preset for code generation tools.
+ * - `'default'` – no compatibility adjustments (default behavior).
+ * - `'kubbV4'` – align generated names and structures with Kubb v4 output.
+ */
+export type CompatibilityPreset = 'default' | 'kubbV4'
+
+export type { Storage } from './createStorage.ts'
+export type { CoreGeneratorV2, Generator, ReactGeneratorV2 } from './defineGenerator.ts'
 export type { KubbEvents } from './Kubb.ts'
+
+/**
+ * A preset bundles a name, one or more resolvers, optional AST transformers,
+ * and optional generators into a single reusable configuration object.
+ *
+ * @template TResolver - The concrete resolver type for this preset.
+ */
+export type Preset<TResolver extends Resolver = Resolver> = {
+  /**
+   * Unique identifier for this preset.
+   */
+  name: string
+  /**
+   * Ordered list of resolvers applied by this preset (last entry wins on merge).
+   */
+  resolvers: Array<TResolver>
+  /**
+   * Optional AST visitors / transformers applied after resolving.
+   */
+  transformers?: Array<Visitor>
+  /**
+   * Optional generators used by this preset. Plugin implementations cast this
+   * to their concrete generator type.
+   */
+  generators?: Array<Generator<any>>
+}
+
+/**
+ * A named registry of presets, keyed by preset name.
+ *
+ * @template TResolver - The concrete resolver type shared by all presets in this registry.
+ * @template TName - The union of valid preset name keys.
+ */
+export type Presets<TResolver extends Resolver = Resolver> = Record<CompatibilityPreset, Preset<TResolver>>
+
+type ByTag = {
+  type: 'tag'
+  pattern: string | RegExp
+}
+
+type ByOperationId = {
+  type: 'operationId'
+  pattern: string | RegExp
+}
+
+type ByPath = {
+  type: 'path'
+  pattern: string | RegExp
+}
+
+type ByMethod = {
+  type: 'method'
+  pattern: HttpMethod | RegExp
+}
+// TODO implement as alternative for ByMethod
+// type ByMethods = {
+//   type: 'methods'
+//   pattern: Array<HttpMethod>
+// }
+
+type BySchemaName = {
+  type: 'schemaName'
+  pattern: string | RegExp
+}
+
+type ByContentType = {
+  type: 'contentType'
+  pattern: string | RegExp
+}
+
+export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  //TODO should be options: Omit<Partial<TOptions>, 'override'>
+  options: Partial<TOptions>
+}
+
+export type ResolvePathOptions = {
+  pluginName?: string
+  group?: {
+    tag?: string
+    path?: string
+  }
+  type?: ResolveNameParams['type']
+}
+
+/**
+ * File-specific parameters for `Resolver.resolvePath`.
+ *
+ * Pass alongside a `ResolverContext` to identify which file to resolve.
+ * Provide `tag` for tag-based grouping or `path` for path-based grouping.
+ *
+ * @example
+ * ```ts
+ * resolver.resolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/petsController/petTypes.ts'
+ * ```
+ */
+export type ResolverPathParams = {
+  baseName: KubbFile.BaseName
+  pathMode?: KubbFile.Mode
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string
+}
+
+/**
+ * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
+ *
+ * Describes where on disk output is rooted, which output config is active, and the optional
+ * grouping strategy that controls subdirectory layout.
+ *
+ * @example
+ * ```ts
+ * const context: ResolverContext = {
+ *   root: config.root,
+ *   output,
+ *   group,
+ * }
+ * ```
+ */
+export type ResolverContext = {
+  root: string
+  output: Output
+  group?: Group
+  /** Plugin name used to populate `meta.pluginName` on the resolved file. */
+  pluginName?: string
+}
+
+/**
+ * File-specific parameters for `Resolver.resolveFile`.
+ *
+ * Pass alongside a `ResolverContext` to fully describe the file to resolve.
+ * `tag` and `path` are used only when a matching `group` is present in the context.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveFile(
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+ * ```
+ */
+export type ResolverFileParams = {
+  name: string
+  extname: KubbFile.Extname
+  /** Tag value used when `group.type === 'tag'`. */
+  tag?: string
+  /** Path value used when `group.type === 'path'`. */
+  path?: string
+}
+
+/**
+ * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
+ *
+ * `output` is optional — not every plugin configures a banner/footer.
+ * `config` carries the global Kubb config, used to derive the default Kubb banner.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveBanner(rootNode, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+export type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>
+  config: Config
+}

package/src/utils/FunctionParams.ts

@@ -30,12 +30,12 @@ type FunctionParamsASTWithType = {
   default?: string
 }
 /**
- * @deprecated
+ * @deprecated use ast package instead
  */
 export type FunctionParamsAST = FunctionParamsASTWithoutType | FunctionParamsASTWithType
 
 /**
- * @deprecated
+ * @deprecated use ast package instead
  */
 export class FunctionParams {
   #items: Array<FunctionParamsAST | FunctionParamsAST[]> = []

package/src/utils/TreeNode.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import type { KubbFile } from '@kubb/fabric-core/types'
-import { getMode } from '../PluginManager.ts'
+import { getMode } from '../PluginDriver.ts'
 
 type BarrelData = {
   file?: KubbFile.File
@@ -12,6 +12,15 @@ type BarrelData = {
   name: string
 }
 
+/**
+ * Tree structure used to build per-directory barrel (`index.ts`) files from a
+ * flat list of generated {@link KubbFile.File} entries.
+ *
+ * Each node represents either a directory or a file within the output tree.
+ * Use {@link TreeNode.build} to construct a root node from a file list, then
+ * traverse with {@link TreeNode.forEach}, {@link TreeNode.leaves}, or the
+ * `*Deep` helpers.
+ */
 export class TreeNode {
   data: BarrelData
   parent?: TreeNode
@@ -32,6 +41,9 @@ export class TreeNode {
     return child
   }
 
+  /**
+   * Returns the root ancestor of this node, walking up via `parent` links.
+   */
   get root(): TreeNode {
     if (!this.parent) {
       return this
@@ -39,6 +51,11 @@ export class TreeNode {
     return this.parent.root
   }
 
+  /**
+   * Returns all leaf descendants (nodes with no children) of this node.
+   *
+   * Results are cached after the first traversal.
+   */
   get leaves(): Array<TreeNode> {
     if (!this.children || this.children.length === 0) {
       // this is a leaf
@@ -105,6 +122,12 @@ export class TreeNode {
     return this.leaves.map(callback)
   }
 
+  /**
+   * Builds a {@link TreeNode} tree from a flat list of files.
+   *
+   * - Filters to files under `root` (when provided) and skips `.json` files.
+   * - Returns `null` when no files match.
+   */
   public static build(files: KubbFile.File[], root?: string): TreeNode | null {
     try {
       const filteredTree = buildDirectoryTree(files, root)

package/src/utils/diagnostics.ts

@@ -2,7 +2,10 @@ import { version as nodeVersion } from 'node:process'
 import { version as KubbVersion } from '../../package.json'
 
 /**
- * Get diagnostic information for debugging
+ * Returns a snapshot of the current runtime environment.
+ *
+ * Useful for attaching context to debug logs and error reports so that
+ * issues can be reproduced without manual information gathering.
  */
 export function getDiagnosticInfo() {
   return {

package/src/utils/executeStrategies.ts

@@ -7,7 +7,11 @@ type ValueOfPromiseFuncArray<TInput extends Array<unknown>> = TInput extends Arr
 type SeqOutput<TInput extends Array<PromiseFunc<TValue, null>>, TValue> = Promise<Array<Awaited<ValueOfPromiseFuncArray<TInput>>>>
 
 /**
- * Chains promises
+ * Runs promise functions in sequence, threading each result into the next call.
+ *
+ * - Each function receives the accumulated state from the previous call.
+ * - Skips functions that return a falsy value (acts as a no-op for that step).
+ * - Returns an array of all individual results.
  */
 export function hookSeq<TInput extends Array<PromiseFunc<TValue, null>>, TValue, TOutput = SeqOutput<TInput, TValue>>(promises: TInput): TOutput {
   return promises.filter(Boolean).reduce(
@@ -33,7 +37,10 @@ export function hookSeq<TInput extends Array<PromiseFunc<TValue, null>>, TValue,
 type HookFirstOutput<TInput extends Array<PromiseFunc<TValue, null>>, TValue = unknown> = ValueOfPromiseFuncArray<TInput>
 
 /**
- * Chains promises, first non-null result stops and returns
+ * Runs promise functions in sequence and returns the first non-null result.
+ *
+ * - Stops as soon as `nullCheck` passes for a result (default: `!== null`).
+ * - Subsequent functions are skipped once a match is found.
  */
 export function hookFirst<TInput extends Array<PromiseFunc<TValue, null>>, TValue = unknown, TOutput = HookFirstOutput<TInput, TValue>>(
   promises: TInput,
@@ -57,7 +64,10 @@ export function hookFirst<TInput extends Array<PromiseFunc<TValue, null>>, TValu
 type HookParallelOutput<TInput extends Array<PromiseFunc<TValue, null>>, TValue> = Promise<PromiseSettledResult<Awaited<ValueOfPromiseFuncArray<TInput>>>[]>
 
 /**
- * Runs an array of promise functions with optional concurrency limit.
+ * Runs promise functions concurrently and returns all settled results.
+ *
+ * - Limits simultaneous executions to `concurrency` (default: unlimited).
+ * - Uses `Promise.allSettled` so individual failures do not cancel other tasks.
  */
 export function hookParallel<TInput extends Array<PromiseFunc<TValue, null>>, TValue = unknown, TOutput = HookParallelOutput<TInput, TValue>>(
   promises: TInput,
@@ -70,12 +80,15 @@ export function hookParallel<TInput extends Array<PromiseFunc<TValue, null>>, TV
   return Promise.allSettled(tasks) as TOutput
 }
 
+/**
+ * Execution strategy used when dispatching plugin hook calls.
+ */
 export type Strategy = 'seq' | 'first' | 'parallel'
 
-export type StrategySwitch<TStrategy extends Strategy, TInput extends Array<PromiseFunc<TValue, null>>, TValue> = TStrategy extends 'first'
-  ? HookFirstOutput<TInput, TValue>
-  : TStrategy extends 'seq'
-    ? SeqOutput<TInput, TValue>
-    : TStrategy extends 'parallel'
-      ? HookParallelOutput<TInput, TValue>
-      : never
+type StrategyOutputMap<TInput extends Array<PromiseFunc<TValue, null>>, TValue> = {
+  first: HookFirstOutput<TInput, TValue>
+  seq: SeqOutput<TInput, TValue>
+  parallel: HookParallelOutput<TInput, TValue>
+}
+
+export type StrategySwitch<TStrategy extends Strategy, TInput extends Array<PromiseFunc<TValue, null>>, TValue> = StrategyOutputMap<TInput, TValue>[TStrategy]