@kubb/core 5.0.0-alpha.20 → 5.0.0-alpha.22

package/dist/index.js

@@ -965,6 +965,15 @@ function hookParallel(promises, concurrency = Number.POSITIVE_INFINITY) {
 }
 //#endregion
 //#region src/PluginDriver.ts
+/**
+* Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
+*
+* @example
+* ```ts
+* getMode('src/gen/types.ts')  // 'single'
+* getMode('src/gen/types')     // 'split'
+* ```
+*/
 function getMode(fileOrFolder) {
 	if (!fileOrFolder) return "split";
 	return extname(fileOrFolder) ? "single" : "split";
@@ -1463,7 +1472,7 @@ const fsStorage = createStorage(() => ({
 }));
 //#endregion
 //#region package.json
-var version$1 = "5.0.0-alpha.20";
+var version$1 = "5.0.0-alpha.22";
 //#endregion
 //#region src/utils/diagnostics.ts
 /**
@@ -1851,6 +1860,26 @@ function createPlugin(build) {
 	return (options) => build(options ?? {});
 }
 //#endregion
+//#region src/defineBuilder.ts
+/**
+* Defines a builder for a plugin — a named collection of schema-building helpers that
+* can be exported alongside the plugin and imported by other plugins or generators.
+*
+* @example
+* export const builder = defineBuilder<PluginTs>(() => ({
+*   name: 'default',
+*   buildParamsSchema({ params, node, resolver }) {
+*     return createSchema({ type: 'object', properties: [] })
+*   },
+*   buildDataSchemaNode({ node, resolver }) {
+*     return createSchema({ type: 'object', properties: [] })
+*   },
+* }))
+*/
+function defineBuilder(build) {
+	return build();
+}
+//#endregion
 //#region src/defineGenerator.ts
 function defineGenerator(generator) {
 	if (generator.type === "react") return {
@@ -1900,8 +1929,8 @@ function defineLogger(logger) {
 //#endregion
 //#region src/definePreset.ts
 /**
-* Creates a typed preset object that bundles a name, resolvers, and optional
-* transformers — the building block for composable plugin presets.
+* Creates a typed preset object that bundles a name, resolvers, optional
+* transformers, and optional generators — the building block for composable plugin presets.
 *
 * @example
 * import { definePreset } from '@kubb/core'
@@ -1912,12 +1941,17 @@ function defineLogger(logger) {
 * @example
 * // With custom transformers
 * export const myPreset = definePreset('myPreset', { resolvers: [resolverTsLegacy], transformers: [myTransformer] })
+*
+* @example
+* // With generators
+* export const myPreset = definePreset('myPreset', { resolvers: [resolverTsLegacy], generators: [typeGeneratorLegacy] })
 */
-function definePreset(name, { resolvers, transformers }) {
+function definePreset(name, { resolvers, transformers, generators }) {
 	return {
 		name,
 		resolvers,
-		transformers
+		transformers,
+		generators
 	};
 }
 //#endregion
@@ -1952,6 +1986,7 @@ function matchesOperationPattern(node, type, pattern) {
 }
 /**
 * Checks if a schema matches a pattern for a given filter type (`schemaName`).
+*
 * Returns `null` when the filter type doesn't apply to schemas.
 */
 function matchesSchemaPattern(node, type, pattern) {
@@ -1961,7 +1996,11 @@ function matchesSchemaPattern(node, type, pattern) {
 	}
 }
 /**
-* Default name resolver — `camelCase` for most types, `PascalCase` for `type`.
+* Default name resolver used by `defineResolver`.
+*
+* - `camelCase` for `function` and `file` types.
+* - `PascalCase` for `type`.
+* - `camelCase` for everything else.
 */
 function defaultResolver(name, type) {
 	let resolvedName = camelCase(name);
@@ -1970,8 +2009,27 @@ function defaultResolver(name, type) {
 	return resolvedName;
 }
 /**
-* Default option resolver — applies include/exclude filters and merges any matching override options.
-* Returns `null` when the node is filtered out.
+* Default option resolver — applies include/exclude filters and merges matching override options.
+*
+* Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
+*
+* @example Include/exclude filtering
+* ```ts
+* const options = defaultResolveOptions(operationNode, {
+*   options: { output: 'types' },
+*   exclude: [{ type: 'tag', pattern: 'internal' }],
+* })
+* // → null when node has tag 'internal'
+* ```
+*
+* @example Override merging
+* ```ts
+* const options = defaultResolveOptions(operationNode, {
+*   options: { enumType: 'asConst' },
+*   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
+* })
+* // → { enumType: 'enum' } when operationId matches
+* ```
 */
 function defaultResolveOptions(node, { options, exclude = [], include, override = [] }) {
 	if (isOperationNode(node)) {
@@ -1998,27 +2056,245 @@ function defaultResolveOptions(node, { options, exclude = [], include, override
 	return options;
 }
 /**
-* Defines a resolver for a plugin, with built-in defaults for name casing and include/exclude/override filtering.
-* Override `default` or `resolveOptions` in the builder to customize the behavior.
+* Default path resolver used by `defineResolver`.
 *
-* @example
+* - Returns the output directory in `single` mode.
+* - Resolves into a tag- or path-based subdirectory when `group` and a `tag`/`path` value are provided.
+* - Falls back to a flat `output/baseName` path otherwise.
+*
+* A custom `group.name` function overrides the default subdirectory naming.
+* For `tag` groups the default is `${camelCase(tag)}Controller`.
+* For `path` groups the default is the first path segment after `/`.
+*
+* @example Flat output
+* ```ts
+* defaultResolvePath({ baseName: 'petTypes.ts' }, { root: '/src', output: { path: 'types' } })
+* // → '/src/types/petTypes.ts'
+* ```
+*
+* @example Tag-based grouping
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', tag: 'pets' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+* )
+* // → '/src/types/petsController/petTypes.ts'
+* ```
+*
+* @example Path-based grouping
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', path: '/pets/list' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'path' } },
+* )
+* // → '/src/types/pets/petTypes.ts'
+* ```
+*
+* @example Single-file mode
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', pathMode: 'single' },
+*   { root: '/src', output: { path: 'types' } },
+* )
+* // → '/src/types'
+* ```
+*/
+function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }, { root, output, group }) {
+	if ((pathMode ?? getMode(path.resolve(root, output.path))) === "single") return path.resolve(root, output.path);
+	if (group && (groupPath || tag)) {
+		const groupName = group.name ? group.name : (ctx) => {
+			if (group.type === "path") return `${ctx.group.split("/")[1]}`;
+			return `${camelCase(ctx.group)}Controller`;
+		};
+		return path.resolve(root, output.path, groupName({ group: group.type === "path" ? groupPath : tag }), baseName);
+	}
+	return path.resolve(root, output.path, baseName);
+}
+/**
+* Default file resolver used by `defineResolver`.
+*
+* Resolves a `FabricFile.File` by combining name resolution (`resolver.default`) with
+* path resolution (`resolver.resolvePath`). The resolved file always has empty
+* `sources`, `imports`, and `exports` arrays — consumers populate those separately.
+*
+* In `single` mode the name is omitted and the file sits directly in the output directory.
+*
+* @example Resolve a schema file
+* ```ts
+* const file = defaultResolveFile.call(resolver,
+*   { name: 'pet', extname: '.ts' },
+*   { root: '/src', output: { path: 'types' } },
+* )
+* // → { baseName: 'pet.ts', path: '/src/types/pet.ts', sources: [], ... }
+* ```
+*
+* @example Resolve an operation file with tag grouping
+* ```ts
+* const file = defaultResolveFile.call(resolver,
+*   { name: 'listPets', extname: '.ts', tag: 'pets' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+* )
+* // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+* ```
+*/
+function defaultResolveFile({ name, extname, tag, path: groupPath }, context) {
+	const pathMode = getMode(path.resolve(context.root, context.output.path));
+	const baseName = `${pathMode === "single" ? "" : this.default(name, "file")}${extname}`;
+	const filePath = this.resolvePath({
+		baseName,
+		pathMode,
+		tag,
+		path: groupPath
+	}, context);
+	return {
+		path: filePath,
+		baseName: path.basename(filePath),
+		meta: { pluginName: this.pluginName },
+		sources: [],
+		imports: [],
+		exports: []
+	};
+}
+/**
+* Generates the default "Generated by Kubb" banner from config and optional node metadata.
+*/
+function buildDefaultBanner({ title, description, version, config }) {
+	try {
+		let source = "";
+		if (Array.isArray(config.input)) {
+			const first = config.input[0];
+			if (first && "path" in first) source = path.basename(first.path);
+		} else if ("path" in config.input) source = path.basename(config.input.path);
+		else if ("data" in config.input) source = "text content";
+		let banner = "/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n";
+		if (config.output.defaultBanner === "simple") {
+			banner += "*/\n";
+			return banner;
+		}
+		if (source) banner += `* Source: ${source}\n`;
+		if (title) banner += `* Title: ${title}\n`;
+		if (description) {
+			const formattedDescription = description.replace(/\n/gm, "\n* ");
+			banner += `* Description: ${formattedDescription}\n`;
+		}
+		if (version) banner += `* OpenAPI spec version: ${version}\n`;
+		banner += "*/\n";
+		return banner;
+	} catch (_error) {
+		return "/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n*/";
+	}
+}
+/**
+* Default banner resolver — returns the banner string for a generated file.
+*
+* - When `output.banner` is a function and `node` is provided, calls it with the node.
+* - When `output.banner` is a function and `node` is absent, falls back to the default Kubb banner.
+* - When `output.banner` is a string, returns it directly.
+* - When `config.output.defaultBanner` is `false`, returns `undefined`.
+* - Otherwise returns the default "Generated by Kubb" banner.
+*
+* @example String banner
+* ```ts
+* defaultResolveBanner(undefined, { output: { banner: '// my banner' }, config })
+* // → '// my banner'
+* ```
+*
+* @example Function banner with node
+* ```ts
+* defaultResolveBanner(rootNode, { output: { banner: (node) => `// v${node.version}` }, config })
+* // → '// v3.0.0'
+* ```
+*
+* @example Disabled banner
+* ```ts
+* defaultResolveBanner(undefined, { config: { output: { defaultBanner: false }, ...config } })
+* // → undefined
+* ```
+*/
+function defaultResolveBanner(node, { output, config }) {
+	if (typeof output?.banner === "function") return node ? output.banner(node) : buildDefaultBanner({ config });
+	if (typeof output?.banner === "string") return output.banner;
+	if (config.output.defaultBanner === false) return;
+	return buildDefaultBanner({ config });
+}
+/**
+* Default footer resolver — returns the footer string for a generated file.
+*
+* - When `output.footer` is a function and `node` is provided, calls it with the node.
+* - When `output.footer` is a function and `node` is absent, returns `undefined`.
+* - When `output.footer` is a string, returns it directly.
+* - Otherwise returns `undefined`.
+*
+* @example String footer
+* ```ts
+* defaultResolveFooter(undefined, { output: { footer: '// end of file' }, config })
+* // → '// end of file'
+* ```
+*
+* @example Function footer with node
+* ```ts
+* defaultResolveFooter(rootNode, { output: { footer: (node) => `// ${node.title}` }, config })
+* // → '// Pet Store'
+* ```
+*/
+function defaultResolveFooter(node, { output }) {
+	if (typeof output?.footer === "function") return node ? output.footer(node) : void 0;
+	if (typeof output?.footer === "string") return output.footer;
+}
+/**
+* Defines a resolver for a plugin, injecting built-in defaults for name casing,
+* include/exclude/override filtering, path resolution, and file construction.
+*
+* All four defaults can be overridden by providing them in the builder function:
+* - `default` — name casing strategy (camelCase / PascalCase)
+* - `resolveOptions` — include/exclude/override filtering
+* - `resolvePath` — output path computation
+* - `resolveFile` — full `FabricFile.File` construction
+*
+* Methods in the builder have access to `this` (the full resolver object), so they
+* can call other resolver methods without circular imports.
+*
+* @example Basic resolver with naming helpers
+* ```ts
 * export const resolver = defineResolver<PluginTs>(() => ({
 *   name: 'default',
-*   resolveName(name) {
-*     return this.default(name, 'function')
+*   resolveName(node) {
+*     return this.default(node.name, 'function')
 *   },
-*   resolveTypedName(name) {
-*     return this.default(name, 'type')
+*   resolveTypedName(node) {
+*     return this.default(node.name, 'type')
 *   },
+* }))
+* ```
+*
+* @example Override resolvePath for a custom output structure
+* ```ts
+* export const resolver = defineResolver<PluginTs>(() => ({
+*   name: 'custom',
+*   resolvePath({ baseName }, { root, output }) {
+*     return path.resolve(root, output.path, 'generated', baseName)
+*   },
+* }))
+* ```
+*
+* @example Use this.default inside a helper
+* ```ts
+* export const resolver = defineResolver<PluginTs>(() => ({
+*   name: 'default',
 *   resolveParamName(node, param) {
-*     return this.resolveName(`${node.operationId} ${param.in} ${param.name}`)
+*     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
 *   },
 * }))
+* ```
 */
 function defineResolver(build) {
 	return {
 		default: defaultResolver,
 		resolveOptions: defaultResolveOptions,
+		resolvePath: defaultResolvePath,
+		resolveFile: defaultResolveFile,
+		resolveBanner: defaultResolveBanner,
+		resolveFooter: defaultResolveFooter,
 		...build()
 	};
 }
@@ -2028,13 +2304,17 @@ function defineResolver(build) {
 * Renders a React component for a list of operation nodes (V2 generators).
 */
 async function renderOperations(nodes, options) {
-	const { config, fabric, plugin, Component, adapter } = options;
+	const { config, fabric, plugin, Component, driver, adapter } = options;
 	if (!Component) return;
 	const fabricChild = createReactFabric();
 	await fabricChild.render(/* @__PURE__ */ jsx(Fabric, {
-		meta: { plugin },
+		meta: {
+			plugin,
+			driver
+		},
 		children: /* @__PURE__ */ jsx(Component, {
 			config,
+			plugin,
 			adapter,
 			nodes,
 			options: options.options
@@ -2047,17 +2327,17 @@ async function renderOperations(nodes, options) {
 * Renders a React component for a single operation node (V2 generators).
 */
 async function renderOperation(node, options) {
-	const { config, fabric, plugin, Component, adapter, driver, mode } = options;
+	const { config, fabric, plugin, Component, adapter, driver } = options;
 	if (!Component) return;
 	const fabricChild = createReactFabric();
 	await fabricChild.render(/* @__PURE__ */ jsx(Fabric, {
 		meta: {
 			plugin,
-			driver,
-			mode
+			driver
 		},
 		children: /* @__PURE__ */ jsx(Component, {
 			config,
+			plugin,
 			adapter,
 			node,
 			options: options.options
@@ -2070,17 +2350,17 @@ async function renderOperation(node, options) {
 * Renders a React component for a single schema node (V2 generators).
 */
 async function renderSchema(node, options) {
-	const { config, fabric, plugin, Component, adapter, driver, mode } = options;
+	const { config, fabric, plugin, Component, adapter, driver } = options;
 	if (!Component) return;
 	const fabricChild = createReactFabric();
 	await fabricChild.render(/* @__PURE__ */ jsx(Fabric, {
 		meta: {
 			plugin,
-			driver,
-			mode
+			driver
 		},
 		children: /* @__PURE__ */ jsx(Component, {
 			config,
+			plugin,
 			adapter,
 			node,
 			options: options.options
@@ -2256,7 +2536,7 @@ async function detectFormatter() {
 //#region src/utils/TreeNode.ts
 /**
 * Tree structure used to build per-directory barrel (`index.ts`) files from a
-* flat list of generated {@link KubbFile.File} entries.
+* flat list of generated {@link FabricFile.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
@@ -2298,24 +2578,39 @@ var TreeNode = class TreeNode {
 		this.#cachedLeaves = leaves;
 		return leaves;
 	}
+	/**
+	* Visits this node and every descendant in depth-first order.
+	*/
 	forEach(callback) {
 		if (typeof callback !== "function") throw new TypeError("forEach() callback must be a function");
 		callback(this);
 		for (const child of this.children) child.forEach(callback);
 		return this;
 	}
+	/**
+	* Finds the first leaf that satisfies `predicate`, or `undefined` when none match.
+	*/
 	findDeep(predicate) {
 		if (typeof predicate !== "function") throw new TypeError("find() predicate must be a function");
 		return this.leaves.find(predicate);
 	}
+	/**
+	* Calls `callback` for every leaf of this node.
+	*/
 	forEachDeep(callback) {
 		if (typeof callback !== "function") throw new TypeError("forEach() callback must be a function");
 		this.leaves.forEach(callback);
 	}
+	/**
+	* Returns all leaves that satisfy `callback`.
+	*/
 	filterDeep(callback) {
 		if (typeof callback !== "function") throw new TypeError("filter() callback must be a function");
 		return this.leaves.filter(callback);
 	}
+	/**
+	* Maps every leaf through `callback` and returns the resulting array.
+	*/
 	mapDeep(callback) {
 		if (typeof callback !== "function") throw new TypeError("map() callback must be a function");
 		return this.leaves.map(callback);
@@ -2401,7 +2696,7 @@ function buildDirectoryTree(files, rootFolder = "") {
 function getBarrelFilesByRoot(root, files) {
 	const cachedFiles = /* @__PURE__ */ new Map();
 	TreeNode.build(files, root)?.forEach((treeNode) => {
-		if (!treeNode || !treeNode.children || !treeNode.parent?.data.path) return;
+		if (!treeNode?.children || !treeNode.parent?.data.path) return;
 		const barrelFile = {
 			path: join(treeNode.parent?.data.path, "index.ts"),
 			baseName: "index.ts",
@@ -2488,7 +2783,15 @@ async function getConfigs(config, args) {
 //#endregion
 //#region src/utils/mergeResolvers.ts
 /**
-* Merges an array of resolvers into a single resolver. Later entries override earlier ones (last wins).
+* Merges an ordered list of resolvers into a single resolver by shallow-merging each entry left to right.
+*
+* Later entries win when keys conflict, so the last resolver in the list takes highest precedence.
+*
+* @example
+* ```ts
+* const resolver = mergeResolvers(resolverTs, resolverTsLegacy)
+* // resolverTsLegacy methods override resolverTs where they overlap
+* ```
 */
 function mergeResolvers(...resolvers) {
 	return resolvers.reduce((acc, curr) => ({
@@ -2499,21 +2802,25 @@ function mergeResolvers(...resolvers) {
 //#endregion
 //#region src/utils/getPreset.ts
 /**
-* Resolves a named preset into merged resolvers and transformers.
+* Resolves a named preset into merged resolvers, transformers, and generators.
 *
-* - Merges the preset's resolvers on top of the first (default) resolver to produce `baseResolver`.
+* - Merges the preset's resolvers on top of the first (default)
 * - Merges any additional user-supplied resolvers on top of that to produce the final `resolver`.
 * - Concatenates preset transformers before user-supplied transformers.
+* - Combines preset generators with user-supplied generators; falls back to the `default` preset's generators when neither provides any.
 */
 function getPreset(params) {
-	const { preset: presetName, presets, resolvers, transformers: userTransformers } = params;
+	const { preset: presetName, presets, resolvers, transformers: userTransformers, generators: userGenerators } = params;
 	const [defaultResolver, ...userResolvers] = resolvers;
 	const preset = presets[presetName];
-	const baseResolver = mergeResolvers(defaultResolver, ...preset?.resolvers ?? []);
+	const resolver = mergeResolvers(mergeResolvers(defaultResolver, ...preset?.resolvers ?? []), ...userResolvers ?? []);
+	const transformers = [...preset?.transformers ?? [], ...userTransformers ?? []];
+	const presetGenerators = preset?.generators ?? [];
+	const defaultPresetGenerators = presets["default"]?.generators ?? [];
 	return {
-		baseResolver,
-		resolver: mergeResolvers(baseResolver, ...userResolvers ?? []),
-		transformers: [...preset?.transformers ?? [], ...userTransformers ?? []],
+		resolver,
+		transformers,
+		generators: presetGenerators.length > 0 || userGenerators.length ? [...presetGenerators, ...userGenerators] : defaultPresetGenerators,
 		preset
 	};
 }
@@ -2600,6 +2907,6 @@ function satisfiesDependency(dependency, version, cwd) {
 	return satisfies(semVer, version);
 }
 //#endregion
-export { AsyncEventEmitter, FunctionParams, PluginDriver, URLPath, 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 { AsyncEventEmitter, FunctionParams, PluginDriver, URLPath, build, build as default, buildDefaultBanner, createAdapter, createPlugin, createStorage, defaultResolveBanner, defaultResolveFile, defaultResolveFooter, defaultResolveOptions, defaultResolvePath, defineBuilder, 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.js.map