@tolgee/core 5.33.2 → 5.33.3-prerelease.2efc0e6b.0

package/src/__test/namespaces.required.test.ts

@@ -0,0 +1,52 @@
+import { Controller } from '../Controller/Controller';
+
+describe('required namespaces', () => {
+  it('<default>', () => {
+    const controller = Controller({
+      options: {},
+    });
+    expect(controller.getDefaultNs()).toEqual('');
+    expect(controller.getRequiredNamespaces()).toEqual(['']);
+  });
+
+  it('ns:[common]', () => {
+    const controller = Controller({
+      options: { ns: ['common'] },
+    });
+    expect(controller.getRequiredNamespaces()).toEqual(['common']);
+    expect(controller.getDefaultNs()).toEqual('common');
+  });
+
+  it('defaultNs: test', () => {
+    const controller = Controller({
+      options: { defaultNs: 'test' },
+    });
+    expect(controller.getRequiredNamespaces()).toEqual(['test']);
+    expect(controller.getDefaultNs()).toEqual('test');
+  });
+
+  it('defaultNs: test, ns:[common]', () => {
+    const controller = Controller({
+      options: { defaultNs: 'test', ns: ['common'] },
+    });
+    expect(controller.getRequiredNamespaces()).toEqual(['test', 'common']);
+    expect(controller.getDefaultNs()).toEqual('test');
+  });
+
+  it('defaultNs, ns, fallbackNs', () => {
+    const controller = Controller({
+      options: {
+        defaultNs: 'test',
+        ns: ['common', 'test2'],
+        fallbackNs: ['fallback', 'fallback2'],
+      },
+    });
+    expect(controller.getRequiredNamespaces()).toEqual([
+      'test',
+      'common',
+      'test2',
+      'fallback',
+      'fallback2',
+    ]);
+  });
+});

package/src/__test/options.test.ts

@@ -41,7 +41,7 @@ describe('initial options', () => {
     expect(restrictedElements).toEqual(['a']);
     expect(highlightColor).toEqual('red');
     expect(inputPrefix).toEqual('%-%tolgee:');
-    expect(defaultNs).toEqual('');
+    expect(defaultNs).toEqual(undefined);
   });
 
   it('sanitizes url', () => {

package/src/__test/testTools.ts

@@ -1,3 +1,5 @@
+import { TolgeePlugin } from '../types';
+
 export const resolvablePromise = <T = any>() => {
   let resolve: (value: T) => void;
   const promise = new Promise<T>((innerResolve) => {
@@ -5,3 +7,40 @@ export const resolvablePromise = <T = any>() => {
   });
   return [promise, resolve!] as const;
 };
+
+export const DevToolsPlugin =
+  (postfix = ''): TolgeePlugin =>
+  (tolgee, tools) => {
+    tolgee.updateOptions({ apiKey: 'test', apiUrl: 'test' });
+    tools.setDevBackend({
+      getRecord({ language, namespace }) {
+        return Promise.resolve({
+          test: { sub: `${language}.${namespace || 'default'}${postfix}` },
+        });
+      },
+    });
+    return tolgee;
+  };
+
+export const BackendPlugin =
+  (postfix = ''): TolgeePlugin =>
+  (tolgee, tools) => {
+    tools.addBackend({
+      getRecord({ language, namespace }) {
+        return Promise.resolve({
+          test: { sub: `${language}.${namespace || 'default'}${postfix}` },
+        });
+      },
+    });
+    return tolgee;
+  };
+
+export const DevToolsThrow = (): TolgeePlugin => (tolgee, tools) => {
+  tolgee.updateOptions({ apiKey: 'test', apiUrl: 'test' });
+  tools.setDevBackend({
+    getRecord() {
+      return Promise.reject();
+    },
+  });
+  return tolgee;
+};

package/src/helpers.ts

@@ -4,6 +4,7 @@ import {
   FallbackLanguageOption,
   FetchFn,
   TolgeeError,
+  ErrorEvent,
 } from './types';
 import { EventEmitterInstance } from './Controller/Events/EventEmitter';
 
@@ -25,7 +26,7 @@ export function valueOrPromise<T, R>(
 }
 
 export function handleRegularOrAsyncErr<T>(
-  onError: EventEmitterInstance<TolgeeError>,
+  onError: EventEmitterInstance<ErrorEvent>,
   createError: (e: any) => TolgeeError,
   callback: () => Promise<T> | T
 ): Promise<T> | T {

package/src/types/cache.ts

@@ -1,6 +1,6 @@
 export type TranslationValue = string | undefined | null;
 
-export type TranslationsFlat = Map<string, TranslationValue>;
+export type TranslationsFlat = Record<string, TranslationValue>;
 
 export type TreeTranslationsData = {
   [key: string]: TranslationValue | TreeTranslationsData;
@@ -35,3 +35,26 @@ export type CachePublicRecord = {
   language: string;
   namespace: string;
 };
+
+export type CacheInternalRecord = {
+  data: TranslationsFlat;
+  language: string;
+  namespace: string;
+  cacheKey: string;
+};
+
+export type LoadOptions = {
+  noDev?: boolean;
+  useCache?: boolean;
+};
+
+export type LoadRequiredOptions = LoadOptions & {
+  language?: string;
+};
+
+export type MatrixOptions = {
+  languages: string[] | 'all';
+  namespaces: string[] | 'all';
+};
+
+export type LoadMatrixOptions = LoadOptions & MatrixOptions;

package/src/types/events.ts

@@ -1,4 +1,3 @@
-import type { NsFallback } from './general';
 import type { CacheDescriptorWithKey } from './cache';
 import { TolgeeError } from './errors';
 
@@ -6,19 +5,26 @@ 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 ListenerEvent<E extends string, T> = { type: E; value: T };
+export type Handler<E extends ListenerEvent<string, any>> = (e: E) => void;
+export type CombinedHandler<E extends ListenerEvent<string, any>> = (
+  e: E[]
+) => void;
+
+export type LanguageEvent = ListenerEvent<'language', string>;
+export type PendingLanguageEvent = ListenerEvent<'pendingLanguage', string>;
+export type LoadingEvent = ListenerEvent<'loading', boolean>;
+export type FetchingEvent = ListenerEvent<'fetching', boolean>;
+export type InitialLoadEvent = ListenerEvent<'initialLoad', void>;
+export type RunningEvent = ListenerEvent<'running', boolean>;
+export type CacheEvent = ListenerEvent<'cache', CacheDescriptorWithKey>;
+export type ErrorEvent = ListenerEvent<'error', TolgeeError>;
+export type PermanentChangeEvent = ListenerEvent<
+  'permanentChange',
+  TranslationDescriptor
+>;
+
+export type UpdateEvent = LanguageEvent | CacheEvent | InitialLoadEvent;
 
 export type TolgeeEvent =
   | 'language'
@@ -49,54 +55,57 @@ 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;
+  (event: 'update', handler: CombinedHandler<UpdateEvent>): Subscription;
 
   /**
    * Emitted on language change.
    */
-  (event: 'language', handler: Listener<string>): Subscription;
+  (event: 'language', handler: Handler<LanguageEvent>): Subscription;
 
   /**
    * Emitted on pendingLanguage change.
    */
-  (event: 'pendingLanguage', handler: Listener<string>): Subscription;
+  (
+    event: 'pendingLanguage',
+    handler: Handler<PendingLanguageEvent>
+  ): Subscription;
 
   /**
    * Emitted on loading change. Changes when tolgee is loading some data for the first time.
    */
-  (event: 'loading', handler: Listener<boolean>): Subscription;
+  (event: 'loading', handler: Handler<LoadingEvent>): Subscription;
 
   /**
    * Emitted on fetching change. Changes when tolgee is fetching any data.
    */
-  (event: 'fetching', handler: Listener<boolean>): Subscription;
+  (event: 'fetching', handler: Handler<FetchingEvent>): Subscription;
 
   /**
    * Emitted when `tolgee.run` method finishes.
    */
-  (event: 'initialLoad', handler: Listener<void>): Subscription;
+  (event: 'initialLoad', handler: Handler<InitialLoadEvent>): Subscription;
 
   /**
    * Emitted when internal `running` state changes.
    */
-  (event: 'running', handler: Listener<boolean>): Subscription;
+  (event: 'running', handler: Handler<RunningEvent>): Subscription;
 
   /**
    * Emitted when cache changes.
    */
-  (event: 'cache', handler: Listener<CacheDescriptorWithKey>): Subscription;
+  (event: 'cache', handler: Handler<CacheEvent>): Subscription;
 
   /**
    * Emitted on errors
    */
-  (event: 'error', handler: Listener<TolgeeError>): Subscription;
+  (event: 'error', handler: Handler<ErrorEvent>): Subscription;
 
   /**
    * Translation was changed or created via dev tools
    */
   (
     event: 'permanentChange',
-    handler: Listener<CacheDescriptorWithKey>
+    handler: Handler<PermanentChangeEvent>
   ): Subscription;
 
   (event: E, handler: unknown): Subscription;

package/src/types/index.ts

@@ -9,6 +9,7 @@ export type {
   TolgeeOptions,
   TolgeeOptionsInternal,
   TolgeeStaticData,
+  TolgeeStaticDataProp,
 } from '../Controller/State/initState';
 
 export type {

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

@@ -1,7 +0,0 @@
-import { Subscription, Listener, SubscriptionSelective } from '../../types';
-export declare function EventEmitterSelective(isActive: () => boolean, getFallbackNs: () => string[], getDefaultNs: () => string): EventEmitterSelectiveInstance;
-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/EventEmitterSelective.test.ts

@@ -1,110 +0,0 @@
-import { EventEmitterSelective } from './EventEmitterSelective';
-
-describe('event emitter selective', () => {
-  it('handles correctly default namespace', () => {
-    const emitter = EventEmitterSelective(
-      () => true,
-      () => [],
-      () => 'default'
-    );
-    const handler = jest.fn();
-    const listener = emitter.listenSome(handler);
-
-    // subscribe to default ns
-    listener.subscribeNs();
-
-    // emmit
-    emitter.emit(['default']);
-    // should be ignored
-    emitter.emit(['c']);
-
-    expect(handler).toBeCalledTimes(1);
-  });
-
-  it('unsubscribes', () => {
-    const emitter = EventEmitterSelective(
-      () => true,
-      () => [],
-      () => ''
-    );
-    const handler = jest.fn();
-    const listener = emitter.listen(handler);
-
-    emitter.emit();
-
-    listener.unsubscribe();
-    emitter.emit();
-    expect(handler).toBeCalledTimes(1);
-  });
-
-  it('groups events correctly', async () => {
-    const emitter = EventEmitterSelective(
-      () => true,
-      () => ['test', 'opqrst'],
-      () => ''
-    );
-    const handler = jest.fn();
-    const hanlderAll = jest.fn();
-    const listener = emitter.listenSome(handler);
-    const listenerAll = emitter.listen(hanlderAll);
-
-    listener.subscribeNs('test');
-
-    // is fallback should always call handler
-    emitter.emit(['opqrst'], true);
-
-    await new Promise((resolve) => setTimeout(resolve));
-
-    expect(hanlderAll).toBeCalledTimes(1);
-    expect(handler).toBeCalledTimes(1);
-
-    // these should be merged together
-    emitter.emit(['abcd'], true);
-    emitter.emit(['abcd']);
-
-    expect(hanlderAll).toBeCalledTimes(2);
-    expect(handler).toBeCalledTimes(1);
-
-    listener.unsubscribe();
-    listenerAll.unsubscribe();
-    emitter.emit();
-  });
-
-  it('always subscribes to fallback ns', async () => {
-    const emitter = EventEmitterSelective(
-      () => true,
-      () => ['fallback1', 'fallback2'],
-      () => ''
-    );
-    const handler = jest.fn();
-    emitter.listenSome(handler);
-
-    emitter.emit(['fallback1']);
-    expect(handler).toBeCalledTimes(1);
-
-    emitter.emit(['fallback2']);
-    expect(handler).toBeCalledTimes(2);
-
-    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

@@ -1,133 +0,0 @@
-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 function EventEmitterSelective(
-  isActive: () => boolean,
-  getFallbackNs: () => string[],
-  getDefaultNs: () => string
-): EventEmitterSelectiveInstance {
-  const listeners: Set<Listener<undefined>> = new Set();
-  const partialListeners: Set<HandlerWrapperType> = new Set();
-
-  function 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
-  function 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);
-  }
-
-  return Object.freeze({
-    emit(ns?: string[], delayed?: boolean) {
-      if (isActive()) {
-        queue.push(ns);
-        if (!delayed) {
-          solveQueue();
-        } else {
-          setTimeout(solveQueue, 0);
-        }
-      }
-    },
-
-    listen(handler: Listener<undefined>) {
-      listeners.add(handler);
-      const result = {
-        unsubscribe: () => {
-          listeners.delete(handler);
-        },
-      };
-      return result;
-    },
-
-    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;
-    },
-  });
-}
-
-export type EventEmitterSelectiveInstance = {
-  readonly listenSome: (handler: Listener<undefined>) => SubscriptionSelective;
-  readonly listen: (handler: Listener<undefined>) => Subscription;
-  readonly emit: (ns?: string[], delayed?: boolean) => void;
-};