@worthy-ventures/metaglotta-runtime 1.0.0

package/src/instance.test.ts

@@ -0,0 +1,645 @@
+import { forgetCompiled } from './format.js';
+import { Metaglotta } from './instance.js';
+import type { MetaglottaOptions, TranslationsInput } from './types.js';
+
+/**
+ * The runtime, against the behaviours the eleven applications actually depend on.
+ *
+ * These are not a description of a design - they are the contract the replaced dependency
+ * had, read off its source and off the call sites: 3,709 uses of the pipe and 938 of
+ * instant(). Anything here that looks arbitrary is arbitrary in the same way the thing it
+ * replaces was, and changing it changes what renders on somebody's screen.
+ */
+
+type Files = Record<string, TranslationsInput>;
+
+function serving(files: Files) {
+    const asked: string[] = [];
+    const fetchFn = (async (url: string) => {
+        asked.push(url);
+        const body = files[url];
+        if (!body) return { ok: false, status: 404, json: async () => ({}) } as unknown as Response;
+        return { ok: true, status: 200, json: async () => body } as unknown as Response;
+    }) as unknown as typeof fetch;
+    return { asked, fetchFn };
+}
+
+const settle = () => new Promise(resolve => setTimeout(resolve, 0));
+
+function build(files: Files, options: Partial<MetaglottaOptions> = {}) {
+    const server = serving(files);
+    const instance = Metaglotta({
+        language: 'el',
+        fallbackLanguage: 'en',
+        defaultNs: 'common',
+        ns: ['common', 'login'],
+        fallbackNs: ['common'],
+        backend: { prefix: '/langs', fetch: server.fetchFn },
+        ...options,
+    });
+    return { instance, ...server };
+}
+
+beforeEach(() => forgetCompiled());
+
+describe('translating', () => {
+    const options: Partial<MetaglottaOptions> = {
+        backend: undefined,
+        staticData: {
+            'el:common': { greeting: 'Γεια', shared: 'κοινό' },
+            'en:common': { greeting: 'Hello', shared: 'shared', onlyEnglish: 'English only' },
+            'el:login': { title: 'Σύνδεση' },
+            'en:login': { title: 'Sign in', greeting: 'Hello from login' },
+        },
+    };
+
+    it('returns the stored string', () => {
+        expect(build({}, options).instance.t('greeting')).toBe('Γεια');
+    });
+
+    /**
+     * The missing case, and it must ECHO THE KEY.
+     *
+     * 938 call sites are written against it - `instant(k) || fallback` reads as "no
+     * translation" only because the key is truthy - and a missing string is meant to be
+     * visible on the page rather than a silent gap.
+     */
+    it('echoes the key when nothing is stored', () => {
+        expect(build({}, options).instance.t('nowhere')).toBe('nowhere');
+    });
+
+    /** The pipe asks for this, which is why a template renders '' rather than the key. */
+    it('returns nothing instead when asked for orEmpty', () => {
+        expect(build({}, options).instance.t({ key: 'nowhere', orEmpty: true })).toBe('');
+    });
+
+    it('prefers a default value to echoing the key', () => {
+        expect(build({}, options).instance.t('nowhere', 'Fallback text')).toBe('Fallback text');
+    });
+
+    it('still prefers a default value when orEmpty was asked for', () => {
+        expect(build({}, options).instance.t({ key: 'nowhere', defaultValue: 'Fallback text', orEmpty: true })).toBe('Fallback text');
+    });
+
+    it('prefers what is stored to the default value', () => {
+        expect(build({}, options).instance.t('greeting', 'Fallback text')).toBe('Γεια');
+    });
+
+    it('falls back to another language when the current one has nothing', () => {
+        expect(build({}, options).instance.t('onlyEnglish')).toBe('English only');
+    });
+
+    it('reads a namespace it was told to read', () => {
+        expect(build({}, options).instance.t({ key: 'title', ns: 'login' })).toBe('Σύνδεση');
+    });
+
+    it('falls back to another namespace when the asked-for one has nothing', () => {
+        expect(build({}, options).instance.t({ key: 'shared', ns: 'login' })).toBe('κοινό');
+    });
+
+    /**
+     * Namespace before language. `greeting` exists in login/en and in common/el; asked for
+     * login in Greek, the answer is the English one from login - the namespace asked for wins
+     * over the language asked for. Reverse the loops and this silently returns 'Γεια'.
+     */
+    it('exhausts the asked-for namespace before falling back to another', () => {
+        expect(build({}, options).instance.t({ key: 'greeting', ns: 'login' })).toBe('Hello from login');
+    });
+
+    it('reads another language on request without changing the current one', () => {
+        const { instance } = build({}, options);
+        expect(instance.t({ key: 'greeting', language: 'en' })).toBe('Hello');
+        expect(instance.getLanguage()).toBe('el');
+    });
+
+    it('formats ICU with the parameters it was given', () => {
+        const { instance } = build({}, { backend: undefined, language: 'en', staticData: { en: { hi: 'Hello {name}' } }, defaultNs: '', ns: [''], fallbackNs: undefined });
+        expect(instance.t('hi', { name: 'Ada' })).toBe('Hello Ada');
+    });
+
+    it('formats in the current language, so plurals follow its rules', () => {
+        const { instance } = build(
+            {},
+            {
+                backend: undefined,
+                language: 'el',
+                staticData: { el: { files: '{count, plural, one {# αρχείο} other {# αρχεία}}' } },
+                defaultNs: '',
+                ns: [''],
+                fallbackNs: undefined,
+            }
+        );
+        expect(instance.t('files', { count: 1 })).toBe('1 αρχείο');
+        expect(instance.t('files', { count: 4 })).toBe('4 αρχεία');
+    });
+
+    /** A broken placeholder must not take the page down with it. */
+    it('renders an unformattable string as "invalid" rather than throwing', () => {
+        const spy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+        try {
+            const { instance } = build({}, { backend: undefined, language: 'en', staticData: { en: { broken: 'Hello {name' } }, defaultNs: '', ns: [''], fallbackNs: undefined });
+            expect(instance.t('broken')).toBe('invalid');
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it('lets you say what an unformattable string should render as', () => {
+        const spy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+        try {
+            const { instance } = build(
+                {},
+                { backend: undefined, language: 'en', staticData: { en: { broken: 'Hello {name' } }, defaultNs: '', ns: [''], fallbackNs: undefined, onFormatError: '???' }
+            );
+            expect(instance.t('broken')).toBe('???');
+        } finally {
+            spy.mockRestore();
+        }
+    });
+
+    it('lets you say what a missing string should render as', () => {
+        const { instance } = build({}, { ...options, onMissing: props => `[[${props.key}]]` });
+        expect(instance.t('nowhere')).toBe('[[nowhere]]');
+    });
+
+    it('reads a per-language fallback map', () => {
+        const { instance } = build(
+            {},
+            {
+                backend: undefined,
+                language: 'el',
+                fallbackLanguage: { el: 'de', de: 'en' },
+                defaultNs: '',
+                ns: [''],
+                fallbackNs: undefined,
+                staticData: { de: { greeting: 'Hallo' }, en: { greeting: 'Hello' } },
+            }
+        );
+        // One hop only: the map is consulted for the current language, not walked.
+        expect(instance.t('greeting')).toBe('Hallo');
+    });
+});
+
+describe('loading', () => {
+    const files: Files = {
+        '/langs/common/el.json': { greeting: 'Γεια' },
+        '/langs/common/en.json': { greeting: 'Hello' },
+        '/langs/login/el.json': { title: 'Σύνδεση' },
+        '/langs/login/en.json': { title: 'Sign in' },
+        '/langs/reception/el.json': { desk: 'Ρεσεψιόν' },
+        '/langs/reception/en.json': { desk: 'Reception' },
+        '/langs/common/de.json': { greeting: 'Hallo' },
+        '/langs/login/de.json': { title: 'Anmelden' },
+        '/langs/reception/de.json': { desk: 'Empfang' },
+    };
+
+    it('fetches every configured namespace in every language it may fall back to', async () => {
+        const { instance, asked } = build(files);
+        await instance.run();
+
+        expect(asked.sort()).toEqual([
+            '/langs/common/el.json',
+            '/langs/common/en.json',
+            '/langs/login/el.json',
+            '/langs/login/en.json',
+        ]);
+        expect(instance.t('greeting')).toBe('Γεια');
+        expect(instance.t({ key: 'title', ns: 'login' })).toBe('Σύνδεση');
+    });
+
+    it('runs once however many times it is asked', async () => {
+        const { instance, asked } = build(files);
+        await Promise.all([instance.run(), instance.run()]);
+        await instance.run();
+
+        expect(asked).toHaveLength(4);
+    });
+
+    it('says when the first load is done', async () => {
+        const { instance } = build(files);
+        const seen: string[] = [];
+        instance.on('initialLoad', () => seen.push('loaded'));
+
+        await instance.run();
+
+        expect(seen).toEqual(['loaded']);
+    });
+
+    it('tells the page to re-translate once for the whole load, not once per file', async () => {
+        const { instance } = build(files);
+        const updates: unknown[] = [];
+        instance.on('update', batch => updates.push(batch));
+
+        await instance.run();
+        await settle();
+
+        // One for the batched writes, one for initialLoad - not one per file.
+        expect(updates.length).toBeLessThanOrEqual(2);
+    });
+
+    /**
+     * Every pipe on the page activates its namespace as it subscribes. Some thousands of them
+     * render at once, and without in-flight de-duplication that is thousands of requests for
+     * the same file.
+     */
+    it('fetches a record once even when everything asks for it at the same time', async () => {
+        const { instance, asked } = build(files);
+        await instance.run();
+        const before = asked.length;
+
+        await Promise.all(Array.from({ length: 50 }, () => instance.addActiveNs('reception')));
+
+        expect(asked.length - before).toBe(2);
+    });
+
+    it('loads a namespace that is activated after it started', async () => {
+        const { instance } = build(files);
+        await instance.run();
+        expect(instance.t({ key: 'desk', ns: 'reception' })).toBe('desk');
+
+        await instance.addActiveNs('reception');
+
+        expect(instance.t({ key: 'desk', ns: 'reception' })).toBe('Ρεσεψιόν');
+    });
+
+    /**
+     * No fallback language in these three, on purpose. With one configured, run() has already
+     * fetched every namespace in both languages and a language change fetches nothing at all
+     * - which would make each of these pass without testing anything.
+     */
+    const oneLanguage = { fallbackLanguage: undefined };
+
+    it('keeps an activated namespace loaded for the next language too', async () => {
+        const { instance, asked } = build(files, oneLanguage);
+        await instance.run();
+        await instance.addActiveNs('reception');
+        asked.length = 0;
+
+        await instance.changeLanguage('en');
+
+        expect(asked).toContain('/langs/common/en.json');
+        expect(asked).toContain('/langs/reception/en.json');
+    });
+
+    it('stops keeping it once the last holder lets go', async () => {
+        const { instance, asked } = build(files, oneLanguage);
+        await instance.run();
+        await instance.addActiveNs('reception');
+        await instance.addActiveNs('reception');
+        instance.removeActiveNs('reception');
+        asked.length = 0;
+
+        // One of the two holders is still holding it.
+        await instance.changeLanguage('en');
+        expect(asked).toContain('/langs/reception/en.json');
+
+        instance.removeActiveNs('reception');
+        asked.length = 0;
+
+        // A third language, so what it fetches is what it needs rather than what it has.
+        await instance.changeLanguage('de');
+        expect(asked).toContain('/langs/common/de.json');
+        expect(asked).not.toContain('/langs/reception/de.json');
+    });
+
+    /** The route resolver loads a namespace for one navigation without holding it open. */
+    it('can load a namespace without holding it', async () => {
+        const { instance, asked } = build(files, oneLanguage);
+        await instance.run();
+        await instance.addActiveNs('reception', true);
+        expect(instance.t({ key: 'desk', ns: 'reception' })).toBe('Ρεσεψιόν');
+        asked.length = 0;
+
+        await instance.changeLanguage('en');
+
+        expect(asked).toContain('/langs/common/en.json');
+        expect(asked).not.toContain('/langs/reception/en.json');
+    });
+
+    it('does nothing before it is running, and catches up when it starts', async () => {
+        const { instance, asked } = build(files);
+        await instance.addActiveNs('reception');
+        expect(asked).toHaveLength(0);
+
+        await instance.run();
+
+        expect(asked).toContain('/langs/reception/el.json');
+    });
+});
+
+describe('when a file cannot be read', () => {
+    const partial: Files = { '/langs/common/el.json': { greeting: 'Γεια' }, '/langs/common/en.json': { greeting: 'Hello' } };
+    let errors: jest.SpyInstance;
+
+    beforeEach(() => {
+        errors = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+    });
+    afterEach(() => errors.mockRestore());
+
+    /** One bad path is a deploy mistake. It should cost that namespace, not the application. */
+    it('keeps the namespaces that did load', async () => {
+        const { instance } = build(partial);
+        await instance.run();
+
+        expect(instance.t('greeting')).toBe('Γεια');
+        expect(instance.t({ key: 'title', ns: 'login' })).toBe('title');
+    });
+
+    it('reports it, so a broken deploy is visible rather than merely quiet', async () => {
+        const { instance } = build(partial);
+        const seen: unknown[] = [];
+        instance.on('error', event => seen.push(event));
+
+        await instance.run();
+
+        expect(seen.length).toBeGreaterThan(0);
+        expect(errors).toHaveBeenCalled();
+    });
+
+    /**
+     * A failed record is remembered as empty rather than left absent. Absent means "not
+     * loaded", and every pipe on the page re-triggers a load for what is not loaded - so a
+     * 404 would be re-requested once per pipe, for as long as the page is open.
+     */
+    it('does not ask again for a file it already failed to read', async () => {
+        const { instance, asked } = build(partial);
+        await instance.run();
+        const before = asked.length;
+
+        await Promise.all(Array.from({ length: 20 }, () => instance.addActiveNs('login')));
+
+        expect(asked.length).toBe(before);
+    });
+
+    it('can be told to fail the whole load instead', async () => {
+        const server = serving(partial);
+        const instance = Metaglotta({
+            language: 'el',
+            defaultNs: 'common',
+            ns: ['common', 'login'],
+            backend: { prefix: '/langs', fetch: server.fetchFn, fallbackOnFail: false },
+        });
+
+        await expect(instance.run()).rejects.toThrow();
+    });
+});
+
+describe('changing language', () => {
+    const files: Files = {
+        '/langs/common/el.json': { greeting: 'Γεια' },
+        '/langs/common/en.json': { greeting: 'Hello' },
+        '/langs/common/de.json': { greeting: 'Hallo' },
+        '/langs/login/el.json': {},
+        '/langs/login/en.json': {},
+        '/langs/login/de.json': {},
+    };
+
+    it('resolves only once the new language has loaded', async () => {
+        const { instance } = build(files, { language: 'el', fallbackLanguage: undefined });
+        await instance.run();
+
+        await instance.changeLanguage('de');
+
+        expect(instance.getLanguage()).toBe('de');
+        expect(instance.t('greeting')).toBe('Hallo');
+    });
+
+    it('says so, so the page re-renders', async () => {
+        const { instance } = build(files, { fallbackLanguage: undefined });
+        await instance.run();
+        const seen: unknown[] = [];
+        instance.on('language', event => seen.push(event));
+
+        await instance.changeLanguage('en');
+
+        expect(seen).toEqual([{ type: 'language', value: 'en' }]);
+    });
+
+    it('has nothing to do when it is already that language', async () => {
+        const { instance, asked } = build(files, { fallbackLanguage: undefined });
+        await instance.run();
+        asked.length = 0;
+
+        await instance.changeLanguage('el');
+
+        expect(asked).toHaveLength(0);
+    });
+
+    /**
+     * Two changes can be in flight at once - a fast double click on a language switcher - and
+     * the one that finishes last is not necessarily the one asked for last. Only the latest
+     * request may apply, or the page settles on a language nobody chose.
+     */
+    it('applies the language asked for last, whichever finishes first', async () => {
+        const server = serving(files);
+        const delays: Record<string, number> = { '/langs/common/de.json': 40, '/langs/common/en.json': 0 };
+        const instance = Metaglotta({
+            language: 'el',
+            defaultNs: 'common',
+            ns: ['common'],
+            backend: {
+                prefix: '/langs',
+                fetch: (async (url: string) => {
+                    await new Promise(resolve => setTimeout(resolve, delays[url] ?? 0));
+                    return server.fetchFn(url) as unknown as Response;
+                }) as unknown as typeof fetch,
+            },
+        });
+        await instance.run();
+
+        const slow = instance.changeLanguage('de');
+        const fast = instance.changeLanguage('en');
+        await Promise.all([slow, fast]);
+
+        expect(instance.getLanguage()).toBe('en');
+    });
+
+    it('does not fetch anything before it is running', async () => {
+        const { instance, asked } = build(files, { fallbackLanguage: undefined });
+
+        await instance.changeLanguage('en');
+
+        expect(asked).toHaveLength(0);
+        expect(instance.getLanguage()).toBe('en');
+    });
+});
+
+describe('starting from data it was given', () => {
+    it('uses translations passed in, and asks for nothing', () => {
+        const { instance, asked } = build({}, { staticData: { 'el:common': { greeting: 'Γεια' } }, backend: undefined });
+
+        expect(instance.t('greeting')).toBe('Γεια');
+        expect(asked).toHaveLength(0);
+    });
+
+    it('reads a key with no namespace as the default one', () => {
+        const { instance } = build({}, { staticData: { el: { greeting: 'Γεια' } }, backend: undefined, defaultNs: '', ns: [''], fallbackNs: undefined });
+
+        expect(instance.t('greeting')).toBe('Γεια');
+    });
+
+    it('does not fetch what it was already given', async () => {
+        const { instance, asked } = build(
+            { '/langs/login/el.json': {}, '/langs/login/en.json': {}, '/langs/common/en.json': {} },
+            { staticData: { 'el:common': { greeting: 'Γεια' } } }
+        );
+
+        await instance.run();
+
+        expect(asked).not.toContain('/langs/common/el.json');
+    });
+});
+
+describe('the decorate pass', () => {
+    const options = { backend: undefined, staticData: { 'el:common': { greeting: 'Γεια {name}' } } };
+
+    it('sees the finished string, after formatting', () => {
+        const seen: string[] = [];
+        const { instance } = build({}, { ...options, decorate: (result: string) => { seen.push(result); return result; } });
+
+        instance.t('greeting', { name: 'Ada' });
+
+        expect(seen).toEqual(['Γεια Ada']);
+    });
+
+    it('can append to it, which is how a key travels with its own text', () => {
+        const { instance } = build({}, { ...options, decorate: (result: string, props: { key: string }) => `${result}[${props.key}]` });
+
+        expect(instance.t('greeting', { name: 'Ada' })).toBe('Γεια Ada[greeting]');
+    });
+
+    /**
+     * A key with nothing behind it yet is exactly the one somebody wants to click on, so the
+     * missing cases are decorated too - both the echoed key and the empty string.
+     */
+    it('applies to a missing translation as well', () => {
+        const { instance } = build({}, { ...options, decorate: (result: string, props: { key: string }) => `${result}[${props.key}]` });
+
+        expect(instance.t('nowhere')).toBe('nowhere[nowhere]');
+        expect(instance.t({ key: 'nowhere', orEmpty: true })).toBe('[nowhere]');
+    });
+
+    it('is absent unless asked for, so production pays nothing for it', () => {
+        const { instance } = build({}, options);
+        expect(instance.t('greeting', { name: 'Ada' })).toBe('Γεια Ada');
+    });
+
+    /**
+     * Which namespace it is told about, and why it is not the one the caller asked with.
+     *
+     * A template writing `{{ 'greeting' | translate }}` names no namespace at all. Passing
+     * that nothing through is what sent the editing dialog to the default namespace - where
+     * the key is not - so it opened with no translations, no screenshots and an extra
+     * "(default)" in its namespace list. It has to be told where the string CAME FROM.
+     */
+    describe('the namespace it reports', () => {
+        const seen: string[] = [];
+        const watching = (over: Partial<MetaglottaOptions> = {}) => {
+            seen.length = 0;
+            return build({}, {
+                backend: undefined,
+                defaultNs: 'common',
+                ns: ['common', 'login'],
+                fallbackNs: ['common'],
+                decorate: (result: string, _props: unknown, namespace: string) => {
+                    seen.push(namespace);
+                    return result;
+                },
+                ...over,
+            }).instance;
+        };
+
+        it('is the namespace the string was found in, not the nothing that was asked for', () => {
+            watching({ staticData: { 'el:common': { greeting: 'Γεια' } } }).t('greeting');
+            expect(seen).toEqual(['common']);
+        });
+
+        it('is the namespace that answered when the fallback answered', () => {
+            watching({ staticData: { 'el:common': { shared: 'κοινό' } } }).t({ key: 'shared', ns: 'login' });
+            expect(seen).toEqual(['common']);
+        });
+
+        it('is the namespace asked for when that is the one holding it', () => {
+            watching({ staticData: { 'el:login': { title: 'Σύνδεση' } } }).t({ key: 'title', ns: 'login' });
+            expect(seen).toEqual(['login']);
+        });
+
+        /** Nothing stored yet: the answer is where creating it would put it. */
+        it('is where a new key would go when there is nothing stored', () => {
+            watching({ staticData: {} }).t('nowhere');
+            expect(seen).toEqual(['common']);
+
+            watching({ staticData: {} }).t({ key: 'nowhere', ns: 'login' });
+            expect(seen).toEqual(['login']);
+        });
+
+        it('is the default namespace when the default namespace really is the empty one', () => {
+            watching({ defaultNs: '', ns: [''], fallbackNs: undefined, staticData: { el: { greeting: 'Γεια' } } }).t('greeting');
+            expect(seen).toEqual(['']);
+        });
+    });
+});
+
+describe('changing a translation in memory', () => {
+    const options = { backend: undefined, staticData: { 'el:common': { greeting: 'Γεια' } } };
+
+    it('changes what the next lookup finds', () => {
+        const { instance } = build({}, options);
+
+        expect(instance.changeTranslation({ language: 'el', namespace: 'common' }, 'greeting', 'Χαίρετε')).toBe(true);
+        expect(instance.t('greeting')).toBe('Χαίρετε');
+    });
+
+    it('says so, so the page re-renders', () => {
+        const { instance } = build({}, options);
+        const updates: unknown[] = [];
+        instance.on('update', batch => updates.push(batch));
+
+        instance.changeTranslation({ language: 'el', namespace: 'common' }, 'greeting', 'Χαίρετε');
+        jest.advanceTimersByTime?.(0);
+
+        // Batched with cache writes, so it lands on the next tick like a load does.
+        return new Promise<void>(resolve =>
+            setTimeout(() => {
+                expect(updates).toHaveLength(1);
+                resolve();
+            }, 0)
+        );
+    });
+
+    it('assumes the current language and default namespace when not told', () => {
+        const { instance } = build({}, options);
+
+        expect(instance.changeTranslation({}, 'greeting', 'Χαίρετε')).toBe(true);
+        expect(instance.t('greeting')).toBe('Χαίρετε');
+    });
+
+    /** Writing into an unloaded record would invent a namespace no element reads. */
+    it('refuses a record nothing has loaded, and says so', () => {
+        const { instance } = build({}, options);
+
+        expect(instance.changeTranslation({ language: 'de', namespace: 'common' }, 'greeting', 'Hallo')).toBe(false);
+    });
+});
+
+describe('stopping', () => {
+    it('stops loading for namespaces activated afterwards', async () => {
+        const files: Files = { '/langs/common/el.json': {}, '/langs/common/en.json': {}, '/langs/login/el.json': {}, '/langs/login/en.json': {} };
+        const { instance, asked } = build(files);
+        await instance.run();
+        instance.stop();
+        asked.length = 0;
+
+        await instance.addActiveNs('reception');
+
+        expect(asked).toHaveLength(0);
+    });
+
+    it('still answers with what it already has', async () => {
+        const { instance } = build({}, { staticData: { 'el:common': { greeting: 'Γεια' } }, backend: undefined });
+        await instance.run();
+        instance.stop();
+
+        expect(instance.t('greeting')).toBe('Γεια');
+    });
+});