fix: support data URLs in tsImport

Author: privatenumber

notes/node/README.md

@@ -8,6 +8,7 @@ Node runtime and loader implementation references. These notes record Node behav
 | --- | --- |
 | [module-hooks.md](./module-hooks.md) | Async `module.register()` and sync `module.registerHooks()` |
 | [module-resolution.md](./module-resolution.md) | ESM root exports, CommonJS directory mains, and ESM error decoration |
+| [data-url-modules.md](./data-url-modules.md) | `data:` module payload and metadata behavior |
 | [cjs-loader.md](./cjs-loader.md) | CommonJS resolution, cache identity, extensions, and ESM error decoration |
 | [cjs-esm-interop.md](./cjs-esm-interop.md) | Node's CJS-to-ESM and ESM-to-CJS interoperability |
 | [type-stripping.md](./type-stripping.md) | Node's native TypeScript type-stripping runtime |

notes/node/data-url-modules.md

@@ -0,0 +1,13 @@
+# Data URL modules
+
+Node loads `data:` modules directly from their URL payload. Supported ESM media types include `text/javascript`, `application/json`, and `application/wasm` ([Node ESM documentation](https://github.com/nodejs/node/blob/v22.9.0/doc/api/esm.md#L219-L241)).
+
+## Query and fragment handling
+
+Before Node 22.9.0, the ESM loader parsed a data module from `url.pathname`, so URL query and fragment metadata were outside the module body ([v20.20.2 loader](https://github.com/nodejs/node/blob/v20.20.2/lib/internal/modules/esm/load.js#L31-L73)). Node 22.9.0 adopted the Fetch-standard data-URL processor ([backport](https://github.com/nodejs/node/commit/40ba89e4524b6593badbdfa9e716c0523a0fa234)); it serializes the URL with only the fragment excluded, then decodes the remaining body ([v22.9.0 processor](https://github.com/nodejs/node/blob/v22.9.0/lib/internal/data_url.js#L35-L96)).
+
+Appending a query to a base64 data URL therefore changes its encoded body on Node 22.9.0 and newer. For example, `data:text/javascript;base64,Y29uc29sZS5sb2coMSk=?namespace=private` is not valid base64. A fragment leaves the payload unchanged because the processor excludes it.
+
+## Loader implication
+
+Loader metadata that must survive into imports from a `data:` module belongs in its fragment, not a query parameter. A `data:` module can import absolute URLs, so preserving the metadata is necessary for a hook to continue handling a TypeScript child module. Relative imports remain unsupported because `data:` is not a special URL scheme.

notes/tsx/module-resolution.md

@@ -53,6 +53,10 @@ Dependency TypeScript parents remain TypeScript-first; consumer `allowJs` never
 
 Dependency classification must inspect `new URL(parentURL).pathname`, not a substring of the serialized URL ([ESM resolver](../../src/esm/hook/resolve.ts)). URL queries and fragments are not filesystem location. A local parent URL containing `?source=/node_modules/` must retain local tsconfig path behavior, while a real dependency pathname must not receive the consumer's aliases.
 
+## Namespaced URLs
+
+`tsImport()` isolates each registration with a namespace. File URLs carry that namespace in their query, while `data:` URLs carry it in a trailing fragment parameter so Node does not include the metadata in the data payload. Data URLs bypass file-oriented resolver logic because their payload can contain query and directory-like text. The trailing marker is removed only when it matches the active registration, leaving user fragments opaque. It lets absolute TypeScript imports from a `data:` module retain the registration namespace ([Node contract](../node/data-url-modules.md), [resolver](../../src/esm/hook/resolve.ts), [lookup](../../src/esm/hook/utils.ts)).
+
 ## Required test matrix
 
 Before changing resolver code, cover each policy row through every execution boundary:
@@ -65,6 +69,7 @@ Before changing resolver code, cover each policy row through every execution bou
 6. Parent URL classification with no query, a `/node_modules/` query, and a real `node_modules` pathname.
 7. Dependency subpaths with conditional root exports, package imports, scoped nested mains, an exact main before extension fallbacks, a missing main that falls through to index, a main directory, and an all-miss native-error comparison.
 8. A relative dependency directory beneath root exports, so the package-subpath boundary cannot block ordinary index fallback.
+9. A namespaced `tsImport()` graph containing base64 and raw `data:` modules, an opaque user fragment, and an absolute TypeScript child across async and sync hooks.
 
 ## Non-goals
 

src/esm/hook/load.ts

@@ -26,6 +26,7 @@ import {
 	getQueryWithoutParameters,
 	namespaceQuery,
 	getNamespace,
+	isDataUrl,
 	moduleSourceByUrl,
 } from './utils.js';
 import type { Data } from './initialize.js';
@@ -173,9 +174,20 @@ const notifyLoad = (
 	const filePath = url.startsWith(fileUrlPrefix)
 		? getFileLoadContext(url).filePath
 		: undefined;
-	parsedUrl.searchParams.delete('tsx-namespace');
-	parsedUrl.searchParams.delete(commonJsExportPreparseSearchParameter);
-	parsedUrl.searchParams.delete(commonJsVirtualQuerySearchParameter);
+	if (isDataUrl(url)) {
+		if (hookData.namespace) {
+			const namespaceFragment = `${namespaceQuery}${hookData.namespace}`;
+			if (parsedUrl.hash === `#${namespaceFragment}`) {
+				parsedUrl.hash = '';
+			} else if (parsedUrl.hash.endsWith(`&${namespaceFragment}`)) {
+				parsedUrl.hash = parsedUrl.hash.slice(0, -namespaceFragment.length - 1);
+			}
+		}
+	} else {
+		parsedUrl.searchParams.delete('tsx-namespace');
+		parsedUrl.searchParams.delete(commonJsExportPreparseSearchParameter);
+		parsedUrl.searchParams.delete(commonJsVirtualQuerySearchParameter);
+	}
 	if (filePath) {
 		parsedUrl.pathname = new URL(pathToFileURL(filePath)).pathname;
 	}

src/esm/hook/resolve.ts

@@ -34,6 +34,7 @@ import {
 	commonJsVirtualQuerySearchParameter,
 	getQueryWithoutParameters,
 	getNamespace,
+	isDataUrl,
 	parentImportsCommonJsExports,
 } from './utils.js';
 import type { Data } from './initialize.js';
@@ -799,6 +800,17 @@ const addQuery = (
 	return `${urlWithoutFragment}${urlWithoutFragment.includes('?') ? '&' : '?'}${query}${fragment}`;
 };
 
+const addNamespace = (
+	url: string,
+	namespace: string,
+) => {
+	if (!isDataUrl(url)) {
+		return addQuery(url, `${namespaceQuery}${namespace}`);
+	}
+
+	return `${url}${url.includes('#') ? '&' : '#'}${namespaceQuery}${namespace}`;
+};
+
 const mergeUrlMetadata = (
 	url: string,
 	metadata: string,
@@ -862,10 +874,10 @@ export const createResolve = (
 			return nextResolve(specifier, context);
 		}
 
-		let requestNamespace = getNamespace(specifier) ?? (
-			// Inherit namespace from parent
-			context.parentURL && getNamespace(context.parentURL)
-		);
+		const parentNamespace = context.parentURL && getNamespace(context.parentURL);
+		let requestNamespace = isDataUrl(specifier)
+			? parentNamespace
+			: getNamespace(specifier) ?? parentNamespace;
 
 		if (hookData.namespace) {
 			let tsImportRequest: TsxRequest | undefined;
@@ -891,6 +903,17 @@ export const createResolve = (
 			}
 		}
 
+		if (isDataUrl(specifier)) {
+			const resolved = await nextResolve(specifier, context);
+			if (!hookData.namespace) {
+				return resolved;
+			}
+			return {
+				...resolved,
+				url: addNamespace(resolved.url, hookData.namespace),
+			};
+		}
+
 		const metadataIndex = getSpecifierMetadataIndex(
 			specifier,
 			isCommonJsRequireContext(context),
@@ -963,7 +986,7 @@ export const createResolve = (
 			requestNamespace
 			&& getNamespace(resolved.url) === undefined
 		) {
-			resolved.url = addQuery(resolved.url, `${namespaceQuery}${requestNamespace}`);
+			resolved.url = addNamespace(resolved.url, requestNamespace);
 		}
 
 		if (shouldLoadForCommonJsExportPreparse) {
@@ -1020,10 +1043,10 @@ export const createResolveSync = (
 			return nextResolve(specifier, context);
 		}
 
-		let requestNamespace = getNamespace(specifier) ?? (
-			// Inherit namespace from parent
-			context.parentURL && getNamespace(context.parentURL)
-		);
+		const parentNamespace = context.parentURL && getNamespace(context.parentURL);
+		let requestNamespace = isDataUrl(specifier)
+			? parentNamespace
+			: getNamespace(specifier) ?? parentNamespace;
 
 		if (hookData.namespace) {
 			let tsImportRequest: TsxRequest | undefined;
@@ -1049,6 +1072,17 @@ export const createResolveSync = (
 			}
 		}
 
+		if (isDataUrl(specifier)) {
+			const resolved = nextResolve(specifier, context);
+			if (!hookData.namespace) {
+				return resolved;
+			}
+			return {
+				...resolved,
+				url: addNamespace(resolved.url, hookData.namespace),
+			};
+		}
+
 		const metadataIndex = getSpecifierMetadataIndex(
 			specifier,
 			isCommonJsRequireContext(context),
@@ -1105,7 +1139,7 @@ export const createResolveSync = (
 			requestNamespace
 			&& getNamespace(resolved.url) === undefined
 		) {
-			resolved.url = addQuery(resolved.url, `${namespaceQuery}${requestNamespace}`);
+			resolved.url = addNamespace(resolved.url, requestNamespace);
 		}
 
 		resolved.url = preserveCommonJsQueryIdentity(

src/esm/hook/utils.ts

@@ -40,6 +40,12 @@ export const commonJsExportPreparseQuery = `${commonJsExportPreparseSearchParame
 export const commonJsVirtualQuerySearchParameter = 'tsx-commonjs-virtual-query';
 export const moduleSourceByUrl = new Map<string, string>();
 
+const dataUrlPattern = /^data:/i;
+
+export const isDataUrl = (
+	url: string,
+) => dataUrlPattern.test(url);
+
 type CommonJsImportBinding = 'named' | 'namespace' | undefined;
 
 export const getQueryWithoutParameters = (
@@ -137,6 +143,20 @@ export const getNamespace = (
 ) => {
 	const queryIndex = url.indexOf('?');
 	const fragmentIndex = url.indexOf('#');
+	if (isDataUrl(url)) {
+		if (fragmentIndex === -1) {
+			return;
+		}
+
+		// Data URL fragments are user content; tsx appends its marker last.
+		const fragment = url.slice(fragmentIndex + 1);
+		const parameterIndex = fragment.lastIndexOf('&');
+		const parameter = fragment.slice(parameterIndex + 1);
+		return parameter.startsWith(namespaceQuery)
+			? parameter.slice(namespaceQuery.length)
+			: undefined;
+	}
+
 	if (
 		queryIndex === -1
 		|| (fragmentIndex !== -1 && fragmentIndex < queryIndex)

tests/specs/version-sensitive.ts

@@ -1399,6 +1399,140 @@ export const versionSensitiveTests = (node: NodeApis) => describe('Version-sensi
 		expect(tsxProcess.stdout).toBe('literal-question');
 	});
 
+	// https://github.com/privatenumber/tsx/issues/750
+	test('tsImport imports data URLs', async () => {
+		if (!node.supports.moduleRegister) {
+			return;
+		}
+
+		await using fixture = await createFixture({
+			'package.json': createPackageJson({ type: 'module' }),
+			'import.mjs': `
+				import { tsImport } from ${JSON.stringify(tsxEsmApiPath)};
+
+				await tsImport('./data-import.ts', import.meta.url);
+				`,
+			'data-import.ts': `
+				const childUrl = new URL('./data-child.ts', import.meta.url);
+				const source = 'import ' + JSON.stringify(childUrl) + '; console.log("data URL");';
+				await import('data:text/javascript;base64,' + Buffer.from(source).toString('base64'));
+
+				console.log('after import');
+				`,
+			'data-child.ts': 'enum Data { Url = "child" } console.log(Data.Url);',
+		});
+
+		const process = await execaNode(fixture.getPath('import.mjs'), [], {
+			nodePath: node.path,
+			reject: false,
+		});
+
+		expect(process.exitCode).toBe(0);
+		expect(process.stderr).toBe('');
+		expect(process.stdout).toBe('child\ndata URL\nafter import');
+	});
+
+	test('tsImport treats uppercase data URL queries as source', async () => {
+		if (!node.supports.moduleRegister) {
+			return;
+		}
+
+		await using fixture = await createFixture({
+			'package.json': createPackageJson({ type: 'module' }),
+			'import.mjs': `
+				import { tsImport } from ${JSON.stringify(tsxEsmApiPath)};
+
+				await tsImport('./data-import.ts', import.meta.url);
+				`,
+			'data-import.ts': `
+				const childUrl = new URL('./data-child.ts', import.meta.url);
+				const source = 'import ' + JSON.stringify(childUrl) + '; //?tsx-namespace=payload';
+				await import('DATA:text/javascript,' + source);
+
+				console.log('after import');
+				`,
+			'data-child.ts': 'enum Data { Url = "child" } console.log(Data.Url);',
+		});
+
+		const process = await execaNode(fixture.getPath('import.mjs'), [], {
+			nodePath: node.path,
+			reject: false,
+		});
+
+		expect(process.exitCode).toBe(0);
+		expect(process.stderr).toBe('');
+		expect(process.stdout).toBe('child\nafter import');
+	});
+
+	test('tsImport isolates data URLs with user namespace fragments', async () => {
+		if (!node.supports.moduleRegister) {
+			return;
+		}
+
+		await using fixture = await createFixture({
+			'package.json': createPackageJson({ type: 'module' }),
+			'import.mjs': `
+				import { tsImport } from ${JSON.stringify(tsxEsmApiPath)};
+
+				await tsImport('./data-import.ts', import.meta.url);
+				await tsImport('./data-import.ts', import.meta.url);
+				`,
+			'data-import.ts': 'await import(\'data:text/javascript,globalThis.dataUrlLoads = (globalThis.dataUrlLoads || 0) + 1; console.log(globalThis.dataUrlLoads)#tsx-namespace=foreign\');',
+		});
+
+		const process = await execaNode(fixture.getPath('import.mjs'), [], {
+			nodePath: node.path,
+			reject: false,
+		});
+
+		expect(process.exitCode).toBe(0);
+		expect(process.stderr).toBe('');
+		expect(process.stdout).toBe('1\n2');
+	});
+
+	test('tsImport preserves data URL fragments in onImport', async () => {
+		if (!node.supports.moduleRegister) {
+			return;
+		}
+
+		await using fixture = await createFixture({
+			'package.json': createPackageJson({ type: 'module' }),
+			'import.mjs': `
+				import { setTimeout } from 'node:timers/promises';
+				import { tsImport } from ${JSON.stringify(tsxEsmApiPath)};
+
+				const importedUrls = [];
+				await tsImport('./data-import.ts', {
+					parentURL: import.meta.url,
+					onImport(url) {
+						importedUrls.push(url);
+					},
+				});
+				await setTimeout(100);
+
+				const dataUrlHashes = importedUrls
+					.filter(url => url.startsWith('data:'))
+					.map(url => new URL(url).hash);
+				console.log(JSON.stringify(dataUrlHashes));
+				`,
+			'data-import.ts': `
+				await import('data:text/javascript,console.log("no fragment")');
+				await import('data:text/javascript,console.log("user fragment")#user&&fragment&tsx-namespace=foreign');
+				`,
+		});
+
+		const process = await execaNode(fixture.getPath('import.mjs'), [], {
+			nodePath: node.path,
+			reject: false,
+		});
+
+		expect(process.exitCode).toBe(0);
+		expect(process.stderr).toBe('');
+		expect(process.stdout).toBe('no fragment\nuser fragment\n["","#user&&fragment&tsx-namespace=foreign"]');
+	}, {
+		retry: 3,
+	});
+
 	test('tsImport keeps CommonJS-classified TypeScript loads isolated when calls share a timestamp', async () => {
 		if (!node.supports.esmLoadReadFile) {
 			return;
@@ -1959,6 +2093,6 @@ export const versionSensitiveTests = (node: NodeApis) => describe('Version-sensi
 				expect(tsxProcess.stdout).toMatch('# pass 1\n');
 			}
 			expect(tsxProcess.exitCode).toBe(0);
-		}, 10_000);
+		}, 20_000);
 	}
 });