i18next 21.9.2 → 22.0.0

package/index.d.ts

@@ -1,21 +1,126 @@
-type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
+// Helpers
 type MergeBy<T, K> = Omit<T, keyof K> & K;
+type StringMap = { [key: string]: any };
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void
+  ? I
+  : never;
+type LastOf<T> = UnionToIntersection<T extends any ? () => T : never> extends () => infer R
+  ? R
+  : never;
 
-export interface FallbackLngObjList {
-  [language: string]: readonly string[];
-}
+/**
+ * This interface can be augmented by users to add types to `i18next` default TypeOptions.
+ */
+export interface CustomTypeOptions {}
 
-export type FallbackLng =
-  | string
-  | readonly string[]
-  | FallbackLngObjList
-  | ((code: string) => string | readonly string[] | FallbackLngObjList);
+/**
+ * This interface can be augmented by users to add types to `i18next` default PluginOptions.
+ *
+ * Usage:
+ * ```ts
+ * // react-i18next.d.ts
+ * import 'react-i18next';
+ * declare module 'react-i18next' {
+ *   interface CustomTypeOptions {
+ *     defaultNS: 'custom';
+ *     returnNull: false;
+ *     returnEmptyString: false;
+ *     nsSeparator: ':';
+ *     keySeparator: '.';
+ *     jsonFormat: 'v4';
+ *     allowObjectInHTMLChildren: false;
+ *     resources: {
+ *       custom: {
+ *         foo: 'foo';
+ *       };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface CustomPluginOptions {}
+
+export type TypeOptions = MergeBy<
+  {
+    /**
+     * Allows null values as valid translation
+     */
+    returnNull: true;
+
+    /**
+     * Allows empty string as valid translation
+     */
+    returnEmptyString: true;
+
+    /**
+     * Char to separate keys
+     */
+    keySeparator: '.';
+
+    /**
+     * Char to split namespace from key
+     */
+    nsSeparator: ':';
+
+    /**
+     * Default namespace used if not passed to translation function
+     */
+    defaultNS: 'translation';
+
+    /**
+     * Json Format Version - V4 allows plural suffixes
+     */
+    jsonFormat: 'v4';
 
-export type FormatFunction = (
+    /**
+     * Resources to initialize with
+     */
+    resources: object;
+
+    /**
+     * Flag that allows HTML elements to receive objects. This is only useful for React applications
+     * where you pass objects to HTML elements so they can be replaced to their respective interpolation
+     * values (mostly with Trans component)
+     */
+    allowObjectInHTMLChildren: false;
+  },
+  CustomTypeOptions
+>;
+
+export type PluginOptions = MergeBy<
+  {
+    /**
+     * Options for language detection - check documentation of plugin
+     * @default undefined
+     */
+    detection?: object;
+
+    /**
+     * Options for backend - check documentation of plugin
+     * @default undefined
+     */
+    backend?: object;
+
+    /**
+     * Options for cache layer - check documentation of plugin
+     * @default undefined
+     */
+    cache?: object;
+
+    /**
+     * Options for i18n message format - check documentation of plugin
+     * @default undefined
+     */
+    i18nFormat?: object;
+  },
+  CustomPluginOptions
+>;
+
+type FormatFunction = (
   value: any,
   format?: string,
   lng?: string,
-  options?: InterpolationOptions & { [key: string]: any },
+  options?: InterpolationOptions & StringMap,
 ) => string;
 
 export interface InterpolationOptions {
@@ -124,6 +229,16 @@ export interface InterpolationOptions {
   skipOnVariables?: boolean;
 }
 
+export interface FallbackLngObjList {
+  [language: string]: readonly string[];
+}
+
+export type FallbackLng =
+  | string
+  | readonly string[]
+  | FallbackLngObjList
+  | ((code: string) => string | readonly string[] | FallbackLngObjList);
+
 export interface ReactOptions {
   /**
    * Set it to fallback to let passed namespaces to translated hoc act as fallbacks
@@ -191,38 +306,7 @@ export interface ReactOptions {
   unescape?(str: string): string;
 }
 
-/**
- * This interface can be augmented by users to add types to `i18next` default PluginOptions.
- */
-export interface PluginOptions {}
-
-interface DefaultPluginOptions {
-  /**
-   * Options for language detection - check documentation of plugin
-   * @default undefined
-   */
-  detection?: object;
-
-  /**
-   * Options for backend - check documentation of plugin
-   * @default undefined
-   */
-  backend?: object;
-
-  /**
-   * Options for cache layer - check documentation of plugin
-   * @default undefined
-   */
-  cache?: object;
-
-  /**
-   * Options for i18n message format - check documentation of plugin
-   * @default undefined
-   */
-  i18nFormat?: object;
-}
-
-export interface InitOptions extends MergeBy<DefaultPluginOptions, PluginOptions> {
+export interface InitOptions extends PluginOptions {
   /**
    * Logs info level to console output. Helps finding issues with loading not working.
    * @default false
@@ -627,37 +711,87 @@ export interface TOptionsBase {
   interpolation?: InterpolationOptions;
 }
 
-/**
- * indexer that is open to any value
- */
-export type StringMap = { [key: string]: any };
-
 /**
  * Options that allow open ended values for interpolation unless type is provided.
  */
 export type TOptions<TInterpolationMap extends object = StringMap> = TOptionsBase &
   TInterpolationMap;
 
-export type Callback = (error: any, t: TFunction) => void;
-
-/**
- * Uses similar args as the t function and returns true if a key exists.
- */
-export interface ExistsFunction<
-  TKeys extends string = string,
-  TInterpolationMap extends object = StringMap,
-> {
-  (key: TKeys | TKeys[], options?: TOptions<TInterpolationMap>): boolean;
-}
-
-export interface WithT {
+type FallbackOrNS<F, T = keyof Resources> = [T] extends [never] ? F : T;
+
+type Resources = TypeOptions['resources'];
+type DefaultNamespace = TypeOptions['defaultNS'];
+
+export type Namespace<T = FallbackOrNS<string>> = T | T[];
+
+type PluralSuffix = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+
+type WithOrWithoutPlural<K> = TypeOptions['jsonFormat'] extends 'v4'
+  ? K extends `${infer B}_${PluralSuffix}`
+    ? B | K
+    : K
+  : K;
+
+// Normalize single namespace
+export type KeysWithSeparator<K1, K2, S extends string = TypeOptions['keySeparator']> = `${K1 &
+  string}${S}${K2 & string}`;
+type KeysWithSeparator2<K1, K2> = KeysWithSeparator<K1, Exclude<K2, keyof any[]>>;
+type Normalize2<T, K = keyof T> = K extends keyof T
+  ? T[K] extends StringMap
+    ? T[K] extends readonly any[]
+      ?
+          | KeysWithSeparator2<K, WithOrWithoutPlural<keyof T[K]>>
+          | KeysWithSeparator2<K, Normalize2<T[K]>>
+      :
+          | KeysWithSeparator<K, WithOrWithoutPlural<keyof T[K]>>
+          | KeysWithSeparator<K, Normalize2<T[K]>>
+    : never
+  : never;
+type Normalize<T> = WithOrWithoutPlural<keyof T> | Normalize2<T>;
+
+// Normalize multiple namespaces
+type KeyWithNSSeparator<N, K, S extends string = TypeOptions['nsSeparator']> = `${N &
+  string}${S}${K & string}`;
+type NormalizeMulti<T, U extends keyof T, L = LastOf<U>> = L extends U
+  ? KeyWithNSSeparator<L, Normalize<T[L]>> | NormalizeMulti<T, Exclude<U, L>>
+  : never;
+
+// Normalize single namespace with key prefix
+type NormalizeWithKeyPrefix<
+  T,
+  K,
+  S extends string = TypeOptions['keySeparator'],
+> = K extends `${infer K1}${S}${infer K2}`
+  ? K1 extends keyof T
+    ? NormalizeWithKeyPrefix<T[K1], K2>
+    : never
+  : K extends keyof T
+  ? T[K] extends string
+    ? never
+    : Normalize<T[K]>
+  : never;
+
+export type KeyPrefix<N extends Namespace> =
+  | (N extends keyof Resources ? Normalize<Resources[N]> : string)
+  | undefined;
+
+export type TFuncKey<
+  N extends Namespace = DefaultNamespace,
+  TKPrefix = undefined,
+  T = Resources,
+> = N extends (keyof T)[] | Readonly<(keyof T)[]>
+  ? NormalizeMulti<T, N[number]>
+  : N extends keyof T
+  ? TKPrefix extends undefined
+    ? Normalize<T[N]>
+    : NormalizeWithKeyPrefix<T[N], TKPrefix>
+  : string;
+
+export interface WithT<N extends Namespace = DefaultNamespace> {
   // Expose parameterized t in the i18next interface hierarchy
-  t: TFunction;
+  t: TFunction<N>;
 }
 
-/**
- * Object returned from t() function when passed returnDetails: true option.
- */
 export type TFunctionDetailedResult<T = string> = {
   /**
    * The plain used key
@@ -680,65 +814,102 @@ export type TFunctionDetailedResult<T = string> = {
    */
   usedNS: string;
 };
-export type TFunctionResult =
+
+type TypeOptionsFallback<TranslationValue, Option, MatchingValue> = Option extends false
+  ? TranslationValue extends MatchingValue
+    ? string
+    : TranslationValue
+  : TranslationValue;
+
+/**
+ * Checks if user has enabled `returnEmptyString` and `returnNull` options to retrieve correct values.
+ */
+export type NormalizeByTypeOptions<
+  TranslationValue,
+  R = TypeOptionsFallback<TranslationValue, TypeOptions['returnEmptyString'], ''>,
+> = TypeOptionsFallback<R, TypeOptions['returnNull'], null>;
+
+type StringIfPlural<T> = TypeOptions['jsonFormat'] extends 'v4'
+  ? T extends `${string}_${PluralSuffix}`
+    ? string
+    : never
+  : never;
+
+type NormalizeReturn<
+  T,
+  V,
+  S extends string | false = TypeOptions['keySeparator'],
+> = V extends keyof T
+  ? NormalizeByTypeOptions<T[V]>
+  : S extends false
+  ? V
+  : V extends `${infer K}${S}${infer R}`
+  ? K extends keyof T
+    ? NormalizeReturn<T[K], R>
+    : never
+  : StringIfPlural<keyof T>;
+
+type NormalizeMultiReturn<T, V> = V extends `${infer N}:${infer R}`
+  ? N extends keyof T
+    ? NormalizeReturn<T[N], R>
+    : never
+  : never;
+
+export type DefaultTFuncReturn =
   | string
   | object
   | TFunctionDetailedResult
   | Array<string | object>
   | undefined
   | null;
-export type TFunctionKeys = string | TemplateStringsArray;
-export interface TFunction {
-  // basic usage
-  <
-    TResult extends TFunctionResult = string,
-    TKeys extends TFunctionKeys = string,
-    TInterpolationMap extends object = StringMap,
-  >(
-    key: TKeys | TKeys[],
-  ): TResult;
+
+export type TFuncReturn<
+  N,
+  TKeys,
+  TDefaultResult,
+  TKPrefix = undefined,
+  T = Resources,
+> = N extends (keyof T)[]
+  ? NormalizeMultiReturn<T, TKeys>
+  : N extends keyof T
+  ? TKPrefix extends undefined
+    ? NormalizeReturn<T[N], TKeys>
+    : NormalizeReturn<T[N], KeysWithSeparator<TKPrefix, TKeys>>
+  : TDefaultResult;
+
+export interface TFunction<N extends Namespace = DefaultNamespace, TKPrefix = undefined> {
   <
-    TResult extends TFunctionResult = TFunctionDetailedResult<object>,
-    TKeys extends TFunctionKeys = string,
+    TKeys extends TFuncKey<N, TKPrefix> | TemplateStringsArray extends infer A ? A : never,
+    TDefaultResult extends DefaultTFuncReturn,
     TInterpolationMap extends object = StringMap,
   >(
     key: TKeys | TKeys[],
-    options?: TOptions<TInterpolationMap> & { returnDetails: true; returnObjects: true },
-  ): TResult;
+  ): TFuncReturn<N, TKeys, TDefaultResult, TKPrefix>;
   <
-    TResult extends TFunctionResult = TFunctionDetailedResult,
-    TKeys extends TFunctionKeys = string,
+    TKeys extends TFuncKey<N, TKPrefix> | TemplateStringsArray extends infer A ? A : never,
+    TDefaultResult extends DefaultTFuncReturn,
     TInterpolationMap extends object = StringMap,
   >(
     key: TKeys | TKeys[],
     options?: TOptions<TInterpolationMap> & { returnDetails: true },
-  ): TResult;
-  <
-    TResult extends TFunctionResult = object,
-    TKeys extends TFunctionKeys = string,
-    TInterpolationMap extends object = StringMap,
-  >(
-    key: TKeys | TKeys[],
-    options?: TOptions<TInterpolationMap> & { returnObjects: true },
-  ): TResult;
+  ): TFunctionDetailedResult<TFuncReturn<N, TKeys, TDefaultResult, TKPrefix>>;
   <
-    TResult extends TFunctionResult = string,
-    TKeys extends TFunctionKeys = string,
+    TKeys extends TFuncKey<N, TKPrefix> | TemplateStringsArray extends infer A ? A : never,
+    TDefaultResult extends DefaultTFuncReturn,
     TInterpolationMap extends object = StringMap,
   >(
     key: TKeys | TKeys[],
-    options?: TOptions<TInterpolationMap> | string,
-  ): TResult;
-  // overloaded usage
+    options?: TOptions<TInterpolationMap>,
+  ): TFuncReturn<N, TKeys, TDefaultResult, TKPrefix>;
   <
-    TResult extends TFunctionResult = string,
-    TKeys extends TFunctionKeys = string,
+    TKeys extends TFuncKey<N, TKPrefix> | TemplateStringsArray extends infer A ? A : never,
+    TDefaultResult extends DefaultTFuncReturn,
     TInterpolationMap extends object = StringMap,
   >(
     key: TKeys | TKeys[],
     defaultValue?: string,
     options?: TOptions<TInterpolationMap> | string,
-  ): TResult;
+  ): TFuncReturn<N, TKeys, TDefaultResult, TKPrefix>;
 }
 
 export interface Resource {
@@ -920,14 +1091,25 @@ export interface Modules {
 export interface Newable<T> {
   new (...args: any[]): T;
 }
-
 export interface NewableModule<T extends Module> extends Newable<T> {
   type: T['type'];
 }
 
+type Callback = (error: any, t: TFunction) => void;
+
+/**
+ * Uses similar args as the t function and returns true if a key exists.
+ */
+export interface ExistsFunction<
+  TKeys extends string = string,
+  TInterpolationMap extends object = StringMap,
+> {
+  (key: TKeys | TKeys[], options?: TOptions<TInterpolationMap>): boolean;
+}
+
 export interface i18n {
   // Expose parameterized t in the i18next interface hierarchy
-  t: TFunction;
+  t: TFunction<FallbackOrNS<string>[]>;
 
   /**
    * The default of the i18next module is an i18next instance ready to be initialized by calling init.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18next",
-  "version": "21.9.2",
+  "version": "22.0.0",
   "description": "i18next internationalization framework",
   "main": "./dist/cjs/i18next.js",
   "module": "./dist/esm/i18next.js",
@@ -98,15 +98,16 @@
     "rollup-plugin-terser": "^4.0.4",
     "sinon": "11.1.2",
     "tslint": "^5.12.1",
-    "typescript": "^3.6.4",
+    "typescript": "^4.7.4",
     "watchify": "3.9.0"
   },
   "scripts": {
-    "pretest": "npm run test:typescript && npm run test:typescript:noninterop",
+    "pretest": "npm run test:typescript && npm run test:custom-typescript && npm run test:typescript:noninterop",
     "test": "npm run test:new && npm run test:compat",
     "test:new": "karma start karma.conf.js --singleRun",
     "test:compat": "karma start karma.backward.conf.js --singleRun",
     "test:typescript": "tslint --project tsconfig.json",
+    "test:custom-typescript": "tslint --project test/typescript/custom-types/tsconfig.json",
     "test:typescript:noninterop": "tslint --project tsconfig.nonEsModuleInterop.json",
     "tdd": "karma start karma.conf.js",
     "tdd:compat": "karma start karma.backward.conf.js",