@zerolith/i18n 0.1.0-alpha.1 → 0.1.0-alpha.10

package/src/compile.ts

@@ -25,6 +25,7 @@ export interface CompileOptions
 /** The result of compiling one catalog. */
 export interface CompiledCatalog
 {
+    /** The generated module's source, TypeScript or JavaScript as the `language` option chose; the `zerolith-i18n` CLI writes it to `<locale>.ts` or `<locale>.js`. */
     code: string;
     /** The message keys as function names, in source order. */
     names: string[];
@@ -414,6 +415,40 @@ const NUMBER_OPTIONS: Record<string, string> = {
     numberingSystem: "numberingSystem"
 };
 
+/** Names a module cannot bind; a message named so is exported under its name from a binding of its own. */
+const RESERVED: ReadonlySet<string> = new Set(["arguments", "await", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "eval", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "var", "void", "while", "with", "yield"]);
+
+/** Characters an HTML parser reads inside an inline script, and the line separators older engines refused in string literals. */
+const SCRIPT_UNSAFE = new RegExp(`[<>${String.fromCodePoint(0x2028, 0x2029)}]`, "g");
+
+/** The line breaks of a message's source, each starting a new line of its doc comment. */
+const SOURCE_LINES = /\r\n|[\n\r\u2028\u2029]/;
+
+/**
+ * A value written as JavaScript source: its JSON, with `<`, `>`, U+2028, and
+ * U+2029 escaped, so generated code stays inert even when a page inlines
+ * it in a script element.
+ */
+function jsLiteral(value: unknown): string
+{
+    return JSON.stringify(value).replace(SCRIPT_UNSAFE, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+
+/** Text for a `//` comment, kept on one line and with `<` written as `&lt;`, so it can end neither the comment nor an inline script. */
+function commentText(text: string): string
+{
+    return text.split(SOURCE_LINES).join(" ").replaceAll("<", "&lt;");
+}
+
+/** An argument or local name JavaScript can write as it is; MessageFormat also allows `-` and `.`, as in `$first-name`. */
+const PLAIN_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** A property name as code: as it is when plain, quoted otherwise. */
+function property(name: string): string
+{
+    return PLAIN_NAME.test(name) ? name : jsLiteral(name);
+}
+
 function identifier(key: string): string
 {
     const words = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter((word) => word !== "");
@@ -428,11 +463,29 @@ class Emitter
     readonly prelude: string[] = [];
     private readonly key: string;
     private readonly message: Message;
+    private readonly formatters: Map<string, string>;
+    private readonly used: Set<Helper>;
+    private reads = 0;
 
-    constructor(key: string, message: Message)
+    constructor(key: string, message: Message, formatters: Map<string, string>, used: Set<Helper>)
     {
         this.key = key;
         this.message = message;
+        this.formatters = formatters;
+        this.used = used;
+    }
+
+    /** The module-level binding of a formatter whose options are known at compile time, created on first use and shared by every message that creates it the same way. */
+    private shared(create: string): string
+    {
+        this.used.add("once");
+        let binding = this.formatters.get(create);
+        if (binding === undefined)
+        {
+            binding = `$f${this.formatters.size}`;
+            this.formatters.set(create, binding);
+        }
+        return binding;
     }
 
     private fail(text: string): never
@@ -442,6 +495,7 @@ class Emitter
 
     private argument(name: string, type: ArgumentType): string
     {
+        this.reads++;
         const local = this.locals.get(name);
         if (local !== undefined)
         {
@@ -456,7 +510,7 @@ class Emitter
         {
             this.fail(`$${name} is used both as ${existing} and as ${type}`);
         }
-        return `args.${name}`;
+        return PLAIN_NAME.test(name) ? `args.${name}` : `args[${jsLiteral(name)}]`;
     }
 
     private optionValue(value: Literal | Variable | undefined): string | undefined
@@ -465,7 +519,7 @@ class Emitter
         {
             return undefined;
         }
-        return value.kind === "literal" ? JSON.stringify(value.value) : `String(${this.argument(value.name, "string")})`;
+        return value.kind === "literal" ? jsLiteral(value.value) : `String(${this.argument(value.name, "string")})`;
     }
 
     private numberOptions(expression: Expression): string
@@ -500,14 +554,14 @@ class Emitter
             }
             else if (option === "useGrouping" && value.kind === "literal")
             {
-                entries.push(`useGrouping: ${value.value === "never" ? "false" : value.value === "always" ? "true" : JSON.stringify(value.value)}`);
+                entries.push(`useGrouping: ${value.value === "never" ? "false" : value.value === "always" ? "true" : jsLiteral(value.value)}`);
             }
             else if (option === "fractionDigits" && value.kind === "literal" && /^[0-9]+$/.test(value.value))
             {
                 entries.push(`minimumFractionDigits: ${value.value}`, `maximumFractionDigits: ${value.value}`);
             }
         }
-        return `{ ${entries.join(", ")} }`;
+        return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
     }
 
     private dateOptions(expression: Expression): string
@@ -522,17 +576,17 @@ class Emitter
         const length = literal(fn === "datetime" ? "dateLength" : "length") ?? (fn === "time" ? undefined : "medium");
         if (length !== undefined && fn !== "time")
         {
-            entries.push(`dateStyle: ${JSON.stringify(length)}`);
+            entries.push(`dateStyle: ${jsLiteral(length)}`);
         }
         const precision = literal(fn === "datetime" ? "timePrecision" : "precision") ?? (fn === "date" ? undefined : "minute");
         if (precision !== undefined && fn !== "date")
         {
-            entries.push(`timeStyle: ${JSON.stringify(precision === "second" ? "medium" : "short")}`);
+            entries.push(`timeStyle: ${jsLiteral(precision === "second" ? "medium" : "short")}`);
         }
         const zone = literal("timeZone");
         if (zone !== undefined && zone !== "input")
         {
-            entries.push(`timeZone: ${JSON.stringify(zone)}`);
+            entries.push(`timeZone: ${jsLiteral(zone)}`);
         }
         const hour12 = literal("hour12");
         if (hour12 !== undefined)
@@ -542,9 +596,9 @@ class Emitter
         const style = literal("timeZoneStyle");
         if (style !== undefined)
         {
-            entries.push(`timeZoneName: ${JSON.stringify(style)}`);
+            entries.push(`timeZoneName: ${jsLiteral(style)}`);
         }
-        return `{ ${entries.join(", ")} }`;
+        return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
     }
 
     /** The JavaScript for an expression's numeric value, before formatting. */
@@ -577,13 +631,13 @@ class Emitter
         return value;
     }
 
-    /** Resolves a plain `{$x}` to its declaration when one exists. */
-    private resolve(expression: Expression): Expression
+    /** Resolves a plain `{$x}` to its `.input` declaration when one exists, or with `locals` to its `.local` one too, so a selector on a local selects as its expression does. */
+    private resolve(expression: Expression, locals = false): Expression
     {
         if (expression.fn === undefined && expression.operand?.kind === "variable")
         {
             const declared = this.message.declarations.get(expression.operand.name);
-            if (declared !== undefined && !declared.local)
+            if (declared !== undefined && (locals || !declared.local))
             {
                 return declared.expression;
             }
@@ -603,11 +657,19 @@ class Emitter
             {
                 this.fail(":string needs an operand");
             }
-            return operand.kind === "literal" ? JSON.stringify(operand.value) : `String(${this.argument(operand.name, "string")})`;
+            return operand.kind === "literal" ? jsLiteral(operand.value) : `String(${this.argument(operand.name, "string")})`;
         }
         if (NUMBER_FUNCTIONS.has(fn))
         {
-            return `number(${this.numeric(expression)}, ${this.numberOptions(expression)})`;
+            const value = this.numeric(expression);
+            const reads = this.reads;
+            const options = this.numberOptions(expression);
+            if (this.reads === reads)
+            {
+                return `${this.shared(`new Intl.NumberFormat(locale, ${options})`)}().format(${value})`;
+            }
+            this.used.add("number");
+            return `$number(${value}, ${options})`;
         }
         if (DATE_FUNCTIONS.has(fn))
         {
@@ -616,8 +678,8 @@ class Emitter
             {
                 this.fail(`:${fn} needs an operand`);
             }
-            const value = operand.kind === "literal" ? `new Date(${JSON.stringify(operand.value)})` : this.argument(operand.name, "date");
-            return `date(${value}, ${this.dateOptions(expression)})`;
+            const value = operand.kind === "literal" ? `new Date(${jsLiteral(operand.value)})` : this.argument(operand.name, "date");
+            return `${this.shared(`new Intl.DateTimeFormat(locale, ${this.dateOptions(expression)})`)}().format(${value})`;
         }
         this.fail(`unknown function :${fn}`);
     }
@@ -625,7 +687,7 @@ class Emitter
     /** The JavaScript for a selector: its comparable value and the categories it matches. */
     selector(raw: Expression): string
     {
-        const expression = this.resolve(raw);
+        const expression = this.resolve(raw, true);
         const fn = expression.fn ?? "string";
         if (NUMBER_FUNCTIONS.has(fn))
         {
@@ -636,7 +698,15 @@ class Emitter
             {
                 return `{ value: String(${value}), categories: [] }`;
             }
-            return `{ value: String(${value}), categories: [plural(${value}, ${JSON.stringify(mode === "ordinal" ? "ordinal" : "cardinal")})] }`;
+            const type = jsLiteral(mode === "ordinal" ? "ordinal" : "cardinal");
+            const reads = this.reads;
+            const options = this.numberOptions(expression);
+            if (this.reads === reads)
+            {
+                return `{ value: String(${value}), categories: [${this.shared(`new Intl.PluralRules(locale, { ...new Intl.NumberFormat(locale, ${options}).resolvedOptions(), type: ${type} })`)}().select(${value})] }`;
+            }
+            this.used.add("plural");
+            return `{ value: String(${value}), categories: [$plural(${value}, ${type}, ${options})] }`;
         }
         if (fn === "string")
         {
@@ -645,7 +715,7 @@ class Emitter
             {
                 this.fail("a selector needs an operand");
             }
-            const value = operand.kind === "literal" ? JSON.stringify(operand.value) : `String(${this.argument(operand.name, "string")})`;
+            const value = operand.kind === "literal" ? jsLiteral(operand.value) : `String(${this.argument(operand.name, "string")})`;
             return `{ value: ${value}, categories: [] }`;
         }
         this.fail(`:${fn} cannot select`);
@@ -657,7 +727,7 @@ class Emitter
         {
             return "\"\"";
         }
-        return parts.map((part) => (typeof part === "string" ? JSON.stringify(part) : this.format(part))).join(" + ");
+        return parts.map((part) => (typeof part === "string" ? jsLiteral(part) : this.format(part))).join(" + ");
     }
 
     body(): string
@@ -667,8 +737,9 @@ class Emitter
             if (declaration.local)
             {
                 const value = this.format(declaration.expression);
-                this.locals.set(name, `local_${name}`);
-                this.prelude.push(`const local_${name} = ${value};`);
+                const binding = PLAIN_NAME.test(name) ? `local_${name}` : `local_${this.locals.size}`;
+                this.locals.set(name, binding);
+                this.prelude.push(`const ${binding} = ${value};`);
             }
         }
         if (this.message.pattern !== undefined)
@@ -676,36 +747,77 @@ class Emitter
             return this.pattern(this.message.pattern);
         }
         const selectors = this.message.selectors.map((selector) => this.selector(selector));
-        const variants = this.message.variants.map((variant) => `{ keys: ${JSON.stringify(variant.keys)}, pattern: () => ${this.pattern(variant.pattern)} }`);
-        return `select([${selectors.join(", ")}], [${variants.join(", ")}])`;
+        const variants = this.message.variants.map((variant) => `{ keys: ${jsLiteral(variant.keys)}, pattern: () => ${this.pattern(variant.pattern)} }`);
+        this.used.add("select");
+        return `$select([${selectors.join(", ")}], [${variants.join(", ")}])`;
     }
 }
 
-const HELPERS = `const formats = new Map();
-function cached(kind, options, create)
+/** A group of helpers a compiled module shares; each is written only when one of the module's messages uses it. */
+type Helper = "cache" | "once" | "number" | "plural" | "select";
+
+/** The helpers in JavaScript and in TypeScript, in the order a module writes them. */
+const HELPERS: Record<Helper, { js: string; ts: string }> = {
+    cache: {
+        js: `const $formats = new Map();
+function $cached(kind, options, create)
 {
     const key = kind + JSON.stringify(options);
-    let instance = formats.get(key);
+    let instance = $formats.get(key);
     if (instance === undefined)
     {
         instance = create();
-        formats.set(key, instance);
+        $formats.set(key, instance);
     }
     return instance;
-}
-function number(value, options)
+}`,
+        ts: `const $formats: Map<string, unknown> = new Map();
+function $cached<T>(kind: string, options: object, create: () => T): T
 {
-    return cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
-}
-function date(value, options)
+    const key = kind + JSON.stringify(options);
+    let instance = $formats.get(key) as T | undefined;
+    if (instance === undefined)
+    {
+        instance = create();
+        $formats.set(key, instance);
+    }
+    return instance;
+}`
+    },
+    once: {
+        js: `function $once(create)
 {
-    return cached("d", options, () => new Intl.DateTimeFormat(locale, options)).format(value);
-}
-function plural(value, type)
+    let instance;
+    return () => (instance ??= create());
+}`,
+        ts: `function $once<T>(create: () => T): () => T
 {
-    return cached("p", { type }, () => new Intl.PluralRules(locale, { type })).select(value);
-}
-function select(selectors, variants)
+    let instance: T | undefined;
+    return () => (instance ??= create());
+}`
+    },
+    number: {
+        js: `function $number(value, options)
+{
+    return $cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
+}`,
+        ts: `function $number(value: number, options: Intl.NumberFormatOptions): string
+{
+    return $cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
+}`
+    },
+    plural: {
+        js: `function $plural(value, type, options)
+{
+    return $cached("p" + type, options, () => new Intl.PluralRules(locale, { ...$cached("n", options, () => new Intl.NumberFormat(locale, options)).resolvedOptions(), type })).select(value);
+}`,
+        ts: `function $plural(value: number, type: "cardinal" | "ordinal", options: Intl.NumberFormatOptions): string
+{
+    return $cached("p" + type, options, () => new Intl.PluralRules(locale, { ...$cached("n", options, () => new Intl.NumberFormat(locale, options)).resolvedOptions(), type })).select(value);
+}`
+    },
+    select: {
+        js: `function $select(selectors, variants)
 {
     let best;
     let bestRank;
@@ -738,7 +850,7 @@ function select(selectors, variants)
         {
             continue;
         }
-        if (matches && better(rank, bestRank))
+        if (matches && $better(rank, bestRank))
         {
             best = variant;
             bestRank = rank;
@@ -746,7 +858,7 @@ function select(selectors, variants)
     }
     return best === undefined ? "" : best.pattern();
 }
-function better(rank, current)
+function $better(rank, current)
 {
     if (current === undefined)
     {
@@ -761,9 +873,8 @@ function better(rank, current)
         }
     }
     return false;
-}`;
-
-const HELPERS_TS = `interface Selector
+}`,
+        ts: `interface Selector
 {
     value: string;
     categories: string[];
@@ -773,31 +884,7 @@ interface Variant
     keys: string[];
     pattern: () => string;
 }
-const formats: Map<string, unknown> = new Map();
-function cached<T>(kind: string, options: object, create: () => T): T
-{
-    const key = kind + JSON.stringify(options);
-    let instance = formats.get(key) as T | undefined;
-    if (instance === undefined)
-    {
-        instance = create();
-        formats.set(key, instance);
-    }
-    return instance;
-}
-function number(value: number, options: Intl.NumberFormatOptions): string
-{
-    return cached("n", options, () => new Intl.NumberFormat(locale, options)).format(value);
-}
-function date(value: Date | number, options: Intl.DateTimeFormatOptions): string
-{
-    return cached("d", options, () => new Intl.DateTimeFormat(locale, options)).format(value);
-}
-function plural(value: number, type: "cardinal" | "ordinal"): string
-{
-    return cached("p", { type }, () => new Intl.PluralRules(locale, { type })).select(value);
-}
-function better(rank: number[], current: number[] | undefined): boolean
+function $better(rank: number[], current: number[] | undefined): boolean
 {
     if (current === undefined)
     {
@@ -813,7 +900,7 @@ function better(rank: number[], current: number[] | undefined): boolean
     }
     return false;
 }
-function select(selectors: Selector[], variants: Variant[]): string
+function $select(selectors: Selector[], variants: Variant[]): string
 {
     let best: Variant | undefined;
     let bestRank: number[] | undefined;
@@ -842,14 +929,27 @@ function select(selectors: Selector[], variants: Variant[]): string
                 break;
             }
         }
-        if (matches && better(rank, bestRank))
+        if (matches && $better(rank, bestRank))
         {
             best = variant;
             bestRank = rank;
         }
     }
     return best === undefined ? "" : best.pattern();
-}`;
+}`
+    }
+};
+
+/** The helpers a module's messages use, with the cache that `$number` and `$plural` share. */
+function helpersFor(used: ReadonlySet<Helper>, javascript: boolean): string
+{
+    const needed = new Set(used);
+    if (needed.has("number") || needed.has("plural"))
+    {
+        needed.add("cache");
+    }
+    return (Object.keys(HELPERS) as Helper[]).filter((name) => needed.has(name)).map((name) => HELPERS[name][javascript ? "js" : "ts"]).join("\n");
+}
 
 function typeOf(type: ArgumentType): string
 {
@@ -860,21 +960,26 @@ function typeOf(type: ArgumentType): string
  * Compiles one locale's catalog into a module: `locale`, one exported
  * function per message named from its key, and the `Intl` helpers they
  * share. Each function takes an `args` object typed from the message's
- * placeholders, or nothing when the message has none.
+ * placeholders, or nothing when the message has none. A formatter whose
+ * options are all literals is a module-level binding created on first use
+ * and shared by every message that formats the same way; options that read
+ * an argument find their formatter in a cache keyed by the options. Only
+ * the helpers the messages use are written.
  */
 export function compileMessages(locale: string, catalog: Catalog, options: CompileOptions = {}): CompiledCatalog
 {
     const javascript = options.language === "js";
     const out: string[] = [];
-    out.push(`// Generated by @zerolith/i18n from ${options.source ?? `the ${locale} catalog`}. Do not edit; regenerate instead.`);
+    out.push(`// Generated by @zerolith/i18n from ${commentText(options.source ?? `the ${locale} catalog`)}. Do not edit; regenerate instead.`);
     if (javascript)
     {
         out.push("// @ts-check");
     }
-    out.push(`export const locale${javascript ? "" : ": string"} = ${JSON.stringify(locale)};`);
-    out.push("");
-    out.push(javascript ? HELPERS : HELPERS_TS);
+    out.push(`export const locale${javascript ? "" : ": string"} = ${jsLiteral(locale)};`);
     out.push("");
+    const head = out.length;
+    const formatters = new Map<string, string>();
+    const used = new Set<Helper>();
     const names: string[] = [];
     const seen = new Set<string>();
     for (const [key, source] of Object.entries(catalog))
@@ -884,23 +989,28 @@ export function compileMessages(locale: string, catalog: Catalog, options: Compi
         {
             throw new Error(`zerolith/i18n: keys "${key}" and another one both become ${name}`);
         }
+        if (name === "locale")
+        {
+            throw new Error(`zerolith/i18n: key "${key}" becomes locale, which every compiled module exports; rename the key`);
+        }
+        const binding = RESERVED.has(name) ? `message_${name}` : name;
         seen.add(name);
         names.push(name);
         const message = new Parser(source, key).parse();
-        const emitter = new Emitter(key, message);
+        const emitter = new Emitter(key, message, formatters, used);
         const body = emitter.body();
         const args = [...emitter.arguments.entries()].toSorted(([a], [b]) => a.localeCompare(b));
-        const doc = source.replace(/\*\//g, "* /").split(/\r?\n/).map((line) => ` * ${line}`.trimEnd()).join("\n");
-        const argumentType = `{ ${args.map(([argument, type]) => `${argument}: ${typeOf(type)}`).join("; ")} }`;
+        const doc = source.replace(/\*\//g, "* /").replaceAll("<", "&lt;").split(SOURCE_LINES).map((line) => ` * ${line}`.trimEnd()).join("\n");
+        const argumentType = `{ ${args.map(([argument, type]) => `${property(argument)}: ${typeOf(type)}`).join("; ")} }`;
         if (javascript)
         {
             out.push(`/**\n${doc}${args.length > 0 ? `\n * @param {${argumentType}} args` : ""}\n * @returns {string}\n */`);
-            out.push(`export function ${name}(${args.length > 0 ? "args" : ""})`);
+            out.push(`${binding === name ? "export " : ""}function ${binding}(${args.length > 0 ? "args" : ""})`);
         }
         else
         {
             out.push(`/**\n${doc}\n */`);
-            out.push(`export function ${name}(${args.length > 0 ? `args: ${argumentType}` : ""}): string`);
+            out.push(`${binding === name ? "export " : ""}function ${binding}(${args.length > 0 ? `args: ${argumentType}` : ""}): string`);
         }
         out.push("{");
         for (const line of emitter.prelude)
@@ -909,8 +1019,15 @@ export function compileMessages(locale: string, catalog: Catalog, options: Compi
         }
         out.push(`    return ${body};`);
         out.push("}");
+        if (binding !== name)
+        {
+            out.push(`export { ${binding} as ${name} };`);
+        }
         out.push("");
     }
+    const helpers = helpersFor(used, javascript);
+    const shared = Array.from(formatters, ([create, binding]) => `const ${binding} = $once(() => ${create});`);
+    out.splice(head, 0, ...(helpers === "" ? [] : [helpers, ""]), ...(shared.length === 0 ? [] : [...shared, ""]));
     return { code: out.join("\n"), names };
 }
 
@@ -935,14 +1052,14 @@ export function compileIndex(locales: readonly string[], options: CompileOptions
     }
     if (!javascript)
     {
-        lines.push(`import type * as first from "./${locales[0] ?? "en"}.${extension}";`);
+        lines.push(`import type * as first from ${jsLiteral(`./${locales[0] ?? "en"}.${extension}`)};`);
         lines.push("");
     }
-    lines.push(`export const locales${javascript ? "" : ": readonly string[]"} = ${JSON.stringify(locales)};`);
+    lines.push(`export const locales${javascript ? "" : ": readonly string[]"} = ${jsLiteral(locales)};`);
     lines.push("");
     lines.push(`/** Loads one locale's messages; each locale is its own module. */`);
     lines.push(javascript ? "export const loaders = {" : "export const loaders: Readonly<Record<string, () => Promise<typeof first>>> = {");
-    lines.push(locales.map((locale) => `    ${JSON.stringify(locale)}: () => import("./${locale}.${extension}")`).join(",\n"));
+    lines.push(locales.map((locale) => `    ${jsLiteral(locale)}: () => import(${jsLiteral(`./${locale}.${extension}`)})`).join(",\n"));
     lines.push("};");
     lines.push("");
     return lines.join("\n");