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

package/dist/tolgee.umd.js

@@ -92,9 +92,9 @@
         };
     };
 
-    function EventEmitter(isActive) {
+    const EventEmitter = (type, isActive) => {
         let handlers = [];
-        return Object.freeze({
+        return {
             listen(handler) {
                 const handlerWrapper = (e) => {
                     handler(e);
@@ -108,27 +108,14 @@
             },
             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() {
@@ -137,87 +124,54 @@
             }
             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;
             },
@@ -246,9 +200,9 @@
                 }
             }),
         });
-        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;
     }
 
@@ -278,7 +232,7 @@
         }
     }
 
-    const flattenTranslations = (data) => {
+    const flattenTranslationsToMap = (data) => {
         const result = new Map();
         Object.entries(data).forEach(([key, value]) => {
             // ignore empty values
@@ -286,7 +240,7 @@
                 return;
             }
             if (typeof value === 'object') {
-                flattenTranslations(value).forEach((flatValue, flatKey) => {
+                flattenTranslationsToMap(value).forEach((flatValue, flatKey) => {
                     result.set(key + '.' + flatKey, flatValue);
                 });
                 return;
@@ -295,6 +249,9 @@
         });
         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
@@ -310,7 +267,7 @@
         }
     };
 
-    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 = {};
@@ -321,7 +278,7 @@
                 data: flattenTranslations(data),
                 version: recordVersion,
             });
-            events.onCacheChange.emit(descriptor);
+            events.onCacheChange.emit(decodeCacheKey(cacheKey));
         }
         /**
          * Fetches production data
@@ -374,14 +331,23 @@
         }
         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);
                             }
                         }
                     });
@@ -392,7 +358,7 @@
                 version += 1;
             },
             addRecord(descriptor, data) {
-                addRecordInternal(descriptor, data, version);
+                addRecordInternal(descriptor, flattenTranslations(data), version);
             },
             exists(descriptor, strict = false) {
                 const record = cache.get(encodeCacheKey(descriptor));
@@ -402,19 +368,27 @@
                 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];
                         }
@@ -426,8 +400,7 @@
                 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;
                         }
@@ -438,8 +411,10 @@
             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()) {
@@ -453,66 +428,74 @@
             },
             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,
+                    });
                 });
             },
         });
@@ -567,13 +550,14 @@
     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 = {};
@@ -767,6 +751,9 @@
             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,
@@ -910,6 +897,9 @@
             isInitialLoading() {
                 return state.isInitialLoading;
             },
+            isCacheDisabled() {
+                return state.initialOptions.disableCache;
+            },
             setInitialLoading(value) {
                 state.isInitialLoading = value;
             },
@@ -960,7 +950,8 @@
             },
             getRequiredNamespaces() {
                 return unique([
-                    ...(state.initialOptions.ns || [state.initialOptions.defaultNs]),
+                    self.getDefaultNs(),
+                    ...(state.initialOptions.ns || []),
                     ...getFallbackArray(state.initialOptions.fallbackNs),
                     ...state.activeNamespaces.keys(),
                 ]);
@@ -978,8 +969,17 @@
             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) {
@@ -990,10 +990,13 @@
                     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,
                 };
@@ -1043,12 +1046,12 @@
     };
 
     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);
         }
@@ -1067,15 +1070,15 @@
         // 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);
@@ -1091,24 +1094,50 @@
             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();
@@ -1122,8 +1151,11 @@
         }
         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);
@@ -1164,14 +1196,16 @@
                 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
@@ -1185,14 +1219,14 @@
                     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);
@@ -1221,6 +1255,17 @@
             }), 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()) {
@@ -1261,20 +1306,6 @@
              * 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.
              */
@@ -1312,6 +1343,16 @@
              * 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)
              *
@@ -1340,9 +1381,9 @@
              */
             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`).
              */