@kubb/parser-ts 5.0.0-beta.8 → 5.0.0-beta.80

package/dist/index.cjs

@@ -25,10 +25,29 @@ let _kubb_core = require("@kubb/core");
 let node_path = require("node:path");
 let typescript = require("typescript");
 typescript = __toESM(typescript, 1);
-//#region src/constants.ts
+//#region ../../internals/utils/src/fs.ts
 /**
-* Matches the trailing `.<ext>` segment of a path (keeps segments like `foo.bar.ts`
-* intact by only trimming the last run of non-`/`/`.` characters).
+* Strips the file extension from a path or file name.
+* Only removes the last `.ext` segment when the dot is not part of a directory name.
+*
+* @example
+* trimExtName('petStore.ts')             // 'petStore'
+* trimExtName('/src/models/pet.ts')      // '/src/models/pet'
+* trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'
+* trimExtName('noExtension')             // 'noExtension'
+*/
+function trimExtName(text) {
+	const dotIndex = text.lastIndexOf(".");
+	if (dotIndex > 0 && !text.includes("/", dotIndex)) return text.slice(0, dotIndex);
+	return text;
+}
+/**
+* Indentation unit prepended once per nesting level when pretty-printing.
+*/
+const INDENT = " ".repeat(2);
+/**
+* Matches only the final `.<ext>` of a path, so a name like `foo.bar.ts` keeps
+* `foo.bar` and loses just `.ts`.
 */
 const FILE_EXTENSION_PATTERN = /\.[^/.]+$/;
 /**
@@ -36,28 +55,28 @@ const FILE_EXTENSION_PATTERN = /\.[^/.]+$/;
 */
 const WINDOWS_PATH_SEPARATOR = /\\/g;
 /**
-* Matches `*\/` in free-form text so JSDoc bodies can neutralise premature
+* Matches `*\/` in free-form text so JSDoc bodies can neutralize premature
 * comment terminators (`*\/` → `* /`).
 */
 const JSDOC_TERMINATOR_PATTERN = /\*\//g;
 /**
-* Matches carriage returns for normalising CRLF/CR line endings to LF.
+* Matches carriage returns for normalizing CRLF/CR line endings to LF.
 */
 const CARRIAGE_RETURN_PATTERN = /\r/g;
 /**
-* Matches CRLF sequences used when normalising TypeScript printer output.
+* Matches CRLF sequences used when normalizing TypeScript printer output.
 */
 const CRLF_PATTERN = /\r\n/g;
 /**
-* Matches an identifier that starts with a digit — JavaScript disallows this
-* so the printer prefixes such names with `_`.
+* Matches an identifier that starts with a digit. JavaScript disallows this,
+* so the printer replaces the leading digit with `_`.
 */
 const LEADING_DIGIT_PATTERN = /^\d/;
 //#endregion
 //#region src/utils.ts
 const { factory } = typescript.default;
 /**
-* Normalises a file-system path to POSIX separators and strips any leading `../` segment.
+* Normalizes a file-system path to POSIX separators and strips any leading `../` segment.
 */
 function slash(path) {
 	return (0, node_path.normalize)(path).replaceAll(WINDOWS_PATH_SEPARATOR, "/").replace("../", "");
@@ -71,13 +90,6 @@ function getRelativePath(rootDir, filePath) {
 	return slashed.startsWith("../") ? slashed : `./${slashed}`;
 }
 /**
-* Strips the trailing file extension (for example `.ts`) from a path.
-* Preserves intermediate dots like `foo.bar.ts` → `foo.bar`.
-*/
-function trimExtName(text) {
-	return text.replace(FILE_EXTENSION_PATTERN, "");
-}
-/**
 * Rewrites an import/export path so its extension matches the caller-supplied
 * `options.extname`. When the source path has no extension the original is kept,
 * so virtual/module-only paths flow through unchanged.
@@ -88,25 +100,64 @@ function resolveOutputPath(path, options, rootAware) {
 	return rootAware ? trimExtName(path) : path;
 }
 /**
-* Serializes the body / value content from a `nodes` array.
-*
-* Each element is either a raw string or a structured {@link CodeNode}
-* (recursively converted via {@link printCodeNode}).
-* Elements are joined with `\n`.
+* Serializes a `nodes` array into source text. Each entry is rendered via {@link printCodeNode}
+* and joined with a single newline. A `Break` node (`<br/>`) inserts one blank line between
+* statements. Consecutive breaks, and breaks at the very start or end, are folded into the
+* separator, so a double `<br/>` never emits more than one blank line.
 */
 function printNodes(nodes) {
 	if (!nodes || nodes.length === 0) return "";
-	return nodes.map(printCodeNode).join("\n");
+	let result = "";
+	let hasContent = false;
+	let pendingBreak = false;
+	for (const node of nodes) {
+		if (node.kind === "Break") {
+			if (hasContent) pendingBreak = true;
+			continue;
+		}
+		const text = printCodeNode(node);
+		if (!text) continue;
+		if (hasContent) result += pendingBreak ? "\n\n" : "\n";
+		result += text;
+		hasContent = true;
+		pendingBreak = false;
+	}
+	return result;
 }
 /**
-* Indents every non-empty line of `text` by `spaces` spaces.
+* Indents every non-empty line of `text` by one indent unit. Pass a number to repeat
+* {@link INDENT_CHAR} that many times, or a string to use as the indent verbatim.
 */
-function indentLines(text, spaces = 2) {
+function indentLines(text, indent = INDENT) {
 	if (!text) return "";
-	const pad = " ".repeat(spaces);
+	const pad = typeof indent === "string" ? indent : " ".repeat(indent);
 	return text.split("\n").map((line) => line.trim() ? `${pad}${line}` : "").join("\n");
 }
 /**
+* Removes the common leading whitespace shared by every non-blank line and trims
+* surrounding blank lines, so multi-line content authored inside an indented template
+* literal lines up at a column-zero baseline. Leading whitespace is counted by
+* character, so N tabs and N spaces are treated as the same depth.
+*
+* @example
+* ```ts
+* dedent('\n    foo\n      bar\n    ')
+* // 'foo\n  bar'
+* ```
+*/
+function dedent(text) {
+	if (!text) return "";
+	const lines = text.split("\n");
+	const isBlank = (line) => line.trim() === "";
+	const start = lines.findIndex((line) => !isBlank(line));
+	if (start === -1) return "";
+	const end = lines.findLastIndex((line) => !isBlank(line));
+	const trimmed = lines.slice(start, end + 1);
+	const indents = trimmed.filter((line) => !isBlank(line)).map((line) => line.match(/^\s*/)?.[0].length ?? 0);
+	const min = indents.length ? Math.min(...indents) : 0;
+	return trimmed.map((line) => isBlank(line) ? "" : line.slice(min)).join("\n");
+}
+/**
 * Renders the generic clause (`<T, U>`) shared by function and arrow-function nodes.
 * Accepts either a raw string (rendered verbatim) or an array of type-parameter names.
 */
@@ -123,34 +174,28 @@ function formatReturnType(returnType, isAsync) {
 	return isAsync ? `: Promise<${returnType}>` : `: ${returnType}`;
 }
 /**
-* Validates TypeScript AST nodes before printing.
-* Throws an error if any node has SyntaxKind.Unknown which would cause the
-* TypeScript printer to crash.
+* Module-scoped TypeScript printer instance. A printer does not mutate the source file, so one
+* instance is reused across every `print()` call instead of constructing a new printer each time.
 */
-function validateNodes(...nodes) {
-	for (const node of nodes) {
-		if (!node) throw new Error("Attempted to print undefined or null TypeScript node");
-		if (node.kind === typescript.default.SyntaxKind.Unknown) throw new Error(`Invalid TypeScript AST node detected with SyntaxKind.Unknown. This typically indicates a schema pattern that could not be properly converted to TypeScript. Node: ${JSON.stringify(node, null, 2)}`);
-	}
-}
+const TS_PRINTER = typescript.default.createPrinter({
+	omitTrailingSemicolon: true,
+	newLine: typescript.default.NewLineKind.LineFeed,
+	removeComments: false,
+	noEmitHelpers: true
+});
 /**
-* Converts TypeScript/TSX AST nodes to a string using the TypeScript printer.
+* Module-scoped source file used as the print target. `printList` only reads the source
+* file's compiler options / language version. It never mutates it.
 */
-function print(...elements) {
-	const sourceFile = typescript.default.createSourceFile("print.tsx", "", typescript.default.ScriptTarget.ES2022, true, typescript.default.ScriptKind.TSX);
-	return typescript.default.createPrinter({
-		omitTrailingSemicolon: true,
-		newLine: typescript.default.NewLineKind.LineFeed,
-		removeComments: false,
-		noEmitHelpers: true
-	}).printList(typescript.default.ListFormat.MultiLine, factory.createNodeArray(elements.filter(Boolean)), sourceFile).replace(CRLF_PATTERN, "\n");
-}
+const PRINT_SOURCE_FILE = typescript.default.createSourceFile("print.tsx", "", typescript.default.ScriptTarget.ES2022, true, typescript.default.ScriptKind.TSX);
+TS_PRINTER.printList(typescript.default.ListFormat.MultiLine, factory.createNodeArray([]), PRINT_SOURCE_FILE);
 /**
-* Like `print` but validates nodes first to surface issues early.
+* Converts TypeScript/TSX AST nodes to a string using the TypeScript printer.
 */
-function safePrint(...elements) {
-	validateNodes(...elements);
-	return print(...elements);
+function print(...elements) {
+	const filtered = elements.filter(Boolean);
+	if (filtered.length === 0) return "";
+	return TS_PRINTER.printList(typescript.default.ListFormat.MultiLine, factory.createNodeArray(filtered), PRINT_SOURCE_FILE).replace(CRLF_PATTERN, "\n");
 }
 /**
 * Converts a {@link JSDocNode} to a JSDoc comment block string.
@@ -182,13 +227,13 @@ function printJSDoc(jsDoc) {
 *
 * @example
 * ```ts
-* printConst(createConst({ name: 'pet', export: true, nodes: ['{}'] }))
+* printConst(factory.createConst({ name: 'pet', export: true, nodes: ['{}'] }))
 * // 'export const pet = {}'
 * ```
 *
 * @example With type and `as const`
 * ```ts
-* printConst(createConst({ name: 'pets', export: true, type: 'Pet[]', asConst: true, nodes: ['[]'] }))
+* printConst(factory.createConst({ name: 'pets', export: true, type: 'Pet[]', asConst: true, nodes: ['[]'] }))
 * // 'export const pets: Pet[] = [] as const'
 * ```
 */
@@ -213,7 +258,7 @@ function printConst(node) {
 *
 * @example
 * ```ts
-* printType(createType({ name: 'Pet', export: true, nodes: ['{ id: number }'] }))
+* printType(factory.createType({ name: 'Pet', export: true, nodes: ['{ id: number }'] }))
 * // 'export type Pet = { id: number }'
 * ```
 */
@@ -236,13 +281,13 @@ function printType(node) {
 *
 * @example
 * ```ts
-* printFunction(createFunction({ name: 'getPet', export: true, params: 'id: string', returnType: 'Pet', nodes: ['return fetch(id)'] }))
+* printFunction(factory.createFunction({ name: 'getPet', export: true, params: 'id: string', returnType: 'Pet', nodes: ['return fetch(id)'] }))
 * // 'export function getPet(id: string): Pet {\n  return fetch(id)\n}'
 * ```
 *
 * @example Async with generics
 * ```ts
-* printFunction(createFunction({ name: 'fetchPet', export: true, async: true, generics: ['T'], params: 'id: string', returnType: 'T' }))
+* printFunction(factory.createFunction({ name: 'fetchPet', export: true, async: true, generics: ['T'], params: 'id: string', returnType: 'T' }))
 * // 'export async function fetchPet<T>(id: string): Promise<T> {\n}'
 * ```
 */
@@ -272,13 +317,13 @@ function printFunction(node) {
 *
 * @example Multi-line arrow function
 * ```ts
-* printArrowFunction(createArrowFunction({ name: 'getPet', export: true, params: 'id: string', nodes: ['return fetch(id)'] }))
+* printArrowFunction(factory.createArrowFunction({ name: 'getPet', export: true, params: 'id: string', nodes: ['return fetch(id)'] }))
 * // 'export const getPet = (id: string) => {\n  return fetch(id)\n}'
 * ```
 *
 * @example Single-line arrow function
 * ```ts
-* printArrowFunction(createArrowFunction({ name: 'double', params: 'n: number', singleLine: true, nodes: ['n * 2'] }))
+* printArrowFunction(factory.createArrowFunction({ name: 'double', params: 'n: number', singleLine: true, nodes: ['n * 2'] }))
 * // 'const double = (n: number) => n * 2'
 * ```
 */
@@ -307,20 +352,19 @@ function printArrowFunction(node) {
 *
 * @example
 * ```ts
-* printCodeNode(createConst({ name: 'x', nodes: ['1'] }))
+* printCodeNode(factory.createConst({ name: 'x', nodes: ['1'] }))
 * // 'const x = 1'
 * ```
 */
 function printCodeNode(node) {
-	switch (node.kind) {
-		case "Break": return "";
-		case "Text": return node.value;
-		case "Jsx": return node.value;
-		case "Const": return printConst(node);
-		case "Type": return printType(node);
-		case "Function": return printFunction(node);
-		case "ArrowFunction": return printArrowFunction(node);
-	}
+	if (node.kind === "Break") return "";
+	if (node.kind === "Text") return dedent(node.value);
+	if (node.kind === "Jsx") return dedent(node.value);
+	if (node.kind === "Const") return printConst(node);
+	if (node.kind === "Type") return printType(node);
+	if (node.kind === "Function") return printFunction(node);
+	if (node.kind === "ArrowFunction") return printArrowFunction(node);
+	return "";
 }
 /**
 * Converts a {@link SourceNode} to its TypeScript string representation.
@@ -328,77 +372,135 @@ function printCodeNode(node) {
 * Iterates `nodes` in DOM order, rendering each {@link CodeNode} via
 * {@link printCodeNode}.
 *
+* Top-level declarations are separated by a blank line so the source reads
+* cleanly without an external formatter.
+*
 * @example From nodes
 * ```ts
-* printSource({ kind: 'Source', nodes: [createConst({ name: 'x', nodes: [createText('1')] }), createText('x.toString()')] })
-* // 'const x = 1\nx.toString()'
+* printSource({ kind: 'Source', nodes: [factory.createConst({ name: 'x', nodes: [factory.createText('1')] }), factory.createText('x.toString()')] })
+* // 'const x = 1\n\nx.toString()'
 * ```
 */
 function printSource(node) {
-	if (node.nodes && node.nodes.length > 0) return node.nodes.map(printCodeNode).join("\n");
-	return "";
-}
-function createImport({ name, path, root, isTypeOnly = false, isNameSpace = false }) {
-	const resolvePath = root ? getRelativePath(root, path) : path;
-	if (!Array.isArray(name)) {
-		if (isNameSpace) return factory.createImportDeclaration(void 0, factory.createImportClause(isTypeOnly, void 0, factory.createNamespaceImport(factory.createIdentifier(name))), factory.createStringLiteral(resolvePath), void 0);
-		return factory.createImportDeclaration(void 0, factory.createImportClause(isTypeOnly, factory.createIdentifier(name), void 0), factory.createStringLiteral(resolvePath), void 0);
+	const nodes = node.nodes;
+	if (!nodes || nodes.length === 0) return "";
+	let result = "";
+	for (const child of nodes) {
+		const text = printCodeNode(child);
+		if (!text) continue;
+		result = result ? `${result}\n\n${text}` : text;
 	}
-	const specifiers = name.map((item) => {
-		if (typeof item === "object") {
-			const { propertyName, name: alias } = item;
-			return factory.createImportSpecifier(false, alias ? factory.createIdentifier(propertyName) : void 0, factory.createIdentifier(alias ?? propertyName));
-		}
-		return factory.createImportSpecifier(false, void 0, factory.createIdentifier(item));
-	});
-	return factory.createImportDeclaration(void 0, factory.createImportClause(isTypeOnly, void 0, factory.createNamedImports(specifiers)), factory.createStringLiteral(resolvePath), void 0);
+	return result;
 }
-function createExport({ path, asAlias, isTypeOnly = false, name }) {
-	if (name && !Array.isArray(name) && !asAlias) console.warn(`When using name as string, asAlias should be true: ${name}`);
+/**
+* Wraps a module specifier in single quotes, escaping any embedded backslash or quote so the emitted
+* statement stays valid even for unusual paths.
+*/
+function quoteModulePath(path) {
+	return `'${path.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+/**
+* Renders an import declaration string in the repo style (single quotes, no semicolons), covering
+* default, namespace (`* as`), and named imports with `{ a as b }` aliases, each optionally
+* `type`-only. `path` is used verbatim, so resolve it first.
+*
+* @example
+* ```ts
+* printImport({ name: ['z'], path: './zod.ts' })
+* // "import { z } from './zod.ts'"
+* ```
+*/
+function printImport({ name, path, isTypeOnly = false, isNameSpace = false }) {
+	const typePrefix = isTypeOnly ? "type " : "";
+	const from = quoteModulePath(path);
 	if (!Array.isArray(name)) {
-		const parsedName = name && LEADING_DIGIT_PATTERN.test(name) ? `_${name.slice(1)}` : name;
-		return factory.createExportDeclaration(void 0, isTypeOnly, asAlias && parsedName ? factory.createNamespaceExport(factory.createIdentifier(parsedName)) : void 0, factory.createStringLiteral(path), void 0);
+		if (isNameSpace) return `import ${typePrefix}* as ${name} from ${from}`;
+		return `import ${typePrefix}${name} from ${from}`;
 	}
-	return factory.createExportDeclaration(void 0, isTypeOnly, factory.createNamedExports(name.map((propertyName) => factory.createExportSpecifier(false, void 0, typeof propertyName === "string" ? factory.createIdentifier(propertyName) : propertyName))), factory.createStringLiteral(path), void 0);
+	return `import ${typePrefix}{ ${name.map((item) => {
+		if (typeof item === "object") return item.name ? `${item.propertyName} as ${item.name}` : item.propertyName;
+		return item;
+	}).join(", ")} } from ${from}`;
+}
+/**
+* Renders an export declaration string in the repo style (single quotes, no semicolons), covering
+* named re-exports, namespace alias (`* as name`), and wildcard, each optionally `type`-only.
+* `path` is used verbatim, so resolve it first.
+*
+* @example
+* ```ts
+* printExport({ name: ['Pet', 'Order'], path: './models.ts' })
+* // "export { Pet, Order } from './models.ts'"
+* ```
+*/
+function printExport({ path, name, isTypeOnly = false, asAlias = false }) {
+	const typePrefix = isTypeOnly ? "type " : "";
+	const from = quoteModulePath(path);
+	if (Array.isArray(name)) return `export ${typePrefix}{ ${name.map((item) => typeof item === "string" ? item : item.text).join(", ")} } from ${from}`;
+	if (asAlias && name) return `export ${typePrefix}* as ${LEADING_DIGIT_PATTERN.test(name) ? `_${name.slice(1)}` : name} from ${from}`;
+	if (name) console.warn(`When using name as string, asAlias should be true: ${name}`);
+	return `export ${typePrefix}* from ${from}`;
 }
 //#endregion
 //#region src/parserTs.ts
 /**
-* Parser that converts `.ts` and `.js` files to strings using the TypeScript
-* compiler. Handles import/export statement generation from file metadata.
+* Default Kubb parser for `.ts` and `.js` files. Takes the universal AST
+* produced by an adapter and prints it as TypeScript source using the official
+* TypeScript compiler. Imports and exports are rewritten based on each file's
+* metadata.
+*
+* Used automatically when no `parsers` option is set on `defineConfig`. Use
+* `parserTsx` instead for React projects that emit JSX.
 *
-* @default Used automatically when no `parsers` option is set in `defineConfig`.
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { adapterOas } from '@kubb/adapter-oas'
+* import { parserTs } from '@kubb/parser-ts'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   adapter: adapterOas(),
+*   parsers: [parserTs],
+*   plugins: [],
+* })
+* ```
 */
 const parserTs = (0, _kubb_core.defineParser)({
 	name: "typescript",
 	extNames: [".ts", ".js"],
-	async parse(file, options = { extname: ".ts" }) {
+	print(...nodes) {
+		return print(...nodes);
+	},
+	parse(file, options = { extname: ".ts" }) {
 		const sourceParts = [];
 		for (const item of file.sources) {
 			const sourceStr = printSource(item);
 			if (sourceStr) sourceParts.push(sourceStr.trimEnd());
 		}
 		const source = sourceParts.join("\n\n");
-		const importNodes = [];
+		const importLines = [];
 		for (const item of file.imports) {
 			const importPath = item.root ? getRelativePath(item.root, item.path) : item.path;
-			importNodes.push(createImport({
+			importLines.push(printImport({
 				name: item.name,
 				path: resolveOutputPath(importPath, options, Boolean(item.root)),
 				isTypeOnly: item.isTypeOnly,
 				isNameSpace: item.isNameSpace
 			}));
 		}
-		const exportNodes = [];
-		for (const item of file.exports) exportNodes.push(createExport({
+		const exportLines = [];
+		for (const item of file.exports) exportLines.push(printExport({
 			name: item.name,
 			path: resolveOutputPath(item.path, options, true),
 			isTypeOnly: item.isTypeOnly,
 			asAlias: item.asAlias
 		}));
+		const importExportBlock = [...importLines, ...exportLines].join("\n");
 		return [
 			file.banner,
-			print(...importNodes, ...exportNodes),
+			importExportBlock,
 			source,
 			file.footer
 		].filter((segment) => Boolean(segment)).map((s) => s.trimEnd()).join("\n\n");
@@ -407,28 +509,39 @@ const parserTs = (0, _kubb_core.defineParser)({
 //#endregion
 //#region src/parserTsx.ts
 /**
-* Parser that converts `.tsx` and `.jsx` files to strings.
-* Delegates to `typescriptParser` since the TypeScript compiler natively
-* supports JSX/TSX syntax via `ScriptKind.TSX`.
+* Kubb parser for `.tsx` and `.jsx` files. Delegates to `parserTs` because the
+* TypeScript compiler handles JSX natively via `ScriptKind.TSX`.
 *
-* Add this parser to the `parsers` option in `defineConfig` when generating `.tsx`/`.jsx` files.
+* Add to the `parsers` array on `defineConfig` when generating components for
+* React (or any framework that emits JSX).
 *
-* @default extname '.tsx'
+* @example
+* ```ts
+* import { defineConfig } from 'kubb'
+* import { adapterOas } from '@kubb/adapter-oas'
+* import { parserTsx } from '@kubb/parser-ts'
+*
+* export default defineConfig({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   adapter: adapterOas(),
+*   parsers: [parserTsx],
+*   plugins: [],
+* })
+* ```
 */
 const parserTsx = (0, _kubb_core.defineParser)({
 	name: "tsx",
 	extNames: [".tsx", ".jsx"],
-	async parse(file, options = { extname: ".tsx" }) {
+	print(...nodes) {
+		return print(...nodes);
+	},
+	parse(file, options = { extname: ".tsx" }) {
 		return parserTs.parse(file, options);
 	}
 });
 //#endregion
-exports.createExport = createExport;
-exports.createImport = createImport;
 exports.parserTs = parserTs;
 exports.parserTsx = parserTsx;
-exports.print = print;
-exports.safePrint = safePrint;
-exports.validateNodes = validateNodes;
 
 //# sourceMappingURL=index.cjs.map