@tolgee/core 5.0.0-rc.af99eec.0 → 5.0.0

package/src/__test/namespaces.test.ts

@@ -1,4 +1,4 @@
-import { Tolgee } from '../index';
+import { TolgeeCore } from '../index';
 
 const tolgeeWithNamespaces = () => {
   const promiseEnTest = jest.fn(() => Promise.resolve({ test: 'Test' }));
@@ -8,9 +8,10 @@ const tolgeeWithNamespaces = () => {
     Promise.resolve({ cancel: 'Cancellar' })
   );
 
-  return Tolgee({
+  return TolgeeCore().init({
     language: 'en',
     ns: ['common'],
+    defaultNs: 'common',
     staticData: {
       'en:common': promiseEnCommon,
       'en:test': promiseEnTest,
@@ -22,7 +23,7 @@ const tolgeeWithNamespaces = () => {
 
 describe('language changes', () => {
   it('returns correct translation from namespace', () => {
-    const tolgee = Tolgee({
+    const tolgee = TolgeeCore().init({
       language: 'en',
       staticData: {
         en: { hello: 'World' },
@@ -35,7 +36,7 @@ describe('language changes', () => {
   });
 
   it('uses defaultNs', async () => {
-    const tolgee = Tolgee({
+    const tolgee = TolgeeCore().init({
       language: 'en',
       defaultNs: 'common',
       staticData: {
@@ -76,24 +77,46 @@ describe('language changes', () => {
 
   it('removing active namespaces', async () => {
     const tolgee = tolgeeWithNamespaces();
-    await tolgee.run();
     const handler = jest.fn();
     tolgee.on('cache', handler);
+    await tolgee.run();
 
     expect(tolgee.t({ key: 'cancel', ns: 'common' })).toEqual('Cancel');
     expect(tolgee.t({ key: 'test', ns: 'test' })).toEqual('test');
 
     await tolgee.addActiveNs('test');
-    expect(handler).toBeCalledTimes(1);
+    expect(handler).toBeCalledTimes(2);
 
     expect(tolgee.t({ key: 'cancel', ns: 'common' })).toEqual('Cancel');
     expect(tolgee.t({ key: 'test', ns: 'test' })).toEqual('Test');
 
     tolgee.removeActiveNs('test');
     await tolgee.changeLanguage('es');
-    expect(handler).toBeCalledTimes(2);
+    expect(handler).toBeCalledTimes(3);
 
     expect(tolgee.t({ key: 'cancel', ns: 'common' })).toEqual('Cancellar');
     expect(tolgee.t({ key: 'test', ns: 'test' })).toEqual('test');
   });
+
+  it('add active namespace with forget', async () => {
+    const tolgee = tolgeeWithNamespaces();
+    const handler = jest.fn();
+    tolgee.on('cache', handler);
+    await tolgee.run();
+
+    // test ns is not loaded
+    expect(tolgee.t({ key: 'test', ns: 'test' })).toEqual('test');
+
+    await tolgee.addActiveNs('test', true);
+    expect(handler).toBeCalledTimes(2);
+
+    // test ns is loaded
+    expect(tolgee.t({ key: 'test', ns: 'test' })).toEqual('Test');
+
+    await tolgee.changeLanguage('es');
+    expect(handler).toBeCalledTimes(3);
+
+    // test ns is not loaded for spanish
+    expect(tolgee.t({ key: 'test', ns: 'test' })).toEqual('test');
+  });
 });

package/src/__test/options.test.ts

@@ -0,0 +1,64 @@
+import { TolgeeCore } from '../TolgeeCore';
+
+describe('initial options', () => {
+  it('combines options correctly', () => {
+    const tolgee = TolgeeCore()
+      .updateDefaults({
+        observerType: 'text',
+        observerOptions: { highlightColor: 'red', restrictedElements: ['a'] },
+        apiUrl: 'https://app.tolgee.io',
+        language: 'en',
+      })
+      .init({
+        language: 'cs',
+        apiUrl: 'http://localhost:8080',
+        observerOptions: { highlightWidth: 90 },
+      });
+
+    expect(tolgee.getInitialOptions().apiUrl).toEqual('http://localhost:8080');
+
+    tolgee.updateOptions({
+      apiUrl: 'http://localhost:8202',
+    });
+
+    const {
+      observerType,
+      apiUrl,
+      language,
+      defaultNs,
+      observerOptions: {
+        highlightColor,
+        highlightWidth,
+        restrictedElements,
+        inputPrefix,
+      },
+    } = tolgee.getInitialOptions();
+
+    expect(apiUrl).toEqual('http://localhost:8202');
+    expect(observerType).toEqual('text');
+    expect(language).toEqual('cs');
+    expect(highlightWidth).toEqual(90);
+    expect(restrictedElements).toEqual(['a']);
+    expect(highlightColor).toEqual('red');
+    expect(inputPrefix).toEqual('%-%tolgee:');
+    expect(defaultNs).toEqual('');
+  });
+
+  it('sanitizes url', () => {
+    const tolgee = TolgeeCore().init({
+      language: 'cs',
+      apiUrl: 'http://localhost:8080/',
+      observerOptions: { highlightWidth: 90 },
+    });
+
+    expect(tolgee.getInitialOptions().apiUrl).toEqual('http://localhost:8080');
+
+    tolgee.updateOptions({ apiUrl: 'http://localhost:8202/' });
+
+    expect(tolgee.getInitialOptions().apiUrl).toEqual('http://localhost:8202');
+
+    tolgee.overrideCredentials({ apiUrl: 'http://localhost:8000/' });
+
+    expect(tolgee.getInitialOptions().apiUrl).toEqual('http://localhost:8000');
+  });
+});

package/src/__test/plugins.test.ts

@@ -1,15 +1,15 @@
-import { Tolgee } from '../Tolgee';
+import { TolgeeCore } from '../TolgeeCore';
 import {
-  FinalFormatterInterface,
-  FormatterInterface,
-  FormatterInterfaceFormatParams,
-  ObserverInterface,
+  FinalFormatterMiddleware,
+  FormatterMiddleware,
+  FormatterMiddlewareFormatParams,
+  ObserverMiddleware,
   TolgeePlugin,
   WrapperWrapFunction,
 } from '../types';
 
 const testObserver =
-  (outputNotFormattable: boolean): ObserverInterface =>
+  (outputNotFormattable: boolean): ObserverMiddleware =>
   () => {
     const wrap: WrapperWrapFunction = ({ key, translation }) => {
       return `${key}|${translation}`;
@@ -35,20 +35,20 @@ const testObserver =
     });
   };
 
-const testFormatter1: FormatterInterface = {
-  format: ({ translation }: FormatterInterfaceFormatParams) => {
+const testFormatter1: FormatterMiddleware = {
+  format: ({ translation }: FormatterMiddlewareFormatParams) => {
     return `(1${translation})`;
   },
 };
 
-const testFormatter2: FormatterInterface = {
-  format: ({ translation }: FormatterInterfaceFormatParams) => {
+const testFormatter2: FormatterMiddleware = {
+  format: ({ translation }: FormatterMiddlewareFormatParams) => {
     return `(2${translation})`;
   },
 };
 
-const testFinalFormatter: FinalFormatterInterface = {
-  format: ({ translation }: FormatterInterfaceFormatParams) => {
+const testFinalFormatter: FinalFormatterMiddleware = {
+  format: ({ translation }: FormatterMiddlewareFormatParams) => {
     return { final: translation };
   },
 };
@@ -69,30 +69,41 @@ const formattersPlugin: TolgeePlugin = (tolgee, tools) => {
 
 describe('plugins', () => {
   it('wraps and formats translation', () => {
-    const tolgee = Tolgee({
+    const tolgee = TolgeeCore().init({
       language: 'en',
       staticData: { en: { hello: 'world' } },
     });
-    tolgee.use(observerPlugin(false));
+    tolgee.addPlugin(observerPlugin(false));
     tolgee.run();
     expect(tolgee.t({ key: 'hello' })).toEqual('hello|world');
 
-    tolgee.use(formattersPlugin);
+    tolgee.addPlugin(formattersPlugin);
     expect(tolgee.t({ key: 'hello' })).toEqual({ final: '(2(1hello|world))' });
     tolgee.stop();
   });
 
   it("won't format when observer doesn't return formattable text", () => {
-    const tolgee = Tolgee({
+    const tolgee = TolgeeCore().init({
       language: 'en',
       staticData: { en: { hello: 'world' } },
     });
-    tolgee.use(observerPlugin(true));
+    tolgee.addPlugin(observerPlugin(true));
     tolgee.run();
     expect(tolgee.t({ key: 'hello' })).toEqual('hello|world');
 
-    tolgee.use(formattersPlugin);
+    tolgee.addPlugin(formattersPlugin);
     expect(tolgee.t({ key: 'hello' })).toEqual('hello|world');
     tolgee.stop();
   });
+
+  it("won't wrap before run", () => {
+    const tolgee = TolgeeCore().init({
+      language: 'en',
+      staticData: { en: { hello: 'world' } },
+    });
+    tolgee.addPlugin(observerPlugin(false));
+    expect(tolgee.t({ key: 'hello' })).toEqual('world');
+    tolgee.run();
+    expect(tolgee.t({ key: 'hello' })).toEqual('hello|world');
+  });
 });

package/src/helpers.ts

@@ -1,3 +1,9 @@
+import {
+  FallbackGeneral,
+  FallbackLanguageObject,
+  FallbackLanguageOption,
+} from './types';
+
 export function isPromise(value: any) {
   return Boolean(value && typeof value.then === 'function');
 }
@@ -15,3 +21,50 @@ export const valueOrPromise = <T, R>(
 
 export const missingOptionError = (option: string) =>
   `Tolgee: You need to specify '${option}' option`;
+
+export function isObject(item: any) {
+  return typeof item === 'object' && !Array.isArray(item) && item !== null;
+}
+
+export function getFallback(value: FallbackGeneral): string[] | undefined {
+  if (typeof value === 'string') {
+    return [value];
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return undefined;
+}
+
+export function getFallbackArray(value: FallbackGeneral): string[] {
+  return getFallback(value) || [];
+}
+
+export function getFallbackFromStruct(
+  language: string,
+  fallbackLanguage: FallbackLanguageOption
+) {
+  if (isObject(fallbackLanguage)) {
+    return getFallbackArray(
+      (fallbackLanguage as FallbackLanguageObject)?.[language]
+    );
+  } else {
+    return getFallbackArray(fallbackLanguage as FallbackGeneral);
+  }
+}
+
+export function unique<T>(arr: T[]) {
+  return Array.from(new Set(arr));
+}
+
+export function sanitizeUrl(url: string | undefined) {
+  return url ? url.replace(/\/+$/, '') : url;
+}
+
+export function getErrorMessage(error: any): string | undefined {
+  if (typeof error === 'string') {
+    return error;
+  } else if (typeof error?.message === 'string') {
+    return error.message;
+  }
+}

package/src/index.ts

@@ -1,11 +1,5 @@
-export { Tolgee } from './Tolgee';
-export {
-  RESTRICTED_ASCENDANT_ATTRIBUTE,
-  DEVTOOLS_ID,
-  TOLGEE_ATTRIBUTE_NAME,
-  TOLGEE_HIGHLIGHTER_CLASS,
-  TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE,
-} from './constants';
+export { getFallback, getFallbackArray } from './helpers';
+export { TolgeeCore } from './TolgeeCore';
 export * from './types';
-export { getTranslateParams } from './TranslateParams';
-export { getFallback, getFallbackArray } from './Controller/State/helpers';
+export { getTranslateProps } from './TranslateParams';
+export { FormatSimple } from './FormatSimple/FormatSimple';

package/src/types/cache.ts

@@ -0,0 +1,37 @@
+export type TranslationValue = string | undefined | null;
+
+export type TranslationsFlat = Map<string, TranslationValue>;
+
+export type TreeTranslationsData = {
+  [key: string]: TranslationValue | TreeTranslationsData;
+};
+
+export type CacheDescriptor = {
+  language: string;
+  namespace?: string;
+};
+
+export type CacheDescriptorInternal = {
+  language: string;
+  namespace: string;
+};
+
+export type CacheDescriptorWithKey = CacheDescriptorInternal & {
+  key?: string;
+};
+
+export type TranslationChanger = {
+  revert: () => void;
+};
+
+export type ChangeTranslationInterface = (
+  descriptor: CacheDescriptor,
+  key: string,
+  value: string
+) => TranslationChanger;
+
+export type CachePublicRecord = {
+  data: TranslationsFlat;
+  language: string;
+  namespace: string;
+};

package/src/types/events.ts

@@ -0,0 +1,85 @@
+import type { NsFallback } from './general';
+import type { CacheDescriptorWithKey } from './cache';
+
+export type Subscription = {
+  unsubscribe: () => void;
+};
+
+export type SubscriptionSelective = {
+  unsubscribe: () => void;
+  /**
+   * Subscribes to namespace(s)
+   * @param ns - namespace(s), if empty default namespace is used
+   *
+   * Can be used multiple times to subscribe for more.
+   */
+  subscribeNs(ns?: NsFallback): SubscriptionSelective;
+};
+
+export type ListenerEvent<T> = { value: T };
+export type Listener<T> = (e: ListenerEvent<T>) => void;
+
+export type TolgeeEvent =
+  | 'language'
+  | 'pendingLanguage'
+  | 'loading'
+  | 'fetching'
+  | 'initialLoad'
+  | 'running'
+  | 'cache'
+  | 'update';
+
+export interface EventType {
+  language: string;
+  pendingLanguage: string;
+  loading: boolean;
+  fetching: boolean;
+  initialLoad: void;
+  running: boolean;
+  cache: CacheDescriptorWithKey;
+  update: void;
+}
+
+export type TolgeeOn<E extends keyof EventType = keyof EventType> = {
+  /**
+   * Emitted when any key needs (or might need) to be re-rendered.
+   * Similar to tolgee.onNsUpdate, except for all namespaces.
+   */
+  (event: 'update', handler: Listener<void>): Subscription;
+
+  /**
+   * Emitted on language change.
+   */
+  (event: 'language', handler: Listener<string>): Subscription;
+
+  /**
+   * Emitted on pendingLanguage change.
+   */
+  (event: 'pendingLanguage', handler: Listener<string>): Subscription;
+
+  /**
+   * Emitted on loading change. Changes when tolgee is loading some data for the first time.
+   */
+  (event: 'loading', handler: Listener<boolean>): Subscription;
+
+  /**
+   * Emitted on fetching change. Changes when tolgee is fetching any data.
+   */
+  (event: 'fetching', handler: Listener<boolean>): Subscription;
+
+  /**
+   * Emitted when `tolgee.run` method finishes.
+   */
+  (event: 'initialLoad', handler: Listener<void>): Subscription;
+
+  /**
+   * Emitted when internal `running` state changes.
+   */
+  (event: 'running', handler: Listener<boolean>): Subscription;
+
+  /**
+   * Emitted when cache changes.
+   */
+  (event: 'cache', handler: Listener<CacheDescriptorWithKey>): Subscription;
+  (event: E, handler: unknown): Subscription;
+};

package/src/types/general.ts

@@ -0,0 +1,50 @@
+export type FallbackGeneral = undefined | false | string | string[];
+
+export type NsType = string;
+
+export type KeyType = string;
+
+export type NsFallback = undefined | NsType | NsType[];
+
+export type FallbackLanguageObject = Record<string, FallbackGeneral>;
+
+export type FallbackLanguageOption = FallbackGeneral | FallbackLanguageObject;
+
+export type DefaultParamType = string | number | bigint;
+
+export type TranslateParams<T = DefaultParamType> = {
+  [key: string]: T;
+};
+
+export type TranslateOptions = {
+  ns?: NsType;
+  noWrap?: boolean;
+  orEmpty?: boolean;
+};
+
+export type TranslateProps<T = DefaultParamType> = {
+  key: KeyType;
+  defaultValue?: string;
+  params?: TranslateParams<T>;
+} & TranslateOptions;
+
+export type TranslatePropsInternal = TranslateProps & {
+  translation?: string;
+};
+
+type PropType<TObj> = TObj[keyof TObj];
+
+export type CombinedOptions<T> = TranslateOptions & {
+  [key: string]: T | PropType<TranslateOptions>;
+};
+
+export type TFnType<T = DefaultParamType, R = string> = {
+  (key: string, defaultValue?: string, options?: CombinedOptions<T>): R;
+  (key: string, options?: CombinedOptions<T>): R;
+  (props: TranslateProps<T>): R;
+};
+
+export type KeyAndNamespacesInternal = Pick<
+  TranslatePropsInternal,
+  'key' | 'ns'
+>;

package/src/types/index.ts

@@ -0,0 +1,19 @@
+export * from './general';
+export * from './events';
+export * from './cache';
+export * from './plugin';
+
+export type {
+  State,
+  TolgeeOptions,
+  TolgeeOptionsInternal,
+  TolgeeStaticData,
+} from '../Controller/State/initState';
+
+export type {
+  ObserverOptions,
+  ObserverOptionsInternal,
+  ModifierKey,
+} from '../Controller/State/observerOptions';
+
+export type { TolgeeChainer, TolgeeInstance } from '../TolgeeCore';

package/src/types/plugin.ts

@@ -0,0 +1,181 @@
+import { ChangeTranslationInterface, TreeTranslationsData } from './cache';
+import {
+  NsFallback,
+  NsType,
+  TranslateParams,
+  TranslatePropsInternal,
+} from './general';
+import type { ObserverOptionsInternal } from '../Controller/State/observerOptions';
+import { TolgeeInstance } from '../TolgeeCore';
+
+export type BackendDevProps = {
+  apiUrl?: string;
+  apiKey?: string;
+  projectId?: number | string;
+};
+
+export type BackendGetRecordProps = {
+  language: string;
+  namespace?: string;
+};
+
+export type BackendGetRecord = (
+  data: BackendGetRecordProps
+) => Promise<TreeTranslationsData | undefined> | undefined;
+
+export interface BackendMiddleware {
+  getRecord: BackendGetRecord;
+}
+
+export type BackendGetDevRecord = (
+  data: BackendGetRecordProps & BackendDevProps
+) => Promise<TreeTranslationsData | undefined> | undefined;
+
+export type BackendDevMiddleware = {
+  getRecord: BackendGetDevRecord;
+};
+
+export type KeyAndParams = {
+  key: string;
+  params?: TranslateParams;
+  defaultValue?: string;
+  ns?: NsType;
+};
+
+export type Unwrapped = { text: string; keys: KeyAndParams[] };
+
+export type WrapperWrapProps = Pick<
+  TranslatePropsInternal,
+  'key' | 'params' | 'defaultValue' | 'ns' | 'translation'
+>;
+export type WrapperWrapFunction = (props: WrapperWrapProps) => string;
+export type WrapperUnwrapFunction = (text: string) => Unwrapped;
+
+export type WrapperAttributeXPathGetter = (props: {
+  tag: string;
+  attribute: string;
+}) => string;
+
+export type HighlightInterface = (key?: string, ns?: NsFallback) => Highlighter;
+
+export type ObserverRunProps = {
+  mouseHighlight: boolean;
+};
+
+export type ObserverMiddleware = (props: ObserverProps) => {
+  unwrap: (text: string) => Unwrapped;
+  wrap: WrapperWrapFunction;
+  retranslate: () => void;
+  stop: () => void;
+  run: (props: ObserverRunProps) => void;
+  highlight: HighlightInterface;
+  outputNotFormattable: boolean;
+};
+
+export type LanguageDetectorProps = {
+  availableLanguages: string[];
+};
+
+export type LanguageDetectorMiddleware = {
+  getLanguage: (
+    props: LanguageDetectorProps
+  ) => string | undefined | Promise<string | undefined>;
+};
+
+export type LanguageStorageMiddleware = {
+  getLanguage: () => string | undefined | Promise<string | undefined>;
+  setLanguage: (language: string) => void | Promise<void>;
+};
+
+export type DevCredentials =
+  | undefined
+  | {
+      apiUrl?: string;
+      apiKey?: string;
+      projectId?: string | number;
+    };
+export type WrapperMiddleware = {
+  unwrap: WrapperUnwrapFunction;
+  wrap: WrapperWrapFunction;
+  getTextXPath: () => string;
+  getAttributeXPath: WrapperAttributeXPathGetter;
+};
+
+export type FormatterMiddlewareFormatParams = {
+  translation: string;
+  language: string;
+  params: Record<string, any> | undefined;
+};
+
+export type FormatterMiddleware = {
+  format: (props: FormatterMiddlewareFormatParams) => string;
+};
+
+export type TranslationOnClick = (data: {
+  keysAndDefaults: KeyAndParams[];
+  event: any;
+}) => void;
+
+export type ObserverProps = {
+  translate: (params: TranslatePropsInternal) => string;
+  onClick: TranslationOnClick;
+  options: ObserverOptionsInternal;
+};
+
+export type Highlighter = {
+  unhighlight(): void;
+};
+
+export type FinalFormatterMiddleware = {
+  format: (props: FormatterMiddlewareFormatParams) => any;
+};
+
+export type UiProps = {
+  apiUrl: string;
+  apiKey: string;
+  projectId: number | string | undefined;
+  highlight: HighlightInterface;
+  changeTranslation: ChangeTranslationInterface;
+};
+
+export type UiKeyOption = {
+  key: string;
+  defaultValue?: string;
+  ns: string[];
+  translation: string | undefined;
+};
+
+export type UiMiddleware = (props: UiProps) => UiInterface;
+
+export interface UiInterface {
+  handleElementClick(keysAndDefaults: UiKeyOption[], event: any): Promise<void>;
+}
+
+export type PluginTools = Readonly<{
+  setFinalFormatter: (formatter: FinalFormatterMiddleware | undefined) => void;
+  addFormatter: (formatter: FormatterMiddleware | undefined) => void;
+  setObserver: (observer: ObserverMiddleware | undefined) => void;
+  hasObserver: () => boolean;
+  setUi: (ui: UiMiddleware | undefined) => void;
+  hasUi: () => boolean;
+  addBackend: (backend: BackendMiddleware | undefined) => void;
+  setDevBackend: (backend: BackendDevMiddleware | undefined) => void;
+  setLanguageDetector: (
+    languageDetector: LanguageDetectorMiddleware | undefined
+  ) => void;
+  setLanguageStorage: (
+    languageStorage: LanguageStorageMiddleware | undefined
+  ) => void;
+}>;
+
+export type TolgeePlugin = (
+  tolgee: TolgeeInstance,
+  tools: PluginTools
+) => TolgeeInstance;
+
+export type FormatErrorHandler = (
+  error: string,
+  info: TranslatePropsInternal
+) => string;
+
+export type OnFormatError = string | FormatErrorHandler;