@kubb/core 5.0.0-alpha.17 → 5.0.0-alpha.18

package/dist/index.d.ts

@@ -1,16 +1,158 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { A as ResolveOptionsContext, B as ReactGeneratorV2, C as PluginParameter, D as Printer, E as Presets, F as UserPlugin, G as formatters, H as KubbEvents, I as UserPluginWithLifeCycle, J as AsyncEventEmitter, K as linters, L as UserResolver, M as Resolver, N as UserConfig, O as PrinterFactoryOptions, P as UserLogger, R as CoreGeneratorV2, S as PluginLifecycleHooks, T as Preset, U as Storage, V as defineGenerator, W as createStorage, _ as Output, a as AdapterFactoryOptions, b as PluginFactoryOptions, c as CompatibilityPreset, d as Group, f as InputData, g as LoggerOptions, h as LoggerContext, i as Adapter, j as ResolvePathParams, k as ResolveNameParams, l as Config, m as Logger, n as PluginDriver, o as AdapterSource, p as InputPath, q as logLevel, r as getMode, s as BarrelType, u as DevtoolsOptions, v as Plugin, w as PluginWithLifeCycle, x as PluginLifecycle, y as PluginContext, z as Generator } from "./PluginDriver-CNKhDf-w.js";
+import { A as ResolveOptionsContext, B as ReactGeneratorV2, C as PluginParameter, D as Printer, E as Presets, F as UserPlugin, G as formatters, H as KubbEvents, I as UserPluginWithLifeCycle, J as PossiblePromise, K as linters, L as UserResolver, M as Resolver, N as UserConfig, O as PrinterFactoryOptions, P as UserLogger, R as CoreGeneratorV2, S as PluginLifecycleHooks, T as Preset, U as Storage, V as defineGenerator, W as createStorage, Y as AsyncEventEmitter, _ as Output, a as AdapterFactoryOptions, b as PluginFactoryOptions, c as CompatibilityPreset, d as Group, f as InputData, g as LoggerOptions, h as LoggerContext, i as Adapter, j as ResolvePathParams, k as ResolveNameParams, l as Config, m as Logger, n as PluginDriver, o as AdapterSource, p as InputPath, q as logLevel, r as getMode, s as BarrelType, u as DevtoolsOptions, v as Plugin, w as PluginWithLifeCycle, x as PluginLifecycle, y as PluginContext, z as Generator } from "./PluginDriver-BRTrzfiD.js";
 import { definePrinter } from "@kubb/ast";
 import { Node, OperationNode, SchemaNode, Visitor } from "@kubb/ast/types";
 import { Fabric, KubbFile } from "@kubb/fabric-core/types";
 import { Fabric as Fabric$1 } from "@kubb/react-fabric/types";
 
+//#region ../../internals/utils/src/urlPath.d.ts
+type URLObject = {
+  /**
+   * The resolved URL string (Express-style or template literal, depending on context).
+   */
+  url: string;
+  /**
+   * Extracted path parameters as a key-value map, or `undefined` when the path has none.
+   */
+  params?: Record<string, string>;
+};
+type ObjectOptions = {
+  /**
+   * Controls whether the `url` is rendered as an Express path or a template literal.
+   * @default 'path'
+   */
+  type?: 'path' | 'template';
+  /**
+   * Optional transform applied to each extracted parameter name.
+   */
+  replacer?: (pathParam: string) => string;
+  /**
+   * When `true`, the result is serialized to a string expression instead of a plain object.
+   */
+  stringify?: boolean;
+};
+/**
+ * Supported identifier casing strategies for path parameters.
+ */
+type PathCasing = 'camelcase';
+type Options = {
+  /**
+   * Casing strategy applied to path parameter names.
+   * @default undefined (original identifier preserved)
+   */
+  casing?: PathCasing;
+};
+/**
+ * Parses and transforms an OpenAPI/Swagger path string into various URL formats.
+ *
+ * @example
+ * const p = new URLPath('/pet/{petId}')
+ * p.URL      // '/pet/:petId'
+ * p.template // '`/pet/${petId}`'
+ */
+declare class URLPath {
+  #private;
+  /**
+   * The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`.
+   */
+  path: string;
+  constructor(path: string, options?: Options);
+  /** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`.
+   *
+   * @example
+   * ```ts
+   * new URLPath('/pet/{petId}').URL // '/pet/:petId'
+   * ```
+   */
+  get URL(): string;
+  /** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`).
+   *
+   * @example
+   * ```ts
+   * new URLPath('https://petstore.swagger.io/v2/pet').isURL // true
+   * new URLPath('/pet/{petId}').isURL                       // false
+   * ```
+   */
+  get isURL(): boolean;
+  /**
+   * Converts the OpenAPI path to a TypeScript template literal string.
+   *
+   * @example
+   * new URLPath('/pet/{petId}').template              // '`/pet/${petId}`'
+   * new URLPath('/account/monetary-accountID').template // '`/account/${monetaryAccountId}`'
+   */
+  get template(): string;
+  /** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set.
+   *
+   * @example
+   * ```ts
+   * new URLPath('/pet/{petId}').object
+   * // { url: '/pet/:petId', params: { petId: 'petId' } }
+   * ```
+   */
+  get object(): URLObject | string;
+  /** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+   *
+   * @example
+   * ```ts
+   * new URLPath('/pet/{petId}').params // { petId: 'petId' }
+   * new URLPath('/pet').params         // undefined
+   * ```
+   */
+  get params(): Record<string, string> | undefined;
+  toObject({
+    type,
+    replacer,
+    stringify
+  }?: ObjectOptions): URLObject | string;
+  /**
+   * Converts the OpenAPI path to a TypeScript template literal string.
+   * An optional `replacer` can transform each extracted parameter name before interpolation.
+   *
+   * @example
+   * new URLPath('/pet/{petId}').toTemplateString() // '`/pet/${petId}`'
+   */
+  toTemplateString({
+    prefix,
+    replacer
+  }?: {
+    prefix?: string;
+    replacer?: (pathParam: string) => string;
+  }): string;
+  /**
+   * Extracts all `{param}` segments from the path and returns them as a key-value map.
+   * An optional `replacer` transforms each parameter name in both key and value positions.
+   * Returns `undefined` when no path parameters are found.
+   *
+   * @example
+   * ```ts
+   * new URLPath('/pet/{petId}/tag/{tagId}').getParams()
+   * // { petId: 'petId', tagId: 'tagId' }
+   * ```
+   */
+  getParams(replacer?: (pathParam: string) => string): Record<string, string> | undefined;
+  /** Converts the OpenAPI path to Express-style colon syntax.
+   *
+   * @example
+   * ```ts
+   * new URLPath('/pet/{petId}').toURLPath() // '/pet/:petId'
+   * ```
+   */
+  toURLPath(): string;
+}
+//#endregion
 //#region src/build.d.ts
 type BuildOptions = {
   config: UserConfig;
   events?: AsyncEventEmitter<KubbEvents>;
 };
+/**
+ * Full output produced by a successful or failed build.
+ */
 type BuildOutput = {
+  /**
+   * Plugins that threw during installation, paired with the caught error.
+   */
   failedPlugins: Set<{
     plugin: Plugin;
     error: Error;
@@ -18,18 +160,54 @@ type BuildOutput = {
   fabric: Fabric;
   files: Array<KubbFile.ResolvedFile>;
   driver: PluginDriver;
+  /**
+   * Elapsed time in milliseconds for each plugin, keyed by plugin name.
+   */
   pluginTimings: Map<string, number>;
   error?: Error;
+  /**
+   * Raw generated source, keyed by absolute file path.
+   */
   sources: Map<KubbFile.Path, string>;
 };
+/**
+ * Intermediate result returned by {@link setup} and accepted by {@link safeBuild}.
+ */
 type SetupResult = {
   events: AsyncEventEmitter<KubbEvents>;
   fabric: Fabric;
   driver: PluginDriver;
   sources: Map<KubbFile.Path, string>;
 };
+/**
+ * Initializes all Kubb infrastructure for a build without executing any plugins.
+ *
+ * - Validates the input path (when applicable).
+ * - Applies config defaults (`root`, `output.*`, `devtools`).
+ * - Creates the Fabric instance and wires storage, format, and lint hooks.
+ * - Runs the adapter (if configured) to produce the universal `RootNode`.
+ *
+ * Pass the returned {@link SetupResult} directly to {@link safeBuild} or {@link build}
+ * via the `overrides` argument to reuse the same infrastructure across multiple runs.
+ */
 declare function setup(options: BuildOptions): Promise<SetupResult>;
+/**
+ * Runs a full Kubb build and throws on any error or plugin failure.
+ *
+ * Internally delegates to {@link safeBuild} and rethrows collected errors.
+ * Pass an existing {@link SetupResult} via `overrides` to skip the setup phase.
+ */
 declare function build(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput>;
+/**
+ * Runs a full Kubb build and captures errors instead of throwing.
+ *
+ * - Installs each plugin in order, recording failures in `failedPlugins`.
+ * - Generates the root barrel file when `output.barrelType` is set.
+ * - Writes all files through Fabric.
+ *
+ * Returns a {@link BuildOutput} even on failure — inspect `error` and
+ * `failedPlugins` to determine whether the build succeeded.
+ */
 declare function safeBuild(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput>;
 //#endregion
 //#region src/config.d.ts
@@ -37,7 +215,13 @@ declare function safeBuild(options: BuildOptions, overrides?: SetupResult): Prom
  * CLI options derived from command-line flags.
  */
 type CLIOptions = {
-  /** Path to `kubb.config.js` */config?: string; /** Enable watch mode for input files */
+  /**
+   * Path to `kubb.config.js`.
+   */
+  config?: string;
+  /**
+   * Enable watch mode for input files.
+   */
   watch?: boolean;
   /**
    * Logging verbosity for CLI usage.
@@ -47,10 +231,11 @@ type CLIOptions = {
    * - `debug`: include detailed plugin lifecycle logs
    * @default 'silent'
    */
-  logLevel?: 'silent' | 'info' | 'debug'; /** Run Kubb with Bun */
-  bun?: boolean;
+  logLevel?: 'silent' | 'info' | 'debug';
 };
-/** All accepted forms of a Kubb configuration. */
+/**
+ * All accepted forms of a Kubb configuration.
+ */
 type ConfigInput = PossiblePromise<UserConfig | UserConfig[]> | ((cli: CLIOptions) => PossiblePromise<UserConfig | UserConfig[]>);
 /**
  * Helper for defining a Kubb configuration.
@@ -347,26 +532,20 @@ declare class FunctionParams {
 //#region src/utils/formatters.d.ts
 type Formatter = keyof typeof formatters;
 /**
- * Detect which formatter is available in the system.
+ * Detects the first available code formatter on the current system.
  *
- * @returns Promise that resolves to the first available formatter or undefined if none are found
- *
- * @remarks
- * Checks in order of preference: biome, oxfmt, prettier.
- * Uses the `--version` flag to detect if each formatter command is available.
- * This is a reliable method as all supported formatters implement this flag.
+ * - Checks in preference order: `biome`, `oxfmt`, `prettier`.
+ * - Returns `null` when none are found.
  *
  * @example
- * ```typescript
+ * ```ts
  * const formatter = await detectFormatter()
  * if (formatter) {
  *   console.log(`Using ${formatter} for formatting`)
- * } else {
- *   console.log('No formatter found')
  * }
  * ```
  */
-declare function detectFormatter(): Promise<Formatter | undefined>;
+declare function detectFormatter(): Promise<Formatter | null>;
 //#endregion
 //#region src/utils/getBarrelFiles.d.ts
 type FileMetaBase = {
@@ -390,6 +569,14 @@ type AddIndexesProps = {
   };
   meta?: FileMetaBase;
 };
+/**
+ * Generates `index.ts` barrel files for all directories under `root/output.path`.
+ *
+ * - Returns an empty array when `type` is falsy or `'propagate'`.
+ * - Skips generation when the output path itself ends with `index` (already a barrel).
+ * - When `type` is `'all'`, strips named exports so every re-export becomes a wildcard (`export * from`).
+ * - Attaches `meta` to each barrel file for downstream plugin identification.
+ */
 declare function getBarrelFiles(files: Array<KubbFile.ResolvedFile>, {
   type,
   meta,
@@ -399,7 +586,11 @@ declare function getBarrelFiles(files: Array<KubbFile.ResolvedFile>, {
 //#endregion
 //#region src/utils/getConfigs.d.ts
 /**
- * Converting UserConfig to Config Array without a change in the object beside the JSON convert.
+ * Resolves a {@link ConfigInput} into a normalized array of {@link Config} objects.
+ *
+ * - Awaits the config when it is a `Promise`.
+ * - Calls the factory function with `args` when the config is a function.
+ * - Wraps a single config object in an array for uniform downstream handling.
  */
 declare function getConfigs(config: ConfigInput | UserConfig, args: CLIOptions): Promise<Array<Config>>;
 //#endregion
@@ -416,11 +607,32 @@ type GetPresetResult<TResolver extends Resolver> = {
   transformers: Array<Visitor>;
   preset: Preset<TResolver> | undefined;
 };
+/**
+ * Resolves a named preset into merged resolvers and transformers.
+ *
+ * - Merges the preset's resolvers on top of the first (default) resolver to produce `baseResolver`.
+ * - Merges any additional user-supplied resolvers on top of that to produce the final `resolver`.
+ * - Concatenates preset transformers before user-supplied transformers.
+ */
 declare function getPreset<TResolver extends Resolver = Resolver>(params: GetPresetParams<TResolver>): GetPresetResult<TResolver>;
 //#endregion
 //#region src/utils/linters.d.ts
 type Linter = keyof typeof linters;
-declare function detectLinter(): Promise<Linter | undefined>;
+/**
+ * Detects the first available linter on the current system.
+ *
+ * - Checks in preference order: `biome`, `oxlint`, `eslint`.
+ * - Returns `null` when none are found.
+ *
+ * @example
+ * ```ts
+ * const linter = await detectLinter()
+ * if (linter) {
+ *   console.log(`Using ${linter} for linting`)
+ * }
+ * ```
+ */
+declare function detectLinter(): Promise<Linter | null>;
 //#endregion
 //#region src/utils/mergeResolvers.d.ts
 /**
@@ -431,7 +643,22 @@ declare function mergeResolvers<T extends Resolver>(...resolvers: Array<T>): T;
 //#region src/utils/packageJSON.d.ts
 type DependencyName = string;
 type DependencyVersion = string;
+/**
+ * Returns `true` when the nearest `package.json` declares a dependency that
+ * satisfies the given semver range.
+ *
+ * - Searches both `dependencies` and `devDependencies`.
+ * - Accepts a string package name or a `RegExp` to match scoped/pattern packages.
+ * - Uses `semver.satisfies` for range comparison; returns `false` when the
+ *   version string cannot be coerced into a valid semver.
+ *
+ * @example
+ * ```ts
+ * satisfiesDependency('react', '>=18')          // true when react@18.x is installed
+ * satisfiesDependency(/^@tanstack\//, '>=5')    // true when any @tanstack/* >=5 is found
+ * ```
+ */
 declare function satisfiesDependency(dependency: DependencyName | RegExp, version: DependencyVersion, cwd?: string): boolean;
 //#endregion
-export { Adapter, AdapterFactoryOptions, AdapterSource, BarrelType, type CLIOptions, CompatibilityPreset, Config, type ConfigInput, CoreGeneratorV2, DevtoolsOptions, type FileMetaBase, FunctionParams, type FunctionParamsAST, Generator, Group, InputData, InputPath, KubbEvents, Logger, LoggerContext, LoggerOptions, Output, Plugin, PluginContext, PluginDriver, PluginFactoryOptions, PluginLifecycle, PluginLifecycleHooks, PluginParameter, PluginWithLifeCycle, Preset, Presets, Printer, PrinterFactoryOptions, ReactGeneratorV2, ResolveNameParams, ResolveOptionsContext, ResolvePathParams, Resolver, Storage, UserConfig, UserLogger, UserPlugin, UserPluginWithLifeCycle, UserResolver, build, build as default, createAdapter, createPlugin, createStorage, defaultResolveOptions, defineConfig, defineGenerator, defineLogger, definePreset, definePresets, definePrinter, defineResolver, detectFormatter, detectLinter, formatters, fsStorage, getBarrelFiles, getConfigs, getMode, getPreset, isInputPath, linters, logLevel, memoryStorage, mergeResolvers, renderOperation, renderOperations, renderSchema, safeBuild, satisfiesDependency, setup };
+export { Adapter, AdapterFactoryOptions, AdapterSource, AsyncEventEmitter, BarrelType, type CLIOptions, CompatibilityPreset, Config, type ConfigInput, CoreGeneratorV2, DevtoolsOptions, type FileMetaBase, FunctionParams, type FunctionParamsAST, Generator, Group, InputData, InputPath, KubbEvents, Logger, LoggerContext, LoggerOptions, Output, Plugin, PluginContext, PluginDriver, PluginFactoryOptions, PluginLifecycle, PluginLifecycleHooks, PluginParameter, PluginWithLifeCycle, Preset, Presets, Printer, PrinterFactoryOptions, ReactGeneratorV2, ResolveNameParams, ResolveOptionsContext, ResolvePathParams, Resolver, Storage, URLPath, UserConfig, UserLogger, UserPlugin, UserPluginWithLifeCycle, UserResolver, build, build as default, createAdapter, createPlugin, createStorage, defaultResolveOptions, defineConfig, defineGenerator, defineLogger, definePreset, definePresets, definePrinter, defineResolver, detectFormatter, detectLinter, formatters, fsStorage, getBarrelFiles, getConfigs, getMode, getPreset, isInputPath, linters, logLevel, memoryStorage, mergeResolvers, renderOperation, renderOperations, renderSchema, safeBuild, satisfiesDependency, setup };
 //# sourceMappingURL=index.d.ts.map