@tolgee/core 5.0.0-alpha.1 → 5.0.0-alpha.3

package/lib/Controller/Controller.d.ts

@@ -31,10 +31,10 @@ export declare const Controller: ({ options }: StateServiceProps) => Readonly<{
         language: string;
         namespace: string;
     }[];
-    prepare: () => void;
     addPlugin: (tolgeeInstance: Readonly<{
         on: import("../types").TolgeeOn<keyof import("../types").EventType>;
         onNsUpdate: (handler: import("../types").Listener<undefined>) => import("../types").SubscriptionSelective;
+        setEmmiterActive: (active: boolean) => void;
         getLanguage: () => string | undefined;
         getPendingLanguage: () => string | undefined;
         changeLanguage: (language: string) => Promise<void>;
@@ -73,8 +73,9 @@ export declare const Controller: ({ options }: StateServiceProps) => Readonly<{
             fallbackNs?: import("../types").FallbackGeneral;
             defaultNs: string;
             staticData?: import("./State/initState").TolgeeStaticData | undefined;
-            observerOptions: import("./State/observerOptions").ObserverOptionsInternal;
             observerType: "invisible" | "text";
+            observerOptions: import("./State/observerOptions").ObserverOptionsInternal;
+            onFormatError: import("../types").OnFormatError;
         };
         isDev: () => boolean;
         wrap: (params: import("../types").WrapperWrapProps) => string | undefined;
@@ -83,7 +84,7 @@ export declare const Controller: ({ options }: StateServiceProps) => Readonly<{
         addPlugin(plugin: import("../types").TolgeePlugin | undefined): void;
         updateOptions(options?: TolgeeOptions | undefined): void;
     }>, plugin: import("../types").TolgeePlugin) => void;
-    formatTranslation: ({ key, translation, defaultValue, noWrap, params, orEmpty, ns, formatEnabled, }: {
+    formatTranslation: ({ formatEnabled, ...props }: {
         key: string;
         defaultValue?: string | undefined;
         params?: import("../types").TranslateParams<import("../types").DefaultParamType> | undefined;
@@ -96,6 +97,7 @@ export declare const Controller: ({ options }: StateServiceProps) => Readonly<{
     getBackendRecord: import("../types").BackendGetRecord;
     getBackendDevRecord: import("../types").BackendGetRecord;
     getLanguageDetector: () => import("../types").LanguageDetectorMiddleware | undefined;
+    getLanguageStorage: () => import("../types").LanguageStorageMiddleware | undefined;
     getInitialLanguage: () => string | Promise<string | undefined> | Promise<string | Promise<string | undefined> | undefined> | undefined;
     setStoredLanguage: (language: string) => void;
     retranslate: () => void;
@@ -123,8 +125,9 @@ export declare const Controller: ({ options }: StateServiceProps) => Readonly<{
         fallbackNs?: import("../types").FallbackGeneral;
         defaultNs: string;
         staticData?: import("./State/initState").TolgeeStaticData | undefined;
-        observerOptions: import("./State/observerOptions").ObserverOptionsInternal;
         observerType: "invisible" | "text";
+        observerOptions: import("./State/observerOptions").ObserverOptionsInternal;
+        onFormatError: import("../types").OnFormatError;
     };
     removeActiveNs: (ns: NsFallback) => void;
     getRequiredNamespaces: () => string[];
@@ -142,6 +145,7 @@ export declare const Controller: ({ options }: StateServiceProps) => Readonly<{
     onRunningChange: import("./Events/EventEmitter").EventEmitterInstance<boolean>;
     onCacheChange: import("./Events/EventEmitter").EventEmitterInstance<import("../types").CacheDescriptorWithKey>;
     onUpdate: import("./Events/EventEmitterSelective").EventEmitterSelectiveInstance;
+    setEmmiterActive: (active: boolean) => void;
     on: import("../types").TolgeeOn<keyof import("../types").EventType>;
 }>;
 export declare type ControllerInstance = ReturnType<typeof Controller>;

package/lib/Controller/Events/EventEmitter.d.ts

@@ -1,5 +1,5 @@
 import { Subscription, Listener } from '../../types';
-export declare const EventEmitter: <T>() => EventEmitterInstance<T>;
+export declare const EventEmitter: <T>(isActive: () => boolean) => EventEmitterInstance<T>;
 export declare type EventEmitterInstance<T> = {
     readonly listen: (handler: Listener<T>) => Subscription;
     readonly emit: (data: T) => void;

package/lib/Controller/Events/EventEmitterSelective.d.ts

@@ -1,5 +1,5 @@
 import { Subscription, Listener, SubscriptionSelective } from '../../types';
-export declare const EventEmitterSelective: (getFallbackNs: () => string[], getDefaultNs: () => string) => EventEmitterSelectiveInstance;
+export declare const EventEmitterSelective: (isActive: () => boolean, getFallbackNs: () => string[], getDefaultNs: () => string) => EventEmitterSelectiveInstance;
 export declare type EventEmitterSelectiveInstance = {
     readonly listenSome: (handler: Listener<undefined>) => SubscriptionSelective;
     readonly listen: (handler: Listener<undefined>) => Subscription;

package/lib/Controller/Events/Events.d.ts

@@ -8,6 +8,7 @@ export declare const Events: (getFallbackNs: () => string[], getDefaultNs: () =>
     onRunningChange: import("./EventEmitter").EventEmitterInstance<boolean>;
     onCacheChange: import("./EventEmitter").EventEmitterInstance<CacheDescriptorWithKey>;
     onUpdate: import("./EventEmitterSelective").EventEmitterSelectiveInstance;
+    setEmmiterActive: (active: boolean) => void;
     on: TolgeeOn<keyof import("../../types").EventType>;
 }>;
 export declare type EventsInstance = ReturnType<typeof Events>;

package/lib/Controller/Plugins/Plugins.d.ts

@@ -1,8 +1,7 @@
-import { BackendDevMiddleware, BackendGetRecord, TranslatePropsInternal, HighlightInterface, LanguageDetectorMiddleware, ChangeTranslationInterface, WrapperWrapProps, Unwrapped, KeyAndNamespacesInternal, TolgeePlugin, TolgeeInstance, TolgeeOptionsInternal } from '../../types';
+import { BackendDevMiddleware, BackendGetRecord, TranslatePropsInternal, HighlightInterface, LanguageDetectorMiddleware, LanguageStorageMiddleware, ChangeTranslationInterface, WrapperWrapProps, Unwrapped, KeyAndNamespacesInternal, TolgeePlugin, TolgeeInstance, TolgeeOptionsInternal } from '../../types';
 export declare const Plugins: (getLanguage: () => string | undefined, getInitialOptions: () => TolgeeOptionsInternal, getAvailableLanguages: () => string[] | undefined, getTranslationNs: (props: KeyAndNamespacesInternal) => string[], getTranslation: (props: KeyAndNamespacesInternal) => string | undefined, changeTranslation: ChangeTranslationInterface) => Readonly<{
-    prepare: () => void;
     addPlugin: (tolgeeInstance: TolgeeInstance, plugin: TolgeePlugin) => void;
-    formatTranslation: ({ key, translation, defaultValue, noWrap, params, orEmpty, ns, formatEnabled, }: {
+    formatTranslation: ({ formatEnabled, ...props }: {
         key: string;
         defaultValue?: string | undefined;
         params?: import("../../types").TranslateParams<import("../../types").DefaultParamType> | undefined;
@@ -15,9 +14,10 @@ export declare const Plugins: (getLanguage: () => string | undefined, getInitial
     getBackendRecord: BackendGetRecord;
     getBackendDevRecord: BackendGetRecord;
     getLanguageDetector: () => LanguageDetectorMiddleware | undefined;
+    getLanguageStorage: () => LanguageStorageMiddleware | undefined;
     getInitialLanguage: () => string | Promise<string | undefined> | Promise<string | Promise<string | undefined> | undefined> | undefined;
     setStoredLanguage: (language: string) => void;
-    run: (isDev: boolean) => void;
+    run: () => void;
     stop: () => void;
     retranslate: () => void;
     highlight: HighlightInterface;

package/lib/Controller/State/State.d.ts

@@ -23,8 +23,9 @@ export declare const State: (onLanguageChange: EventEmitterInstance<string>, onP
         fallbackNs?: import("../../types").FallbackGeneral;
         defaultNs: string;
         staticData?: import("./initState").TolgeeStaticData | undefined;
-        observerOptions: import("./observerOptions").ObserverOptionsInternal;
         observerType: "invisible" | "text";
+        observerOptions: import("./observerOptions").ObserverOptionsInternal;
+        onFormatError: import("../../types").OnFormatError;
     };
     addActiveNs: (ns: NsFallback) => void;
     removeActiveNs: (ns: NsFallback) => void;

package/lib/Controller/State/initState.d.ts

@@ -1,5 +1,6 @@
-import { FallbackGeneral, FallbackLanguageOption, TreeTranslationsData } from '../../types';
+import { FallbackGeneral, FallbackLanguageOption, TreeTranslationsData, OnFormatError } from '../../types';
 import { ObserverOptions, ObserverOptionsInternal } from './observerOptions';
+export declare const DEFAULT_FORMAT_ERROR = "invalid";
 export declare type TolgeeStaticData = {
     [key: string]: TreeTranslationsData | (() => Promise<TreeTranslationsData>);
 };
@@ -57,8 +58,18 @@ export declare type TolgeeOptionsInternal = {
      * ```
      */
     staticData?: TolgeeStaticData;
-    observerOptions: ObserverOptionsInternal;
+    /**
+     * Switches between invisible and text observer. (Default: invisible)
+     */
     observerType: 'invisible' | 'text';
+    /**
+     * Observer options object.
+     */
+    observerOptions: ObserverOptionsInternal;
+    /**
+     * Define what to display in case of formatting error. (Default: 'invalid')
+     */
+    onFormatError: OnFormatError;
 };
 export declare type TolgeeOptions = Partial<Omit<TolgeeOptionsInternal, 'observerOptions'>> & {
     observerOptions?: ObserverOptions;

package/lib/{Tolgee.d.ts → TolgeeCore.d.ts}

@@ -18,6 +18,10 @@ declare const createTolgee: (options: TolgeeOptions) => Readonly<{
      * ```
      */
     onNsUpdate: (handler: import("./types").Listener<undefined>) => import("./types").SubscriptionSelective;
+    /**
+     * Turn off/on events emitting. Is on by default.
+     */
+    setEmmiterActive: (active: boolean) => void;
     /**
      * @return current language if set.
      */
@@ -135,8 +139,9 @@ declare const createTolgee: (options: TolgeeOptions) => Readonly<{
         fallbackNs?: import("./types").FallbackGeneral;
         defaultNs: string;
         staticData?: import("./types").TolgeeStaticData | undefined;
-        observerOptions: import("./types").ObserverOptionsInternal;
         observerType: "invisible" | "text";
+        observerOptions: import("./types").ObserverOptionsInternal;
+        onFormatError: import("./types").OnFormatError;
     };
     /**
      * Tolgee is in dev mode if `DevTools` plugin is used and `apiKey` + `apiUrl` are specified.
@@ -152,11 +157,15 @@ declare const createTolgee: (options: TolgeeOptions) => Readonly<{
      */
     unwrap: (text: string) => import("./types").Unwrapped;
     /**
-     * Override creadentials passed on initialization
+     * Override creadentials passed on initialization.
+     *
+     * When called in running state, tolgee stops and runs again.
      */
     overrideCredentials(credentials: DevCredentials): void;
     /**
-     * Add tolgee plugin.
+     * Add tolgee plugin after initialization.
+     *
+     * When called in running state, tolgee stops and runs again.
      */
     addPlugin(plugin: TolgeePlugin | undefined): void;
     /**
@@ -191,5 +200,5 @@ export declare type TolgeeChainer = {
  * const tolgee = Tolgee().use(...).init(...)
  * ```
  */
-export declare const Tolgee: () => TolgeeChainer;
+export declare const TolgeeCore: () => TolgeeChainer;
 export {};

package/lib/helpers.d.ts

@@ -8,3 +8,4 @@ export declare function getFallbackArray(value: FallbackGeneral): string[];
 export declare function getFallbackFromStruct(language: string, fallbackLanguage: FallbackLanguageOption): string[];
 export declare function unique<T>(arr: T[]): T[];
 export declare function sanitizeUrl(url: string | undefined): string | undefined;
+export declare function getErrorMessage(error: any): string | undefined;

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { getFallback, getFallbackArray } from './helpers';
-export { Tolgee } from './Tolgee';
+export { TolgeeCore } from './TolgeeCore';
 export * from './types';
 export { getTranslateProps } from './TranslateParams';
 export { FormatSimple } from './FormatSimple/FormatSimple';

package/lib/types/events.d.ts

@@ -17,10 +17,10 @@ export declare type ListenerEvent<T> = {
     value: T;
 };
 export declare type Listener<T> = (e: ListenerEvent<T>) => void;
-export declare type TolgeeEvent = 'pendingLanguage' | 'language' | 'loading' | 'fetching' | 'initialLoad' | 'running' | 'cache' | 'update';
+export declare type TolgeeEvent = 'language' | 'pendingLanguage' | 'loading' | 'fetching' | 'initialLoad' | 'running' | 'cache' | 'update';
 export interface EventType {
-    pendingLanguage: string;
     language: string;
+    pendingLanguage: string;
     loading: boolean;
     fetching: boolean;
     initialLoad: void;

package/lib/types/index.d.ts

@@ -4,4 +4,4 @@ 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 '../Tolgee';
+export type { TolgeeChainer, TolgeeInstance } from '../TolgeeCore';

package/lib/types/plugin.d.ts

@@ -1,7 +1,7 @@
 import { ChangeTranslationInterface, TreeTranslationsData } from './cache';
 import { NsFallback, NsType, TranslateParams, TranslatePropsInternal } from './general';
 import type { ObserverOptionsInternal } from '../Controller/State/observerOptions';
-import { TolgeeInstance } from '../Tolgee';
+import { TolgeeInstance } from '../TolgeeCore';
 export declare type BackendDevProps = {
     apiUrl?: string;
     apiKey?: string;
@@ -106,25 +106,22 @@ export declare type UiKeyOption = {
     ns: string[];
     translation: string | undefined;
 };
-export interface UiMiddleware {
+export declare type UiMiddleware = (props: UiProps) => UiInterface;
+export interface UiInterface {
     handleElementClick(keysAndDefaults: UiKeyOption[], event: any): Promise<void>;
 }
-export declare type UiConstructor = new (props: UiProps) => UiMiddleware;
-export declare type UiLibMiddleware = {
-    UI: UiConstructor;
-};
-export declare type UiType = UiConstructor | UiLibMiddleware;
 export declare type PluginTools = Readonly<{
     setFinalFormatter: (formatter: FinalFormatterMiddleware | undefined) => void;
     addFormatter: (formatter: FormatterMiddleware | undefined) => void;
     setObserver: (observer: ObserverMiddleware | undefined) => void;
     hasObserver: () => boolean;
-    setUi: (ui: UiLibMiddleware | undefined) => void;
+    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;
-    onPrepare: (callback: () => void) => void;
 }>;
 export declare type TolgeePlugin = (tolgee: TolgeeInstance, tools: PluginTools) => TolgeeInstance;
+export declare type FormatErrorHandler = (error: string, info: TranslatePropsInternal) => string;
+export declare type OnFormatError = string | FormatErrorHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolgee/core",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.3",
   "description": "Library providing ability to translate messages directly in context of developed application.",
   "main": "./dist/tolgee.cjs.js",
   "module": "./dist/tolgee.esm.js",
@@ -62,5 +62,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9c66dbc9a72cc2874cf24abbe99af5eb6df45d50"
+  "gitHead": "8bb0a0873ba83cce1292464649cb999fc7ecea72"
 }

package/src/Controller/Controller.ts

@@ -248,15 +248,16 @@ export const Controller = ({ options }: StateServiceProps) => {
   }
 
   const checkCorrectConfiguration = () => {
-    const languageDetector = pluginService.getLanguageDetector();
-    if (languageDetector) {
+    const languageComputable =
+      pluginService.getLanguageDetector() || pluginService.getLanguageStorage();
+    if (languageComputable) {
       const availableLanguages = state.getAvailableLanguages();
       if (!availableLanguages) {
         throw new Error(missingOptionError('availableLanguages'));
       }
     }
     if (!state.getLanguage() && !state.getInitialOptions().defaultLanguage) {
-      if (languageDetector) {
+      if (languageComputable) {
         throw new Error(missingOptionError('defaultLanguage'));
       } else {
         throw new Error(missingOptionError('language'));
@@ -272,7 +273,7 @@ export const Controller = ({ options }: StateServiceProps) => {
         cache.invalidate();
       }
       state.setRunning(true);
-      pluginService.run(isDev());
+      pluginService.run();
       result = loadInitial();
     }
     return Promise.resolve(result);

package/src/Controller/Events/EventEmitter.ts

@@ -1,6 +1,8 @@
 import { Subscription, Listener } from '../../types';
 
-export const EventEmitter = <T>(): EventEmitterInstance<T> => {
+export const EventEmitter = <T>(
+  isActive: () => boolean
+): EventEmitterInstance<T> => {
   let handlers: Listener<T>[] = [];
 
   const listen = (handler: Listener<T>): Subscription => {
@@ -18,7 +20,9 @@ export const EventEmitter = <T>(): EventEmitterInstance<T> => {
   };
 
   const emit = (data: T) => {
-    handlers.forEach((handler) => handler({ value: data }));
+    if (isActive()) {
+      handlers.forEach((handler) => handler({ value: data }));
+    }
   };
 
   return Object.freeze({ listen, emit });

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

@@ -3,6 +3,7 @@ import { EventEmitterSelective } from './EventEmitterSelective';
 describe('event emitter selective', () => {
   it('handles correctly default namespace', () => {
     const emitter = EventEmitterSelective(
+      () => true,
       () => [],
       () => 'default'
     );
@@ -22,6 +23,7 @@ describe('event emitter selective', () => {
 
   it('unsubscribes', () => {
     const emitter = EventEmitterSelective(
+      () => true,
       () => [],
       () => ''
     );
@@ -37,6 +39,7 @@ describe('event emitter selective', () => {
 
   it('groups events correctly', async () => {
     const emitter = EventEmitterSelective(
+      () => true,
       () => ['test', 'opqrst'],
       () => ''
     );
@@ -69,6 +72,7 @@ describe('event emitter selective', () => {
 
   it('always subscribes to fallback ns', async () => {
     const emitter = EventEmitterSelective(
+      () => true,
       () => ['fallback1', 'fallback2'],
       () => ''
     );
@@ -84,4 +88,23 @@ describe('event emitter selective', () => {
     emitter.emit(['test']);
     expect(handler).toBeCalledTimes(2);
   });
+
+  it('switches off emitting', () => {
+    const emitter = EventEmitterSelective(
+      () => false,
+      () => ['fallback1', 'fallback2'],
+      () => ''
+    );
+    const handler = jest.fn();
+    emitter.listenSome(handler);
+
+    emitter.emit(['fallback1']);
+    expect(handler).toBeCalledTimes(0);
+
+    emitter.emit(['fallback2']);
+    expect(handler).toBeCalledTimes(0);
+
+    emitter.emit(['']);
+    expect(handler).toBeCalledTimes(0);
+  });
 });

package/src/Controller/Events/EventEmitterSelective.ts

@@ -16,6 +16,7 @@ type HandlerWrapperType = {
 };
 
 export const EventEmitterSelective = (
+  isActive: () => boolean,
   getFallbackNs: () => string[],
   getDefaultNs: () => string
 ): EventEmitterSelectiveInstance => {
@@ -111,11 +112,13 @@ export const EventEmitterSelective = (
   };
 
   const emit = (ns?: string[], delayed?: boolean) => {
-    queue.push(ns);
-    if (!delayed) {
-      solveQueue();
-    } else {
-      setTimeout(solveQueue, 0);
+    if (isActive()) {
+      queue.push(ns);
+      if (!delayed) {
+        solveQueue();
+      } else {
+        setTimeout(solveQueue, 0);
+      }
     }
   };
 

package/src/Controller/Events/Events.ts

@@ -6,14 +6,20 @@ export const Events = (
   getFallbackNs: () => string[],
   getDefaultNs: () => string
 ) => {
-  const onPendingLanguageChange = EventEmitter<string>();
-  const onLanguageChange = EventEmitter<string>();
-  const onLoadingChange = EventEmitter<boolean>();
-  const onFetchingChange = EventEmitter<boolean>();
-  const onInitialLoaded = EventEmitter<void>();
-  const onRunningChange = EventEmitter<boolean>();
-  const onCacheChange = EventEmitter<CacheDescriptorWithKey>();
-  const onUpdate = EventEmitterSelective(getFallbackNs, getDefaultNs);
+  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());
@@ -42,6 +48,10 @@ export const Events = (
     }
   };
 
+  function setEmmiterActive(active: boolean) {
+    emitterActive = active;
+  }
+
   return Object.freeze({
     onPendingLanguageChange,
     onLanguageChange,
@@ -51,6 +61,7 @@ export const Events = (
     onRunningChange,
     onCacheChange,
     onUpdate,
+    setEmmiterActive,
     on,
   });
 };