@tolgee/core 5.0.0-rc.9be0f0e.0 → 5.0.0

package/src/Controller/Events/EventEmitterSelective.ts

@@ -0,0 +1,132 @@
+import { getFallbackArray } from '../../helpers';
+import {
+  NsFallback,
+  Subscription,
+  Listener,
+  ListenerEvent,
+  SubscriptionSelective,
+  NsType,
+} from '../../types';
+
+type NsListType = string;
+
+type HandlerWrapperType = {
+  fn: Listener<undefined>;
+  namespaces: Set<string>;
+};
+
+export const EventEmitterSelective = (
+  isActive: () => boolean,
+  getFallbackNs: () => string[],
+  getDefaultNs: () => string
+): EventEmitterSelectiveInstance => {
+  const listeners: Set<Listener<undefined>> = new Set();
+  const partialListeners: Set<HandlerWrapperType> = new Set();
+
+  const listen = (handler: Listener<undefined>) => {
+    listeners.add(handler);
+    const result = {
+      unsubscribe: () => {
+        listeners.delete(handler);
+      },
+    };
+    return result;
+  };
+
+  const listenSome = (handler: Listener<undefined>) => {
+    const handlerWrapper = {
+      fn: (e: ListenerEvent<undefined>) => {
+        handler(e);
+      },
+      namespaces: new Set<NsListType>(),
+    };
+
+    partialListeners.add(handlerWrapper);
+
+    const result = {
+      unsubscribe: () => {
+        partialListeners.delete(handlerWrapper);
+      },
+      subscribeNs: (ns: NsFallback) => {
+        getFallbackArray(ns).forEach((val) =>
+          handlerWrapper.namespaces.add(val)
+        );
+        if (ns === undefined) {
+          // subscribing to default ns
+          handlerWrapper.namespaces.add(getDefaultNs());
+        }
+        return result;
+      },
+    };
+
+    return result;
+  };
+
+  const callHandlers = (ns: Array<string> | undefined) => {
+    // everything is implicitly subscribed to fallbacks
+    // as it can always fall through to it
+    const fallbackNamespaces = new Set(getFallbackNs());
+
+    partialListeners.forEach((handler) => {
+      const nsMatches =
+        ns === undefined ||
+        ns?.findIndex(
+          (ns) => fallbackNamespaces.has(ns) || handler.namespaces.has(ns!)
+        ) !== -1;
+
+      if (nsMatches) {
+        handler.fn({ value: undefined as any });
+      }
+    });
+  };
+
+  let queue: (string[] | undefined)[] = [];
+  // merge events in queue into one event
+  const solveQueue = () => {
+    if (queue.length === 0) {
+      return;
+    }
+    const queueCopy = queue;
+    queue = [];
+
+    listeners.forEach((handler) => {
+      handler({ value: undefined as any });
+    });
+
+    let namespaces: Set<NsType> | undefined = new Set<NsType>();
+
+    queueCopy.forEach((ns) => {
+      if (ns === undefined) {
+        // when no ns specified, it affects all namespaces
+        namespaces = undefined;
+      } else if (namespaces !== undefined) {
+        ns.forEach((ns) => namespaces!.add(ns));
+      }
+    });
+
+    const namespacesArray = namespaces
+      ? Array.from(namespaces.keys())
+      : undefined;
+
+    callHandlers(namespacesArray);
+  };
+
+  const emit = (ns?: string[], delayed?: boolean) => {
+    if (isActive()) {
+      queue.push(ns);
+      if (!delayed) {
+        solveQueue();
+      } else {
+        setTimeout(solveQueue, 0);
+      }
+    }
+  };
+
+  return Object.freeze({ listenSome, listen, emit });
+};
+
+export type EventEmitterSelectiveInstance = {
+  readonly listenSome: (handler: Listener<undefined>) => SubscriptionSelective;
+  readonly listen: (handler: Listener<undefined>) => Subscription;
+  readonly emit: (ns?: string[], delayed?: boolean) => void;
+};

package/src/Controller/Events/Events.ts

@@ -0,0 +1,69 @@
+import { EventEmitter } from './EventEmitter';
+import { EventEmitterSelective } from './EventEmitterSelective';
+import { CacheDescriptorWithKey, TolgeeOn } from '../../types';
+
+export const Events = (
+  getFallbackNs: () => string[],
+  getDefaultNs: () => string
+) => {
+  let emitterActive = true;
+
+  function isActive() {
+    return emitterActive;
+  }
+
+  const onPendingLanguageChange = EventEmitter<string>(isActive);
+  const onLanguageChange = EventEmitter<string>(isActive);
+  const onLoadingChange = EventEmitter<boolean>(isActive);
+  const onFetchingChange = EventEmitter<boolean>(isActive);
+  const onInitialLoaded = EventEmitter<void>(isActive);
+  const onRunningChange = EventEmitter<boolean>(isActive);
+  const onCacheChange = EventEmitter<CacheDescriptorWithKey>(isActive);
+  const onUpdate = EventEmitterSelective(isActive, getFallbackNs, getDefaultNs);
+
+  onInitialLoaded.listen(() => onUpdate.emit());
+  onLanguageChange.listen(() => onUpdate.emit());
+  onCacheChange.listen(({ value }) => {
+    onUpdate.emit([value.namespace], true);
+  });
+
+  const on: TolgeeOn = (event, handler): any => {
+    switch (event) {
+      case 'pendingLanguage':
+        return onPendingLanguageChange.listen(handler as any);
+      case 'language':
+        return onLanguageChange.listen(handler as any);
+      case 'loading':
+        return onLoadingChange.listen(handler as any);
+      case 'fetching':
+        return onFetchingChange.listen(handler as any);
+      case 'initialLoad':
+        return onInitialLoaded.listen(handler as any);
+      case 'running':
+        return onRunningChange.listen(handler as any);
+      case 'cache':
+        return onCacheChange.listen(handler as any);
+      case 'update':
+        return onUpdate.listen(handler as any);
+    }
+  };
+
+  function setEmmiterActive(active: boolean) {
+    emitterActive = active;
+  }
+
+  return Object.freeze({
+    onPendingLanguageChange,
+    onLanguageChange,
+    onLoadingChange,
+    onFetchingChange,
+    onInitialLoaded,
+    onRunningChange,
+    onCacheChange,
+    onUpdate,
+    setEmmiterActive,
+    on,
+  });
+};
+
+export type EventsInstance = ReturnType<typeof Events>;

package/src/Controller/Plugins/Plugins.ts

@@ -1,86 +1,68 @@
-import { isPromise, missingOptionError, valueOrPromise } from '../../helpers';
+import { getErrorMessage, isPromise, valueOrPromise } from '../../helpers';
 import {
-  BackendDevInterface,
+  BackendDevMiddleware,
   BackendGetRecord,
-  BackendInterface,
-  FormatterInterface,
-  ObserverInterface,
+  BackendMiddleware,
+  FormatterMiddleware,
+  ObserverMiddleware,
   TranslatePropsInternal,
   TranslationOnClick,
-  UiInterface,
-  UiLibInterface,
-  UiType,
-  FinalFormatterInterface,
+  UiMiddleware,
+  FinalFormatterMiddleware,
   HighlightInterface,
-  UiConstructor,
   UiKeyOption,
-  LanguageDetectorInterface,
-  LanguageStorageInterface,
-  Options,
+  LanguageDetectorMiddleware,
+  LanguageStorageMiddleware,
   ChangeTranslationInterface,
   WrapperWrapProps,
   Unwrapped,
+  KeyAndNamespacesInternal,
+  TolgeePlugin,
+  TolgeeInstance,
+  TolgeeOptionsInternal,
+  FormatErrorHandler,
 } from '../../types';
-import { getFallbackArray } from '../State/helpers';
+import { DEFAULT_FORMAT_ERROR } from '../State/initState';
 
-export const PluginService = (
+export const Plugins = (
   getLanguage: () => string | undefined,
-  getInitialOptions: () => Options,
+  getInitialOptions: () => TolgeeOptionsInternal,
   getAvailableLanguages: () => string[] | undefined,
-  getTranslationNs: (props: TranslatePropsInternal) => string[] | string,
-  getTranslation: (props: TranslatePropsInternal) => string | undefined,
+  getTranslationNs: (props: KeyAndNamespacesInternal) => string[],
+  getTranslation: (props: KeyAndNamespacesInternal) => string | undefined,
   changeTranslation: ChangeTranslationInterface
 ) => {
   const plugins = {
-    ui: undefined as UiConstructor | undefined,
+    ui: undefined as UiMiddleware | undefined,
+    observer: undefined as ObserverMiddleware | undefined,
   };
 
   const instances = {
-    formatters: [] as FormatterInterface[],
-    finalFormatter: undefined as FinalFormatterInterface | undefined,
-    observer: undefined as ReturnType<ObserverInterface> | undefined,
-    devBackend: undefined as BackendDevInterface | undefined,
-    backends: [] as BackendInterface[],
-    ui: undefined as UiInterface | undefined,
-    languageDetector: undefined as LanguageDetectorInterface | undefined,
-    languageStorage: undefined as LanguageStorageInterface | undefined,
+    formatters: [] as FormatterMiddleware[],
+    finalFormatter: undefined as FinalFormatterMiddleware | undefined,
+    observer: undefined as ReturnType<ObserverMiddleware> | undefined,
+    devBackend: undefined as BackendDevMiddleware | undefined,
+    backends: [] as BackendMiddleware[],
+    ui: undefined as ReturnType<UiMiddleware> | undefined,
+    languageDetector: undefined as LanguageDetectorMiddleware | undefined,
+    languageStorage: undefined as LanguageStorageMiddleware | undefined,
   };
 
-  const onClick: TranslationOnClick = async (event, { keysAndDefaults }) => {
+  const onClick: TranslationOnClick = async ({ keysAndDefaults, event }) => {
     const withNs: UiKeyOption[] = keysAndDefaults.map(
-      ({ key, ns, defaultValue }) => ({
-        key,
-        defaultValue,
-        ns: getFallbackArray(getTranslationNs({ key, ns, defaultValue })),
-        translation: getTranslation({
+      ({ key, ns, defaultValue }) => {
+        return {
           key,
-          ns,
-        }),
-      })
-    );
-    instances.ui?.handleElementClick(event, withNs);
-  };
-
-  const run = () => {
-    instances.ui =
-      plugins.ui &&
-      new plugins.ui({
-        apiKey: getInitialOptions().apiKey!,
-        apiUrl: getInitialOptions().apiUrl!,
-        highlight,
-        changeTranslation,
-      });
-    instances.observer?.run({ mouseHighlight: Boolean(instances.ui) });
-    checkCorrectConfiguration();
-  };
-
-  const checkCorrectConfiguration = () => {
-    if (instances.languageDetector) {
-      const availableLanguages = getAvailableLanguages();
-      if (!availableLanguages) {
-        throw new Error(missingOptionError('availableLanguages'));
+          defaultValue,
+          ns: getTranslationNs({ key, ns }),
+          translation: getTranslation({
+            key,
+            ns,
+          }),
+        };
       }
-    }
+    );
+    instances.ui?.handleElementClick(withNs, event);
   };
 
   const stop = () => {
@@ -93,54 +75,65 @@ export const PluginService = (
   };
 
   const translate = (props: TranslatePropsInternal) => {
-    const translation = getTranslation(props);
+    const translation = getTranslation({
+      key: props.key,
+      ns: props.ns,
+    });
     return formatTranslation({ ...props, translation, formatEnabled: true });
   };
 
-  const setObserver = (observer: ObserverInterface | undefined) => {
-    instances.observer = observer?.({ translate, onClick });
+  const setObserver = (observer: ObserverMiddleware | undefined) => {
+    plugins.observer = observer;
   };
 
-  const getObserver = () => {
-    return instances.observer;
+  const hasObserver = () => {
+    return Boolean(plugins.observer);
   };
 
-  const addFormatter = (formatter: FormatterInterface | undefined) => {
+  const addFormatter = (formatter: FormatterMiddleware | undefined) => {
     if (formatter) {
       instances.formatters.push(formatter);
     }
   };
 
   const setFinalFormatter = (
-    formatter: FinalFormatterInterface | undefined
+    formatter: FinalFormatterMiddleware | undefined
   ) => {
     instances.finalFormatter = formatter;
   };
 
-  const setUi = (ui: UiType | undefined) => {
-    plugins.ui = (ui as UiLibInterface)?.UI || ui;
+  const setUi = (ui: UiMiddleware | undefined) => {
+    plugins.ui = ui as UiMiddleware;
   };
 
-  const getUi = () => {
-    return plugins.ui;
+  const hasUi = () => {
+    return Boolean(plugins.ui);
   };
 
   const setLanguageStorage = (
-    storage: LanguageStorageInterface | undefined
+    storage: LanguageStorageMiddleware | undefined
   ) => {
     instances.languageStorage = storage;
   };
 
+  const getLanguageStorage = () => {
+    return instances.languageStorage;
+  };
+
   const setStoredLanguage = (language: string) => {
     instances.languageStorage?.setLanguage(language);
   };
 
   const setLanguageDetector = (
-    detector: LanguageDetectorInterface | undefined
+    detector: LanguageDetectorMiddleware | undefined
   ) => {
     instances.languageDetector = detector;
   };
 
+  const getLanguageDetector = () => {
+    return instances.languageDetector;
+  };
+
   const detectLanguage = () => {
     if (!instances.languageDetector) {
       return undefined;
@@ -168,24 +161,47 @@ export const PluginService = (
     });
   };
 
-  const addBackend = (backend: BackendInterface | undefined) => {
+  const addBackend = (backend: BackendMiddleware | undefined) => {
     if (backend) {
       instances.backends.push(backend);
     }
   };
 
-  const setDevBackend = (backend: BackendDevInterface | undefined) => {
+  const setDevBackend = (backend: BackendDevMiddleware | undefined) => {
     instances.devBackend = backend;
   };
 
+  const run = () => {
+    if (!instances.ui) {
+      const { apiKey, apiUrl, projectId } = getInitialOptions();
+      instances.ui = plugins.ui?.({
+        apiKey: apiKey!,
+        apiUrl: apiUrl!,
+        projectId,
+        highlight,
+        changeTranslation,
+      });
+    }
+    if (!instances.observer) {
+      instances.observer = plugins.observer?.({
+        translate,
+        onClick,
+        options: getInitialOptions().observerOptions,
+      });
+    }
+    instances.observer?.run({ mouseHighlight: true });
+  };
+
   const getDevBackend = () => {
     return instances.devBackend;
   };
 
   const getBackendDevRecord: BackendGetRecord = ({ language, namespace }) => {
+    const { apiKey, apiUrl, projectId } = getInitialOptions();
     return instances.devBackend?.getRecord({
-      apiKey: getInitialOptions().apiKey,
-      apiUrl: getInitialOptions().apiUrl,
+      apiKey,
+      apiUrl,
+      projectId,
       language,
       namespace,
     });
@@ -208,55 +224,105 @@ export const PluginService = (
     return undefined;
   };
 
-  const formatTranslation = ({
-    key,
-    translation,
-    defaultValue,
-    noWrap,
-    params,
-    orEmpty,
-    ns,
+  const unwrap = (text: string): Unwrapped => {
+    if (instances.observer) {
+      return instances.observer?.unwrap(text);
+    }
+    return { text, keys: [] };
+  };
+
+  const retranslate = () => {
+    instances.observer?.retranslate();
+  };
+
+  function addPlugin(tolgeeInstance: TolgeeInstance, plugin: TolgeePlugin) {
+    const pluginTools = Object.freeze({
+      setFinalFormatter,
+      addFormatter,
+      setObserver,
+      hasObserver,
+      setUi,
+      hasUi,
+      setDevBackend,
+      addBackend,
+      setLanguageDetector,
+      setLanguageStorage,
+    });
+    plugin(tolgeeInstance, pluginTools);
+  }
+
+  function formatTranslation({
     formatEnabled,
-  }: TranslatePropsInternal & { formatEnabled?: boolean }) => {
+    ...props
+  }: TranslatePropsInternal & { formatEnabled?: boolean }) {
+    const { key, translation, defaultValue, noWrap, params, orEmpty, ns } =
+      props;
     const formattableTranslation = translation || defaultValue;
     let result = formattableTranslation || (orEmpty ? '' : key);
-    if (instances.observer && !noWrap) {
-      result = instances.observer.wrap({
-        key,
-        translation: result,
-        defaultValue,
-        params,
-        ns,
-      });
-    }
 
     const language = getLanguage();
     const isFormatEnabled =
       formatEnabled || !instances.observer?.outputNotFormattable;
-    if (formattableTranslation && language && isFormatEnabled) {
-      for (const formatter of instances.formatters) {
-        result = formatter.format({
+
+    const wrap = (result: string) => {
+      if (instances.observer && !noWrap) {
+        return instances.observer.wrap({
+          key,
+          translation: result,
+          defaultValue,
+          params,
+          ns,
+        });
+      }
+      return result;
+    };
+
+    result = wrap(result);
+    try {
+      if (formattableTranslation && language && isFormatEnabled) {
+        for (const formatter of instances.formatters) {
+          result = formatter.format({
+            translation: result,
+            language,
+            params,
+          });
+        }
+      }
+      if (
+        instances.finalFormatter &&
+        formattableTranslation &&
+        language &&
+        isFormatEnabled
+      ) {
+        result = instances.finalFormatter.format({
           translation: result,
           language,
           params,
         });
       }
+    } catch (e: any) {
+      // eslint-disable-next-line no-console
+      console.error(e);
+      const errorMessage = getErrorMessage(e) || DEFAULT_FORMAT_ERROR;
+      const onFormatError = getInitialOptions().onFormatError;
+      const formatErrorType = typeof onFormatError;
+      if (formatErrorType === 'string') {
+        result = onFormatError as string;
+      } else if (formatErrorType === 'function') {
+        result = (onFormatError as FormatErrorHandler)(errorMessage, props);
+      } else {
+        result = DEFAULT_FORMAT_ERROR;
+      }
+      // wrap error message, so it's detectable
+      result = wrap(result);
     }
 
-    if (
-      instances.finalFormatter &&
-      formattableTranslation &&
-      language &&
-      isFormatEnabled
-    ) {
-      result = instances.finalFormatter.format({
-        translation: result,
-        language,
-        params,
-      });
-    }
     return result;
-  };
+  }
+
+  function hasDevBackend() {
+    return Boolean(getDevBackend());
+  }
 
   const wrap = (params: WrapperWrapProps) => {
     if (instances.observer) {
@@ -265,41 +331,24 @@ export const PluginService = (
     return params.translation;
   };
 
-  const unwrap = (text: string): Unwrapped => {
-    if (instances.observer) {
-      return instances.observer?.unwrap(text);
-    }
-    return { text, keys: [] };
-  };
-
-  const retranslate = () => {
-    instances.observer?.retranslate();
-  };
-
   return Object.freeze({
-    setFinalFormatter,
-    addFormatter,
+    addPlugin,
     formatTranslation,
-    setObserver,
-    getObserver,
-    setUi,
-    getUi,
-    addBackend,
-    setDevBackend,
     getDevBackend,
     getBackendRecord,
     getBackendDevRecord,
-    setLanguageDetector,
-    setLanguageStorage,
+    getLanguageDetector,
+    getLanguageStorage,
     getInitialLanguage,
     setStoredLanguage,
     run,
     stop,
     retranslate,
     highlight,
-    wrap,
     unwrap,
+    wrap,
+    hasDevBackend,
   });
 };
 
-export type PluginServiceType = ReturnType<typeof PluginService>;
+export type PluginsInstance = ReturnType<typeof Plugins>;