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

package/src/FormatSimple/formatter.test.ts

@@ -0,0 +1,190 @@
+import { TranslateParams } from '../types';
+import IntlMessageFormat from 'intl-messageformat';
+import { formatter } from './formatter';
+import {
+  ErrorCode,
+  ERROR_PARAM_EMPTY,
+  ERROR_UNEXPECTED_CHAR,
+  ERROR_UNEXPECTED_END,
+  FormatError,
+} from './FormatError';
+
+function icu(text: string, params?: TranslateParams) {
+  return new IntlMessageFormat(text, 'en', undefined, {
+    ignoreTag: true,
+  }).format(params);
+}
+
+function getText() {
+  return expect.getState().currentTestName.replace('simple formatter ', '');
+}
+
+function matchIcu(params?: TranslateParams) {
+  const text = getText();
+  expect(formatter(text, params)).toEqual(icu(text, params));
+}
+
+function expectToThrow(
+  text: string,
+  code?: ErrorCode,
+  params?: TranslateParams
+) {
+  let error: FormatError | undefined = undefined;
+  try {
+    formatter(text, params);
+  } catch (e) {
+    error = e as FormatError;
+  }
+  expect(error).toBeInstanceOf(FormatError);
+  expect(error?.code).toEqual(code);
+}
+
+function expectToThrowWithIcu(code?: ErrorCode, params?: TranslateParams) {
+  const text = getText();
+  expect(() => icu(text, params)).toThrow();
+  expectToThrow(text, code, params);
+}
+
+function unsupported(code?: ErrorCode, params?: TranslateParams) {
+  const text = getText();
+  expect(() => icu(text, params)).not.toThrow();
+  expectToThrow(text, code, params);
+}
+
+function combineChars(chars: string[]) {
+  const result: string[] = [];
+  chars.forEach((char) => {
+    [`start${char}`, `${char}end`, `mid${char}dle`, char].forEach((param) => {
+      result.push(param);
+    });
+  });
+  return result;
+}
+
+function characterInParamSupported(chars: string[]) {
+  combineChars(chars).forEach((param) => {
+    const text = `test { ${param} } param`;
+    it(`works with: ${text}`, () => {
+      const params = { [param]: 'valid' };
+      expect(icu(text, params)).toEqual('test valid param');
+      expect(formatter(text, params)).toEqual('test valid param');
+    });
+  });
+}
+
+function characterInParamFailWithIcu(chars: string[]) {
+  combineChars(chars).forEach((param) => {
+    const text = `test { ${param} } param`;
+    it(`fails with: ${text}`, () => {
+      const params = { [param]: 'test' };
+      expect(() => icu(text, params)).toThrow();
+      expectToThrow(text, ERROR_UNEXPECTED_CHAR, params);
+    });
+  });
+}
+
+function characterInParamFail(chars: string[]) {
+  combineChars(chars).forEach((param) => {
+    const text = `test { ${param} } param`;
+    it(`works with: ${text}`, () => {
+      const params = { [param]: 'valid' };
+      expectToThrow(text, ERROR_UNEXPECTED_CHAR, params);
+    });
+  });
+}
+
+describe('simple formatter', () => {
+  test('test test', () => {
+    expect(getText()).toEqual('test test');
+  });
+
+  test('simple test', () => {
+    matchIcu();
+  });
+
+  test('this is {name}', () => {
+    matchIcu({ name: 'Bob' });
+  });
+
+  test('this is {  name  }', () => {
+    matchIcu({ name: 'Bob' });
+  });
+
+  test('{ user } has { num } apples.', () => {
+    matchIcu({ user: 'John', num: 2 });
+  });
+
+  test('passing params, but no params here', () => {
+    matchIcu({ user: 'John', num: 2 });
+  });
+
+  test('{ user } has { user } apples.', () => {
+    matchIcu({ user: 'John', num: 2 });
+  });
+
+  test("ICU: '{ parameter '} format", () => {
+    matchIcu();
+  });
+
+  test("this '{ escaped }' well", () => {
+    matchIcu();
+  });
+
+  test("this is '{ weird } but valid", () => {
+    matchIcu();
+  });
+
+  test("edge case '", () => {
+    matchIcu();
+  });
+
+  test("What's {subject}?", () => {
+    matchIcu({ subject: 'that' });
+  });
+
+  test('this is also } right', () => {
+    matchIcu();
+  });
+
+  test('this is just {} wrong', () => {
+    expectToThrowWithIcu(ERROR_PARAM_EMPTY);
+  });
+
+  test('this also { } wrong', () => {
+    expectToThrowWithIcu(ERROR_PARAM_EMPTY);
+  });
+
+  test('this plain { , } wrong', () => {
+    expectToThrowWithIcu(ERROR_UNEXPECTED_CHAR);
+  });
+
+  test('this is { unexpected', () => {
+    expectToThrowWithIcu(ERROR_UNEXPECTED_END);
+  });
+
+  test('this is obviously bad { yo yo }', () => {
+    expectToThrowWithIcu(ERROR_UNEXPECTED_CHAR);
+  });
+
+  test('this is obviously bad { yo, }', () => {
+    expectToThrowWithIcu(ERROR_UNEXPECTED_CHAR);
+  });
+
+  test('good for icu { yo, number } not for me', () => {
+    unsupported(ERROR_UNEXPECTED_CHAR, { yo: 6 });
+  });
+
+  describe('supported characters in params', () => {
+    characterInParamSupported(Array.from('019_axAX'));
+  });
+
+  describe('invalid characters in params', () => {
+    characterInParamFailWithIcu('[+-@#$~^&*{%)(§\'"`!?:.;<>[]\\=|☺'.split(''));
+  });
+
+  describe('unsupported characters which are supported in ICU', () => {
+    characterInParamFail(Array.from('šřýíéúůĚŽÝÁÍÉůú¨ˇ'));
+    characterInParamFail(['汉字', '字', 'हि', 'हिन्दी']);
+    characterInParamFail(['😊']);
+  });
+});

package/src/FormatSimple/formatter.ts

@@ -0,0 +1,19 @@
+import { DefaultParamType, TranslateParams } from '../types';
+import { formatParser } from './formatParser';
+
+export function formatter(
+  translation: string,
+  params?: TranslateParams<DefaultParamType>
+) {
+  const [texts, pars] = formatParser(translation);
+  const result = [texts[0]];
+  for (let i = 1; i < texts.length; i++) {
+    const parameter = params?.[pars[i - 1]];
+    if (parameter === undefined) {
+      throw new Error(`Missing parameter "${pars[i - 1]}" in "${translation}"`);
+    }
+    result.push(String(parameter));
+    result.push(texts[i]);
+  }
+  return result.join('');
+}

package/src/TolgeeCore.ts

@@ -0,0 +1,267 @@
+import { Controller } from './Controller/Controller';
+import { combineOptions } from './Controller/State/initState';
+import { TolgeeOptions, TolgeePlugin, DevCredentials } from './types';
+
+const createTolgee = (options: TolgeeOptions) => {
+  const controller = Controller({
+    options,
+  });
+
+  // restarts tolgee while applying callback
+  const withRestart = (callback: () => void) => {
+    const wasRunning = controller.isRunning();
+    wasRunning && controller.stop();
+    callback();
+    wasRunning && controller.run();
+  };
+
+  const tolgee = Object.freeze({
+    /**
+     * Listen to tolgee events.
+     */
+    on: controller.on,
+
+    /**
+     * Listen for specific namespaces changes.
+     *
+     * ```
+     * const sub = tolgee.onUpdate(handler)
+     *
+     * // subscribe to selected namespace
+     * sub.subscribeNs(['common'])
+     *
+     * // unsubscribe
+     * sub.unsubscribe()
+     * ```
+     */
+    onNsUpdate: controller.onUpdate.listenSome,
+
+    /**
+     * Turn off/on events emitting. Is on by default.
+     */
+    setEmmiterActive: controller.setEmmiterActive,
+
+    /**
+     * @return current language if set.
+     */
+    getLanguage: controller.getLanguage,
+
+    /**
+     * `pendingLanguage` represents language which is currently being loaded.
+     * @return current `pendingLanguage` if set.
+     */
+    getPendingLanguage: controller.getPendingLanguage,
+
+    /**
+     * Change current language.
+     * - if not running sets `pendingLanguage`, `language` to the new value
+     * - if running sets `pendingLanguage` to the value, fetches necessary data and then changes `language`
+     *
+     * @return Promise which is resolved when `language` is changed.
+     */
+    changeLanguage: controller.changeLanguage,
+
+    /**
+     * Temporarily change translation in cache.
+     * @return object with revert method.
+     */
+    changeTranslation: controller.changeTranslation,
+
+    /**
+     * Adds namespace(s) list of active namespaces. And if tolgee is running, loads required data.
+     */
+    addActiveNs: controller.addActiveNs,
+
+    /**
+     * Remove namespace(s) from active namespaces.
+     *
+     * Tolgee internally counts how many times was each active namespace added,
+     * so this method will remove namespace only if the counter goes down to 0.
+     */
+    removeActiveNs: controller.removeActiveNs,
+
+    /**
+     * Manually load multiple records from `Backend` (or `DevBackend` when in dev mode)
+     *
+     * It loads data together and adds them to cache in one operation, to prevent partly loaded state.
+     */
+    loadRecords: controller.loadRecords,
+
+    /**
+     * Manually load record from `Backend` (or `DevBackend` when in dev mode)
+     */
+    loadRecord: controller.loadRecord,
+
+    /**
+     *
+     */
+    addStaticData: controller.addStaticData,
+
+    /**
+     * Get record from cache.
+     */
+    getRecord: controller.getRecord,
+
+    /**
+     * Get all records from cache.
+     */
+    getAllRecords: controller.getAllRecords,
+
+    /**
+     * @param ns optional list of namespaces that you are interested in
+     * @return `true` if there are data that need to be fetched.
+     */
+    isLoaded: controller.isLoaded,
+
+    /**
+     * @return `true` if tolgee is loading initial data (triggered by `run`).
+     */
+    isInitialLoading: controller.isInitialLoading,
+
+    /**
+     * @param ns optional list of namespaces that you are interested in
+     * @return `true` if tolgee is loading some translations for the first time.
+     */
+    isLoading: controller.isLoading,
+
+    /**
+     * @param ns optional list of namespaces that you are interested in
+     * @return `true` if tolgee is fetching some translations.
+     */
+    isFetching: controller.isFetching,
+
+    /**
+     * @return `true` if tolgee is running.
+     */
+    isRunning: controller.isRunning,
+
+    /**
+     * Changes internal state to running: true and loads initial files.
+     * Runs runnable plugins mainly Observer if present.
+     */
+    run: controller.run,
+
+    /**
+     * Changes internal state to running: false and stops runnable plugins.
+     */
+    stop: controller.stop,
+
+    /**
+     * Returns translated and formatted key.
+     * If Observer is present and tolgee is running, wraps result to be identifiable in the DOM.
+     */
+    t: controller.t,
+
+    /**
+     * Highlight keys that match selection.
+     */
+    highlight: controller.highlight,
+
+    /**
+     * @return current Tolgee options.
+     */
+    getInitialOptions: controller.getInitialOptions,
+
+    /**
+     * Tolgee is in dev mode if `DevTools` plugin is used and `apiKey` + `apiUrl` are specified.
+     * @return `true` if tolgee is in dev mode.
+     */
+    isDev: controller.isDev,
+
+    /**
+     * Wraps translation if there is `Observer` plugin
+     */
+    wrap: controller.wrap,
+
+    /**
+     * Unwrap translation
+     */
+    unwrap: controller.unwrap,
+
+    /**
+     * Override creadentials passed on initialization.
+     *
+     * When called in running state, tolgee stops and runs again.
+     */
+    overrideCredentials(credentials: DevCredentials) {
+      withRestart(() => controller.overrideCredentials(credentials));
+    },
+
+    /**
+     * Add tolgee plugin after initialization.
+     *
+     * When called in running state, tolgee stops and runs again.
+     */
+    addPlugin(plugin: TolgeePlugin | undefined) {
+      if (plugin) {
+        withRestart(() => controller.addPlugin(tolgee, plugin));
+      }
+    },
+
+    /**
+     * Updates options after instance creation. Extends existing options,
+     * so it only changes the fields, that are listed.
+     *
+     * When called in running state, tolgee stops and runs again.
+     */
+    updateOptions(options?: TolgeeOptions) {
+      if (options) {
+        withRestart(() => controller.init(options));
+      }
+    },
+  });
+
+  return tolgee;
+};
+
+export type TolgeeInstance = ReturnType<typeof createTolgee>;
+
+export type TolgeeChainer = {
+  /**
+   * Add plugin, plugins are applied when `init` method is called.
+   */
+  use: (plugin: TolgeePlugin | undefined) => TolgeeChainer;
+
+  /**
+   * Update default options before tolgee is initialized.
+   */
+  updateDefaults: (options: TolgeeOptions) => TolgeeChainer;
+
+  /**
+   * Initialize tolgee options and apply plugins
+   * @returns tolgee instance
+   */
+  init(options?: TolgeeOptions): TolgeeInstance;
+};
+
+/**
+ * Tolgee chainable constructor.
+ *
+ * Usage:
+ * ```
+ * const tolgee = Tolgee().use(...).init(...)
+ * ```
+ */
+export const TolgeeCore = (): TolgeeChainer => {
+  const state = {
+    plugins: [] as (TolgeePlugin | undefined)[],
+    options: {} as TolgeeOptions,
+  };
+
+  const tolgeeChain = Object.freeze({
+    use(plugin: TolgeePlugin | undefined) {
+      state.plugins.push(plugin);
+      return tolgeeChain;
+    },
+    updateDefaults(options: TolgeeOptions) {
+      state.options = combineOptions(state.options, options);
+      return tolgeeChain;
+    },
+    init(options?: TolgeeOptions) {
+      const tolgee = createTolgee(combineOptions(state.options, options));
+      state.plugins.forEach(tolgee.addPlugin);
+      return tolgee;
+    },
+  });
+  return tolgeeChain;
+};

package/src/TranslateParams.test.ts

@@ -1,40 +1,37 @@
-import { getTranslateParams } from './TranslateParams';
+import { getTranslateProps } from './TranslateParams';
 import { TranslateProps } from './types';
 
 const testParams: TranslateProps = {
   key: 'test',
   defaultValue: 'Test',
   noWrap: true,
-  ns: [],
+  ns: 'test',
   orEmpty: true,
-  params: { yo: 'yo', ns: '(this is param not namespace)' },
+  params: { yo: 'yo' },
 };
 
-describe('getTranslateParams', () => {
+describe('getTranslateProps', () => {
   it('manages regular params', () => {
-    const result = getTranslateParams(testParams);
+    const result = getTranslateProps(testParams);
     expect(result).toEqual(testParams);
   });
 
   it('manages key with default value', () => {
-    const result = getTranslateParams('test', 'Test');
+    const result = getTranslateProps('test', 'Test');
     expect(result).toEqual({ key: 'test', defaultValue: 'Test' });
   });
 
   it('manages key with options', () => {
-    const result = getTranslateParams('test', { noWrap: true, yo: 'yo' });
+    const result = getTranslateProps('test', { noWrap: true, yo: 'yo' });
     expect(result).toEqual({ key: 'test', noWrap: true, params: { yo: 'yo' } });
   });
 
   it('manages key default and options', () => {
-    const result = getTranslateParams('test', 'Test', {
+    const result = getTranslateProps('test', 'Test', {
       noWrap: true,
-      ns: [],
+      ns: 'test',
       orEmpty: true,
       yo: 'yo',
-      params: {
-        ns: '(this is param not namespace)',
-      },
     });
     expect(result).toEqual(testParams);
   });

package/src/TranslateParams.ts

@@ -11,20 +11,21 @@ function parseCombinedOptions({
   orEmpty,
   params,
   ...rest
-}: CombinedOptions<any>): Partial<TranslateProps> {
-  const options: Required<TranslateOptions<any>> = {
+}: Partial<TranslateProps>): Partial<TranslateProps> {
+  const options: Required<TranslateOptions> = {
     ns: ns!,
     noWrap: noWrap!,
     orEmpty: orEmpty!,
+  };
+  return {
+    ...options,
     params: {
       ...rest,
-      ...params,
     },
   };
-  return options;
 }
 
-export const getTranslateParams: TFnType<any, TranslateProps<any>> = (
+export const getTranslateProps: TFnType<any, TranslateProps<any>> = (
   keyOrProps,
   ...params
 ) => {

package/src/__test/backend.test.ts

@@ -1,5 +1,5 @@
-import { Tolgee } from '../Tolgee';
-import { BackendInterface, TolgeePlugin } from '../types';
+import { TolgeeCore } from '../TolgeeCore';
+import { BackendMiddleware, TolgeePlugin } from '../types';
 
 const data = {
   en: {
@@ -12,13 +12,13 @@ const data = {
   },
 } as any;
 
-const backendNormal: BackendInterface = {
+const backendNormal: BackendMiddleware = {
   getRecord({ language, namespace = '' }) {
     return data[language]?.[namespace];
   },
 };
 
-const backendDev: BackendInterface = {
+const backendDev: BackendMiddleware = {
   getRecord() {
     return Promise.resolve({ cancel: 'Dev' });
   },
@@ -32,7 +32,7 @@ const backendPlugin: TolgeePlugin = (tolgee, tools) => {
 
 describe('backend plugins', () => {
   it('uses plugin to fetch', async () => {
-    const tolgee = Tolgee()
+    const tolgee = TolgeeCore()
       .use(backendPlugin)
       .init({
         ns: ['common', 'test'],
@@ -41,7 +41,7 @@ describe('backend plugins', () => {
     await tolgee.run();
     expect(tolgee.t({ key: 'cancel', ns: 'common' })).toEqual('Cancel');
     tolgee.stop();
-    tolgee.init({ apiUrl: 'asdfasdf', apiKey: 'test' });
+    tolgee.overrideCredentials({ apiUrl: 'asdfasdf', apiKey: 'test' });
     await tolgee.run();
     expect(tolgee.t({ key: 'cancel', ns: 'common' })).toEqual('Dev');
   });