i18next 26.4.7 → 26.5.1

package/dist/esm/package.json

@@ -1 +1 @@
-{"type":"module","version":"26.4.7"}
+{"type":"module","version":"26.5.1"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18next",
-  "version": "26.4.7",
+  "version": "26.5.1",
   "description": "i18next internationalization framework",
   "main": "./dist/cjs/i18next.js",
   "module": "./dist/esm/i18next.js",

package/typescript/options.d.ts

@@ -189,8 +189,24 @@ export type TypeOptions = $MergeBy<
        * `}}`. This flag is type-only; runtime interpolation is governed by
        * `InterpolationOptions` and is unaffected.
        *
-       * Required by `i18next-icu` users — see that package's docs for the
-       * recommended `CustomTypeOptions` augmentation.
+       * Set to `'icu'` with `i18next-icu` to type `t()` options from the ICU
+       * MessageFormat arguments instead: `{name}` takes `string | number`,
+       * `{n, number}`, `plural` and `selectordinal` take `number`, `{d, date}`
+       * and `{t, time}` take `Date`, `select` takes its case keys or any string
+       * (for `other`), and arguments nested in cases are required too.
+       * `interpolationFormatTypeMap` overrides a type by its format name (e.g.
+       * `date: Date | number`). Options become required for a message with
+       * arguments.
+       *
+       * Set to `'mf2'` with `i18next-mf2` to type `t()` options from the
+       * MessageFormat 2 variables: `{$name}` takes `string | number`, a
+       * variable annotated with `:number`, `:integer`, `:currency`, `:percent`
+       * or `:unit` (directly or through `.input`/`.local`) takes `number`,
+       * `:datetime`, `:date` and `:time` take `Date`, `:string` takes `string`,
+       * option and markup variables (`minimumFractionDigits=$digits`,
+       * `{#link href=$url}`) take `string | number`, and `.local` variables are
+       * not arguments. `interpolationFormatTypeMap` overrides a type by its
+       * function name.
        *
        * @default true
        */

package/typescript/t.d.ts

@@ -74,6 +74,26 @@ interface Branded<Ns extends Namespace> {
     : never;
 }
 
+/**
+ * `keyof Res`, built once per resource object. TypeScript does not cache
+ * `keyof` of an object type, so `keyof Res` inside a conditional that runs per
+ * key (or per `t()` call) rebuilt the union of all keys every time: quadratic
+ * in the namespace size. Conditional type instantiations are cached.
+ */
+type _KeysOf<Res> = [Res] extends [unknown] ? keyof Res : never;
+
+/**
+ * `Res[Key & keyof Res]`: a literal key is looked up directly instead of being
+ * intersected with every key; a wide key (`string`, `${string}_suffix` from a
+ * string context) still matches all keys it covers.
+ */
+type _ValueOf<Res, Key> =
+  Key extends _KeysOf<Res>
+    ? Res[Key]
+    : _IsLiteral<Key & PropertyKey> extends true
+      ? never
+      : Res[Key & _KeysOf<Res>];
+
 /** ****************************************************
  * Build all keys and key prefixes based on Resources *
  ***************************************************** */
@@ -81,18 +101,20 @@ interface Branded<Ns extends Namespace> {
 // conditional types, so `KeyPrefix<Ns>` no longer resolves to a literal union
 // and `keyPrefix` inference widens to the whole namespace, polluting `t()`
 // return types with sibling keys (#2434 regression). Guard `never` in the merge.
-type KeysBuilderWithReturnObjects<Res, Key = keyof Res> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary | readonly unknown[]
-    ? | JoinKeys<Key, WithOrWithoutPlural<keyof $OmitArrayKeys<Res[Key]>>>
-      | JoinKeys<Key, KeysBuilderWithReturnObjects<Res[Key]>>
-    : never
-  : never;
+type KeysBuilderWithReturnObjects<Res, Key = keyof Res> =
+  Key extends _KeysOf<Res>
+    ? Res[Key] extends $Dictionary | readonly unknown[]
+      ? | JoinKeys<Key, WithOrWithoutPlural<keyof $OmitArrayKeys<Res[Key]>>>
+        | JoinKeys<Key, KeysBuilderWithReturnObjects<Res[Key]>>
+      : never
+    : never;
 
-type KeysBuilderWithoutReturnObjects<Res, Key = keyof $OmitArrayKeys<Res>> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary | readonly unknown[]
-    ? JoinKeys<Key, KeysBuilderWithoutReturnObjects<Res[Key]>>
-    : Key
-  : never;
+type KeysBuilderWithoutReturnObjects<Res, Key = keyof $OmitArrayKeys<Res>> =
+  Key extends _KeysOf<Res>
+    ? Res[Key] extends $Dictionary | readonly unknown[]
+      ? JoinKeys<Key, KeysBuilderWithoutReturnObjects<Res[Key]>>
+      : Key
+    : never;
 
 type KeysBuilder<Res, WithReturnObjects> = $IsResourcesDefined extends true
   ? WithReturnObjects extends true
@@ -172,7 +194,7 @@ type ParseActualValue<Ret> = Ret extends `${_UnescapePrefix}${infer ActualValue}
   : Ret;
 
 /** Parses interpolation entries as `[variableName, formatSpecifier | never]` tuples. */
-type ParseInterpolationEntries<Ret> = [_ParseInterpolation] extends [false]
+type ParseInterpolationEntries<Ret> = [_ParseInterpolation] extends [false | 'icu' | 'mf2']
   ? never
   : Ret extends `${string}${_InterpolationPrefix}${infer Value}${_InterpolationSuffix}${infer Rest}`
     ? | (Value extends `${infer ActualValue},${infer Format}`
@@ -225,23 +247,213 @@ type _InterpolationMapFromEntries<E> = _UnionToIntersection<
     : never
 >;
 
-export type InterpolationMap<Ret> = $PreservedValue<
-  _InterpolationMapFromEntries<ParseInterpolationEntries<Ret>>,
-  Record<string, unknown>
->;
+/** *********************************************************************
+ * ICU MessageFormat arguments (`parseInterpolation: 'icu'`)            *
+ *********************************************************************** */
+type _IcuWhitespace = ' ' | '\n' | '\t' | '\r';
+type _IcuTrim<S> = S extends `${_IcuWhitespace}${infer R}`
+  ? _IcuTrim<R>
+  : S extends `${infer R}${_IcuWhitespace}`
+    ? _IcuTrim<R>
+    : S;
+
+/**
+ * Drops ICU apostrophe quoting as intl-messageformat (i18next-icu) reads it:
+ * `''` is a literal apostrophe, `'{...}'` (also `'}'`, `'<'`, `'>'`, `'#'`) is
+ * literal text up to the next single apostrophe.
+ * Simplification: `'#` quotes everywhere here, at runtime only inside plurals.
+ */
+type _IcuStripQuotes<S, Acc extends string = ''> = S extends `${infer L}'${infer R}`
+  ? R extends `'${infer R2}`
+    ? _IcuStripQuotes<R2, `${Acc}${L}`>
+    : R extends `${'{' | '}' | '<' | '>' | '#'}${string}`
+      ? _IcuStripQuotes<_IcuSkipQuoted<R>, `${Acc}${L}`>
+      : _IcuStripQuotes<R, `${Acc}${L}'`>
+  : `${Acc}${S & string}`;
+type _IcuSkipQuoted<S> = S extends `${string}'${infer R}`
+  ? R extends `'${infer R2}`
+    ? _IcuSkipQuoted<R2>
+    : R
+  : '';
+
+/** Reads up to the `}` closing an already opened `{`; returns `[content, rest]`. */
+type _IcuBlock<
+  S,
+  Acc extends string = '',
+  Depth extends 0[] = [],
+> = S extends `${infer L}}${infer R}`
+  ? L extends `${infer L2}{${infer R2}`
+    ? _IcuBlock<`${R2}}${R}`, `${Acc}${L2}{`, [...Depth, 0]>
+    : Depth extends [0, ...infer D extends 0[]]
+      ? _IcuBlock<R, `${Acc}${L}}`, D>
+      : [`${Acc}${L}`, R]
+  : never;
+
+/** `[name, type]` entries of every argument in a message, nested cases included. */
+type _IcuEntries<S, Acc = never> = S extends `${string}{${infer R}`
+  ? _IcuBlock<R> extends [infer Arg, infer Rest]
+    ? _IcuEntries<Rest, Acc | _IcuArg<Arg>>
+    : Acc
+  : Acc;
+
+/** Walks plural/select cases: `[selector keys, entries of all case messages]`. */
+type _IcuCases<S, Keys = never, Acc = never> = S extends `${infer L}{${infer R}`
+  ? _IcuBlock<R> extends [infer Msg, infer Rest]
+    ? _IcuCases<Rest, Keys | _IcuTrim<L>, Acc | _IcuEntries<Msg>>
+    : [Keys, Acc]
+  : [Keys, Acc];
+
+type _IcuArg<A> = A extends `${infer Name},${infer Type},${infer Cases}`
+  ? _IcuTrim<Type> extends 'plural' | 'selectordinal'
+    ? [_IcuTrim<Name>, _IcuFormatType<_IcuTrim<Type>>] | _IcuCases<Cases>[1]
+    : _IcuTrim<Type> extends 'select'
+      ? _IcuCases<Cases> extends [infer Keys, infer E]
+        ? [_IcuTrim<Name>, 'other' extends Keys ? Exclude<Keys, 'other'> | (string & {}) : Keys] | E
+        : never
+      : [_IcuTrim<Name>, _IcuFormatType<_IcuTrim<Type>>] // `{n, number, ::currency/EUR}`
+  : A extends `${infer Name},${infer Type}`
+    ? [_IcuTrim<Name>, _IcuFormatType<_IcuTrim<Type>>]
+    : [_IcuTrim<A>, _IcuFormatType<never>];
+
+/** `interpolationFormatTypeMap` wins, then ICU's built-in argument types. */
+type _IcuFormatType<F> = [F] extends [never]
+  ? string | number
+  : F extends keyof _InterpolationFormatTypeMap
+    ? _InterpolationFormatTypeMap[F]
+    : F extends 'number' | 'plural' | 'selectordinal'
+      ? number
+      : F extends 'date' | 'time'
+        ? Date
+        : string | number;
+
+/**
+ * Merges `[name, type]` entries into one record: a name used twice gets both
+ * types, a dotted MF2 name (`$user.name`) becomes a nested object.
+ */
+type _ArgsFromEntries<E> =
+  _UnionToIntersection<
+    E extends [infer Name extends string, infer Type]
+      ? Name extends `${string}.${string}`
+        ? $StringKeyPathToRecord<Name, Type>
+        : { [K in Name]: Type }
+      : never
+  > extends infer M
+    ? [E] extends [never]
+      ? never
+      : { [K in keyof M]: M[K] }
+    : never;
+
+type _IcuArgsMap<Ret> = Ret extends string
+  ? string extends Ret
+    ? never
+    : _ArgsFromEntries<_IcuEntries<_IcuStripQuotes<Ret>>>
+  : never;
+
+/** *********************************************************************
+ * MessageFormat 2 variables (`parseInterpolation: 'mf2'`)              *
+ *********************************************************************** */
+/** Drops `\`-escapes (`\{`, `\}`, `\|`, `\\`), so they are neither braces nor quotes. */
+type _Mf2StripEscapes<S, Acc extends string = ''> = S extends `${infer L}\\${string}${infer R}`
+  ? _Mf2StripEscapes<R, `${Acc}${L}`>
+  : `${Acc}${S & string}`;
+
+/** Reads an expression up to its `}`, skipping `|quoted literals|`; returns `[body, rest]`. */
+type _Mf2Expression<S, Acc extends string = ''> = S extends `${infer B}}${infer Rest}`
+  ? B extends `${infer Before}|${infer Lit}`
+    ? `${Lit}}${Rest}` extends `${string}|${infer After}`
+      ? _Mf2Expression<After, `${Acc}${Before} `>
+      : never
+    : [`${Acc}${B}`, Rest]
+  : never;
+
+/** `[name, type]` entries of every variable in a message's expressions; `{{` opens a quoted pattern. */
+type _Mf2Entries<S, Acc = never> = S extends `${string}{${infer R}`
+  ? R extends `{${infer Pattern}`
+    ? _Mf2Entries<Pattern, Acc>
+    : _Mf2Expression<R> extends [infer Body, infer Rest]
+      ? _Mf2Entries<Rest, Acc | _Mf2ExprEntries<_Mf2Spaces<Body>>>
+      : Acc
+  : Acc;
+
+type _Mf2Space<S, C extends string> = S extends `${infer L}${C}${infer R}`
+  ? _Mf2Space<`${L} ${R}`, C>
+  : S;
+type _Mf2Spaces<S> = _IcuTrim<_Mf2Space<_Mf2Space<_Mf2Space<S, '\n'>, '\t'>, '\r'>>;
+type _Mf2Name<S> = S extends `${infer N} ${string}`
+  ? _Mf2Name<N>
+  : S extends `${infer N}/${string}`
+    ? N
+    : S;
+
+/** `{$x :fn opt=$y}`: `$x` typed by its function, option and markup variables `string | number`. */
+type _Mf2ExprEntries<Body> = Body extends `$${infer R}`
+  ? R extends `${infer Name} ${infer Tail}`
+    ? | [Name, _Mf2FunctionType<_IcuTrim<Tail> extends `:${infer F}` ? _Mf2Name<F> : never>]
+      | _Mf2Vars<Tail>
+    : [_Mf2Name<R>, _Mf2FunctionType<never>]
+  : _Mf2Vars<Body>;
+
+/** Every `$name` in a string, typed `string | number`. */
+type _Mf2Vars<S, Acc = never> = S extends `${string}$${infer R}`
+  ? _Mf2Vars<R, Acc | [_Mf2Name<R>, string | number]>
+  : Acc;
+
+/** `interpolationFormatTypeMap` wins, then messageformat's built-in functions. */
+type _Mf2FunctionType<F> = [F] extends [never]
+  ? string | number
+  : F extends keyof _InterpolationFormatTypeMap
+    ? _InterpolationFormatTypeMap[F]
+    : F extends 'number' | 'integer' | 'currency' | 'percent' | 'offset' | 'unit' | 'math'
+      ? number
+      : F extends 'datetime' | 'date' | 'time'
+        ? Date
+        : F extends 'string'
+          ? string
+          : string | number;
+
+/** Names declared by `.local $name = ...` (local, not passed in). */
+type _Mf2Locals<S, Acc = never> = S extends `${string}.local${infer R}`
+  ? _Mf2Locals<R, Acc | (_IcuTrim<R> extends `$${infer N}=${string}` ? _IcuTrim<N> : never)>
+  : Acc;
+/** `.match $a $b`: selectors, normally also declared by `.input` or `.local`. */
+type _Mf2Selectors<S> = S extends `${string}.match${infer R}`
+  ? _Mf2Vars<_Mf2Spaces<R extends `${infer Sel}{${string}` ? Sel : R>>
+  : never;
+
+type _Mf2ArgsMap<Ret> = Ret extends string
+  ? string extends Ret
+    ? never
+    : _Mf2StripEscapes<Ret> extends infer S
+      ? _ArgsFromEntries<
+          Exclude<
+            _Mf2Entries<S> | _Mf2Selectors<S>,
+            [_IcuTrim<S> extends `.${string}` ? _Mf2Locals<S> : never, unknown]
+          >
+        >
+      : never
+  : never;
+
+export type InterpolationMap<Ret> = [_ParseInterpolation] extends ['icu']
+  ? $PreservedValue<_IcuArgsMap<Ret>, Record<string, unknown>>
+  : [_ParseInterpolation] extends ['mf2']
+    ? $PreservedValue<_Mf2ArgsMap<Ret>, Record<string, unknown>>
+    : $PreservedValue<
+        _InterpolationMapFromEntries<ParseInterpolationEntries<Ret>>,
+        Record<string, unknown>
+      >;
 
 type ParseTReturnPlural<
   Res,
   Key,
   KeyWithPlural = `${Key & string}${_PluralSeparator}${PluralSuffix}`,
-> = Res[(KeyWithPlural | Key) & keyof Res];
+> = _ValueOf<Res, KeyWithPlural | Key>;
 
 type ParseTReturnPluralOrdinal<
   Res,
   Key,
   KeyWithOrdinalPlural = `${Key &
     string}${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`,
-> = Res[(KeyWithOrdinalPlural | Key) & keyof Res];
+> = _ValueOf<Res, KeyWithOrdinalPlural | Key>;
 
 type ParseTReturnWithFallback<Key, Val> = Val extends ''
   ? _ReturnEmptyString extends true
@@ -256,7 +468,7 @@ type ParseTReturnWithFallback<Key, Val> = Val extends ''
 type ParseTReturn<Key, Res, TOpt extends TOptions = {}> = ParseTReturnWithFallback<
   Key,
   Key extends `${infer K1}${_KeySeparator}${infer RestKey}`
-    ? ParseTReturn<RestKey, Res[K1 & keyof Res], TOpt>
+    ? ParseTReturn<RestKey, _ValueOf<Res, K1>, TOpt>
     : // Process plurals only if count is provided inside options
       TOpt['count'] extends number
       ? TOpt['ordinal'] extends boolean
@@ -267,7 +479,7 @@ type ParseTReturn<Key, Res, TOpt extends TOptions = {}> = ParseTReturnWithFallba
         ? Key extends `${infer NKey extends number}`
           ? Res[NKey]
           : never
-        : Res[Key & keyof Res]
+        : _ValueOf<Res, Key>
 >;
 
 type TReturnOptionalNull = _ReturnNull extends true ? null : never;
@@ -393,6 +605,28 @@ type EffectiveKPrefix<KPrefix, TOpt> = TOpt extends { keyPrefix: infer OptKP ext
   ? OptKP
   : KPrefix;
 
+/** `parseInterpolation: 'icu'` or `'mf2'`: messages are typed by their arguments. */
+type _ParsesMessageFormat = [_ParseInterpolation] extends ['icu'] | ['mf2'] ? true : false;
+
+/**
+ * `t()` options are optional, except for a message with arguments under
+ * `parseInterpolation: 'icu'` or `'mf2'` (on a missing one, i18next-icu renders
+ * the raw message and i18next-mf2 a `{$name}` fallback). The conditional
+ * resolves eagerly; a generic one here would break inference.
+ */
+type _KeyAndOptions<Key, Ret, Opts> = _ParsesMessageFormat extends true
+  ? [key: Key | Key[], options: Opts] | [key: (Key | Key[]) & _IfOptionalOptions<Ret>]
+  : [key: Key | Key[], options?: Opts];
+/** `unknown` when options may be left out, else a type naming the missing arguments. */
+type _IfOptionalOptions<Ret> = _ParsesMessageFormat extends true
+  ? {} extends InterpolationMap<Ret>
+    ? unknown
+    : { 'pass these arguments as t() options': InterpolationMap<Ret> }
+  : unknown;
+/** Options parameter of a selector overload: required for a message with arguments. */
+type _SelectorOptionsArg<Ret, Opts> =
+  unknown extends _IfOptionalOptions<Ret> ? [options?: Opts] : [options: Opts];
+
 /** ************************
  * T function declaration *
  ************************* */
@@ -407,7 +641,7 @@ interface TFunctionStrict<
     Ret extends TFunctionReturn<Ns, AppendKeyPrefix<Key, EffectiveKPrefix<KPrefix, TOpt>>, TOpt>,
   >(
     key: Key | Key[],
-    options?: TOpt &
+    options: TOpt &
       InterpolationMap<Ret> & {
         context?: Key extends string
           ? unknown extends TOpt['context']
@@ -416,6 +650,13 @@ interface TFunctionStrict<
           : never;
       },
   ): TFunctionReturnOptionalDetails<TFunctionProcessReturnValue<$NoInfer<Ret>, never>, TOpt>;
+  <
+    const Key extends ParseKeys<Ns, TOpt, EffectiveKPrefix<KPrefix, TOpt>> | TemplateStringsArray,
+    const TOpt extends TOptions,
+    Ret extends TFunctionReturn<Ns, AppendKeyPrefix<Key, EffectiveKPrefix<KPrefix, TOpt>>, TOpt>,
+  >(
+    key: (Key | Key[]) & _IfOptionalOptions<$NoInfer<Ret>>,
+  ): TFunctionReturnOptionalDetails<TFunctionProcessReturnValue<$NoInfer<Ret>, never>, TOpt>;
   <
     const Key extends ParseKeys<Ns, TOpt, EffectiveKPrefix<KPrefix, TOpt>> | TemplateStringsArray,
     const TOpt extends TOptions,
@@ -460,9 +701,9 @@ interface TFunctionNonStrict<
     DefaultValue extends string = never,
   >(
     ...args:
-      | [key: Key | Key[], options?: ActualOptions]
       | [key: string | string[], options: TOpt & $Dictionary & { defaultValue: DefaultValue }]
       | [key: string | string[], defaultValue: DefaultValue, options?: TOpt & $Dictionary]
+      | _KeyAndOptions<Key, $NoInfer<Ret>, ActualOptions>
   ): TFunctionReturnOptionalDetails<TFunctionProcessReturnValue<$NoInfer<Ret>, DefaultValue>, TOpt>;
 }
 
@@ -596,10 +837,13 @@ interface TFunctionSelector<Ns extends Namespace, KPrefix, Source> extends Brand
     const Opts extends SelectorOptions<Ns[number]> = SelectorOptions<Ns[number]>,
   >(
     selectors: Fns,
-    options?: Opts &
-      InterpolationMap<
-        DeepUnwrapPlural<Fns[number] extends (...args: any[]) => infer R ? R : never>
-      >,
+    ...args: _SelectorOptionsArg<
+      DeepUnwrapPlural<Fns[number] extends (...args: any[]) => infer R ? R : never>,
+      Opts &
+        InterpolationMap<
+          DeepUnwrapPlural<Fns[number] extends (...args: any[]) => infer R ? R : never>
+        >
+    >
   ): SelectorReturn<Fns[number] extends (...args: any[]) => infer R ? R : never, Opts>;
 
   // ── Single selector with context + returnObjects ────────────────────────────
@@ -667,7 +911,7 @@ interface TFunctionSelector<Ns extends Namespace, KPrefix, Source> extends Brand
     selector: Fn,
     ...args: ReturnType<Fn> extends PluralValue<string>
       ? [options: Opts & { count: number } & InterpolationMap<DeepUnwrapPlural<ReturnType<Fn>>>]
-      : [options?: Opts & InterpolationMap<ReturnType<Fn>>]
+      : _SelectorOptionsArg<ReturnType<Fn>, Opts & InterpolationMap<ReturnType<Fn>>>
   ): SelectorReturn<ReturnType<Fn>, Opts>;
 }
 
@@ -751,26 +995,97 @@ type _DefinedContextKeys<T, Pattern extends string> = {
   [P in keyof T as P extends Pattern ? ([T[P]] extends [undefined] ? never : P) : never]: true;
 };
 
-type _HasContextVariant<T, K extends string, Context> = [
-  keyof _DefinedContextKeys<
-    T,
-    | `${K}${_ContextSeparator}${Context & string}`
-    | `${K}${_ContextSeparator}${Context & string}${_PluralSeparator}${PluralSuffix}`
-  >,
+/**
+ * Keys of T whose value is not `undefined` (JSON-union phantoms are typed as
+ * optional `undefined`), built once per object.
+ */
+type _DefinedKeys<T> = [T] extends [unknown]
+  ? keyof { [P in keyof T as [T[P]] extends [undefined] ? never : P]: true }
+  : never;
+
+/**
+ * For every defined key, the prefixes K before each context separator, as
+ * `[all, bases]`: `all` has every K with a defined key `${K}${_ContextSeparator}...`,
+ * `bases` only those where the rest is not just a plural suffix. Jumps from one
+ * separator occurrence to the next (so the recursion depth is the number of
+ * separators, not the key length, which can be a whole sentence) and resumes one
+ * character after the match, so overlapping occurrences (`a___b` with `__`) count.
+ */
+type _ContextPrefixesOf<
+  P,
+  Head extends string = '',
+  All = never,
+  Bases = never,
+> = P extends `${infer B}${_ContextSeparator}${string}`
+  ? P extends `${B}${infer FromSep}`
+    ? FromSep extends `${infer C}${infer Rest}`
+      ? _ContextPrefixesOf<
+          Rest,
+          `${Head}${B}${C}`,
+          All | `${Head}${B}`,
+          FromSep extends
+            | `${_PluralSeparator}${PluralSuffix}`
+            | `${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`
+            ? Bases
+            : Bases | `${Head}${B}`
+        >
+      : [All, Bases]
+    : [All, Bases]
+  : [All, Bases];
+
+/**
+ * The context prefixes of an object, built once per object (conditional type
+ * instantiations are cached): scanning all keys for every key was quadratic
+ * in the object size, TS2589 at about 1,000 keys with context variants.
+ */
+type _ContextPrefixes<T> = [T] extends [unknown]
+  ? _ContextPrefixesOf<_DefinedKeys<T> & string>
+  : never;
+type _AllContextPrefixes<T> = [T] extends [unknown] ? _ContextPrefixes<T>[0] : never;
+type _ContextBases<T> = [T] extends [unknown] ? _ContextPrefixes<T>[1] : never;
+
+/** Whether a string type is a single literal (not `string` or a `${string}` pattern). */
+type _IsLiteral<S extends PropertyKey> = {} extends Record<S, unknown> ? false : true;
+
+/**
+ * Whether T has a defined key matching Pattern: literal keys are looked up, a
+ * pattern with a wide member scans the keys.
+ */
+type _HasDefinedKey<T, Pattern extends string> = [
+  false extends (Pattern extends unknown ? _IsLiteral<Pattern> : never)
+    ? keyof _DefinedContextKeys<T, Pattern>
+    : Extract<Pattern, _DefinedKeys<T>>,
 ] extends [never]
   ? false
   : true;
 
+type _HasContextVariant<T, K extends string, Context> = string extends Context
+  ? _IsLiteral<K> extends true
+    ? K extends _AllContextPrefixes<T>
+      ? true
+      : false
+    : _HasDefinedKey<T, `${K}${_ContextSeparator}${string}`>
+  : _HasDefinedKey<
+      T,
+      | `${K}${_ContextSeparator}${Context & string}`
+      | `${K}${_ContextSeparator}${Context & string}${_PluralSeparator}${PluralSuffix}`
+    >;
+
 /** Checks whether key K has **any** context variant in T (excluding pure plural suffixes). */
-type _IsContextualKey<T, K extends string> = [
-  Exclude<
-    keyof _DefinedContextKeys<T, `${K}${_ContextSeparator}${string}`>,
-    | `${K}${_PluralSeparator}${PluralSuffix}`
-    | `${K}${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`
-  >,
-] extends [never]
-  ? false
-  : true;
+type _IsContextualKey<T, K extends string> =
+  _IsLiteral<K> extends true
+    ? K extends _ContextBases<T>
+      ? true
+      : false
+    : [
+          Exclude<
+            keyof _DefinedContextKeys<T, `${K}${_ContextSeparator}${string}`>,
+            | `${K}${_PluralSeparator}${PluralSuffix}`
+            | `${K}${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`
+          >,
+        ] extends [never]
+      ? false
+      : true;
 
 /**
  * Distributes {@link FilterKeysObject} over unions so heterogeneous JSON array