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

package/dist/tolgee.cjs.js

@@ -90,9 +90,9 @@ const createFetchFunction = (fetchFn = defaultFetchFunction) => {
     };
 };
 
-function EventEmitter(isActive) {
+const EventEmitter = (type, isActive) => {
     let handlers = [];
-    return Object.freeze({
+    return {
         listen(handler) {
             const handlerWrapper = (e) => {
                 handler(e);
@@ -106,27 +106,14 @@ function EventEmitter(isActive) {
         },
         emit(data) {
             if (isActive()) {
-                handlers.forEach((handler) => handler({ value: data }));
+                handlers.forEach((handler) => handler({ type: type, value: data }));
             }
         },
-    });
-}
+    };
+};
 
-function EventEmitterSelective(isActive, getFallbackNs, getDefaultNs) {
-    const listeners = new Set();
-    const partialListeners = new Set();
-    function 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 nsMatches = ns === undefined ||
-                (ns === null || ns === void 0 ? void 0 : ns.findIndex((ns) => fallbackNamespaces.has(ns) || handler.namespaces.has(ns))) !== -1;
-            if (nsMatches) {
-                handler.fn({ value: undefined });
-            }
-        });
-    }
+function EventEmitterCombined(isActive) {
+    let handlers = [];
     let queue = [];
     // merge events in queue into one event
     function solveQueue() {
@@ -135,87 +122,54 @@ function EventEmitterSelective(isActive, getFallbackNs, getDefaultNs) {
         }
         const queueCopy = queue;
         queue = [];
-        listeners.forEach((handler) => {
-            handler({ value: undefined });
+        handlers.forEach((handler) => {
+            handler(queueCopy);
         });
-        let namespaces = new Set();
-        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, delayed) {
-            if (isActive()) {
-                queue.push(ns);
-                if (!delayed) {
-                    solveQueue();
-                }
-                else {
-                    setTimeout(solveQueue, 0);
-                }
-            }
-        },
         listen(handler) {
-            listeners.add(handler);
-            const result = {
-                unsubscribe: () => {
-                    listeners.delete(handler);
-                },
+            const handlerWrapper = (events) => {
+                handler(events);
             };
-            return result;
-        },
-        listenSome(handler) {
-            const handlerWrapper = {
-                fn: (e) => {
-                    handler(e);
+            handlers.push(handlerWrapper);
+            return {
+                unsubscribe() {
+                    handlers = handlers.filter((i) => handlerWrapper !== i);
                 },
-                namespaces: new Set(),
             };
-            partialListeners.add(handlerWrapper);
-            const result = {
-                unsubscribe: () => {
-                    partialListeners.delete(handlerWrapper);
-                },
-                subscribeNs: (ns) => {
-                    getFallbackArray(ns).forEach((val) => handlerWrapper.namespaces.add(val));
-                    if (ns === undefined) {
-                        // subscribing to default ns
-                        handlerWrapper.namespaces.add(getDefaultNs());
+        },
+        emit(e, delayed) {
+            if (isActive()) {
+                if (isActive()) {
+                    queue.push(e);
+                    if (!delayed) {
+                        solveQueue();
                     }
-                    return result;
-                },
-            };
-            return result;
+                    else {
+                        setTimeout(solveQueue, 0);
+                    }
+                }
+            }
         },
     });
 }
 
-function Events(getFallbackNs, getDefaultNs) {
+function Events() {
     let emitterActive = true;
     function isActive() {
         return emitterActive;
     }
     const self = Object.freeze({
-        onPendingLanguageChange: EventEmitter(isActive),
-        onLanguageChange: EventEmitter(isActive),
-        onLoadingChange: EventEmitter(isActive),
-        onFetchingChange: EventEmitter(isActive),
-        onInitialLoaded: EventEmitter(isActive),
-        onRunningChange: EventEmitter(isActive),
-        onCacheChange: EventEmitter(isActive),
-        onUpdate: EventEmitterSelective(isActive, getFallbackNs, getDefaultNs),
-        onPermanentChange: EventEmitter(isActive),
-        onError: EventEmitter(isActive),
+        onPendingLanguageChange: EventEmitter('pendingLanguage', isActive),
+        onLanguageChange: EventEmitter('language', isActive),
+        onLoadingChange: EventEmitter('loading', isActive),
+        onFetchingChange: EventEmitter('fetching', isActive),
+        onInitialLoaded: EventEmitter('initialLoad', isActive),
+        onRunningChange: EventEmitter('running', isActive),
+        onCacheChange: EventEmitter('cache', isActive),
+        onPermanentChange: EventEmitter('permanentChange', isActive),
+        onError: EventEmitter('error', isActive),
+        onUpdate: EventEmitterCombined(isActive),
         setEmitterActive(active) {
             emitterActive = active;
         },
@@ -244,9 +198,9 @@ function Events(getFallbackNs, getDefaultNs) {
             }
         }),
     });
-    self.onInitialLoaded.listen(() => self.onUpdate.emit());
-    self.onLanguageChange.listen(() => self.onUpdate.emit());
-    self.onCacheChange.listen(({ value }) => self.onUpdate.emit([value.namespace], true));
+    self.onInitialLoaded.listen((e) => self.onUpdate.emit(e, false));
+    self.onLanguageChange.listen((e) => self.onUpdate.emit(e, false));
+    self.onCacheChange.listen((e) => self.onUpdate.emit(e, true));
     return self;
 }
 
@@ -276,7 +230,7 @@ class LanguageStorageError extends Error {
     }
 }
 
-const flattenTranslations = (data) => {
+const flattenTranslationsToMap = (data) => {
     const result = new Map();
     Object.entries(data).forEach(([key, value]) => {
         // ignore empty values
@@ -284,7 +238,7 @@ const flattenTranslations = (data) => {
             return;
         }
         if (typeof value === 'object') {
-            flattenTranslations(value).forEach((flatValue, flatKey) => {
+            flattenTranslationsToMap(value).forEach((flatValue, flatKey) => {
                 result.set(key + '.' + flatKey, flatValue);
             });
             return;
@@ -293,6 +247,9 @@ const flattenTranslations = (data) => {
     });
     return result;
 };
+const flattenTranslations = (data) => {
+    return Object.fromEntries(flattenTranslationsToMap(data).entries());
+};
 const decodeCacheKey = (key) => {
     const [firstPart, ...rest] = key.split(':');
     // if namespaces contains ":" it won't get lost
@@ -308,7 +265,7 @@ const encodeCacheKey = ({ language, namespace, }) => {
     }
 };
 
-function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isInitialLoading, fetchingObserver, loadingObserver) {
+function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isInitialLoading, isCacheDisabled, fetchingObserver, loadingObserver) {
     const asyncRequests = new Map();
     const cache = new Map();
     let staticData = {};
@@ -319,7 +276,7 @@ function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isI
             data: flattenTranslations(data),
             version: recordVersion,
         });
-        events.onCacheChange.emit(descriptor);
+        events.onCacheChange.emit(decodeCacheKey(cacheKey));
     }
     /**
      * Fetches production data
@@ -372,14 +329,23 @@ function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isI
     }
     const self = Object.freeze({
         addStaticData(data) {
-            if (data) {
+            if (Array.isArray(data)) {
+                for (const record of data) {
+                    const key = encodeCacheKey(record);
+                    const existing = cache.get(key);
+                    if (!existing || existing.version === 0) {
+                        addRecordInternal(record, flattenTranslations(record.data), 0);
+                    }
+                }
+            }
+            else if (data) {
                 staticData = Object.assign(Object.assign({}, staticData), data);
                 Object.entries(data).forEach(([key, value]) => {
                     if (typeof value !== 'function') {
                         const descriptor = decodeCacheKey(key);
                         const existing = cache.get(key);
                         if (!existing || existing.version === 0) {
-                            addRecordInternal(descriptor, value, 0);
+                            addRecordInternal(descriptor, flattenTranslations(value), 0);
                         }
                     }
                 });
@@ -390,7 +356,7 @@ function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isI
             version += 1;
         },
         addRecord(descriptor, data) {
-            addRecordInternal(descriptor, data, version);
+            addRecordInternal(descriptor, flattenTranslations(data), version);
         },
         exists(descriptor, strict = false) {
             const record = cache.get(encodeCacheKey(descriptor));
@@ -400,19 +366,27 @@ function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isI
             return Boolean(record);
         },
         getRecord(descriptor) {
-            var _a;
-            return (_a = cache.get(encodeCacheKey(withDefaultNs(descriptor)))) === null || _a === void 0 ? void 0 : _a.data;
+            const descriptorWithNs = withDefaultNs(descriptor);
+            const cacheKey = encodeCacheKey(descriptorWithNs);
+            const cacheRecord = cache.get(cacheKey);
+            if (!cacheRecord) {
+                return undefined;
+            }
+            return Object.assign(Object.assign({}, descriptorWithNs), { cacheKey, data: cacheRecord.data });
+        },
+        getAllRecords() {
+            const entries = Array.from(cache.entries());
+            return entries.map(([key]) => self.getRecord(decodeCacheKey(key)));
         },
         getTranslation(descriptor, key) {
             var _a;
-            return (_a = cache.get(encodeCacheKey(descriptor))) === null || _a === void 0 ? void 0 : _a.data.get(key);
+            return (_a = cache.get(encodeCacheKey(descriptor))) === null || _a === void 0 ? void 0 : _a.data[key];
         },
         getTranslationNs(namespaces, languages, key) {
             var _a;
             for (const namespace of namespaces) {
                 for (const language of languages) {
-                    const value = (_a = cache
-                        .get(encodeCacheKey({ language, namespace }))) === null || _a === void 0 ? void 0 : _a.data.get(key);
+                    const value = (_a = cache.get(encodeCacheKey({ language, namespace }))) === null || _a === void 0 ? void 0 : _a.data[key];
                     if (value !== undefined && value !== null) {
                         return [namespace];
                     }
@@ -424,8 +398,7 @@ function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isI
             var _a;
             for (const namespace of namespaces) {
                 for (const language of languages) {
-                    const value = (_a = cache
-                        .get(encodeCacheKey({ language, namespace }))) === null || _a === void 0 ? void 0 : _a.data.get(key);
+                    const value = (_a = cache.get(encodeCacheKey({ language, namespace }))) === null || _a === void 0 ? void 0 : _a.data[key];
                     if (value !== undefined && value !== null) {
                         return value;
                     }
@@ -436,8 +409,10 @@ function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isI
         changeTranslation(descriptor, key, value) {
             var _a;
             const record = (_a = cache.get(encodeCacheKey(descriptor))) === null || _a === void 0 ? void 0 : _a.data;
-            record === null || record === void 0 ? void 0 : record.set(key, value);
-            events.onCacheChange.emit(Object.assign(Object.assign({}, descriptor), { key }));
+            if (record === null || record === void 0 ? void 0 : record[key]) {
+                record[key] = value;
+                events.onCacheChange.emit(Object.assign(Object.assign({}, descriptor), { key }));
+            }
         },
         isFetching(ns) {
             if (isInitialLoading()) {
@@ -451,66 +426,74 @@ function Cache(events, backendGetRecord, backendGetDevRecord, withDefaultNs, isI
         },
         isLoading(language, ns) {
             const namespaces = getFallbackArray(ns);
-            return Boolean(isInitialLoading() ||
-                Array.from(asyncRequests.keys()).find((key) => {
-                    const descriptor = decodeCacheKey(key);
-                    return ((!namespaces.length ||
-                        namespaces.includes(descriptor.namespace)) &&
-                        !self.exists({
-                            namespace: descriptor.namespace,
-                            language: language,
-                        }));
-                }));
-        },
-        async loadRecords(descriptors, isDev) {
+            if (isInitialLoading()) {
+                return true;
+            }
+            const pendingCacheKeys = Array.from(asyncRequests.keys());
+            return Boolean(pendingCacheKeys.find((key) => {
+                const descriptor = decodeCacheKey(key);
+                return ((!namespaces.length || namespaces.includes(descriptor.namespace)) &&
+                    !self.exists({
+                        namespace: descriptor.namespace,
+                        language: language,
+                    }));
+            }));
+        },
+        async loadRecords(descriptors, options) {
             const withPromises = descriptors.map((descriptor) => {
                 const keyObject = withDefaultNs(descriptor);
                 const cacheKey = encodeCacheKey(keyObject);
+                if (options === null || options === void 0 ? void 0 : options.useCache) {
+                    const exists = self.exists(keyObject, true);
+                    if (exists) {
+                        return Object.assign(Object.assign({}, keyObject), { new: false, cacheKey, data: self.getRecord(keyObject).data });
+                    }
+                }
                 const existingPromise = asyncRequests.get(cacheKey);
                 if (existingPromise) {
-                    return {
-                        new: false,
-                        promise: existingPromise,
-                        keyObject,
-                        cacheKey,
-                    };
+                    return Object.assign(Object.assign({}, keyObject), { new: false, promise: existingPromise, cacheKey });
                 }
-                const dataPromise = fetchData(keyObject, isDev) || Promise.resolve(undefined);
+                const dataPromise = fetchData(keyObject, !(options === null || options === void 0 ? void 0 : options.noDev)) || Promise.resolve(undefined);
                 asyncRequests.set(cacheKey, dataPromise);
-                return {
-                    new: true,
-                    promise: dataPromise,
-                    keyObject,
-                    cacheKey,
-                };
+                return Object.assign(Object.assign({}, keyObject), { new: true, promise: dataPromise, cacheKey });
             });
             fetchingObserver.notify();
             loadingObserver.notify();
-            const results = await Promise.all(withPromises.map((val) => val.promise));
-            withPromises.forEach((value, i) => {
-                const promiseChanged = asyncRequests.get(value.cacheKey) !== value.promise;
+            const promisesToWait = withPromises
+                .map((val) => val.promise)
+                .filter(Boolean);
+            const fetchedData = await Promise.all(promisesToWait);
+            withPromises.forEach((value) => {
+                var _a;
+                if (value.promise) {
+                    value.data = flattenTranslations((_a = fetchedData[0]) !== null && _a !== void 0 ? _a : {});
+                    fetchedData.shift();
+                }
                 // if promise has changed in between, it means cache been invalidated or
                 // new data are being fetched
+                const promiseChanged = asyncRequests.get(value.cacheKey) !== value.promise;
                 if (value.new && !promiseChanged) {
                     asyncRequests.delete(value.cacheKey);
-                    const data = results[i];
-                    if (data) {
-                        self.addRecord(value.keyObject, data);
+                    if (value.data) {
+                        self.addRecord(value, value.data);
                     }
-                    else if (!self.getRecord(value.keyObject)) {
+                    else if (!self.getRecord(value)) {
                         // if no data exist, put empty object
-                        self.addRecord(value.keyObject, {});
+                        // so we know we don't have to fetch again
+                        self.addRecord(value, {});
                     }
                 }
             });
             fetchingObserver.notify();
             loadingObserver.notify();
-            return withPromises.map((val) => self.getRecord(val.keyObject));
-        },
-        getAllRecords() {
-            const entries = Array.from(cache.entries());
-            return entries.map(([key, entry]) => {
-                return Object.assign(Object.assign({}, decodeCacheKey(key)), { data: entry.data });
+            return withPromises.map((val) => {
+                var _a;
+                return ({
+                    language: val.language,
+                    namespace: val.namespace,
+                    data: (_a = val.data) !== null && _a !== void 0 ? _a : {},
+                    cacheKey: val.cacheKey,
+                });
             });
         },
     });
@@ -565,13 +548,14 @@ const DEFAULT_FORMAT_ERROR = 'invalid';
 const DEFAULT_API_URL = 'https://app.tolgee.io';
 const DEFAULT_MISSING_TRANSLATION = ({ key, }) => key;
 const defaultValues = {
-    defaultNs: '',
     observerOptions: defaultObserverOptions,
     observerType: 'invisible',
     onFormatError: DEFAULT_FORMAT_ERROR,
     apiUrl: DEFAULT_API_URL,
+    autoLoadRequiredData: true,
     fetch: createFetchFunction(),
     onTranslationMissing: DEFAULT_MISSING_TRANSLATION,
+    disableCache: false,
 };
 const combineOptions = (...states) => {
     let result = {};
@@ -765,6 +749,9 @@ function Plugins(getLanguage, getInitialOptions, getAvailableLanguages, getFallb
         getBackendDevRecord: (async ({ language, namespace }) => {
             var _a;
             const { apiKey, apiUrl, projectId, filterTag } = getInitialOptions();
+            if (!apiKey || !apiUrl || !self.hasDevBackend()) {
+                return undefined;
+            }
             return (_a = instances.devBackend) === null || _a === void 0 ? void 0 : _a.getRecord(Object.assign({ apiKey,
                 apiUrl,
                 projectId,
@@ -908,6 +895,9 @@ function State(onLanguageChange, onPendingLanguageChange, onRunningChange) {
         isInitialLoading() {
             return state.isInitialLoading;
         },
+        isCacheDisabled() {
+            return state.initialOptions.disableCache;
+        },
         setInitialLoading(value) {
             state.isInitialLoading = value;
         },
@@ -958,7 +948,8 @@ function State(onLanguageChange, onPendingLanguageChange, onRunningChange) {
         },
         getRequiredNamespaces() {
             return unique([
-                ...(state.initialOptions.ns || [state.initialOptions.defaultNs]),
+                self.getDefaultNs(),
+                ...(state.initialOptions.ns || []),
                 ...getFallbackArray(state.initialOptions.fallbackNs),
                 ...state.activeNamespaces.keys(),
             ]);
@@ -976,8 +967,17 @@ function State(onLanguageChange, onPendingLanguageChange, onRunningChange) {
         getFallbackNs() {
             return getFallbackArray(state.initialOptions.fallbackNs);
         },
+        getNs() {
+            var _a, _b;
+            return ((_a = state.initialOptions.ns) === null || _a === void 0 ? void 0 : _a.length)
+                ? state.initialOptions.ns
+                : [(_b = state.initialOptions.defaultNs) !== null && _b !== void 0 ? _b : ''];
+        },
         getDefaultNs(ns) {
-            return ns === undefined ? state.initialOptions.defaultNs : ns;
+            var _a, _b, _c;
+            return ns === undefined
+                ? (_c = (_a = state.initialOptions.defaultNs) !== null && _a !== void 0 ? _a : (_b = state.initialOptions.ns) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : ''
+                : ns;
         },
         getAvailableLanguages() {
             if (state.initialOptions.availableLanguages) {
@@ -988,10 +988,13 @@ function State(onLanguageChange, onPendingLanguageChange, onRunningChange) {
                 return Array.from(new Set(languagesFromStaticData));
             }
         },
+        getAvailableNs() {
+            return state.initialOptions.availableNs;
+        },
         withDefaultNs(descriptor) {
             return {
                 namespace: descriptor.namespace === undefined
-                    ? self.getInitialOptions().defaultNs
+                    ? self.getDefaultNs()
                     : descriptor.namespace,
                 language: descriptor.language,
             };
@@ -1041,12 +1044,12 @@ const getTranslateProps = (keyOrProps, ...params) => {
 };
 
 function Controller({ options }) {
-    const events = Events(getFallbackNs, getDefaultNs);
+    const events = Events();
     const fetchingObserver = ValueObserver(false, () => cache.isFetching(), events.onFetchingChange.emit);
     const loadingObserver = ValueObserver(false, () => self.isLoading(), events.onLoadingChange.emit);
     const state = State(events.onLanguageChange, events.onPendingLanguageChange, events.onRunningChange);
     const pluginService = Plugins(state.getLanguage, state.getInitialOptions, state.getAvailableLanguages, getDefaultAndFallbackNs, getTranslationNs, getTranslation, changeTranslation, events);
-    const cache = Cache(events, pluginService.getBackendRecord, pluginService.getBackendDevRecord, state.withDefaultNs, state.isInitialLoading, fetchingObserver, loadingObserver);
+    const cache = Cache(events, pluginService.getBackendRecord, pluginService.getBackendDevRecord, state.withDefaultNs, state.isInitialLoading, state.isCacheDisabled, fetchingObserver, loadingObserver);
     if (options) {
         init(options);
     }
@@ -1065,15 +1068,15 @@ function Controller({ options }) {
     // gets all namespaces where translation could be located
     // takes (ns|default, fallback ns)
     function getDefaultAndFallbackNs(ns) {
-        return [...getFallbackArray(getDefaultNs(ns)), ...getFallbackNs()];
+        return unique([...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 [
+        return unique([
             ...getFallbackArray(ns !== null && ns !== void 0 ? ns : getDefaultNs()),
             ...state.getRequiredNamespaces(),
-        ];
+        ]);
     }
     function changeTranslation(descriptor, key, value) {
         const keyObject = state.withDefaultNs(descriptor);
@@ -1089,24 +1092,50 @@ function Controller({ options }) {
         state.init(options);
         cache.addStaticData(state.getInitialOptions().staticData);
     }
-    function getRequiredRecords(lang, ns) {
+    function getRequiredDescriptors(lang, ns) {
         const languages = state.getFallbackLangs(lang);
         const namespaces = getRequiredNamespaces(ns);
         const result = [];
         languages.forEach((language) => {
             namespaces.forEach((namespace) => {
-                if (!cache.exists({ language, namespace }, true)) {
-                    result.push({ language, namespace });
-                }
+                result.push({ language, namespace });
             });
         });
         return result;
     }
-    function loadRequiredRecords(lang, ns) {
-        const descriptors = getRequiredRecords(lang, ns);
-        if (descriptors.length) {
-            return valueOrPromise(self.loadRecords(descriptors), () => { });
+    function getMissingDescriptors(lang, ns) {
+        return getRequiredDescriptors(lang, ns).filter((descriptor) => !cache.exists(descriptor, true));
+    }
+    function getMatrixRecords(options) {
+        let languages = [];
+        let namespaces = [];
+        if (Array.isArray(options.languages)) {
+            languages = options.languages;
+        }
+        else if (options.languages === 'all') {
+            const availableLanguages = self.getAvailableLanguages();
+            if (!availableLanguages) {
+                throw new Error(missingOptionError('availableLanguages'));
+            }
+            languages = availableLanguages;
+        }
+        if (Array.isArray(options.namespaces)) {
+            namespaces = options.namespaces;
+        }
+        else if (options.namespaces === 'all') {
+            const availableNs = self.getAvailableNs();
+            if (!availableNs) {
+                throw new Error(missingOptionError('availableNs'));
+            }
+            namespaces = availableNs;
         }
+        const records = [];
+        languages.forEach((language) => {
+            namespaces.forEach((namespace) => {
+                records.push({ language, namespace });
+            });
+        });
+        return records;
     }
     function getTranslationNs({ key, ns }) {
         const languages = state.getFallbackLangs();
@@ -1120,8 +1149,11 @@ function Controller({ options }) {
     }
     function loadInitial() {
         const data = valueOrPromise(initializeLanguage(), () => {
-            // fail if there is no language
-            return loadRequiredRecords();
+            const missingDescriptors = getMissingDescriptors();
+            if (missingDescriptors.length &&
+                state.getInitialOptions().autoLoadRequiredData) {
+                return cache.loadRecords(missingDescriptors, { useCache: true });
+            }
         });
         if (isPromise(data)) {
             state.setInitialLoading(true);
@@ -1162,14 +1194,16 @@ function Controller({ options }) {
             throw new Error(missingOptionError(['defaultLanguage', 'language']));
         }
     }
-    const self = Object.freeze(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, events), state), pluginService), cache), { init: init, getTranslation: getTranslation, changeTranslation: changeTranslation, getTranslationNs: getTranslationNs, getDefaultAndFallbackNs: getDefaultAndFallbackNs, findPositions: pluginService.findPositions, getRequiredRecords: getRequiredRecords, async changeLanguage(language) {
+    const self = Object.freeze(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, events), state), pluginService), cache), { init: init, getTranslation: getTranslation, changeTranslation: changeTranslation, getTranslationNs: getTranslationNs, getDefaultAndFallbackNs: getDefaultAndFallbackNs, findPositions: pluginService.findPositions, getRequiredDescriptors: getRequiredDescriptors, async changeLanguage(language) {
             if (state.getPendingLanguage() === language &&
                 state.getLanguage() === language) {
                 return;
             }
             state.setPendingLanguage(language);
-            if (state.isRunning()) {
-                await loadRequiredRecords(language);
+            if (state.isRunning() && state.getInitialOptions().autoLoadRequiredData) {
+                await cache.loadRecords(getRequiredDescriptors(language), {
+                    useCache: true,
+                });
             }
             if (language === state.getPendingLanguage()) {
                 // there might be parallel language change
@@ -1183,14 +1217,14 @@ function Controller({ options }) {
                 state.addActiveNs(ns);
             }
             if (state.isRunning()) {
-                await loadRequiredRecords(undefined, ns);
+                await cache.loadRecords(getRequiredDescriptors(undefined, ns), {
+                    useCache: true,
+                });
             }
         },
-        loadRecords(descriptors) {
-            return cache.loadRecords(descriptors, self.isDev());
-        },
-        async loadRecord(descriptor) {
-            return (await self.loadRecords([descriptor]))[0];
+        async loadRecord(descriptor, options) {
+            var _a;
+            return (_a = (await self.loadRecords([descriptor], options))[0]) === null || _a === void 0 ? void 0 : _a.data;
         },
         isLoading(ns) {
             return cache.isLoading(state.getLanguage(), ns);
@@ -1219,6 +1253,17 @@ function Controller({ options }) {
         }), isDev() {
             return Boolean(state.getInitialOptions().apiKey && state.getInitialOptions().apiUrl);
         },
+        async loadRequired(options) {
+            if (!(options === null || options === void 0 ? void 0 : options.language)) {
+                await initializeLanguage();
+            }
+            const requiredRecords = getRequiredDescriptors(options === null || options === void 0 ? void 0 : options.language);
+            return self.loadRecords(requiredRecords, options);
+        },
+        async loadMatrix(options) {
+            const records = getMatrixRecords(options);
+            return self.loadRecords(records, options);
+        },
         run() {
             checkCorrectConfiguration();
             if (!state.isRunning()) {
@@ -1259,20 +1304,6 @@ function createTolgee(options) {
          * 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.
          */
@@ -1310,6 +1341,16 @@ function createTolgee(options) {
          * so this method will remove namespace only if the counter goes down to 0.
          */
         removeActiveNs: controller.removeActiveNs,
+        /**
+         * Load records which would be loaded by `run` function
+         *
+         * You can provide language if not previously set on tolgee instance
+         */
+        loadRequired: controller.loadRequired,
+        /**
+         * Load records in matrix (languages x namespaces)
+         */
+        loadMatrix: controller.loadMatrix,
         /**
          * Manually load multiple records from `Backend` (or `DevBackend` when in dev mode)
          *
@@ -1338,9 +1379,9 @@ function createTolgee(options) {
          */
         isLoaded: controller.isLoaded,
         /**
-         * Returns records needed for instance to be `loaded`
+         * Returns descriptors of records needed for instance to be `loaded`
          */
-        getRequiredRecords: controller.getRequiredRecords,
+        getRequiredDescriptors: controller.getRequiredDescriptors,
         /**
          * @return `true` if tolgee is loading initial data (triggered by `run`).
          */