@sveltekit-i18n/base 3.1.0 → 3.1.2

package/README.md

@@ -122,8 +122,8 @@ export { load } from '$lib/i18n';
 The server picks the visitor's locale from the `Accept-Language` header (or
 from a cookie, with `preferredLocale`), loads it per request and hands it to
 the browser, so nothing loads twice and no visitor sees another's locale. See
-[SvelteKit](./docs/README.md#sveltekit) for the details and
-[Server-Side Rendering](./docs/README.md#server-side-rendering) for wiring it
+[SvelteKit](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#sveltekit) for the details and
+[Server-Side Rendering](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#server-side-rendering) for wiring it
 by hand.
 
 ### 4. Use in components
@@ -232,11 +232,11 @@ A named capture group in a `RegExp` route is a load parameter: its match reaches
 }
 ```
 
-`API_ORIGIN` stands for an origin such as `https://api.example.com`: a loader runs on the server too, where `fetch` takes only an absolute URL. See [route params](./docs/README.md#route-params) for the rules.
+`API_ORIGIN` stands for an origin such as `https://api.example.com`: a loader runs on the server too, where `fetch` takes only an absolute URL. See [route params](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#route-params) for the rules.
 
-A loader whose source does the caching itself — a SvelteKit remote `query`, an SWR layer, an HTTP cache — sets `cache: false`. It then runs on every load trigger that selects it, and `config.cache` does not apply to it; only a hydrated snapshot holds it back, for the locale and route it was rendered for. See [the loader's `cache`](./docs/README.md#cache-optional).
+A loader whose source does the caching itself — a SvelteKit remote `query`, an SWR layer, an HTTP cache — sets `cache: false`. It then runs on every load trigger that selects it, and `config.cache` does not apply to it; only a hydrated snapshot holds it back, for the locale and route it was rendered for. See [the loader's `cache`](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#cache-optional).
 
-A loader that throws is logged, and the rest of the load lands without its data; it runs again on the next load trigger. SvelteKit's `redirect()` and an `error()` below 500 (told by their shape: an own `status` with a `location` or a `body`, on a value that is not an `Error`) are logged too, but they also reject the load, so a SvelteKit `load` awaiting the call hands them to SvelteKit; the rejected call is undone — what it replaced goes back — unless a later call that has not failed came in the meantime. See [the loader](./docs/README.md#loader-required).
+A loader that throws is logged, and the rest of the load lands without its data; it runs again on the next load trigger. SvelteKit's `redirect()` and an `error()` below 500 (told by their shape: an own `status` with a `location` or a `body`, on a value that is not an `Error`) are logged too, but they also reject the load, so a SvelteKit `load` awaiting the call hands them to SvelteKit; the rejected call is undone — what it replaced goes back — unless a later call that has not failed came in the meantime. See [the loader](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#loader-required).
 
 Both `loaders` and a loader's `routes` accept readonly arrays, so a whole-config `as const` is fine.
 
@@ -251,11 +251,11 @@ import { PUBLIC_BASE_PATH } from '$env/static/public';
 basePath: PUBLIC_BASE_PATH
 ```
 
-See [`basePath`](./docs/README.md#basepath).
+See [`basePath`](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#basepath).
 
 ### `translations`
 
-Synchronous translations, available immediately. They seed the tables: the loaders of a namespace they name still run and merge into it. Hand a server's state over with [`hydrate()`](./docs/README.md#hydrateenvelope) instead:
+Synchronous translations, available immediately. They seed the tables: the loaders of a namespace they name still run and merge into it. Hand a server's state over with [`hydrate()`](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#hydrateenvelope) instead:
 
 ```javascript
 translations: {
@@ -273,7 +273,7 @@ Initialize with a specific locale immediately:
 initLocale: 'en'
 ```
 
-With [`defineI18n()`](#sveltekit) it loads nothing: it is a negotiation candidate. Leave it out of a config whose instance you [`hydrate()`](./docs/README.md#hydrateenvelope) by hand — its load starts in the constructor, before the hand-off can be applied.
+With [`defineI18n()`](#sveltekit) it loads nothing: it is a negotiation candidate. Leave it out of a config whose instance you [`hydrate()`](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#hydrateenvelope) by hand — its load starts in the constructor, before the hand-off can be applied.
 
 ### `fallbackLocale`
 
@@ -295,7 +295,7 @@ fallbackValue: '...' // Default: returns the key itself
 
 ### `sanitizeLocales`
 
-How locale identifiers are normalized before they key anything: `true` (default) resolves them to their ISO form through `Intl` (`'en-us'` is `'en-US'`), `false` keeps them as authored, and a function normalizes them your way. See [`sanitizeLocales`](./docs/README.md#sanitizelocales).
+How locale identifiers are normalized before they key anything: `true` (default) resolves them to their ISO form through `Intl` (`'en-us'` is `'en-US'`), `false` keeps them as authored, and a function normalizes them your way. See [`sanitizeLocales`](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#sanitizelocales).
 
 ### `preprocess`
 
@@ -334,11 +334,11 @@ Or state it per instance — only its type is read, so the value can stay empty
 const i18n = new I18n({ ...config, schema: {} as TranslationSchema });
 ```
 
-Hand-write it for a small set of messages, or generate it — [@sveltekit-i18n/typegen](https://github.com/sveltekit-i18n/typegen), a separate package, generates one. A schema whose keys are not a closed set (`schema: {}`) types nothing and keeps the registry out, so keys stay plain strings. A library never registers. The registry needs base 3.1 or newer. See [`schema`](./docs/README.md#schema) for the full rules.
+Hand-write it for a small set of messages, or generate it — [@sveltekit-i18n/typegen](https://github.com/sveltekit-i18n/typegen), a separate package, generates one. A schema whose keys are not a closed set (`schema: {}`) types nothing and keeps the registry out, so keys stay plain strings. A library never registers. The registry needs base 3.1 or newer. See [`schema`](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#schema) for the full rules.
 
 ### `cache`
 
-Time in milliseconds the loaded translations stay fresh for. By default, loaded translations never expire — each loader (but one with [`cache: false`](./docs/README.md#cache-optional)) runs once per locale and [route params](./docs/README.md#route-params) (a loader's `routes` decide whether a load trigger considers it, and the params their named groups capture decide when it runs again).
+Time in milliseconds the loaded translations stay fresh for. By default, loaded translations never expire — each loader (but one with [`cache: false`](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#cache-optional)) runs once per locale and [route params](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#route-params) (a loader's `routes` decide whether a load trigger considers it, and the params their named groups capture decide when it runs again).
 
 Set a finite value when your loaders fetch from a source that can change at runtime (e.g. a CMS):
 
@@ -399,7 +399,7 @@ log: {
 - `locales` – available locales
 - `loading` – `true` while any activating load is in flight; a `{ activate: false }` load counts only once an activating trigger joins it
 - `initialized` – locale and route set, translations present
-- `translations` / `rawTranslations` – the (pre/post-preprocess) tables
+- `translations` / `rawTranslations` – the tables after and before preprocessing
 
 ### Methods
 
@@ -443,12 +443,12 @@ export const { handle, load, use, get } = defineI18n(config, { preferredLocale }
 - `use(() => data)` – called once in the root `+layout.svelte`; provides the instance, follows every navigation and keeps `<html lang>` and `<html dir>` in sync
 - `get()` – the instance, in any component below the root layout
 
-Full API documentation: [docs/README.md](./docs/README.md)
+Full API documentation: [docs/README.md](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md)
 
 ## Documentation
 
 - 🌐 [sveltekit-i18n.github.io](https://sveltekit-i18n.github.io) – The documentation site, with a live playground
-- 📖 [Full API Documentation](./docs/README.md) – Complete reference
+- 📖 [Full API Documentation](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md) – Complete reference
 - 📚 [Main Library Docs](https://github.com/sveltekit-i18n/lib/tree/master/docs/INDEX.md) – Guides, tutorials, and best practices
 - 🎨 [Parsers](https://github.com/sveltekit-i18n/parsers) – Available parsers and how to create your own
 - 💡 [Examples](https://github.com/sveltekit-i18n/lib/tree/master/examples) – Real-world usage examples
@@ -479,7 +479,7 @@ i18n.setLocale('en'); // 'en' | 'de' autocomplete here
 i18n.setLocale('sv'); // still accepted — the union is a hint, not a constraint
 ```
 
-The locales survive only when the config reaches the constructor as a literal — inline, as above, or a separate object with `as const`. An annotated or separately widened config, and any config with one dynamic locale source (`loaders: locales.map(...)`), leaves them plain `string`. See [TypeScript](./docs/README.md#typescript) for both.
+The locales survive only when the config reaches the constructor as a literal — inline, as above, or a separate object with `as const`. An annotated or separately widened config, and any config with one dynamic locale source (`loaders: locales.map(...)`), leaves them plain `string`. See [TypeScript](https://github.com/sveltekit-i18n/base/blob/3.1.2/docs/README.md#typescript) for both.
 
 ## Related Packages
 

package/dist/I18n.svelte.d.ts

@@ -113,9 +113,10 @@ declare class I18nCore<ParserParams extends Parser.Params = any, ParserOutput =
      * records name each loader, so a namespace fed by several loaders is handed
      * over too, and so is one a loader delivered for route params while its
      * record says so — not a namespace with both, whose data the client could
-     * not split between them. What was seeded into the namespace of a loader
-     * whose routes capture params travels apart as `seeds`, so it outlives new
-     * params there, and reaches the client where the namespace is left out.
+     * not split between them. What was seeded into the namespace of a recorded
+     * loader, or of one whose routes capture params, travels apart as `seeds`,
+     * so it outlives the loader's next fetch there, and reaches the client
+     * where the namespace is left out.
      */
     snapshot: {
         (options?: {

package/dist/I18n.svelte.js

@@ -1,5 +1,5 @@
 import { untrack } from 'svelte';
-import { capturesParams, fetchTranslation, hasOwn, loaderName, mergeFetched, mergeTranslations, omitProtoKeys, paramsSignature, read, resolveLoaders, routeParams, sanitizerFactory, sanitizeTranslationLocales, serialize, servedLocales, toDotNotation, translate, unique, withoutBasePath } from './utils.js';
+import { capturesParams, fetchTranslation, hasOwn, loaderName, maskOutputKeys, maskTranslations, mergeFetched, mergeTranslations, omitProtoKeys, paramsSignature, read, resolveLoaders, routeParams, sanitizerFactory, sanitizeTranslationLocales, serialize, servedLocales, toDotNotation, translate, unique, withoutBasePath } from './utils.js';
 import { logError, logger, loggerFactory, setLogger } from './logger.js';
 const defaultCache = Number.POSITIVE_INFINITY;
 /**
@@ -413,9 +413,10 @@ class I18nCore {
      * records name each loader, so a namespace fed by several loaders is handed
      * over too, and so is one a loader delivered for route params while its
      * record says so — not a namespace with both, whose data the client could
-     * not split between them. What was seeded into the namespace of a loader
-     * whose routes capture params travels apart as `seeds`, so it outlives new
-     * params there, and reaches the client where the namespace is left out.
+     * not split between them. What was seeded into the namespace of a recorded
+     * loader, or of one whose routes capture params, travels apart as `seeds`,
+     * so it outlives the loader's next fetch there, and reaches the client
+     * where the namespace is left out.
      */
     snapshot = ((options) => {
         const withRecords = options?.records === true;
@@ -472,11 +473,12 @@ class I18nCore {
                 return [];
             return [signature ? { id, signature } : { id }];
         });
-        // Where params can change, the client takes a recorded namespace whole as
-        // its loader's delivery and loads one left out itself, so what was seeded
-        // into it travels apart: the seed has to outlive the delivery new params
-        // replace there as it does here.
-        const seeds = omitProtoKeys(this.#externalOf(loaders.filter(({ locale, routes }) => omitted.has(locale) && locale !== '__proto__' && capturesParams(routes))));
+        // The client takes a recorded namespace whole as its loader's delivery,
+        // and loads one left out where params can change itself, so what was
+        // seeded into either travels apart: the seed has to outlive the delivery
+        // the next fetch replaces there as it does here.
+        const recorded = new Set(records.map(({ id }) => id));
+        const seeds = omitProtoKeys(this.#externalOf(loaders.filter(({ id, locale, routes }) => omitted.has(locale) && locale !== '__proto__' && (capturesParams(routes) || (id !== null && recorded.has(id))))));
         return {
             translations,
             records,
@@ -585,34 +587,40 @@ class I18nCore {
         });
         const takers = new Map([...byIdTaken, ...byFunction]);
         const orphaned = deliveries.filter((delivery) => !takers.has(delivery));
-        this.#deliveries = new Map(Array.from(takers, ([delivery, taker]) => [taker, { ...delivery, loader: taker }]));
+        this.#deliveries = new Map(deliveries.flatMap((delivery) => {
+            const taker = takers.get(delivery);
+            return taker ? [[taker, { ...delivery, loader: taker }]] : [];
+        }));
         this.#keepExternal(serialize(orphaned.map(({ loader, data }) => ({ ...loader, data }))));
     }
     /**
-     * Applies what loaders delivered and records them as loaded. A loader whose
-     * params changed replaces the part of its namespace it delivered before:
-     * the namespace is rebuilt from the data supplied without a loader and from
-     * what each of its loaders last delivered, so no key of the previous params
-     * survives and a sibling's part stays in place. The preprocessed table of a
+     * Applies what loaders delivered and records them as loaded. A loader that
+     * delivered before, for the same params or for others, replaces the part of
+     * its namespace it delivered then: the namespace is rebuilt from the data
+     * supplied without a loader and from what each of its loaders last
+     * delivered, so no key its source dropped survives and a sibling's part
+     * stays in place. The preprocessed table of a
      * locale that lost data is derived again from the raw one, since a custom
      * `preprocess` may have renamed the keys that would have to go. Both tables
      * are computed before anything is written, so a `preprocess` that throws
      * records no loader and the next trigger fetches it again.
      */
-    #applyDeliveries(deliveries) {
+    #applyDeliveries(applied) {
+        const { loaders = [] } = this.#config ?? {};
+        // One load, however its deliveries were gathered: a preload claimed with
+        // it comes first, yet the loader declared later still wins.
+        const deliveries = [...applied].sort((a, b) => loaders.indexOf(a.loader) - loaders.indexOf(b.loader));
         const replaced = deliveries
-            .filter(({ loader, signature }) => {
-            const previous = this.#deliveries.get(loader);
-            return previous !== undefined && previous.signature !== signature;
-        })
+            .filter(({ loader }) => this.#deliveries.has(loader))
             .map(({ loader }) => loader);
-        const delivered = new Map(deliveries.map((delivery) => [delivery.loader, delivery]));
+        const delivered = new Set(deliveries.map(({ loader }) => loader));
         const isReplaced = ({ locale, namespace }) => replaced.some((loader) => loader.locale === locale && loader.namespace === namespace);
-        const { loaders = [] } = this.#config ?? {};
-        const rebuilt = loaders
-            .filter(isReplaced)
-            .map((loader) => delivered.get(loader) ?? this.#deliveries.get(loader))
-            .filter((delivery) => delivery !== undefined);
+        // In the order they were delivered, so across loads the data delivered
+        // last wins, as it does where nothing is rebuilt.
+        const rebuilt = [
+            ...Array.from(this.#deliveries.values()).filter(({ loader }) => isReplaced(loader) && !delivered.has(loader)),
+            ...deliveries.filter(({ loader }) => isReplaced(loader)),
+        ];
         const raw = replaced.reduce((acc, { locale, namespace }) => ({
             ...acc,
             [locale]: Object.fromEntries(Object.entries(read(acc, locale) ?? {}).filter(([key]) => !isNamespaceKey(key, namespace))),
@@ -642,6 +650,23 @@ class I18nCore {
     #addSanitized(sanitized) {
         this.#mergeTranslations(sanitized);
         this.#keepExternal(sanitized);
+        const { preprocess } = this.#config ?? {};
+        // Seeded over what a loader delivered before, so a rebuild of the
+        // namespace, which lays the seeds under every delivery, keeps it on top
+        // until that loader delivers again.
+        this.#deliveries.forEach((delivery, loader) => {
+            const own = Object.entries(read(sanitized, loader.locale) ?? {}).filter(([key]) => isNamespaceKey(key, loader.namespace));
+            if (!own.length)
+                return;
+            const nested = read(read(sanitized, loader.locale), loader.namespace);
+            const masked = nested === undefined ? delivery.data : maskTranslations(delivery.data, nested) ?? {};
+            // Dot notation, as `#preprocess` applies it, merges both spellings of a
+            // key into one.
+            const dotted = typeof preprocess !== 'function' && preprocess !== 'none'
+                ? maskOutputKeys(masked, new Set(Object.keys(toDotNotation(Object.fromEntries(own), preprocess === 'preserveArrays') ?? {})), loader.namespace, preprocess === 'preserveArrays') ?? {}
+                : masked;
+            this.#deliveries.set(loader, { ...delivery, data: dotted });
+        });
     }
     /**
      * Applies plain hand-off data. It records every namespace the data names,
@@ -672,7 +697,7 @@ class I18nCore {
      * that change later replace it; the rest is kept as data supplied without a
      * loader and, like a seed, records no namespace — the hand-off says which loaders it
      * covers, and anything else loads again rather than going missing. `seeds`
-     * is what was seeded where params can change, displayed and kept as a seed
+     * is what was seeded into those namespaces, displayed and kept as a seed
      * so that it outlives a delivery. A record naming no loader of this config
      * is dropped, and its loader runs again.
      */
@@ -705,6 +730,8 @@ class I18nCore {
     }
     /** Records `delivery` as its loader's; what was parked for its params is older. */
     #record(delivery) {
+        // Deleted first, so the map keeps the order the deliveries arrived in.
+        this.#deliveries.delete(delivery.loader);
         this.#deliveries.set(delivery.loader, delivery);
         this.#loaderRecords.set(delivery.loader, delivery.signature);
         if (this.#parked.get(delivery.loader)?.signature === delivery.signature)

package/dist/types.d.ts

@@ -628,10 +628,11 @@ export declare namespace Snapshot {
          */
         records?: LoadRecord[];
         /**
-         * What was seeded into the namespace of a loader whose routes capture
-         * params – repeated where `translations` carries the namespace, and
-         * carried where the payload leaves it out, so that it outlives the
-         * delivery new params replace. Read with `records` only.
+         * What was seeded into the namespace of a recorded loader or of one whose
+         * routes capture params – repeated where `translations` carries the
+         * namespace, and carried where the payload leaves it out, so that it
+         * outlives the delivery the loader's next fetch replaces. Read with
+         * `records` only.
          */
         seeds?: Translations.SerializedTranslations;
         /** The active locale. */
@@ -645,9 +646,11 @@ export declare namespace Translations {
     type SerializedTranslations = LocaleIndexed<DotNotation.Input>;
     /**
      * What `t`/`l` yield. The parser's output on the paths that reach the parser,
-     * and a plain string on the ones that cannot: an empty key, no locale, or a
-     * config carrying no parser. `O` is `string` for every parser that returns
-     * one, which collapses the union everywhere it is not needed.
+     * and a plain string on the misses: `''` for an empty key or no locale, the
+     * key itself for a missing translation. Two paths hand back data unchecked:
+     * a configured `fallbackValue`, and the stored value while the config
+     * carries no parser. `O` is `string` for every parser that returns one,
+     * which collapses the union everywhere it is not needed.
      */
     type Translated<O> = O | string;
     type TranslationFunction<P extends Parser.Params = Parser.Params, O = string, S = never> = <K extends Schema.Key<S>>(key: K, ...restParams: Schema.Params<S, K, P>) => Translated<O>;

package/dist/utils.d.ts

@@ -54,6 +54,8 @@ export declare const toDotNotation: DotNotation.T;
 export declare const unique: <V>(values: readonly V[]) => V[];
 export declare const resolveLoaders: (input?: readonly Loader.LoaderModule[], sanitizeLocales?: Config.SanitizeLocales) => Loader.Resolved[];
 export declare const mergeTranslations: (target: any, source: any, path: string, onConflict?: (path: string) => void) => any;
+export declare const maskTranslations: (target: any, source: any) => any;
+export declare const maskOutputKeys: (target: any, keys: ReadonlySet<string>, prefix: string, preserveArrays?: boolean) => any;
 export declare const omitProtoKeys: (value: any) => any;
 export declare const serialize: (input: Array<Loader.Resolved & {
     data: any;

package/dist/utils.js

@@ -492,6 +492,42 @@ export const mergeTranslations = (target, source, path, onConflict) => {
         [key]: hasOwn(acc, key) ? mergeTranslations(read(acc, key), read(source, key), `${path}.${key}`, onConflict) : read(source, key),
     }), target);
 };
+// What of `target` still shows once `source` is merged over it: the branches
+// both hold as objects keep what `source` leaves out, and anything else it
+// sets is gone. `undefined` when `source` replaces the whole of `target`.
+export const maskTranslations = (target, source) => {
+    if (!isMergeable(target) || !isMergeable(source))
+        return undefined;
+    return Object.keys(target).reduce((acc, key) => {
+        if (!hasOwn(source, key))
+            return { ...acc, [key]: read(target, key) };
+        const masked = maskTranslations(read(target, key), read(source, key));
+        return masked === undefined ? acc : { ...acc, [key]: masked };
+    }, {});
+};
+// What of `target`, dot-notated under `prefix`, still shows once `keys` are
+// dot-notated beside it: a leaf whose key is among them is gone. A key spelled
+// with dots and a nested branch meet only there, after `preprocess`. Unless
+// `preserveArrays`, an array is walked as `toDotNotation` walks it, and one
+// that lost an item keeps the others under their indexes. What lost nothing is
+// returned as it is, and an array that lost no item and holds nothing but its
+// items stays one.
+export const maskOutputKeys = (target, keys, prefix, preserveArrays = false) => {
+    const walked = Array.isArray(target) ? !preserveArrays : isMergeable(target);
+    if (!walked)
+        return keys.has(prefix) ? undefined : target;
+    const entries = Object.keys(target).flatMap((key) => {
+        const masked = maskOutputKeys(read(target, key), keys, `${prefix}.${key}`, preserveArrays);
+        return masked === undefined ? [] : [[key, masked]];
+    });
+    if (entries.length === Object.keys(target).length) {
+        if (entries.every(([key, value]) => Object.is(value, read(target, key))))
+            return target;
+        if (Array.isArray(target) && entries.every(([key], index) => key === `${index}`))
+            return entries.map(([, value]) => value);
+    }
+    return entries.reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {});
+};
 const isPlainObject = (value) => {
     if (!value || typeof value !== 'object')
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltekit-i18n/base",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Base functionality of sveltekit-i18n library with a support for external message parsers.",
   "type": "module",
   "types": "./dist/index.d.ts",