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

package/lib/TolgeeCore.d.ts

@@ -0,0 +1,204 @@
+import { TolgeeOptions, TolgeePlugin, DevCredentials } from './types';
+declare const createTolgee: (options: TolgeeOptions) => Readonly<{
+    /**
+     * Listen to tolgee events.
+     */
+    on: import("./types").TolgeeOn<keyof import("./types").EventType>;
+    /**
+     * Listen for specific namespaces changes.
+     *
+     * ```
+     * const sub = tolgee.onUpdate(handler)
+     *
+     * // subscribe to selected namespace
+     * sub.subscribeNs(['common'])
+     *
+     * // unsubscribe
+     * sub.unsubscribe()
+     * ```
+     */
+    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.
+     */
+    getLanguage: () => string | undefined;
+    /**
+     * `pendingLanguage` represents language which is currently being loaded.
+     * @return current `pendingLanguage` if set.
+     */
+    getPendingLanguage: () => string | undefined;
+    /**
+     * 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: (language: string) => Promise<void>;
+    /**
+     * Temporarily change translation in cache.
+     * @return object with revert method.
+     */
+    changeTranslation: (descriptor: import("./types").CacheDescriptor, key: string, value: string) => {
+        revert: () => void;
+    };
+    /**
+     * Adds namespace(s) list of active namespaces. And if tolgee is running, loads required data.
+     */
+    addActiveNs: (ns: import("./types").NsFallback, forget?: boolean | undefined) => Promise<void>;
+    /**
+     * 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: (ns: import("./types").NsFallback) => void;
+    /**
+     * 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: (descriptors: import("./types").CacheDescriptor[]) => Promise<import("./types").TranslationsFlat[]>;
+    /**
+     * Manually load record from `Backend` (or `DevBackend` when in dev mode)
+     */
+    loadRecord: (descriptor: import("./types").CacheDescriptor) => Promise<import("./types").TranslationsFlat>;
+    /**
+     *
+     */
+    addStaticData: (data: import("./types").TolgeeStaticData | undefined) => void;
+    /**
+     * Get record from cache.
+     */
+    getRecord: (descriptor: import("./types").CacheDescriptor) => import("./types").TranslationsFlat | undefined;
+    /**
+     * Get all records from cache.
+     */
+    getAllRecords: () => {
+        data: import("./types").TranslationsFlat;
+        language: string;
+        namespace: string;
+    }[];
+    /**
+     * @param ns optional list of namespaces that you are interested in
+     * @return `true` if there are data that need to be fetched.
+     */
+    isLoaded: (ns?: import("./types").NsFallback) => boolean;
+    /**
+     * @return `true` if tolgee is loading initial data (triggered by `run`).
+     */
+    isInitialLoading: () => boolean;
+    /**
+     * @param ns optional list of namespaces that you are interested in
+     * @return `true` if tolgee is loading some translations for the first time.
+     */
+    isLoading: (ns?: import("./types").NsFallback) => boolean;
+    /**
+     * @param ns optional list of namespaces that you are interested in
+     * @return `true` if tolgee is fetching some translations.
+     */
+    isFetching: (ns?: import("./types").NsFallback) => boolean;
+    /**
+     * @return `true` if tolgee is running.
+     */
+    isRunning: () => boolean;
+    /**
+     * Changes internal state to running: true and loads initial files.
+     * Runs runnable plugins mainly Observer if present.
+     */
+    run: () => Promise<void | undefined>;
+    /**
+     * Changes internal state to running: false and stops runnable plugins.
+     */
+    stop: () => void;
+    /**
+     * Returns translated and formatted key.
+     * If Observer is present and tolgee is running, wraps result to be identifiable in the DOM.
+     */
+    t: import("./types").TFnType<import("./types").DefaultParamType, string>;
+    /**
+     * Highlight keys that match selection.
+     */
+    highlight: import("./types").HighlightInterface;
+    /**
+     * @return current Tolgee options.
+     */
+    getInitialOptions: () => {
+        apiUrl?: string | undefined;
+        apiKey?: string | undefined;
+        projectId?: string | number | undefined;
+        language?: string | undefined;
+        defaultLanguage?: string | undefined;
+        availableLanguages?: string[] | undefined;
+        fallbackLanguage?: import("./types").FallbackLanguageOption;
+        ns?: string[] | undefined;
+        fallbackNs?: import("./types").FallbackGeneral;
+        defaultNs: string;
+        staticData?: import("./types").TolgeeStaticData | undefined;
+        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.
+     * @return `true` if tolgee is in dev mode.
+     */
+    isDev: () => boolean;
+    /**
+     * Wraps translation if there is `Observer` plugin
+     */
+    wrap: (params: import("./types").WrapperWrapProps) => string | undefined;
+    /**
+     * Unwrap translation
+     */
+    unwrap: (text: string) => import("./types").Unwrapped;
+    /**
+     * Override creadentials passed on initialization.
+     *
+     * When called in running state, tolgee stops and runs again.
+     */
+    overrideCredentials(credentials: DevCredentials): void;
+    /**
+     * Add tolgee plugin after initialization.
+     *
+     * When called in running state, tolgee stops and runs again.
+     */
+    addPlugin(plugin: TolgeePlugin | undefined): void;
+    /**
+     * 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): void;
+}>;
+export declare type TolgeeInstance = ReturnType<typeof createTolgee>;
+export declare 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 declare const TolgeeCore: () => TolgeeChainer;
+export {};

package/lib/TranslateParams.d.ts

@@ -1,2 +1,2 @@
 import { TFnType, TranslateProps } from './types';
-export declare const getTranslateParams: TFnType<any, TranslateProps<any>>;
+export declare const getTranslateProps: TFnType<any, TranslateProps<any>>;

package/lib/helpers.d.ts

@@ -1,3 +1,11 @@
+import { FallbackGeneral, FallbackLanguageOption } from './types';
 export declare function isPromise(value: any): boolean;
 export declare const valueOrPromise: <T, R>(value: T | Promise<T>, callback: (value: T) => R) => R | Promise<R>;
 export declare const missingOptionError: (option: string) => string;
+export declare function isObject(item: any): boolean;
+export declare function getFallback(value: FallbackGeneral): string[] | undefined;
+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 { 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/lib/types/cache.d.ts

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

package/lib/types/events.d.ts

@@ -0,0 +1,66 @@
+import type { NsFallback } from './general';
+import type { CacheDescriptorWithKey } from './cache';
+export declare type Subscription = {
+    unsubscribe: () => void;
+};
+export declare 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 declare type ListenerEvent<T> = {
+    value: T;
+};
+export declare type Listener<T> = (e: ListenerEvent<T>) => void;
+export declare 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 declare 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/lib/types/general.d.ts

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

package/lib/types/index.d.ts

@@ -0,0 +1,7 @@
+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/lib/types/plugin.d.ts

@@ -0,0 +1,127 @@
+import { ChangeTranslationInterface, TreeTranslationsData } from './cache';
+import { NsFallback, NsType, TranslateParams, TranslatePropsInternal } from './general';
+import type { ObserverOptionsInternal } from '../Controller/State/observerOptions';
+import { TolgeeInstance } from '../TolgeeCore';
+export declare type BackendDevProps = {
+    apiUrl?: string;
+    apiKey?: string;
+    projectId?: number | string;
+};
+export declare type BackendGetRecordProps = {
+    language: string;
+    namespace?: string;
+};
+export declare type BackendGetRecord = (data: BackendGetRecordProps) => Promise<TreeTranslationsData | undefined> | undefined;
+export interface BackendMiddleware {
+    getRecord: BackendGetRecord;
+}
+export declare type BackendGetDevRecord = (data: BackendGetRecordProps & BackendDevProps) => Promise<TreeTranslationsData | undefined> | undefined;
+export declare type BackendDevMiddleware = {
+    getRecord: BackendGetDevRecord;
+};
+export declare type KeyAndParams = {
+    key: string;
+    params?: TranslateParams;
+    defaultValue?: string;
+    ns?: NsType;
+};
+export declare type Unwrapped = {
+    text: string;
+    keys: KeyAndParams[];
+};
+export declare type WrapperWrapProps = Pick<TranslatePropsInternal, 'key' | 'params' | 'defaultValue' | 'ns' | 'translation'>;
+export declare type WrapperWrapFunction = (props: WrapperWrapProps) => string;
+export declare type WrapperUnwrapFunction = (text: string) => Unwrapped;
+export declare type WrapperAttributeXPathGetter = (props: {
+    tag: string;
+    attribute: string;
+}) => string;
+export declare type HighlightInterface = (key?: string, ns?: NsFallback) => Highlighter;
+export declare type ObserverRunProps = {
+    mouseHighlight: boolean;
+};
+export declare type ObserverMiddleware = (props: ObserverProps) => {
+    unwrap: (text: string) => Unwrapped;
+    wrap: WrapperWrapFunction;
+    retranslate: () => void;
+    stop: () => void;
+    run: (props: ObserverRunProps) => void;
+    highlight: HighlightInterface;
+    outputNotFormattable: boolean;
+};
+export declare type LanguageDetectorProps = {
+    availableLanguages: string[];
+};
+export declare type LanguageDetectorMiddleware = {
+    getLanguage: (props: LanguageDetectorProps) => string | undefined | Promise<string | undefined>;
+};
+export declare type LanguageStorageMiddleware = {
+    getLanguage: () => string | undefined | Promise<string | undefined>;
+    setLanguage: (language: string) => void | Promise<void>;
+};
+export declare type DevCredentials = undefined | {
+    apiUrl?: string;
+    apiKey?: string;
+    projectId?: string | number;
+};
+export declare type WrapperMiddleware = {
+    unwrap: WrapperUnwrapFunction;
+    wrap: WrapperWrapFunction;
+    getTextXPath: () => string;
+    getAttributeXPath: WrapperAttributeXPathGetter;
+};
+export declare type FormatterMiddlewareFormatParams = {
+    translation: string;
+    language: string;
+    params: Record<string, any> | undefined;
+};
+export declare type FormatterMiddleware = {
+    format: (props: FormatterMiddlewareFormatParams) => string;
+};
+export declare type TranslationOnClick = (data: {
+    keysAndDefaults: KeyAndParams[];
+    event: any;
+}) => void;
+export declare type ObserverProps = {
+    translate: (params: TranslatePropsInternal) => string;
+    onClick: TranslationOnClick;
+    options: ObserverOptionsInternal;
+};
+export declare type Highlighter = {
+    unhighlight(): void;
+};
+export declare type FinalFormatterMiddleware = {
+    format: (props: FormatterMiddlewareFormatParams) => any;
+};
+export declare type UiProps = {
+    apiUrl: string;
+    apiKey: string;
+    projectId: number | string | undefined;
+    highlight: HighlightInterface;
+    changeTranslation: ChangeTranslationInterface;
+};
+export declare type UiKeyOption = {
+    key: string;
+    defaultValue?: string;
+    ns: string[];
+    translation: string | undefined;
+};
+export declare type UiMiddleware = (props: UiProps) => UiInterface;
+export interface UiInterface {
+    handleElementClick(keysAndDefaults: UiKeyOption[], event: any): Promise<void>;
+}
+export declare 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 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,9 +1,9 @@
 {
   "name": "@tolgee/core",
-  "version": "5.0.0-rc.9be0f0e.0",
+  "version": "5.0.0",
   "description": "Library providing ability to translate messages directly in context of developed application.",
   "main": "./dist/tolgee.cjs.js",
-  "module": "./dist/tolgee.esm.mjs",
+  "module": "./dist/tolgee.esm.js",
   "types": "./lib/index.d.ts",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
   "declaration": true,
   "exports": {
     "require": "./dist/tolgee.cjs.js",
-    "import": "./dist/tolgee.esm.mjs"
+    "import": "./dist/tolgee.esm.js"
   },
   "directories": {
     "lib": "lib",
@@ -49,6 +49,7 @@
     "@types/node": "^17.0.8",
     "@types/testing-library__jest-dom": "^5.14.5",
     "concurrently": "7.3.0",
+    "intl-messageformat": "^9.9.1",
     "jest": "^27.2.4",
     "jest-fetch-mock": "^3.0.3",
     "rollup": "^2.56.3",
@@ -61,5 +62,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "f2d1821b4e9c6af080a331a8a3378e5ad6488f92"
+  "gitHead": "7219c4f801aba29347a7c5c251178c2948432d24"
 }