perf: share type declarations via typesVersions

Every property directory shipped four identical declaration files
(`ranges.d.mts`, `regex.d.mts`, `code-points.d.mts`, `symbols.d.mts`),
about 4,000 files per package. They are now written once under `types/`
and selected through a generated `typesVersions` map in package.json.
Mapping directories (Case_Folding, Simple_Case_Mapping, Special_Casing,
Decomposition_Mapping) keep their own `code-points`/`symbols`
declarations, since their value types differ per directory; more
specific patterns route them there. The build removes per-directory
declarations left over from earlier runs.

`decode-ranges.d.mts` now exports the `UnicodeRange` type at module
level; previously `ranges.d.mts` imported a name that was only declared
inside a namespace, so TypeScript consumers saw an error. The README now
documents TypeScript 4.7 as the minimum, which is what `.d.mts` requires.

Verified with TypeScript 5.9 (node16, bundler and node10 resolution) and
TypeScript 4.7: imports resolve to the same types as before. A new test
checks the declaration layout and the typesVersions targets.

For Unicode 18.0.0 this shrinks the package from 378 KB to 312 KB packed
(1.38 MB to 1.08 MB unpacked) and from 8,352 to 4,320 files.

Assisted-By: Claude Fable 5.1
Issue: #109

Author: JLHwung

index.mjs

@@ -334,14 +334,22 @@ const generateData = async (version) => {
 	);
 	fs.writeFileSync(
 		path.resolve(__dirname, `output/unicode-${version}/package.json`),
-		compilePackage({ version: version }),
+		compilePackage({
+			version: version,
+			typesVersions: JSON.stringify(utils.typesVersions(dirMap), null, '\t')
+				// Indent to match the surrounding JSON.
+				.replace(/\n/g, '\n\t'),
+		}),
 	);
 	fs.mkdirSync(
 		path.resolve(__dirname, `output/unicode-${version}/.github/workflows`),
 		{
 			recursive: true,
 		},
 	);
+	fs.mkdirSync(path.resolve(__dirname, `output/unicode-${version}/types`), {
+		recursive: true,
+	});
 	const staticFiles = [
 		'.github/workflows/publish-on-tag.yml',
 		'.gitattributes',
@@ -357,6 +365,7 @@ const generateData = async (version) => {
 		'decode-names.d.mts',
 		'decode-mapping.mjs',
 		'decode-mapping.d.mts',
+		...utils.SHARED_DECLARATIONS.map((file) => `types/${file}.d.mts`),
 	];
 	for (const file of staticFiles) {
 		fs.copyFileSync(

scripts/utils.mjs

@@ -35,6 +35,18 @@ const brotliInline = (data) => {
 	return `JSON.parse(${brotliInlineBuffer(JSON.stringify(data))})`;
 };
 
+// Modules whose declarations are shared via `types/*.d.mts` and
+// `typesVersions` instead of being repeated in every directory.
+const SHARED_DECLARATIONS = ['ranges', 'regex', 'code-points', 'symbols'];
+
+// Directories under these types declare their own `code-points`/`symbols` types.
+const MAPPING_TYPES = [
+	'Case_Folding',
+	'Simple_Case_Mapping',
+	'Special_Casing',
+	'Decomposition_Mapping',
+];
+
 const range = (start, stop) => {
 	// Inclusive, e.g. `range(1, 3)` → `[1, 2, 3]`.
 	const result = [];
@@ -183,11 +195,7 @@ const writeFiles = (options) => {
 		const codePoints = map[item];
 		const type =
 			typeof options.type === 'function' ? options.type(item) : options.type;
-		const isCodePointMapping =
-			type === 'Case_Folding' ||
-			type === 'Simple_Case_Mapping' ||
-			type === 'Special_Casing' ||
-			type === 'Decomposition_Mapping';
+		const isCodePointMapping = MAPPING_TYPES.includes(type);
 		const isNamesCanon = type === 'Names' && !subType;
 		const isNameAliases = type === 'Names' && subType === 'name-aliases';
 		const subdir = isNameAliases
@@ -259,18 +267,10 @@ const writeFiles = (options) => {
 				path.resolve(dir, 'ranges.mjs'),
 				`import decodeRanges from '../../decode-ranges.mjs';\n\nexport default decodeRanges('${encodedRanges}');\n`,
 			);
-			writeFileIfChanged(
-				path.resolve(dir, 'ranges.d.mts'),
-				'import type { UnicodeRange } from "../../decode-ranges.mjs";\n\ndeclare const ranges: UnicodeRange[];\nexport default ranges;\n',
-			);
 			writeFileIfChanged(
 				path.resolve(dir, 'regex.mjs'),
 				'export default /' + regenerate(codePoints).toString() + '/;\n',
 			);
-			writeFileIfChanged(
-				path.resolve(dir, 'regex.d.mts'),
-				'declare const regex: RegExp;\nexport default regex;\n',
-			);
 			if (codePointsSizeLt(codePoints, 10)) {
 				const codePointsAsArray =
 					codePoints instanceof regenerate ? codePoints.toArray() : codePoints;
@@ -314,15 +314,26 @@ const writeFiles = (options) => {
 			path.resolve(dir, 'code-points.mjs'),
 			codePointsFileContent,
 		);
-		writeFileIfChanged(
-			path.resolve(dir, 'code-points.d.mts'),
-			`declare const codePoints: ${codePointsType};\nexport default codePoints;\n`,
-		);
 		writeFileIfChanged(path.resolve(dir, 'symbols.mjs'), symbolsFileContent);
-		writeFileIfChanged(
-			path.resolve(dir, 'symbols.d.mts'),
-			`declare const symbols: ${symbolsType};\nexport default symbols;\n`,
-		);
+		if (isCodePointMapping) {
+			// Mapping directories declare their own types, since the value type
+			// differs per directory (`Map<number, number>` vs. `Map<number, number[]>`).
+			writeFileIfChanged(
+				path.resolve(dir, 'code-points.d.mts'),
+				`declare const codePoints: ${codePointsType};\nexport default codePoints;\n`,
+			);
+			writeFileIfChanged(
+				path.resolve(dir, 'symbols.d.mts'),
+				`declare const symbols: ${symbolsType};\nexport default symbols;\n`,
+			);
+		} else {
+			// All other directories share the declarations in `types/`, selected
+			// through `typesVersions` in package.json. Remove per-directory
+			// declarations left over from earlier builds.
+			for (const file of SHARED_DECLARATIONS) {
+				fs.rmSync(path.resolve(dir, file + '.d.mts'), { force: true });
+			}
+		}
 	}
 	if (options.type === 'Bidi_Mirroring_Glyph') {
 		const type = options.type;
@@ -415,7 +426,26 @@ const readDataFile = (version, type) => {
 	}
 };
 
+// The `typesVersions` map for package.json. TypeScript picks the most specific
+// matching pattern, so mapping directories keep their own declarations while
+// everything else resolves to the shared ones in `types/`.
+const typesVersions = (dirMap) => {
+	const map = {};
+	for (const type of MAPPING_TYPES) {
+		if (hasKey(dirMap, type)) {
+			map[`${type}/*/code-points.mjs`] = [`${type}/*/code-points.d.mts`];
+			map[`${type}/*/symbols.mjs`] = [`${type}/*/symbols.d.mts`];
+		}
+	}
+	for (const file of SHARED_DECLARATIONS) {
+		map[`*/${file}.mjs`] = [`types/${file}.d.mts`];
+	}
+	return { '*': map };
+};
+
 export default {
+	SHARED_DECLARATIONS,
+	typesVersions,
 	range,
 	append,
 	extend,

static/decode-ranges.d.mts

@@ -22,5 +22,8 @@ declare function decodeRanges(input: string): decodeRanges.UnicodeRange[];
  */
 declare function decodeDeltas(input: string): number[];
 
+type UnicodeRange = decodeRanges.UnicodeRange;
+
 export { decodeDeltas };
+export type { UnicodeRange };
 export default decodeRanges;

static/types/code-points.d.mts

@@ -0,0 +1,2 @@
+declare const codePoints: number[];
+export default codePoints;

static/types/ranges.d.mts

@@ -0,0 +1,4 @@
+import type { UnicodeRange } from '../decode-ranges.mjs';
+
+declare const ranges: UnicodeRange[];
+export default ranges;

static/types/regex.d.mts

@@ -0,0 +1,2 @@
+declare const regex: RegExp;
+export default regex;

static/types/symbols.d.mts

@@ -0,0 +1,2 @@
+declare const symbols: string[];
+export default symbols;

templates/README.md

@@ -12,6 +12,8 @@ npm install @unicode/unicode-<%= version %> --save-dev
 
 **Note:** _@unicode/unicode-<%= version %>_ is supposed to be used in build scripts (i.e. as a `devDependency`), and not at runtime (i.e. as a regular `dependency`).
 
+TypeScript declarations are included. They require TypeScript 4.7 or newer, which is the first version that understands `.d.mts` declaration files.
+
 ## Regular expressions
 
 The Unicode data modules ship with pre-compiled regular expressions for categories, scripts, script extensions, blocks, and properties. But maybe you want to create a single regular expression that combines several categories, scripts, etc. In that case, [***you should use Regenerate***](https://mths.be/regenerate). For example, to construct a regex that matches all symbols in the Arabic and Greek scripts as per Unicode v6.3.0:

templates/package.json

@@ -25,5 +25,6 @@
 		"type": "git",
 		"url": "git+https://github.com/node-unicode/unicode-<%= version %>.git"
 	},
-	"bugs": "https://github.com/node-unicode/node-unicode-data/issues"
+	"bugs": "https://github.com/node-unicode/node-unicode-data/issues",
+	"typesVersions": <%= typesVersions %>
 }

tests/tests.mjs

@@ -165,6 +165,47 @@ suite(`The generated latest Unicode js`, () => {
 			}
 		}
 	});
+	test('type declarations should be shared via typesVersions', async (t) => {
+		const root = path.resolve(__dirname, '..', 'output', `unicode-${newest}`);
+		const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json')));
+		// Every typesVersions target that is not a wildcard must exist.
+		for (const targets of Object.values(pkg.typesVersions['*'])) {
+			for (const target of targets) {
+				if (!target.includes('*')) {
+					t.assert.ok(fs.existsSync(path.join(root, target)), target);
+				}
+			}
+		}
+		for (const type of fs.readdirSync(root)) {
+			const typeDir = path.join(root, type);
+			if (type.startsWith('.') || !fs.statSync(typeDir).isDirectory()) {
+				continue;
+			}
+			const isMapping = Object.hasOwn(
+				pkg.typesVersions['*'],
+				`${type}/*/symbols.mjs`,
+			);
+			for (const name of fs.readdirSync(typeDir)) {
+				const dir = path.join(typeDir, name);
+				if (!fs.existsSync(path.join(dir, 'symbols.mjs'))) {
+					continue;
+				}
+				// Mapping directories keep their own declarations; others share.
+				t.assert.strictEqual(
+					fs.existsSync(path.join(dir, 'symbols.d.mts')),
+					isMapping,
+					dir,
+				);
+				t.assert.strictEqual(
+					fs.existsSync(path.join(dir, 'code-points.d.mts')),
+					isMapping,
+					dir,
+				);
+				t.assert.ok(!fs.existsSync(path.join(dir, 'ranges.d.mts')), dir);
+				t.assert.ok(!fs.existsSync(path.join(dir, 'regex.d.mts')), dir);
+			}
+		}
+	});
 	test('every mapping symbols.mjs should match code-points.mjs', async (t) => {
 		await assertSymbolsMatchCodePoints(t, newest);
 	});