@stealthscale/core-locale 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @stealthscale/core-locale
+
+A **library**: the browser, the server and the message compiler all install it.
+
+Which locale to answer in. BCP-47 tags read with the engine's own `Intl`, and ECMA-402's
+lookup matcher against what a catalogue actually ships.
+
+```ts
+import { chain, negotiate, preferences } from '@stealthscale/core-locale'
+
+const wanted = preferences(request.headers.get('accept-language') ?? undefined)
+const answer = negotiate(
+  wanted.map((p) => p.tag),
+  ['en', 'nl', 'zh-Hans'],
+  'en',
+)
+
+chain('zh-Hant-TW') // ['zh-Hant-TW', 'zh-Hant', 'zh'] — the order a catalogue resolves in
+```
+
+`negotiate` truncates each requested tag until it names something available, so `en-GB`
+reaches a catalogue that ships `en`, and `nl-BE` reaches one that ships `nl`.
+
+Where truncation finds nothing it widens both sides to their likely script and region and
+matches over every step of the widened chain, so the two meet at whatever depth they share:
+`zh` reaches `zh-Hans`, `zh-HK` reaches `zh-Hant` even though the two widen to different
+regions, and `en-GB` reaches `en-US`. It gives back the available tag **as the catalogue wrote
+it**, because that string is a file name.
+
+`preferences` drops what the client cannot use: the wildcard, anything that is not a tag, and
+a tag at `q=0`, which RFC 9110 defines as "not acceptable" rather than as a weak preference.
+
+`directionOf` reads which way a tag's text runs from its script, so `ar` and `ur` are `rtl`,
+`ar-Latn` is `ltr`, and a string that is not a tag is `ltr` as the ordinary case.
+
+## No locale library
+
+`@formatjs/intl-localematcher` is the usual answer and it is 58 KB, almost all of it the
+likely-subtags data. The engine already has that data: `Intl.Locale.prototype.maximize()`
+turns `zh` into `zh-Hans-CN`, `Intl.getCanonicalLocales` fixes subtag case, and `Intl.Locale`
+takes a tag apart. So this package is the lookup algorithm over what `Intl` already knows, and
+carries one table of its own: the right-to-left scripts, because the engines agree on a
+language's likely script and disagree on what `getTextInfo` says about it.
+
+## Install
+
+```sh
+bun add @stealthscale/core-locale
+```

package/dist/index.d.mts

@@ -0,0 +1,145 @@
+//#region src/tags.d.ts
+/**
+ * @fileoverview Reads a BCP-47 language tag with the engine's own ECMA-402 implementation:
+ * canonicalising it, taking it apart, walking it from most specific to least, and reading
+ * the direction its text runs in. `Intl` carries the locale data, including the likely
+ * subtags a `zh` to `zh-Hans-CN` widening needs; the one table here is the right-to-left
+ * scripts, for the reason `directionOf` gives.
+ */
+/**
+ * Names a canonical BCP-47 language tag: `nl`, `en-GB`, `zh-Hant-TW`.
+ *
+ * It is a string rather than a class so a tag can be a catalogue key, a URL segment and a
+ * `lang` attribute without unwrapping.
+ */
+type Tag = string;
+/**
+ * Describes the parts of a tag a caller reaches for.
+ */
+interface Parts {
+  /**
+   * Names the primary language: `nl`, `en`, `zh`.
+   */
+  language: string;
+  /**
+   * Names the region, where the tag names one: `GB`, `TW`.
+   */
+  region: string | undefined;
+  /**
+   * Names the script, where the tag names one: `Hant`.
+   */
+  script: string | undefined;
+}
+/**
+ * Canonicalises a tag, correcting the case of each subtag as BCP-47 writes it.
+ *
+ * @param {string} tag - The tag as it arrived, from a header, a URL or a manifest.
+ * @returns {Tag | undefined} The canonical tag, or `undefined` when it is not a tag at all.
+ */
+declare function canonical(tag: string): Tag | undefined;
+/**
+ * Takes a tag apart into the language, script and region.
+ *
+ * @param {string} tag - The tag to read.
+ * @returns {Parts | undefined} The parts, or `undefined` when the tag is not a tag at all.
+ */
+declare function parts(tag: string): Parts | undefined;
+/**
+ * Widens a tag to the script and region the engine considers likely, so two tags written at
+ * different depths can be compared: `zh` becomes `zh-Hans-CN`.
+ *
+ * @param {string} tag - The tag to widen.
+ * @returns {Tag | undefined} The widened tag, or `undefined` when the tag is not a tag at all.
+ */
+declare function widened(tag: string): Tag | undefined;
+/**
+ * Walks a tag from most specific to least, which is the order a catalogue chain resolves in
+ * and the order ECMA-402's lookup matcher truncates in.
+ *
+ * A single-character subtag starts an extension (`-u-`, `-x-`), and everything from there on
+ * is dropped rather than walked, as the lookup algorithm requires.
+ *
+ * @param {string} tag - The tag to walk.
+ * @returns {Tag[]} The tag and each shorter form, most specific first, empty when the tag is
+ *     not a tag at all. `zh-Hant-TW` gives `zh-Hant-TW`, `zh-Hant`, `zh`.
+ */
+declare function chain(tag: string): Tag[];
+/**
+ * Names the direction a script's text runs in.
+ */
+type Direction = 'ltr' | 'rtl';
+/**
+ * Reads the direction a tag's text runs in, from the script the tag names or the one the
+ * engine considers likely for its language.
+ *
+ * @param {string} tag - The tag to read.
+ * @returns {Direction} `rtl` for `ar`, `he`, `fa`, `ur` and `dv`. `ltr` for every other
+ *     script, for `ar-Latn`, and for a string that is not a tag at all.
+ */
+declare function directionOf(tag: string): Direction;
+/**
+ * Widens a tag and walks the result, which is the depth a lookup compares two tags at.
+ *
+ * A tag and an offer that widen to different regions still share their script, so both sides
+ * of a lookup walk this rather than compare their widened tags whole.
+ *
+ * @param {string} tag - The tag to widen and walk.
+ * @returns {Tag[]} The widened tag and each shorter form, most specific first, empty when the
+ *     tag is not a tag at all. `zh-HK` gives `zh-Hant-HK`, `zh-Hant`, `zh`.
+ */
+declare function widenedChain(tag: string): Tag[];
+//#endregion
+//#region src/negotiate.d.ts
+/**
+ * Describes one entry of an `Accept-Language` header: a tag and how much the client wants it.
+ */
+interface Preference {
+  /**
+   * Carries how much the client wants this tag, above 0 and up to 1. A header that names no
+   * quality means 1, and one that names 0 refuses the tag, which `preferences` drops.
+   */
+  quality: number;
+  /**
+   * Names the canonical tag the client asked for.
+   */
+  tag: Tag;
+}
+/**
+ * Reads an `Accept-Language` header into the tags a client asked for, most wanted first.
+ *
+ * A tag the header writes but no canonical form exists for is dropped rather than carried as
+ * a string nothing can match. The wildcard `*` is dropped for the same reason: it names no
+ * locale, and a caller that runs out of preferences uses its own default.
+ *
+ * A tag at `q=0` is dropped as well. RFC 9110 gives that quality the meaning "not
+ * acceptable", so the client named the tag to refuse it, and a refusal carried on as a
+ * preference is a locale the client asked not to be answered in.
+ *
+ * @param {string} [header] - The header as it arrived, such as `en-GB,en;q=0.9,nl;q=0.8`.
+ *     Left out, or empty, means the client asked for nothing.
+ * @returns {Preference[]} The tags the client will accept, highest quality first, and in the
+ *     header's own order where two share a quality. Empty when the header names nothing
+ *     usable.
+ */
+declare function preferences(header?: string): Preference[];
+/**
+ * Picks the first available locale a request would accept.
+ *
+ * Each requested tag is truncated in turn, `en-GB` and then `en`, and the first that names an
+ * available locale wins, which is ECMA-402's lookup matcher. `nl-BE` reaches a catalogue that
+ * ships `nl` in this pass.
+ *
+ * Where truncation finds nothing, both sides are widened to their likely script and region
+ * and matched over every step of the widened chain, so they meet at whatever depth they
+ * share: `zh` reaches `zh-Hans`, `zh-HK` reaches `zh-Hant`, and `en-GB` reaches `en-US`.
+ *
+ * @param {readonly string[]} requested - The tags asked for, most wanted first, as
+ *     `preferences` orders them.
+ * @param {readonly string[]} available - The tags a catalogue ships.
+ * @param {string} fallback - The tag to answer in where nothing matches. It is returned as
+ *     given, so a caller that ships it gets back something it can serve.
+ * @returns {Tag} The available tag to answer in, or the fallback.
+ */
+declare function negotiate(requested: readonly string[], available: readonly string[], fallback: string): Tag;
+//#endregion
+export { type Direction, type Parts, type Preference, type Tag, canonical, chain, directionOf, negotiate, parts, preferences, widened, widenedChain };

package/dist/index.mjs

@@ -0,0 +1,245 @@
+//#region src/tags.ts
+/**
+* Canonicalises a tag, correcting the case of each subtag as BCP-47 writes it.
+*
+* @param {string} tag - The tag as it arrived, from a header, a URL or a manifest.
+* @returns {Tag | undefined} The canonical tag, or `undefined` when it is not a tag at all.
+*/
+function canonical(tag) {
+	try {
+		return Intl.getCanonicalLocales(tag)[0];
+	} catch {
+		return;
+	}
+}
+/**
+* Takes a tag apart into the language, script and region.
+*
+* @param {string} tag - The tag to read.
+* @returns {Parts | undefined} The parts, or `undefined` when the tag is not a tag at all.
+*/
+function parts(tag) {
+	try {
+		const locale = new Intl.Locale(tag);
+		return {
+			language: locale.language,
+			region: locale.region,
+			script: locale.script
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* Widens a tag to the script and region the engine considers likely, so two tags written at
+* different depths can be compared: `zh` becomes `zh-Hans-CN`.
+*
+* @param {string} tag - The tag to widen.
+* @returns {Tag | undefined} The widened tag, or `undefined` when the tag is not a tag at all.
+*/
+function widened(tag) {
+	try {
+		return new Intl.Locale(tag).maximize().toString();
+	} catch {
+		return;
+	}
+}
+/**
+* Walks a tag from most specific to least, which is the order a catalogue chain resolves in
+* and the order ECMA-402's lookup matcher truncates in.
+*
+* A single-character subtag starts an extension (`-u-`, `-x-`), and everything from there on
+* is dropped rather than walked, as the lookup algorithm requires.
+*
+* @param {string} tag - The tag to walk.
+* @returns {Tag[]} The tag and each shorter form, most specific first, empty when the tag is
+*     not a tag at all. `zh-Hant-TW` gives `zh-Hant-TW`, `zh-Hant`, `zh`.
+*/
+function chain(tag) {
+	const start = canonical(tag);
+	if (start === void 0) return [];
+	const subtags = start.split("-");
+	const extension = subtags.findIndex((subtag, index) => index > 0 && subtag.length === 1);
+	const named = extension === -1 ? subtags : subtags.slice(0, extension);
+	const walked = [];
+	for (let depth = named.length; depth > 0; depth -= 1) walked.push(named.slice(0, depth).join("-"));
+	return walked;
+}
+/**
+* Lists the scripts written right to left that a living language widens to, as CLDR's
+* script metadata marks them. The engines answer `getTextInfo` differently, Bun's ICU calling
+* Thaana and Hanifi Rohingya left to right, while every engine agrees on the likely script,
+* so the script decides.
+*/
+const RIGHT_TO_LEFT = /* @__PURE__ */ new Set([
+	"Adlm",
+	"Arab",
+	"Aran",
+	"Hebr",
+	"Mand",
+	"Nkoo",
+	"Rohg",
+	"Samr",
+	"Syrc",
+	"Thaa",
+	"Yezi"
+]);
+/**
+* Reads the direction a tag's text runs in, from the script the tag names or the one the
+* engine considers likely for its language.
+*
+* @param {string} tag - The tag to read.
+* @returns {Direction} `rtl` for `ar`, `he`, `fa`, `ur` and `dv`. `ltr` for every other
+*     script, for `ar-Latn`, and for a string that is not a tag at all.
+*/
+function directionOf(tag) {
+	try {
+		const script = new Intl.Locale(tag).maximize().script;
+		return script !== void 0 && RIGHT_TO_LEFT.has(script) ? "rtl" : "ltr";
+	} catch {
+		return "ltr";
+	}
+}
+/**
+* Widens a tag and walks the result, which is the depth a lookup compares two tags at.
+*
+* A tag and an offer that widen to different regions still share their script, so both sides
+* of a lookup walk this rather than compare their widened tags whole.
+*
+* @param {string} tag - The tag to widen and walk.
+* @returns {Tag[]} The widened tag and each shorter form, most specific first, empty when the
+*     tag is not a tag at all. `zh-HK` gives `zh-Hant-HK`, `zh-Hant`, `zh`.
+*/
+function widenedChain(tag) {
+	const wide = widened(tag);
+	return wide === void 0 ? [] : chain(wide);
+}
+//#endregion
+//#region src/negotiate.ts
+/**
+* @fileoverview Picks the locale to answer in: reads what a request asked for, in the order
+* it asked, and matches it against what a catalogue actually ships. The matcher is ECMA-402's
+* lookup algorithm: it truncates the requested tag until it names something available.
+*/
+/**
+* Reads how much a client wants a tag from the `q` parameter beside it.
+*
+* A parameter that names no number leaves the tag fully wanted. Only a `q` the client
+* actually wrote lowers a tag, so `en;` and `en;q=` mean the same as `en`.
+*
+* @param {string} [parameter] - The text after the tag's semicolon, such as `q=0.8`.
+* @returns {number} The quality between 0 and 1, and 1 where the parameter names none.
+*/
+function qualityOf(parameter) {
+	const named = parameter?.trim().replace(/^q=/u, "").trim() ?? "";
+	if (named === "") return 1;
+	const value = Number(named);
+	return Number.isFinite(value) && value >= 0 && value <= 1 ? value : 1;
+}
+/**
+* Reads an `Accept-Language` header into the tags a client asked for, most wanted first.
+*
+* A tag the header writes but no canonical form exists for is dropped rather than carried as
+* a string nothing can match. The wildcard `*` is dropped for the same reason: it names no
+* locale, and a caller that runs out of preferences uses its own default.
+*
+* A tag at `q=0` is dropped as well. RFC 9110 gives that quality the meaning "not
+* acceptable", so the client named the tag to refuse it, and a refusal carried on as a
+* preference is a locale the client asked not to be answered in.
+*
+* @param {string} [header] - The header as it arrived, such as `en-GB,en;q=0.9,nl;q=0.8`.
+*     Left out, or empty, means the client asked for nothing.
+* @returns {Preference[]} The tags the client will accept, highest quality first, and in the
+*     header's own order where two share a quality. Empty when the header names nothing
+*     usable.
+*/
+function preferences(header) {
+	if (header === void 0 || header.trim() === "") return [];
+	return header.split(",").map((entry) => {
+		const semicolon = entry.indexOf(";");
+		const named = semicolon === -1 ? entry : entry.slice(0, semicolon);
+		const parameter = semicolon === -1 ? void 0 : entry.slice(semicolon + 1);
+		const canonicalised = canonical(named.trim());
+		return canonicalised === void 0 ? void 0 : {
+			quality: qualityOf(parameter),
+			tag: canonicalised
+		};
+	}).filter((preference) => preference !== void 0 && preference.quality > 0).toSorted((left, right) => right.quality - left.quality);
+}
+/**
+* Keys what a catalogue ships by its canonical tag, keeping the spelling the catalogue used.
+*
+* The spelling matters because that string is a file name. Where two entries canonicalise the
+* same, the first wins, so a catalogue's own order decides.
+*
+* @param {readonly string[]} available - The tags a catalogue ships.
+* @returns {Map<Tag, Tag>} The canonical tag mapped to the tag as it was written, skipping
+*     anything that is not a tag.
+*/
+function offers(available) {
+	const offered = /* @__PURE__ */ new Map();
+	for (const tag of available) {
+		const canonicalised = canonical(tag);
+		if (canonicalised !== void 0 && !offered.has(canonicalised)) offered.set(canonicalised, tag);
+	}
+	return offered;
+}
+/**
+* Keys the same offers by every step of their widened chain, so the two sides meet at
+* whatever depth they share.
+*
+* An offer keyed by its full widened tag alone is reached only by a request that widens to
+* the same region. `zh-Hant` widens to `zh-Hant-TW`, and a request for `zh-HK` widens to
+* `zh-Hant-HK`, so the two never meet at their full depth; keying `zh-Hant` and `zh` as well
+* lets them meet at the script. Where two offers claim a step, the first wins, so a
+* catalogue's own order decides.
+*
+* @param {Offers} offered - The offers, as `offers` keyed them.
+* @returns {Map<Tag, Tag>} Every step of every offer's widened chain, mapped to the tag as
+*     the catalogue wrote it.
+*/
+function widenedOffers(offered) {
+	const wide = /* @__PURE__ */ new Map();
+	for (const [canonicalised, written] of offered) for (const step of widenedChain(canonicalised)) if (!wide.has(step)) wide.set(step, written);
+	return wide;
+}
+/**
+* Runs ECMA-402's lookup over the requested tags: the first whose chain names an offer wins.
+*
+* @param {readonly string[]} requested - The tags asked for, most wanted first.
+* @param {Offers} offered - The offers to match against.
+* @param {boolean} widen - Widens each requested tag before walking it. The second pass
+*     sets it when truncation alone found nothing.
+* @returns {Tag | undefined} The offer as the catalogue wrote it, or `undefined` when none
+*     of the requested tags names one.
+*/
+function lookup(requested, offered, widen) {
+	for (const tag of requested) for (const step of widen ? widenedChain(tag) : chain(tag)) {
+		const match = offered.get(step);
+		if (match !== void 0) return match;
+	}
+}
+/**
+* Picks the first available locale a request would accept.
+*
+* Each requested tag is truncated in turn, `en-GB` and then `en`, and the first that names an
+* available locale wins, which is ECMA-402's lookup matcher. `nl-BE` reaches a catalogue that
+* ships `nl` in this pass.
+*
+* Where truncation finds nothing, both sides are widened to their likely script and region
+* and matched over every step of the widened chain, so they meet at whatever depth they
+* share: `zh` reaches `zh-Hans`, `zh-HK` reaches `zh-Hant`, and `en-GB` reaches `en-US`.
+*
+* @param {readonly string[]} requested - The tags asked for, most wanted first, as
+*     `preferences` orders them.
+* @param {readonly string[]} available - The tags a catalogue ships.
+* @param {string} fallback - The tag to answer in where nothing matches. It is returned as
+*     given, so a caller that ships it gets back something it can serve.
+* @returns {Tag} The available tag to answer in, or the fallback.
+*/
+function negotiate(requested, available, fallback) {
+	const offered = offers(available);
+	return lookup(requested, offered, false) ?? lookup(requested, widenedOffers(offered), true) ?? fallback;
+}
+//#endregion
+export { canonical, chain, directionOf, negotiate, parts, preferences, widened, widenedChain };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@stealthscale/core-locale",
+  "version": "0.1.0",
+  "description": "Which locale to answer in: BCP-47 tags read with the engine's own Intl, and ECMA-402 lookup against what a catalogue ships.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stealth-scale/tooling.git",
+    "directory": "core/locale"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "tooling-source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack src/index.ts"
+  },
+  "devDependencies": {
+    "@stealthscale/tool-config": "^0.1.0"
+  }
+}