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

package/dist/index.js

@@ -1463,7 +1463,7 @@ const fsStorage = createStorage(() => ({
 }));
 //#endregion
 //#region package.json
-var version$1 = "5.0.0-alpha.20";
+var version$1 = "5.0.0-alpha.21";
 //#endregion
 //#region src/utils/diagnostics.ts
 /**
@@ -1851,6 +1851,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 +1920,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 +1932,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 +1977,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 +1987,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 +2000,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 +2047,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 `KubbFile.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 `KubbFile.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(node) {
+*     return this.default(node.name, 'type')
 *   },
-*   resolveTypedName(name) {
-*     return this.default(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 +2295,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 +2318,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 +2341,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
@@ -2401,7 +2672,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",
@@ -2499,21 +2770,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 +2875,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