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

package/src/Controller/Events/EventEmitterSelective.test.ts

@@ -0,0 +1,125 @@
+import { EventEmitterSelective } from './EventEmitterSelective';
+
+describe('event emitter selective', () => {
+  it('handles correctly fallback namespaces', () => {
+    const emitter = EventEmitterSelective(() => ['a', 'b']);
+    const handler = jest.fn();
+    const listener = emitter.listenSome(handler);
+
+    // subscribe to fallback namespaces
+    listener.subscribeKey({ key: 'test' });
+
+    // emmit
+    emitter.emit({ key: 'test' });
+    emitter.emit({ ns: ['a'] });
+    // should be ignored
+    emitter.emit({ ns: ['c'] });
+
+    expect(handler).toBeCalledTimes(2);
+  });
+
+  it('subscribes to key', () => {
+    const emitter = EventEmitterSelective(() => ['']);
+    const handler = jest.fn();
+    const listener = emitter.listenSome(handler);
+    listener.subscribeKey({ key: 'test' });
+    listener.subscribeKey({ key: 'abcd' });
+
+    emitter.emit({ key: 'test' });
+    emitter.emit({ key: 'youda' });
+    expect(handler).toBeCalledTimes(1);
+    listener.unsubscribe();
+    emitter.emit();
+    expect(handler).toBeCalledTimes(1);
+  });
+
+  it('subscribes to key with namespaces', () => {
+    const emitter = EventEmitterSelective(() => []);
+    const handler = jest.fn();
+    const listener = emitter.listenSome(handler);
+
+    listener.subscribeKey({ key: 'test', ns: 'common' });
+    listener.subscribeKey({ key: 'abcd', ns: ['test', 'abcd'] });
+
+    emitter.emit({ key: 'youda', ns: ['common'] });
+    emitter.emit({ key: 'test', ns: ['youda'] });
+    expect(handler).toBeCalledTimes(0);
+    emitter.emit({ key: 'abcd', ns: ['abcd'] });
+    emitter.emit({ ns: ['test'] });
+    expect(handler).toBeCalledTimes(2);
+    listener.unsubscribe();
+    emitter.emit();
+    expect(handler).toBeCalledTimes(2);
+  });
+
+  it('unsubscribes', () => {
+    const emitter = EventEmitterSelective(() => []);
+    const handler = jest.fn();
+    const listener = emitter.listenSome(handler);
+
+    listener.subscribeKey({ key: 'test', ns: 'common' });
+    listener.subscribeKey({ key: 'abcd', ns: ['test', 'abcd'] });
+
+    emitter.emit({ key: 'youda', ns: ['common'] });
+    emitter.emit({ key: 'test', ns: ['youda'] });
+    expect(handler).toBeCalledTimes(0);
+    emitter.emit({ key: 'abcd', ns: ['abcd'] });
+    emitter.emit({ ns: ['test'] });
+    expect(handler).toBeCalledTimes(2);
+
+    listener.unsubscribeKey({ key: 'abcd', ns: ['test', 'abcd'] });
+    emitter.emit({ key: 'abcd' });
+    emitter.emit({ ns: ['test'] });
+
+    listener.unsubscribe();
+    emitter.emit();
+    expect(handler).toBeCalledTimes(2);
+  });
+
+  it('groups events correctly', async () => {
+    const emitter = EventEmitterSelective(() => ['test', 'opqrst']);
+    const handler = jest.fn();
+    const hanlderAll = jest.fn();
+    const listener = emitter.listenSome(handler);
+    const listenerAll = emitter.listen(hanlderAll);
+
+    listener.subscribeKey({ key: 'abcd', ns: ['test'] });
+
+    emitter.emit({ key: 'abcd' }, true);
+    emitter.emit({ ns: ['opqrst'] }, true);
+
+    await Promise.resolve();
+
+    expect(hanlderAll).toBeCalledTimes(1);
+    expect(handler).toBeCalledTimes(1);
+
+    emitter.emit({ key: 'youda', ns: ['test'] }, true);
+    emitter.emit({ key: 'filda', ns: ['test'] });
+
+    expect(hanlderAll).toBeCalledTimes(2);
+    expect(handler).toBeCalledTimes(1);
+
+    listener.unsubscribe();
+    listenerAll.unsubscribe();
+    emitter.emit();
+  });
+
+  it('subscribes to ns only', async () => {
+    const emitter = EventEmitterSelective(() => ['test', 'youda']);
+    const handler = jest.fn();
+    const listener = emitter.listenSome(handler);
+    listener.subscribeNs(['test']);
+
+    emitter.emit({ key: 'youda' });
+    expect(handler).toBeCalledTimes(1);
+
+    emitter.emit({ ns: ['test'] });
+    expect(handler).toBeCalledTimes(2);
+
+    emitter.emit({ ns: ['youda'] });
+    expect(handler).toBeCalledTimes(2);
+
+    emitter.emit({ key: 'youda', ns: ['youda'] });
+    expect(handler).toBeCalledTimes(2);
+  });
+});

package/src/Controller/Events/EventEmitterSelective.ts

@@ -0,0 +1,188 @@
+import { getFallbackArray } from '../State/helpers';
+import {
+  FallbackNSTranslation,
+  KeyDescriptor,
+  KeyDescriptorInternal,
+  Listener,
+  ListenerHandler,
+  ListenerHandlerEvent,
+  ListenerSelective,
+} from '../../types';
+
+type HandlerWrapperType = {
+  fn: ListenerHandler<undefined>;
+  keys: Map<string, number>;
+  namespaces: Map<string | undefined, number>;
+};
+
+function incrementInMap(map: Map<any, number>, value: any) {
+  const currNum = map.get(value) || 0;
+  map.set(value, currNum + 1);
+}
+
+function decrementInMap(map: Map<any, number>, value: any) {
+  let currNum = map.get(value) || 1;
+  currNum -= 1;
+  if (currNum <= 0) {
+    map.delete(value);
+  } else {
+    map.set(value, currNum);
+  }
+}
+
+export const EventEmitterSelective = (
+  getFallbackNamespaces: () => string[]
+): EventEmitterSelectiveInstance => {
+  const listeners: Set<ListenerHandler<undefined>> = new Set();
+  const partialListeners: Set<HandlerWrapperType> = new Set();
+
+  const listen = (handler: ListenerHandler<undefined>) => {
+    listeners.add(handler);
+    const result = {
+      unsubscribe: () => {
+        listeners.delete(handler);
+      },
+    };
+    return result;
+  };
+
+  const listenSome = (handler: ListenerHandler<undefined>) => {
+    const handlerWrapper = {
+      fn: (e: ListenerHandlerEvent<undefined>) => {
+        handler(e);
+      },
+      keys: new Map<string, number>(),
+      namespaces: new Map<string | undefined, number>(),
+    };
+
+    partialListeners.add(handlerWrapper);
+
+    const result = {
+      unsubscribe: () => {
+        partialListeners.delete(handlerWrapper);
+      },
+      subscribeNs: (ns: FallbackNSTranslation) => {
+        getFallbackArray(ns).forEach((val) =>
+          incrementInMap(handlerWrapper.namespaces, val)
+        );
+        return result;
+      },
+      unsubscribeNs: (ns: FallbackNSTranslation) => {
+        getFallbackArray(ns).forEach((val) =>
+          decrementInMap(handlerWrapper.namespaces, val)
+        );
+        return result;
+      },
+      subscribeKey: (descriptor: KeyDescriptor) => {
+        const { key, ns } = descriptor;
+        incrementInMap(handlerWrapper.keys, key);
+        getFallbackArray(ns).forEach((val) =>
+          incrementInMap(handlerWrapper.namespaces, val)
+        );
+        if (ns === undefined) {
+          // subscribing to all namespaces
+          incrementInMap(handlerWrapper.namespaces, undefined);
+        }
+        return result;
+      },
+      unsubscribeKey: (descriptor: KeyDescriptor) => {
+        const { key, ns } = descriptor;
+        decrementInMap(handlerWrapper.keys, key);
+        getFallbackArray(ns).forEach((val) =>
+          decrementInMap(handlerWrapper.namespaces, val)
+        );
+        if (ns === undefined) {
+          // subscribing to all namespaces
+          decrementInMap(handlerWrapper.namespaces, undefined);
+        }
+        return result;
+      },
+    };
+
+    return result;
+  };
+
+  const namespacesWithFallbacks = (
+    namespaces: Map<string | undefined, number> | Set<string | undefined>
+  ) => {
+    if (namespaces.has(undefined)) {
+      const result = new Set(namespaces.keys());
+      result.delete(undefined);
+      getFallbackNamespaces().forEach((ns) => result.add(ns));
+      return result as Set<string>;
+    }
+    return namespaces as Map<string, number>;
+  };
+
+  const callHandlers = (key: string | undefined, ns: string[] | undefined) => {
+    partialListeners.forEach((handler) => {
+      const handlerNamespaces = namespacesWithFallbacks(handler.namespaces);
+      const nsMatches =
+        ns === undefined ||
+        ns?.findIndex((ns) => handlerNamespaces.has(ns)) !== -1;
+      const keyMatches =
+        key === undefined || handler.keys.has(key) || handler.keys.size === 0;
+      if (nsMatches && keyMatches) {
+        handler.fn({ value: undefined as any });
+      }
+    });
+  };
+
+  let queue: (KeyDescriptorInternal | undefined)[] = [];
+  // merge events in queue into one event
+  const solveQueue = () => {
+    if (queue.length === 0) {
+      return;
+    }
+    listeners.forEach((handler) => {
+      handler({ value: undefined as any });
+    });
+
+    const namespaces = new Set<string | undefined>();
+    let keys: Set<string> | undefined = new Set<string>();
+    queue.forEach((descriptor) => {
+      if (descriptor?.ns === undefined) {
+        // when no ns specified, it affets all fallback namespaces
+        namespaces.add(undefined);
+      } else {
+        descriptor.ns.forEach((ns) => namespaces.add(ns));
+      }
+      if (descriptor?.key === undefined) {
+        // when no key specified, it affects all keys
+        keys = undefined;
+      } else if (keys !== undefined) {
+        keys.add(descriptor.key);
+      }
+    });
+    const namespacesArray = Array.from(
+      namespacesWithFallbacks(namespaces).keys()
+    );
+    (keys || [undefined]).forEach((key) => {
+      callHandlers(key, namespacesArray);
+    });
+    queue = [];
+  };
+  const emit = (descriptor?: KeyDescriptorInternal, delayed?: boolean) => {
+    queue.push(descriptor);
+    if (!delayed) {
+      solveQueue();
+    } else {
+      Promise.resolve().then(() => {
+        solveQueue();
+      });
+    }
+  };
+
+  return Object.freeze({ listenSome, listen, emit });
+};
+
+export type EventEmitterSelectiveInstance = {
+  readonly listenSome: (
+    handler: ListenerHandler<undefined>
+  ) => ListenerSelective;
+  readonly listen: (handler: ListenerHandler<undefined>) => Listener;
+  readonly emit: (
+    descriptor?: KeyDescriptorInternal,
+    delayed?: boolean
+  ) => void;
+};

package/src/Controller/Events/Events.ts

@@ -0,0 +1,66 @@
+import { EventEmitter } from './EventEmitter';
+import { EventEmitterSelective } from './EventEmitterSelective';
+import {
+  CacheDescriptorWithKey,
+  KeyDescriptorInternal,
+  ListenerHandler,
+  TolgeeOn,
+} from '../../types';
+
+export const Events = (getFallbackNamespaces: () => string[]) => {
+  const onPendingLanguageChange = EventEmitter<string>();
+  const onLanguageChange = EventEmitter<string>();
+  const onKeyChange = EventEmitter<KeyDescriptorInternal>();
+  const onLoadingChange = EventEmitter<boolean>();
+  const onFetchingChange = EventEmitter<boolean>();
+  const onInitialLoaded = EventEmitter<void>();
+  const onKeyUpdate = EventEmitterSelective(getFallbackNamespaces);
+  const onCacheChange = EventEmitter<CacheDescriptorWithKey>();
+  const onRunningChange = EventEmitter<boolean>();
+
+  onInitialLoaded.listen(() => onKeyUpdate.emit());
+  onLanguageChange.listen(() => onKeyUpdate.emit());
+  onCacheChange.listen(({ value }) => {
+    onKeyUpdate.emit({ ns: [value.namespace], key: value.key }, true);
+  });
+
+  const on: TolgeeOn = (event, handler): any => {
+    switch (event) {
+      case 'pendingLanguage':
+        return onPendingLanguageChange.listen(
+          handler as ListenerHandler<string>
+        );
+      case 'language':
+        return onLanguageChange.listen(handler as ListenerHandler<string>);
+      case 'loading':
+        return onLoadingChange.listen(handler as ListenerHandler<boolean>);
+      case 'fetching':
+        return onFetchingChange.listen(handler as ListenerHandler<boolean>);
+      case 'initialLoad':
+        return onInitialLoaded.listen(handler as ListenerHandler<void>);
+      case 'running':
+        return onRunningChange.listen(handler as ListenerHandler<boolean>);
+      case 'cache':
+        return onCacheChange.listen(
+          handler as ListenerHandler<CacheDescriptorWithKey>
+        );
+      case 'keyUpdate':
+        return onKeyUpdate.listen(handler as ListenerHandler<void>);
+    }
+  };
+
+  return Object.freeze({
+    onPendingLanguageChange,
+    onLanguageChange,
+    onKeyChange,
+    onKeyUpdate,
+    onLoadingChange,
+    onFetchingChange,
+    onInitialLoaded,
+    onRunningChange,
+    onCacheChange,
+    on,
+  });
+};
+
+export type EventServiceType = ReturnType<typeof Events>;

package/src/Controller/Plugins/Plugins.ts

@@ -0,0 +1,315 @@
+import { isPromise, valueOrPromise } from '../../helpers';
+import {
+  BackendDevInterface,
+  BackendGetRecord,
+  BackendInterface,
+  FormatterInterface,
+  ObserverInterface,
+  TranslatePropsInternal,
+  TranslationOnClick,
+  UiInterface,
+  UiLibInterface,
+  UiType,
+  FinalFormatterInterface,
+  HighlightInterface,
+  UiConstructor,
+  UiKeyOption,
+  LanguageDetectorInterface,
+  LanguageStorageInterface,
+  Options,
+  ChangeTranslationInterface,
+  WrapperWrapProps,
+  Unwrapped,
+} from '../../types';
+import { getFallbackArray } from '../State/helpers';
+import { ObserverOptions } from '../State/initObserverOptions';
+
+export const PluginService = (
+  getLanguage: () => string | undefined,
+  getInitialOptions: () => Options,
+  getObserverOptions: () => ObserverOptions,
+  getAvailableLanguages: () => string[] | undefined,
+  getTranslationNs: (props: TranslatePropsInternal) => string[] | string,
+  getTranslation: (props: TranslatePropsInternal) => string | undefined,
+  changeTranslation: ChangeTranslationInterface
+) => {
+  const plugins = {
+    ui: undefined as UiConstructor | undefined,
+    observer: undefined as ObserverInterface | 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,
+  };
+
+  const onClick: TranslationOnClick = async (event, { keysAndDefaults }) => {
+    const withNs: UiKeyOption[] = keysAndDefaults.map(
+      ({ key, ns, defaultValue }) => ({
+        key,
+        defaultValue,
+        ns: getFallbackArray(getTranslationNs({ key, ns, defaultValue })),
+        translation: getTranslation({
+          key,
+          ns,
+        }),
+      })
+    );
+    instances.ui?.handleElementClick(event, withNs);
+  };
+
+  const run = (isDev: boolean) => {
+    if (!instances.ui && plugins.ui) {
+      instances.ui = new plugins.ui({
+        apiKey: getInitialOptions().apiKey!,
+        apiUrl: getInitialOptions().apiUrl!,
+        highlight,
+        changeTranslation,
+      });
+    }
+    if (!instances.observer) {
+      instances.observer = plugins.observer?.({
+        translate,
+        onClick,
+        options: getObserverOptions(),
+      });
+    }
+    instances.observer?.run({ mouseHighlight: isDev });
+  };
+
+  const stop = () => {
+    instances.ui = undefined;
+    instances.observer?.stop();
+  };
+
+  const highlight: HighlightInterface = (key, ns) => {
+    return instances.observer?.highlight?.(key, ns) || { unhighlight() {} };
+  };
+
+  const translate = (props: TranslatePropsInternal) => {
+    const translation = getTranslation(props);
+    return formatTranslation({ ...props, translation, formatEnabled: true });
+  };
+
+  const setObserver = (observer: ObserverInterface | undefined) => {
+    plugins.observer = observer;
+  };
+
+  const hasObserver = () => {
+    return Boolean(plugins.observer);
+  };
+
+  const addFormatter = (formatter: FormatterInterface | undefined) => {
+    if (formatter) {
+      instances.formatters.push(formatter);
+    }
+  };
+
+  const setFinalFormatter = (
+    formatter: FinalFormatterInterface | undefined
+  ) => {
+    instances.finalFormatter = formatter;
+  };
+
+  const setUi = (ui: UiType | undefined) => {
+    plugins.ui = (ui as UiLibInterface)?.UI || ui;
+  };
+
+  const hasUi = () => {
+    return Boolean(plugins.ui);
+  };
+
+  const setLanguageStorage = (
+    storage: LanguageStorageInterface | undefined
+  ) => {
+    instances.languageStorage = storage;
+  };
+
+  const getLanguageStorage = () => {
+    return instances.languageStorage;
+  };
+
+  const setStoredLanguage = (language: string) => {
+    instances.languageStorage?.setLanguage(language);
+  };
+
+  const setLanguageDetector = (
+    detector: LanguageDetectorInterface | undefined
+  ) => {
+    instances.languageDetector = detector;
+  };
+
+  const getLanguageDetector = () => {
+    return instances.languageDetector;
+  };
+
+  const detectLanguage = () => {
+    if (!instances.languageDetector) {
+      return undefined;
+    }
+
+    const availableLanguages = getAvailableLanguages()!;
+
+    return instances.languageDetector.getLanguage({
+      availableLanguages,
+    });
+  };
+
+  const getInitialLanguage = () => {
+    const availableLanguages = getAvailableLanguages();
+    const languageOrPromise = instances.languageStorage?.getLanguage();
+
+    return valueOrPromise(languageOrPromise, (language) => {
+      if (
+        (!availableLanguages || availableLanguages.includes(language!)) &&
+        language
+      ) {
+        return language;
+      }
+      return detectLanguage();
+    });
+  };
+
+  const addBackend = (backend: BackendInterface | undefined) => {
+    if (backend) {
+      instances.backends.push(backend);
+    }
+  };
+
+  const setDevBackend = (backend: BackendDevInterface | undefined) => {
+    instances.devBackend = backend;
+  };
+
+  const getDevBackend = () => {
+    return instances.devBackend;
+  };
+
+  const getBackendDevRecord: BackendGetRecord = ({ language, namespace }) => {
+    return instances.devBackend?.getRecord({
+      apiKey: getInitialOptions().apiKey,
+      apiUrl: getInitialOptions().apiUrl,
+      language,
+      namespace,
+    });
+  };
+
+  const getBackendRecord: BackendGetRecord = ({ language, namespace }) => {
+    for (const backend of instances.backends) {
+      const data = backend.getRecord({ language, namespace });
+      if (isPromise(data)) {
+        return data?.catch((e) => {
+          // eslint-disable-next-line no-console
+          console.error(e);
+          return {};
+        });
+      }
+      if (data !== undefined) {
+        return data;
+      }
+    }
+    return undefined;
+  };
+
+  const formatTranslation = ({
+    key,
+    translation,
+    defaultValue,
+    noWrap,
+    params,
+    orEmpty,
+    ns,
+    formatEnabled,
+  }: TranslatePropsInternal & { formatEnabled?: boolean }) => {
+    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({
+          translation: result,
+          language,
+          params,
+        });
+      }
+    }
+
+    if (
+      instances.finalFormatter &&
+      formattableTranslation &&
+      language &&
+      isFormatEnabled
+    ) {
+      result = instances.finalFormatter.format({
+        translation: result,
+        language,
+        params,
+      });
+    }
+    return result;
+  };
+
+  const wrap = (params: WrapperWrapProps) => {
+    if (instances.observer) {
+      return instances.observer?.wrap(params);
+    }
+    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,
+    formatTranslation,
+    setObserver,
+    hasObserver,
+    setUi,
+    hasUi,
+    addBackend,
+    setDevBackend,
+    getDevBackend,
+    getBackendRecord,
+    getBackendDevRecord,
+    setLanguageDetector,
+    getLanguageDetector,
+    setLanguageStorage,
+    getLanguageStorage,
+    getInitialLanguage,
+    setStoredLanguage,
+    run,
+    stop,
+    retranslate,
+    highlight,
+    wrap,
+    unwrap,
+  });
+};
+
+export type PluginServiceType = ReturnType<typeof PluginService>;