rolldown-plugin-dts 0.27.2 → 0.27.4

package/README.md

@@ -56,6 +56,22 @@ Configuration options for the plugin.
 
 ### General Options
 
+#### `generator`
+
+Specifies which generator to use for `.d.ts` generation.
+
+- `'tsc'`: Uses the TypeScript 5.x or 6.x compiler. Compatible with all TypeScript features.
+- `'oxc'`: Uses [Oxc](https://oxc.rs/docs/guide/usage/transformer.html)'s isolated declaration generator, which is significantly faster than the TypeScript compiler. Only compatible with TypeScript features that do not require type checking.
+- `'tsgo'`: **[Experimental]** Uses the TypeScript Go compiler ([`tsgo`](https://github.com/microsoft/typescript-go)). May not support all TypeScript features.
+
+**Default:** `'tsc'`, unless `isolatedDeclarations` is enabled in `compilerOptions`, in which case it defaults to `'oxc'`. If TypeScript 7.0 is installed, it defaults to `'tsgo'`.
+
+```ts
+dts({
+  generator: 'oxc',
+})
+```
+
 #### `entry`
 
 Glob pattern(s) to filter which files get `.d.ts` generation.
@@ -140,7 +156,7 @@ Indicates whether the generated `.d.ts` files have side effects.
 ### `tsc` Options
 
 > [!NOTE]
-> These options are only applicable when `oxc` and `tsgo` are not enabled.
+> These options are only applicable when the `generator` is `'tsc'`.
 
 #### `build`
 
@@ -201,24 +217,37 @@ Enabled by default when `allowJs` in compilerOptions is `true`.
 
 ### Oxc
 
+> [!NOTE]
+> These options are only applicable when the `generator` is `'oxc'`. Set `generator: 'oxc'` to enable the Oxc generator, or leave it unset when `isolatedDeclarations` in `compilerOptions` is `true`.
+
 #### `oxc`
 
-If `true`, the plugin will generate `.d.ts` files using [Oxc](https://oxc.rs/docs/guide/usage/transformer.html), which is significantly faster than the TypeScript compiler.
+Options passed to Oxc's isolated declaration generator.
 
-This option is automatically enabled when `isolatedDeclarations` in `compilerOptions` is set to `true`.
+See: [IsolatedDeclarationsOptions](https://oxc.rs/docs/guide/usage/transformer.html)
 
 ### TypeScript Go
 
 > [!WARNING]
 > TypeScript 7.0 does not yet have a stable API and is experimental. This feature is not yet recommended for production environments, and some options will be unavailable.
 
+> [!NOTE]
+> These options are only applicable when the `generator` is `'tsgo'`. Set `generator: 'tsgo'` to enable the TypeScript Go generator, or leave it unset — it is used automatically when the native TypeScript compiler (v7+) is installed as the `typescript` package. Otherwise, ensure that `@typescript/native-preview` is installed as a dependency.
+>
+> `tsconfigRaw` and `compilerOptions` options are ignored when this generator is used.
+
 #### `tsgo`
 
-**[Experimental]** Enables DTS generation using [`tsgo`](https://github.com/microsoft/typescript-go).
+**[Experimental]** Options for the [`tsgo`](https://github.com/microsoft/typescript-go) generator.
 
-This is automatically enabled when the native TypeScript compiler (v7+) is installed as the `typescript` package. Otherwise, ensure that `@typescript/native-preview` is installed as a dependency.
+- `path`: Custom path to the `tsgo` binary (e.g., when managed by Nix).
 
-`tsconfigRaw` and `compilerOptions` options will be ignored when this option is enabled.
+```ts
+dts({
+  generator: 'tsgo',
+  tsgo: { path: '/path/to/tsgo' },
+})
+```
 
 ## Code Splitting Support
 

package/dist/index.d.mts

@@ -3,6 +3,28 @@ import { IsolatedDeclarationsOptions } from "rolldown/experimental";
 import { TsconfigJson } from "get-tsconfig";
 //#region src/options.d.ts
 interface GeneralOptions {
+  /**
+   * The generator used to produce `.d.ts` files.
+   *
+   * - `'tsc'`: The TypeScript 5.x/6.x compiler. Supports all TypeScript features.
+   * - `'oxc'`: {@link https://oxc.rs Oxc}'s isolated declaration generator. Much
+   *   faster than `tsc`, but only supports code that satisfies
+   *   [`isolatedDeclarations`](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations).
+   * - `'tsgo'`: **[Experimental]** The TypeScript Go compiler
+   *   ({@link https://github.com/microsoft/typescript-go tsgo}). May not support
+   *   all TypeScript features yet.
+   *
+   * When unset, the generator is inferred:
+   * - `'oxc'` if {@link Options.oxc oxc} options are provided or
+   *   `isolatedDeclarations` is enabled in `compilerOptions`.
+   * - `'tsgo'` if TypeScript 7.0 (or `@typescript/native-preview`) is installed,
+   *   or {@link Options.tsgo tsgo} options are provided.
+   * - `'tsc'` otherwise, and always when {@link TscOptions.vue vue} or
+   *   {@link TscOptions.tsMacro tsMacro} is enabled.
+   *
+   * @default 'tsc'
+   */
+  generator?: "tsc" | "oxc" | "tsgo";
   /**
    * Glob pattern(s) to filter which entry files get `.d.ts` generation.
    *
@@ -199,7 +221,6 @@ interface Options extends GeneralOptions, TscOptions {
   tsgo?: boolean | TsgoOptions;
 }
 interface TsgoOptions {
-  enabled?: boolean;
   /**
    * Custom path to the `tsgo` binary.
    */
@@ -209,17 +230,17 @@ type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
 type OptionsResolved = Overwrite<Required<Omit<Options, "compilerOptions">>, {
   entry?: string[];
   tsconfig?: string;
-  oxc: IsolatedDeclarationsOptions | false;
+  oxc: IsolatedDeclarationsOptions;
   tsconfigRaw: TsconfigJson;
-  tsgo: Omit<TsgoOptions, "enabled"> | false;
+  tsgo: TsgoOptions;
 }>;
-declare function resolveOptions({ entry, cwd, dtsInput, emitDtsOnly, tsconfig, tsconfigRaw: overriddenTsconfigRaw, compilerOptions, sourcemap, resolver, cjsDefault, sideEffects, build, incremental, vue, tsMacro, parallel, eager, newContext, emitJs, oxc, tsgo }: Options): OptionsResolved;
+declare function resolveOptions({ generator, entry, cwd, dtsInput, emitDtsOnly, tsconfig, tsconfigRaw: overriddenTsconfigRaw, compilerOptions, sourcemap, resolver, cjsDefault, sideEffects, build, incremental, vue, tsMacro, parallel, eager, newContext, emitJs, oxc, tsgo }: Options): OptionsResolved;
 //#endregion
 //#region src/fake-js.d.ts
 declare function createFakeJsPlugin({ sourcemap, cjsDefault, sideEffects }: Pick<OptionsResolved, "sourcemap" | "cjsDefault" | "sideEffects">): Plugin;
 //#endregion
 //#region src/generate.d.ts
-declare function createGeneratePlugin({ entry, tsconfig, tsconfigRaw, build, incremental, cwd, oxc, emitDtsOnly, vue, tsMacro, parallel, eager, tsgo, newContext, emitJs, sourcemap }: Pick<OptionsResolved, "entry" | "cwd" | "tsconfig" | "tsconfigRaw" | "build" | "incremental" | "oxc" | "emitDtsOnly" | "vue" | "tsMacro" | "parallel" | "eager" | "tsgo" | "newContext" | "emitJs" | "sourcemap">): Plugin;
+declare function createGeneratePlugin({ generator, entry, tsconfig, tsconfigRaw, build, incremental, cwd, oxc, emitDtsOnly, vue, tsMacro, parallel, eager, tsgo, newContext, emitJs, sourcemap }: Pick<OptionsResolved, "generator" | "entry" | "cwd" | "tsconfig" | "tsconfigRaw" | "build" | "incremental" | "oxc" | "emitDtsOnly" | "vue" | "tsMacro" | "parallel" | "eager" | "tsgo" | "newContext" | "emitJs" | "sourcemap">): Plugin;
 //#endregion
 //#region src/index.d.ts
 declare function dts(options?: Options): Plugin[];

package/dist/index.mjs

@@ -767,7 +767,7 @@ function getIdentifierIndex(identifierMap, name) {
 //#endregion
 //#region src/tsgo.ts
 const require = createRequire(import.meta.url);
-const debug$3 = createDebug("rolldown-plugin-dts:tsgo");
+const debug$4 = createDebug("rolldown-plugin-dts:tsgo");
 function getTypeScriptMajor() {
 	try {
 		const { version } = require("typescript/package.json");
@@ -777,7 +777,7 @@ function getTypeScriptMajor() {
 		return;
 	}
 }
-function isTsgo() {
+function isTS7Installed() {
 	const major = getTypeScriptMajor();
 	return major != null && major >= 7;
 }
@@ -787,23 +787,23 @@ const spawnAsync = (...args) => new Promise((resolve, reject) => {
 	child.on("error", (error) => reject(error));
 });
 async function getTsgoPathFromNodeModules() {
-	const pkgName = isTsgo() ? "typescript" : "@typescript/native-preview";
+	const pkgName = isTS7Installed() ? "typescript" : "@typescript/native-preview";
 	const tsgoPkg = import.meta.resolve(`${pkgName}/package.json`);
 	const { default: getExePath } = await import(new URL("lib/getExePath.js", tsgoPkg).href);
 	return getExePath();
 }
 async function runTsgo(rootDir, tsconfig, sourcemap, tsgoPath) {
-	debug$3("[tsgo] rootDir", rootDir);
+	debug$4("[tsgo] rootDir", rootDir);
 	let tsgo;
 	if (tsgoPath) {
 		tsgo = tsgoPath;
-		debug$3("[tsgo] using custom path", tsgo);
+		debug$4("[tsgo] using custom path", tsgo);
 	} else {
 		tsgo = await getTsgoPathFromNodeModules();
-		debug$3("[tsgo] using tsgo from node_modules", tsgo);
+		debug$4("[tsgo] using tsgo from node_modules", tsgo);
 	}
 	const tsgoDist = await mkdtemp(path.join(tmpdir(), "rolldown-plugin-dts-"));
-	debug$3("[tsgo] tsgoDist", tsgoDist);
+	debug$4("[tsgo] tsgoDist", tsgoDist);
 	const args = [
 		"--noEmit",
 		"false",
@@ -817,14 +817,14 @@ async function runTsgo(rootDir, tsconfig, sourcemap, tsgoPath) {
 		"--noCheck",
 		...sourcemap ? ["--declarationMap"] : []
 	];
-	debug$3("[tsgo] args %o", args);
+	debug$4("[tsgo] args %o", args);
 	await spawnAsync(tsgo, args, { stdio: "inherit" });
 	return {
 		path: tsgoDist,
 		async dispose() {
-			if (debug$3.enabled) debug$3("[tsgo] skip cleanup of tsgoDist", tsgoDist);
+			if (debug$4.enabled) debug$4("[tsgo] skip cleanup of tsgoDist", tsgoDist);
 			else {
-				debug$3("[tsgo] disposing tsgoDist", tsgoDist);
+				debug$4("[tsgo] disposing tsgoDist", tsgoDist);
 				await rm(tsgoDist, {
 					recursive: true,
 					force: true
@@ -835,9 +835,9 @@ async function runTsgo(rootDir, tsconfig, sourcemap, tsgoPath) {
 }
 //#endregion
 //#region src/generate.ts
-const debug$2 = createDebug("rolldown-plugin-dts:generate");
+const debug$3 = createDebug("rolldown-plugin-dts:generate");
 const WORKER_URL = "./tsc-worker.mjs";
-function createGeneratePlugin({ entry, tsconfig, tsconfigRaw, build, incremental, cwd, oxc, emitDtsOnly, vue, tsMacro, parallel, eager, tsgo, newContext, emitJs, sourcemap }) {
+function createGeneratePlugin({ generator, entry, tsconfig, tsconfigRaw, build, incremental, cwd, oxc, emitDtsOnly, vue, tsMacro, parallel, eager, tsgo, newContext, emitJs, sourcemap }) {
 	const entryIncludes = entry?.filter((p) => p[0] !== "!");
 	const entryIgnores = entry?.filter((p) => p[0] === "!").map((p) => p.slice(1));
 	const entryMatcher = entry ? (file) => entryIncludes.some((p) => path.matchesGlob(file, p)) && !entryIgnores.some((p) => path.matchesGlob(file, p)) : void 0;
@@ -860,18 +860,18 @@ function createGeneratePlugin({ entry, tsconfig, tsconfigRaw, build, incremental
 	return {
 		name: "rolldown-plugin-dts:generate",
 		async buildStart(options) {
-			if (tsgo) tsgoContext = await runTsgo(rootDir, tsconfig, sourcemap, tsgo.path);
-			else if (!oxc) if (parallel) tscWorker = createTscWorker();
+			if (generator === "tsgo") tsgoContext = await runTsgo(rootDir, tsconfig, sourcemap, tsgo.path);
+			else if (generator === "tsc") if (parallel) tscWorker = createTscWorker();
 			else {
 				tscModule = await import("./tsc.mjs");
 				if (newContext) tscContext = createContext();
 			}
 			if (!Array.isArray(options.input)) for (const [name, id] of Object.entries(options.input)) {
-				debug$2("resolving input alias %s -> %s", name, id);
+				debug$3("resolving input alias %s -> %s", name, id);
 				let resolved = await this.resolve(id);
 				if (!id.startsWith("./")) resolved ||= await this.resolve(`./${id}`);
 				const resolvedId = resolved?.id || id;
-				debug$2("resolved input alias %s -> %s", id, resolvedId);
+				debug$3("resolved input alias %s -> %s", id, resolvedId);
 				inputAliasMap.set(resolvedId, name);
 			}
 		},
@@ -891,7 +891,7 @@ function createGeneratePlugin({ entry, tsconfig, tsconfigRaw, build, incremental
 		},
 		resolveId(id) {
 			if (dtsMap.has(id)) {
-				debug$2("resolve dts id %s", id);
+				debug$3("resolve dts id %s", id);
 				return { id };
 			}
 		},
@@ -922,7 +922,7 @@ function createGeneratePlugin({ entry, tsconfig, tsconfigRaw, build, incremental
 						isEntry,
 						jsFile
 					});
-					debug$2("register dts source: %s", id);
+					debug$3("register dts source: %s", id);
 					if (isEntry) {
 						const name = inputAliasMap.get(id);
 						this.emitFile({
@@ -948,17 +948,17 @@ function createGeneratePlugin({ entry, tsconfig, tsconfigRaw, build, incremental
 				if (!module) return;
 				const { code, id, jsFile } = module;
 				if (jsFile && await access(dtsId).then(() => true).catch(() => false)) {
-					debug$2("dts file already exists for %s, skipping generation", id);
+					debug$3("dts file already exists for %s, skipping generation", id);
 					return;
 				}
 				let dtsCode;
 				let map;
-				debug$2("generate dts %s from %s", dtsId, id);
-				if (tsgo) {
+				debug$3("generate dts %s from %s", dtsId, id);
+				if (generator === "tsgo") {
 					if (RE_VUE.test(id)) throw new Error("tsgo does not support Vue files.");
 					const dtsPath = path.resolve(tsgoContext.path, path.relative(path.resolve(rootDir), filename_to_dts(id)));
 					if (!existsSync(dtsPath)) {
-						debug$2("[tsgo]", dtsPath, "is missing");
+						debug$3("[tsgo]", dtsPath, "is missing");
 						throw new Error(`tsgo did not generate dts file for ${id}, please check your tsconfig.`);
 					}
 					dtsCode = await readFile(dtsPath, "utf8");
@@ -970,7 +970,7 @@ function createGeneratePlugin({ entry, tsconfig, tsconfigRaw, build, incremental
 							sources: [id]
 						};
 					}
-				} else if (oxc && !RE_VUE.test(id)) {
+				} else if (generator === "oxc" && !RE_VUE.test(id)) {
 					const result = isolatedDeclarationSync(id, code, oxc);
 					if (result.errors.length) {
 						const [error] = result.errors;
@@ -1108,12 +1108,9 @@ function collectJsonExports(code) {
 }
 //#endregion
 //#region src/options.ts
+const debug$2 = createDebug("rolldown-plugin-dts:options");
 let warnedTsgo = false;
-function resolveOptions({ entry, cwd = process.cwd(), dtsInput = false, emitDtsOnly = false, tsconfig, tsconfigRaw: overriddenTsconfigRaw = {}, compilerOptions = {}, sourcemap, resolver = "oxc", cjsDefault = false, sideEffects = false, build = false, incremental = false, vue = false, tsMacro = false, parallel = false, eager = false, newContext = false, emitJs, oxc, tsgo }) {
-	if (tsgo == null) tsgo = isTsgo() && !vue && !tsMacro && !oxc;
-	if (tsgo === true) tsgo = {};
-	else if (typeof tsgo === "object" && tsgo.enabled === false) tsgo = false;
-	if (!tsgo && isTsgo()) throw new Error("[rolldown-plugin-dts] TypeScript 7.0 is installed, but the `tsgo` option is disabled. Please enable it to use TypeScript 7.0 features.");
+function resolveOptions({ generator, entry, cwd = process.cwd(), dtsInput = false, emitDtsOnly = false, tsconfig, tsconfigRaw: overriddenTsconfigRaw = {}, compilerOptions = {}, sourcemap, resolver = "oxc", cjsDefault = false, sideEffects = false, build = false, incremental = false, vue = false, tsMacro = false, parallel = false, eager = false, newContext = false, emitJs, oxc, tsgo }) {
 	let resolvedTsconfig;
 	if (tsconfig === true || tsconfig == null) {
 		const { config, path } = getTsconfig(cwd) || {};
@@ -1135,25 +1132,24 @@ function resolveOptions({ entry, cwd = process.cwd(), dtsInput = false, emitDtsO
 		...overriddenTsconfigRaw,
 		compilerOptions
 	};
-	oxc ??= !!(compilerOptions?.isolatedDeclarations && !vue && !tsgo && !tsMacro);
-	if (oxc === true) oxc = {};
+	if (!generator) if (vue || tsMacro) generator = "tsc";
+	else if (tsgo) generator = "tsgo";
+	else if (oxc || compilerOptions?.isolatedDeclarations) generator = "oxc";
+	else if (isTS7Installed()) generator = "tsgo";
+	else generator = "tsc";
+	if (oxc === true || !oxc) oxc = {};
 	if (oxc) {
 		oxc.stripInternal ??= !!compilerOptions?.stripInternal;
 		oxc.sourcemap = !!compilerOptions.declarationMap;
 	}
+	if (tsgo === true || !tsgo) tsgo = {};
 	emitJs ??= !!(compilerOptions.checkJs || compilerOptions.allowJs);
-	if (tsgo) {
-		if (vue) throw new Error("[rolldown-plugin-dts] The `tsgo` option is not compatible with the `vue` option. Please disable one of them.");
-		if (tsMacro) throw new Error("[rolldown-plugin-dts] The `tsgo` option is not compatible with the `tsMacro` option. Please disable one of them.");
-		if (oxc) throw new Error("[rolldown-plugin-dts] The `tsgo` option is not compatible with the `oxc` option. Please disable one of them.");
-	}
-	if (oxc && vue) throw new Error("[rolldown-plugin-dts] The `oxc` option is not compatible with the `vue` option. Please disable one of them.");
-	if (oxc && tsMacro) throw new Error("[rolldown-plugin-dts] The `oxc` option is not compatible with the `tsMacro` option. Please disable one of them.");
-	if (tsgo && !warnedTsgo) {
+	if (generator === "tsgo" && !warnedTsgo) {
 		console.warn("TypeScript 7.0 does not yet have a stable API and is experimental. Some options will be unavailable.");
 		warnedTsgo = true;
 	}
-	return {
+	const resolved = {
+		generator,
 		entry: entry ? Array.isArray(entry) ? entry : [entry] : void 0,
 		cwd,
 		dtsInput,
@@ -1175,6 +1171,8 @@ function resolveOptions({ entry, cwd = process.cwd(), dtsInput = false, emitDtsO
 		oxc,
 		tsgo
 	};
+	debug$2("Resolved Options: %O", resolved);
+	return resolved;
 }
 //#endregion
 //#region src/resolver.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rolldown-plugin-dts",
   "type": "module",
-  "version": "0.27.2",
+  "version": "0.27.4",
   "description": "A Rolldown plugin to generate and bundle dts files.",
   "author": "Kevin Deng <sxzz@sxzz.moe>",
   "license": "MIT",