@browsery/i18next - npm Package Compare versions

Comparing version 0.7.2 to 23.8.2

index.d.ts

 // Internal Helpers
-import type { $Dictionary } from './typescript/helpers.d.ts';
+import type { $Dictionary, $NormalizeIntoArray } from './typescript/helpers.js';
 import type {
@@ -14,6 +14,5 @@ DefaultNamespace,
   TOptions,
-} from './typescript/options.d.ts';
+} from './typescript/options.js';
+import type { KeyPrefix, TFunction } from './typescript/t.js';
 
-import type { KeyPrefix, TFunction } from './typescript/t.d.ts';
-
 export interface WithT<Ns extends Namespace = DefaultNamespace> {
@@ -36,2 +35,3 @@ // Expose parameterized t in the i18next interface hierarchy
   public data: Resource;
+
   public options: InitOptions;
@@ -43,2 +43,3 @@
   on(event: 'added' | 'removed', callback: (lng: string, ns: string) => void): void;
+
   /**
@@ -98,5 +99,5 @@ * Remove event listener
  */
-export interface BackendModule<TOptions = object> extends Module {
+export interface BackendModule<Options = object> extends Module {
   type: 'backend';
-  init(services: Services, backendOptions: TOptions, i18nextOptions: InitOptions): void;
+  init(services: Services, backendOptions: Options, i18nextOptions: InitOptions): void;
   read(language: string, namespace: string, callback: ReadCallback): void;
@@ -143,3 +144,3 @@ /** Save the missing translation */
   init?(services: Services, detectorOptions: object, i18nextOptions: InitOptions): void;
-  /** Must call callback passing detected language or return a Promise*/
+  /** Must call callback passing detected language or return a Promise */
   detect(
@@ -224,5 +225,18 @@ callback: (lng: string | readonly string[] | undefined) => void | undefined,
 
-export interface i18n {
+export interface CustomInstanceExtensions {}
+
+// Used just here to exclude `DefaultNamespace` which can be both string or array from `FlatNamespace`
+// in TFunction declaration below.
+// Due to this only very special usage I'm not moving this inside helpers.
+type InferArrayValuesElseReturnType<T> = T extends (infer A)[] ? A : T;
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface i18n extends CustomInstanceExtensions {
   // Expose parameterized t in the i18next interface hierarchy
-  t: TFunction<[DefaultNamespace, ...Exclude<FlatNamespace, DefaultNamespace>[]]>;
+  t: TFunction<
+    [
+      ...$NormalizeIntoArray<DefaultNamespace>,
+      ...Exclude<FlatNamespace, InferArrayValuesElseReturnType<DefaultNamespace>>[],
+    ]
+  >;
 
@@ -498,2 +512,12 @@ /**
   /**
+   * Store was initialized
+   */
+  initializedStoreOnce: boolean;
+
+  /**
+   * Language was initialized
+   */
+  initializedLanguageOnce: boolean;
+
+  /**
    * Emit event
@@ -504,4 +528,5 @@ */
 
-export type * from './typescript/options.d.ts';
+export type * from './typescript/options.js';
 export type {
+  // we need to explicitely export some types, to prevent some issues with next-i18next and interpolation variable validation, etc...
   FallbackLngObjList,
@@ -524,4 +549,4 @@ FallbackLng,
   FlatNamespace,
-} from './typescript/options.d.ts';
-export type * from './typescript/t.d.ts';
+} from './typescript/options.js';
+export type * from './typescript/t.js';
 export type {
@@ -533,3 +558,3 @@ TFunction,
   KeyPrefix,
-} from './typescript/t.d.ts';
+} from './typescript/t.js';
 
@@ -536,0 +561,0 @@ declare const i18next: i18n;

package.json

 {
   "name": "@browsery/i18next",
-  "version": "0.7.2",
+  "version": "23.8.2",
   "description": "Browser compatible i18next module",
@@ -5,0 +5,0 @@ "author": "Panates",

typescript/helpers.d.ts

@@ -0,5 +1,15 @@
+// Types
+
+export type $Dictionary<T = unknown> = { [key: string]: T };
+
+export type $SpecialObject = object | Array<string | object>;
+
+// Types Operators
+
 export type $MergeBy<T, K> = Omit<T, keyof K> & K;
-export type $Dictionary<T = unknown> = { [key: string]: T };
+
 export type $OmitArrayKeys<Arr> = Arr extends readonly any[] ? Omit<Arr, keyof any[]> : Arr;
+
 export type $PreservedValue<Value, Fallback> = [Value] extends [never] ? Fallback : Value;
-export type $SpecialObject = object | Array<string | object>;
+
+export type $NormalizeIntoArray<T extends unknown | readonly unknown[]> = T extends readonly unknown[] ? T : [T];

typescript/options.d.ts

@@ -1,2 +0,2 @@
-import type { $MergeBy, $PreservedValue, $Dictionary } from './helpers.d.ts';
+import type { $MergeBy, $PreservedValue, $Dictionary } from './helpers.js';
 
@@ -43,2 +43,7 @@ /**
     /**
+     * Allows empty string as valid translation
+     */
+    returnEmptyString: true;
+
+    /**
      * Allows objects as valid translation result
@@ -142,3 +147,3 @@ */
   lng?: string,
-  options?: InterpolationOptions & $Dictionary,
+  options?: InterpolationOptions & $Dictionary<any>,
 ) => string;
@@ -145,0 +150,0 @@

typescript/t.d.ts

@@ -1,2 +0,2 @@
-import type { $OmitArrayKeys, $PreservedValue, $Dictionary, $SpecialObject } from './helpers.d.ts';
+import type { $OmitArrayKeys, $PreservedValue, $Dictionary, $SpecialObject } from './helpers.js';
 import type {
@@ -8,12 +8,10 @@ TypeOptions,
   TOptions,
-} from './options.d.ts';
+} from './options.js';
 
-type $IsResourcesDefined = [keyof _Resources] extends [never] ? false : true;
-type $ValueIfResourcesDefined<Value, Fallback> = $IsResourcesDefined extends true
-  ? Value
-  : Fallback;
-type $FirstNamespace<Ns extends Namespace> = Ns extends readonly any[] ? Ns[0] : Ns;
+/** @todo consider to replace {} with Record<string, never> */
+/* eslint @typescript-eslint/ban-types: ['error', { types: { "{}": false } }] */
 
 // Type Options
 type _ReturnObjects = TypeOptions['returnObjects'];
+type _ReturnEmptyString = TypeOptions['returnEmptyString'];
 type _ReturnNull = TypeOptions['returnNull'];
@@ -30,7 +28,15 @@ type _KeySeparator = TypeOptions['keySeparator'];
 
+type $IsResourcesDefined = [keyof _Resources] extends [never] ? false : true;
+type $ValueIfResourcesDefined<Value, Fallback> = $IsResourcesDefined extends true
+  ? Value
+  : Fallback;
+type $FirstNamespace<Ns extends Namespace> = Ns extends readonly any[] ? Ns[0] : Ns;
+
 type Resources = $ValueIfResourcesDefined<_Resources, $Dictionary<string>>;
 
-type PluralSuffix = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+type PluralSuffix = _JSONFormat extends 'v4'
+  ? 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'
+  : number | 'plural';
 
-type WithOrWithoutPlural<Key> = _JSONFormat extends 'v4'
+type WithOrWithoutPlural<Key> = _JSONFormat extends 'v4' | 'v3'
   ? Key extends `${infer KeyWithoutOrdinalPlural}${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`
@@ -46,7 +52,7 @@ ? KeyWithoutOrdinalPlural | Key
 
-/******************************************************
+/** ****************************************************
  * Build all keys and key prefixes based on Resources *
- ******************************************************/
+ ***************************************************** */
 type KeysBuilderWithReturnObjects<Res, Key = keyof Res> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary
+  ? Res[Key] extends $Dictionary | readonly unknown[]
     ?
@@ -59,3 +65,3 @@ | JoinKeys<Key, WithOrWithoutPlural<keyof $OmitArrayKeys<Res[Key]>>>
 type KeysBuilderWithoutReturnObjects<Res, Key = keyof $OmitArrayKeys<Res>> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary
+  ? Res[Key] extends $Dictionary | readonly unknown[]
     ? JoinKeys<Key, KeysBuilderWithoutReturnObjects<Res[Key]>>
@@ -82,10 +88,10 @@ : Key
 
-/************************************************************************
+/** **********************************************************************
  * Parse t function keys based on the namespace, options and key prefix *
- ************************************************************************/
-type KeysByTOptions<TOpt extends TOptions> = TOpt['returnObjects'] extends true
+ *********************************************************************** */
+export type KeysByTOptions<TOpt extends TOptions> = TOpt['returnObjects'] extends true
   ? ResourceKeys<true>
   : ResourceKeys;
 
-type NsByTOptions<Ns extends Namespace, TOpt extends TOptions> = TOpt['ns'] extends Namespace
+export type NsByTOptions<Ns extends Namespace, TOpt extends TOptions> = TOpt['ns'] extends Namespace
   ? TOpt['ns']
@@ -133,5 +139,5 @@ : Ns;
 
-/*********************************************************
+/** *******************************************************
  * Parse t function return type and interpolation values *
- *********************************************************/
+ ******************************************************** */
 type ParseInterpolationValues<Ret> =
@@ -152,10 +158,38 @@ Ret extends `${string}${_InterpolationPrefix}${infer Value}${_InterpolationSuffix}${infer Rest}`
   KeyWithPlural = `${Key & string}${_PluralSeparator}${PluralSuffix}`,
+> = Res[(KeyWithPlural | Key) & keyof Res];
+
+type ParseTReturnPluralOrdinal<
+  Res,
+  Key,
   KeyWithOrdinalPlural = `${Key &
     string}${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`,
-> = Res[(KeyWithOrdinalPlural | KeyWithPlural | Key) & keyof Res];
+> = Res[(KeyWithOrdinalPlural | Key) & keyof Res];
 
-type ParseTReturn<Key, Res> = Key extends `${infer K1}${_KeySeparator}${infer RestKey}`
-  ? ParseTReturn<RestKey, Res[K1 & keyof Res]>
-  : ParseTReturnPlural<Res, Key>;
+type ParseTReturnWithFallback<Key, Val> = Val extends ''
+  ? _ReturnEmptyString extends true
+    ? ''
+    : Key
+  : Val extends null
+  ? _ReturnNull extends true
+    ? null
+    : Key
+  : Val;
 
+type ParseTReturn<Key, Res, TOpt extends TOptions = {}> = ParseTReturnWithFallback<
+  Key,
+  Key extends `${infer K1}${_KeySeparator}${infer RestKey}`
+    ? ParseTReturn<RestKey, Res[K1 & keyof Res], TOpt>
+    : // Process plurals only if count is provided inside options
+    TOpt['count'] extends number
+    ? TOpt['ordinal'] extends boolean
+      ? ParseTReturnPluralOrdinal<Res, Key>
+      : ParseTReturnPlural<Res, Key>
+    : // otherwise access plain key without adding plural and ordinal suffixes
+    Res extends readonly unknown[]
+    ? Key extends `${infer NKey extends number}`
+      ? Res[NKey]
+      : never
+    : Res[Key & keyof Res]
+>;
+
 type TReturnOptionalNull = _ReturnNull extends true ? null : never;
@@ -169,3 +203,3 @@ type TReturnOptionalObjects<TOpt extends TOptions> = _ReturnObjects extends true
 
-type KeyWithContext<Key, TOpt extends TOptions> = TOpt['context'] extends string
+export type KeyWithContext<Key, TOpt extends TOptions> = TOpt['context'] extends string
   ? `${Key & string}${_ContextSeparator}${TOpt['context']}`
@@ -182,7 +216,7 @@ : Key;
   ? ActualKey extends `${infer Nsp}${_NsSeparator}${infer RestKey}`
-    ? ParseTReturn<RestKey, Resources[Nsp & keyof Resources]>
-    : ParseTReturn<ActualKey, Resources[$FirstNamespace<ActualNS>]>
+    ? ParseTReturn<RestKey, Resources[Nsp & keyof Resources], TOpt>
+    : ParseTReturn<ActualKey, Resources[$FirstNamespace<ActualNS>], TOpt>
   : DefaultTReturn<TOpt>;
 
-export type TFunctionDetailedResult<T = string> = {
+export type TFunctionDetailedResult<T = string, TOpt extends TOptions = {}> = {
   /**
@@ -208,6 +242,10 @@ * The plain used key
   usedNS: string;
+  /**
+   * The parameters used for interpolation.
+   */
+  usedParams: InterpolationMap<T> & { count?: TOpt['count'] };
 };
 
 type TFunctionReturnOptionalDetails<Ret, TOpt extends TOptions> = TOpt['returnDetails'] extends true
-  ? TFunctionDetailedResult<Ret>
+  ? TFunctionDetailedResult<Ret, TOpt>
   : Ret;
@@ -219,8 +257,7 @@
 
-/**************************
+/** ************************
  * T function declaration *
- **************************/
+ ************************* */
 export interface TFunction<Ns extends Namespace = DefaultNamespace, KPrefix = undefined> {
   $TFunctionBrand: $IsResourcesDefined extends true ? `${$FirstNamespace<Ns>}` : never;
-
   <
@@ -227,0 +264,0 @@ const Key extends ParseKeys<Ns, TOpt, KPrefix> | TemplateStringsArray,

typescript/t.v4.d.ts

@@ -1,2 +0,2 @@
-import type { $OmitArrayKeys, $PreservedValue, $Dictionary, $SpecialObject } from './helpers.d.ts';
+import type { $OmitArrayKeys, $PreservedValue, $Dictionary, $SpecialObject } from './helpers.js';
 import type {
@@ -8,12 +8,7 @@ TypeOptions,
   TOptions,
-} from './options.d.ts';
+} from './options.js';
 
-type $IsResourcesDefined = [keyof _Resources] extends [never] ? false : true;
-type $ValueIfResourcesDefined<Value, Fallback> = $IsResourcesDefined extends true
-  ? Value
-  : Fallback;
-type $FirstNamespace<Ns extends Namespace> = Ns extends readonly any[] ? Ns[0] : Ns;
-
 // Type Options
 type _ReturnObjects = TypeOptions['returnObjects'];
+type _ReturnEmptyString = TypeOptions['returnEmptyString'];
 type _ReturnNull = TypeOptions['returnNull'];
@@ -30,7 +25,18 @@ type _KeySeparator = TypeOptions['keySeparator'];
 
+/** @todo consider to replace {} with Record<string, never> */
+/* eslint @typescript-eslint/ban-types: ['error', { types: { "{}": false } }] */
+
+type $IsResourcesDefined = [keyof _Resources] extends [never] ? false : true;
+type $ValueIfResourcesDefined<Value, Fallback> = $IsResourcesDefined extends true
+  ? Value
+  : Fallback;
+type $FirstNamespace<Ns extends Namespace> = Ns extends readonly any[] ? Ns[0] : Ns;
+
 type Resources = $ValueIfResourcesDefined<_Resources, $Dictionary<string>>;
 
-type PluralSuffix = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+type PluralSuffix = _JSONFormat extends 'v4'
+  ? 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'
+  : number | 'plural';
 
-type WithOrWithoutPlural<Key> = _JSONFormat extends 'v4'
+type WithOrWithoutPlural<Key> = _JSONFormat extends 'v4' | 'v3'
   ? Key extends `${infer KeyWithoutOrdinalPlural}${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`
@@ -46,7 +52,7 @@ ? KeyWithoutOrdinalPlural | Key
 
-/******************************************************
+/** ****************************************************
  * Build all keys and key prefixes based on Resources *
- ******************************************************/
+ ***************************************************** */
 type KeysBuilderWithReturnObjects<Res, Key = keyof Res> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary
+  ? Res[Key] extends $Dictionary | readonly unknown[]
     ?
@@ -59,3 +65,3 @@ | JoinKeys<Key, WithOrWithoutPlural<keyof $OmitArrayKeys<Res[Key]>>>
 type KeysBuilderWithoutReturnObjects<Res, Key = keyof $OmitArrayKeys<Res>> = Key extends keyof Res
-  ? Res[Key] extends $Dictionary
+  ? Res[Key] extends $Dictionary | readonly unknown[]
     ? JoinKeys<Key, KeysBuilderWithoutReturnObjects<Res[Key]>>
@@ -82,10 +88,10 @@ : Key
 
-/************************************************************************
+/** **********************************************************************
  * Parse t function keys based on the namespace, options and key prefix *
- ************************************************************************/
-type KeysByTOptions<TOpt extends TOptions> = TOpt['returnObjects'] extends true
+ *********************************************************************** */
+export type KeysByTOptions<TOpt extends TOptions> = TOpt['returnObjects'] extends true
   ? ResourceKeys<true>
   : ResourceKeys;
 
-type NsByTOptions<Ns extends Namespace, TOpt extends TOptions> = TOpt['ns'] extends Namespace
+export type NsByTOptions<Ns extends Namespace, TOpt extends TOptions> = TOpt['ns'] extends Namespace
   ? TOpt['ns']
@@ -106,14 +112,16 @@ : Ns;
 
+// this seems not to work for ts < 4.7.2
+// type ParseKeysByFallbackNs<Keys extends $Dictionary> = _FallbackNamespace extends false
+//   ? never
+//   : _FallbackNamespace extends (infer UnionFallbackNs extends string)[]
+//     ? Keys[UnionFallbackNs]
+//     : Keys[_FallbackNamespace & string];
+// so let's try this:
+type First<T> = T extends [infer U, ...any[]] ? U : any;
 type ParseKeysByFallbackNs<Keys extends $Dictionary> = _FallbackNamespace extends false
   ? never
-  : _FallbackNamespace extends (infer UnionFallbackNs extends string)[]
-  ? Keys[UnionFallbackNs]
-  : Keys[_FallbackNamespace & string];
+  : _FallbackNamespace extends string
+  ? Keys[_FallbackNamespace & string]
+  : Keys[First<_FallbackNamespace>];
 
-type FilterKeysByContext<Keys, TOpt extends TOptions> = TOpt['context'] extends string
-  ? Keys extends `${infer Prefix}${_ContextSeparator}${TOpt['context']}${infer Suffix}`
-    ? `${Prefix}${Suffix}`
-    : never
-  : Keys;
-
 export type ParseKeys<
@@ -126,13 +134,11 @@ Ns extends Namespace = DefaultNamespace,
 > = $IsResourcesDefined extends true
-  ? FilterKeysByContext<
+  ?
       | ParseKeysByKeyPrefix<Keys[$FirstNamespace<ActualNS>], KPrefix>
       | ParseKeysByNamespaces<ActualNS, Keys>
-      | ParseKeysByFallbackNs<Keys>,
-      TOpt
-    >
+      | ParseKeysByFallbackNs<Keys>
   : string;
 
-/*********************************************************
+/** *******************************************************
  * Parse t function return type and interpolation values *
- *********************************************************/
+ ******************************************************** */
 type ParseInterpolationValues<Ret> =
@@ -153,10 +159,38 @@ Ret extends `${string}${_InterpolationPrefix}${infer Value}${_InterpolationSuffix}${infer Rest}`
   KeyWithPlural = `${Key & string}${_PluralSeparator}${PluralSuffix}`,
+> = Res[(KeyWithPlural | Key) & keyof Res];
+
+type ParseTReturnPluralOrdinal<
+  Res,
+  Key,
   KeyWithOrdinalPlural = `${Key &
     string}${_PluralSeparator}ordinal${_PluralSeparator}${PluralSuffix}`,
-> = Res[(KeyWithOrdinalPlural | KeyWithPlural | Key) & keyof Res];
+> = Res[(KeyWithOrdinalPlural | Key) & keyof Res];
 
-type ParseTReturn<Key, Res> = Key extends `${infer K1}${_KeySeparator}${infer RestKey}`
-  ? ParseTReturn<RestKey, Res[K1 & keyof Res]>
-  : ParseTReturnPlural<Res, Key>;
+type ParseTReturnWithFallback<Key, Val> = Val extends ''
+  ? _ReturnEmptyString extends true
+    ? ''
+    : Key
+  : Val extends null
+  ? _ReturnNull extends true
+    ? null
+    : Key
+  : Val;
 
+type ParseTReturn<Key, Res, TOpt extends TOptions = {}> = ParseTReturnWithFallback<
+  Key,
+  Key extends `${infer K1}${_KeySeparator}${infer RestKey}`
+    ? ParseTReturn<RestKey, Res[K1 & keyof Res], TOpt>
+    : // Process plurals only if count is provided inside options
+    TOpt['count'] extends number
+    ? TOpt['ordinal'] extends boolean
+      ? ParseTReturnPluralOrdinal<Res, Key>
+      : ParseTReturnPlural<Res, Key>
+    : // otherwise access plain key without adding plural and ordinal suffixes
+    Res extends readonly unknown[]
+    ? Key extends `${infer NKey extends number}`
+      ? Res[NKey]
+      : never
+    : Res[Key & keyof Res]
+>;
+
 type TReturnOptionalNull = _ReturnNull extends true ? null : never;
@@ -170,3 +204,3 @@ type TReturnOptionalObjects<TOpt extends TOptions> = _ReturnObjects extends true
 
-type KeyWithContext<Key, TOpt extends TOptions> = TOpt['context'] extends string
+export type KeyWithContext<Key, TOpt extends TOptions> = TOpt['context'] extends string
   ? `${Key & string}${_ContextSeparator}${TOpt['context']}`
@@ -183,7 +217,7 @@ : Key;
   ? ActualKey extends `${infer Nsp}${_NsSeparator}${infer RestKey}`
-    ? ParseTReturn<RestKey, Resources[Nsp & keyof Resources]>
-    : ParseTReturn<ActualKey, Resources[$FirstNamespace<ActualNS>]>
+    ? ParseTReturn<RestKey, Resources[Nsp & keyof Resources], TOpt>
+    : ParseTReturn<ActualKey, Resources[$FirstNamespace<ActualNS>], TOpt>
   : DefaultTReturn<TOpt>;
 
-export type TFunctionDetailedResult<T = string> = {
+export type TFunctionDetailedResult<T = string, TOpt extends TOptions = {}> = {
   /**
@@ -209,6 +243,10 @@ * The plain used key
   usedNS: string;
+  /**
+   * The parameters used for interpolation.
+   */
+  usedParams: InterpolationMap<T> & { count?: TOpt['count'] };
 };
 
 type TFunctionReturnOptionalDetails<Ret, TOpt extends TOptions> = TOpt['returnDetails'] extends true
-  ? TFunctionDetailedResult<Ret>
+  ? TFunctionDetailedResult<Ret, TOpt>
   : Ret;
@@ -220,5 +258,5 @@
 
-/**************************
+/** ************************
  * T function declaration *
- **************************/
+ ************************* */
 export interface TFunction<Ns extends Namespace = DefaultNamespace, KPrefix = undefined> {
@@ -225,0 +263,0 @@ $TFunctionBrand: $IsResourcesDefined extends true ? `${$FirstNamespace<Ns>}` : never;

Fixed alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

247650

increased by6.25%

Lines of code

6778

increased by6.51%

Number of low quality alerts

1

decreased by-50%

No dependency changes