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

package/src/Controller/Events/Events.ts

@@ -1,16 +1,20 @@
 import { EventEmitter } from './EventEmitter';
-import { EventEmitterSelective } from './EventEmitterSelective';
 import {
-  CacheDescriptorWithKey,
-  TolgeeError,
+  CacheEvent,
+  FetchingEvent,
+  InitialLoadEvent,
+  LanguageEvent,
+  LoadingEvent,
+  PendingLanguageEvent,
+  PermanentChangeEvent,
+  RunningEvent,
   TolgeeOn,
-  TranslationDescriptor,
+  UpdateEvent,
+  ErrorEvent,
 } from '../../types';
+import { EventEmitterCombined } from './EventEmitterCombined';
 
-export function Events(
-  getFallbackNs: () => string[],
-  getDefaultNs: () => string
-) {
+export function Events() {
   let emitterActive = true;
 
   function isActive() {
@@ -18,16 +22,22 @@ export function Events(
   }
 
   const self = Object.freeze({
-    onPendingLanguageChange: EventEmitter<string>(isActive),
-    onLanguageChange: EventEmitter<string>(isActive),
-    onLoadingChange: EventEmitter<boolean>(isActive),
-    onFetchingChange: EventEmitter<boolean>(isActive),
-    onInitialLoaded: EventEmitter<void>(isActive),
-    onRunningChange: EventEmitter<boolean>(isActive),
-    onCacheChange: EventEmitter<CacheDescriptorWithKey>(isActive),
-    onUpdate: EventEmitterSelective(isActive, getFallbackNs, getDefaultNs),
-    onPermanentChange: EventEmitter<TranslationDescriptor>(isActive),
-    onError: EventEmitter<TolgeeError>(isActive),
+    onPendingLanguageChange: EventEmitter<PendingLanguageEvent>(
+      'pendingLanguage',
+      isActive
+    ),
+    onLanguageChange: EventEmitter<LanguageEvent>('language', isActive),
+    onLoadingChange: EventEmitter<LoadingEvent>('loading', isActive),
+    onFetchingChange: EventEmitter<FetchingEvent>('fetching', isActive),
+    onInitialLoaded: EventEmitter<InitialLoadEvent>('initialLoad', isActive),
+    onRunningChange: EventEmitter<RunningEvent>('running', isActive),
+    onCacheChange: EventEmitter<CacheEvent>('cache', isActive),
+    onPermanentChange: EventEmitter<PermanentChangeEvent>(
+      'permanentChange',
+      isActive
+    ),
+    onError: EventEmitter<ErrorEvent>('error', isActive),
+    onUpdate: EventEmitterCombined<UpdateEvent>(isActive),
     setEmitterActive(active: boolean) {
       emitterActive = active;
     },
@@ -57,11 +67,9 @@ export function Events(
     }) as TolgeeOn,
   });
 
-  self.onInitialLoaded.listen(() => self.onUpdate.emit());
-  self.onLanguageChange.listen(() => self.onUpdate.emit());
-  self.onCacheChange.listen(({ value }) =>
-    self.onUpdate.emit([value.namespace], true)
-  );
+  self.onInitialLoaded.listen((e) => self.onUpdate.emit(e, false));
+  self.onLanguageChange.listen((e) => self.onUpdate.emit(e, false));
+  self.onCacheChange.listen((e) => self.onUpdate.emit(e, true));
 
   return self;
 }

package/src/Controller/Plugins/Plugins.ts

@@ -267,6 +267,11 @@ export function Plugins(
 
     getBackendDevRecord: (async ({ language, namespace }) => {
       const { apiKey, apiUrl, projectId, filterTag } = getInitialOptions();
+
+      if (!apiKey || !apiUrl || !self.hasDevBackend()) {
+        return undefined;
+      }
+
       return instances.devBackend?.getRecord({
         apiKey,
         apiUrl,

package/src/Controller/State/State.ts

@@ -2,8 +2,11 @@ import {
   CacheDescriptor,
   CacheDescriptorInternal,
   DevCredentials,
+  LanguageEvent,
   NsFallback,
   NsType,
+  PendingLanguageEvent,
+  RunningEvent,
 } from '../../types';
 
 import { decodeCacheKey } from '../Cache/helpers';
@@ -17,9 +20,9 @@ import {
 import { initState, TolgeeOptions } from './initState';
 
 export function State(
-  onLanguageChange: EventEmitterInstance<string>,
-  onPendingLanguageChange: EventEmitterInstance<string>,
-  onRunningChange: EventEmitterInstance<boolean>
+  onLanguageChange: EventEmitterInstance<LanguageEvent>,
+  onPendingLanguageChange: EventEmitterInstance<PendingLanguageEvent>,
+  onRunningChange: EventEmitterInstance<RunningEvent>
 ) {
   let state = initState();
   let devCredentials: DevCredentials = undefined;
@@ -44,6 +47,10 @@ export function State(
       return state.isInitialLoading;
     },
 
+    isCacheDisabled() {
+      return state.initialOptions.disableCache;
+    },
+
     setInitialLoading(value: boolean) {
       state.isInitialLoading = value;
     },
@@ -99,7 +106,8 @@ export function State(
     },
     getRequiredNamespaces() {
       return unique([
-        ...(state.initialOptions.ns || [state.initialOptions.defaultNs]),
+        self.getDefaultNs(),
+        ...(state.initialOptions.ns || []),
         ...getFallbackArray(state.initialOptions.fallbackNs),
         ...state.activeNamespaces.keys(),
       ]);
@@ -123,8 +131,16 @@ export function State(
       return getFallbackArray(state.initialOptions.fallbackNs);
     },
 
+    getNs() {
+      return state.initialOptions.ns?.length
+        ? state.initialOptions.ns
+        : [state.initialOptions.defaultNs ?? ''];
+    },
+
     getDefaultNs(ns?: NsType) {
-      return ns === undefined ? state.initialOptions.defaultNs : ns;
+      return ns === undefined
+        ? state.initialOptions.defaultNs ?? state.initialOptions.ns?.[0] ?? ''
+        : ns;
     },
 
     getAvailableLanguages() {
@@ -138,11 +154,15 @@ export function State(
       }
     },
 
+    getAvailableNs() {
+      return state.initialOptions.availableNs;
+    },
+
     withDefaultNs(descriptor: CacheDescriptor): CacheDescriptorInternal {
       return {
         namespace:
           descriptor.namespace === undefined
-            ? self.getInitialOptions().defaultNs
+            ? self.getDefaultNs()
             : descriptor.namespace,
         language: descriptor.language,
       };

package/src/Controller/State/initState.ts

@@ -5,6 +5,7 @@ import {
   OnFormatError,
   FetchFn,
   MissingTranslationHandler,
+  CachePublicRecord,
 } from '../../types';
 import { createFetchFunction, sanitizeUrl } from '../../helpers';
 import {
@@ -23,6 +24,8 @@ export type TolgeeStaticData = {
   [key: string]: TreeTranslationsData | (() => Promise<TreeTranslationsData>);
 };
 
+export type TolgeeStaticDataProp = TolgeeStaticData | CachePublicRecord[];
+
 export type TolgeeOptionsInternal = {
   /**
    * Initial language
@@ -50,8 +53,8 @@ export type TolgeeOptionsInternal = {
   defaultLanguage?: string;
 
   /**
-   * Languages which can be used for language detection
-   * and also limits which values can be stored
+   * Specify all available languages. Required for language detection or loading all languages at once (loadMatrix).
+   * It also limits which values can be stored. Is derrived from `staticData` keys if not provided.
    */
   availableLanguages?: string[];
 
@@ -61,7 +64,7 @@ export type TolgeeOptionsInternal = {
   fallbackLanguage?: FallbackLanguageOption;
 
   /**
-   * Namespaces which should be always fetched
+   * Namespaces which should be always fetched (default: [defaultNs] or [''])
    */
   ns?: string[];
 
@@ -71,9 +74,14 @@ export type TolgeeOptionsInternal = {
   fallbackNs?: FallbackGeneral;
 
   /**
-   * Default namespace when no namespace defined (default: '')
+   * Default namespace when no namespace defined (default: first from `ns`)
+   */
+  defaultNs?: string;
+
+  /**
+   * Specify all available namespaces. Required for loading all namespaces at once (loadMatrix).
    */
-  defaultNs: string;
+  availableNs?: string[];
 
   /**
    * These data go directly to cache or you can specify async
@@ -85,8 +93,17 @@ export type TolgeeOptionsInternal = {
    *   'language:namespace': <translations | async function>
    * }
    * ```
+   *
+   * You can also pass list of `CachePublicRecord`, which is in format:
+   *
+   * {
+   *   'language': <locale>,
+   *   'namespace': <namespace>
+   *   'data': <translations>
+   * }
+   *
    */
-  staticData?: TolgeeStaticData;
+  staticData?: TolgeeStaticDataProp;
 
   /**
    * Switches between invisible and text observer. (Default: invisible)
@@ -124,6 +141,16 @@ export type TolgeeOptionsInternal = {
    * Use only keys tagged with one of the listed tags
    */
   filterTag?: string[];
+
+  /**
+   * automatically load required records on `run` and `changeLanguage` (default: true)
+   */
+  autoLoadRequiredData: boolean;
+
+  /**
+   * no internal cache is being held inside tolgee
+   */
+  disableCache: boolean;
 };
 
 export type TolgeeOptions = Partial<
@@ -142,13 +169,14 @@ export type State = {
 };
 
 const defaultValues: TolgeeOptionsInternal = {
-  defaultNs: '',
   observerOptions: defaultObserverOptions,
   observerType: 'invisible',
   onFormatError: DEFAULT_FORMAT_ERROR,
   apiUrl: DEFAULT_API_URL,
+  autoLoadRequiredData: true,
   fetch: createFetchFunction(),
   onTranslationMissing: DEFAULT_MISSING_TRANSLATION,
+  disableCache: false,
 };
 
 export const combineOptions = <T extends TolgeeOptions>(

package/src/TolgeeCore.ts

@@ -35,21 +35,6 @@ function createTolgee(options: TolgeeOptions) {
      */
     on: controller.on,
 
-    /**
-     * Listen for specific namespaces changes.
-     *
-     * ```
-     * const sub = tolgee.onUpdate(handler)
-     *
-     * // subscribe to selected namespace
-     * sub.subscribeNs(['common'])
-     *
-     * // unsubscribe
-     * sub.unsubscribe()
-     * ```
-     */
-    onNsUpdate: controller.onUpdate.listenSome,
-
     /**
      * Turn off/on events emitting. Is on by default.
      */
@@ -94,6 +79,18 @@ function createTolgee(options: TolgeeOptions) {
      */
     removeActiveNs: controller.removeActiveNs,
 
+    /**
+     * Load records which would be loaded by `run` function
+     *
+     * You can provide language if not previously set on tolgee instance
+     */
+    loadRequired: controller.loadRequired,
+
+    /**
+     * Load records in matrix (languages x namespaces)
+     */
+    loadMatrix: controller.loadMatrix,
+
     /**
      * Manually load multiple records from `Backend` (or `DevBackend` when in dev mode)
      *
@@ -128,9 +125,9 @@ function createTolgee(options: TolgeeOptions) {
     isLoaded: controller.isLoaded,
 
     /**
-     * Returns records needed for instance to be `loaded`
+     * Returns descriptors of records needed for instance to be `loaded`
      */
-    getRequiredRecords: controller.getRequiredRecords,
+    getRequiredDescriptors: controller.getRequiredDescriptors,
 
     /**
      * @return `true` if tolgee is loading initial data (triggered by `run`).

package/src/__test/cache.test.ts

@@ -1,7 +1,7 @@
 /* eslint-disable no-console */
 import { TolgeeCore, TolgeeInstance } from '../TolgeeCore';
-import { TolgeePlugin, TreeTranslationsData } from '../types';
-import { resolvablePromise } from './testTools';
+import { TreeTranslationsData } from '../types';
+import { DevToolsPlugin, DevToolsThrow, resolvablePromise } from './testTools';
 
 function waitForInitialLoad(tolgee: TolgeeInstance) {
   return new Promise<void>((resolve) => {
@@ -12,30 +12,6 @@ function waitForInitialLoad(tolgee: TolgeeInstance) {
   });
 }
 
-const DevToolsPlugin =
-  (postfix = ''): TolgeePlugin =>
-  (tolgee, tools) => {
-    tolgee.updateOptions({ apiKey: 'test', apiUrl: 'test' });
-    tools.setDevBackend({
-      getRecord({ language, namespace }) {
-        return Promise.resolve({
-          test: { sub: `${language}.${namespace || 'default'}${postfix}` },
-        });
-      },
-    });
-    return tolgee;
-  };
-
-const DevToolsThrow = (): TolgeePlugin => (tolgee, tools) => {
-  tolgee.updateOptions({ apiKey: 'test', apiUrl: 'test' });
-  tools.setDevBackend({
-    getRecord() {
-      return Promise.reject();
-    },
-  });
-  return tolgee;
-};
-
 describe('cache', () => {
   let tolgee: TolgeeInstance;
 

package/src/__test/client.test.ts

@@ -28,14 +28,14 @@ describe('using tolgee as client', () => {
     });
     expect(promiseEnTest).toBeCalledTimes(1);
     expect(promiseEnCommon).not.toBeCalled();
-    expect(enTest).toEqual(new Map([['test', 'Test']]));
+    expect(enTest).toEqual({ test: 'Test' });
 
     const enCommon = await tolgee.loadRecord({
       language: 'en',
       namespace: 'common',
     });
     expect(promiseEnCommon).toBeCalledTimes(1);
-    expect(enCommon).toEqual(new Map([['cancel', 'Cancel']]));
+    expect(enCommon).toEqual({ cancel: 'Cancel' });
 
     const esTest = await tolgee.loadRecord({
       language: 'es',
@@ -43,6 +43,6 @@ describe('using tolgee as client', () => {
     });
     expect(promiseEsTest).toBeCalledTimes(1);
     expect(promiseEsCommon).not.toBeCalled();
-    expect(esTest).toEqual(new Map([['test', 'Testa']]));
+    expect(esTest).toEqual({ test: 'Testa' });
   });
 });

package/src/__test/events.test.ts

@@ -6,29 +6,56 @@ describe('events', () => {
     const handler = jest.fn((lang) => {});
     tolgee.on('language', handler);
     await tolgee.changeLanguage('es');
-    expect(handler).toHaveBeenCalledWith({ value: 'es' });
+    expect(handler).toHaveBeenCalledWith({ type: 'language', value: 'es' });
   });
 
-  it('correctly emits translation change listeners', async () => {
+  it('emits pendingLanguage event correctly', async () => {
     const tolgee = TolgeeCore().init({
       language: 'en',
       staticData: {
-        en: { hello: 'World', language: 'English' },
-        es: { hello: 'Mundo', language: 'Spanish' },
+        en: () => Promise.resolve().then(() => ({ test: 'Test' })),
+        es: () => Promise.resolve().then(() => ({ test: 'El Test' })),
       },
     });
-    const helloHandler = jest.fn(() => {});
-    const languageHandler = jest.fn(() => {});
-
-    tolgee.onNsUpdate(helloHandler);
-    tolgee.onNsUpdate(languageHandler);
+    await tolgee.run();
+    const languageHandler = jest.fn();
+    const pendingLanguageHandler = jest.fn();
+    tolgee.on('language', languageHandler);
+    tolgee.on('pendingLanguage', pendingLanguageHandler);
+    const promise = tolgee.changeLanguage('es');
+    expect(pendingLanguageHandler).toHaveBeenCalledTimes(1);
+    expect(languageHandler).toHaveBeenCalledTimes(0);
+    await promise;
+    expect(pendingLanguageHandler).toHaveBeenCalledTimes(1);
+    expect(languageHandler).toHaveBeenCalledTimes(1);
+  });
 
-    tolgee.changeTranslation({ language: 'es' }, 'hello', 'Světe');
+  it('groups cache events with language change event', async () => {
+    const tolgee = TolgeeCore().init({ language: 'en' });
+    const handler = jest.fn((e) => {});
+    tolgee.on('update', handler);
+    tolgee.addStaticData({ en: { test: 'Test' } });
     tolgee.changeLanguage('es');
+    expect(handler).toHaveBeenCalledWith([
+      { type: 'cache', value: { language: 'en', namespace: '' } },
+      { type: 'language', value: 'es' },
+    ]);
+  });
 
-    await Promise.resolve();
-    expect(helloHandler).toHaveBeenCalledTimes(1);
-    expect(languageHandler).toHaveBeenCalledTimes(1);
+  it('groups cache events with initialLoad event', async () => {
+    const tolgee = TolgeeCore().init({
+      language: 'en',
+      staticData: {
+        en: () => Promise.resolve({ test: 'Test' }),
+      },
+    });
+    const handler = jest.fn((e) => {});
+    tolgee.on('update', handler);
+    await tolgee.run();
+    expect(handler).toHaveBeenCalledWith([
+      { type: 'cache', value: { language: 'en', namespace: '' } },
+      { type: 'initialLoad', value: undefined },
+    ]);
   });
 
   it('stop emitting when turned off', async () => {

package/src/__test/load.matrix.test.ts

@@ -0,0 +1,123 @@
+import { TolgeeCore } from '../TolgeeCore';
+import { TolgeeInstance } from '../types';
+import { BackendPlugin, DevToolsPlugin } from './testTools';
+
+describe('load required', () => {
+  let tolgee: TolgeeInstance;
+
+  beforeEach(async () => {
+    tolgee = TolgeeCore()
+      .use(DevToolsPlugin('.dev'))
+      .use(BackendPlugin('.prod'))
+      .init({
+        language: 'en',
+        apiKey: 'test',
+        apiUrl: 'test',
+      });
+  });
+
+  it('loads english and empty ns', async () => {
+    const records = await tolgee.loadMatrix({
+      languages: ['en'],
+      namespaces: [''],
+    });
+    expect(records).toEqual([
+      {
+        cacheKey: 'en',
+        data: { 'test.sub': 'en.default.dev' },
+        language: 'en',
+        namespace: '',
+      },
+    ]);
+  });
+
+  it('loads english and empty ns', async () => {
+    const records = await tolgee.loadMatrix({
+      languages: ['en'],
+      namespaces: [''],
+    });
+    expect(records).toEqual([
+      {
+        cacheKey: 'en',
+        data: { 'test.sub': 'en.default.dev' },
+        language: 'en',
+        namespace: '',
+      },
+    ]);
+  });
+
+  it('fails to load all namespaces when no availableNs specified', async () => {
+    const promise = tolgee.loadMatrix({
+      languages: ['en'],
+      namespaces: 'all',
+    });
+
+    expect(() => promise).rejects.toThrow(
+      "Tolgee: You need to specify 'availableNs' option"
+    );
+  });
+
+  it('fails to load all languages when no availableLanguages specified', async () => {
+    const promise = tolgee.loadMatrix({
+      languages: 'all',
+      namespaces: [''],
+    });
+
+    expect(() => promise).rejects.toThrow(
+      "Tolgee: You need to specify 'availableLanguages' option"
+    );
+  });
+
+  it('loads all dev', async () => {
+    tolgee.updateOptions({
+      availableLanguages: ['en'],
+      availableNs: ['', 'test'],
+    });
+    const result = await tolgee.loadMatrix({
+      languages: 'all',
+      namespaces: 'all',
+    });
+
+    expect(result).toEqual([
+      {
+        cacheKey: 'en',
+        data: { 'test.sub': 'en.default.dev' },
+        language: 'en',
+        namespace: '',
+      },
+      {
+        cacheKey: 'en:test',
+        data: { 'test.sub': 'en.test.dev' },
+        language: 'en',
+        namespace: 'test',
+      },
+    ]);
+  });
+
+  it('loads all prod', async () => {
+    tolgee.updateOptions({
+      availableLanguages: ['en'],
+      availableNs: ['', 'test'],
+    });
+    const result = await tolgee.loadMatrix({
+      languages: 'all',
+      namespaces: 'all',
+      noDev: true,
+    });
+
+    expect(result).toEqual([
+      {
+        cacheKey: 'en',
+        data: { 'test.sub': 'en.default.prod' },
+        language: 'en',
+        namespace: '',
+      },
+      {
+        cacheKey: 'en:test',
+        data: { 'test.sub': 'en.test.prod' },
+        language: 'en',
+        namespace: 'test',
+      },
+    ]);
+  });
+});

package/src/__test/load.required.test.ts

@@ -0,0 +1,71 @@
+import { TolgeeCore } from '../TolgeeCore';
+import { TolgeeInstance } from '../types';
+import { BackendPlugin, DevToolsPlugin } from './testTools';
+
+describe('load required', () => {
+  let tolgee: TolgeeInstance;
+
+  beforeEach(async () => {
+    tolgee = TolgeeCore()
+      .use(DevToolsPlugin('.dev'))
+      .use(BackendPlugin('.prod'))
+      .init({
+        language: 'en',
+        apiKey: 'test',
+        apiUrl: 'test',
+      });
+  });
+
+  it('loads required records', async () => {
+    const records = await tolgee.loadRequired();
+    expect(records).toEqual([
+      {
+        cacheKey: 'en',
+        data: { 'test.sub': 'en.default.dev' },
+        language: 'en',
+        namespace: '',
+      },
+    ]);
+  });
+
+  it('loads required records when language is passed through parameter', async () => {
+    tolgee.updateOptions({ language: undefined });
+    const noRecords = await tolgee.loadRequired();
+    expect(noRecords).toEqual([]);
+    const records = await tolgee.loadRequired({ language: 'en' });
+    expect(records).toEqual([
+      {
+        cacheKey: 'en',
+        data: { 'test.sub': 'en.default.dev' },
+        language: 'en',
+        namespace: '',
+      },
+    ]);
+  });
+
+  it('loads records with namespaces', async () => {
+    tolgee.updateOptions({ defaultNs: 'namespace' });
+    const records = await tolgee.loadRequired();
+    expect(records).toEqual([
+      {
+        cacheKey: 'en:namespace',
+        data: { 'test.sub': 'en.namespace.dev' },
+        language: 'en',
+        namespace: 'namespace',
+      },
+    ]);
+  });
+
+  it('loads records production', async () => {
+    tolgee.updateOptions();
+    const records = await tolgee.loadRequired({ noDev: true });
+    expect(records).toEqual([
+      {
+        cacheKey: 'en',
+        data: { 'test.sub': 'en.default.prod' },
+        language: 'en',
+        namespace: '',
+      },
+    ]);
+  });
+});