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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/dist/{types-B7eZvqwD.d.ts → PluginDriver-CEQPafXV.d.ts} +687 -298
  2. package/dist/hooks.cjs +15 -9
  3. package/dist/hooks.cjs.map +1 -1
  4. package/dist/hooks.d.ts +11 -5
  5. package/dist/hooks.js +16 -10
  6. package/dist/hooks.js.map +1 -1
  7. package/dist/index.cjs +1131 -536
  8. package/dist/index.cjs.map +1 -1
  9. package/dist/index.d.ts +674 -89
  10. package/dist/index.js +1114 -532
  11. package/dist/index.js.map +1 -1
  12. package/package.json +6 -6
  13. package/src/Kubb.ts +37 -55
  14. package/src/{PluginManager.ts → PluginDriver.ts} +51 -40
  15. package/src/build.ts +74 -29
  16. package/src/config.ts +9 -8
  17. package/src/constants.ts +44 -1
  18. package/src/createAdapter.ts +25 -0
  19. package/src/createPlugin.ts +28 -0
  20. package/src/createStorage.ts +58 -0
  21. package/src/defineBuilder.ts +26 -0
  22. package/src/defineGenerator.ts +137 -0
  23. package/src/defineLogger.ts +13 -3
  24. package/src/definePreset.ts +27 -0
  25. package/src/definePresets.ts +16 -0
  26. package/src/defineResolver.ts +448 -0
  27. package/src/hooks/index.ts +1 -1
  28. package/src/hooks/useDriver.ts +8 -0
  29. package/src/hooks/useMode.ts +5 -2
  30. package/src/hooks/usePlugin.ts +5 -2
  31. package/src/index.ts +21 -6
  32. package/src/renderNode.tsx +105 -0
  33. package/src/storages/fsStorage.ts +2 -2
  34. package/src/storages/memoryStorage.ts +2 -2
  35. package/src/types.ts +342 -42
  36. package/src/utils/FunctionParams.ts +2 -2
  37. package/src/utils/TreeNode.ts +24 -1
  38. package/src/utils/diagnostics.ts +4 -1
  39. package/src/utils/executeStrategies.ts +23 -10
  40. package/src/utils/formatters.ts +10 -21
  41. package/src/utils/getBarrelFiles.ts +79 -9
  42. package/src/utils/getConfigs.ts +8 -22
  43. package/src/utils/getPreset.ts +52 -0
  44. package/src/utils/linters.ts +23 -3
  45. package/src/utils/mergeResolvers.ts +8 -0
  46. package/src/utils/packageJSON.ts +76 -0
  47. package/src/BarrelManager.ts +0 -74
  48. package/src/PackageManager.ts +0 -180
  49. package/src/PromiseManager.ts +0 -40
  50. package/src/defineAdapter.ts +0 -22
  51. package/src/definePlugin.ts +0 -12
  52. package/src/defineStorage.ts +0 -56
  53. package/src/errors.ts +0 -1
  54. package/src/hooks/usePluginManager.ts +0 -8
  55. package/src/utils/getPlugins.ts +0 -23
@@ -1,100 +1,102 @@
1
1
  import { t as __name } from "./chunk--u3MIqq1.js";
2
- import { EventEmitter } from "node:events";
3
- import { Fabric } from "@kubb/react-fabric";
4
- import { KubbFile } from "@kubb/fabric-core/types";
5
- import { Printer, PrinterFactoryOptions, RootNode } from "@kubb/ast/types";
2
+ import { Node, OperationNode, Printer, PrinterFactoryOptions, RootNode, SchemaNode, Visitor } from "@kubb/ast/types";
3
+ import { Fabric, KubbFile } from "@kubb/fabric-core/types";
4
+ import { HttpMethod } from "@kubb/oas";
5
+ import { FabricReactNode } from "@kubb/react-fabric/types";
6
6
 
7
- //#region ../../internals/utils/dist/index.d.ts
8
- /**
9
- * A typed EventEmitter that awaits all async listeners before resolving.
10
- * Wraps Node's `EventEmitter` with full TypeScript event-map inference.
11
- */
12
- declare var AsyncEventEmitter: {
13
- new (maxListener?: number): {
14
- "__#private@#emitter": EventEmitter<[never]>;
15
- /**
16
- * Emits an event and awaits all registered listeners in parallel.
17
- * Throws if any listener rejects, wrapping the cause with the event name and serialized arguments.
18
- */
19
- emit(eventName: any, ...eventArgs: any[]): Promise<void>; /** Registers a persistent listener for the given event. */
20
- on(eventName: any, handler: any): void; /** Registers a one-shot listener that removes itself after the first invocation. */
21
- onOnce(eventName: any, handler: any): void; /** Removes a previously registered listener. */
22
- off(eventName: any, handler: any): void; /** Removes all listeners from every event channel. */
23
- removeAll(): void;
24
- };
25
- };
7
+ //#region ../../internals/utils/src/asyncEventEmitter.d.ts
26
8
  /**
27
- * Parses and transforms an OpenAPI/Swagger path string into various URL formats.
28
- *
29
- * @example
30
- * const p = new URLPath('/pet/{petId}')
31
- * p.URL // '/pet/:petId'
32
- * p.template // '`/pet/${petId}`'
33
- */
34
- declare var URLPath: {
35
- new (path: any, options?: {}): {
36
- /** The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`. */path: any;
37
- "__#private@#options": {}; /** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
38
- get URL(): any; /** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`). */
39
- get isURL(): boolean;
40
- /**
41
- * Converts the OpenAPI path to a TypeScript template literal string.
42
- *
43
- * @example
44
- * new URLPath('/pet/{petId}').template // '`/pet/${petId}`'
45
- * new URLPath('/account/monetary-accountID').template // '`/account/${monetaryAccountId}`'
46
- */
47
- get template(): string; /** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set. */
48
- get object(): string | {
49
- url: any;
50
- params: {} | undefined;
51
- }; /** Returns a map of path parameter names, or `undefined` when the path has no parameters. */
52
- get params(): {} | undefined;
53
- "__#private@#transformParam"(raw: any): any; /** Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name. */
54
- "__#private@#eachParam"(fn: any): void;
55
- toObject({
56
- type,
57
- replacer,
58
- stringify
59
- }?: {
60
- type?: string | undefined;
61
- }): string | {
62
- url: any;
63
- params: {} | undefined;
64
- };
65
- /**
66
- * Converts the OpenAPI path to a TypeScript template literal string.
67
- * An optional `replacer` can transform each extracted parameter name before interpolation.
68
- *
69
- * @example
70
- * new URLPath('/pet/{petId}').toTemplateString() // '`/pet/${petId}`'
71
- */
72
- toTemplateString({
73
- prefix,
74
- replacer
75
- }?: {
76
- prefix?: string | undefined;
77
- }): string;
78
- /**
79
- * Extracts all `{param}` segments from the path and returns them as a key-value map.
80
- * An optional `replacer` transforms each parameter name in both key and value positions.
81
- * Returns `undefined` when no path parameters are found.
82
- */
83
- getParams(replacer: any): {} | undefined; /** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
84
- toURLPath(): any;
85
- };
86
- };
9
+ * A function that can be registered as an event listener, synchronous or async.
10
+ */
11
+ type AsyncListener<TArgs extends unknown[]> = (...args: TArgs) => void | Promise<void>;
87
12
  /**
88
- * Serializes a primitive value to a JSON string literal, stripping any surrounding quote characters first.
89
- *
90
- * @example
91
- * stringify('hello') // '"hello"'
92
- * stringify('"hello"') // '"hello"'
93
- */
94
- declare function stringify(value: any): string;
13
+ * Typed `EventEmitter` that awaits all async listeners before resolving.
14
+ * Wraps Node's `EventEmitter` with full TypeScript event-map inference.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * const emitter = new AsyncEventEmitter<{ build: [name: string] }>()
19
+ * emitter.on('build', async (name) => { console.log(name) })
20
+ * await emitter.emit('build', 'petstore') // all listeners awaited
21
+ * ```
22
+ */
23
+ declare class AsyncEventEmitter<TEvents extends { [K in keyof TEvents]: unknown[] }> {
24
+ #private;
25
+ /**
26
+ * Maximum number of listeners per event before Node emits a memory-leak warning.
27
+ * @default 10
28
+ */
29
+ constructor(maxListener?: number);
30
+ /**
31
+ * Emits `eventName` and awaits all registered listeners in parallel.
32
+ * Throws if any listener rejects, wrapping the cause with the event name and serialized arguments.
33
+ *
34
+ * @example
35
+ * ```ts
36
+ * await emitter.emit('build', 'petstore')
37
+ * ```
38
+ */
39
+ emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void>;
40
+ /**
41
+ * Registers a persistent listener for `eventName`.
42
+ *
43
+ * @example
44
+ * ```ts
45
+ * emitter.on('build', async (name) => { console.log(name) })
46
+ * ```
47
+ */
48
+ on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: AsyncListener<TEvents[TEventName]>): void;
49
+ /**
50
+ * Registers a one-shot listener that removes itself after the first invocation.
51
+ *
52
+ * @example
53
+ * ```ts
54
+ * emitter.onOnce('build', async (name) => { console.log(name) })
55
+ * ```
56
+ */
57
+ onOnce<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: AsyncListener<TEvents[TEventName]>): void;
58
+ /**
59
+ * Removes a previously registered listener.
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * emitter.off('build', handler)
64
+ * ```
65
+ */
66
+ off<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: AsyncListener<TEvents[TEventName]>): void;
67
+ /**
68
+ * Removes all listeners from every event channel.
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * emitter.removeAll()
73
+ * ```
74
+ */
75
+ removeAll(): void;
76
+ }
77
+ //#endregion
78
+ //#region ../../internals/utils/src/promise.d.ts
79
+ /** A value that may already be resolved or still pending.
80
+ *
81
+ * @example
82
+ * ```ts
83
+ * function load(id: string): PossiblePromise<string> {
84
+ * return cache.get(id) ?? fetchRemote(id)
85
+ * }
86
+ * ```
87
+ */
88
+ type PossiblePromise<T> = Promise<T> | T;
95
89
  //#endregion
96
90
  //#region src/constants.d.ts
91
+ /**
92
+ * Base URL for the Kubb Studio web app.
93
+ */
97
94
  declare const DEFAULT_STUDIO_URL: "https://studio.kubb.dev";
95
+ /**
96
+ * Numeric log-level thresholds used internally to compare verbosity.
97
+ *
98
+ * Higher numbers are more verbose.
99
+ */
98
100
  declare const logLevel: {
99
101
  readonly silent: number;
100
102
  readonly error: 0;
@@ -103,6 +105,13 @@ declare const logLevel: {
103
105
  readonly verbose: 4;
104
106
  readonly debug: 5;
105
107
  };
108
+ /**
109
+ * CLI command descriptors for each supported linter.
110
+ *
111
+ * Each entry contains the executable `command`, an `args` factory that maps an
112
+ * output path to the correct argument list, and an `errorMessage` shown when
113
+ * the linter is not found.
114
+ */
106
115
  declare const linters: {
107
116
  readonly eslint: {
108
117
  readonly command: "eslint";
@@ -120,6 +129,13 @@ declare const linters: {
120
129
  readonly errorMessage: "Oxlint not found";
121
130
  };
122
131
  };
132
+ /**
133
+ * CLI command descriptors for each supported code formatter.
134
+ *
135
+ * Each entry contains the executable `command`, an `args` factory that maps an
136
+ * output path to the correct argument list, and an `errorMessage` shown when
137
+ * the formatter is not found.
138
+ */
123
139
  declare const formatters: {
124
140
  readonly prettier: {
125
141
  readonly command: "prettier";
@@ -138,46 +154,46 @@ declare const formatters: {
138
154
  };
139
155
  };
140
156
  //#endregion
141
- //#region src/defineStorage.d.ts
142
- /**
143
- * Storage interface for persisting Kubb output.
144
- *
145
- * Keys are root-relative forward-slash paths (e.g. `src/gen/api/getPets.ts`).
146
- * Implement this interface to route generated files to any backend — filesystem,
147
- * S3, Redis, in-memory, etc.
148
- *
149
- * Use `defineStorage` to create a typed storage driver.
150
- */
151
- interface DefineStorage {
152
- /** Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`). */
157
+ //#region src/createStorage.d.ts
158
+ type Storage = {
159
+ /**
160
+ * Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`).
161
+ */
153
162
  readonly name: string;
154
- /** Returns `true` when an entry for `key` exists in storage. */
163
+ /**
164
+ * Returns `true` when an entry for `key` exists in storage.
165
+ */
155
166
  hasItem(key: string): Promise<boolean>;
156
- /** Returns the stored string value, or `null` when `key` does not exist. */
167
+ /**
168
+ * Returns the stored string value, or `null` when `key` does not exist.
169
+ */
157
170
  getItem(key: string): Promise<string | null>;
158
- /** Persists `value` under `key`, creating any required structure. */
171
+ /**
172
+ * Persists `value` under `key`, creating any required structure.
173
+ */
159
174
  setItem(key: string, value: string): Promise<void>;
160
- /** Removes the entry for `key`. No-ops when the key does not exist. */
175
+ /**
176
+ * Removes the entry for `key`. No-ops when the key does not exist.
177
+ */
161
178
  removeItem(key: string): Promise<void>;
162
- /** Returns all keys, optionally filtered to those starting with `base`. */
179
+ /**
180
+ * Returns all keys, optionally filtered to those starting with `base`.
181
+ */
163
182
  getKeys(base?: string): Promise<Array<string>>;
164
- /** Removes all entries, optionally scoped to those starting with `base`. */
183
+ /**
184
+ * Removes all entries, optionally scoped to those starting with `base`.
185
+ */
165
186
  clear(base?: string): Promise<void>;
166
- /** Optional teardown hook called after the build completes. */
187
+ /**
188
+ * Optional teardown hook called after the build completes.
189
+ */
167
190
  dispose?(): Promise<void>;
168
- }
191
+ };
169
192
  /**
170
- * Wraps a storage builder so the `options` argument is optional, following the
171
- * same factory pattern as `definePlugin`, `defineLogger`, and `defineAdapter`.
172
- *
173
- * The builder receives the resolved options object and must return a
174
- * `DefineStorage`-compatible object that includes a `name` string.
193
+ * Creates a storage factory. Call the returned function with optional options to get the storage instance.
175
194
  *
176
195
  * @example
177
- * ```ts
178
- * import { defineStorage } from '@kubb/core'
179
- *
180
- * export const memoryStorage = defineStorage((_options) => {
196
+ * export const memoryStorage = createStorage(() => {
181
197
  * const store = new Map<string, string>()
182
198
  * return {
183
199
  * name: 'memory',
@@ -185,160 +201,127 @@ interface DefineStorage {
185
201
  * async getItem(key) { return store.get(key) ?? null },
186
202
  * async setItem(key, value) { store.set(key, value) },
187
203
  * async removeItem(key) { store.delete(key) },
188
- * async getKeys() { return [...store.keys()] },
189
- * async clear() { store.clear() },
204
+ * async getKeys(base) {
205
+ * const keys = [...store.keys()]
206
+ * return base ? keys.filter((k) => k.startsWith(base)) : keys
207
+ * },
208
+ * async clear(base) { if (!base) store.clear() },
190
209
  * }
191
210
  * })
192
- * ```
193
211
  */
194
- declare function defineStorage<TOptions = Record<string, never>>(build: (options: TOptions) => DefineStorage): (options?: TOptions) => DefineStorage;
212
+ declare function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage;
195
213
  //#endregion
196
- //#region src/PluginManager.d.ts
197
- type RequiredPluginLifecycle = Required<PluginLifecycle>;
198
- type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookSeq';
199
- type ParseResult<H extends PluginLifecycleHooks> = RequiredPluginLifecycle[H];
200
- type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseResult<H>>> = {
201
- result: Result;
202
- plugin: Plugin;
214
+ //#region src/defineGenerator.d.ts
215
+ /**
216
+ * Props for the `operations` lifecycle receives all operation nodes at once.
217
+ */
218
+ type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
219
+ config: Config;
220
+ plugin: Plugin<TPlugin>;
221
+ adapter: Adapter;
222
+ options: Plugin<TPlugin>['options'];
223
+ nodes: Array<OperationNode>;
203
224
  };
204
- type Options = {
205
- fabric: Fabric;
206
- events: AsyncEventEmitter<KubbEvents>;
207
- /**
208
- * @default Number.POSITIVE_INFINITY
209
- */
210
- concurrency?: number;
225
+ /**
226
+ * Props for the `operation` lifecycle — receives a single operation node.
227
+ */
228
+ type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
229
+ config: Config;
230
+ adapter: Adapter;
231
+ plugin: Plugin<TPlugin>;
232
+ options: Plugin<TPlugin>['options'];
233
+ node: OperationNode;
211
234
  };
212
- type GetFileProps<TOptions = object> = {
235
+ /**
236
+ * Props for the `schema` lifecycle — receives a single schema node.
237
+ */
238
+ type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
239
+ config: Config;
240
+ adapter: Adapter;
241
+ plugin: Plugin<TPlugin>;
242
+ options: Plugin<TPlugin>['options'];
243
+ node: SchemaNode;
244
+ };
245
+ type UserCoreGeneratorV2<TPlugin extends PluginFactoryOptions> = {
213
246
  name: string;
214
- mode?: KubbFile.Mode;
215
- extname: KubbFile.Extname;
216
- pluginName: string;
217
- options?: TOptions;
247
+ type: 'core';
248
+ version?: '2';
249
+ operations?(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
250
+ operation?(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
251
+ schema?(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
218
252
  };
219
- declare function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode;
220
- declare class PluginManager {
221
- #private;
222
- readonly config: Config;
223
- readonly options: Options;
224
- /**
225
- * The universal `@kubb/ast` `RootNode` produced by the adapter, set by
226
- * the build pipeline after the adapter's `parse()` resolves.
227
- */
228
- rootNode: RootNode | undefined;
229
- constructor(config: Config, options: Options);
230
- get events(): AsyncEventEmitter<KubbEvents>;
231
- getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown>;
232
- get plugins(): Array<Plugin>;
233
- getFile<TOptions = object>({
234
- name,
235
- mode,
236
- extname,
237
- pluginName,
238
- options
239
- }: GetFileProps<TOptions>): KubbFile.File<{
240
- pluginName: string;
241
- }>;
242
- resolvePath: <TOptions = object>(params: ResolvePathParams<TOptions>) => KubbFile.Path;
243
- resolveName: (params: ResolveNameParams) => string;
244
- /**
245
- * Run a specific hookName for plugin x.
246
- */
247
- hookForPlugin<H extends PluginLifecycleHooks>({
248
- pluginName,
249
- hookName,
250
- parameters
251
- }: {
252
- pluginName: string;
253
- hookName: H;
254
- parameters: PluginParameter<H>;
255
- }): Promise<Array<ReturnType<ParseResult<H>> | null>>;
256
- /**
257
- * Run a specific hookName for plugin x.
258
- */
259
- hookForPluginSync<H extends PluginLifecycleHooks>({
260
- pluginName,
261
- hookName,
262
- parameters
263
- }: {
264
- pluginName: string;
265
- hookName: H;
266
- parameters: PluginParameter<H>;
267
- }): Array<ReturnType<ParseResult<H>>> | null;
268
- /**
269
- * Returns the first non-null result.
270
- */
271
- hookFirst<H extends PluginLifecycleHooks>({
272
- hookName,
273
- parameters,
274
- skipped
275
- }: {
276
- hookName: H;
277
- parameters: PluginParameter<H>;
278
- skipped?: ReadonlySet<Plugin> | null;
279
- }): Promise<SafeParseResult<H>>;
280
- /**
281
- * Returns the first non-null result.
282
- */
283
- hookFirstSync<H extends PluginLifecycleHooks>({
284
- hookName,
285
- parameters,
286
- skipped
287
- }: {
288
- hookName: H;
289
- parameters: PluginParameter<H>;
290
- skipped?: ReadonlySet<Plugin> | null;
291
- }): SafeParseResult<H> | null;
292
- /**
293
- * Runs all plugins in parallel based on `this.plugin` order and `pre`/`post` settings.
294
- */
295
- hookParallel<H extends PluginLifecycleHooks, TOutput = void>({
296
- hookName,
297
- parameters
298
- }: {
299
- hookName: H;
300
- parameters?: Parameters<RequiredPluginLifecycle[H]> | undefined;
301
- }): Promise<Awaited<TOutput>[]>;
302
- /**
303
- * Chains plugins
304
- */
305
- hookSeq<H extends PluginLifecycleHooks>({
306
- hookName,
307
- parameters
308
- }: {
309
- hookName: H;
310
- parameters?: PluginParameter<H>;
311
- }): Promise<void>;
312
- getPluginByName(pluginName: string): Plugin | undefined;
313
- getPluginsByName(hookName: keyof PluginWithLifeCycle, pluginName: string): Plugin[];
314
- }
253
+ type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
254
+ name: string;
255
+ type: 'react';
256
+ version?: '2';
257
+ Operations?(props: OperationsV2Props<TPlugin>): FabricReactNode;
258
+ Operation?(props: OperationV2Props<TPlugin>): FabricReactNode;
259
+ Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode;
260
+ };
261
+ type CoreGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
262
+ name: string;
263
+ type: 'core';
264
+ version: '2';
265
+ operations(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
266
+ operation(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
267
+ schema(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>;
268
+ };
269
+ type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
270
+ name: string;
271
+ type: 'react';
272
+ version: '2';
273
+ Operations(props: OperationsV2Props<TPlugin>): FabricReactNode;
274
+ Operation(props: OperationV2Props<TPlugin>): FabricReactNode;
275
+ Schema(props: SchemaV2Props<TPlugin>): FabricReactNode;
276
+ };
277
+ type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>;
278
+ /**
279
+ * Defines a generator with no-op defaults for any omitted lifecycle methods.
280
+ * Works for both `core` (async file output) and `react` (JSX component) generators.
281
+ *
282
+ * @example
283
+ * // react generator
284
+ * export const typeGenerator = defineGenerator<PluginTs>({
285
+ * name: 'typescript',
286
+ * type: 'react',
287
+ * Operation({ node, options }) { return <File>...</File> },
288
+ * Schema({ node, options }) { return <File>...</File> },
289
+ * })
290
+ *
291
+ * @example
292
+ * // core generator
293
+ * export const myGenerator = defineGenerator<MyPlugin>({
294
+ * name: 'my-generator',
295
+ * type: 'core',
296
+ * async operation({ node, options }) { return [{ path: '...', content: '...' }] },
297
+ * })
298
+ */
299
+ declare function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserReactGeneratorV2<TPlugin>): ReactGeneratorV2<TPlugin>;
300
+ declare function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserCoreGeneratorV2<TPlugin>): CoreGeneratorV2<TPlugin>;
315
301
  //#endregion
316
302
  //#region src/Kubb.d.ts
317
- type DebugEvent = {
303
+ type DebugInfo = {
318
304
  date: Date;
319
- logs: string[];
305
+ logs: Array<string>;
320
306
  fileName?: string;
321
307
  };
322
- type ProgressStartMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
308
+ type HookProgress<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
323
309
  hookName: H;
324
310
  plugins: Array<Plugin>;
325
311
  };
326
- type ProgressStopMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
327
- hookName: H;
328
- };
329
- type ExecutingMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
312
+ type HookExecution<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
330
313
  strategy: Strategy;
331
314
  hookName: H;
332
315
  plugin: Plugin;
333
- parameters?: unknown[] | undefined;
316
+ parameters?: Array<unknown>;
334
317
  output?: unknown;
335
318
  };
336
- type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
319
+ type HookResult<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
337
320
  duration: number;
338
321
  strategy: Strategy;
339
322
  hookName: H;
340
323
  plugin: Plugin;
341
- parameters?: unknown[] | undefined;
324
+ parameters?: Array<unknown>;
342
325
  output?: unknown;
343
326
  };
344
327
  /**
@@ -347,7 +330,7 @@ type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
347
330
  *
348
331
  * @example
349
332
  * ```typescript
350
- * import type { AsyncEventEmitter } from '@kubb/core'
333
+ * import type { AsyncEventEmitter } from '@internals/utils'
351
334
  * import type { KubbEvents } from '@kubb/core'
352
335
  *
353
336
  * const events: AsyncEventEmitter<KubbEvents> = new AsyncEventEmitter()
@@ -385,12 +368,12 @@ interface KubbEvents {
385
368
  /**
386
369
  * Emitted when code generation phase completes.
387
370
  */
388
- 'generation:end': [Config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>];
371
+ 'generation:end': [config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>];
389
372
  /**
390
373
  * Emitted with a summary of the generation results.
391
374
  * Contains summary lines, title, and success status.
392
375
  */
393
- 'generation:summary': [Config: Config, {
376
+ 'generation:summary': [config: Config, {
394
377
  failedPlugins: Set<{
395
378
  plugin: Plugin;
396
379
  error: Error;
@@ -398,7 +381,7 @@ interface KubbEvents {
398
381
  status: 'success' | 'failed';
399
382
  hrStart: [number, number];
400
383
  filesCreated: number;
401
- pluginTimings?: Map<string, number>;
384
+ pluginTimings?: Map<Plugin['name'], number>;
402
385
  }];
403
386
  /**
404
387
  * Emitted when code formatting starts (e.g., running Biome or Prettier).
@@ -425,7 +408,7 @@ interface KubbEvents {
425
408
  */
426
409
  'hooks:end': [];
427
410
  /**
428
- * Emitted when a single hook execution starts. (e.g., format or lint).
411
+ * Emitted when a single hook execution starts (e.g., format or lint).
429
412
  * The callback should be invoked when the command completes.
430
413
  */
431
414
  'hook:start': [{
@@ -467,7 +450,7 @@ interface KubbEvents {
467
450
  * Debug event for detailed logging.
468
451
  * Contains timestamp, log messages, and optional filename.
469
452
  */
470
- debug: [meta: DebugEvent];
453
+ debug: [info: DebugInfo];
471
454
  /**
472
455
  * Emitted when file processing starts.
473
456
  * Contains the list of files to be processed.
@@ -478,10 +461,25 @@ interface KubbEvents {
478
461
  * Contains processed count, total count, percentage, and file details.
479
462
  */
480
463
  'file:processing:update': [{
481
- /** Number of files processed so far */processed: number; /** Total number of files to process */
482
- total: number; /** Processing percentage (0-100) */
483
- percentage: number; /** Optional source identifier */
484
- source?: string; /** The file being processed */
464
+ /**
465
+ * Number of files processed so far.
466
+ */
467
+ processed: number;
468
+ /**
469
+ * Total number of files to process.
470
+ */
471
+ total: number;
472
+ /**
473
+ * Processing percentage (0–100).
474
+ */
475
+ percentage: number;
476
+ /**
477
+ * Optional source identifier.
478
+ */
479
+ source?: string;
480
+ /**
481
+ * The file being processed.
482
+ */
485
483
  file: KubbFile.ResolvedFile;
486
484
  /**
487
485
  * Kubb configuration (not present in Fabric).
@@ -493,16 +491,16 @@ interface KubbEvents {
493
491
  * Emitted when file processing completes.
494
492
  * Contains the list of processed files.
495
493
  */
496
- 'files:processing:end': [files: KubbFile.ResolvedFile[]];
494
+ 'files:processing:end': [files: Array<KubbFile.ResolvedFile>];
497
495
  /**
498
496
  * Emitted when a plugin starts executing.
499
497
  */
500
498
  'plugin:start': [plugin: Plugin];
501
499
  /**
502
500
  * Emitted when a plugin completes execution.
503
- * Duration in ms
501
+ * Duration in ms.
504
502
  */
505
- 'plugin:end': [plugin: Plugin, meta: {
503
+ 'plugin:end': [plugin: Plugin, result: {
506
504
  duration: number;
507
505
  success: boolean;
508
506
  error?: Error;
@@ -511,22 +509,24 @@ interface KubbEvents {
511
509
  * Emitted when plugin hook progress tracking starts.
512
510
  * Contains the hook name and list of plugins to execute.
513
511
  */
514
- 'plugins:hook:progress:start': [meta: ProgressStartMeta];
512
+ 'plugins:hook:progress:start': [progress: HookProgress];
515
513
  /**
516
514
  * Emitted when plugin hook progress tracking ends.
517
515
  * Contains the hook name that completed.
518
516
  */
519
- 'plugins:hook:progress:end': [meta: ProgressStopMeta];
517
+ 'plugins:hook:progress:end': [{
518
+ hookName: PluginLifecycleHooks;
519
+ }];
520
520
  /**
521
521
  * Emitted when a plugin hook starts processing.
522
522
  * Contains strategy, hook name, plugin, parameters, and output.
523
523
  */
524
- 'plugins:hook:processing:start': [meta: ExecutingMeta];
524
+ 'plugins:hook:processing:start': [execution: HookExecution];
525
525
  /**
526
526
  * Emitted when a plugin hook completes processing.
527
527
  * Contains duration, strategy, hook name, plugin, parameters, and output.
528
528
  */
529
- 'plugins:hook:processing:end': [meta: ExecutedMeta];
529
+ 'plugins:hook:processing:end': [result: HookResult];
530
530
  }
531
531
  //#endregion
532
532
  //#region src/types.d.ts
@@ -589,11 +589,13 @@ type AdapterSource = {
589
589
  * - `TName` — unique string identifier (e.g. `'oas'`, `'asyncapi'`)
590
590
  * - `TOptions` — raw user-facing options passed to the adapter factory
591
591
  * - `TResolvedOptions` — defaults applied; what the adapter stores as `options`
592
+ * - `TDocument` — type of the raw source document exposed by the adapter after `parse()`
592
593
  */
593
- type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions> = {
594
+ type AdapterFactoryOptions<TName extends string = string, TOptions extends object = object, TResolvedOptions extends object = TOptions, TDocument = unknown> = {
594
595
  name: TName;
595
596
  options: TOptions;
596
597
  resolvedOptions: TResolvedOptions;
598
+ document: TDocument;
597
599
  };
598
600
  /**
599
601
  * An adapter converts a source file or data into a `@kubb/ast` `RootNode`.
@@ -614,9 +616,35 @@ type AdapterFactoryOptions<TName extends string = string, TOptions extends objec
614
616
  * ```
615
617
  */
616
618
  type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
617
- /** Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`. */name: TOptions['name']; /** Resolved options (after defaults have been applied). */
618
- options: TOptions['resolvedOptions']; /** Convert the raw source into a universal `RootNode`. */
619
+ /**
620
+ * Human-readable identifier, e.g. `'oas'`, `'drizzle'`, `'asyncapi'`.
621
+ */
622
+ name: TOptions['name'];
623
+ /**
624
+ * Resolved options (after defaults have been applied).
625
+ */
626
+ options: TOptions['resolvedOptions'];
627
+ /**
628
+ * The raw source document produced after the first `parse()` call.
629
+ * `undefined` before parsing; typed by the adapter's `TDocument` generic.
630
+ */
631
+ document: TOptions['document'] | null;
632
+ rootNode: RootNode | null;
633
+ /**
634
+ * Convert the raw source into a universal `RootNode`.
635
+ */
619
636
  parse: (source: AdapterSource) => PossiblePromise<RootNode>;
637
+ /**
638
+ * Extracts `KubbFile.Import` entries needed by a `SchemaNode` tree.
639
+ * Populated after the first `parse()` call. Returns an empty array before that.
640
+ *
641
+ * The `resolve` callback receives the collision-corrected schema name and must
642
+ * return the `{ name, path }` pair for the import, or `undefined` to skip it.
643
+ */
644
+ getImports: (node: SchemaNode, resolve: (schemaName: string) => {
645
+ name: string;
646
+ path: string;
647
+ }) => Array<KubbFile.Import>;
620
648
  };
621
649
  type BarrelType = 'all' | 'named' | 'propagate';
622
650
  type DevtoolsOptions = {
@@ -681,16 +709,16 @@ type Config<TInput = Input> = {
681
709
  /**
682
710
  * Storage backend for generated files.
683
711
  * Defaults to `fsStorage()` — the built-in filesystem driver.
684
- * Accepts any object implementing the {@link DefineStorage} interface.
712
+ * Accepts any object implementing the {@link Storage} interface.
685
713
  * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
686
714
  * @default fsStorage()
687
715
  * @example
688
716
  * ```ts
689
- * import { defineStorage, fsStorage } from '@kubb/core'
690
- * storage: defineStorage(fsStorage())
717
+ * import { memoryStorage } from '@kubb/core'
718
+ * storage: memoryStorage()
691
719
  * ```
692
720
  */
693
- storage?: DefineStorage;
721
+ storage?: Storage;
694
722
  /**
695
723
  * Specifies the formatting tool to be used.
696
724
  * - 'auto' automatically detects and uses biome or prettier (in that order of preference).
@@ -720,7 +748,7 @@ type Config<TInput = Input> = {
720
748
  * 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`).
721
749
  * @default 'named'
722
750
  */
723
- barrelType?: Exclude<BarrelType, 'propagate'> | false;
751
+ barrelType?: 'all' | 'named' | false;
724
752
  /**
725
753
  * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
726
754
  * - 'simple' adds banner with link to Kubb.
@@ -764,6 +792,67 @@ type Config<TInput = Input> = {
764
792
  done?: string | Array<string>;
765
793
  };
766
794
  };
795
+ type PatternFilter = {
796
+ type: string;
797
+ pattern: string | RegExp;
798
+ };
799
+ type PatternOverride<TOptions> = PatternFilter & {
800
+ options: Omit<Partial<TOptions>, 'override'>;
801
+ };
802
+ type ResolveOptionsContext<TOptions> = {
803
+ options: TOptions;
804
+ exclude?: Array<PatternFilter>;
805
+ include?: Array<PatternFilter>;
806
+ override?: Array<PatternOverride<TOptions>>;
807
+ };
808
+ /**
809
+ * Base constraint for all plugin resolver objects.
810
+ *
811
+ * `default`, `resolveOptions`, `resolvePath`, and `resolveFile` are injected automatically
812
+ * by `defineResolver` — plugin authors may override them but never need to implement them
813
+ * from scratch.
814
+ *
815
+ * @example
816
+ * ```ts
817
+ * type MyResolver = Resolver & {
818
+ * resolveName(node: SchemaNode): string
819
+ * resolveTypedName(node: SchemaNode): string
820
+ * }
821
+ * ```
822
+ */
823
+ type Resolver = {
824
+ name: string;
825
+ pluginName: Plugin['name'];
826
+ default(name: ResolveNameParams['name'], type?: ResolveNameParams['type']): string;
827
+ resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null;
828
+ resolvePath(params: ResolverPathParams, context: ResolverContext): KubbFile.Path;
829
+ resolveFile(params: ResolverFileParams, context: ResolverContext): KubbFile.File;
830
+ resolveBanner(node: RootNode | null, context: ResolveBannerContext): string | undefined;
831
+ resolveFooter(node: RootNode | null, context: ResolveBannerContext): string | undefined;
832
+ };
833
+ /**
834
+ * The user-facing subset of a `Resolver` — everything except the four methods injected by
835
+ * `defineResolver` (`default`, `resolveOptions`, `resolvePath`, and `resolveFile`).
836
+ *
837
+ * All four injected methods can still be overridden by providing them explicitly in the builder.
838
+ *
839
+ * @example
840
+ * ```ts
841
+ * export const resolver = defineResolver<PluginTs>(() => ({
842
+ * name: 'default',
843
+ * resolveName(node) { return this.default(node.name, 'function') },
844
+ * }))
845
+ * ```
846
+ */
847
+ type UserResolver = Omit<Resolver, 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>;
848
+ /**
849
+ * Base type for plugin builder objects.
850
+ * Concrete plugin builder types extend this with their own schema-building helpers.
851
+ * Use `defineBuilder` to define a builder object and export it alongside the plugin.
852
+ */
853
+ type Builder = {
854
+ name: string;
855
+ };
767
856
  type PluginFactoryOptions<
768
857
  /**
769
858
  * Name to be used for the plugin.
@@ -784,14 +873,25 @@ TContext = unknown,
784
873
  /**
785
874
  * When calling `resolvePath` you can specify better types.
786
875
  */
787
- TResolvePathOptions extends object = object> = {
876
+ TResolvePathOptions extends object = object,
877
+ /**
878
+ * Resolver object that encapsulates the naming and path-resolution helpers used by this plugin.
879
+ * Use `defineResolver` to define the resolver object and export it alongside the plugin.
880
+ */
881
+ TResolver extends Resolver = Resolver,
882
+ /**
883
+ * Builder object that encapsulates the schema-building helpers used by this plugin.
884
+ * Use `defineBuilder` to define the builder object and export it alongside the plugin.
885
+ */
886
+ TBuilder extends Builder = Builder> = {
788
887
  name: TName;
789
888
  options: TOptions;
790
889
  resolvedOptions: TResolvedOptions;
791
890
  context: TContext;
792
891
  resolvePathOptions: TResolvePathOptions;
892
+ resolver: TResolver;
893
+ builder: TBuilder;
793
894
  };
794
- type GetPluginFactoryOptions<TPlugin extends UserPlugin> = TPlugin extends UserPlugin<infer X> ? X : never;
795
895
  type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
796
896
  /**
797
897
  * Unique name used for the plugin
@@ -815,7 +915,7 @@ type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> =
815
915
  inject?: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context'];
816
916
  };
817
917
  type UserPluginWithLifeCycle<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = UserPlugin<TOptions> & PluginLifecycle<TOptions>;
818
- type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<any, any, any, any, any>>;
918
+ type UnknownUserPlugin = UserPlugin<PluginFactoryOptions<string, object, object, unknown, object>>;
819
919
  type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
820
920
  /**
821
921
  * Unique name used for the plugin
@@ -837,7 +937,7 @@ type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
837
937
  options: TOptions['resolvedOptions'];
838
938
  install: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => PossiblePromise<void>;
839
939
  /**
840
- * Define a context that can be used by other plugins, see `PluginManager' where we convert from `UserPlugin` to `Plugin`(used when calling `definePlugin`).
940
+ * Defines a context that can be used by other plugins, see `PluginDriver` where we convert from `UserPlugin` to `Plugin` (used when calling `createPlugin`).
841
941
  */
842
942
  inject: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context'];
843
943
  };
@@ -853,6 +953,7 @@ type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOption
853
953
  * Options can als be included.
854
954
  * @type hookFirst
855
955
  * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
956
+ * @deprecated this will be replaced by resolvers
856
957
  */
857
958
  resolvePath?: (this: PluginContext<TOptions>, baseName: KubbFile.BaseName, mode?: KubbFile.Mode, options?: TOptions['resolvePathOptions']) => KubbFile.Path;
858
959
  /**
@@ -860,6 +961,7 @@ type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactoryOption
860
961
  * Useful when converting to PascalCase or camelCase.
861
962
  * @type hookFirst
862
963
  * @example ('pet') => 'Pet'
964
+ * @deprecated this will be replaced by resolvers
863
965
  */
864
966
  resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string;
865
967
  };
@@ -890,7 +992,7 @@ type ResolveNameParams = {
890
992
  type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
891
993
  fabric: Fabric;
892
994
  config: Config;
893
- pluginManager: PluginManager;
995
+ driver: PluginDriver;
894
996
  /**
895
997
  * Only add when the file does not exist yet
896
998
  */
@@ -905,22 +1007,30 @@ type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
905
1007
  * Current plugin
906
1008
  */
907
1009
  plugin: Plugin<TOptions>;
908
- /**
909
- * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
910
- * Returns `undefined` when no adapter was set (legacy OAS-only usage).
911
- */
912
- rootNode: RootNode | undefined;
913
1010
  /**
914
1011
  * Opens the Kubb Studio URL for the current `rootNode` in the default browser.
915
1012
  * Falls back to printing the URL if the browser cannot be launched.
916
1013
  * No-ops silently when no adapter has set a `rootNode`.
917
1014
  */
918
1015
  openInStudio: (options?: DevtoolsOptions) => Promise<void>;
919
- } & Kubb.PluginContext;
1016
+ } & ({
1017
+ /**
1018
+ * Returns the universal `@kubb/ast` `RootNode` produced by the configured adapter.
1019
+ * Returns `undefined` when no adapter was set (legacy OAS-only usage).
1020
+ */
1021
+ rootNode: RootNode;
1022
+ /**
1023
+ * Return the adapter from `@kubb/ast`
1024
+ */
1025
+ adapter: Adapter;
1026
+ } | {
1027
+ rootNode?: never;
1028
+ adapter?: never;
1029
+ }) & Kubb.PluginContext;
920
1030
  /**
921
1031
  * Specify the export location for the files and define the behavior of the output
922
1032
  */
923
- type Output<TOptions> = {
1033
+ type Output<_TOptions = unknown> = {
924
1034
  /**
925
1035
  * Path to the output folder or file that will contain the generated code
926
1036
  */
@@ -933,20 +1043,17 @@ type Output<TOptions> = {
933
1043
  /**
934
1044
  * Add a banner text in the beginning of every file
935
1045
  */
936
- banner?: string | ((options: TOptions) => string);
1046
+ banner?: string | ((node: RootNode) => string);
937
1047
  /**
938
1048
  * Add a footer text in the beginning of every file
939
1049
  */
940
- footer?: string | ((options: TOptions) => string);
1050
+ footer?: string | ((node: RootNode) => string);
941
1051
  /**
942
1052
  * Whether to override existing external files if they already exist.
943
1053
  * @default false
944
1054
  */
945
1055
  override?: boolean;
946
1056
  };
947
- type GroupContext = {
948
- group: string;
949
- };
950
1057
  type Group = {
951
1058
  /**
952
1059
  * Defines the type where to group the files.
@@ -956,9 +1063,11 @@ type Group = {
956
1063
  */
957
1064
  type: 'tag' | 'path';
958
1065
  /**
959
- * Return the name of a group based on the group name, this used for the file and name generation
1066
+ * Return the name of a group based on the group name, this is used for the file and name generation.
960
1067
  */
961
- name?: (context: GroupContext) => string;
1068
+ name?: (context: {
1069
+ group: string;
1070
+ }) => string;
962
1071
  };
963
1072
  type LoggerOptions = {
964
1073
  /**
@@ -969,13 +1078,293 @@ type LoggerOptions = {
969
1078
  /**
970
1079
  * Shared context passed to all plugins, parsers, and Fabric internals.
971
1080
  */
972
- interface LoggerContext extends AsyncEventEmitter<KubbEvents> {}
973
- type Install<TOptions = unknown> = (context: LoggerContext, options?: TOptions) => void | Promise<void>;
1081
+ type LoggerContext = AsyncEventEmitter<KubbEvents>;
974
1082
  type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
975
1083
  name: string;
976
- install: Install<TOptions>;
1084
+ install: (context: LoggerContext, options?: TOptions) => void | Promise<void>;
1085
+ };
1086
+ type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>;
1087
+ /**
1088
+ * Compatibility preset for code generation tools.
1089
+ * - `'default'` – no compatibility adjustments (default behavior).
1090
+ * - `'kubbV4'` – align generated names and structures with Kubb v4 output.
1091
+ */
1092
+ type CompatibilityPreset = 'default' | 'kubbV4';
1093
+ /**
1094
+ * A preset bundles a name, one or more resolvers, optional AST transformers,
1095
+ * and optional generators into a single reusable configuration object.
1096
+ *
1097
+ * @template TResolver - The concrete resolver type for this preset.
1098
+ */
1099
+ type Preset<TResolver extends Resolver = Resolver> = {
1100
+ /**
1101
+ * Unique identifier for this preset.
1102
+ */
1103
+ name: string;
1104
+ /**
1105
+ * Ordered list of resolvers applied by this preset (last entry wins on merge).
1106
+ */
1107
+ resolvers: Array<TResolver>;
1108
+ /**
1109
+ * Optional AST visitors / transformers applied after resolving.
1110
+ */
1111
+ transformers?: Array<Visitor>;
1112
+ /**
1113
+ * Optional generators used by this preset. Plugin implementations cast this
1114
+ * to their concrete generator type.
1115
+ */
1116
+ generators?: Array<Generator<any>>;
1117
+ };
1118
+ /**
1119
+ * A named registry of presets, keyed by preset name.
1120
+ *
1121
+ * @template TResolver - The concrete resolver type shared by all presets in this registry.
1122
+ * @template TName - The union of valid preset name keys.
1123
+ */
1124
+ type Presets<TResolver extends Resolver = Resolver> = Record<CompatibilityPreset, Preset<TResolver>>;
1125
+ type ByTag = {
1126
+ type: 'tag';
1127
+ pattern: string | RegExp;
1128
+ };
1129
+ type ByOperationId = {
1130
+ type: 'operationId';
1131
+ pattern: string | RegExp;
1132
+ };
1133
+ type ByPath = {
1134
+ type: 'path';
1135
+ pattern: string | RegExp;
1136
+ };
1137
+ type ByMethod = {
1138
+ type: 'method';
1139
+ pattern: HttpMethod | RegExp;
1140
+ };
1141
+ type BySchemaName = {
1142
+ type: 'schemaName';
1143
+ pattern: string | RegExp;
1144
+ };
1145
+ type ByContentType = {
1146
+ type: 'contentType';
1147
+ pattern: string | RegExp;
1148
+ };
1149
+ type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
1150
+ type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName;
1151
+ type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
1152
+ options: Partial<TOptions>;
1153
+ };
1154
+ type ResolvePathOptions = {
1155
+ pluginName?: string;
1156
+ group?: {
1157
+ tag?: string;
1158
+ path?: string;
1159
+ };
1160
+ type?: ResolveNameParams['type'];
1161
+ };
1162
+ /**
1163
+ * File-specific parameters for `Resolver.resolvePath`.
1164
+ *
1165
+ * Pass alongside a `ResolverContext` to identify which file to resolve.
1166
+ * Provide `tag` for tag-based grouping or `path` for path-based grouping.
1167
+ *
1168
+ * @example
1169
+ * ```ts
1170
+ * resolver.resolvePath(
1171
+ * { baseName: 'petTypes.ts', tag: 'pets' },
1172
+ * { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
1173
+ * )
1174
+ * // → '/src/types/petsController/petTypes.ts'
1175
+ * ```
1176
+ */
1177
+ type ResolverPathParams = {
1178
+ baseName: KubbFile.BaseName;
1179
+ pathMode?: KubbFile.Mode;
1180
+ /**
1181
+ * Tag value used when `group.type === 'tag'`.
1182
+ */
1183
+ tag?: string;
1184
+ /**
1185
+ * Path value used when `group.type === 'path'`.
1186
+ */
1187
+ path?: string;
1188
+ };
1189
+ /**
1190
+ * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
1191
+ *
1192
+ * Describes where on disk output is rooted, which output config is active, and the optional
1193
+ * grouping strategy that controls subdirectory layout.
1194
+ *
1195
+ * @example
1196
+ * ```ts
1197
+ * const context: ResolverContext = {
1198
+ * root: config.root,
1199
+ * output,
1200
+ * group,
1201
+ * }
1202
+ * ```
1203
+ */
1204
+ type ResolverContext = {
1205
+ root: string;
1206
+ output: Output;
1207
+ group?: Group; /** Plugin name used to populate `meta.pluginName` on the resolved file. */
1208
+ pluginName?: string;
1209
+ };
1210
+ /**
1211
+ * File-specific parameters for `Resolver.resolveFile`.
1212
+ *
1213
+ * Pass alongside a `ResolverContext` to fully describe the file to resolve.
1214
+ * `tag` and `path` are used only when a matching `group` is present in the context.
1215
+ *
1216
+ * @example
1217
+ * ```ts
1218
+ * resolver.resolveFile(
1219
+ * { name: 'listPets', extname: '.ts', tag: 'pets' },
1220
+ * { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
1221
+ * )
1222
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
1223
+ * ```
1224
+ */
1225
+ type ResolverFileParams = {
1226
+ name: string;
1227
+ extname: KubbFile.Extname; /** Tag value used when `group.type === 'tag'`. */
1228
+ tag?: string; /** Path value used when `group.type === 'path'`. */
1229
+ path?: string;
1230
+ };
1231
+ /**
1232
+ * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
1233
+ *
1234
+ * `output` is optional — not every plugin configures a banner/footer.
1235
+ * `config` carries the global Kubb config, used to derive the default Kubb banner.
1236
+ *
1237
+ * @example
1238
+ * ```ts
1239
+ * resolver.resolveBanner(rootNode, { output: { banner: '// generated' }, config })
1240
+ * // → '// generated'
1241
+ * ```
1242
+ */
1243
+ type ResolveBannerContext = {
1244
+ output?: Pick<Output, 'banner' | 'footer'>;
1245
+ config: Config;
1246
+ };
1247
+ //#endregion
1248
+ //#region src/PluginDriver.d.ts
1249
+ type RequiredPluginLifecycle = Required<PluginLifecycle>;
1250
+ type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookSeq';
1251
+ type ParseResult<H extends PluginLifecycleHooks> = RequiredPluginLifecycle[H];
1252
+ type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseResult<H>>> = {
1253
+ result: Result;
1254
+ plugin: Plugin;
1255
+ };
1256
+ type Options = {
1257
+ fabric: Fabric;
1258
+ events: AsyncEventEmitter<KubbEvents>;
1259
+ /**
1260
+ * @default Number.POSITIVE_INFINITY
1261
+ */
1262
+ concurrency?: number;
1263
+ };
1264
+ type GetFileOptions<TOptions = object> = {
1265
+ name: string;
1266
+ mode?: KubbFile.Mode;
1267
+ extname: KubbFile.Extname;
1268
+ pluginName: string;
1269
+ options?: TOptions;
977
1270
  };
978
- type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Omit<Logger<TOptions>, 'logLevel'>;
1271
+ declare function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode;
1272
+ declare class PluginDriver {
1273
+ #private;
1274
+ readonly config: Config;
1275
+ readonly options: Options;
1276
+ /**
1277
+ * The universal `@kubb/ast` `RootNode` produced by the adapter, set by
1278
+ * the build pipeline after the adapter's `parse()` resolves.
1279
+ */
1280
+ rootNode: RootNode | undefined;
1281
+ adapter: Adapter | undefined;
1282
+ constructor(config: Config, options: Options);
1283
+ get events(): AsyncEventEmitter<KubbEvents>;
1284
+ getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown>;
1285
+ get plugins(): Array<Plugin>;
1286
+ getFile<TOptions = object>({
1287
+ name,
1288
+ mode,
1289
+ extname,
1290
+ pluginName,
1291
+ options
1292
+ }: GetFileOptions<TOptions>): KubbFile.File<{
1293
+ pluginName: string;
1294
+ }>;
1295
+ resolvePath: <TOptions = object>(params: ResolvePathParams<TOptions>) => KubbFile.Path;
1296
+ resolveName: (params: ResolveNameParams) => string;
1297
+ /**
1298
+ * Run a specific hookName for plugin x.
1299
+ */
1300
+ hookForPlugin<H extends PluginLifecycleHooks>({
1301
+ pluginName,
1302
+ hookName,
1303
+ parameters
1304
+ }: {
1305
+ pluginName: string;
1306
+ hookName: H;
1307
+ parameters: PluginParameter<H>;
1308
+ }): Promise<Array<ReturnType<ParseResult<H>> | null>>;
1309
+ /**
1310
+ * Run a specific hookName for plugin x.
1311
+ */
1312
+ hookForPluginSync<H extends PluginLifecycleHooks>({
1313
+ pluginName,
1314
+ hookName,
1315
+ parameters
1316
+ }: {
1317
+ pluginName: string;
1318
+ hookName: H;
1319
+ parameters: PluginParameter<H>;
1320
+ }): Array<ReturnType<ParseResult<H>>> | null;
1321
+ /**
1322
+ * Returns the first non-null result.
1323
+ */
1324
+ hookFirst<H extends PluginLifecycleHooks>({
1325
+ hookName,
1326
+ parameters,
1327
+ skipped
1328
+ }: {
1329
+ hookName: H;
1330
+ parameters: PluginParameter<H>;
1331
+ skipped?: ReadonlySet<Plugin> | null;
1332
+ }): Promise<SafeParseResult<H>>;
1333
+ /**
1334
+ * Returns the first non-null result.
1335
+ */
1336
+ hookFirstSync<H extends PluginLifecycleHooks>({
1337
+ hookName,
1338
+ parameters,
1339
+ skipped
1340
+ }: {
1341
+ hookName: H;
1342
+ parameters: PluginParameter<H>;
1343
+ skipped?: ReadonlySet<Plugin> | null;
1344
+ }): SafeParseResult<H> | null;
1345
+ /**
1346
+ * Runs all plugins in parallel based on `this.plugin` order and `pre`/`post` settings.
1347
+ */
1348
+ hookParallel<H extends PluginLifecycleHooks, TOutput = void>({
1349
+ hookName,
1350
+ parameters
1351
+ }: {
1352
+ hookName: H;
1353
+ parameters?: Parameters<RequiredPluginLifecycle[H]> | undefined;
1354
+ }): Promise<Awaited<TOutput>[]>;
1355
+ /**
1356
+ * Chains plugins
1357
+ */
1358
+ hookSeq<H extends PluginLifecycleHooks>({
1359
+ hookName,
1360
+ parameters
1361
+ }: {
1362
+ hookName: H;
1363
+ parameters?: PluginParameter<H>;
1364
+ }): Promise<void>;
1365
+ getPluginByName(pluginName: string): Plugin | undefined;
1366
+ getPluginsByName(hookName: keyof PluginWithLifeCycle, pluginName: string): Plugin[];
1367
+ }
979
1368
  //#endregion
980
- export { UserPluginWithLifeCycle as A, URLPath as B, PrinterFactoryOptions as C, UserConfig as D, UnknownUserPlugin as E, defineStorage as F, formatters as I, linters as L, PluginManager as M, getMode as N, UserLogger as O, DefineStorage as P, logLevel as R, Printer as S, ResolvePathParams as T, PluginFactoryOptions as _, Config as a, PluginParameter as b, Group as c, Logger as d, LoggerContext as f, PluginContext as g, Plugin as h, BarrelType as i, KubbEvents as j, UserPlugin as k, InputData as l, Output as m, AdapterFactoryOptions as n, DevtoolsOptions as o, LoggerOptions as p, AdapterSource as r, GetPluginFactoryOptions as s, Adapter as t, InputPath as u, PluginLifecycle as v, ResolveNameParams as w, PluginWithLifeCycle as x, PluginLifecycleHooks as y, AsyncEventEmitter as z };
981
- //# sourceMappingURL=types-B7eZvqwD.d.ts.map
1369
+ export { formatters as $, Printer as A, ResolverPathParams as B, PluginFactoryOptions as C, PluginWithLifeCycle as D, PluginParameter as E, ResolvePathOptions as F, UserResolver as G, UserLogger as H, ResolvePathParams as I, Generator as J, KubbEvents as K, Resolver as L, ResolveBannerContext as M, ResolveNameParams as N, Preset as O, ResolveOptionsContext as P, createStorage as Q, ResolverContext as R, PluginContext as S, PluginLifecycleHooks as T, UserPlugin as U, UserConfig as V, UserPluginWithLifeCycle as W, defineGenerator as X, ReactGeneratorV2 as Y, Storage as Z, LoggerContext as _, AdapterSource as a, Override as b, CompatibilityPreset as c, Exclude as d, linters as et, Group as f, Logger as g, InputPath as h, AdapterFactoryOptions as i, PrinterFactoryOptions as j, Presets as k, Config as l, InputData as m, getMode as n, PossiblePromise as nt, BarrelType as o, Include as p, CoreGeneratorV2 as q, Adapter as r, AsyncEventEmitter as rt, Builder as s, PluginDriver as t, logLevel as tt, DevtoolsOptions as u, LoggerOptions as v, PluginLifecycle as w, Plugin as x, Output as y, ResolverFileParams as z };
1370
+ //# sourceMappingURL=PluginDriver-CEQPafXV.d.ts.map