@tolgee/core 5.20.3 → 5.21.0

package/src/Controller/Controller.ts

@@ -6,7 +6,6 @@ import {
   TFnType,
   NsType,
   KeyAndNamespacesInternal,
-  TranslationDescriptor,
 } from '../types';
 import { Cache } from './Cache/Cache';
 import { getFallbackArray } from '../helpers';
@@ -47,11 +46,11 @@ export function Controller({ options }: StateServiceProps) {
     getTranslationNs,
     getTranslation,
     changeTranslation,
-    onPermanentChange
+    events
   );
 
   const cache = Cache(
-    events.onCacheChange,
+    events,
     pluginService.getBackendRecord,
     pluginService.getBackendDevRecord,
     state.withDefaultNs,
@@ -110,13 +109,6 @@ export function Controller({ options }: StateServiceProps) {
     };
   }
 
-  function onPermanentChange(props: TranslationDescriptor) {
-    events.onPermanentChange.emit({
-      key: props.key,
-      namespace: props.namespace,
-    });
-  }
-
   function init(options: Partial<TolgeeOptions>) {
     state.init(options);
     cache.addStaticData(state.getInitialOptions().staticData);
@@ -182,6 +174,7 @@ export function Controller({ options }: StateServiceProps) {
       return;
     }
     const languageOrPromise = pluginService.getInitialLanguage();
+
     return valueOrPromise(languageOrPromise, (lang) => {
       const language =
         (lang as string | undefined) ||
@@ -231,7 +224,7 @@ export function Controller({ options }: StateServiceProps) {
         // there might be parallel language change
         // we only want to apply latest
         state.setLanguage(language);
-        pluginService.setStoredLanguage(language);
+        await pluginService.setStoredLanguage(language);
       }
     },
 

package/src/Controller/Events/Events.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from './EventEmitter';
 import { EventEmitterSelective } from './EventEmitterSelective';
 import {
   CacheDescriptorWithKey,
+  TolgeeError,
   TolgeeOn,
   TranslationDescriptor,
 } from '../../types';
@@ -26,6 +27,7 @@ export function Events(
     onCacheChange: EventEmitter<CacheDescriptorWithKey>(isActive),
     onUpdate: EventEmitterSelective(isActive, getFallbackNs, getDefaultNs),
     onPermanentChange: EventEmitter<TranslationDescriptor>(isActive),
+    onError: EventEmitter<TolgeeError>(isActive),
     setEmitterActive(active: boolean) {
       emitterActive = active;
     },
@@ -49,6 +51,8 @@ export function Events(
           return self.onUpdate.listen(handler as any);
         case 'permanentChange':
           return self.onPermanentChange.listen(handler as any);
+        case 'error':
+          return self.onError.listen(handler as any);
       }
     }) as TolgeeOn,
   });

package/src/Controller/Plugins/Plugins.ts

@@ -1,4 +1,8 @@
-import { getErrorMessage, isPromise, valueOrPromise } from '../../helpers';
+import {
+  getErrorMessage,
+  valueOrPromise,
+  handleRegularOrAsyncErr,
+} from '../../helpers';
 import {
   BackendDevMiddleware,
   BackendMiddleware,
@@ -22,8 +26,10 @@ import {
   FormatErrorHandler,
   FindPositionsInterface,
   BackendGetRecordInternal,
-  TranslationDescriptor,
+  LanguageStorageError,
+  LanguageDetectorError,
 } from '../../types';
+import { EventsInstance } from '../Events/Events';
 import { DEFAULT_FORMAT_ERROR } from '../State/initState';
 
 export function Plugins(
@@ -34,7 +40,7 @@ export function Plugins(
   getTranslationNs: (props: KeyAndNamespacesInternal) => string[],
   getTranslation: (props: KeyAndNamespacesInternal) => string | undefined,
   changeTranslation: ChangeTranslationInterface,
-  onPermanentChange: (props: TranslationDescriptor) => void
+  events: EventsInstance
 ) {
   const plugins = {
     ui: undefined as UiMiddleware | undefined,
@@ -125,6 +131,14 @@ export function Plugins(
     instances.languageDetector = detector;
   }
 
+  function storageLoadLanguage() {
+    return handleRegularOrAsyncErr(
+      events.onError,
+      (e) => new LanguageStorageError('Tolgee: Failed to load language', e),
+      () => instances.languageStorage?.getLanguage(getCommonProps())
+    );
+  }
+
   function detectLanguage() {
     if (!instances.languageDetector) {
       return undefined;
@@ -132,10 +146,15 @@ export function Plugins(
 
     const availableLanguages = getAvailableLanguages()!;
 
-    return instances.languageDetector.getLanguage({
-      availableLanguages,
-      ...getCommonProps(),
-    });
+    return handleRegularOrAsyncErr(
+      events.onError,
+      (e) => new LanguageDetectorError('Tolgee: Failed to detect language', e),
+      () =>
+        instances.languageDetector?.getLanguage({
+          availableLanguages,
+          ...getCommonProps(),
+        })
+    );
   }
 
   function addBackend(backend: BackendMiddleware | undefined) {
@@ -177,7 +196,7 @@ export function Plugins(
         highlight: self.highlight,
         changeTranslation,
         findPositions,
-        onPermanentChange,
+        onPermanentChange: (data) => events.onPermanentChange.emit(data),
       });
 
       instances.observer?.run({
@@ -199,9 +218,7 @@ export function Plugins(
 
     getInitialLanguage() {
       const availableLanguages = getAvailableLanguages();
-      const languageOrPromise = instances.languageStorage?.getLanguage(
-        getCommonProps()
-      );
+      const languageOrPromise = storageLoadLanguage();
 
       return valueOrPromise(languageOrPromise, (language) => {
         if (
@@ -215,7 +232,11 @@ export function Plugins(
     },
 
     setStoredLanguage(language: string) {
-      instances.languageStorage?.setLanguage(language, getCommonProps());
+      return handleRegularOrAsyncErr(
+        events.onError,
+        (e) => new LanguageStorageError('Tolgee: Failed to store language', e),
+        () => instances.languageStorage?.setLanguage(language, getCommonProps())
+      );
     },
 
     getDevBackend() {
@@ -229,13 +250,6 @@ export function Plugins(
           namespace,
           ...getCommonProps(),
         });
-        if (isPromise(data)) {
-          return data?.catch((e) => {
-            // eslint-disable-next-line no-console
-            console.error(e);
-            return {};
-          });
-        }
         if (data !== undefined) {
           return data;
         }

package/src/__test/errors.detector.test.ts

@@ -0,0 +1,64 @@
+/* eslint-disable no-console */
+import { TolgeeCore } from '../TolgeeCore';
+import { LanguageDetectorError, TolgeePlugin } from '../types';
+
+const failingDetector = (async: boolean): TolgeePlugin => {
+  return (tolgee, tools) => {
+    tools.setLanguageDetector({
+      async getLanguage() {
+        if (async) {
+          return Promise.reject(new Error('failed to fetch'));
+        } else {
+          throw new Error('failed to fetch');
+        }
+      },
+    });
+    return tolgee;
+  };
+};
+
+describe('language detector errors', () => {
+  beforeEach(() => {
+    console.warn = jest.fn();
+    console.error = jest.fn();
+  });
+
+  it('emitts error when detector fails async', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingDetector(true))
+      .init({ availableLanguages: ['en', 'cs'], defaultLanguage: 'en' });
+    tolgee.on('error', errorHandler);
+    await expect(() => tolgee.run()).rejects.toThrow(LanguageDetectorError);
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as LanguageDetectorError;
+    expect(firstArgument).toBeInstanceOf(LanguageDetectorError);
+    expect(firstArgument).toBeInstanceOf(Error);
+    expect(firstArgument).toHaveProperty('name', 'LanguageDetectorError');
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to detect language'
+    );
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+
+  it('emitts error when detector fails sync', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingDetector(false))
+      .init({ availableLanguages: ['en', 'cs'], defaultLanguage: 'en' });
+    tolgee.on('error', errorHandler);
+    await expect(() => tolgee.run()).rejects.toThrow(LanguageDetectorError);
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as LanguageDetectorError;
+    expect(firstArgument).toBeInstanceOf(LanguageDetectorError);
+    expect(firstArgument).toHaveProperty('name', 'LanguageDetectorError');
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to detect language'
+    );
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+});

package/src/__test/errors.record.test.ts

@@ -0,0 +1,127 @@
+/* eslint-disable no-console */
+import { TolgeeCore } from '../TolgeeCore';
+import { RecordFetchError, TolgeePlugin } from '../types';
+
+const failingBackend = (): TolgeePlugin => {
+  return (tolgee, tools) => {
+    tools.addBackend({
+      async getRecord() {
+        return Promise.reject(new Error('failed to fetch'));
+      },
+    });
+    return tolgee;
+  };
+};
+
+const failingDevBackend = (): TolgeePlugin => {
+  return (tolgee, tools) => {
+    tools.setDevBackend({
+      async getRecord() {
+        return Promise.reject(new Error('failed to fetch'));
+      },
+    });
+    return tolgee;
+  };
+};
+
+describe('translation records', () => {
+  beforeEach(() => {
+    console.warn = jest.fn();
+    console.error = jest.fn();
+  });
+
+  it('emitts error when fails to fetch dev record', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingDevBackend())
+      .init({ language: 'en', apiKey: 'test', apiUrl: 'test' });
+    tolgee.on('error', errorHandler);
+    await tolgee.run();
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as RecordFetchError;
+    expect(firstArgument).toBeInstanceOf(RecordFetchError);
+    expect(firstArgument).toBeInstanceOf(Error);
+    expect(firstArgument).toHaveProperty('language', 'en');
+    expect(firstArgument).toHaveProperty('namespace', '');
+    expect(firstArgument).toHaveProperty('isDev', true);
+    expect(firstArgument).toHaveProperty('name', 'RecordFetchError');
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to fetch record for "en"'
+    );
+    expect(console.warn).toBeCalledTimes(1);
+    expect(console.error).toBeCalledTimes(0);
+  });
+
+  it('emitts error when fails to fetch record', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore().use(failingBackend()).init({ language: 'en' });
+    tolgee.on('error', errorHandler);
+    await expect(() => tolgee.run()).rejects.toThrow(RecordFetchError);
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as RecordFetchError;
+    expect(firstArgument).toBeInstanceOf(RecordFetchError);
+    expect(firstArgument).toHaveProperty('language', 'en');
+    expect(firstArgument).toHaveProperty('namespace', '');
+    expect(firstArgument).toHaveProperty('isDev', false);
+    expect(firstArgument).toHaveProperty('name', 'RecordFetchError');
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to fetch record for "en"'
+    );
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+
+  it('emitts error when fails to fetch promise in static data', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingDevBackend())
+      .init({
+        language: 'en',
+        staticData: { en: () => Promise.reject(new Error('No data')) },
+      });
+    tolgee.on('error', errorHandler);
+    await expect(() => tolgee.run()).rejects.toThrow(RecordFetchError);
+
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as RecordFetchError;
+    expect(firstArgument).toBeInstanceOf(RecordFetchError);
+    expect(firstArgument).toHaveProperty('language', 'en');
+    expect(firstArgument).toHaveProperty('namespace', '');
+    expect(firstArgument).toHaveProperty('isDev', false);
+    expect(firstArgument).toHaveProperty('name', 'RecordFetchError');
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to fetch record for "en"'
+    );
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+
+  it('emitts error when it fails', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingDevBackend())
+      .init({
+        language: 'en',
+        staticData: { en: () => Promise.reject(new Error('No data')) },
+      });
+    tolgee.on('error', errorHandler);
+    await expect(() => tolgee.run()).rejects.toThrow(RecordFetchError);
+
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as RecordFetchError;
+    expect(firstArgument).toBeInstanceOf(RecordFetchError);
+    expect(firstArgument).toHaveProperty('language', 'en');
+    expect(firstArgument).toHaveProperty('namespace', '');
+    expect(firstArgument).toHaveProperty('isDev', false);
+    expect(firstArgument).toHaveProperty('name', 'RecordFetchError');
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to fetch record for "en"'
+    );
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+});

package/src/__test/errors.storage.test.ts

@@ -0,0 +1,117 @@
+/* eslint-disable no-console */
+import { TolgeeCore } from '../TolgeeCore';
+import { LanguageStorageError, TolgeePlugin } from '../types';
+
+const failingStorage = (async: boolean): TolgeePlugin => {
+  return (tolgee, tools) => {
+    tools.setLanguageStorage({
+      async getLanguage() {
+        if (async) {
+          return Promise.reject(new Error('failed to fetch'));
+        } else {
+          throw new Error('failed to fetch');
+        }
+      },
+      async setLanguage() {
+        if (async) {
+          return Promise.reject(new Error('failed to fetch'));
+        } else {
+          throw new Error('failed to fetch');
+        }
+      },
+    });
+    return tolgee;
+  };
+};
+
+describe('language storage errors', () => {
+  beforeEach(() => {
+    console.warn = jest.fn();
+    console.error = jest.fn();
+  });
+
+  it('emitts error when language is loaded async', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingStorage(true))
+      .init({ availableLanguages: ['en', 'cs'], defaultLanguage: 'en' });
+    tolgee.on('error', errorHandler);
+    await expect(() => tolgee.run()).rejects.toThrow(LanguageStorageError);
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as LanguageStorageError;
+
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to load language'
+    );
+    expect(firstArgument).toBeInstanceOf(Error);
+    expect(firstArgument).toBeInstanceOf(LanguageStorageError);
+    expect(firstArgument).toHaveProperty('name', 'LanguageStorageError');
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+
+  it('emitts error when language is loaded sync', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingStorage(false))
+      .init({ availableLanguages: ['en', 'cs'], defaultLanguage: 'en' });
+    tolgee.on('error', errorHandler);
+    await expect(() => tolgee.run()).rejects.toThrow(LanguageStorageError);
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as LanguageStorageError;
+
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to load language'
+    );
+    expect(firstArgument).toBeInstanceOf(LanguageStorageError);
+    expect(firstArgument).toHaveProperty('name', 'LanguageStorageError');
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+
+  it('emitts error when language is saved async', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingStorage(true))
+      .init({ availableLanguages: ['en', 'cs'], language: 'en' });
+    tolgee.on('error', errorHandler);
+    await tolgee.run();
+    await expect(() => tolgee.changeLanguage('cs')).rejects.toThrow(
+      LanguageStorageError
+    );
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as LanguageStorageError;
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to store language'
+    );
+    expect(firstArgument).toBeInstanceOf(LanguageStorageError);
+    expect(firstArgument).toHaveProperty('name', 'LanguageStorageError');
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+
+  it('emitts error when language is saved sync', async () => {
+    const errorHandler = jest.fn();
+    const tolgee = TolgeeCore()
+      .use(failingStorage(false))
+      .init({ availableLanguages: ['en', 'cs'], language: 'en' });
+    tolgee.on('error', errorHandler);
+    await tolgee.run();
+    await expect(() => tolgee.changeLanguage('cs')).rejects.toThrow(
+      LanguageStorageError
+    );
+    const firstArgument = errorHandler.mock.calls[0][0]
+      .value as LanguageStorageError;
+    expect(firstArgument).toHaveProperty(
+      'message',
+      'Tolgee: Failed to store language'
+    );
+    expect(firstArgument).toBeInstanceOf(LanguageStorageError);
+    expect(firstArgument).toHaveProperty('name', 'LanguageStorageError');
+    expect(console.warn).toBeCalledTimes(0);
+    expect(console.error).toBeCalledTimes(1);
+  });
+});

package/src/helpers.ts

@@ -3,10 +3,14 @@ import {
   FallbackLanguageObject,
   FallbackLanguageOption,
   FetchFn,
+  TolgeeError,
 } from './types';
+import { EventEmitterInstance } from './Controller/Events/EventEmitter';
 
-export function isPromise(value: any) {
-  return Boolean(value && typeof value.then === 'function');
+export function isPromise(value: unknown): value is Promise<unknown> {
+  return Boolean(
+    value && typeof (value as unknown as Promise<unknown>).then === 'function'
+  );
 }
 
 export function valueOrPromise<T, R>(
@@ -20,6 +24,29 @@ export function valueOrPromise<T, R>(
   }
 }
 
+export function handleRegularOrAsyncErr<T>(
+  onError: EventEmitterInstance<TolgeeError>,
+  createError: (e: any) => TolgeeError,
+  callback: () => Promise<T> | T
+): Promise<T> | T {
+  function handle(e: any): never {
+    const error = createError(e);
+    onError.emit(error);
+    // eslint-disable-next-line no-console
+    console.error(error);
+    throw error;
+  }
+  try {
+    const result = callback();
+    if (isPromise(result)) {
+      return result.catch(handle);
+    }
+    return result;
+  } catch (e) {
+    handle(e);
+  }
+}
+
 export function missingOptionError(option: string | string[]) {
   const options = (Array.isArray(option) ? option : [option]).map(
     (val) => `'${val}'`

package/src/types/errors.ts

@@ -0,0 +1,40 @@
+import { CacheDescriptorInternal } from './cache';
+
+export class RecordFetchError extends Error {
+  public name = 'RecordFetchError' as const;
+  public language: string;
+  public namespace: string | undefined;
+  constructor(
+    descriptor: CacheDescriptorInternal,
+    public cause: any,
+    public isDev: boolean = false
+  ) {
+    const { language, namespace } = descriptor;
+    super(
+      `Tolgee: Failed to fetch record for "${language}"${
+        namespace && ` and "${namespace}"`
+      }`
+    );
+    this.language = language;
+    this.namespace = namespace;
+  }
+}
+
+export class LanguageDetectorError extends Error {
+  public name = 'LanguageDetectorError' as const;
+  constructor(message: string, public cause: any) {
+    super(message);
+  }
+}
+
+export class LanguageStorageError extends Error {
+  public name = 'LanguageStorageError' as const;
+  constructor(message: string, public cause: any) {
+    super(message);
+  }
+}
+
+export type TolgeeError =
+  | RecordFetchError
+  | LanguageDetectorError
+  | LanguageStorageError;

package/src/types/events.ts

@@ -1,5 +1,6 @@
 import type { NsFallback } from './general';
 import type { CacheDescriptorWithKey } from './cache';
+import { TolgeeError } from './errors';
 
 export type Subscription = {
   unsubscribe: () => void;
@@ -39,6 +40,7 @@ export interface EventType {
   running: boolean;
   cache: CacheDescriptorWithKey;
   update: void;
+  error: TolgeeError;
   permanentChange: CacheDescriptorWithKey;
 }
 
@@ -84,6 +86,11 @@ export type TolgeeOn<E extends keyof EventType = keyof EventType> = {
    */
   (event: 'cache', handler: Listener<CacheDescriptorWithKey>): Subscription;
 
+  /**
+   * Emitted on errors
+   */
+  (event: 'error', handler: Listener<TolgeeError>): Subscription;
+
   /**
    * Translation was changed or created via dev tools
    */

package/src/types/index.ts

@@ -2,6 +2,7 @@ export * from './general';
 export * from './events';
 export * from './cache';
 export * from './plugin';
+export * from './errors';
 
 export type {
   State,