@tolgee/core 5.33.2 → 5.33.3-prerelease.2efc0e6b.0

package/lib/TolgeeCore.d.ts

@@ -4,20 +4,6 @@ declare function createTolgee(options: TolgeeOptions): Readonly<{
      * Listen to tolgee events.
      */
     on: import("./types").TolgeeOn<keyof import("./types").EventType>;
-    /**
-     * Listen for specific namespaces changes.
-     *
-     * ```
-     * const sub = tolgee.onUpdate(handler)
-     *
-     * // subscribe to selected namespace
-     * sub.subscribeNs(['common'])
-     *
-     * // unsubscribe
-     * sub.unsubscribe()
-     * ```
-     */
-    onNsUpdate: (handler: import("./types").Listener<undefined>) => import("./types").SubscriptionSelective;
     /**
      * Turn off/on events emitting. Is on by default.
      */
@@ -44,7 +30,9 @@ declare function createTolgee(options: TolgeeOptions): Readonly<{
      * @return object with revert method.
      */
     changeTranslation: (descriptor: import("./types").CacheDescriptor, key: string, value: string) => {
-        revert(): void;
+        revert(): void; /**
+         * Manually load record from `Backend` (or `DevBackend` when in dev mode)
+         */
     };
     /**
      * Adds namespace(s) list of active namespaces. And if tolgee is running, loads required data.
@@ -57,41 +45,47 @@ declare function createTolgee(options: TolgeeOptions): Readonly<{
      * so this method will remove namespace only if the counter goes down to 0.
      */
     removeActiveNs: (ns: import("./types").NsFallback) => void;
+    /**
+     * Load records which would be loaded by `run` function
+     *
+     * You can provide language if not previously set on tolgee instance
+     */
+    loadRequired: (options?: import("./types").LoadRequiredOptions | undefined) => Promise<import("./types").CacheInternalRecord[]>;
+    /**
+     * Load records in matrix (languages x namespaces)
+     */
+    loadMatrix: (options: import("./types").LoadMatrixOptions) => Promise<import("./types").CacheInternalRecord[]>;
     /**
      * Manually load multiple records from `Backend` (or `DevBackend` when in dev mode)
      *
      * It loads data together and adds them to cache in one operation, to prevent partly loaded state.
      */
-    loadRecords: (descriptors: import("./types").CacheDescriptor[]) => Promise<import("./types").TranslationsFlat[]>;
+    loadRecords: (descriptors: import("./types").CacheDescriptor[], options?: import("./types").LoadOptions | undefined) => Promise<import("./types").CacheInternalRecord[]>;
     /**
      * Manually load record from `Backend` (or `DevBackend` when in dev mode)
      */
-    loadRecord: (descriptor: import("./types").CacheDescriptor) => Promise<import("./types").TranslationsFlat>;
+    loadRecord: (descriptor: import("./types").CacheDescriptor, options?: import("./types").LoadOptions | undefined) => Promise<import("./types").TranslationsFlat>;
     /**
      * Prefill static data
      */
-    addStaticData: (data: import("./types").TolgeeStaticData | undefined) => void;
+    addStaticData: (data: import("./types").TolgeeStaticDataProp | undefined) => void;
     /**
      * Get record from cache.
      */
-    getRecord: (descriptor: import("./types").CacheDescriptor) => import("./types").TranslationsFlat | undefined;
+    getRecord: (descriptor: import("./types").CacheDescriptor) => import("./types").CacheInternalRecord | undefined;
     /**
      * Get all records from cache.
      */
-    getAllRecords: () => {
-        data: import("./types").TranslationsFlat;
-        language: string;
-        namespace: string;
-    }[];
+    getAllRecords: () => (import("./types").CacheInternalRecord | undefined)[];
     /**
      * @param ns optional list of namespaces that you are interested in
      * @return `true` if there are data that need to be fetched.
      */
     isLoaded: (ns?: import("./types").NsFallback) => boolean;
     /**
-     * Returns records needed for instance to be `loaded`
+     * Returns descriptors of records needed for instance to be `loaded`
      */
-    getRequiredRecords: (lang?: string | undefined, ns?: import("./types").NsFallback) => import("./types").CacheDescriptor[];
+    getRequiredDescriptors: (lang?: string | undefined, ns?: import("./types").NsFallback) => import("./types").CacheDescriptorInternal[];
     /**
      * @return `true` if tolgee is loading initial data (triggered by `run`).
      */
@@ -145,8 +139,9 @@ declare function createTolgee(options: TolgeeOptions): Readonly<{
         fallbackLanguage?: import("./types").FallbackLanguageOption;
         ns?: string[] | undefined;
         fallbackNs?: import("./types").FallbackGeneral;
-        defaultNs: string;
-        staticData?: import("./types").TolgeeStaticData | undefined;
+        defaultNs?: string | undefined;
+        availableNs?: string[] | undefined;
+        staticData?: import("./types").TolgeeStaticDataProp | undefined;
         observerType: "invisible" | "text";
         observerOptions: import("./types").ObserverOptionsInternal;
         onFormatError: import("./types").OnFormatError;
@@ -154,6 +149,8 @@ declare function createTolgee(options: TolgeeOptions): Readonly<{
         fetch: import("./types").FetchFn;
         tagNewKeys?: string[] | undefined;
         filterTag?: string[] | undefined;
+        autoLoadRequiredData: boolean;
+        disableCache: boolean;
     };
     /**
      * Tolgee is in dev mode if `DevTools` plugin is used and `apiKey` + `apiUrl` are specified.

package/lib/helpers.d.ts

@@ -1,8 +1,8 @@
-import { FallbackGeneral, FallbackLanguageOption, FetchFn, TolgeeError } from './types';
+import { FallbackGeneral, FallbackLanguageOption, FetchFn, TolgeeError, ErrorEvent } from './types';
 import { EventEmitterInstance } from './Controller/Events/EventEmitter';
 export declare function isPromise(value: unknown): value is Promise<unknown>;
 export declare function valueOrPromise<T, R>(value: T | Promise<T>, callback: (value: T) => R): R | Promise<R>;
-export declare function handleRegularOrAsyncErr<T>(onError: EventEmitterInstance<TolgeeError>, createError: (e: any) => TolgeeError, callback: () => Promise<T> | T): Promise<T> | T;
+export declare function handleRegularOrAsyncErr<T>(onError: EventEmitterInstance<ErrorEvent>, createError: (e: any) => TolgeeError, callback: () => Promise<T> | T): Promise<T> | T;
 export declare function missingOptionError(option: string | string[]): string;
 export declare function isObject(item: any): boolean;
 export declare function getFallback(value: FallbackGeneral): string[] | undefined;

package/lib/types/cache.d.ts

@@ -1,5 +1,5 @@
 export type TranslationValue = string | undefined | null;
-export type TranslationsFlat = Map<string, TranslationValue>;
+export type TranslationsFlat = Record<string, TranslationValue>;
 export type TreeTranslationsData = {
     [key: string]: TranslationValue | TreeTranslationsData;
 };
@@ -23,3 +23,21 @@ export type CachePublicRecord = {
     language: string;
     namespace: string;
 };
+export type CacheInternalRecord = {
+    data: TranslationsFlat;
+    language: string;
+    namespace: string;
+    cacheKey: string;
+};
+export type LoadOptions = {
+    noDev?: boolean;
+    useCache?: boolean;
+};
+export type LoadRequiredOptions = LoadOptions & {
+    language?: string;
+};
+export type MatrixOptions = {
+    languages: string[] | 'all';
+    namespaces: string[] | 'all';
+};
+export type LoadMatrixOptions = LoadOptions & MatrixOptions;

package/lib/types/events.d.ts

@@ -1,23 +1,24 @@
-import type { NsFallback } from './general';
 import type { CacheDescriptorWithKey } from './cache';
 import { TolgeeError } from './errors';
 export type Subscription = {
     unsubscribe: () => void;
 };
-export type SubscriptionSelective = {
-    unsubscribe: () => void;
-    /**
-     * Subscribes to namespace(s)
-     * @param ns - namespace(s), if empty default namespace is used
-     *
-     * Can be used multiple times to subscribe for more.
-     */
-    subscribeNs(ns?: NsFallback): SubscriptionSelective;
-};
-export type ListenerEvent<T> = {
+export type ListenerEvent<E extends string, T> = {
+    type: E;
     value: T;
 };
-export type Listener<T> = (e: ListenerEvent<T>) => void;
+export type Handler<E extends ListenerEvent<string, any>> = (e: E) => void;
+export type CombinedHandler<E extends ListenerEvent<string, any>> = (e: E[]) => void;
+export type LanguageEvent = ListenerEvent<'language', string>;
+export type PendingLanguageEvent = ListenerEvent<'pendingLanguage', string>;
+export type LoadingEvent = ListenerEvent<'loading', boolean>;
+export type FetchingEvent = ListenerEvent<'fetching', boolean>;
+export type InitialLoadEvent = ListenerEvent<'initialLoad', void>;
+export type RunningEvent = ListenerEvent<'running', boolean>;
+export type CacheEvent = ListenerEvent<'cache', CacheDescriptorWithKey>;
+export type ErrorEvent = ListenerEvent<'error', TolgeeError>;
+export type PermanentChangeEvent = ListenerEvent<'permanentChange', TranslationDescriptor>;
+export type UpdateEvent = LanguageEvent | CacheEvent | InitialLoadEvent;
 export type TolgeeEvent = 'language' | 'pendingLanguage' | 'loading' | 'fetching' | 'initialLoad' | 'running' | 'cache' | 'update' | 'permanentChange';
 export interface EventType {
     language: string;
@@ -36,43 +37,43 @@ export type TolgeeOn<E extends keyof EventType = keyof EventType> = {
      * Emitted when any key needs (or might need) to be re-rendered.
      * Similar to tolgee.onNsUpdate, except for all namespaces.
      */
-    (event: 'update', handler: Listener<void>): Subscription;
+    (event: 'update', handler: CombinedHandler<UpdateEvent>): Subscription;
     /**
      * Emitted on language change.
      */
-    (event: 'language', handler: Listener<string>): Subscription;
+    (event: 'language', handler: Handler<LanguageEvent>): Subscription;
     /**
      * Emitted on pendingLanguage change.
      */
-    (event: 'pendingLanguage', handler: Listener<string>): Subscription;
+    (event: 'pendingLanguage', handler: Handler<PendingLanguageEvent>): Subscription;
     /**
      * Emitted on loading change. Changes when tolgee is loading some data for the first time.
      */
-    (event: 'loading', handler: Listener<boolean>): Subscription;
+    (event: 'loading', handler: Handler<LoadingEvent>): Subscription;
     /**
      * Emitted on fetching change. Changes when tolgee is fetching any data.
      */
-    (event: 'fetching', handler: Listener<boolean>): Subscription;
+    (event: 'fetching', handler: Handler<FetchingEvent>): Subscription;
     /**
      * Emitted when `tolgee.run` method finishes.
      */
-    (event: 'initialLoad', handler: Listener<void>): Subscription;
+    (event: 'initialLoad', handler: Handler<InitialLoadEvent>): Subscription;
     /**
      * Emitted when internal `running` state changes.
      */
-    (event: 'running', handler: Listener<boolean>): Subscription;
+    (event: 'running', handler: Handler<RunningEvent>): Subscription;
     /**
      * Emitted when cache changes.
      */
-    (event: 'cache', handler: Listener<CacheDescriptorWithKey>): Subscription;
+    (event: 'cache', handler: Handler<CacheEvent>): Subscription;
     /**
      * Emitted on errors
      */
-    (event: 'error', handler: Listener<TolgeeError>): Subscription;
+    (event: 'error', handler: Handler<ErrorEvent>): Subscription;
     /**
      * Translation was changed or created via dev tools
      */
-    (event: 'permanentChange', handler: Listener<CacheDescriptorWithKey>): Subscription;
+    (event: 'permanentChange', handler: Handler<PermanentChangeEvent>): Subscription;
     (event: E, handler: unknown): Subscription;
 };
 export type TranslationDescriptor = {

package/lib/types/index.d.ts

@@ -3,6 +3,6 @@ export * from './events';
 export * from './cache';
 export * from './plugin';
 export * from './errors';
-export type { State, TolgeeOptions, TolgeeOptionsInternal, TolgeeStaticData, } from '../Controller/State/initState';
+export type { State, TolgeeOptions, TolgeeOptionsInternal, TolgeeStaticData, TolgeeStaticDataProp, } from '../Controller/State/initState';
 export type { ObserverOptions, ObserverOptionsInternal, ModifierKey, } from '../Controller/State/observerOptions';
 export type { TolgeeChainer, TolgeeInstance } from '../TolgeeCore';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolgee/core",
-  "version": "5.33.2",
+  "version": "5.33.3-prerelease.2efc0e6b.0",
   "description": "Library providing ability to translate messages directly in context of developed application.",
   "main": "./dist/tolgee.cjs.js",
   "module": "./dist/tolgee.esm.js",
@@ -73,5 +73,5 @@
     "access": "public"
   },
   "sideEffects": false,
-  "gitHead": "73467e06c29511cafab7e7162cef8ac4a36ff507"
+  "gitHead": "799332abc27675f19c1b722ac063cbe2451f500e"
 }

package/src/Controller/Cache/Cache.test.ts

@@ -0,0 +1,189 @@
+import { ListenerEvent } from '../../types';
+import { EventEmitterInstance } from '../Events/EventEmitter';
+import { ValueObserver } from '../ValueObserver';
+import { Cache, CacheInstance } from './Cache';
+
+describe('cache', () => {
+  function createEventMock(): EventEmitterInstance<ListenerEvent<any, any>> {
+    return {
+      emit: jest.fn(),
+      listen: jest.fn(),
+    };
+  }
+
+  let mockedBackendGetRecord: jest.Mock<any, any>;
+  let mockedBackendGetDevRecord: jest.Mock<any, any>;
+
+  let onFetchingChange: jest.Mock<any, any>;
+  let onLoadingChange: jest.Mock<any, any>;
+
+  let cache: CacheInstance;
+
+  beforeEach(() => {
+    const mockedEvents = {
+      on: jest.fn(),
+      onCacheChange: createEventMock(),
+      onError: createEventMock(),
+      onFetchingChange: createEventMock(),
+      onInitialLoaded: createEventMock(),
+      onLanguageChange: createEventMock(),
+      onLoadingChange: createEventMock(),
+      onPendingLanguageChange: createEventMock(),
+      onPermanentChange: createEventMock(),
+      onRunningChange: createEventMock(),
+      onUpdate: createEventMock() as any,
+      setEmitterActive: jest.fn(),
+    };
+
+    mockedBackendGetRecord = jest.fn((args) => {
+      return Promise.resolve({ data: 'Prod', ...args });
+    });
+    mockedBackendGetDevRecord = jest.fn((args) => {
+      return Promise.resolve({ data: 'Dev', ...args });
+    });
+
+    onFetchingChange = jest.fn();
+    onLoadingChange = jest.fn();
+
+    const fetchingObserver = ValueObserver(
+      false,
+      () => cache.isFetching(),
+      onFetchingChange
+    );
+
+    const loadingObserver = ValueObserver(
+      false,
+      () => cache.isLoading('en'),
+      onLoadingChange
+    );
+
+    cache = Cache(
+      mockedEvents,
+      mockedBackendGetRecord,
+      mockedBackendGetDevRecord,
+      (descriptor) => ({ namespace: '', ...descriptor }),
+      () => false,
+      () => false,
+      fetchingObserver,
+      loadingObserver
+    );
+  });
+
+  it('fetches language with default namespace', async () => {
+    const result = await cache.loadRecords([{ language: 'en' }]);
+    expect(result[0].data).toEqual({
+      language: 'en',
+      namespace: '',
+      data: 'Dev',
+    });
+  });
+
+  it('fetches language with specified namespace', async () => {
+    const result = await cache.loadRecords([
+      { language: 'en', namespace: 'test' },
+    ]);
+    expect(result[0].data).toEqual({
+      language: 'en',
+      namespace: 'test',
+      data: 'Dev',
+    });
+  });
+
+  it('fetches language with specified namespace', async () => {
+    const result = await cache.loadRecords([
+      { language: 'en', namespace: 'test' },
+    ]);
+    expect(result[0].data).toEqual({
+      language: 'en',
+      namespace: 'test',
+      data: 'Dev',
+    });
+  });
+
+  it('uses cache when fetching twice the same thing', async () => {
+    await cache.loadRecords([{ language: 'en' }]);
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(1);
+    const result = await cache.loadRecords([{ language: 'en' }], {
+      useCache: true,
+    });
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(1);
+    expect(result[0].data).toEqual({
+      language: 'en',
+      namespace: '',
+      data: 'Dev',
+    });
+  });
+
+  it('uses cache when fetching twice production data', async () => {
+    await cache.loadRecords([{ language: 'en' }], { noDev: true });
+    expect(mockedBackendGetRecord).toBeCalledTimes(1);
+    const result = await cache.loadRecords([{ language: 'en' }], {
+      noDev: true,
+      useCache: true,
+    });
+    expect(mockedBackendGetRecord).toBeCalledTimes(1);
+    expect(result[0].data).toEqual({
+      language: 'en',
+      namespace: '',
+      data: 'Prod',
+    });
+  });
+
+  it('does not use cache when `noCache` is on', async () => {
+    await cache.loadRecords([{ language: 'en' }]);
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(1);
+    await cache.loadRecords([{ language: 'en' }]);
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(2);
+  });
+
+  it('correctly returns combination of non-cached and cached', async () => {
+    await cache.loadRecords([{ language: 'en' }]);
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(1);
+    const result = await cache.loadRecords(
+      [{ language: 'en' }, { language: 'en', namespace: 'new' }],
+      { useCache: true }
+    );
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(2);
+    expect(result).toEqual([
+      {
+        cacheKey: 'en',
+        data: { data: 'Dev', language: 'en', namespace: '' },
+        language: 'en',
+        namespace: '',
+      },
+      {
+        cacheKey: 'en:new',
+        data: { data: 'Dev', language: 'en', namespace: 'new' },
+        language: 'en',
+        namespace: 'new',
+      },
+    ]);
+  });
+
+  it('correctly refetches dev data', async () => {
+    await cache.loadRecords([{ language: 'en' }], { noDev: true });
+    expect(mockedBackendGetRecord).toBeCalledTimes(1);
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(0);
+    cache.invalidate();
+    const result = await cache.loadRecords([{ language: 'en' }]);
+    expect(mockedBackendGetRecord).toBeCalledTimes(1);
+    expect(mockedBackendGetDevRecord).toBeCalledTimes(1);
+    expect(result[0].data).toEqual({
+      language: 'en',
+      namespace: '',
+      data: 'Dev',
+    });
+  });
+
+  it('correctly notifies about fetching and loading', async () => {
+    expect(onLoadingChange).toBeCalledTimes(0);
+    expect(onFetchingChange).toBeCalledTimes(0);
+    await cache.loadRecords([{ language: 'en' }]);
+    expect(onLoadingChange).toBeCalledTimes(2);
+    expect(onFetchingChange).toBeCalledTimes(2);
+    cache.invalidate();
+    await cache.loadRecords([{ language: 'en' }]);
+    expect(onFetchingChange).toBeCalledTimes(4);
+    expect(onLoadingChange).toBeCalledTimes(2);
+  });
+});