@tolgee/core 4.9.2 → 4.9.3-rc.ad9d2a4.0

package/src/Tolgee.ts

@@ -1,335 +1,84 @@
-import { TolgeeConfig } from './TolgeeConfig';
+import { Controller } from './Controller/Controller';
 import {
-  InstantProps,
-  InstantPropsTags,
-  TolgeeModule,
-  TranslateProps,
-  TranslatePropsTags,
-  TranslationTags,
-  TranslationParams,
-  TranslationParamsTags,
+  Options,
+  TolgeeInstance,
+  TolgeePlugin,
+  ObserverOptions,
 } from './types';
 
-import { EventEmitterImpl } from './services/EventEmitter';
-import { DependencyService } from './services/DependencyService';
-
-export class Tolgee {
-  private dependencyService: DependencyService;
-
-  private constructor() {
-    this.dependencyService = new DependencyService();
-  }
-
-  get properties() {
-    return this.dependencyService.properties;
-  }
-
-  public get lang() {
-    return this.properties.currentLanguage;
-  }
-
-  /**
-   * This sets a new language.
-   *
-   * Using this setter can behave buggy when you change languages
-   * too fast, since it changes the language property before
-   * translations are actually loaded.
-   * @deprecated use asynchronous changeLanguage method.
-   */
-  public set lang(newLanguage) {
-    this.properties.currentLanguage = newLanguage;
-
-    this.dependencyService.translationService
-      .loadTranslations(newLanguage)
-      .then(() => {
-        this.emitLangChangeEvent(newLanguage);
-      });
-  }
-
-  public get defaultLanguage() {
-    return this.properties.config.defaultLanguage;
-  }
-
-  public get onLangChange() {
-    return this.dependencyService.eventService.LANGUAGE_CHANGED;
-  }
-
-  public get onTranslationChange() {
-    return this.dependencyService.eventService.TRANSLATION_CHANGED;
-  }
-
-  /**
-   * Is emitted when language is loaded for the first time
-   */
-  public get onLangLoaded() {
-    return this.dependencyService.eventService.LANGUAGE_LOADED;
-  }
-
-  /**
-   * True if loading is needed to wait for Tolgee init.
-   * When translation data are provided statically (using import
-   * as staticData config property) then there is no need for translation
-   * fetching so initial loading is not needed at all.
-   */
-  get initialLoading(): boolean {
-    const currentLang = this.properties.currentLanguage;
-    const fallbackLang = this.properties.config.fallbackLanguage;
-    const fallbackPreloading = this.properties.config.preloadFallback;
-    const isStaticDataProvided = (data?: any) => {
-      return data !== undefined && typeof data !== 'function';
-    };
-
-    return (
-      !isStaticDataProvided(this.properties.config.staticData?.[currentLang]) ||
-      (!!fallbackPreloading &&
-        !isStaticDataProvided(
-          this.properties.config.staticData?.[fallbackLang]
-        ))
-    );
-  }
-
-  private get coreService() {
-    return this.dependencyService.coreService;
-  }
-
-  static use(module: TolgeeModule) {
-    return new Tolgee().use(module);
-  }
-
-  static init(config: TolgeeConfig) {
-    return new Tolgee().init(config);
-  }
-
-  /**
-   * Sets the new language.
-   *
-   * Emits the onLangChange and onLangChangeAndLoad events after
-   * the translations are loaded.
-   *
-   * @return Promise<void> Resolves when translations are loaded
-   */
-  public async changeLanguage(newLanguage: string): Promise<void> {
-    await this.dependencyService.translationService.loadTranslations(
-      newLanguage
-    );
-    this.properties.currentLanguage = newLanguage;
-    this.emitLangChangeEvent(newLanguage);
-  }
-
-  use(module: TolgeeModule) {
-    this.dependencyService.moduleService.addModule(module);
-    return this;
-  }
-
-  init(config: TolgeeConfig) {
-    this.dependencyService.init(config);
-    const { apiKey, apiUrl } = this.dependencyService.properties.config;
-    this.dependencyService.properties.mode =
-      apiKey && apiUrl ? 'development' : 'production';
-
-    return this;
-  }
-
-  public async run(): Promise<void> {
-    this.dependencyService.run();
-    if (this.properties.mode === 'development') {
-      try {
-        await this.coreService.loadApiKeyDetails();
-      } catch (e) {
-        // eslint-disable-next-line no-console
-        console.error("Couldn't connect to Tolgee");
-        // eslint-disable-next-line no-console
-        console.error(e);
-        this.properties.mode = 'production';
-      }
-    }
-
-    await this.dependencyService.translationService.loadTranslations();
-    await this.dependencyService.pluginManager.run();
-
-    if (this.properties.config.preloadFallback) {
-      await this.dependencyService.translationService.loadTranslations(
-        this.properties.config.fallbackLanguage
-      );
-    }
-
-    await this.refresh();
-
-    if (this.properties.config.watch) {
-      this.dependencyService.observer.observe();
-    }
-  }
-
-  public async refresh() {
-    return this.dependencyService.wrapper.handleSubtree(
-      this.properties.config.targetElement
-    );
-  }
-
-  async translate(props: TranslateProps): Promise<string>;
-  async translate<T>(props: TranslatePropsTags<T>): Promise<TranslationTags<T>>;
-
-  async translate(
-    key: string,
-    params?: TranslationParams,
-    noWrap?: boolean,
-    defaultValue?: string
-  ): Promise<string>;
-  async translate<T>(
-    key: string,
-    params?: TranslationParamsTags<T>,
-    noWrap?: boolean,
-    defaultValue?: string
-  ): Promise<TranslationTags<T>>;
-
-  async translate(
-    keyOrProps: string | TranslatePropsTags<any>,
-    params: TranslationParamsTags<any> = {},
-    noWrap = false,
-    defaultValue: string | undefined = undefined
-  ): Promise<TranslationTags<any>> {
-    const key = typeof keyOrProps === 'string' ? keyOrProps : keyOrProps.key;
-    let orEmpty = undefined;
-    if (typeof keyOrProps === 'object') {
-      const props = keyOrProps as TranslateProps;
-      // if values are not provided in props object, get them from function
-      // params defaults
-      params = props.params !== undefined ? props.params : params;
-      noWrap = props.noWrap !== undefined ? props.noWrap : noWrap;
-      defaultValue =
-        props.defaultValue !== undefined ? props.defaultValue : defaultValue;
-      orEmpty = props.orEmpty;
-    }
-
-    const translation = await this.dependencyService.textService.translate(
-      key,
-      params,
-      undefined,
-      orEmpty,
-      defaultValue
-    );
-
-    if (this.properties.mode === 'development' && !noWrap) {
-      await this.coreService.loadApiKeyDetails();
-      return this.dependencyService.wrapper.wrap(
-        key,
-        params,
-        defaultValue,
-        translation
-      );
-    }
-
-    return translation;
-  }
-
-  wrap(
-    key: string,
-    params?: TranslationParams,
-    defaultValue?: string | undefined,
-    translation?: string
-  ): string;
-  wrap<T>(
-    key: string,
-    params?: TranslationTags<T>,
-    defaultValue?: string | undefined,
-    translation?: TranslationTags<T>
-  ): TranslationTags<T>;
-
-  wrap(
-    key: string,
-    params?: any,
-    defaultValue?: string | undefined,
-    translation?: TranslationTags<any>
-  ): TranslationTags<any> {
-    if (this.properties.mode === 'development') {
-      return this.dependencyService.wrapper.wrap(
-        key,
-        params,
-        defaultValue,
-        translation
-      );
-    } else {
-      return translation || defaultValue;
-    }
-  }
-
-  instant(
-    key: string,
-    params?: TranslationParams,
-    noWrap?: boolean,
-    orEmpty?: boolean,
-    defaultValue?: string
-  ): string;
-  instant<T>(
-    key: string,
-    params?: TranslationParamsTags<T>,
-    noWrap?: boolean,
-    orEmpty?: boolean,
-    defaultValue?: string
-  ): TranslationTags<T>;
-
-  instant(props: InstantProps): string;
-  instant<T>(props: InstantPropsTags<T>): TranslationTags<T>;
-
-  instant(
-    keyOrProps: string | InstantPropsTags<any>,
-    params: TranslationParams = {},
-    noWrap = false,
-    orEmpty?: boolean,
-    defaultValue?: string
-  ) {
-    const key = typeof keyOrProps === 'string' ? keyOrProps : keyOrProps.key;
-    if (typeof keyOrProps === 'object') {
-      const props = keyOrProps as InstantProps;
-      // if values are not provided in props object, get them from function
-      // params defaults
-      params = props.params !== undefined ? props.params : params;
-      noWrap = props.noWrap !== undefined ? props.noWrap : noWrap;
-      defaultValue =
-        props.defaultValue !== undefined ? props.defaultValue : defaultValue;
-      orEmpty = props.orEmpty !== undefined ? props.orEmpty : orEmpty;
-    }
-
-    const translation = this.dependencyService.textService.instant(
-      key,
-      params,
-      undefined,
-      orEmpty,
-      defaultValue
-    );
-
-    if (this.properties.mode === 'development' && !noWrap) {
-      return this.dependencyService.wrapper.wrap(
-        key,
-        params,
-        defaultValue,
-        translation
-      );
-    }
-    return translation;
-  }
-
-  /**
-   * Get currently cached translations for all languages
-   */
-  public getCachedTranslations() {
-    return this.dependencyService.translationService.getCachedTranslations();
-  }
-
-  /**
-   * Loads translations for given language or returns them from cache
-   * @returns Loaded translations
-   */
-  public loadTranslations(lang: string) {
-    return this.dependencyService.translationService.loadTranslations(lang);
-  }
-
-  public stop = () => {
-    this.dependencyService.stop();
+export const Tolgee = (options?: Partial<Options>): TolgeeInstance => {
+  const controller = Controller({
+    options,
+  });
+
+  const pluginTools = Object.freeze({
+    setFinalFormatter: controller.setFinalFormatter,
+    addFormatter: controller.addFormatter,
+    setObserver: controller.setObserver,
+    hasObserver: controller.hasObserver,
+    setUi: controller.setUi,
+    hasUi: controller.hasUi,
+    setDevBackend: controller.setDevBackend,
+    addBackend: controller.addBackend,
+    setLanguageDetector: controller.setLanguageDetector,
+    setLanguageStorage: controller.setLanguageStorage,
+    overrideCredentials: controller.overrideCredentials,
+  });
+
+  const withRestart = (callback: () => void) => {
+    const wasRunning = controller.isRunning();
+    wasRunning && controller.stop();
+    callback();
+    wasRunning && controller.run();
   };
 
-  private emitLangChangeEvent(value: string) {
-    const langChangedEmitter = this.onLangChange as EventEmitterImpl<any>;
-    langChangedEmitter.emit(value);
-  }
-}
+  const tolgee: TolgeeInstance = Object.freeze({
+    // event listeners
+    on: controller.on,
+    onKeyUpdate: controller.onKeyUpdate.listenSome,
+
+    // state
+    getLanguage: controller.getLanguage,
+    getPendingLanguage: controller.getPendingLanguage,
+    changeLanguage: controller.changeLanguage,
+    changeTranslation: controller.changeTranslation,
+    addActiveNs: controller.addActiveNs,
+    removeActiveNs: controller.removeActiveNs,
+    loadRecords: controller.loadRecords,
+    loadRecord: controller.loadRecord,
+    addStaticData: controller.addStaticData,
+    getRecord: controller.getRecord,
+    getAllRecords: controller.getAllRecords,
+    isLoaded: controller.isLoaded,
+    isInitialLoading: controller.isInitialLoading,
+    isLoading: controller.isLoading,
+    isFetching: controller.isFetching,
+    isRunning: controller.isRunning,
+    run: controller.run,
+    stop: controller.stop,
+    t: controller.t,
+    highlight: controller.highlight,
+    getInitialOptions: controller.getInitialOptions,
+    isDev: controller.isDev,
+    wrap: controller.wrap,
+    unwrap: controller.unwrap,
+
+    // plugins
+    setObserverOptions: (options: Partial<ObserverOptions>) => {
+      controller.setObserverOptions(options);
+      return tolgee;
+    },
+    use: (plugin: TolgeePlugin | undefined) => {
+      if (plugin) {
+        withRestart(() => plugin(tolgee, pluginTools));
+      }
+      return tolgee;
+    },
+    init: (options: Partial<Options>) => {
+      withRestart(() => controller.init(options));
+      return tolgee;
+    },
+  });
+
+  return tolgee;
+};

package/src/TranslateParams.test.ts

@@ -0,0 +1,41 @@
+import { getTranslateParams } from './TranslateParams';
+import { TranslateProps } from './types';
+
+const testParams: TranslateProps = {
+  key: 'test',
+  defaultValue: 'Test',
+  noWrap: true,
+  ns: [],
+  orEmpty: true,
+  params: { yo: 'yo', ns: '(this is param not namespace)' },
+};
+
+describe('getTranslateParams', () => {
+  it('manages regular params', () => {
+    const result = getTranslateParams(testParams);
+    expect(result).toEqual(testParams);
+  });
+
+  it('manages key with default value', () => {
+    const result = getTranslateParams('test', 'Test');
+    expect(result).toEqual({ key: 'test', defaultValue: 'Test' });
+  });
+
+  it('manages key with options', () => {
+    const result = getTranslateParams('test', { noWrap: true, yo: 'yo' });
+    expect(result).toEqual({ key: 'test', noWrap: true, params: { yo: 'yo' } });
+  });
+
+  it('manages key default and options', () => {
+    const result = getTranslateParams('test', 'Test', {
+      noWrap: true,
+      ns: [],
+      orEmpty: true,
+      yo: 'yo',
+      params: {
+        ns: '(this is param not namespace)',
+      },
+    });
+    expect(result).toEqual(testParams);
+  });
+});

package/src/TranslateParams.ts

@@ -0,0 +1,51 @@
+import {
+  CombinedOptions,
+  TFnType,
+  TranslateOptions,
+  TranslateProps,
+} from './types';
+
+function parseCombinedOptions({
+  ns,
+  noWrap,
+  orEmpty,
+  params,
+  ...rest
+}: CombinedOptions<any>): Partial<TranslateProps> {
+  const options: Required<TranslateOptions<any>> = {
+    ns: ns!,
+    noWrap: noWrap!,
+    orEmpty: orEmpty!,
+    params: {
+      ...rest,
+      ...params,
+    },
+  };
+  return options;
+}
+
+export const getTranslateParams: TFnType<any, TranslateProps<any>> = (
+  keyOrProps,
+  ...params
+) => {
+  let result = {} as TranslateProps<any>;
+  let options: CombinedOptions<any> | undefined;
+  if (typeof keyOrProps === 'object') {
+    result = keyOrProps;
+  } else {
+    result.key = keyOrProps;
+    if (typeof params[0] === 'string') {
+      result.defaultValue = params[0];
+      options = params[1] as CombinedOptions<any>;
+    } else if (typeof params[0] === 'object') {
+      options = params[0] as CombinedOptions<any>;
+    }
+  }
+  if (options) {
+    result = {
+      ...parseCombinedOptions(options),
+      ...result,
+    };
+  }
+  return result;
+};

package/src/__test/backend.test.ts

@@ -0,0 +1,48 @@
+import { Tolgee } from '../Tolgee';
+import { BackendInterface, TolgeePlugin } from '../types';
+
+const data = {
+  en: {
+    common: { cancel: 'Cancel' },
+    test: { test: 'Test' },
+  },
+  es: {
+    common: { cancel: 'Cancellar' },
+    test: { test: 'Testar' },
+  },
+} as any;
+
+const backendNormal: BackendInterface = {
+  getRecord({ language, namespace = '' }) {
+    return data[language]?.[namespace];
+  },
+};
+
+const backendDev: BackendInterface = {
+  getRecord() {
+    return Promise.resolve({ cancel: 'Dev' });
+  },
+};
+
+const backendPlugin: TolgeePlugin = (tolgee, tools) => {
+  tools.addBackend(backendNormal);
+  tools.setDevBackend(backendDev);
+  return tolgee;
+};
+
+describe('backend plugins', () => {
+  it('uses plugin to fetch', async () => {
+    const tolgee = Tolgee()
+      .use(backendPlugin)
+      .init({
+        ns: ['common', 'test'],
+        language: 'en',
+      });
+    await tolgee.run();
+    expect(tolgee.t({ key: 'cancel', ns: 'common' })).toEqual('Cancel');
+    tolgee.stop();
+    tolgee.init({ apiUrl: 'asdfasdf', apiKey: 'test' });
+    await tolgee.run();
+    expect(tolgee.t({ key: 'cancel', ns: 'common' })).toEqual('Dev');
+  });
+});

package/src/__test/cache.test.ts

@@ -0,0 +1,148 @@
+import { Tolgee } from '../Tolgee';
+import { TolgeeInstance, TolgeePlugin, TreeTranslationsData } from '../types';
+import { resolvablePromise } from './testTools';
+
+const waitForInitialLoad = (tolgee: TolgeeInstance) =>
+  new Promise<void>((resolve) => {
+    const { unsubscribe } = tolgee.on('initialLoad', () => {
+      unsubscribe();
+      resolve();
+    });
+  });
+
+const DevToolsPlugin =
+  (postfix = ''): TolgeePlugin =>
+  (tolgee, tools) => {
+    tolgee.init({ apiKey: 'test', apiUrl: 'test' });
+    tools.setDevBackend({
+      getRecord({ language, namespace }) {
+        return Promise.resolve({
+          test: { sub: `${language}.${namespace || 'default'}${postfix}` },
+        });
+      },
+    });
+    return tolgee;
+  };
+
+describe('cache', () => {
+  let tolgee: TolgeeInstance;
+
+  beforeEach(async () => {
+    tolgee = Tolgee({
+      language: 'en',
+      staticData: {
+        en: { test: { sub: 'subtestEn' } },
+        cs: { 'test.sub': 'subtestCs' },
+      },
+    });
+  });
+
+  afterEach(() => {
+    tolgee.stop();
+  });
+
+  it('stores initial data correctly', async () => {
+    expect(tolgee.t('test.sub')).toEqual('subtestEn');
+    await tolgee.changeLanguage('cs');
+    expect(tolgee.t('test.sub')).toEqual('subtestCs');
+  });
+
+  it('ignores empty values', async () => {
+    tolgee.addStaticData({
+      en: { sub: { test: 'Test', null: null, undefined: undefined } },
+    });
+    expect(tolgee.t('sub.test')).toEqual('Test');
+    expect(tolgee.t('sub.null')).toEqual('sub.null');
+    expect(tolgee.t('sub.undefined')).toEqual('sub.undefined');
+  });
+
+  it('returns correct data when in dev mode', async () => {
+    expect(tolgee.t('test.sub')).toEqual('subtestEn');
+    tolgee.use(DevToolsPlugin());
+    await tolgee.run();
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+    const changeLangPromise = tolgee.changeLanguage('cs');
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+    await changeLangPromise;
+    expect(tolgee.t('test.sub')).toEqual('cs.default');
+  });
+
+  it('invalidates the cache when switching to dev', async () => {
+    await tolgee.run();
+    expect(tolgee.t('test.sub')).toEqual('subtestEn');
+    tolgee.use(DevToolsPlugin());
+    expect(tolgee.t('test.sub')).toEqual('subtestEn');
+
+    await new Promise<void>((resolve) => {
+      const { unsubscribe } = tolgee.on('initialLoad', async () => {
+        expect(tolgee.t('test.sub')).toEqual('en.default');
+        unsubscribe();
+        resolve();
+      });
+    });
+  });
+
+  it('works with switching to different dev backend', async () => {
+    tolgee.use(DevToolsPlugin());
+    await tolgee.run();
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+    tolgee.use(DevToolsPlugin('.new'));
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+
+    await waitForInitialLoad(tolgee);
+    expect(tolgee.t('test.sub')).toEqual('en.default.new');
+  });
+
+  it('updates initial data correctly', async () => {
+    await tolgee.run();
+    expect(tolgee.t('test.sub')).toEqual('subtestEn');
+    tolgee.addStaticData({ en: { test: { sub: 'newSubtestEn' } } });
+    expect(tolgee.t('test.sub')).toEqual('newSubtestEn');
+  });
+
+  it('ignores new initial data when already in dev mode', async () => {
+    tolgee.use(DevToolsPlugin());
+    await tolgee.run();
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+    tolgee.addStaticData({ en: { test: { sub: 'newSubtestEn' } } });
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+  });
+
+  it('gets all records', async () => {
+    await tolgee.run();
+    expect(tolgee.getAllRecords().length).toEqual(2);
+  });
+
+  it('fetching works with namespaces', async () => {
+    tolgee.use(DevToolsPlugin());
+    const runPromise = tolgee.run();
+    expect(tolgee.isFetching()).toBeTruthy();
+    await runPromise;
+    expect(tolgee.t('test.sub', { ns: 'common' })).toEqual('test.sub');
+    const nsPromise = tolgee.addActiveNs('common');
+    expect(tolgee.isFetching()).toBeTruthy();
+    expect(tolgee.isFetching('common')).toBeTruthy();
+    expect(tolgee.isFetching('nonexistant')).toBeFalsy();
+    await nsPromise;
+    expect(tolgee.t('test.sub', { ns: 'common' })).toEqual('en.common');
+    expect(tolgee.isFetching()).toBeFalsy();
+  });
+
+  it("pending requests won't rewrite cache when reinitialized", async () => {
+    const [promiseEn, resolveEn] = resolvablePromise<TreeTranslationsData>();
+    tolgee = Tolgee({
+      language: 'en',
+      staticData: {
+        en: () => promiseEn,
+      },
+    });
+    tolgee.run();
+    await Promise.resolve();
+    tolgee.use(DevToolsPlugin());
+    await waitForInitialLoad(tolgee);
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+    resolveEn({ test: { sub: 'Invalid' } });
+    await Promise.resolve();
+    expect(tolgee.t('test.sub')).toEqual('en.default');
+  });
+});