@tolgee/core 4.10.0-rc.d9fac95.0 → 5.0.0-alpha.1

package/dist/tolgee.cjs.js

@@ -2,25 +2,18 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-const EventEmitter = () => {
-    let handlers = [];
-    const listen = (handler) => {
-        const handlerWrapper = (e) => {
-            handler(e);
-        };
-        handlers.push(handlerWrapper);
-        return {
-            unsubscribe: () => {
-                handlers = handlers.filter((i) => handlerWrapper !== i);
-            },
-        };
-    };
-    const emit = (data) => {
-        handlers.forEach((handler) => handler({ value: data }));
-    };
-    return Object.freeze({ listen, emit });
+function isPromise(value) {
+    return Boolean(value && typeof value.then === 'function');
+}
+const valueOrPromise = (value, callback) => {
+    if (isPromise(value)) {
+        return Promise.resolve(value).then(callback);
+    }
+    else {
+        return callback(value);
+    }
 };
-
+const missingOptionError = (option) => `Tolgee: You need to specify '${option}' option`;
 function isObject(item) {
     return typeof item === 'object' && !Array.isArray(item) && item !== null;
 }
@@ -47,22 +40,30 @@ function getFallbackFromStruct(language, fallbackLanguage) {
 function unique(arr) {
     return Array.from(new Set(arr));
 }
-
-function incrementInMap(map, value) {
-    const currNum = map.get(value) || 0;
-    map.set(value, currNum + 1);
-}
-function decrementInMap(map, value) {
-    let currNum = map.get(value) || 1;
-    currNum -= 1;
-    if (currNum <= 0) {
-        map.delete(value);
-    }
-    else {
-        map.set(value, currNum);
-    }
+function sanitizeUrl(url) {
+    return url ? url.replace(/\/+$/, '') : url;
 }
-const EventEmitterSelective = (getFallbackNamespaces) => {
+
+const EventEmitter = () => {
+    let handlers = [];
+    const listen = (handler) => {
+        const handlerWrapper = (e) => {
+            handler(e);
+        };
+        handlers.push(handlerWrapper);
+        return {
+            unsubscribe: () => {
+                handlers = handlers.filter((i) => handlerWrapper !== i);
+            },
+        };
+    };
+    const emit = (data) => {
+        handlers.forEach((handler) => handler({ value: data }));
+    };
+    return Object.freeze({ listen, emit });
+};
+
+const EventEmitterSelective = (getFallbackNs, getDefaultNs) => {
     const listeners = new Set();
     const partialListeners = new Set();
     const listen = (handler) => {
@@ -79,8 +80,7 @@ const EventEmitterSelective = (getFallbackNamespaces) => {
             fn: (e) => {
                 handler(e);
             },
-            keys: new Map(),
-            namespaces: new Map(),
+            namespaces: new Set(),
         };
         partialListeners.add(handlerWrapper);
         const result = {
@@ -88,52 +88,24 @@ const EventEmitterSelective = (getFallbackNamespaces) => {
                 partialListeners.delete(handlerWrapper);
             },
             subscribeNs: (ns) => {
-                getFallbackArray(ns).forEach((val) => incrementInMap(handlerWrapper.namespaces, val));
-                return result;
-            },
-            unsubscribeNs: (ns) => {
-                getFallbackArray(ns).forEach((val) => decrementInMap(handlerWrapper.namespaces, val));
-                return result;
-            },
-            subscribeKey: (descriptor) => {
-                const { key, ns } = descriptor;
-                incrementInMap(handlerWrapper.keys, key);
-                getFallbackArray(ns).forEach((val) => incrementInMap(handlerWrapper.namespaces, val));
-                if (ns === undefined) {
-                    // subscribing to all namespaces
-                    incrementInMap(handlerWrapper.namespaces, undefined);
-                }
-                return result;
-            },
-            unsubscribeKey: (descriptor) => {
-                const { key, ns } = descriptor;
-                decrementInMap(handlerWrapper.keys, key);
-                getFallbackArray(ns).forEach((val) => decrementInMap(handlerWrapper.namespaces, val));
+                getFallbackArray(ns).forEach((val) => handlerWrapper.namespaces.add(val));
                 if (ns === undefined) {
-                    // subscribing to all namespaces
-                    decrementInMap(handlerWrapper.namespaces, undefined);
+                    // subscribing to default ns
+                    handlerWrapper.namespaces.add(getDefaultNs());
                 }
                 return result;
             },
         };
         return result;
     };
-    const namespacesWithFallbacks = (namespaces) => {
-        if (namespaces.has(undefined)) {
-            const result = new Set(namespaces.keys());
-            result.delete(undefined);
-            getFallbackNamespaces().forEach((ns) => result.add(ns));
-            return result;
-        }
-        return namespaces;
-    };
-    const callHandlers = (key, ns) => {
+    const callHandlers = (ns) => {
+        // everything is implicitly subscribed to fallbacks
+        // as it can always fall through to it
+        const fallbackNamespaces = new Set(getFallbackNs());
         partialListeners.forEach((handler) => {
-            const handlerNamespaces = namespacesWithFallbacks(handler.namespaces);
             const nsMatches = ns === undefined ||
-                (ns === null || ns === void 0 ? void 0 : ns.findIndex((ns) => handlerNamespaces.has(ns))) !== -1;
-            const keyMatches = key === undefined || handler.keys.has(key) || handler.keys.size === 0;
-            if (nsMatches && keyMatches) {
+                (ns === null || ns === void 0 ? void 0 : ns.findIndex((ns) => fallbackNamespaces.has(ns) || handler.namespaces.has(ns))) !== -1;
+            if (nsMatches) {
                 handler.fn({ value: undefined });
             }
         });
@@ -144,61 +116,51 @@ const EventEmitterSelective = (getFallbackNamespaces) => {
         if (queue.length === 0) {
             return;
         }
+        const queueCopy = queue;
+        queue = [];
         listeners.forEach((handler) => {
             handler({ value: undefined });
         });
-        const namespaces = new Set();
-        let keys = new Set();
-        queue.forEach((descriptor) => {
-            if ((descriptor === null || descriptor === void 0 ? void 0 : descriptor.ns) === undefined) {
-                // when no ns specified, it affets all fallback namespaces
-                namespaces.add(undefined);
+        let namespaces = new Set();
+        queueCopy.forEach((ns) => {
+            if (ns === undefined) {
+                // when no ns specified, it affects all namespaces
+                namespaces = undefined;
             }
-            else {
-                descriptor.ns.forEach((ns) => namespaces.add(ns));
-            }
-            if ((descriptor === null || descriptor === void 0 ? void 0 : descriptor.key) === undefined) {
-                // when no key specified, it affects all keys
-                keys = undefined;
-            }
-            else if (keys !== undefined) {
-                keys.add(descriptor.key);
+            else if (namespaces !== undefined) {
+                ns.forEach((ns) => namespaces.add(ns));
             }
         });
-        const namespacesArray = Array.from(namespacesWithFallbacks(namespaces).keys());
-        (keys || [undefined]).forEach((key) => {
-            callHandlers(key, namespacesArray);
-        });
-        queue = [];
+        const namespacesArray = namespaces
+            ? Array.from(namespaces.keys())
+            : undefined;
+        callHandlers(namespacesArray);
     };
-    const emit = (descriptor, delayed) => {
-        queue.push(descriptor);
+    const emit = (ns, delayed) => {
+        queue.push(ns);
         if (!delayed) {
             solveQueue();
         }
         else {
-            Promise.resolve().then(() => {
-                solveQueue();
-            });
+            setTimeout(solveQueue, 0);
         }
     };
     return Object.freeze({ listenSome, listen, emit });
 };
 
-const Events = (getFallbackNamespaces) => {
+const Events = (getFallbackNs, getDefaultNs) => {
     const onPendingLanguageChange = EventEmitter();
     const onLanguageChange = EventEmitter();
-    const onKeyChange = EventEmitter();
     const onLoadingChange = EventEmitter();
     const onFetchingChange = EventEmitter();
     const onInitialLoaded = EventEmitter();
-    const onKeyUpdate = EventEmitterSelective(getFallbackNamespaces);
-    const onCacheChange = EventEmitter();
     const onRunningChange = EventEmitter();
-    onInitialLoaded.listen(() => onKeyUpdate.emit());
-    onLanguageChange.listen(() => onKeyUpdate.emit());
+    const onCacheChange = EventEmitter();
+    const onUpdate = EventEmitterSelective(getFallbackNs, getDefaultNs);
+    onInitialLoaded.listen(() => onUpdate.emit());
+    onLanguageChange.listen(() => onUpdate.emit());
     onCacheChange.listen(({ value }) => {
-        onKeyUpdate.emit({ ns: [value.namespace], key: value.key }, true);
+        onUpdate.emit([value.namespace], true);
     });
     const on = (event, handler) => {
         switch (event) {
@@ -216,20 +178,19 @@ const Events = (getFallbackNamespaces) => {
                 return onRunningChange.listen(handler);
             case 'cache':
                 return onCacheChange.listen(handler);
-            case 'keyUpdate':
-                return onKeyUpdate.listen(handler);
+            case 'update':
+                return onUpdate.listen(handler);
         }
     };
     return Object.freeze({
         onPendingLanguageChange,
         onLanguageChange,
-        onKeyChange,
-        onKeyUpdate,
         onLoadingChange,
         onFetchingChange,
         onInitialLoaded,
         onRunningChange,
         onCacheChange,
+        onUpdate,
         on,
     });
 };
@@ -252,7 +213,9 @@ const flattenTranslations = (data) => {
     return result;
 };
 const decodeCacheKey = (key) => {
-    const [firstPart, secondPart] = key.split(':');
+    const [firstPart, ...rest] = key.split(':');
+    // if namespaces contains ":" it won't get lost
+    const secondPart = rest.join(':');
     return { language: firstPart, namespace: secondPart || '' };
 };
 const encodeCacheKey = ({ language, namespace, }) => {
@@ -320,11 +283,11 @@ const Cache = (onCacheChange, backendGetRecord, backendGetDevRecord, withDefault
                 const value = (_a = cache
                     .get(encodeCacheKey({ language, namespace }))) === null || _a === void 0 ? void 0 : _a.data.get(key);
                 if (value !== undefined && value !== null) {
-                    return namespace;
+                    return [namespace];
                 }
             }
         }
-        return Array.from(new Set(namespaces));
+        return unique(namespaces);
     }
     function getTranslationFallback(namespaces, languages, key) {
         var _a;
@@ -367,7 +330,10 @@ const Cache = (onCacheChange, backendGetRecord, backendGetDevRecord, withDefault
                     }));
             }));
     }
-    function fetchNormal(keyObject) {
+    /**
+     * Fetches production data
+     */
+    function fetchProd(keyObject) {
         let dataPromise = undefined;
         if (!dataPromise) {
             const staticDataValue = staticData[encodeCacheKey(keyObject)];
@@ -378,10 +344,6 @@ const Cache = (onCacheChange, backendGetRecord, backendGetDevRecord, withDefault
         if (!dataPromise) {
             dataPromise = backendGetRecord(keyObject);
         }
-        if (!dataPromise) {
-            // return empty data, so we know it has already been attempted to fetch
-            dataPromise = Promise.resolve({});
-        }
         return dataPromise;
     }
     function fetchData(keyObject, isDev) {
@@ -391,12 +353,12 @@ const Cache = (onCacheChange, backendGetRecord, backendGetDevRecord, withDefault
             dataPromise = (_a = backendGetDevRecord(keyObject)) === null || _a === void 0 ? void 0 : _a.catch(() => {
                 // eslint-disable-next-line no-console
                 console.warn(`Tolgee: Failed to fetch data from dev backend`);
-                // fallback to normal fetch if dev fails
-                return fetchNormal(keyObject);
+                // fallback to prod fetch if dev fails
+                return fetchProd(keyObject);
             });
         }
         if (!dataPromise) {
-            dataPromise = fetchNormal(keyObject);
+            dataPromise = fetchProd(keyObject);
         }
         return dataPromise;
     }
@@ -413,7 +375,7 @@ const Cache = (onCacheChange, backendGetRecord, backendGetDevRecord, withDefault
                     cacheKey,
                 };
             }
-            const dataPromise = fetchData(keyObject, isDev);
+            const dataPromise = fetchData(keyObject, isDev) || Promise.resolve(undefined);
             asyncRequests.set(cacheKey, dataPromise);
             return {
                 new: true,
@@ -435,6 +397,10 @@ const Cache = (onCacheChange, backendGetRecord, backendGetDevRecord, withDefault
                 if (data) {
                     addRecord(value.keyObject, data);
                 }
+                else if (!getRecord(value.keyObject)) {
+                    // if no data exist, put empty object
+                    addRecord(value.keyObject, {});
+                }
             }
         });
         fetchingObserver.notify();
@@ -464,20 +430,9 @@ const Cache = (onCacheChange, backendGetRecord, backendGetDevRecord, withDefault
     });
 };
 
-function isPromise(value) {
-    return Boolean(value && typeof value.then === 'function');
-}
-const valueOrPromise = (value, callback) => {
-    if (isPromise(value)) {
-        return Promise.resolve(value).then(callback);
-    }
-    else {
-        return callback(value);
-    }
-};
-const missingOptionError = (option) => `Tolgee: You need to specify '${option}' option`;
-
-const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAvailableLanguages, getTranslationNs, getTranslation, changeTranslation) => {
+const Plugins = (getLanguage, getInitialOptions, getAvailableLanguages, getTranslationNs, getTranslation, changeTranslation) => {
+    let prepared = false;
+    let onPrepareQueue = [];
     const plugins = {
         ui: undefined,
         observer: undefined,
@@ -492,37 +447,20 @@ const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAv
         languageDetector: undefined,
         languageStorage: undefined,
     };
-    const onClick = async (event, { keysAndDefaults }) => {
+    const onClick = async ({ keysAndDefaults, event }) => {
         var _a;
-        const withNs = keysAndDefaults.map(({ key, ns, defaultValue }) => ({
-            key,
-            defaultValue,
-            ns: getFallbackArray(getTranslationNs({ key, ns, defaultValue })),
-            translation: getTranslation({
+        const withNs = keysAndDefaults.map(({ key, ns, defaultValue }) => {
+            return {
                 key,
-                ns,
-            }),
-        }));
-        (_a = instances.ui) === null || _a === void 0 ? void 0 : _a.handleElementClick(event, withNs);
-    };
-    const run = (isDev) => {
-        var _a, _b;
-        if (!instances.ui && plugins.ui) {
-            instances.ui = new plugins.ui({
-                apiKey: getInitialOptions().apiKey,
-                apiUrl: getInitialOptions().apiUrl,
-                highlight,
-                changeTranslation,
-            });
-        }
-        if (!instances.observer) {
-            instances.observer = (_a = plugins.observer) === null || _a === void 0 ? void 0 : _a.call(plugins, {
-                translate,
-                onClick,
-                options: getObserverOptions(),
-            });
-        }
-        (_b = instances.observer) === null || _b === void 0 ? void 0 : _b.run({ mouseHighlight: isDev });
+                defaultValue,
+                ns: getTranslationNs({ key, ns }),
+                translation: getTranslation({
+                    key,
+                    ns,
+                }),
+            };
+        });
+        (_a = instances.ui) === null || _a === void 0 ? void 0 : _a.handleElementClick(withNs, event);
     };
     const stop = () => {
         var _a;
@@ -534,7 +472,10 @@ const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAv
         return ((_b = (_a = instances.observer) === null || _a === void 0 ? void 0 : _a.highlight) === null || _b === void 0 ? void 0 : _b.call(_a, key, ns)) || { unhighlight() { } };
     };
     const translate = (props) => {
-        const translation = getTranslation(props);
+        const translation = getTranslation({
+            key: props.key,
+            ns: props.ns,
+        });
         return formatTranslation(Object.assign(Object.assign({}, props), { translation, formatEnabled: true }));
     };
     const setObserver = (observer) => {
@@ -560,9 +501,6 @@ const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAv
     const setLanguageStorage = (storage) => {
         instances.languageStorage = storage;
     };
-    const getLanguageStorage = () => {
-        return instances.languageStorage;
-    };
     const setStoredLanguage = (language) => {
         var _a;
         (_a = instances.languageStorage) === null || _a === void 0 ? void 0 : _a.setLanguage(language);
@@ -602,14 +540,37 @@ const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAv
     const setDevBackend = (backend) => {
         instances.devBackend = backend;
     };
+    const run = (isDev) => {
+        var _a, _b;
+        if (!instances.ui && plugins.ui) {
+            const { apiKey, apiUrl, projectId } = getInitialOptions();
+            instances.ui = new plugins.ui({
+                apiKey: apiKey,
+                apiUrl: apiUrl,
+                projectId,
+                highlight,
+                changeTranslation,
+            });
+        }
+        if (!instances.observer) {
+            instances.observer = (_a = plugins.observer) === null || _a === void 0 ? void 0 : _a.call(plugins, {
+                translate,
+                onClick,
+                options: getInitialOptions().observerOptions,
+            });
+        }
+        (_b = instances.observer) === null || _b === void 0 ? void 0 : _b.run({ mouseHighlight: isDev });
+    };
     const getDevBackend = () => {
         return instances.devBackend;
     };
     const getBackendDevRecord = ({ language, namespace }) => {
         var _a;
+        const { apiKey, apiUrl, projectId } = getInitialOptions();
         return (_a = instances.devBackend) === null || _a === void 0 ? void 0 : _a.getRecord({
-            apiKey: getInitialOptions().apiKey,
-            apiUrl: getInitialOptions().apiUrl,
+            apiKey,
+            apiUrl,
+            projectId,
             language,
             namespace,
         });
@@ -630,7 +591,40 @@ const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAv
         }
         return undefined;
     };
-    const formatTranslation = ({ key, translation, defaultValue, noWrap, params, orEmpty, ns, formatEnabled, }) => {
+    const unwrap = (text) => {
+        var _a;
+        if (instances.observer) {
+            return (_a = instances.observer) === null || _a === void 0 ? void 0 : _a.unwrap(text);
+        }
+        return { text, keys: [] };
+    };
+    const retranslate = () => {
+        var _a;
+        (_a = instances.observer) === null || _a === void 0 ? void 0 : _a.retranslate();
+    };
+    const onPrepare = (callback) => {
+        onPrepareQueue.push(callback);
+    };
+    function addPlugin(tolgeeInstance, plugin) {
+        const pluginTools = Object.freeze({
+            setFinalFormatter,
+            addFormatter,
+            setObserver,
+            hasObserver,
+            setUi,
+            hasUi,
+            setDevBackend,
+            addBackend,
+            setLanguageDetector,
+            setLanguageStorage,
+            onPrepare,
+        });
+        plugin(tolgeeInstance, pluginTools);
+        if (prepared) {
+            prepare();
+        }
+    }
+    function formatTranslation({ key, translation, defaultValue, noWrap, params, orEmpty, ns, formatEnabled, }) {
         var _a;
         const formattableTranslation = translation || defaultValue;
         let result = formattableTranslation || (orEmpty ? '' : key);
@@ -665,7 +659,10 @@ const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAv
             });
         }
         return result;
-    };
+    }
+    function hasDevBackend() {
+        return Boolean(getDevBackend());
+    }
     const wrap = (params) => {
         var _a;
         if (instances.observer) {
@@ -673,42 +670,31 @@ const PluginService = (getLanguage, getInitialOptions, getObserverOptions, getAv
         }
         return params.translation;
     };
-    const unwrap = (text) => {
-        var _a;
-        if (instances.observer) {
-            return (_a = instances.observer) === null || _a === void 0 ? void 0 : _a.unwrap(text);
+    function prepare() {
+        prepared = true;
+        while (onPrepareQueue.length) {
+            const queue = onPrepareQueue;
+            onPrepareQueue = [];
+            queue.forEach((callback) => callback());
         }
-        return { text, keys: [] };
-    };
-    const retranslate = () => {
-        var _a;
-        (_a = instances.observer) === null || _a === void 0 ? void 0 : _a.retranslate();
-    };
+    }
     return Object.freeze({
-        setFinalFormatter,
-        addFormatter,
+        prepare,
+        addPlugin,
         formatTranslation,
-        setObserver,
-        hasObserver,
-        setUi,
-        hasUi,
-        addBackend,
-        setDevBackend,
         getDevBackend,
         getBackendRecord,
         getBackendDevRecord,
-        setLanguageDetector,
         getLanguageDetector,
-        setLanguageStorage,
-        getLanguageStorage,
         getInitialLanguage,
         setStoredLanguage,
         run,
         stop,
         retranslate,
         highlight,
-        wrap,
         unwrap,
+        wrap,
+        hasDevBackend,
     });
 };
 
@@ -730,7 +716,7 @@ const ValueObserver = (initialValue, valueGetter, handler) => {
     });
 };
 
-const defaultValues$1 = {
+const defaultObserverOptions = {
     tagAttributes: {
         textarea: ['placeholder'],
         input: ['value', 'placeholder'],
@@ -745,18 +731,23 @@ const defaultValues$1 = {
     inputSuffix: '%-%',
     passToParent: ['option', 'optgroup'],
 };
-const initObserverOptions = (options) => {
-    return Object.assign(Object.assign({}, defaultValues$1), options);
-};
 
 const defaultValues = {
     defaultNs: '',
+    observerOptions: defaultObserverOptions,
+    observerType: 'invisible',
+};
+const combineOptions = (...states) => {
+    let result = {};
+    states.forEach((state) => {
+        result = Object.assign(Object.assign(Object.assign({}, result), state), { observerOptions: Object.assign(Object.assign({}, result.observerOptions), state === null || state === void 0 ? void 0 : state.observerOptions) });
+    });
+    return result;
 };
 const initState = (options, previousState) => {
-    const initialOptions = Object.assign(Object.assign(Object.assign({}, defaultValues), previousState === null || previousState === void 0 ? void 0 : previousState.initialOptions), options);
+    const initialOptions = combineOptions(defaultValues, previousState === null || previousState === void 0 ? void 0 : previousState.initialOptions, options);
     // remove extra '/' from url end
-    const apiUrl = initialOptions.apiUrl;
-    initialOptions.apiUrl = apiUrl ? apiUrl.replace(/\/+$/, '') : apiUrl;
+    initialOptions.apiUrl = sanitizeUrl(initialOptions.apiUrl);
     return {
         initialOptions,
         activeNamespaces: (previousState === null || previousState === void 0 ? void 0 : previousState.activeNamespaces) || new Map(),
@@ -769,7 +760,6 @@ const initState = (options, previousState) => {
 
 const State = (onLanguageChange, onPendingLanguageChange, onRunningChange) => {
     let state = initState();
-    let observerOptions = initObserverOptions();
     let devCredentials = undefined;
     function init(options) {
         state = initState(options, state);
@@ -837,6 +827,7 @@ const State = (onLanguageChange, onPendingLanguageChange, onRunningChange) => {
     function getRequiredNamespaces() {
         return unique([
             ...(state.initialOptions.ns || [state.initialOptions.defaultNs]),
+            ...getFallbackArray(state.initialOptions.fallbackNs),
             ...state.activeNamespaces.keys(),
         ]);
     }
@@ -850,11 +841,11 @@ const State = (onLanguageChange, onPendingLanguageChange, onRunningChange) => {
             ...getFallbackFromStruct(language, state.initialOptions.fallbackLanguage),
         ]);
     }
-    function getFallbackNamespaces() {
-        const defaultNs = state.initialOptions.defaultNs;
-        const fallbackNs = state.initialOptions.fallbackNs;
-        const fallbackNamespaces = typeof defaultNs === 'string' ? [defaultNs] : [];
-        return unique([...fallbackNamespaces, ...getFallbackArray(fallbackNs)]);
+    function getFallbackNs() {
+        return getFallbackArray(state.initialOptions.fallbackNs);
+    }
+    function getDefaultNs(ns) {
+        return ns === undefined ? state.initialOptions.defaultNs : ns;
     }
     function getAvailableLanguages() {
         if (state.initialOptions.availableLanguages) {
@@ -874,13 +865,12 @@ const State = (onLanguageChange, onPendingLanguageChange, onRunningChange) => {
         };
     }
     function overrideCredentials(credentials) {
-        devCredentials = credentials;
-    }
-    function setObserverOptions(options) {
-        observerOptions = initObserverOptions(options);
-    }
-    function getObserverOptions() {
-        return observerOptions;
+        if (credentials) {
+            devCredentials = Object.assign(Object.assign({}, credentials), { apiUrl: sanitizeUrl(credentials.apiUrl) });
+        }
+        else {
+            devCredentials = undefined;
+        }
     }
     return Object.freeze({
         init,
@@ -897,12 +887,11 @@ const State = (onLanguageChange, onPendingLanguageChange, onRunningChange) => {
         removeActiveNs,
         getRequiredNamespaces,
         getFallbackLangs,
-        getFallbackNamespaces,
+        getFallbackNs,
+        getDefaultNs,
         getAvailableLanguages,
         withDefaultNs,
         overrideCredentials,
-        setObserverOptions,
-        getObserverOptions,
     });
 };
 
@@ -939,11 +928,10 @@ function parseCombinedOptions(_a) {
         ns: ns,
         noWrap: noWrap,
         orEmpty: orEmpty,
-        params: Object.assign(Object.assign({}, rest), params),
     };
-    return options;
+    return Object.assign(Object.assign({}, options), { params: Object.assign({}, rest) });
 }
-const getTranslateParams = (keyOrProps, ...params) => {
+const getTranslateProps = (keyOrProps, ...params) => {
     let result = {};
     let options;
     if (typeof keyOrProps === 'object') {
@@ -966,20 +954,39 @@ const getTranslateParams = (keyOrProps, ...params) => {
 };
 
 const Controller = ({ options }) => {
-    const events = Events(getFallbackNamespaces);
+    const events = Events(getFallbackNs, getDefaultNs);
     const fetchingObserver = ValueObserver(false, () => cache.isFetching(), events.onFetchingChange.emit);
     const loadingObserver = ValueObserver(false, () => isLoading(), events.onLoadingChange.emit);
     const state = State(events.onLanguageChange, events.onPendingLanguageChange, events.onRunningChange);
-    const pluginService = PluginService(state.getLanguage, state.getInitialOptions, state.getObserverOptions, state.getAvailableLanguages, getTranslationNs, getTranslation, changeTranslation);
+    const pluginService = Plugins(state.getLanguage, state.getInitialOptions, state.getAvailableLanguages, getTranslationNs, getTranslation, changeTranslation);
     const cache = Cache(events.onCacheChange, pluginService.getBackendRecord, pluginService.getBackendDevRecord, state.withDefaultNs, state.isInitialLoading, fetchingObserver, loadingObserver);
     if (options) {
         init(options);
     }
-    events.onKeyUpdate.listen(() => {
+    events.onUpdate.listen(() => {
         if (state.isRunning()) {
             pluginService.retranslate();
         }
     });
+    function getFallbackNs() {
+        return state.getFallbackNs();
+    }
+    function getDefaultNs(ns) {
+        return state.getDefaultNs(ns);
+    }
+    // gets all namespaces where translation could be located
+    // takes (ns|default, fallback ns)
+    function getDefaultAndFallbackNs(ns) {
+        return [...getFallbackArray(getDefaultNs(ns)), ...getFallbackNs()];
+    }
+    // gets all namespaces which need to be loaded
+    // takes (ns|default, initial ns, fallback ns, active ns)
+    function getRequiredNamespaces(ns) {
+        return [
+            ...getFallbackArray(ns || getDefaultNs()),
+            ...state.getRequiredNamespaces(),
+        ];
+    }
     function changeTranslation(descriptor, key, value) {
         const keyObject = state.withDefaultNs(descriptor);
         const previousValue = cache.getTranslation(keyObject, key);
@@ -990,9 +997,6 @@ const Controller = ({ options }) => {
             },
         };
     }
-    function getFallbackNamespaces() {
-        return state.getFallbackNamespaces();
-    }
     function init(options) {
         state.init(options);
         cache.addStaticData(state.getInitialOptions().staticData);
@@ -1001,9 +1005,7 @@ const Controller = ({ options }) => {
         return cache.isLoading(state.getLanguage(), ns);
     }
     function isDev() {
-        return Boolean(state.getInitialOptions().apiKey &&
-            state.getInitialOptions().apiUrl &&
-            pluginService.getDevBackend());
+        return Boolean(state.getInitialOptions().apiKey && state.getInitialOptions().apiUrl);
     }
     async function addActiveNs(ns, forget) {
         if (!forget) {
@@ -1015,7 +1017,7 @@ const Controller = ({ options }) => {
     }
     function getRequiredRecords(lang, ns) {
         const languages = state.getFallbackLangs(lang);
-        const namespaces = ns !== undefined ? getFallbackArray(ns) : state.getRequiredNamespaces();
+        const namespaces = getRequiredNamespaces(ns);
         const result = [];
         languages.forEach((language) => {
             namespaces.forEach((namespace) => {
@@ -1032,7 +1034,7 @@ const Controller = ({ options }) => {
             return false;
         }
         const languages = state.getFallbackLangs(language);
-        const namespaces = ns !== undefined ? getFallbackArray(ns) : state.getRequiredNamespaces();
+        const namespaces = getRequiredNamespaces(ns);
         const result = [];
         languages.forEach((language) => {
             namespaces.forEach((namespace) => {
@@ -1065,13 +1067,13 @@ const Controller = ({ options }) => {
             pluginService.setStoredLanguage(language);
         }
     }
-    function getTranslationNs({ key, ns, }) {
-        const namespaces = ns !== undefined ? getFallbackArray(ns) : state.getFallbackNamespaces();
+    function getTranslationNs({ key, ns }) {
         const languages = state.getFallbackLangs();
+        const namespaces = getDefaultAndFallbackNs(ns);
         return cache.getTranslationNs(namespaces, languages, key);
     }
-    function getTranslation({ key, ns, }) {
-        const namespaces = ns !== undefined ? getFallbackArray(ns) : state.getFallbackNamespaces();
+    function getTranslation({ key, ns }) {
+        const namespaces = getDefaultAndFallbackNs(ns);
         const languages = state.getFallbackLangs();
         return cache.getTranslationFallback(namespaces, languages, key);
     }
@@ -1154,7 +1156,7 @@ const Controller = ({ options }) => {
     }
     const t = (...args) => {
         // @ts-ignore
-        const params = getTranslateParams(...args);
+        const params = getTranslateProps(...args);
         const translation = getTranslation(params);
         return pluginService.formatTranslation(Object.assign(Object.assign({}, params), { translation }));
     };
@@ -1163,7 +1165,6 @@ const Controller = ({ options }) => {
         getTranslation,
         changeTranslation,
         addActiveNs,
-        loadRequiredRecords,
         loadRecords,
         loadRecord,
         isLoading,
@@ -1174,23 +1175,11 @@ const Controller = ({ options }) => {
         stop }));
 };
 
-const Tolgee = (options) => {
+const createTolgee = (options) => {
     const controller = Controller({
         options,
     });
-    const pluginTools = Object.freeze({
-        setFinalFormatter: controller.setFinalFormatter,
-        addFormatter: controller.addFormatter,
-        setObserver: controller.setObserver,
-        hasObserver: controller.hasObserver,
-        setUi: controller.setUi,
-        hasUi: controller.hasUi,
-        setDevBackend: controller.setDevBackend,
-        addBackend: controller.addBackend,
-        setLanguageDetector: controller.setLanguageDetector,
-        setLanguageStorage: controller.setLanguageStorage,
-        overrideCredentials: controller.overrideCredentials,
-    });
+    // restarts tolgee while applying callback
     const withRestart = (callback) => {
         const wasRunning = controller.isRunning();
         wasRunning && controller.stop();
@@ -1198,57 +1187,195 @@ const Tolgee = (options) => {
         wasRunning && controller.run();
     };
     const tolgee = Object.freeze({
-        // event listeners
+        /**
+         * Listen to tolgee events.
+         */
         on: controller.on,
-        onKeyUpdate: controller.onKeyUpdate.listenSome,
-        // state
+        /**
+         * Listen for specific namespaces changes.
+         *
+         * ```
+         * const sub = tolgee.onUpdate(handler)
+         *
+         * // subscribe to selected namespace
+         * sub.subscribeNs(['common'])
+         *
+         * // unsubscribe
+         * sub.unsubscribe()
+         * ```
+         */
+        onNsUpdate: controller.onUpdate.listenSome,
+        /**
+         * @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,
-        // plugins
-        setObserverOptions: (options) => {
-            controller.setObserverOptions(options);
-            return tolgee;
+        /**
+         * Override creadentials passed on initialization
+         */
+        overrideCredentials(credentials) {
+            withRestart(() => controller.overrideCredentials(credentials));
         },
-        use: (plugin) => {
+        /**
+         * Add tolgee plugin.
+         */
+        addPlugin(plugin) {
             if (plugin) {
-                withRestart(() => plugin(tolgee, pluginTools));
+                withRestart(() => controller.addPlugin(tolgee, plugin));
             }
-            return tolgee;
         },
-        init: (options) => {
-            withRestart(() => controller.init(options));
-            return tolgee;
+        /**
+         * 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) {
+            if (options) {
+                withRestart(() => controller.init(options));
+            }
         },
     });
     return tolgee;
 };
-
-const RESTRICTED_ASCENDANT_ATTRIBUTE = 'data-tolgee-restricted';
-const TOLGEE_ATTRIBUTE_NAME = '_tolgee';
-const TOLGEE_HIGHLIGHTER_CLASS = '_tolgee-highlighter';
-const TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE = 'data-tolgee-key-only';
+/**
+ * Tolgee chainable constructor.
+ *
+ * Usage:
+ * ```
+ * const tolgee = Tolgee().use(...).init(...)
+ * ```
+ */
+const Tolgee = () => {
+    const state = {
+        plugins: [],
+        options: {},
+    };
+    const tolgeeChain = Object.freeze({
+        use(plugin) {
+            state.plugins.push(plugin);
+            return tolgeeChain;
+        },
+        updateDefaults(options) {
+            state.options = combineOptions(state.options, options);
+            return tolgeeChain;
+        },
+        init(options) {
+            const tolgee = createTolgee(combineOptions(state.options, options));
+            state.plugins.forEach(tolgee.addPlugin);
+            return tolgee;
+        },
+    });
+    return tolgeeChain;
+};
 
 const ERROR_PARAM_EMPTY = 0, ERROR_UNEXPECTED_CHAR = 1, ERROR_UNEXPECTED_END = 2;
 class FormatError extends Error {
@@ -1394,23 +1521,19 @@ function formatter(translation, params) {
     return result.join('');
 }
 
-function FormatSimpleCreator() {
+function createFormatSimple() {
     return {
         format: ({ translation, params }) => formatter(translation, params),
     };
 }
 const FormatSimple = () => (tolgee, tools) => {
-    tools.setFinalFormatter(FormatSimpleCreator());
+    tools.setFinalFormatter(createFormatSimple());
     return tolgee;
 };
 
 exports.FormatSimple = FormatSimple;
-exports.RESTRICTED_ASCENDANT_ATTRIBUTE = RESTRICTED_ASCENDANT_ATTRIBUTE;
-exports.TOLGEE_ATTRIBUTE_NAME = TOLGEE_ATTRIBUTE_NAME;
-exports.TOLGEE_HIGHLIGHTER_CLASS = TOLGEE_HIGHLIGHTER_CLASS;
-exports.TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE = TOLGEE_WRAPPED_ONLY_DATA_ATTRIBUTE;
 exports.Tolgee = Tolgee;
 exports.getFallback = getFallback;
 exports.getFallbackArray = getFallbackArray;
-exports.getTranslateParams = getTranslateParams;
+exports.getTranslateProps = getTranslateProps;
 //# sourceMappingURL=tolgee.cjs.js.map