@sveltekit-i18n/base 3.0.1 → 3.1.0-next.1

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { I18n } from './I18n.svelte.js';
 export declare namespace DotNotation {
     type Input = any;
     type Output<V = any, K extends keyof V = keyof V> = {
@@ -48,11 +49,13 @@ export declare namespace Config {
     } ? L : never;
     type LocaleSources<C> = (C extends {
         loaders: readonly {
-            locale: infer L extends string;
+            locale: infer L;
         }[];
-    } ? L : never) | (C extends {
+    } ? LoaderLocales<L> : never) | (C extends {
         translations: infer T;
     } ? keyof T & string : never) | LocaleProp<C, 'initLocale'> | LocaleProp<C, 'fallbackLocale'>;
+    /** A loader's `locale`, spelled as one locale or as several. */
+    type LoaderLocales<L> = L extends readonly (infer M)[] ? M : L;
     type ResolveLocales<L> = L extends string ? L : never;
     /**
      * The locales a config type spells – loader locales, `initLocale`,
@@ -67,11 +70,11 @@ export declare namespace Config {
     export type SanitizeLocales = boolean | ((locale: Locale) => Locale);
     export type T<P extends Parser.Params = Parser.Params, O = Parser.Output, S = any> = {
         /**
-         * You can use loaders to define your asyncronous translation load. All loaded data are stored so loader is triggered only once – in case there is no previous version of the translation. It can get triggered again once the `config.cache` window elapses, or after `invalidate()` is called.
+         * You can use loaders to define your asyncronous translation load. All loaded data are stored so loader is triggered only once – in case there is no previous version of the translation. It can get triggered again when the params its `routes` capture change, once the `config.cache` window elapses, or after `invalidate()` is called. A loader with `cache: false` runs on every load trigger that selects it.
          */
         loaders?: readonly Loader.LoaderModule[];
         /**
-         * Locale-indexed translations, which should be in place before loaders will trigger. It's useful for static pages and synchronous translations – for example locally defined language names which are the same for all of the language mutations.
+         * Locale-indexed translations, in place before any loader runs. They seed the tables: they record nothing, so the loaders of a namespace they name still run and their data merges in. Useful for static pages and synchronous translations – for example locally defined language names which are the same for all of the language mutations. Hand server-rendered data over with `hydrate()` instead.
          *
          * @example {
          *  "en": {"lang": {"en": "English", "cs": "Česky"}}
@@ -80,7 +83,7 @@ export declare namespace Config {
          */
         translations?: Translations.T;
         /**
-         * If you set this property, translations will be initialized immediately using this locale.
+         * If you set this property, translations will be initialized immediately using this locale. `defineI18n()` from `/kit` loads nothing for it: there it is a negotiation candidate. Leave it out of a config whose instance you `hydrate()` by hand – its load starts in the constructor, before the hand-off can be applied.
          */
         initLocale?: InitLocale;
         /**
@@ -133,8 +136,9 @@ export declare namespace Config {
          * `export const schema = {} as TranslationSchema`. A schema whose keys are not a
          * closed set (an open index signature, or no keys at all) is ignored and
          * keys stay plain strings. Read at construction time only: a later
-         * `loadConfig()` cannot retype the instance, and `config.extensions`
-         * erases the instance's type parameters entirely.
+         * `loadConfig()` cannot retype the instance, and an extension typed by a
+         * fixed return type erases the instance's type parameters, while one
+         * typed by an `Extension.Operator` (`Extension.Generic`) keeps them.
          *
          * @example
          * import { schema } from './generated/i18n-schema.js';
@@ -143,11 +147,27 @@ export declare namespace Config {
          */
         schema?: S;
         /**
-         * Time in milliseconds the loaded translations stay fresh for. Once a locale's translations are older, the next load trigger runs its loaders again. By default, loaded translations never expire – call `invalidate()` (or set a finite `cache`) when your translation source can change at runtime, e.g. a CMS.
+         * The path the app is served under – SvelteKit's `kit.paths.base`, spelled
+         * as it appears in `url.pathname`. Every route handed in (`setRoute()`,
+         * `loadTranslations()`) loses it on the way in, on a segment boundary only:
+         * under `/repo`, `/repo/about` is `/about` and `/repo` is `/`, while
+         * `/repository` and a route without it pass through. So loader `routes`,
+         * the `route` a loader receives and the snapshot's route never carry it.
+         *
+         * @example
+         * // .env: PUBLIC_BASE_PATH= (defined even when empty; the build's environment sets it)
+         * // svelte.config.js: kit: { paths: { base: process.env.PUBLIC_BASE_PATH ?? '' } }
+         * import { PUBLIC_BASE_PATH } from '$env/static/public';
+         *
+         * const config = { basePath: PUBLIC_BASE_PATH, loaders };
+         */
+        basePath?: string;
+        /**
+         * Time in milliseconds the loaded translations stay fresh for. Once a locale's translations are older, the next activating load trigger (`setLocale()`, `setRoute()`, `loadTranslations()`) runs its loaders again; a warm load – `loadTranslations(…, { activate: false })` or `loadNamespace()` – fills the tables without evaluating the window. By default, loaded translations never expire – call `invalidate()` (or set a finite `cache`) when your translation source can change at runtime, e.g. a CMS. A loader with `cache: false` is outside the window.
          *
          * @default Number.POSITIVE_INFINITY
          *
-         * @tip Set to `0` to treat translations as always stale (refetch on every load trigger).
+         * @tip Set to `0` to treat translations as always stale (refetch on every activating load trigger).
          */
         cache?: number;
         /**
@@ -231,53 +251,125 @@ export declare namespace Extension {
     } ? Apply<O, Instance> : Head extends T<any, infer Out> ? Out : Instance, Rest> : Instance;
 }
 export declare namespace Loader {
-    type Key = string;
-    type Locale = Config.Locale;
+    export type Key = string;
+    export type Locale = Config.Locale;
     /**
      * Anything with a `test` method can act as a route matcher. It receives the
-     * bare route path (e.g. `/products/123`), so a matcher built around a full
+     * bare route path (e.g. `/products/123`) without `config.basePath`, so a matcher built around a full
      * URL has to be wrapped in a predicate that supplies the origin itself.
      */
-    type RouteMatcher = {
+    export type RouteMatcher = {
         test: (route: string) => boolean;
     };
-    type Route = string | RegExp | RouteMatcher;
+    export type Route = string | RegExp | RouteMatcher;
+    /** The named capture groups a route pattern matched, by name. */
+    export type Params = Record<string, string>;
     /** The load context every loader is called with. */
-    type Props = {
+    export type Props = {
         /**
          * Sanitized locale this loader run fetches translations for.
          */
         locale: Locale;
         /**
-         * Route the load was triggered for.
+         * Namespace this loader run fetches translations for – one call per
+         * namespace, even when the loader names several.
          */
-        route: string;
-    };
-    type LoaderModule = {
+        namespace: Key;
         /**
-         * Represents the translation namespace. This key is used as a translation prefix so it should be module-unique. You can access your translation later using `t('key.yourTranslation')`. It shouldn't include `.` (dot) character.
+         * Route the load was triggered for, without `config.basePath`.
          */
-        key: Key;
+        route: string;
         /**
-         * Locale (e.g. `en`, `de`) which is this loader for.
+         * The named capture groups of the first route pattern in `routes` that
+         * matched `route` – `{}` for a loader without `routes`, for a string route
+         * and for a `RouteMatcher`. A loader runs again when they change.
          */
-        locale: Locale;
+        params: Params;
+    };
+    type LoaderModuleBody = {
         /**
          * Function returning a `Promise` with translation data. You can use it to load files locally, fetch it from your API etc...
+         * It must not await a load of the same instance for the route it was called with: that load can be the one waiting for it, which then never settles.
+         *
+         * Whatever it throws is logged and the rest of the load lands without this loader's data – except SvelteKit's `redirect()` and `error()` below 500,
+         * told by their shape: an integer `status` from 300 to 308 with a string `location`, or from 400 to 499 with an object `body`, each an own property
+         * of a value that is neither an `Error` of this realm nor tagged `'Error'` (a thrown `Response` fails soft).
+         *
+         * Those are logged too, and reject the load with the thrown value once its other loaders have settled. The locale does not advance, and the
+         * rejected call is undone: its requested locale, route and route params go back to what it replaced – as do those of a call whose control flow it
+         * replaced – unless a later call that has not failed came in the meantime. A locale or a route nothing was asked for before stands. The request
+         * put back activates at once when its data is already there – or leaves it to its own activating load still in flight, which activates it or
+         * fails – and is loaded again otherwise, unless it is the request that failed, or this loader threw for it in the load of a call the undo
+         * drops: a failure never runs again by itself. What the other loaders delivered is kept without activating anything; what was
+         * fetched for params the route no longer asks for is kept aside, for the trigger that asks for them.
+         *
+         * An activating load a later call replaced – with another locale, or with other params for this loader, which a route that does not select it
+         * asks for none of – resolves without the control flow.
+         * Nothing replaces a warm load's, unless it shares the load of an activating call, whose outcome it then gets. What a loader throws is discarded,
+         * like its data, when an invalidation, a reconfiguration or `destroy()` severed it before the load settled.
         */
         loader: T;
         /**
-        * Define routes this loader should be triggered for. You can use Regular expressions or any object with a `test` method too. For example `[/\/.ome/]` will be triggered for `/home` and `/rome` route as well (but still only once). Leave this `undefined` in case you want to load this module with any route (useful for common translations).
+        * Define routes this loader should be triggered for. You can use Regular expressions or any object with a `test` method too. For example `[/\/.ome/]` will be triggered for `/home` and `/rome` route as well (but still only once per set of params, unless the loader sets `cache: false`). The routes are matched without `config.basePath`. Leave this `undefined` in case you want to load this module with any route (useful for common translations).
         *
-        * Named capture groups in a route `RegExp` are reserved: today they match exactly as any other group does, but a future minor may read their matches as load parameters and re-run the loader when those change. Use a non-capturing group (`(?:...)`) where you only need grouping.
+        * Named capture groups in a route `RegExp` are load parameters: their matches reach the loader as `Props.params`, and the loader runs again when they change, its data replacing what it delivered for the previous ones. Use a non-capturing group (`(?:...)`) where you only need grouping.
         */
         routes?: readonly Route[];
+        /**
+        * Set to `false` when the loader's source does the caching – a SvelteKit remote `query`, an SWR layer, an HTTP cache. The core then keeps no freshness of its own for it: it runs on every load trigger that selects it, its data is applied each time like any refetch, and `config.cache` does not apply to it – refreshing the source is the app's business. Data hydrated from a snapshot still holds it back for the pass it arrived with, until an activating trigger asks for another locale or route; `invalidate()` ends that hand-off and discards a fetch of it in flight. Only `false` is accepted.
+        */
+        cache?: false;
+    };
+    /**
+     * The namespace a loader loads into, under either name. A union rather than
+     * two optional properties so the compiler keeps what one required property
+     * gave: a loader names exactly one, and naming both is rejected instead of
+     * resolved by a precedence rule.
+     */
+    type Named = {
+        /**
+         * Represents the translation namespace. It is used as a translation prefix so it should be module-unique. You can access your translation later using `t('namespace.yourTranslation')`. It shouldn't include `.` (dot) character.
+         *
+         * Several namespaces may be listed: the loader is then called once per namespace (and per locale), with the one it is loading in `Props.namespace`.
+         */
+        namespace: Key | readonly Key[];
+        key?: never;
+    } | {
+        /**
+         * @deprecated Renamed to `namespace`. Still honored; scheduled for removal in the next major.
+         */
+        key: Key;
+        namespace?: never;
+    };
+    export type LoaderModule = LoaderModuleBody & Named & {
+        /**
+         * Locale (e.g. `en`, `de`) which is this loader for. Several locales may be listed: the loader is then called once per locale (and per namespace), with the one it is loading in `Props.locale`.
+         */
+        locale: Locale | readonly Locale[];
     };
     /**
-     * Loads translation data. Receives the load context (`locale`, `route`) –
+     * A loader module after `resolveLoaders`: one per locale and namespace pair
+     * the module names, with its namespace settled under one name and its locale
+     * sanitized.
+     */
+    export type Resolved = LoaderModuleBody & {
+        locale: Locale;
+        namespace: Key;
+        /**
+         * Names this loader outside the process that resolved it, derived by base
+         * from the loader's locale, namespace and routes – never declared by a
+         * loader. Equal for equal content, across processes. `null` when another
+         * loader resolves to the same content (a `RouteMatcher` contributes its
+         * form, not its behavior), so the name would not tell the two apart.
+         */
+        id: string | null;
+    };
+    /**
+     * Loads translation data. Receives the load context (`locale`, `namespace`, `route`, `params`) –
      * loaders that don't need it can simply take no parameters.
      */
-    type T = (props: Props) => Promise<Translations.Input>;
+    export type T = (props: Props) => Promise<Translations.Input>;
+    export {};
 }
 export declare namespace Parser {
     type Value = any;
@@ -351,7 +443,7 @@ export declare namespace Parser {
      * with anything yields the other kind. `'date'` covers both date and time
      * formatting and means `Date | number`. `'function'` is a rich-text callback,
      * the shape ICU tags require. `'boolean'` is here for parsers that can prove
-     * it – neither official parser can, since both compare stringified values.
+     * it – no official parser can, since each compares stringified values.
      */
     type ParamKind = 'unknown' | 'string' | 'number' | 'boolean' | 'date' | 'function';
     /**
@@ -371,7 +463,7 @@ export declare namespace Parser {
         kind?: ParamKind | readonly ParamKind[];
         /**
          * Values the message names explicitly – a hint for authoring tools, never
-         * an exhaustive set. Both official parsers fall back to a default branch
+         * an exhaustive set. Every official parser falls back to a default branch
          * for anything unlisted, so this must not be used to close a union. Omit it
          * where the listed values are not values at all (numeric thresholds, plural
          * categories) or mean the opposite (an inequality's operands).
@@ -394,7 +486,7 @@ export declare namespace Parser {
             branch: string;
         }[];
     };
-    /** Diagnostic context for an extractor. Neither official parser needs it to extract. */
+    /** Diagnostic context for an extractor. No official parser needs it to extract. */
     type ExtractContext = {
         key?: Key;
         locale?: Locale;
@@ -430,6 +522,17 @@ export declare namespace Schema {
     export type FromConfig<C> = C extends {
         schema?: infer S extends object;
     } ? (HasClosedKeys<S> extends true ? S : never) : never;
+    /**
+     * The key schema an instance was built with; `never` when it carries none.
+     * The counterpart of `FromConfig` for code handed a constructed surface
+     * rather than a config — an extension typing its own output, for instance.
+     *
+     * Read off the class type parameter rather than off the shape of `t`: an
+     * extension that retypes `t` by intersection leaves a structural read
+     * unable to pick the schema out of the intersected signature, while the
+     * instance itself stays a member of that intersection.
+     */
+    export type FromInstance<I> = I extends I18n<any, any, infer S, any> ? S : never;
     /** The keys a schema allows; any string when there is no schema. */
     export type Key<S> = [S] extends [never] ? string : keyof S & string;
     type IsAny<T> = 0 extends 1 & T ? true : false;
@@ -466,6 +569,49 @@ export declare namespace Schema {
     export type Params<S, K extends string, P extends Parser.Params> = [S] extends [never] ? P : [K] extends [keyof S] ? Payload<P, PayloadOf<S, K>, undefined extends S[K & keyof S] ? true : false> : P;
     export {};
 }
+export declare namespace Snapshot {
+    /**
+     * A loader that delivered on the instance a snapshot was taken of: its
+     * `Loader.Resolved.id`, and the signature of the route params it delivered
+     * for – left out when its routes captured none.
+     */
+    type LoadRecord = {
+        id: string;
+        signature?: string;
+    };
+    /**
+     * What `snapshot({ records: true })` returns and `hydrate()` applies. Plain
+     * data throughout – strings, arrays and plain objects – so `devalue`, the
+     * serializer SvelteKit hands load data to, accepts it. Its locales are held
+     * sanitized and are not sanitized again, and `locale` and `route` are applied
+     * as they are, so take it from the server: the whole envelope from
+     * `snapshot({ records: true })`, or for a plain hand-off the data of
+     * `snapshot()` with the server's `i18n.locale`.
+     */
+    type Envelope = {
+        /** What the instance held for its active locale and the fallback locale, shaped like `config.translations`. */
+        translations: Translations.SerializedTranslations;
+        /**
+         * The loaders that delivered, which `hydrate()` keeps from running again
+         * for the same params – one with `cache: false` only for the pass the
+         * envelope arrived with. Without it, the data is handed over as plain data:
+         * it keeps every loader without params of every namespace it names from
+         * running, and holds one with `cache: false` back for that pass.
+         */
+        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.
+         */
+        seeds?: Translations.SerializedTranslations;
+        /** The active locale. */
+        locale?: string;
+        /** The current route, without `config.basePath`. */
+        route?: string;
+    };
+}
 export declare namespace Translations {
     type Locales<T = string> = T[];
     type SerializedTranslations = LocaleIndexed<DotNotation.Input>;

package/dist/utils.d.ts

@@ -14,13 +14,91 @@ type Sanitizer = (...locales: any[]) => Config.Locale[];
 export declare const sanitizeLocales: Sanitizer;
 export declare const sanitizerFactory: (sanitize?: Config.SanitizeLocales) => Sanitizer;
 export declare const sanitizeTranslationLocales: (input: Translations.SerializedTranslations, sanitize: Sanitizer) => Translations.SerializedTranslations;
+/**
+ * Matches what a visitor asked for against the locales an app actually has.
+ *
+ * `requested` is an `Accept-Language` field value, a single locale, or a
+ * preference list such as `navigator.languages`; `available` is the configured
+ * set, and the winner is returned as IT spells it. A miss is `undefined` rather
+ * than a guess – what a miss means is the caller's to decide.
+ */
+export declare const matchLocale: <const L extends string>(requested: string | readonly string[] | null | undefined, available: readonly L[]) => L | undefined;
+/**
+ * The direction `locale` is written in, for `dir` and `<html dir>`.
+ *
+ * Decided by the script alone: the one the tag spells (`az-Arab`, `pa-Guru`),
+ * or else the one `Intl.Locale#maximize()` adds (`dv` is `Thaa`, `pa-PK` is
+ * `Arab`). That likely script is the engine's CLDR data and can differ between
+ * engines (`prs` has none in JavaScriptCore), so a locale whose direction
+ * matters spells its script. The engines' own text info is not read –
+ * JavaScriptCore reports `dv` and `az-Arab` as left to right. A tag
+ * `Intl.Locale` rejects, and a missing locale, is `'ltr'`.
+ */
+export declare const textDirection: (locale: string | undefined) => "ltr" | "rtl";
+/**
+ * `route` without `basePath` in front of it, cut on a segment boundary only:
+ * under `/repo`, `/repo/about` is `/about`, `/repo` is `/` and `/repo?tab=1`
+ * is `/?tab=1`, while `/repository` and a route without the prefix pass
+ * through unchanged.
+ */
+export declare const withoutBasePath: (route: string, basePath: string | undefined) => string;
+/**
+ * What stands in front of the part of `pathname` that SvelteKit's `routeId`
+ * matched: `''` when nothing does, `undefined` when the id fits no suffix of
+ * it, when it is `null` (a 404), or when the pathname is too long to examine.
+ * Param matchers cannot run here, so an optional param on the first segment
+ * absorbs a prefix. No regex runs on the pathname.
+ */
+export declare const routePrefix: (pathname: string, routeId: string | null) => string | undefined;
 export declare const toDotNotation: DotNotation.T;
-export declare const resolveLoaders: (input?: readonly Loader.LoaderModule[]) => Loader.LoaderModule[];
+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 omitProtoKeys: (value: any) => any;
-export declare const serialize: (input: Array<Loader.LoaderModule & {
+export declare const serialize: (input: Array<Loader.Resolved & {
     data: any;
 }>) => Translations.SerializedTranslations;
-export declare const fetchTranslations: (loaders: Loader.LoaderModule[], route: string) => Promise<Translations.SerializedTranslations>;
+/** The locales the loaders serve, then the ones the tables hold. */
+export declare const servedLocales: (loaders: readonly Loader.Resolved[], tables: Translations.SerializedTranslations) => Config.Locale[];
+/**
+ * The locales a config serves, sanitized as an instance built from it
+ * sanitizes them. Resolving the loaders logs what is wrong with them, so a
+ * caller runs this once per config.
+ */
+export declare const configLocales: ({ loaders, translations, sanitizeLocales: strategy }: Pick<Config.T, "loaders" | "translations" | "sanitizeLocales">) => Config.Locale[];
+/** A loader selected for a load, with the params its route yielded. */
+export type LoadRequest = {
+    loader: Loader.Resolved;
+    params: Loader.Params;
+    signature: string;
+};
+/** What a loader delivered. A loader that threw has no entry; one that returned nothing delivered no keys. */
+export type Delivery = {
+    loader: Loader.Resolved;
+    signature: string;
+    data: Translations.Input;
+};
+/** SvelteKit's control flow a loader threw instead of delivering: `redirect()`, and `error()` below 500. */
+export type ControlFlow = {
+    loader: Loader.Resolved;
+    signature: string;
+    value: unknown;
+};
+/** What a fetch returns: the deliveries, and the control flow thrown instead of one. */
+export type Fetched = {
+    deliveries: Delivery[];
+    controlFlow: ControlFlow[];
+};
+/** A loader as a message names it. `String`, since interpolating a Symbol namespace throws. */
+export declare const loaderName: ({ locale, namespace }: Loader.Resolved) => string;
+export declare const fetchTranslation: ({ loader: resolved, params, signature }: LoadRequest, route: string) => Promise<Fetched>;
+/** The fetches of a load as one. */
+export declare const mergeFetched: (fetched: Fetched[]) => Fetched;
+export declare const matchRoute: (route: string) => (input: Loader.Route) => Loader.Params | undefined;
 export declare const testRoute: (route: string) => (input: Loader.Route) => boolean;
+/** The params a loader loads with on `route` – its first matching route's – or `undefined` when none matches. */
+export declare const routeParams: (routes: readonly Loader.Route[] | undefined, route: string) => Loader.Params | undefined;
+/** Whether any of `routes` can yield params. */
+export declare const capturesParams: (routes: readonly Loader.Route[] | undefined) => boolean;
+export declare const paramsSignature: (params: Loader.Params) => string;
 export {};