lambder 14.1.1 → 15.0.2

package/dist/shared/LambderI18n.js

@@ -10,36 +10,36 @@
 // Implementation
 // ---------------------------------------------------------------------------
 /**
- * Browser detection: ordered prefs, full code then primary subtag. Only in a
- * page, where there is a document: Node 21 and later, Deno and Bun define
- * `navigator.languages` too, from the process locale, and a server's locale
- * is not its reader's.
+ * Browser detection: ordered prefs, full code then primary subtag, each
+ * matched in any case and answered as registered. Only in a page, where there
+ * is a document: Node 21 and later, Deno and Bun define `navigator.languages`
+ * too, from the process locale, and a server's locale is not its reader's.
  */
-const detectBrowserLanguage = (isCode) => {
+const detectBrowserLanguage = (codeOf) => {
     if (typeof document === "undefined" || typeof navigator === "undefined")
         return null;
     const prefs = navigator.languages?.length ? navigator.languages : [navigator.language];
     for (const pref of prefs ?? []) {
-        const lower = (pref ?? "").toLowerCase();
-        if (isCode(lower))
-            return lower;
-        const primary = lower.split("-")[0] ?? "";
-        if (isCode(primary))
+        const full = codeOf(pref ?? "");
+        if (full)
+            return full;
+        const primary = codeOf((pref ?? "").split("-")[0] ?? "");
+        if (primary)
             return primary;
     }
     return null;
 };
 /** Mutable active-language state, shared between an instance and all its extensions. */
 class LanguageState {
-    isCode;
+    codeOf;
     defaultLanguage;
     customDetect;
     override = null;
     /** A throwing detector is reported once rather than on every t() call that runs it. */
     detectorFailureReported = false;
     listeners = new Set();
-    constructor(isCode, defaultLanguage, customDetect) {
-        this.isCode = isCode;
+    constructor(codeOf, defaultLanguage, customDetect) {
+        this.codeOf = codeOf;
         this.defaultLanguage = defaultLanguage;
         this.customDetect = customDetect;
     }
@@ -63,13 +63,13 @@ class LanguageState {
                 console.error("LambderI18n: detectLanguage threw; continuing detection chain.", err);
             }
         }
-        if (custom && this.isCode(custom))
-            return custom;
-        return detectBrowserLanguage(this.isCode) ?? this.defaultLanguage;
+        const detected = typeof custom === "string" ? this.codeOf(custom) : null;
+        if (detected)
+            return detected;
+        return detectBrowserLanguage(this.codeOf) ?? this.defaultLanguage;
     }
+    /** Overrides the active language with a code as registered (registeredCodeOf). */
     set(code) {
-        if (!this.isCode(code))
-            throw new Error(`LambderI18n: unsupported language code "${code}".`);
         if (this.override === code)
             return;
         this.override = code;
@@ -101,8 +101,8 @@ class LanguageState {
 }
 /**
  * Fills `{name}` tokens in one pass over the template, so a value is inserted
- * as it is: a display name "Eve {org}" stays that, rather than having its own
- * `{org}` filled by the next parameter. A token with no parameter stays.
+ * as it is: a display name "Eve {store}" stays that, rather than having its own
+ * `{store}` filled by the next parameter. A token with no parameter stays.
  * Own properties only, through Object.prototype.hasOwnProperty rather than
  * Object.hasOwn: this runs in the browser bundle, and a browser without
  * ES2022 (Safari before 15.4) would throw on the first parameterised text.
@@ -116,33 +116,111 @@ const interpolate = (text, params) => {
 const placeholdersOf = (text) => new Set([...text.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1]));
 /** A set of placeholders as a message shows it: `{count}, {name}`, or "none". */
 const describePlaceholders = (placeholders) => placeholders.size ? [...placeholders].sort().map((name) => `{${name}}`).join(", ") : "none";
-/** How many mismatched translations an error lists before it only counts the rest. */
-const PLACEHOLDER_MISMATCH_LIMIT = 20;
+/** How many refused entries an error lists, per kind of refusal, before it only counts the rest. */
+const REFUSED_ENTRY_LIST_LIMIT = 20;
+/** The plural categories in CLDR's order, the order messages list them in. */
+const PLURAL_CATEGORIES = ["zero", "one", "two", "few", "many", "other"];
 /**
- * Refuses translations that do not carry the placeholders of the text they
- * translate. The default language's text is the contract the translator's
- * type takes its parameters from, so a translation that drops one loses the
- * value a caller passed, and one that adds one shows its `{token}` as it
- * is. `lookupDefault` answers the default language's text for a key, and a
- * key it has none for is left to the other checks.
+ * What is wrong with a dictionary value that is not a text, as the end of a
+ * sentence about its key, or null for a well-formed plural entry: an object
+ * of texts under plural categories. Which categories it must hold is its
+ * language's, so that is checked apart.
  */
-const assertPlaceholdersKept = (lookupDefault, lang, dict, label) => {
+const pluralEntryProblem = (value) => {
+    if (!isObjectValue(value) || Array.isArray(value))
+        return "is neither a text nor a plural entry";
+    for (const [category, form] of Object.entries(value)) {
+        if (!PLURAL_CATEGORIES.includes(category)) {
+            return `has "${category}", which is no plural category (${PLURAL_CATEGORIES.join(", ")})`;
+        }
+        if (typeof form !== "string")
+            return `has a ${category} form that is not a text`;
+    }
+    if (value.other === undefined)
+        return "has no other form, which every plural entry needs";
+    return null;
+};
+/** A list of refused entries under its heading, as one section of an error. */
+const refusalSection = (heading, lines) => {
+    const listed = lines.slice(0, REFUSED_ENTRY_LIST_LIMIT).map((line) => `  ${line}`);
+    const more = lines.length > REFUSED_ENTRY_LIST_LIMIT ? [`  ... and ${lines.length - REFUSED_ENTRY_LIST_LIMIT} more`] : [];
+    return [heading, ...listed, ...more].join("\n");
+};
+/**
+ * Refuses the entries of one language's block that do not keep the default
+ * language's contract, every such key listed in one error. Everything
+ * refused here is refused alike by every runtime; which plural categories a
+ * language uses is not (runtimes ship different plural data), so that is
+ * left to checkPluralCoverage.
+ *
+ * Placeholders: the default language's text is the contract the
+ * translator's type takes its parameters from, so a translation that drops
+ * one loses the value a caller passed, and one that adds one shows its
+ * `{token}` as it is. A plural entry's contract is the tokens across all
+ * the default entry's forms, and every form in every language, the default
+ * one's included, carries each of them, except `{count}`, which a form may
+ * leave out to spell the number in words ("one item"). The default
+ * language's plain texts are the contract itself and are not compared.
+ *
+ * Kinds: a plural entry where the default language has a text is refused,
+ * since `t` takes no count for that key. A plain text where the default
+ * language has a plural entry is taken as the other form alone.
+ *
+ * Intl locale: a language with a plural entry has its plural rules built
+ * here, so an Intl locale that is no well-formed language tag, which every
+ * runtime refuses, fails where the dictionary arrives rather than in `t`.
+ *
+ * `lookupDefault` answers the default language's entry for a key, the one
+ * already held when the block is the default language's own registration.
+ * A key it has none for is held to itself.
+ */
+const assertEntriesKept = (core, lookupDefault, lang, dict, label) => {
+    const refused = [];
     const mismatches = [];
-    for (const [key, text] of Object.entries(dict)) {
-        const original = lookupDefault(key);
-        if (original === undefined || typeof text !== "string")
-            continue;
-        const expected = placeholdersOf(original);
-        const found = placeholdersOf(text);
-        if (expected.size === found.size && [...expected].every((name) => found.has(name)))
+    for (const [key, entry] of Object.entries(dict)) {
+        if (typeof entry !== "string") {
+            const problem = pluralEntryProblem(entry);
+            if (problem) {
+                refused.push(`"${key}" ${problem}`);
+                continue;
+            }
+        }
+        const checked = entry;
+        const reference = lookupDefault(key) ?? checked;
+        if (typeof reference === "string") {
+            if (typeof checked !== "string") {
+                refused.push(`"${key}" is a plural entry where the default language has a text, for which t takes no count: make the default language's entry plural`);
+            }
+            else if (lang !== core.defaultLanguage) {
+                const expected = placeholdersOf(reference);
+                const found = placeholdersOf(checked);
+                if (expected.size !== found.size || ![...expected].every((name) => found.has(name))) {
+                    mismatches.push(`"${key}" has ${describePlaceholders(found)} where the default language has ${describePlaceholders(expected)}`);
+                }
+            }
             continue;
-        mismatches.push(`"${key}" has ${describePlaceholders(found)} where the default language has ${describePlaceholders(expected)}`);
+        }
+        const forms = typeof checked === "string" ? { other: checked } : checked;
+        core.pluralRulesOf(lang);
+        const tokens = new Set(Object.values(reference).flatMap((form) => [...placeholdersOf(form)]));
+        tokens.delete("count");
+        for (const [category, form] of Object.entries(forms)) {
+            const found = placeholdersOf(form);
+            if ([...tokens].every((name) => found.has(name)) && [...found].every((name) => name === "count" || tokens.has(name)))
+                continue;
+            mismatches.push(`"${key}" (${category}) has ${describePlaceholders(found)} where every form needs ${describePlaceholders(tokens)} and may add {count}`);
+        }
     }
-    if (mismatches.length === 0)
-        return;
-    const listed = mismatches.slice(0, PLACEHOLDER_MISMATCH_LIMIT).map((line) => `  ${line}`);
-    const more = mismatches.length > PLACEHOLDER_MISMATCH_LIMIT ? [`  ... and ${mismatches.length - PLACEHOLDER_MISMATCH_LIMIT} more`] : [];
-    throw new Error([`LambderI18n: in ${label}, these "${lang}" translations carry other placeholders than the default language's text:`, ...listed, ...more].join("\n"));
+    const sections = [];
+    if (refused.length > 0) {
+        sections.push(refusalSection(`LambderI18n: in ${label}, these "${lang}" entries are refused:`, refused));
+    }
+    if (mismatches.length > 0) {
+        const texts = lang === core.defaultLanguage ? "plural forms" : "translations";
+        sections.push(refusalSection(`LambderI18n: in ${label}, these "${lang}" ${texts} carry other placeholders than the default language's text:`, mismatches));
+    }
+    if (sections.length > 0)
+        throw new Error(sections.join("\n"));
 };
 const layerLookup = (layer, lang, key) => {
     for (let node = layer; node; node = node.parent) {
@@ -167,8 +245,10 @@ const assertInlineDefaultBlock = (dict, defaultLanguage, label) => {
 };
 /**
  * A layer over its parent, from a dictionary set as configured. The inline
- * blocks' placeholders are checked here, against the default language's
- * texts the layer reaches; a loader's are checked when it has run.
+ * blocks are checked here (assertEntriesKept), against the default
+ * language's entries the layer reaches, the default block first so that a
+ * fault in the contract is reported as its own; a loader's block is checked
+ * when it has run.
  */
 const createLayer = (core, sources, parent, label) => {
     const layer = { dicts: {}, loaders: new Map(), inFlight: new Map(), parent };
@@ -178,9 +258,11 @@ const createLayer = (core, sources, parent, label) => {
         else if (source)
             layer.dicts[lang] = source;
     }
-    for (const [lang, dict] of Object.entries(layer.dicts)) {
-        if (lang !== core.defaultLanguage && dict)
-            assertPlaceholdersKept((key) => layerLookup(layer, core.defaultLanguage, key), lang, dict, label);
+    const languages = [core.defaultLanguage, ...Object.keys(layer.dicts).filter((lang) => lang !== core.defaultLanguage)];
+    for (const lang of languages) {
+        const dict = layer.dicts[lang];
+        if (dict)
+            assertEntriesKept(core, (key) => layerLookup(layer, core.defaultLanguage, key), lang, dict, label);
     }
     if (layer.loaders.size > 0)
         core.lazyLayers.add(layer);
@@ -189,11 +271,16 @@ const createLayer = (core, sources, parent, label) => {
 const isObjectValue = (value) => typeof value === "object" && value !== null;
 /**
  * A loader resolves to the dictionary itself or to a module whose default
- * export is the dictionary. The two cannot be confused: a dictionary's values
- * are strings, so a `default` holding an object can only be a module's.
+ * export is the dictionary. A `default` holding an object is a module's
+ * export, unless the contract makes `default` a plural key and the object is
+ * a plural entry: then it is the dictionary's own entry for that key, since
+ * a module's dictionary would carry keys that are no plural category.
  */
-const dictionaryFromLoaded = (loaded, lang) => {
-    const dict = isObjectValue(loaded) && isObjectValue(loaded.default) ? loaded.default : loaded;
+const dictionaryFromLoaded = (loaded, lang, lookupDefault) => {
+    const ownPluralDefault = isObjectValue(loaded)
+        && isObjectValue(lookupDefault("default"))
+        && pluralEntryProblem(loaded.default) === null;
+    const dict = isObjectValue(loaded) && isObjectValue(loaded.default) && !ownPluralDefault ? loaded.default : loaded;
     if (!isObjectValue(dict)) {
         throw new Error(`LambderI18n: the "${lang}" loader resolved to neither a dictionary nor a module whose default export is one.`);
     }
@@ -210,10 +297,11 @@ const startLayerLoad = (core, layer, lang, loader) => {
         layer.loaders.delete(lang);
         if (layer.loaders.size === 0)
             core.lazyLayers.delete(layer);
-        const dict = dictionaryFromLoaded(loaded, lang);
+        const lookupDefault = (key) => layerLookup(layer, core.defaultLanguage, key);
+        const dict = dictionaryFromLoaded(loaded, lang, lookupDefault);
         if (layer.parent)
             assertNoRedeclaredKeys(layer.parent, core.defaultLanguage, dict, `the "${lang}" loader`);
-        assertPlaceholdersKept((key) => layerLookup(layer, core.defaultLanguage, key), lang, dict, `the "${lang}" loader`);
+        assertEntriesKept(core, lookupDefault, lang, dict, `the "${lang}" loader`);
         // Translations registered while the loader ran override what it brought.
         layer.dicts[lang] = { ...dict, ...layer.dicts[lang] };
     })
@@ -249,15 +337,41 @@ const loadLanguageAcrossRoot = async (core, lang) => {
     if (failure)
         throw failure.reason;
 };
+/**
+ * A code a caller passed, as registered: language tags are case-insensitive
+ * (BCP 47), so `pt-br` names a registered `pt-BR`, and everything past this
+ * point (the override, the dictionaries, the loaders) is keyed by the one
+ * spelling the config used.
+ */
+const registeredCodeOf = (core, code) => {
+    const registered = core.codeOf(code);
+    if (registered === null)
+        throw new Error(`LambderI18n: unsupported language code "${code}".`);
+    return registered;
+};
 const buildInstance = (core, layer) => {
     const translateIn = (lang, key, params) => {
-        const text = layerLookup(layer, lang, key)
-            ?? layerLookup(layer, core.defaultLanguage, key)
-            ?? key;
+        let textLanguage = lang;
+        let entry = layerLookup(layer, lang, key);
+        if (entry === undefined) {
+            textLanguage = core.defaultLanguage;
+            entry = layerLookup(layer, textLanguage, key);
+        }
+        if (entry === undefined)
+            return key;
+        // A form is picked under the rules of the language the text is in,
+        // which is the default language's when the key fell back to it. A
+        // category the entry lacks falls back to other, silently: this
+        // runtime's plural data may list a category the dictionary was not
+        // written for, which is no fault a visitor's page can act on, and a
+        // warning would reach every visitor's console from the render path.
+        // checkPluralCoverage is where such gaps are reported.
+        const text = typeof entry === "string" ? entry : entry[core.pluralCategoryOf(textLanguage, params?.count)] ?? entry.other;
         return interpolate(text, params);
     };
     const t = (key, params) => translateIn(core.state.resolve(), key, params);
-    // forLanguage sits on the hot path of reactive T() bridges: cache per code.
+    // forLanguage sits on the hot path of reactive T() bridges: cache per
+    // code as registered, so every spelling of one hands back one translator.
     const translatorCache = new Map();
     const validateExtension = (dict, requiredLanguages, label) => {
         for (const lang of Object.keys(dict)) {
@@ -285,13 +399,12 @@ const buildInstance = (core, layer) => {
     const instance = {
         t,
         forLanguage(code) {
-            const cached = translatorCache.get(code);
+            const registered = registeredCodeOf(core, code);
+            const cached = translatorCache.get(registered);
             if (cached)
                 return cached;
-            if (!core.isCode(code))
-                throw new Error(`LambderI18n: unsupported language code "${code}".`);
-            const translator = (key, params) => translateIn(code, key, params);
-            translatorCache.set(code, translator);
+            const translator = (key, params) => translateIn(registered, key, params);
+            translatorCache.set(registered, translator);
             return translator;
         },
         extend(dict) {
@@ -303,23 +416,57 @@ const buildInstance = (core, layer) => {
             return buildInstance(core, createLayer(core, dict, layer, "extendPartial() dictionary"));
         },
         loadLanguage(code) {
-            const lang = code ?? core.state.resolve();
-            if (!core.isCode(lang))
-                return Promise.reject(new Error(`LambderI18n: unsupported language code "${lang}".`));
+            let lang;
+            try {
+                lang = registeredCodeOf(core, code ?? core.state.resolve());
+            }
+            catch (err) {
+                return Promise.reject(err);
+            }
             return loadLanguageAcrossRoot(core, lang);
         },
         registerDictionary(code, dict) {
-            if (!core.isCode(code))
-                throw new Error(`LambderI18n: unsupported language code "${code}".`);
-            if (code !== core.defaultLanguage) {
-                assertPlaceholdersKept((key) => layerLookup(layer, core.defaultLanguage, key), code, dict, `registerDictionary("${code}")`);
-            }
-            layer.dicts[code] = { ...layer.dicts[code], ...dict };
+            const lang = registeredCodeOf(core, code);
+            assertEntriesKept(core, (key) => layerLookup(layer, core.defaultLanguage, key), lang, dict, `registerDictionary("${lang}")`);
+            layer.dicts[lang] = { ...layer.dicts[lang], ...dict };
             core.state.emitChange();
         },
+        async checkPluralCoverage() {
+            await Promise.all(core.languageList.map((lang) => loadLanguageAcrossRoot(core, lang)));
+            const gaps = [];
+            for (const lang of core.languageList) {
+                // Every key this instance answers in the language, each by
+                // the entry t would use: the nearest layer's.
+                const keys = new Set();
+                for (let node = layer; node; node = node.parent) {
+                    for (const key of Object.keys(node.dicts[lang] ?? {}))
+                        keys.add(key);
+                }
+                for (const key of keys) {
+                    const entry = layerLookup(layer, lang, key);
+                    const reference = layerLookup(layer, core.defaultLanguage, key) ?? entry;
+                    if (typeof reference === "string")
+                        continue;
+                    const forms = typeof entry === "string" ? { other: entry } : entry;
+                    const used = core.pluralCategoriesOf(lang);
+                    const missing = used.filter((category) => forms[category] === undefined);
+                    if (missing.length === 0)
+                        continue;
+                    const text = typeof entry === "string" ? "is a text, which stands for the other form alone, and " : "";
+                    gaps.push(`  "${key}" in "${lang}" ${text}lacks ${missing.join(", ")}: "${lang}" uses ${used.join(", ")}`);
+                }
+            }
+            if (gaps.length > 0) {
+                throw new Error([
+                    "LambderI18n: these plural entries lack forms for categories their language's plural rules use, by this runtime's Intl plural data; t shows their other form for those counts:",
+                    ...gaps,
+                ].join("\n"));
+            }
+        },
         setLanguage(code) {
-            core.state.set(code);
-            loadSwitchedLanguage(code);
+            const lang = registeredCodeOf(core, code);
+            core.state.set(lang);
+            loadSwitchedLanguage(lang);
         },
         resetLanguage() {
             core.state.reset();
@@ -355,6 +502,18 @@ const buildInstance = (core, layer) => {
 export const createLambderI18n = (config) => {
     const languageList = Object.keys(config.languages);
     const isCode = (value) => Object.prototype.hasOwnProperty.call(config.languages, value);
+    // Language tags are case-insensitive (BCP 47): a browser's `pt-br` and a
+    // path's `PT-BR` both name a registered `pt-BR`. So two registered codes
+    // that differ only in case would be one language twice.
+    const codeByLowerCase = new Map();
+    for (const code of languageList) {
+        const clash = codeByLowerCase.get(code.toLowerCase());
+        if (clash !== undefined) {
+            throw new Error(`LambderI18n: languages registers "${clash}" and "${code}", one language tag in two spellings: tags are compared case-insensitively.`);
+        }
+        codeByLowerCase.set(code.toLowerCase(), code);
+    }
+    const codeOf = (value) => typeof value === "string" ? codeByLowerCase.get(value.toLowerCase()) ?? null : null;
     if (!isCode(config.defaultLanguage)) {
         throw new Error(`LambderI18n: defaultLanguage "${config.defaultLanguage}" is not in languages.`);
     }
@@ -384,6 +543,25 @@ export const createLambderI18n = (config) => {
         })
         : null;
     const metaByCode = new Map(languageList.map((code) => [code, { code, ...config.languages[code] }]));
+    // Built for a language the first time one of its plural entries arrives,
+    // and kept: t picks a form on every call, and building the rules costs
+    // far more than the pick. Never for a language without plural entries,
+    // so its code need not be a tag Intl accepts.
+    const pluralRules = new Map();
+    const pluralRulesOf = (lang) => {
+        let rules = pluralRules.get(lang);
+        if (!rules) {
+            const locale = metaByCode.get(lang)?.intlLocale ?? lang;
+            try {
+                rules = new Intl.PluralRules(locale);
+            }
+            catch (err) {
+                throw new Error(`LambderI18n: "${lang}" has plural entries, and Intl.PluralRules refuses its Intl locale "${locale}" (${err.message}): give the language an intlLocale it accepts.`);
+            }
+            pluralRules.set(lang, rules);
+        }
+        return rules;
+    };
     const core = {
         languages: config.languages,
         languageList,
@@ -391,9 +569,16 @@ export const createLambderI18n = (config) => {
         metaList: [...metaByCode.values()],
         defaultLanguage: config.defaultLanguage,
         enforced: config.enforced,
-        state: new LanguageState(isCode, config.defaultLanguage, customDetect),
+        state: new LanguageState(codeOf, config.defaultLanguage, customDetect),
         isCode,
+        codeOf,
         lazyLayers: new Set(),
+        pluralRulesOf,
+        pluralCategoriesOf: (lang) => {
+            const used = pluralRulesOf(lang).resolvedOptions().pluralCategories;
+            return PLURAL_CATEGORIES.filter((category) => used.includes(category));
+        },
+        pluralCategoryOf: (lang, count) => pluralRulesOf(lang).select(Number(count)),
     };
     return buildInstance(core, createLayer(core, config.base, null, "base dictionary"));
 };

package/dist/shared/contracts/LambderCache.d.ts

@@ -22,6 +22,19 @@ export interface LambderCacheSetOptions {
     /** How long the entry lives. Default: the cache's own defaultTtlSeconds. */
     ttlSeconds?: number;
 }
+/**
+ * What getOrSet takes: a write's options, and the fill lease LambderDdbCache
+ * holds across containers while one of them loads a missing entry. A cache
+ * that holds no lease checks the lease options all the same and otherwise
+ * ignores them, so code typed against LambderCache tunes the lease for the
+ * table and runs unchanged over any cache.
+ */
+export interface LambderCacheGetOrSetOptions extends LambderCacheSetOptions {
+    /** How long one container's fill lease on a missing entry holds the others off. Default: 15. */
+    leaseSeconds?: number;
+    /** How long a container waits for another's fill before loading itself. Default: (leaseSeconds + 1) * 1000. */
+    waitForFillMs?: number;
+}
 export interface LambderCacheListOptions {
     /** Only sort keys starting with this prefix. */
     prefix?: string;
@@ -63,5 +76,5 @@ export interface LambderCache {
      * lands over it. An invalid option throws before anything is read or
      * loaded.
      */
-    getOrSet<T>(key: LambderCacheKey, loader: () => Promise<T>, options?: LambderCacheSetOptions): Promise<T>;
+    getOrSet<T>(key: LambderCacheKey, loader: () => Promise<T>, options?: LambderCacheGetOrSetOptions): Promise<T>;
 }

package/dist/shared/contracts/LambderRateLimiter.d.ts

@@ -58,12 +58,11 @@ export type LambderRateLimitResult = false | LambderRateLimitExceeded;
  * implementations disagree on a negative cap (one refuses the first attempt,
  * the other allows it), since neither is meant to be asked.
  *
- * The tracker key is bounded there too: the variable half of it (a custom
- * key handler's return, a session key) is replaced by its own sha256 once it
- * passes 1024 UTF-8 bytes as written into the key, so an implementation with
- * a key limit of its own never meets a key it has to refuse. That matters
- * because a limiter's refusal is a throw, and a throw is what failOpen
- * swallows into no limit at all.
+ * The tracker key is bounded there too: its caller's half (an address, a
+ * session key, a custom key handler's return) arrives as a digest of fixed
+ * length, so an implementation with a key limit of its own never meets a key
+ * it has to refuse. That matters because a limiter's refusal is a throw, and
+ * a throw is what failOpen swallows into no limit at all.
  *
  * A limiter that answers a run of requests with one continuing failure (the
  * DynamoDB limiter, for a flooded partition it cannot size) may throw the

package/dist/shared/transport/LambderApiTransport.d.ts

@@ -67,8 +67,9 @@ export declare const isLambderTransportFailure: (err: unknown) => err is Lambder
  *   status means. Rejecting on a status would throw away the envelope a
  *   refusal, a validation failure or a crash arrived in.
  * - **A rejection is a transport failure.** The caller reports it as
- *   `network`, as `timeout` when its own abort fired, or as the reason a
- *   thrown LambderTransportFailure names. That failure's `cause` carries the
+ *   `network`, as `timeout` or `aborted` when the call's own timeout or
+ *   signal had aborted it, or as the reason a thrown LambderTransportFailure
+ *   names. That failure's `cause` carries the
  *   real error through to the caller's `outcome.error`.
  * - **`request.signal` must be honoured**, by rejecting as soon as it aborts.
  *   Without that, the caller's `timeoutMs` and per-call `signal` mean

package/dist/shared/util/LambderBackoffTimer.d.ts

@@ -7,7 +7,9 @@
  * retry. So the timer holds exactly one wait of either kind: `retry` and
  * `wait` climb the ladder, `after` waits a fixed time without climbing it, and
  * scheduling any of them replaces whatever was waiting. A caller says what to
- * run and when it worked, and never keeps a handle and a counter of its own.
+ * run and when it worked, and never keeps a handle and a counter of its own:
+ * `retries` is how many times it has been asked to try again since the last
+ * reset, so a loop that gives up after so many reads it there.
  *
  * The ladder: a retry waits the base plus a share of a ceiling that grows by
  * `factor` with every failed attempt, the whole never past `maxMs`. With full
@@ -22,15 +24,17 @@
  */
 export type LambderBackoffTimerOptions = {
     /**
-     * The shortest retry wait, in milliseconds. The first after a reset falls
-     * between it and twice it (exactly twice with `jitter: "none"`), so even
-     * the first retries of many clients spread out. Default: 1000.
+     * The shortest retry wait, in milliseconds, above 0: every wait is a
+     * multiple of it, so 0 would retry with no pause. The first after a reset
+     * falls between it and twice it (exactly twice with `jitter: "none"`), so
+     * even the first retries of many clients spread out. Default: 1000.
      */
     baseMs?: number;
     /**
      * The longest any retry wait is, in milliseconds, however many attempts
-     * have failed; at least `baseMs`. Default: 60000, or `baseMs` when that is
-     * longer.
+     * have failed; at least `baseMs`, and at most 2147483647 (about 24.8
+     * days), the longest delay setTimeout keeps. Default: 60000, or `baseMs`
+     * when that is longer.
      */
     maxMs?: number;
     /** How much the ceiling grows with each failed attempt. Default: 2. */
@@ -47,7 +51,7 @@ export declare class LambderBackoffTimer {
     private readonly maxMs;
     private readonly factor;
     private readonly jitter;
-    private attempts;
+    private retriesSinceReset;
     private timer;
     /** Settles the promise of a `wait` that cancel() or a replacement drops, so no `await` is left hanging. */
     private dropPending;
@@ -55,13 +59,20 @@ export declare class LambderBackoffTimer {
     /** True while a wait of any kind is pending. False again by the time it runs. */
     get pending(): boolean;
     /**
-     * Runs `run` after the next rung of the ladder, counting one more failed
-     * attempt. Replaces whatever was waiting.
+     * How many retries `retry` and `wait` have scheduled since the last reset
+     * (or since the timer was built), a dropped one included: the rung the
+     * next one climbs from. A loop that gives up after so many retries reads
+     * it here rather than keeping a counter of its own.
+     */
+    get retries(): number;
+    /**
+     * Runs `run` after the next rung of the ladder, counting one more retry.
+     * Replaces whatever was waiting.
      */
     retry(run: () => void): void;
     /**
-     * Resolves after the next rung of the ladder, counting one more failed
-     * attempt: the `retry` for code that awaits rather than calls back.
+     * Resolves after the next rung of the ladder, counting one more retry:
+     * the `retry` for code that awaits rather than calls back.
      * Replaces whatever was waiting. Rejects at once with the signal's reason
      * when `signal` aborts, and with an Error when cancel() or a later wait
      * drops it before it ran, so an await on it always settles.
@@ -72,11 +83,11 @@ export declare class LambderBackoffTimer {
      * climbs. Replaces whatever was waiting.
      */
     after(delayMs: number, run: () => void): void;
-    /** The attempt worked: the next failure waits the shortest time again. A pending wait is left alone. */
+    /** The attempt worked: the next failure waits the shortest time again, and `retries` is 0. A pending wait is left alone. */
     reset(): void;
     /** Drops the pending wait (the caller is trying right now, or going away), keeping the count. */
     cancel(): void;
-    /** The next wait on the ladder, in milliseconds, counting one more failed attempt. */
+    /** The next wait on the ladder, in milliseconds, counting one more retry. */
     private nextRung;
     private schedule;
 }