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

package/dist/index.cjs

@@ -971,6 +971,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 (0, node_path.extname)(fileOrFolder) ? "single" : "split";
@@ -1469,7 +1478,7 @@ const fsStorage = createStorage(() => ({
 }));
 //#endregion
 //#region package.json
-var version = "5.0.0-alpha.20";
+var version = "5.0.0-alpha.22";
 //#endregion
 //#region src/utils/diagnostics.ts
 /**
@@ -1857,6 +1866,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 {
@@ -1906,8 +1935,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'
@@ -1918,12 +1947,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
@@ -1958,6 +1992,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) {
@@ -1967,7 +2002,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);
@@ -1976,8 +2015,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 ((0, _kubb_ast.isOperationNode)(node)) {
@@ -2004,27 +2062,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(node_path.default.resolve(root, output.path))) === "single") return node_path.default.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 node_path.default.resolve(root, output.path, groupName({ group: group.type === "path" ? groupPath : tag }), baseName);
+	}
+	return node_path.default.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(node_path.default.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: node_path.default.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 = node_path.default.basename(first.path);
+		} else if ("path" in config.input) source = node_path.default.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()
 	};
 }
@@ -2034,13 +2310,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 = (0, _kubb_react_fabric.createReactFabric)();
 	await fabricChild.render(/* @__PURE__ */ (0, _kubb_react_fabric_jsx_runtime.jsx)(_kubb_react_fabric.Fabric, {
-		meta: { plugin },
+		meta: {
+			plugin,
+			driver
+		},
 		children: /* @__PURE__ */ (0, _kubb_react_fabric_jsx_runtime.jsx)(Component, {
 			config,
+			plugin,
 			adapter,
 			nodes,
 			options: options.options
@@ -2053,17 +2333,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 = (0, _kubb_react_fabric.createReactFabric)();
 	await fabricChild.render(/* @__PURE__ */ (0, _kubb_react_fabric_jsx_runtime.jsx)(_kubb_react_fabric.Fabric, {
 		meta: {
 			plugin,
-			driver,
-			mode
+			driver
 		},
 		children: /* @__PURE__ */ (0, _kubb_react_fabric_jsx_runtime.jsx)(Component, {
 			config,
+			plugin,
 			adapter,
 			node,
 			options: options.options
@@ -2076,17 +2356,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 = (0, _kubb_react_fabric.createReactFabric)();
 	await fabricChild.render(/* @__PURE__ */ (0, _kubb_react_fabric_jsx_runtime.jsx)(_kubb_react_fabric.Fabric, {
 		meta: {
 			plugin,
-			driver,
-			mode
+			driver
 		},
 		children: /* @__PURE__ */ (0, _kubb_react_fabric_jsx_runtime.jsx)(Component, {
 			config,
+			plugin,
 			adapter,
 			node,
 			options: options.options
@@ -2262,7 +2542,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
@@ -2304,24 +2584,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);
@@ -2407,7 +2702,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: (0, node_path.join)(treeNode.parent?.data.path, "index.ts"),
 			baseName: "index.ts",
@@ -2494,7 +2789,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) => ({
@@ -2505,21 +2808,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
 	};
 }
@@ -2611,11 +2918,17 @@ exports.FunctionParams = FunctionParams;
 exports.PluginDriver = PluginDriver;
 exports.URLPath = URLPath;
 exports.build = build;
+exports.buildDefaultBanner = buildDefaultBanner;
 exports.createAdapter = createAdapter;
 exports.createPlugin = createPlugin;
 exports.createStorage = createStorage;
 exports.default = build;
+exports.defaultResolveBanner = defaultResolveBanner;
+exports.defaultResolveFile = defaultResolveFile;
+exports.defaultResolveFooter = defaultResolveFooter;
 exports.defaultResolveOptions = defaultResolveOptions;
+exports.defaultResolvePath = defaultResolvePath;
+exports.defineBuilder = defineBuilder;
 exports.defineConfig = defineConfig;
 exports.defineGenerator = defineGenerator;
 exports.defineLogger = defineLogger;