@worthy-ventures/metaglotta-runtime 1.0.0

package/src/instance.ts

@@ -0,0 +1,257 @@
+import { createBackend, RecordLoadError, type Backend } from './backend.js';
+import { createCache } from './cache.js';
+import { createEvents } from './events.js';
+import { resolveFormat } from './format.js';
+import { asList, getTranslateProps, unique } from './props.js';
+import type { EventName, LanguageFallback, MetaglottaOptions, NamespaceFallback, RecordDescriptor, Subscription, TranslateProps } from './types.js';
+
+/**
+ * What both runtimes provide, and all the Angular layer asks for.
+ *
+ * Eight methods. That number is the whole reason this package could be written at all: the
+ * dependency being replaced is nineteen thousand lines, but the part anything here actually
+ * calls is this - measured by counting call sites, not by reading a feature list.
+ */
+export type I18nInstance = {
+    t: (keyOrProps: string | TranslateProps, ...rest: unknown[]) => string;
+    on: (event: EventName | 'update', handler: (event: never) => void) => Subscription;
+    run: () => Promise<void>;
+    stop: () => void;
+    getLanguage: () => string | undefined;
+    changeLanguage: (language: string) => Promise<void>;
+    addActiveNs: (ns?: NamespaceFallback, forget?: boolean) => Promise<void>;
+    removeActiveNs: (ns?: NamespaceFallback) => void;
+    /** In-memory only, and only where the record is loaded. Returns whether it took. */
+    changeTranslation: (descriptor: { language?: string; namespace?: string }, key: string, value: string) => boolean;
+};
+
+const DEFAULT_FORMAT_ERROR = 'invalid';
+
+/**
+ * The Metaglotta translation runtime.
+ *
+ * Everything the eleven applications do in production: hold translations per language and
+ * namespace, fetch the ones they need from the CDN, fall back through namespaces and
+ * languages when a key is missing, format ICU, and say when any of that changed.
+ *
+ * What it deliberately does not do is in-context editing. That needs the page's rendered text
+ * traced back to its key, which means wrapping every string and watching the DOM - a
+ * different job, only wanted while authoring, and it stays where it is until it is rewritten
+ * too. Both runtimes satisfy I18nInstance, so a bootstrap picks one per environment.
+ */
+export function Metaglotta(options: MetaglottaOptions): I18nInstance {
+    const events = createEvents();
+    const cache = createCache();
+    const format = resolveFormat(options.format);
+    const backend: Backend | undefined = options.backend ? createBackend(options.backend) : undefined;
+    const onMissing = options.onMissing ?? ((props: TranslateProps) => props.key);
+    // Identity in production: there is nothing to decorate a string with, and a call per
+    // rendered string is worth not making.
+    const decorate: NonNullable<MetaglottaOptions['decorate']> = options.decorate ?? ((result: string) => result);
+
+    /** Namespaces a subscriber is currently holding open, by how many hold each. */
+    const active = new Map<string, number>();
+    /**
+     * Loads in flight, by record.
+     *
+     * Every pipe instance activates its namespace on subscribe - some thousands of them on a
+     * first render - and without this each would start its own fetch of the same file.
+     */
+    const inFlight = new Map<string, Promise<void>>();
+
+    let language = options.language;
+    /** The language a change is on its way to, so a slower earlier change cannot win. */
+    let pending = options.language;
+    let running = false;
+    let runPromise: Promise<void> | undefined;
+
+    for (const [key, data] of Object.entries(options.staticData ?? {})) {
+        const [first, ...rest] = key.split(':');
+        cache.set({ language: first!, namespace: rest.join(':') }, data);
+    }
+
+    const defaultNamespace = (): string => options.defaultNs ?? options.ns?.[0] ?? '';
+
+    /** Where a lookup looks, in order: the one asked for, then the configured fallbacks. */
+    const lookupNamespaces = (ns: NamespaceFallback): string[] => unique([...asList(ns ?? defaultNamespace()), ...asList(options.fallbackNs)]);
+
+    /** Everything that must be in memory: the fallbacks plus whatever is being held open. */
+    const requiredNamespaces = (ns?: NamespaceFallback): string[] =>
+        unique([...asList(ns ?? defaultNamespace()), defaultNamespace(), ...(options.ns ?? []), ...asList(options.fallbackNs), ...active.keys()]);
+
+    const languagesFor = (requested?: string): string[] => {
+        const from = requested || language;
+        if (!from) return [];
+        return unique([from, ...fallbacksOf(from, options.fallbackLanguage)]);
+    };
+
+    const descriptors = (forLanguage?: string, ns?: NamespaceFallback): RecordDescriptor[] =>
+        languagesFor(forLanguage).flatMap(lang => requiredNamespaces(ns).map(namespace => ({ language: lang, namespace })));
+
+    async function loadOne(descriptor: RecordDescriptor): Promise<void> {
+        if (!backend || cache.has(descriptor)) return;
+
+        const key = `${descriptor.language}:${descriptor.namespace}`;
+        const existing = inFlight.get(key);
+        if (existing) return existing;
+
+        const attempt = backend
+            .load(descriptor)
+            .then(data => {
+                // A backend that returns nothing has nothing to say about this record, which
+                // is different from failing: leave the record absent so a later load retries.
+                if (data) {
+                    cache.set(descriptor, data);
+                    events.emit('cache', descriptor);
+                }
+            })
+            .catch((error: unknown) => {
+                events.emit('error', error);
+                console.error(error);
+                if (!backend.fallbackOnFail) throw error;
+                /**
+                 * Remembered as empty rather than left absent.
+                 *
+                 * Absent means "not loaded", and every one of the thousands of pipes on a
+                 * page activates its namespace on subscribe - so a namespace whose file 404s
+                 * would be re-fetched once per pipe, for as long as the page is open. One
+                 * bad path is a deploy mistake; it should not also be a thundering herd.
+                 */
+                cache.set(descriptor, {});
+            })
+            .finally(() => inFlight.delete(key));
+
+        inFlight.set(key, attempt);
+        return attempt;
+    }
+
+    const loadAll = async (records: RecordDescriptor[]): Promise<void> => {
+        await Promise.all(records.map(loadOne));
+    };
+
+    function formatted(props: TranslateProps, text: string, forLanguage: string): string {
+        try {
+            return format({ translation: text, language: forLanguage, params: props.params });
+        } catch (error) {
+            console.error(error);
+            const handler = options.onFormatError;
+            if (typeof handler === 'string') return handler;
+            if (typeof handler === 'function') return handler(messageOf(error), props);
+            return DEFAULT_FORMAT_ERROR;
+        }
+    }
+
+    const self: I18nInstance = {
+        t(keyOrProps, ...rest) {
+            const props = getTranslateProps(keyOrProps, ...rest);
+            const namespaces = lookupNamespaces(props.ns);
+            const stored = cache.find(namespaces, languagesFor(props.language), props.key);
+
+            /**
+             * Where the string came from, or - with nothing stored - where a new one would go.
+             *
+             * Only interesting to the decorate pass, and only in the authoring build, but it
+             * has to be worked out here: this is the one place that knows which namespace
+             * answered, and by the time anybody clicks the rendered text it is unknowable.
+             */
+            const namespace = stored?.namespace ?? namespaces[0] ?? '';
+
+            /**
+             * The missing case, which two call sites depend on being exactly this.
+             *
+             * With nothing stored and no default, t() ECHOES THE KEY - that is what makes a
+             * missing string visible on the page instead of a silent gap, and callers write
+             * `instant(k) || fallback` against it. The pipe passes orEmpty and so renders ''.
+             */
+            const value = stored?.value ?? props.defaultValue;
+            if (value === undefined) return decorate(props.orEmpty ? '' : onMissing(props), props, namespace);
+
+            const forLanguage = props.language || language;
+            if (!value || !forLanguage) return decorate(value, props, namespace);
+            return decorate(formatted(props, value, forLanguage), props, namespace);
+        },
+
+        /**
+         * Rewrites one translation in memory.
+         *
+         * For the in-context dialog: the page shows the new text the moment it is saved,
+         * rather than after a reload. Refuses a namespace nothing has loaded, because writing
+         * into one would invent a record no element reads and hide the mistake.
+         */
+        changeTranslation(descriptor, key, value) {
+            const written = cache.write({ language: descriptor.language ?? language, namespace: descriptor.namespace ?? defaultNamespace() }, key, value);
+            if (written) events.emit('cache', descriptor);
+            return written;
+        },
+
+        on: events.on,
+
+        getLanguage: () => language,
+
+        async changeLanguage(next: string) {
+            if (pending === next && language === next) return;
+            pending = next;
+
+            if (running) await loadAll(descriptors(next));
+
+            // Two changes can be in flight at once, and the one that finishes last is not
+            // necessarily the one that was asked for last. Only the latest may apply.
+            if (pending !== next) return;
+            if (language !== next) {
+                language = next;
+                events.emit('language', next);
+            }
+        },
+
+        async addActiveNs(ns?: NamespaceFallback, forget?: boolean) {
+            if (!forget) {
+                // Naming no namespace holds nothing open: the default one is always required
+                // anyway, so there is nothing for a reference count to keep alive.
+                for (const namespace of asList(ns)) {
+                    active.set(namespace, (active.get(namespace) ?? 0) + 1);
+                }
+            }
+            if (running) await loadAll(descriptors(undefined, ns));
+        },
+
+        removeActiveNs(ns?: NamespaceFallback) {
+            for (const namespace of asList(ns)) {
+                const held = active.get(namespace);
+                if (held !== undefined && held > 1) active.set(namespace, held - 1);
+                else active.delete(namespace);
+            }
+        },
+
+        run() {
+            if (!running) {
+                running = true;
+                runPromise = loadAll(descriptors()).then(() => {
+                    events.emit('initialLoad', undefined);
+                });
+            }
+            return runPromise ?? Promise.resolve();
+        },
+
+        stop() {
+            running = false;
+        },
+    };
+
+    return self;
+}
+
+/** A fallback language list, which may be given per language or for all of them. */
+function fallbacksOf(forLanguage: string, fallback: LanguageFallback): string[] {
+    if (fallback && typeof fallback === 'object' && !Array.isArray(fallback)) {
+        return asList(fallback[forLanguage]);
+    }
+    return asList(fallback as NamespaceFallback);
+}
+
+function messageOf(error: unknown): string {
+    if (typeof error === 'string') return error;
+    if (error instanceof Error) return error.message;
+    return DEFAULT_FORMAT_ERROR;
+}
+
+export { RecordLoadError };

package/src/props.test.ts

@@ -0,0 +1,79 @@
+import { asList, getTranslateProps, unique } from './props.js';
+
+/**
+ * How t() is called.
+ *
+ * Five forms, and the awkward one is `t(key, default, options)`: options and parameters share
+ * a single object, so anything that is not a known option name is a parameter. Getting that
+ * split wrong turns `ns` into a message parameter, and the string then renders from the wrong
+ * namespace with a stray placeholder.
+ */
+describe('getTranslateProps', () => {
+    it('takes a key on its own', () => {
+        expect(getTranslateProps('greeting')).toEqual({ key: 'greeting' });
+    });
+
+    it('takes a key and a default value', () => {
+        expect(getTranslateProps('greeting', 'Hello')).toEqual({ key: 'greeting', defaultValue: 'Hello' });
+    });
+
+    it('reads a bare object as parameters, not as options', () => {
+        expect(getTranslateProps('greeting', { name: 'Ada' })).toEqual({ key: 'greeting', params: { name: 'Ada' } });
+    });
+
+    it('separates the options from the parameters they travel with', () => {
+        expect(getTranslateProps('greeting', 'Hello', { ns: 'login', name: 'Ada' })).toEqual({
+            key: 'greeting',
+            defaultValue: 'Hello',
+            ns: 'login',
+            params: { name: 'Ada' },
+        });
+    });
+
+    it('knows every option name, so none of them leaks into the parameters', () => {
+        const props = getTranslateProps('greeting', { ns: 'login', noWrap: true, orEmpty: true, language: 'el', name: 'Ada' });
+
+        expect(props.ns).toBe('login');
+        expect(props.noWrap).toBe(true);
+        expect(props.orEmpty).toBe(true);
+        expect(props.language).toBe('el');
+        expect(props.params).toEqual({ name: 'Ada' });
+    });
+
+    it('passes a full props object straight through', () => {
+        const props = { key: 'greeting', ns: 'login', params: { name: 'Ada' } };
+        expect(getTranslateProps(props)).toBe(props);
+    });
+
+    /** The explicit key wins: it is the one the caller wrote outside the options bag. */
+    it('does not let the options bag overwrite the key', () => {
+        expect(getTranslateProps('greeting', { key: 'other' } as never).key).toBe('greeting');
+    });
+
+    it('leaves parameters absent when there were none', () => {
+        expect(getTranslateProps('greeting', 'Hello').params).toBeUndefined();
+    });
+});
+
+describe('asList', () => {
+    it('accepts a fallback written either way', () => {
+        expect(asList('common')).toEqual(['common']);
+        expect(asList(['common', 'login'])).toEqual(['common', 'login']);
+    });
+
+    /** The default namespace is the empty string, which is a real namespace, not an absence. */
+    it('keeps the empty string, which names the default namespace', () => {
+        expect(asList('')).toEqual(['']);
+    });
+
+    it('reads nothing as no fallbacks at all', () => {
+        expect(asList(undefined)).toEqual([]);
+        expect(asList(null)).toEqual([]);
+    });
+});
+
+describe('unique', () => {
+    it('keeps the first of each, in order', () => {
+        expect(unique(['a', 'b', 'a', 'c', 'b'])).toEqual(['a', 'b', 'c']);
+    });
+});

package/src/props.ts

@@ -0,0 +1,62 @@
+import type { NamespaceFallback, TranslateParams, TranslateProps } from './types.js';
+
+/**
+ * The four ways t() can be called, reduced to one shape.
+ *
+ *   t('key')
+ *   t('key', 'Default value')
+ *   t('key', { name: 'Ada' })
+ *   t('key', 'Default value', { ns: 'login' })
+ *   t({ key: 'key', ns: 'login', params: { name: 'Ada' } })
+ *
+ * The third form is the awkward one: options and parameters share a single object, so
+ * anything that is not a known option is a parameter. That is why `ns`, `noWrap`, `orEmpty`
+ * and `language` cannot be used as parameter names - a limitation of the calling convention,
+ * not of the formatter.
+ */
+const OPTION_NAMES = ['ns', 'noWrap', 'orEmpty', 'language'] as const;
+
+type Combined = TranslateParams & Partial<TranslateProps>;
+
+function split(combined: Combined): Partial<TranslateProps> {
+    const options: Partial<TranslateProps> = {};
+    const params: TranslateParams = {};
+
+    for (const [name, value] of Object.entries(combined)) {
+        if ((OPTION_NAMES as readonly string[]).includes(name)) {
+            (options as Record<string, unknown>)[name] = value;
+        } else {
+            params[name] = value;
+        }
+    }
+
+    return { ...options, params };
+}
+
+export function getTranslateProps(keyOrProps: string | TranslateProps, ...rest: unknown[]): TranslateProps {
+    // Already the full shape: nothing to work out.
+    if (typeof keyOrProps === 'object' && keyOrProps !== null) return keyOrProps;
+
+    const props: TranslateProps = { key: keyOrProps };
+    let combined: Combined | undefined;
+
+    if (typeof rest[0] === 'string') {
+        props.defaultValue = rest[0];
+        combined = rest[1] as Combined | undefined;
+    } else if (typeof rest[0] === 'object' && rest[0] !== null) {
+        combined = rest[0] as Combined;
+    }
+
+    return combined ? { ...split(combined), ...props } : props;
+}
+
+/** A fallback list, however it was written, as an array. */
+export function asList(value: NamespaceFallback): string[] {
+    if (typeof value === 'string') return [value];
+    if (Array.isArray(value)) return value;
+    return [];
+}
+
+export function unique<T>(values: T[]): T[] {
+    return [...new Set(values)];
+}

package/src/types.ts

@@ -0,0 +1,165 @@
+/**
+ * What a caller can pass to t(), and what the runtime hands back.
+ *
+ * Deliberately small: this is the whole surface the Angular glue and the eleven applications
+ * use, verified by counting call sites rather than by reading a feature list.
+ */
+
+export type TranslateParams = Record<string, unknown>;
+
+export type TranslateProps = {
+    key: string;
+    /** Used when nothing is stored, in place of echoing the key back. */
+    defaultValue?: string;
+    params?: TranslateParams;
+    /**
+     * Where to look. Undefined means the default namespace; null means the same, because
+     * callers that model "no namespace" as null are common enough to be worth accepting.
+     */
+    ns?: NamespaceFallback;
+    /** Return '' rather than the key when nothing is stored. */
+    orEmpty?: boolean;
+    /** Read a language other than the current one. */
+    language?: string;
+    /**
+     * Accepted and ignored.
+     *
+     * In-context editing wraps every rendered string so a click can be traced back to its
+     * key; noWrap opts out of that. This runtime does no wrapping at all - it is the
+     * production path - so there is nothing to opt out of. Accepted rather than rejected
+     * because the same templates render under both runtimes.
+     */
+    noWrap?: boolean;
+};
+
+/** A single namespace, several to try in order, or nothing for the default one. */
+export type NamespaceFallback = string | string[] | undefined | null;
+
+/** A language, several to fall back through, or a per-language map of those. */
+export type LanguageFallback = string | string[] | Record<string, string | string[]> | undefined;
+
+export type I18nEvent<Value = unknown> = { type: string; value: Value };
+export type Subscription = { unsubscribe(): void };
+
+export type EventName = 'language' | 'update' | 'running' | 'initialLoad' | 'cache' | 'error';
+
+/** Nested json is flattened on the way in, so a record is always one level deep. */
+export type TranslationsRecord = Record<string, string>;
+export type TranslationsInput = { [key: string]: string | number | boolean | null | undefined | TranslationsInput };
+
+export type RecordDescriptor = { language: string; namespace: string };
+
+export type GetPath = (options: { namespace: string; language: string; prefix: string }) => string;
+
+export type BackendOptions = {
+    /** Where the files live. A namespace and language are appended by getPath. */
+    prefix?: string;
+    getPath?: GetPath;
+    /**
+     * Reads the body. Given the record it was asked for, because a source may not answer in
+     * the shape it was asked in - the authoring API returns `{ [language]: {...} }` where the
+     * CDN returns the translations directly, and unwrapping that needs to know the language.
+     */
+    getData?: (response: Response, descriptor: RecordDescriptor) => Promise<unknown>;
+    headers?: Record<string, string>;
+    /**
+     * Leave a record empty when its file cannot be read, rather than failing the whole load
+     * (default true).
+     *
+     * The opposite is what the previous runtime defaulted to, and it means one missing
+     * namespace file empties every namespace: the load is one operation and it rejects as
+     * one. A missing `reception/el.json` should cost you the reception strings, not the
+     * application. Failures are reported on the 'error' event and to the console either way.
+     */
+    fallbackOnFail?: boolean;
+    fetch?: typeof fetch;
+    /** Abort a file that has not arrived in this many milliseconds. */
+    timeout?: number;
+};
+
+export type FormatFn = (options: { translation: string; language: string; params?: TranslateParams }) => string;
+
+/**
+ * A last pass over the finished string, for in-context editing.
+ *
+ * The authoring build appends invisible characters naming the key, so a click on the rendered
+ * text can be traced back to what produced it. Production leaves this unset and the string
+ * goes out exactly as formatted.
+ *
+ * `namespace` is where the string was RESOLVED FROM, which is not what the caller asked with:
+ * a template writing `{{ 'greeting' | translate }}` names no namespace at all, and one
+ * writing `ns: 'login'` may still have been answered out of `common` by the fallback. Passing
+ * the caller's own answer through here instead sends anything editing the string to the wrong
+ * place - and for the default case, to a namespace nothing is in. When there is nothing stored
+ * it is the namespace a new key would be created in.
+ */
+export type DecorateFn = (result: string, props: TranslateProps, namespace: string) => string;
+
+export type MetaglottaOptions = {
+    /** The language to start in. */
+    language: string;
+    /** Tried in order when the current language has nothing for a key. */
+    fallbackLanguage?: LanguageFallback;
+    /** Fetched up front, and always kept loaded. */
+    ns?: string[];
+    /** Where to look when a call names no namespace of its own. */
+    fallbackNs?: NamespaceFallback;
+    /** The namespace a call with no namespace means (default: the first of `ns`). */
+    defaultNs?: string;
+    /**
+     * Accepted and ignored.
+     *
+     * It exists for language detection and for loading every language at once, neither of
+     * which this runtime does. Kept in the type so a bootstrap can pass the same options
+     * object to either runtime.
+     */
+    availableLanguages?: string[];
+    /** Where translations are loaded from. Omitted, nothing is loaded. */
+    backend?: BackendOptions;
+    /**
+     * How a stored string becomes the rendered one. 'icu' is the ICU MessageFormat used
+     * across these projects; 'none' returns it unchanged.
+     */
+    format?: 'icu' | 'none' | FormatFn;
+    /** Translations to start with, keyed `language` or `language:namespace`. */
+    staticData?: Record<string, TranslationsInput>;
+    /**
+     * What a missing translation renders as, when there is no defaultValue and orEmpty was
+     * not asked for. The default echoes the key, which is what makes a missing string
+     * visible on the page rather than a silent gap.
+     */
+    onMissing?: (props: TranslateProps) => string;
+    /** What an unformattable string renders as. Default 'invalid'. */
+    onFormatError?: string | ((error: string, props: TranslateProps) => string);
+    /**
+     * A last pass over every finished string. Used by in-context editing and by nothing else.
+     *
+     * Applied to the MISSING case too - to the echoed key, and to the empty string orEmpty
+     * asks for - because a key with no translation yet is exactly the one somebody wants to
+     * click on.
+     */
+    decorate?: DecorateFn;
+};
+
+/** The options half of the combined bag `t(key, { ns, name })` accepts. */
+export type TranslateOptions = {
+    ns?: NamespaceFallback;
+    noWrap?: boolean;
+    orEmpty?: boolean;
+    language?: string;
+};
+
+/**
+ * How t(), instant(), translate() and the pipe are all called.
+ *
+ * Written out as overloads rather than a loose signature because these are the shapes 3,709
+ * template uses and 938 call sites already have, and the compiler is the only thing that
+ * would notice if one of them stopped being accepted.
+ */
+export type TranslateFn<Result> = {
+    (key: string): Result;
+    (key: string, defaultValue: string): Result;
+    (key: string, options: TranslateParams & TranslateOptions): Result;
+    (key: string, defaultValue: string, options: TranslateParams & TranslateOptions): Result;
+    (props: TranslateProps): Result;
+};