@worthy-ventures/metaglotta-runtime 1.0.0

package/src/backend.ts

@@ -0,0 +1,81 @@
+import type { BackendOptions, GetPath, RecordDescriptor, TranslationsInput } from './types.js';
+
+/**
+ * Loading one `{namespace}/{language}.json` from wherever the translations are published.
+ *
+ * Deliberately not a plugin. There is exactly one backend in these applications - a
+ * CloudFront prefix - and a plugin system for a single implementation is machinery with
+ * nothing to choose between.
+ */
+
+const defaultGetPath: GetPath = ({ namespace, language, prefix }) => {
+    const base = prefix.replace(/\/+$/, '');
+    return namespace ? `${base}/${namespace}/${language}.json` : `${base}/${language}.json`;
+};
+
+/**
+ * Carries which record failed, because the url alone does not say it.
+ *
+ * The caller decides whether one unreadable file costs a namespace or the whole load, and it
+ * cannot decide that without knowing which namespace it was.
+ */
+export class RecordLoadError extends Error {
+    constructor(
+        readonly descriptor: RecordDescriptor,
+        readonly url: string,
+        readonly cause: unknown
+    ) {
+        super(`Metaglotta: could not load ${descriptor.namespace || '(default)'}/${descriptor.language} from ${url}`);
+        this.name = 'RecordLoadError';
+    }
+}
+
+export type Backend = {
+    load: (descriptor: RecordDescriptor) => Promise<TranslationsInput | undefined>;
+    /** Whether a failed record is survivable. Read by the caller, not here. */
+    fallbackOnFail: boolean;
+};
+
+export function createBackend(options: BackendOptions): Backend {
+    const prefix = options.prefix ?? '/i18n';
+    const getPath = options.getPath ?? defaultGetPath;
+    const getData = options.getData ?? ((response: Response) => response.json() as Promise<unknown>);
+    const headers = { Accept: 'application/json', ...options.headers };
+    const fetchFn = options.fetch ?? ((input: RequestInfo | URL, init?: RequestInit) => fetch(input, init));
+
+    return {
+        fallbackOnFail: options.fallbackOnFail !== false,
+        async load(descriptor: RecordDescriptor): Promise<TranslationsInput | undefined> {
+            const url = getPath({ ...descriptor, prefix });
+            try {
+                const response = await withTimeout(() => fetchFn(url, { headers }), options.timeout, url);
+                if (!response.ok) throw new Error(`responded ${response.status}`);
+                return (await getData(response, descriptor)) as TranslationsInput;
+            } catch (error) {
+                throw new RecordLoadError(descriptor, url, error);
+            }
+        },
+    };
+}
+
+/**
+ * A fetch that gives up.
+ *
+ * Without this a hung connection holds the initial load open for as long as the browser's own
+ * timeout, which is minutes - and an application that awaits run() waits with it.
+ */
+async function withTimeout(run: () => Promise<Response>, ms: number | undefined, url: string): Promise<Response> {
+    if (ms === undefined) return run();
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+        return await Promise.race([
+            run(),
+            new Promise<never>((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms: ${url}`)), ms);
+            }),
+        ]);
+    } finally {
+        if (timer) clearTimeout(timer);
+    }
+}

package/src/cache.test.ts

@@ -0,0 +1,99 @@
+import { createCache, flatten, recordKey } from './cache.js';
+
+describe('flatten', () => {
+    it('joins nested keys with a dot, which is how templates ask for them', () => {
+        expect(flatten({ menu: { file: { save: 'Save' } }, ok: 'OK' })).toEqual({ 'menu.file.save': 'Save', ok: 'OK' });
+    });
+
+    /**
+     * A null in the file means the string has no translation yet. Storing it would count as a
+     * hit and stop the language fallback from ever running, so the key would render empty in
+     * every language instead of falling back to English.
+     */
+    it('drops empty values rather than storing them as hits', () => {
+        expect(flatten({ a: null, b: undefined, c: 'here' })).toEqual({ c: 'here' });
+    });
+
+    it('keeps numbers and booleans as the strings they render as', () => {
+        expect(flatten({ count: 3, on: true })).toEqual({ count: '3', on: 'true' });
+    });
+
+    it('has nothing to say about an empty file', () => {
+        expect(flatten({})).toEqual({});
+    });
+});
+
+describe('recordKey', () => {
+    it('names the default namespace by the language alone', () => {
+        expect(recordKey({ language: 'en', namespace: '' })).toBe('en');
+        expect(recordKey({ language: 'en', namespace: 'login' })).toBe('en:login');
+    });
+});
+
+describe('the cache', () => {
+    it('stores and finds a translation', () => {
+        const cache = createCache();
+        cache.set({ language: 'en', namespace: 'login' }, { greeting: 'Hello' });
+
+        expect(cache.find(['login'], ['en'], 'greeting')).toEqual({ value: 'Hello', namespace: 'login' });
+        expect(cache.find(['login'], ['en'], 'missing')).toBeUndefined();
+    });
+
+    /**
+     * The order of the two loops decides which translation the page shows, and it only shows
+     * up for keys that exist in more than one namespace - which is to say, silently.
+     *
+     * Namespace is the outer loop. Asked for `login` with `common` as fallback, in `el` with
+     * `en` as fallback, a key present in BOTH login/en and common/el resolves to login/en:
+     * the namespace you asked for wins over the language you asked for.
+     */
+    it('exhausts a namespace before moving to the next one', () => {
+        const cache = createCache();
+        cache.set({ language: 'en', namespace: 'login' }, { greeting: 'Hello from login' });
+        cache.set({ language: 'el', namespace: 'common' }, { greeting: 'Γεια from common' });
+
+        expect(cache.find(['login', 'common'], ['el', 'en'], 'greeting')).toEqual({ value: 'Hello from login', namespace: 'login' });
+    });
+
+    /**
+     * And it says which namespace answered, not which one was asked for. Anything that edits
+     * the string afterwards has to go to where the string actually is.
+     */
+    it('falls through to the next namespace when the first has nothing, and says so', () => {
+        const cache = createCache();
+        cache.set({ language: 'el', namespace: 'common' }, { greeting: 'Γεια' });
+
+        expect(cache.find(['login', 'common'], ['el', 'en'], 'greeting')).toEqual({ value: 'Γεια', namespace: 'common' });
+    });
+
+    it('flattens on the way in, so nested files are found by their dotted key', () => {
+        const cache = createCache();
+        cache.set({ language: 'en', namespace: '' }, { menu: { save: 'Save' } });
+
+        expect(cache.find([''], ['en'], 'menu.save')?.value).toBe('Save');
+    });
+
+    it('knows whether a record has been loaded, which is not the same as having the key', () => {
+        const cache = createCache();
+        cache.set({ language: 'en', namespace: 'login' }, {});
+
+        expect(cache.has({ language: 'en', namespace: 'login' })).toBe(true);
+        expect(cache.has({ language: 'el', namespace: 'login' })).toBe(false);
+    });
+
+    describe('writing a single translation', () => {
+        it('changes what a lookup finds', () => {
+            const cache = createCache();
+            cache.set({ language: 'en', namespace: '' }, { greeting: 'Hello' });
+
+            expect(cache.write({ language: 'en', namespace: '' }, 'greeting', 'Hi')).toBe(true);
+            expect(cache.find([''], ['en'], 'greeting')?.value).toBe('Hi');
+        });
+
+        /** Writing into a record nobody loaded would invent a half-loaded namespace. */
+        it('refuses a record that was never loaded, and says so', () => {
+            const cache = createCache();
+            expect(cache.write({ language: 'en', namespace: 'nope' }, 'greeting', 'Hi')).toBe(false);
+        });
+    });
+});

package/src/cache.ts

@@ -0,0 +1,80 @@
+import type { RecordDescriptor, TranslationsInput, TranslationsRecord } from './types.js';
+
+/**
+ * Translations, keyed by language and namespace.
+ *
+ * Flat on the way in. A file may nest - `{ "menu": { "save": "Save" } }` - and callers ask
+ * for `menu.save`, so the nesting is resolved once at load rather than walked on every
+ * lookup. Empty values are dropped rather than stored: a null in the file means the string
+ * has no translation, and storing it would stop the language fallback from ever running.
+ */
+export function flatten(data: TranslationsInput, prefix = ''): TranslationsRecord {
+    const flat: TranslationsRecord = {};
+
+    for (const [key, value] of Object.entries(data)) {
+        if (value === undefined || value === null) continue;
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === 'object') {
+            Object.assign(flat, flatten(value, path));
+        } else {
+            flat[path] = String(value);
+        }
+    }
+
+    return flat;
+}
+
+/** `en` for the default namespace, `en:login` otherwise - the shape staticData is keyed by. */
+export function recordKey({ language, namespace }: RecordDescriptor): string {
+    return namespace ? `${language}:${namespace}` : language;
+}
+
+export function createCache() {
+    const records = new Map<string, TranslationsRecord>();
+
+    return {
+        has(descriptor: RecordDescriptor): boolean {
+            return records.has(recordKey(descriptor));
+        },
+
+        set(descriptor: RecordDescriptor, data: TranslationsInput): void {
+            records.set(recordKey(descriptor), flatten(data));
+        },
+
+        /**
+         * The first stored value, trying every namespace against every language.
+         *
+         * Namespace is the OUTER loop, and that is not arbitrary: a key present in both the
+         * asked-for namespace's fallback language and a fallback namespace's primary
+         * language resolves to the former. Reversing the loops changes which translation the
+         * page shows, silently, and only for keys that exist in two namespaces.
+         *
+         * WHERE it was found comes back with it. A template that names no namespace still
+         * resolves to a real one, and anything that wants to edit the string afterwards needs
+         * that name rather than the nothing the caller asked with.
+         */
+        find(namespaces: string[], languages: string[], key: string): { value: string; namespace: string } | undefined {
+            for (const namespace of namespaces) {
+                for (const language of languages) {
+                    const value = records.get(recordKey({ language, namespace }))?.[key];
+                    if (value !== undefined) return { value, namespace };
+                }
+            }
+            return undefined;
+        },
+
+        /** In-memory only, for a page whose text was just edited elsewhere. */
+        write(descriptor: RecordDescriptor, key: string, value: string): boolean {
+            const record = records.get(recordKey(descriptor));
+            if (!record) return false;
+            record[key] = value;
+            return true;
+        },
+
+        clear(): void {
+            records.clear();
+        },
+    };
+}
+
+export type Cache = ReturnType<typeof createCache>;

package/src/events.test.ts

@@ -0,0 +1,118 @@
+import { createEvents } from './events.js';
+
+/**
+ * What counts as "the page may now be wrong", and when it is said.
+ *
+ * The batching is the part with teeth. Every record written during a load is a change, and a
+ * load writes one per language per namespace - so an unbatched runtime re-translates the
+ * whole page once per file, which for these applications is six times for one load.
+ */
+describe('events', () => {
+    beforeEach(() => jest.useFakeTimers());
+    afterEach(() => jest.useRealTimers());
+
+    it('delivers an event to its own listeners, with its type and value', () => {
+        const events = createEvents();
+        const seen: unknown[] = [];
+        events.on('language', event => seen.push(event));
+
+        events.emit('language', 'el');
+
+        expect(seen).toEqual([{ type: 'language', value: 'el' }]);
+    });
+
+    it('stops delivering once unsubscribed', () => {
+        const events = createEvents();
+        const seen: unknown[] = [];
+        const subscription = events.on('language', event => seen.push(event));
+
+        events.emit('language', 'el');
+        subscription.unsubscribe();
+        events.emit('language', 'en');
+
+        expect(seen).toHaveLength(1);
+    });
+
+    it('reports a language change at once, because the page should not wait a tick for it', () => {
+        const events = createEvents();
+        const updates: unknown[] = [];
+        events.on('update', batch => updates.push(batch));
+
+        events.emit('language', 'el');
+
+        expect(updates).toHaveLength(1);
+    });
+
+    it('collects the writes of one load into a single update', () => {
+        const events = createEvents();
+        const updates: unknown[][] = [];
+        events.on('update', (batch: never) => updates.push(batch));
+
+        events.emit('cache', { language: 'en', namespace: 'common' });
+        events.emit('cache', { language: 'en', namespace: 'login' });
+        events.emit('cache', { language: 'el', namespace: 'common' });
+        expect(updates).toHaveLength(0);
+
+        jest.runAllTimers();
+
+        expect(updates).toHaveLength(1);
+        expect(updates[0]).toHaveLength(3);
+    });
+
+    /** A file that failed to load changed nothing on screen; re-rendering would be noise. */
+    it('does not call an error an update', () => {
+        const events = createEvents();
+        const updates: unknown[] = [];
+        events.on('update', batch => updates.push(batch));
+
+        events.emit('error', new Error('no'));
+        jest.runAllTimers();
+
+        expect(updates).toHaveLength(0);
+    });
+
+    it('still reports the error to anyone listening for one', () => {
+        const events = createEvents();
+        const errors: unknown[] = [];
+        events.on('error', event => errors.push(event));
+
+        events.emit('error', 'went wrong');
+
+        expect(errors).toEqual([{ type: 'error', value: 'went wrong' }]);
+    });
+
+    /**
+     * A handler that unsubscribes itself while the list is being walked would otherwise make
+     * the loop skip the handler that followed it - the classic mutate-while-iterating bug,
+     * and one that only shows up when two subscribers happen to be adjacent.
+     */
+    it('delivers to every listener even when one unsubscribes mid-delivery', () => {
+        const events = createEvents();
+        const seen: string[] = [];
+
+        const first = events.on('language', () => {
+            seen.push('first');
+            first.unsubscribe();
+        });
+        events.on('language', () => seen.push('second'));
+
+        events.emit('language', 'el');
+
+        expect(seen).toEqual(['first', 'second']);
+    });
+
+    it('flushes a pending batch alongside an immediate one rather than losing it', () => {
+        const events = createEvents();
+        const updates: unknown[][] = [];
+        events.on('update', (batch: never) => updates.push(batch));
+
+        events.emit('cache', { language: 'en', namespace: 'common' });
+        events.emit('language', 'el');
+
+        expect(updates).toHaveLength(1);
+        expect(updates[0]).toHaveLength(2);
+
+        jest.runAllTimers();
+        expect(updates).toHaveLength(1);
+    });
+});

package/src/events.ts

@@ -0,0 +1,77 @@
+import type { EventName, I18nEvent, Subscription } from './types.js';
+
+/**
+ * Which events mean "what is on screen may now be wrong".
+ *
+ * Cache writes are batched. A load writes one record per (language, namespace), and emitting
+ * an update for each would re-translate the page six times for one load, so they are queued
+ * and flushed on the next tick. A language change is not batched: it is a single event and
+ * the page should not wait a tick to reflect it. An error is not an update at all - nothing
+ * on screen changed because a file failed to load.
+ */
+const FEEDS_UPDATE: Partial<Record<EventName, 'now' | 'batched'>> = {
+    language: 'now',
+    initialLoad: 'now',
+    cache: 'batched',
+};
+
+export function createEvents() {
+    const handlers = new Map<string, ((event: never) => void)[]>();
+    let queued: I18nEvent[] = [];
+    let flushScheduled = false;
+
+    function listeners(name: string): ((event: never) => void)[] {
+        const existing = handlers.get(name);
+        if (existing) return existing;
+        const created: ((event: never) => void)[] = [];
+        handlers.set(name, created);
+        return created;
+    }
+
+    function deliver(name: string, payload: unknown): void {
+        // Copied before iterating: a handler that unsubscribes itself would otherwise make
+        // the loop skip the handler after it.
+        for (const handler of [...listeners(name)]) (handler as (event: unknown) => void)(payload);
+    }
+
+    function flush(): void {
+        flushScheduled = false;
+        if (!queued.length) return;
+        const batch = queued;
+        queued = [];
+        deliver('update', batch);
+    }
+
+    return {
+        on(name: EventName | 'update', handler: (event: never) => void): Subscription {
+            const list = listeners(name);
+            list.push(handler);
+            return {
+                unsubscribe() {
+                    const at = list.indexOf(handler);
+                    if (at >= 0) list.splice(at, 1);
+                },
+            };
+        },
+
+        emit(name: EventName, value: unknown): void {
+            const event: I18nEvent = { type: name, value };
+            deliver(name, event);
+
+            const update = FEEDS_UPDATE[name];
+            if (!update) return;
+
+            queued.push(event);
+            if (update === 'now') {
+                flush();
+                return;
+            }
+            if (!flushScheduled) {
+                flushScheduled = true;
+                setTimeout(flush, 0);
+            }
+        },
+    };
+}
+
+export type Events = ReturnType<typeof createEvents>;

package/src/format.test.ts

@@ -0,0 +1,92 @@
+import { formatIcu, forgetCompiled, resolveFormat } from './format.js';
+
+/**
+ * ICU formatting, and the shortcut past it.
+ *
+ * The shortcut is where a mistake would hide: most translations are literal text, so skipping
+ * the parser for them is most of the speed - but skip a string that only LOOKS literal and it
+ * renders with its escapes showing, in one language, on one page.
+ */
+describe('formatIcu', () => {
+    beforeEach(() => forgetCompiled());
+
+    const format = (translation: string, params?: Record<string, unknown>, language = 'en') => formatIcu({ translation, language, params });
+
+    it('substitutes a placeholder', () => {
+        expect(format('Hello {name}', { name: 'Ada' })).toBe('Hello Ada');
+    });
+
+    it('returns literal text unchanged', () => {
+        expect(format('Hello there')).toBe('Hello there');
+    });
+
+    it('chooses a plural form', () => {
+        const message = '{count, plural, one {# item} other {# items}}';
+        expect(format(message, { count: 1 })).toBe('1 item');
+        expect(format(message, { count: 5 })).toBe('5 items');
+    });
+
+    /** Greek has its own plural rules, and the language argument is what selects them. */
+    it('pluralises in the language it was given', () => {
+        const message = '{count, plural, one {# αρχείο} other {# αρχεία}}';
+        expect(formatIcu({ translation: message, language: 'el', params: { count: 1 } })).toBe('1 αρχείο');
+        expect(formatIcu({ translation: message, language: 'el', params: { count: 3 } })).toBe('3 αρχεία');
+    });
+
+    it('selects on a value', () => {
+        const message = '{gender, select, female {She} male {He} other {They}} replied';
+        expect(format(message, { gender: 'female' })).toBe('She replied');
+        expect(format(message, { gender: 'x' })).toBe('They replied');
+    });
+
+    /**
+     * The escape cases, and the reason the shortcut tests for an apostrophe rather than only
+     * for a brace. In ICU `''` is one apostrophe and `'{'` is a literal brace - so a string
+     * with no brace at all can still need the parser.
+     */
+    it('unescapes a doubled apostrophe, which has no brace to give it away', () => {
+        expect(format("It''s ready")).toBe("It's ready");
+    });
+
+    it('leaves a lone apostrophe alone', () => {
+        expect(format("L'utilisateur")).toBe("L'utilisateur");
+    });
+
+    it('renders a quoted brace as a brace rather than a placeholder', () => {
+        expect(format("Use '{' to open")).toBe('Use { to open');
+    });
+
+    it('formats a number for the language', () => {
+        expect(format('{n, number}', { n: 1234.5 })).toBe('1,234.5');
+    });
+
+    /** Same message, two languages: caching on the text alone would return the wrong one. */
+    it('keeps the languages apart in its cache', () => {
+        const message = '{n, number}';
+        expect(formatIcu({ translation: message, language: 'en', params: { n: 1234.5 } })).toBe('1,234.5');
+        expect(formatIcu({ translation: message, language: 'de', params: { n: 1234.5 } })).toBe('1.234,5');
+    });
+
+    it('gives the same answer the second time, from the cache', () => {
+        expect(format('Hello {name}', { name: 'Ada' })).toBe('Hello Ada');
+        expect(format('Hello {name}', { name: 'Grace' })).toBe('Hello Grace');
+    });
+
+    it('throws on a message it cannot parse, for the caller to turn into something readable', () => {
+        expect(() => format('Hello {name')).toThrow();
+    });
+});
+
+describe('resolveFormat', () => {
+    it('defaults to ICU', () => {
+        expect(resolveFormat(undefined)({ translation: 'Hello {name}', language: 'en', params: { name: 'Ada' } })).toBe('Hello Ada');
+    });
+
+    it('can be turned off, which leaves the stored string exactly as it is', () => {
+        expect(resolveFormat('none')({ translation: 'Hello {name}', language: 'en', params: { name: 'Ada' } })).toBe('Hello {name}');
+    });
+
+    it('takes a formatter of your own', () => {
+        expect(resolveFormat(({ translation }) => translation.toUpperCase())({ translation: 'hello', language: 'en' })).toBe('HELLO');
+    });
+});

package/src/format.ts

@@ -0,0 +1,59 @@
+/**
+ * The NAMED import, not the default one.
+ *
+ * intl-messageformat ships CommonJS with an ESM wrapper, and under Node's ESM interop the
+ * default export resolves to the whole module namespace rather than to the class - so
+ * `new IntlMessageFormat(...)` throws "is not a constructor", and every string with a
+ * placeholder in it renders as the format-error text. Bundlers and jest both take the
+ * CommonJS path, where the default DOES work, so nothing catches this until it is running
+ * somewhere real. The named export is the class in both.
+ */
+import { IntlMessageFormat } from 'intl-messageformat';
+import type { FormatFn, TranslateParams } from './types.js';
+
+/**
+ * ICU MessageFormat, over FormatJS directly rather than through a wrapper.
+ *
+ * Compiled formatters are cached by (language, message). Parsing an ICU message is the
+ * expensive half, and the message text is what varies least: the same string is formatted
+ * once per render of every component that shows it, with different parameters each time.
+ */
+const compiled = new Map<string, IntlMessageFormat>();
+
+/**
+ * Strings that cannot mean anything but themselves.
+ *
+ * Most translations are plain text, and running the parser over them is pure cost. Only two
+ * characters can make a string non-literal: `{` opens a placeholder, and `'` is ICU's escape
+ * character - `'{'` renders a literal brace and `''` renders one apostrophe, so `It''s` would
+ * render wrongly if this shortcut took it. `#` is special only inside a plural, which needs a
+ * `{` to open.
+ */
+const LITERAL = /^[^{']*$/;
+
+export function formatIcu({ translation, language, params }: { translation: string; language: string; params?: TranslateParams }): string {
+    if (LITERAL.test(translation)) return translation;
+
+    const cacheKey = `${language} ${translation}`;
+    let formatter = compiled.get(cacheKey);
+    if (!formatter) {
+        formatter = new IntlMessageFormat(translation, language);
+        compiled.set(cacheKey, formatter);
+    }
+
+    const formatted = formatter.format(params as Record<string, string | number> | undefined);
+    // format() returns an array for messages with rich-text tags. Nothing here uses those,
+    // but joining beats rendering "[object Object]" if one ever appears.
+    return Array.isArray(formatted) ? formatted.join('') : String(formatted);
+}
+
+/** Test seam: the cache is a module global by design, and lives as long as the page. */
+export function forgetCompiled(): void {
+    compiled.clear();
+}
+
+export function resolveFormat(format: 'icu' | 'none' | FormatFn | undefined): FormatFn {
+    if (typeof format === 'function') return format;
+    if (format === 'none') return ({ translation }) => translation;
+    return formatIcu;
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { Metaglotta } from './instance.js';
+export type { I18nInstance } from './instance.js';
+export { RecordLoadError } from './backend.js';
+export { getTranslateProps, asList, unique } from './props.js';
+export { flatten, recordKey } from './cache.js';
+export { formatIcu, forgetCompiled, resolveFormat } from './format.js';
+export type {
+    BackendOptions,
+    EventName,
+    FormatFn,
+    GetPath,
+    I18nEvent,
+    LanguageFallback,
+    MetaglottaOptions,
+    NamespaceFallback,
+    RecordDescriptor,
+    Subscription,
+    TranslateParams,
+    TranslateProps,
+    DecorateFn,
+    TranslateOptions,
+    TranslateFn,
+    TranslationsInput,
+    TranslationsRecord,
+} from './types.js';