lambder 14.1.1 → 15.0.2

package/dist/session/LambderSessionManager.d.ts

@@ -171,9 +171,15 @@ export default class LambderSessionManager<SessionData = any> {
      */
     private hashToken;
     createSession(sessionKey: string, data?: SessionData, ttlInSeconds?: number, options?: {
-        /** The data refresh deadline to start with (regenerateSession starts its data due). */
+        /** The data refresh deadline to start with, in epoch seconds. Default: dataRefresh.ttlSeconds from now. */
         dataExpiresAt?: number;
     }): Promise<LambderCreatedSession<SessionData>>;
+    /**
+     * Writes a new record holding `data` under fresh tokens, and hands it
+     * back with `served` as its data: the schema's reading of what the record
+     * holds, which createSession has checked and a rotation carries over.
+     */
+    private mintSession;
     /**
      * Writes new session data onto the record, and nothing else: the expiry
      * slides only in renewSession, which also re-issues the cookies, so a
@@ -216,8 +222,16 @@ export default class LambderSessionManager<SessionData = any> {
      * when the session is over: a refresh said so (a deleted or disabled
      * login), or the record was deleted while this request read it (a
      * logout, a password change), which a renewal must not undo.
+     *
+     * `refreshData: true` renews the data on this read whatever its
+     * deadline, for a read that wants it fresh (a page load): the callback
+     * runs once and its result shares the read's one write, where a read
+     * followed by refreshSessionData would run both twice whenever the data
+     * was due. Requires dataRefresh, and throws without it.
      */
-    renewSession(session: LambderSessionRecord<SessionData>): Promise<LambderSessionRecord<SessionData> | null>;
+    renewSession(session: LambderSessionRecord<SessionData>, options?: {
+        refreshData?: boolean;
+    }): Promise<LambderSessionRecord<SessionData> | null>;
     /**
      * Data about to be stored, held to the schema: what a read of it will
      * serve, or the error `refused` builds from where it does not match.
@@ -297,7 +311,7 @@ export default class LambderSessionManager<SessionData = any> {
      * than landing data derived before the change. Requires dataRefresh to
      * be configured.
      */
-    expireSessionDataAllByKey(sessionKey: string): Promise<boolean>;
+    expireSessionDataAllByKey(sessionKey: string): Promise<void>;
     /**
      * Replaces the session with a new one under new tokens, carrying over
      * the data as the delete removed it rather than as this request read
@@ -319,6 +333,22 @@ export default class LambderSessionManager<SessionData = any> {
      * marked by expireSessionDataAllByKey while the new record was being
      * written may have passed it by, and due, its next read renews the data
      * from the source of truth either way.
+     *
+     * The record is read first, because what the request holds is the
+     * schema's reading of the data, which a schema that strips keys or
+     * transforms is not the data the record holds. The new record holds the
+     * stored data, every comparison is between stored data, and the request
+     * is handed the schema's reading of what the new record holds, as a read
+     * would hand it.
      */
     regenerateSession(session: LambderSessionRecord<SessionData>): Promise<LambderCreatedSession<SessionData> | null>;
+    /**
+     * Data a rotation carries over, as the request is handed it: the
+     * schema's reading of it. It is the record's own data rather than the
+     * app's, so it is not refused as a write would be. Where the schema
+     * refuses it, the request keeps the data it already held, and the new
+     * record's next read meets it as every read meets such data: refreshed
+     * with dataRefresh (the new record starts due), ended without.
+     */
+    private carriedDataOf;
 }

package/dist/session/LambderSessionManager.js

@@ -185,6 +185,14 @@ export default class LambderSessionManager {
         // Refused for the same reason: data the schema refuses would end the
         // session on its first read, a sign-out right after the sign-in.
         const served = this.servedDataOf(data, (issues) => new Error(`Lambder: createSession was given data that does not match session.dataSchema (${issues}).`));
+        return await this.mintSession(sessionKey, data, served, ttlInSeconds, options?.dataExpiresAt);
+    }
+    /**
+     * Writes a new record holding `data` under fresh tokens, and hands it
+     * back with `served` as its data: the schema's reading of what the record
+     * holds, which createSession has checked and a rotation carries over.
+     */
+    async mintSession(sessionKey, data, served, ttlInSeconds, dataExpiresAt) {
         const sessionKeyHash = await this.sessionKeyHashOf(sessionKey);
         // The sort-key SECRET goes to the client; only its hash becomes the
         // store's range key, so the store never contains a usable token.
@@ -200,7 +208,7 @@ export default class LambderSessionManager {
             csrfTokenHash: await this.hashToken(csrfToken),
             sessionKey, data,
             createdAt, lastAccessedAt, expiresAt, ttlInSeconds,
-            ...(this.dataRefresh ? { dataExpiresAt: options?.dataExpiresAt ?? (createdAt + this.dataRefresh.ttlSeconds) } : {}),
+            ...(this.dataRefresh ? { dataExpiresAt: dataExpiresAt ?? (createdAt + this.dataRefresh.ttlSeconds) } : {}),
             dataVersion: 0,
         };
         await this.store.create(session);
@@ -320,8 +328,16 @@ export default class LambderSessionManager {
      * when the session is over: a refresh said so (a deleted or disabled
      * login), or the record was deleted while this request read it (a
      * logout, a password change), which a renewal must not undo.
+     *
+     * `refreshData: true` renews the data on this read whatever its
+     * deadline, for a read that wants it fresh (a page load): the callback
+     * runs once and its result shares the read's one write, where a read
+     * followed by refreshSessionData would run both twice whenever the data
+     * was due. Requires dataRefresh, and throws without it.
      */
-    async renewSession(session) {
+    async renewSession(session, options = {}) {
+        if (options.refreshData && !this.dataRefresh)
+            throw new Error("dataRefresh is not configured. Pass session.dataRefresh at creation to enable.");
         const now = Math.floor(Date.now() / 1000);
         const refreshed = {};
         const slid = {};
@@ -337,10 +353,10 @@ export default class LambderSessionManager {
         // once a refresh ran, the refresh's.
         let served = read?.success ? read.data : session.data;
         // Renew session.data once its shelf life has passed (opt-in
-        // dataRefresh), or at once when it does not match the schema. A
-        // record created while dataRefresh was off has no dataExpiresAt, so
-        // it renews on its first read.
-        if (this.dataRefresh && (read?.success === false || (session.dataExpiresAt ?? 0) <= now)) {
+        // dataRefresh), at once when it does not match the schema, or when
+        // the read asks for it. A record created while dataRefresh was off
+        // has no dataExpiresAt, so it renews on its first read.
+        if (this.dataRefresh && (options.refreshData === true || read?.success === false || (session.dataExpiresAt ?? 0) <= now)) {
             let newData;
             try {
                 newData = await this.dataRefresh.refresh(session);
@@ -573,7 +589,6 @@ export default class LambderSessionManager {
         const now = Math.floor(Date.now() / 1000);
         // An update, so a session deleted in between stays deleted.
         await this.forEachSessionOf(sessionKeyHash, (secretHash) => this.store.update(sessionKeyHash, secretHash, { dataExpiresAt: now }));
-        return true;
     }
     ;
     /**
@@ -597,29 +612,53 @@ export default class LambderSessionManager {
      * marked by expireSessionDataAllByKey while the new record was being
      * written may have passed it by, and due, its next read renews the data
      * from the source of truth either way.
+     *
+     * The record is read first, because what the request holds is the
+     * schema's reading of the data, which a schema that strips keys or
+     * transforms is not the data the record holds. The new record holds the
+     * stored data, every comparison is between stored data, and the request
+     * is handed the schema's reading of what the new record holds, as a read
+     * would hand it.
      */
     async regenerateSession(session) {
         if (!session)
             throw new Error("Invalid session");
         const now = Math.floor(Date.now() / 1000);
-        const created = await this.createSession(session.sessionKey, session.data, session.ttlInSeconds, this.dataRefresh ? { dataExpiresAt: now } : undefined);
+        const stored = await this.store.get(session.sessionKeyHash, session.secretHash);
+        if (!stored || stored.expiresAt <= now)
+            return null;
+        const created = await this.mintSession(session.sessionKey, stored.data, this.carriedDataOf(stored.data, session), session.ttlInSeconds, this.dataRefresh ? now : undefined);
         const replacement = created.session;
         const removed = await this.store.delete(session.sessionKeyHash, session.secretHash);
         if (!removed || removed.expiresAt <= now) {
             await this.store.delete(replacement.sessionKeyHash, replacement.secretHash);
             return null;
         }
-        if (canonicalJson(removed.data) === canonicalJson(session.data))
+        if (canonicalJson(removed.data) === canonicalJson(stored.data))
             return created;
-        // Another request wrote the data after this one read it. The write
-        // moves the replacement's dataVersion one past the one it was created
-        // with, and the record handed back says so: a data write later in
-        // this request names the version the store holds rather than answer
-        // stale. A mark landing in between still makes it stale, the safe
-        // side (see updateSessionData).
+        // Another request wrote the data between this read and the delete.
+        // The write moves the replacement's dataVersion one past the one it
+        // was created with, and the record handed back says so: a data write
+        // later in this request names the version the store holds rather
+        // than answer stale. A mark landing in between still makes it stale,
+        // the safe side (see updateSessionData).
         if (await this.store.update(replacement.sessionKeyHash, replacement.secretHash, { data: removed.data }) === "missing")
             return null;
-        return { ...created, session: { ...replacement, data: removed.data, dataVersion: replacement.dataVersion + 1 } };
+        return { ...created, session: { ...replacement, data: this.carriedDataOf(removed.data, session), dataVersion: replacement.dataVersion + 1 } };
+    }
+    /**
+     * Data a rotation carries over, as the request is handed it: the
+     * schema's reading of it. It is the record's own data rather than the
+     * app's, so it is not refused as a write would be. Where the schema
+     * refuses it, the request keeps the data it already held, and the new
+     * record's next read meets it as every read meets such data: refreshed
+     * with dataRefresh (the new record starts due), ended without.
+     */
+    carriedDataOf(data, session) {
+        if (!this.dataSchema)
+            return data;
+        const read = this.dataSchema.safeParse(data);
+        return read.success ? read.data : session.data;
     }
 }
 ;

package/dist/shared/LambderHtml.d.ts

@@ -65,8 +65,27 @@ export declare const xml: (strings: TemplateStringsArray, ...values: LambderHtml
 /** Mark a trusted string as safe (inserted without escaping). Never pass user input. */
 export declare const raw: (value: string) => LambderSafeHtml;
 /**
- * Server-preloaded state as <script type="application/json" id="..."> so an SPA
- * can hydrate without a first fetch. Escaped so the payload can't break out of
- * the script element. Read with JSON.parse(document.getElementById(id).textContent).
+ * Where jsonScript writes its data, and the id it carries. A data block
+ * (`application/json`, the default) is found by its id, so it needs one;
+ * JSON-LD (`application/ld+json`) is read by whatever crawls the page, so its
+ * id is optional.
  */
-export declare const jsonScript: (id: string, data: unknown) => LambderSafeHtml;
+export type LambderJsonScriptOptions = {
+    type?: "application/json";
+    id: string;
+} | {
+    type: "application/ld+json";
+    id?: string;
+};
+/**
+ * JSON in a <script> element, escaped so the payload cannot break out of it:
+ * every `<` is written `\u003c` (so no `</script>` or `<!--` can appear), and
+ * U+2028 and U+2029 as escapes too, which JSON.parse reads back unchanged.
+ *
+ * `jsonScript(id, data)` is server-preloaded state as
+ * <script type="application/json" id="...">, so an SPA can hydrate without a
+ * first fetch; read it with JSON.parse(document.getElementById(id).textContent).
+ * `jsonScript({ type: "application/ld+json" }, data)` is structured data for
+ * search engines, with the same escaping.
+ */
+export declare const jsonScript: (target: string | LambderJsonScriptOptions, data: unknown) => LambderSafeHtml;

package/dist/shared/LambderHtml.js

@@ -169,14 +169,26 @@ export const xml = html;
 /** Mark a trusted string as safe (inserted without escaping). Never pass user input. */
 export const raw = (value) => new LambderSafeHtml(value);
 /**
- * Server-preloaded state as <script type="application/json" id="..."> so an SPA
- * can hydrate without a first fetch. Escaped so the payload can't break out of
- * the script element. Read with JSON.parse(document.getElementById(id).textContent).
+ * JSON in a <script> element, escaped so the payload cannot break out of it:
+ * every `<` is written `\u003c` (so no `</script>` or `<!--` can appear), and
+ * U+2028 and U+2029 as escapes too, which JSON.parse reads back unchanged.
+ *
+ * `jsonScript(id, data)` is server-preloaded state as
+ * <script type="application/json" id="...">, so an SPA can hydrate without a
+ * first fetch; read it with JSON.parse(document.getElementById(id).textContent).
+ * `jsonScript({ type: "application/ld+json" }, data)` is structured data for
+ * search engines, with the same escaping.
  */
-export const jsonScript = (id, data) => {
+export const jsonScript = (target, data) => {
+    const { type = "application/json", id } = typeof target === "string" ? { id: target } : target;
+    // The type is written into the markup as it is, so only the two it may be get there.
+    if (type !== "application/json" && type !== "application/ld+json") {
+        throw new Error(`jsonScript: type must be "application/json" or "application/ld+json", got ${JSON.stringify(type)}.`);
+    }
     const json = JSON.stringify(data)
         .replace(/</g, "\\u003c")
         .replace(/\u2028/g, "\\u2028")
         .replace(/\u2029/g, "\\u2029");
-    return new LambderSafeHtml(`<script type="application/json" id="${escapeHtml(id)}">${json}</script>`);
+    const idAttribute = id === undefined ? "" : ` id="${escapeHtml(id)}"`;
+    return new LambderSafeHtml(`<script type="${type}"${idAttribute}>${json}</script>`);
 };

package/dist/shared/LambderI18n.d.ts

@@ -18,13 +18,63 @@ export interface LambderLanguageMeta {
     /** App-specific extras (e.g. flag emoji). */
     [extra: string]: unknown;
 }
+/**
+ * The plural categories `Intl.PluralRules` sorts a count into. Which of them
+ * a language uses is its own: English uses one and other, Arabic all six,
+ * Japanese other alone.
+ */
+export type LambderI18nPluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
+/**
+ * A text that varies with a count: one form per plural category, keyed by
+ * category, so `{ one: "{count} item", other: "{count} items" }`.
+ * `t(key, { count })` picks the form for the count under the plural rules
+ * of the language the text is in, and `other` when the entry lacks the
+ * category picked. `other` is required, so there is always a form to fall
+ * back to. Which other categories a language uses is the runtime's plural
+ * data, which differs between runtimes, so whether an entry holds them all
+ * is what `checkPluralCoverage()` reports, in a test or a build, rather than
+ * anything that fails where the dictionary arrives.
+ */
+export interface LambderI18nPluralEntry {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+/** What a dictionary holds under one key: a text, or a plural entry. */
+export type LambderI18nDictionaryEntry = string | LambderI18nPluralEntry;
 /** Extracts `{param}` placeholder names from a string literal type. */
 export type LambderI18nExtractParams<S extends string> = S extends `${string}{${infer P}}${infer Rest}` ? P | LambderI18nExtractParams<Rest> : never;
+/** The `{param}` names across every form of a plural entry. */
+type PluralEntryParams<TEntry> = LambderI18nExtractParams<Extract<TEntry[keyof TEntry], string>>;
 /**
  * Typed translator: `t(key)`, and when the key's contract value contains
- * `{tokens}`, a params object with exactly those tokens is required.
+ * `{tokens}`, a params object with exactly those tokens is required. A
+ * plural key always takes one: a numeric `count`, which picks the form,
+ * beside the tokens across its forms.
+ *
+ * The text test is wrapped (`[...] extends [string]`) so that it does not
+ * distribute: a translator stays comparable to `(key: string) => string`,
+ * which a cast for keys known only at runtime relies on.
+ */
+export type LambderI18nTranslator<TContract extends Record<string, LambderI18nDictionaryEntry>> = <K extends keyof TContract & string>(...args: [TContract[K]] extends [string] ? LambderI18nExtractParams<TContract[K] & string> extends never ? [key: K] : [key: K, params: Record<LambderI18nExtractParams<TContract[K] & string>, string | number>] : [key: K, params: {
+    count: number;
+} & Record<Exclude<PluralEntryParams<TContract[K]>, "count">, string | number>]) => string;
+/**
+ * What a language other than the default gives for a contract (the default
+ * language's block): a text for each text, and for each plural entry a
+ * plural entry of its own, whose forms are its language's. A plain text in
+ * place of a plural entry stands for the other form alone: complete for a
+ * language whose rules use nothing else (Japanese, say), and a gap that
+ * `checkPluralCoverage()` reports for any other. A plural entry where the
+ * contract has a text is a type error: `t` takes no count for that key, so
+ * no form could be picked.
  */
-export type LambderI18nTranslator<TContract extends Record<string, string>> = <K extends keyof TContract & string>(...args: LambderI18nExtractParams<TContract[K]> extends never ? [key: K] : [key: K, params: Record<LambderI18nExtractParams<TContract[K]>, string | number>]) => string;
+type TranslationBlock<TContract> = {
+    [K in keyof TContract]: TContract[K] extends string ? string : LambderI18nDictionaryEntry;
+};
 /**
  * A language block fetched on demand instead of bundled: a function that
  * resolves to the dictionary, or to a module whose default export is the
@@ -40,7 +90,7 @@ export type LambderI18nDictionaryLoader<TDict> = () => Promise<TDict | {
  * rather than the union, is what lets a compile error name the missing key.
  */
 type LanguageBlockFor<TBlocks, L, TDict> = L extends keyof TBlocks ? TBlocks[L] extends (...args: never[]) => unknown ? LambderI18nDictionaryLoader<TDict> : TDict : TDict;
-export interface LambderI18nConfig<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TBase extends Record<TDefault, Record<string, string>>> {
+export interface LambderI18nConfig<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TBase extends Record<TDefault, Record<string, LambderI18nDictionaryEntry>>> {
     /** Master registry of every supported language and its metadata. */
     languages: TLanguages;
     /** Final fallback language. Must be included in `enforced`. */
@@ -53,16 +103,18 @@ export interface LambderI18nConfig<TLanguages extends Record<string, LambderLang
     /**
      * App-wide base dictionary. Strict: every language in `languages` must
      * provide every key (the `defaultLanguage` block is the typed contract).
-     * Any language but the default may be a loader instead
+     * A key's entry is a text, or a plural entry where the text varies with
+     * a count. Any language but the default may be a loader instead
      * (`tr: () => import("./tr")`), fetched by `loadLanguage`. The default
      * block stays inline, because every lookup falls back to it.
      */
     base: TBase & {
-        [L in keyof TLanguages]: L extends TDefault ? Record<keyof TBase[TDefault], string> : LanguageBlockFor<TBase, L, Record<keyof TBase[TDefault], string>>;
+        [L in keyof TLanguages]: L extends TDefault ? Record<keyof TBase[TDefault], LambderI18nDictionaryEntry> : LanguageBlockFor<TBase, L, TranslationBlock<TBase[TDefault]>>;
     };
     /**
      * Optional language detector, tried before browser detection. Return a
-     * supported code to pick it, or null/undefined to continue the chain:
+     * supported code, in any case, to pick it (it is matched as language tags
+     * are, case-insensitively), or anything else to continue the chain:
      * setLanguage override → detectLanguage → browser languages → defaultLanguage.
      */
     detectLanguage?: (helpers: {
@@ -71,7 +123,7 @@ export interface LambderI18nConfig<TLanguages extends Record<string, LambderLang
         defaultLanguage: TDefault;
     }) => string | null | undefined;
 }
-export interface LambderI18nInstance<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TContract extends Record<string, string>> {
+export interface LambderI18nInstance<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TContract extends Record<string, LambderI18nDictionaryEntry>> {
     /** Translate using the automatically resolved active language. */
     t: LambderI18nTranslator<TContract>;
     /** Translator bound to an explicit language (per-request backend use). */
@@ -83,9 +135,9 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
      * Returns a new instance whose key space = parent keys + new keys.
      */
     extend<const TExt extends {
-        [D in TDefault]: Record<string, string>;
+        [D in TDefault]: Record<string, LambderI18nDictionaryEntry>;
     }>(dict: {
-        [L in keyof TLanguages]: L extends TDefault ? Record<keyof TExt[TDefault], string> : LanguageBlockFor<TExt, L, Record<keyof TExt[TDefault], string>>;
+        [L in keyof TLanguages]: L extends TDefault ? Record<keyof TExt[TDefault], LambderI18nDictionaryEntry> : LanguageBlockFor<TExt, L, TranslationBlock<TExt[TDefault]>>;
     } & {
         [D in TDefault]: Partial<Record<keyof TContract, never>>;
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
@@ -97,11 +149,11 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
      * Any language but the default may be a loader, as in `base`.
      */
     extendPartial<const TExt extends {
-        [D in TDefault]: Record<string, string>;
+        [D in TDefault]: Record<string, LambderI18nDictionaryEntry>;
     }>(dict: {
-        [E in TEnforced[number]]: E extends TDefault ? Record<keyof TExt[TDefault], string> : LanguageBlockFor<TExt, E, Record<keyof TExt[TDefault], string>>;
+        [E in TEnforced[number]]: E extends TDefault ? Record<keyof TExt[TDefault], LambderI18nDictionaryEntry> : LanguageBlockFor<TExt, E, TranslationBlock<TExt[TDefault]>>;
     } & {
-        [L in Exclude<keyof TLanguages & string, TEnforced[number]>]?: LanguageBlockFor<TExt, L, Partial<Record<keyof TExt[TDefault], string>>>;
+        [L in Exclude<keyof TLanguages & string, TEnforced[number]>]?: LanguageBlockFor<TExt, L, Partial<TranslationBlock<TExt[TDefault]>>>;
     } & {
         [D in TDefault]: Partial<Record<keyof TContract, never>>;
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
@@ -118,8 +170,27 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
      * `loadLanguage()`, which runs only what is still missing.
      */
     loadLanguage(code?: keyof TLanguages & string): Promise<void>;
-    /** Merge additional translations at runtime (e.g. fetched from an API). Notifies change listeners. */
-    registerDictionary(code: keyof TLanguages & string, dict: Record<string, string>): void;
+    /**
+     * Merge additional translations at runtime (e.g. fetched from an API),
+     * checked as inline blocks are. Notifies change listeners.
+     */
+    registerDictionary(code: keyof TLanguages & string, dict: Record<string, LambderI18nDictionaryEntry>): void;
+    /**
+     * Whether every plural entry this instance translates with (its own and
+     * its parents', in every language) holds a form for each category the
+     * language's plural rules use, by this runtime's Intl plural data. Loads
+     * every language first, as `loadLanguage` does for each, so entries behind
+     * loaders are checked too. Resolves when nothing is missing; rejects with
+     * every gap listed by key, language and missing categories, or with the
+     * failure of a loader that would not load.
+     *
+     * For a test or a build step, not for app start: runtimes ship different
+     * plural data, and `t` falls back to an entry's `other` form for a
+     * category it lacks, so a gap shows the other form rather than failing.
+     * An extension sees its parents but not its siblings, so check each leaf
+     * extension.
+     */
+    checkPluralCoverage(): Promise<void>;
     /**
      * Override the active language (shared with all extended instances), and
      * start its loaders; change listeners fire again when they land. Await
@@ -150,7 +221,11 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
      * `i18n.onLanguageChange(() => i18n.applyToDocument())`.
      */
     applyToDocument(): void;
-    /** Type guard: is this string a supported language code? */
+    /**
+     * Type guard: is this string a supported language code, spelled exactly
+     * as registered? The methods that take a code match it in any case, as
+     * language tags are compared, and answer it as registered.
+     */
     isLanguageCode(value: string): value is keyof TLanguages & string;
     readonly languages: TLanguages;
     readonly languageList: (keyof TLanguages & string)[];
@@ -161,6 +236,21 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     readonly defaultLanguage: TDefault;
     readonly enforced: TEnforced;
 }
+/**
+ * What reading translations takes, over any instance of one contract: `t`,
+ * `forLanguage`, the active language and its metadata, change notifications
+ * and the registry, without the members that change what an instance
+ * answers (`setLanguage`, `resetLanguage`, `loadLanguage`,
+ * `registerDictionary`, `applyToDocument`, and `checkPluralCoverage`, which
+ * loads every language) or build new ones (`extend`,
+ * `extendPartial`). Instances of one contract over different language sets
+ * are different types, and every one of them is assignable to this, so code
+ * that only reads translations takes this rather than one instance's type:
+ * `LambderI18nReadonlyInstance<typeof en>` for the contract of an `en` block.
+ * Language codes read as plain strings here, the language set being what it
+ * leaves open.
+ */
+export type LambderI18nReadonlyInstance<TContract extends Record<string, LambderI18nDictionaryEntry>> = Pick<LambderI18nInstance<Record<string, LambderLanguageMeta>, string, readonly string[], TContract>, "t" | "forLanguage" | "currentLanguage" | "currentLanguageMeta" | "currentDir" | "currentIntlLocale" | "onLanguageChange" | "isLanguageCode" | "languages" | "languageList" | "languageMetaList" | "defaultLanguage" | "enforced">;
 /** Language codes of an instance: `LambderI18nCodes<typeof i18n>`. */
 export type LambderI18nCodes<T extends {
     languageList: readonly string[];
@@ -173,5 +263,5 @@ export type LambderI18nKeys<T extends {
 export type LambderI18nTranslatorFor<T extends {
     t: unknown;
 }> = T["t"];
-export declare const createLambderI18n: <const TLanguages extends Record<string, LambderLanguageMeta>, const TDefault extends keyof TLanguages & string, const TEnforced extends readonly (keyof TLanguages & string)[], const TBase extends Record<TDefault, Record<string, string>>>(config: LambderI18nConfig<TLanguages, TDefault, TEnforced, TBase>) => LambderI18nInstance<TLanguages, TDefault, TEnforced, TBase[TDefault]>;
+export declare const createLambderI18n: <const TLanguages extends Record<string, LambderLanguageMeta>, const TDefault extends keyof TLanguages & string, const TEnforced extends readonly (keyof TLanguages & string)[], const TBase extends Record<TDefault, Record<string, LambderI18nDictionaryEntry>>>(config: LambderI18nConfig<TLanguages, TDefault, TEnforced, TBase>) => LambderI18nInstance<TLanguages, TDefault, TEnforced, TBase[TDefault]>;
 export {};