@tolgee/core 4.9.2 → 4.9.3-rc.04b22e6.0

package/src/Controller/Cache/Cache.ts

@@ -0,0 +1,296 @@
+import {
+  CacheAsyncRequests,
+  CacheDescriptor,
+  CacheDescriptorInternal,
+  CacheDescriptorWithKey,
+  EventEmitterInstance,
+  FallbackNSTranslation,
+  Options,
+  TranslationsFlat,
+  TranslationValue,
+  TreeTranslationsData,
+  BackendGetRecord,
+  BackendGetDevRecord,
+} from '../../types';
+import { getFallbackArray } from '../State/helpers';
+import { ValueObserverInstance } from '../ValueObserver';
+
+import { decodeCacheKey, encodeCacheKey, flattenTranslations } from './helpers';
+
+type CacheRecord = {
+  version: number;
+  data: TranslationsFlat;
+};
+
+type StateCache = Map<string, CacheRecord>;
+
+export const Cache = (
+  onCacheChange: EventEmitterInstance<CacheDescriptorWithKey>,
+  backendGetRecord: BackendGetRecord,
+  backendGetDevRecord: BackendGetDevRecord,
+  withDefaultNs: (descriptor: CacheDescriptor) => CacheDescriptorInternal,
+  isInitialLoading: () => boolean,
+  fetchingObserver: ValueObserverInstance<boolean>,
+  loadingObserver: ValueObserverInstance<boolean>
+) => {
+  const asyncRequests: CacheAsyncRequests = new Map();
+  const cache: StateCache = new Map();
+  let staticData: NonNullable<Options['staticData']> = {};
+  let version = 0;
+
+  function addStaticData(data: Options['staticData']) {
+    if (data) {
+      staticData = { ...staticData, ...data };
+      Object.entries(data).forEach(([key, value]) => {
+        if (typeof value !== 'function') {
+          const descriptor = decodeCacheKey(key);
+          const existing = cache.get(key);
+          if (!existing || existing.version === 0) {
+            addRecordInternal(descriptor, value, 0);
+          }
+        }
+      });
+    }
+  }
+
+  function invalidate() {
+    asyncRequests.clear();
+    version += 1;
+  }
+
+  function addRecordInternal(
+    descriptor: CacheDescriptorInternal,
+    data: TreeTranslationsData,
+    recordVersion: number
+  ) {
+    const cacheKey = encodeCacheKey(descriptor);
+    cache.set(cacheKey, {
+      data: flattenTranslations(data),
+      version: recordVersion,
+    });
+    onCacheChange.emit(descriptor);
+  }
+
+  function addRecord(
+    descriptor: CacheDescriptorInternal,
+    data: TreeTranslationsData
+  ) {
+    addRecordInternal(descriptor, data, version);
+  }
+
+  function exists(descriptor: CacheDescriptorInternal, strict = false) {
+    const record = cache.get(encodeCacheKey(descriptor));
+    if (record && strict) {
+      return record.version === version;
+    }
+    return Boolean(record);
+  }
+
+  function getRecord(descriptor: CacheDescriptor) {
+    return cache.get(encodeCacheKey(withDefaultNs(descriptor)))?.data;
+  }
+
+  function getTranslation(descriptor: CacheDescriptorInternal, key: string) {
+    return cache.get(encodeCacheKey(descriptor))?.data.get(key);
+  }
+
+  function getTranslationNs(
+    namespaces: string[],
+    languages: string[],
+    key: string
+  ) {
+    for (const namespace of namespaces) {
+      for (const language of languages) {
+        const value = cache
+          .get(encodeCacheKey({ language, namespace }))
+          ?.data.get(key);
+        if (value !== undefined && value !== null) {
+          return namespace;
+        }
+      }
+    }
+    return Array.from(new Set(namespaces));
+  }
+
+  function getTranslationFallback(
+    namespaces: string[],
+    languages: string[],
+    key: string
+  ) {
+    for (const namespace of namespaces) {
+      for (const language of languages) {
+        const value = cache
+          .get(encodeCacheKey({ language, namespace }))
+          ?.data.get(key);
+        if (value !== undefined && value !== null) {
+          return value;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  function changeTranslation(
+    descriptor: CacheDescriptorInternal,
+    key: string,
+    value: TranslationValue
+  ) {
+    const record = cache.get(encodeCacheKey(descriptor))?.data;
+    record?.set(key, value);
+    onCacheChange.emit({ ...descriptor, key });
+  }
+
+  function isFetching(ns?: FallbackNSTranslation) {
+    if (isInitialLoading()) {
+      return true;
+    }
+
+    if (ns === undefined) {
+      return asyncRequests.size > 0;
+    }
+    const namespaces = getFallbackArray(ns);
+    return Boolean(
+      Array.from(asyncRequests.keys()).find((key) =>
+        namespaces.includes(decodeCacheKey(key).namespace)
+      )
+    );
+  }
+
+  function isLoading(language: string | undefined, ns?: FallbackNSTranslation) {
+    const namespaces = getFallbackArray(ns);
+
+    return Boolean(
+      isInitialLoading() ||
+        Array.from(asyncRequests.keys()).find((key) => {
+          const descriptor = decodeCacheKey(key);
+          return (
+            (!namespaces.length || namespaces.includes(descriptor.namespace)) &&
+            !exists({
+              namespace: descriptor.namespace,
+              language: language!,
+            })
+          );
+        })
+    );
+  }
+
+  function fetchNormal(keyObject: CacheDescriptorInternal) {
+    let dataPromise = undefined as
+      | Promise<TreeTranslationsData | undefined>
+      | undefined;
+    if (!dataPromise) {
+      const staticDataValue = staticData[encodeCacheKey(keyObject)];
+      if (typeof staticDataValue === 'function') {
+        dataPromise = staticDataValue();
+      } else if (staticDataValue) {
+        dataPromise = Promise.resolve(staticDataValue);
+      }
+    }
+
+    if (!dataPromise) {
+      dataPromise = backendGetRecord(keyObject);
+    }
+
+    if (!dataPromise) {
+      // return current data or empty object
+      dataPromise = Promise.resolve({});
+    }
+
+    return dataPromise;
+  }
+
+  function fetchData(keyObject: CacheDescriptorInternal, isDev: boolean) {
+    let dataPromise = undefined as
+      | Promise<TreeTranslationsData | undefined>
+      | undefined;
+    if (isDev) {
+      dataPromise = backendGetDevRecord(keyObject)?.catch(() => {
+        // eslint-disable-next-line no-console
+        console.warn(`Tolgee: Failed to fetch data from dev backend`);
+        // fallback to normal fetch if dev fails
+        return fetchNormal(keyObject);
+      });
+    }
+
+    if (!dataPromise) {
+      dataPromise = fetchNormal(keyObject);
+    }
+
+    return dataPromise;
+  }
+
+  async function loadRecords(descriptors: CacheDescriptor[], isDev: boolean) {
+    const withPromises = descriptors.map((descriptor) => {
+      const keyObject = withDefaultNs(descriptor);
+      const cacheKey = encodeCacheKey(keyObject);
+      const existingPromise = asyncRequests.get(cacheKey);
+
+      if (existingPromise) {
+        return {
+          new: false,
+          promise: existingPromise,
+          keyObject,
+          cacheKey,
+        };
+      }
+      const dataPromise = fetchData(keyObject, isDev);
+      asyncRequests.set(cacheKey, dataPromise);
+      return {
+        new: true,
+        promise: dataPromise,
+        keyObject,
+        cacheKey,
+      };
+    });
+    fetchingObserver.notify();
+    loadingObserver.notify();
+
+    const results = await Promise.all(withPromises.map((val) => val.promise));
+
+    withPromises.forEach((value, i) => {
+      const promiseChanged =
+        asyncRequests.get(value.cacheKey) !== value.promise;
+      // if promise has changed in between, it means cache been invalidated or
+      // new data are being fetched
+      if (value.new && !promiseChanged) {
+        asyncRequests.delete(value.cacheKey);
+        const data = results[i];
+        if (data) {
+          addRecord(value.keyObject, data);
+        }
+      }
+    });
+    fetchingObserver.notify();
+    loadingObserver.notify();
+
+    return withPromises.map((val) => getRecord(val.keyObject)!);
+  }
+
+  function getAllRecords() {
+    const entries = Array.from(cache.entries());
+    return entries.map(([key, entry]) => {
+      return {
+        ...decodeCacheKey(key),
+        data: entry.data,
+      };
+    });
+  }
+
+  return Object.freeze({
+    addStaticData,
+    invalidate,
+    addRecord,
+    exists,
+    getRecord,
+    getTranslation,
+    getTranslationNs,
+    getTranslationFallback,
+    changeTranslation,
+    isFetching,
+    isLoading,
+    loadRecords,
+    getAllRecords,
+  });
+};
+
+export type CacheType = ReturnType<typeof Cache>;

package/src/Controller/Cache/helpers.ts

@@ -0,0 +1,37 @@
+import { CacheDescriptorInternal, TreeTranslationsData } from '../../types';
+
+export const flattenTranslations = (
+  data: TreeTranslationsData
+): Map<string, string> => {
+  const result: Map<string, string> = new Map();
+  Object.entries(data).forEach(([key, value]) => {
+    // ignore empty values
+    if (value === undefined || value === null) {
+      return;
+    }
+    if (typeof value === 'object') {
+      flattenTranslations(value).forEach((flatValue, flatKey) => {
+        result.set(key + '.' + flatKey, flatValue);
+      });
+      return;
+    }
+    result.set(key, value as string);
+  });
+  return result;
+};
+
+export const decodeCacheKey = (key: string): CacheDescriptorInternal => {
+  const [firstPart, secondPart] = key.split(':');
+  return { language: firstPart, namespace: secondPart || '' };
+};
+
+export const encodeCacheKey = ({
+  language,
+  namespace,
+}: CacheDescriptorInternal) => {
+  if (namespace) {
+    return `${language}:${namespace}`;
+  } else {
+    return language;
+  }
+};

package/src/Controller/Controller.ts

@@ -0,0 +1,310 @@
+import { Events } from './Events/Events';
+import {
+  CacheDescriptor,
+  FallbackNSTranslation,
+  Options,
+  TFnType,
+  TranslatePropsInternal,
+} from '../types';
+import { Cache } from './Cache/Cache';
+import { getFallbackArray } from './State/helpers';
+import { PluginService } from './Plugins/Plugins';
+import { ValueObserver } from './ValueObserver';
+import { State } from './State/State';
+import { isPromise, missingOptionError, valueOrPromise } from '../helpers';
+import { getTranslateParams } from '../TranslateParams';
+
+type StateServiceProps = {
+  options?: Partial<Options>;
+};
+
+export const Controller = ({ options }: StateServiceProps) => {
+  const events = Events(getFallbackNamespaces);
+  const fetchingObserver = ValueObserver<boolean>(
+    false,
+    () => cache.isFetching(),
+    events.onFetchingChange.emit
+  );
+  const loadingObserver = ValueObserver<boolean>(
+    false,
+    () => isLoading(),
+    events.onLoadingChange.emit
+  );
+
+  const state = State(
+    events.onLanguageChange,
+    events.onPendingLanguageChange,
+    events.onRunningChange
+  );
+
+  const pluginService = PluginService(
+    state.getLanguage,
+    state.getInitialOptions,
+    state.getObserverOptions,
+    state.getAvailableLanguages,
+    getTranslationNs,
+    getTranslation,
+    changeTranslation
+  );
+
+  const cache = Cache(
+    events.onCacheChange,
+    pluginService.getBackendRecord,
+    pluginService.getBackendDevRecord,
+    state.withDefaultNs,
+    state.isInitialLoading,
+    fetchingObserver,
+    loadingObserver
+  );
+
+  if (options) {
+    init(options);
+  }
+
+  events.onKeyUpdate.listen(() => {
+    if (state.isRunning()) {
+      pluginService.retranslate();
+    }
+  });
+
+  function changeTranslation(
+    descriptor: CacheDescriptor,
+    key: string,
+    value: string
+  ) {
+    const keyObject = state.withDefaultNs(descriptor);
+    const previousValue = cache.getTranslation(keyObject, key);
+    cache.changeTranslation(keyObject, key, value);
+    return {
+      revert: () => {
+        cache.changeTranslation(keyObject, key, previousValue);
+      },
+    };
+  }
+
+  function getFallbackNamespaces() {
+    return state.getFallbackNamespaces();
+  }
+
+  function init(options: Partial<Options>) {
+    state.init(options);
+    cache.addStaticData(state.getInitialOptions().staticData);
+  }
+
+  function isLoading(ns?: FallbackNSTranslation) {
+    return cache.isLoading(state.getLanguage()!, ns);
+  }
+
+  function isDev() {
+    return Boolean(
+      state.getInitialOptions().apiKey &&
+        state.getInitialOptions().apiUrl &&
+        pluginService.getDevBackend()
+    );
+  }
+
+  async function addActiveNs(ns: FallbackNSTranslation, forget?: boolean) {
+    if (!forget) {
+      state.addActiveNs(ns);
+    }
+    if (state.isRunning()) {
+      await loadRequiredRecords(undefined, ns);
+    }
+  }
+
+  function getRequiredRecords(lang?: string, ns?: FallbackNSTranslation) {
+    const languages = state.getFallbackLangs(lang);
+    const namespaces =
+      ns !== undefined ? getFallbackArray(ns) : state.getRequiredNamespaces();
+    const result: CacheDescriptor[] = [];
+    languages.forEach((language) => {
+      namespaces.forEach((namespace) => {
+        if (!cache.exists({ language, namespace }, true)) {
+          result.push({ language, namespace });
+        }
+      });
+    });
+    return result;
+  }
+
+  function isLoaded(ns?: FallbackNSTranslation) {
+    const language = state.getLanguage();
+    if (!language) {
+      return false;
+    }
+    const languages = state.getFallbackLangs(language);
+    const namespaces =
+      ns !== undefined ? getFallbackArray(ns) : state.getRequiredNamespaces();
+    const result: CacheDescriptor[] = [];
+    languages.forEach((language) => {
+      namespaces.forEach((namespace) => {
+        if (!cache.exists({ language, namespace })) {
+          result.push({ language, namespace });
+        }
+      });
+    });
+    return result.length === 0;
+  }
+
+  function loadRequiredRecords(lang?: string, ns?: FallbackNSTranslation) {
+    const descriptors = getRequiredRecords(lang, ns);
+    if (descriptors.length) {
+      return valueOrPromise(loadRecords(descriptors), () => {});
+    }
+  }
+
+  async function changeLanguage(language: string) {
+    if (
+      state.getPendingLanguage() === language &&
+      state.getLanguage() === language
+    ) {
+      return;
+    }
+    state.setPendingLanguage(language);
+
+    if (state.isRunning()) {
+      await loadRequiredRecords(language);
+    }
+
+    if (language === state.getPendingLanguage()) {
+      // there might be parallel language change
+      // we only want to apply latest
+      state.setLanguage(language);
+      pluginService.setStoredLanguage(language);
+    }
+  }
+
+  function getTranslationNs({
+    key,
+    ns,
+  }: Pick<TranslatePropsInternal, 'key' | 'ns'>) {
+    const namespaces =
+      ns !== undefined ? getFallbackArray(ns) : state.getFallbackNamespaces();
+    const languages = state.getFallbackLangs();
+    return cache.getTranslationNs(namespaces, languages, key);
+  }
+
+  function getTranslation({
+    key,
+    ns,
+  }: Pick<TranslatePropsInternal, 'key' | 'ns'>) {
+    const namespaces =
+      ns !== undefined ? getFallbackArray(ns) : state.getFallbackNamespaces();
+    const languages = state.getFallbackLangs();
+    return cache.getTranslationFallback(namespaces, languages, key);
+  }
+
+  function loadInitial() {
+    const data = valueOrPromise(initializeLanguage(), () => {
+      // fail if there is no language
+      return loadRequiredRecords();
+    });
+
+    if (isPromise(data)) {
+      state.setInitialLoading(true);
+      fetchingObserver.notify();
+      loadingObserver.notify();
+      return Promise.resolve(data).then(() => {
+        state.setInitialLoading(false);
+        fetchingObserver.notify();
+        loadingObserver.notify();
+        events.onInitialLoaded.emit();
+      });
+    } else {
+      events.onInitialLoaded.emit();
+    }
+  }
+
+  function initializeLanguage() {
+    const existingLanguage = state.getLanguage();
+    if (existingLanguage) {
+      return;
+    }
+    if (!state.getInitialOptions().defaultLanguage) {
+      throw new Error(missingOptionError('defaultLanguage'));
+    }
+    const languageOrPromise = pluginService.getInitialLanguage();
+    return valueOrPromise(languageOrPromise, (lang) => {
+      const language =
+        (lang as string | undefined) ||
+        state.getInitialOptions().defaultLanguage;
+      language && state.setLanguage(language);
+    });
+  }
+
+  async function loadRecord(descriptor: CacheDescriptor) {
+    return (await loadRecords([descriptor]))[0];
+  }
+
+  function loadRecords(descriptors: CacheDescriptor[]) {
+    return cache.loadRecords(descriptors, isDev());
+  }
+
+  const checkCorrectConfiguration = () => {
+    const languageDetector = pluginService.getLanguageDetector();
+    if (languageDetector) {
+      const availableLanguages = state.getAvailableLanguages();
+      if (!availableLanguages) {
+        throw new Error(missingOptionError('availableLanguages'));
+      }
+    }
+    if (!state.getLanguage() && !state.getInitialOptions().defaultLanguage) {
+      if (languageDetector) {
+        throw new Error(missingOptionError('defaultLanguage'));
+      } else {
+        throw new Error(missingOptionError('language'));
+      }
+    }
+  };
+
+  function run() {
+    let result: Promise<void> | undefined = undefined;
+    checkCorrectConfiguration();
+    if (!state.isRunning()) {
+      if (isDev()) {
+        cache.invalidate();
+      }
+      state.setRunning(true);
+      pluginService.run(isDev());
+      result = loadInitial();
+    }
+    return Promise.resolve(result);
+  }
+
+  function stop() {
+    if (state.isRunning()) {
+      pluginService.stop();
+      state.setRunning(false);
+    }
+  }
+
+  const t: TFnType = (...args) => {
+    // @ts-ignore
+    const params = getTranslateParams(...args);
+    const translation = getTranslation(params);
+    return pluginService.formatTranslation({ ...params, translation });
+  };
+
+  return Object.freeze({
+    ...events,
+    ...state,
+    ...pluginService,
+    ...cache,
+    init,
+    changeLanguage,
+    getTranslation,
+    changeTranslation,
+    addActiveNs,
+    loadRequiredRecords,
+    loadRecords,
+    loadRecord,
+    isLoading,
+    isLoaded,
+    t,
+    isDev,
+    run,
+    stop,
+  });
+};
+
+export type StateServiceType = ReturnType<typeof Controller>;

package/src/Controller/Events/EventEmitter.ts

@@ -0,0 +1,30 @@
+import { Listener, ListenerHandler } from '../../types';
+
+export const EventEmitter = <T>(): EventEmitterInstance<T> => {
+  let handlers: ListenerHandler<T>[] = [];
+
+  const listen = (handler: ListenerHandler<T>): Listener => {
+    const handlerWrapper: ListenerHandler<T> = (e) => {
+      handler(e);
+    };
+
+    handlers.push(handlerWrapper);
+
+    return {
+      unsubscribe: () => {
+        handlers = handlers.filter((i) => handlerWrapper !== i);
+      },
+    };
+  };
+
+  const emit = (data: T) => {
+    handlers.forEach((handler) => handler({ value: data }));
+  };
+
+  return Object.freeze({ listen, emit });
+};
+
+export type EventEmitterInstance<T> = {
+  readonly listen: (handler: ListenerHandler<T>) => Listener;
+  readonly emit: (data: T) => void;
+};