@twin.org/core 0.0.1-next.51 → 0.0.1-next.53

package/dist/esm/index.mjs

@@ -1814,6 +1814,53 @@ class Guards {
     }
 }
 
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Provide a store for shared objects which can be accesses through multiple
+ * instance loads of a packages.
+ */
+class SharedStore {
+    /**
+     * Get a property from the shared store.
+     * @param prop The name of the property to get.
+     * @returns The property if it exists.
+     */
+    static get(prop) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const shared = globalThis.__TWIN_SHARED__;
+        if (Is.undefined(shared)) {
+            return;
+        }
+        return shared[prop];
+    }
+    /**
+     * Set the property in the shared store.
+     * @param prop The name of the property to set.
+     * @param value The value to set.
+     */
+    static set(prop, value) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (Is.undefined(globalThis.__TWIN_SHARED__)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            globalThis.__TWIN_SHARED__ = {};
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        globalThis.__TWIN_SHARED__[prop] = value;
+    }
+    /**
+     * Remove a property from the shared store.
+     * @param prop The name of the property to remove.
+     */
+    static remove(prop) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const shared = globalThis.__TWIN_SHARED__;
+        if (!Is.undefined(shared)) {
+            delete shared[prop];
+        }
+    }
+}
+
 /**
  * Factory for creating implementation of generic types.
  */
@@ -1823,11 +1870,6 @@ class Factory {
      * @internal
      */
     static _CLASS_NAME = "Factory";
-    /**
-     * Store all the created factories.
-     * @internal
-     */
-    static _factories = {};
     /**
      * Type name for the instances.
      * @internal
@@ -1881,32 +1923,40 @@ class Factory {
      * @returns The factory instance.
      */
     static createFactory(typeName, autoInstance = false, matcher) {
-        if (Is.undefined(Factory._factories[typeName])) {
-            Factory._factories[typeName] = new Factory(typeName, autoInstance, matcher);
+        const factories = Factory.getFactories();
+        if (Is.undefined(factories[typeName])) {
+            factories[typeName] = new Factory(typeName, autoInstance, matcher);
         }
-        return Factory._factories[typeName];
+        return factories[typeName];
     }
     /**
      * Get all the factories.
      * @returns All the factories.
      */
     static getFactories() {
-        return Factory._factories;
+        let factories = SharedStore.get("factories");
+        if (Is.undefined(factories)) {
+            factories = {};
+            SharedStore.set("factories", factories);
+        }
+        return factories;
     }
     /**
      * Reset all the factories, which removes any created instances, but not the registrations.
      */
     static resetFactories() {
-        for (const typeName in Factory._factories) {
-            Factory._factories[typeName].reset();
+        const factories = Factory.getFactories();
+        for (const typeName in factories) {
+            factories[typeName].reset();
         }
     }
     /**
      * Clear all the factories, which removes anything registered with the factories.
      */
     static clearFactories() {
-        for (const typeName in Factory._factories) {
-            Factory._factories[typeName].clear();
+        const factories = Factory.getFactories();
+        for (const typeName in factories) {
+            factories[typeName].clear();
         }
     }
     /**
@@ -2854,34 +2904,15 @@ class I18n {
      * The default translation.
      */
     static DEFAULT_LOCALE = "en";
-    /**
-     * Dictionaries for lookups.
-     * @internal
-     */
-    static _localeDictionaries = {};
-    /**
-     * The current locale.
-     * @internal
-     */
-    static _currentLocale = I18n.DEFAULT_LOCALE;
-    /**
-     * Change handler for the locale being updated.
-     * @internal
-     */
-    static _localeChangedHandlers = {};
-    /**
-     * Change handler for the dictionaries being updated.
-     * @internal
-     */
-    static _dictionaryChangedHandlers = {};
     /**
      * Set the locale.
      * @param locale The new locale.
      */
     static setLocale(locale) {
-        I18n._currentLocale = locale;
-        for (const callback in I18n._localeChangedHandlers) {
-            I18n._localeChangedHandlers[callback](I18n._currentLocale);
+        const i18nShared = I18n.getI18nShared();
+        i18nShared.currentLocale = locale;
+        for (const callback in i18nShared.localeChangedHandlers) {
+            i18nShared.localeChangedHandlers[callback](i18nShared.currentLocale);
         }
     }
     /**
@@ -2889,7 +2920,8 @@ class I18n {
      * @returns The current locale.
      */
     static getLocale() {
-        return I18n._currentLocale;
+        const i18nShared = I18n.getI18nShared();
+        return i18nShared.currentLocale;
     }
     /**
      * Add a locale dictionary.
@@ -2897,11 +2929,12 @@ class I18n {
      * @param dictionary The dictionary to add.
      */
     static addDictionary(locale, dictionary) {
+        const i18nShared = I18n.getI18nShared();
         const mergedKeys = {};
         I18n.flattenTranslationKeys(dictionary, "", mergedKeys);
-        I18n._localeDictionaries[locale] = mergedKeys;
-        for (const callback in I18n._dictionaryChangedHandlers) {
-            I18n._dictionaryChangedHandlers[callback](I18n._currentLocale);
+        i18nShared.localeDictionaries[locale] = mergedKeys;
+        for (const callback in i18nShared.dictionaryChangedHandlers) {
+            i18nShared.dictionaryChangedHandlers[callback](i18nShared.currentLocale);
         }
     }
     /**
@@ -2910,14 +2943,16 @@ class I18n {
      * @returns The dictionary of undefined if it does not exist.
      */
     static getDictionary(locale) {
-        return I18n._localeDictionaries[locale];
+        const i18nShared = I18n.getI18nShared();
+        return i18nShared.localeDictionaries[locale];
     }
     /**
      * Get all the locale dictionaries.
      * @returns The dictionaries.
      */
     static getAllDictionaries() {
-        return I18n._localeDictionaries;
+        const i18nShared = I18n.getI18nShared();
+        return i18nShared.localeDictionaries;
     }
     /**
      * Add a locale changed handler.
@@ -2925,14 +2960,16 @@ class I18n {
      * @param handler The handler to add.
      */
     static addLocaleHandler(id, handler) {
-        I18n._localeChangedHandlers[id] = handler;
+        const i18nShared = I18n.getI18nShared();
+        i18nShared.localeChangedHandlers[id] = handler;
     }
     /**
      * Remove a locale changed handler.
      * @param id The id of the handler.
      */
     static removeLocaleHandler(id) {
-        delete I18n._localeChangedHandlers[id];
+        const i18nShared = I18n.getI18nShared();
+        delete i18nShared.localeChangedHandlers[id];
     }
     /**
      * Add a dictionary changed handler.
@@ -2940,14 +2977,16 @@ class I18n {
      * @param handler The handler to add.
      */
     static addDictionaryHandler(id, handler) {
-        I18n._dictionaryChangedHandlers[id] = handler;
+        const i18nShared = I18n.getI18nShared();
+        i18nShared.dictionaryChangedHandlers[id] = handler;
     }
     /**
      * Remove a dictionary changed handler.
      * @param id The id of the handler.
      */
     static removeDictionaryHandler(id) {
-        delete I18n._dictionaryChangedHandlers[id];
+        const i18nShared = I18n.getI18nShared();
+        delete i18nShared.dictionaryChangedHandlers[id];
     }
     /**
      * Format a message.
@@ -2957,21 +2996,22 @@ class I18n {
      * @returns The formatted string.
      */
     static formatMessage(key, values, overrideLocale) {
-        let cl = overrideLocale ?? I18n._currentLocale;
+        const i18nShared = I18n.getI18nShared();
+        let cl = overrideLocale ?? i18nShared.currentLocale;
         if (cl.startsWith("debug-")) {
             cl = I18n.DEFAULT_LOCALE;
         }
-        if (!I18n._localeDictionaries[cl]) {
+        if (!i18nShared.localeDictionaries[cl]) {
             return `!!Missing ${cl}`;
         }
-        if (!I18n._localeDictionaries[cl][key]) {
+        if (!i18nShared.localeDictionaries[cl][key]) {
             return `!!Missing ${cl}.${key}`;
         }
-        if (I18n._currentLocale === "debug-k") {
+        if (i18nShared.currentLocale === "debug-k") {
             return key;
         }
-        let ret = new IntlMessageFormat(I18n._localeDictionaries[cl][key], cl).format(values);
-        if (I18n._currentLocale === "debug-x") {
+        let ret = new IntlMessageFormat(i18nShared.localeDictionaries[cl][key], cl).format(values);
+        if (i18nShared.currentLocale === "debug-x") {
             ret = ret.replace(/[a-z]/g, "x").replace(/[A-Z]/g, "x").replace(/\d/g, "n");
         }
         return ret;
@@ -2982,7 +3022,8 @@ class I18n {
      * @returns True if the key exists.
      */
     static hasMessage(key) {
-        return Is.string(I18n._localeDictionaries[I18n._currentLocale]?.[key]);
+        const i18nShared = I18n.getI18nShared();
+        return Is.string(i18nShared.localeDictionaries[i18nShared.currentLocale]?.[key]);
     }
     /**
      * Flatten the translation property paths for faster lookup.
@@ -3003,6 +3044,24 @@ class I18n {
             }
         }
     }
+    /**
+     * Get the I18n shared data.
+     * @returns The I18n shared data.
+     * @internal
+     */
+    static getI18nShared() {
+        let i18nShared = SharedStore.get("i18n");
+        if (Is.undefined(i18nShared)) {
+            i18nShared = {
+                localeDictionaries: {},
+                currentLocale: I18n.DEFAULT_LOCALE,
+                localeChangedHandlers: {},
+                dictionaryChangedHandlers: {}
+            };
+            SharedStore.set("i18n", i18nShared);
+        }
+        return i18nShared;
+    }
 }
 
 // Copyright 2024 IOTA Stiftung.
@@ -3940,29 +3999,93 @@ class Urn {
  * Cache the results from asynchronous requests.
  */
 class AsyncCache {
-    /**
-     * Cache for the fetch requests.
-     * @internal
-     */
-    static _cache = {};
     /**
      * Execute an async request and cache the result.
      * @param key The key for the entry in the cache.
      * @param ttlMs The TTL of the entry in the cache.
      * @param requestMethod The method to call if not cached.
+     * @param cacheFailures Cache failure results, defaults to false.
      * @returns The response.
      */
-    static exec(key, ttlMs, requestMethod) {
+    static exec(key, ttlMs, requestMethod, cacheFailures) {
         const cacheEnabled = Is.integer(ttlMs) && ttlMs >= 0;
         if (cacheEnabled) {
             AsyncCache.cleanupExpired();
-            if (!this._cache[key]) {
-                this._cache[key] = {
-                    response: requestMethod(),
-                    expires: ttlMs === 0 ? 0 : Date.now() + ttlMs
-                };
+            const cache = AsyncCache.getSharedCache();
+            // Do we have a cache entry for the key
+            if (cache[key]) {
+                if (!Is.empty(cache[key].result)) {
+                    // If the cache has already resulted in a value, resolve it
+                    return Promise.resolve(cache[key].result);
+                }
+                else if (!Is.empty(cache[key].error)) {
+                    // If the cache has already resulted in an error, reject it
+                    return Promise.reject(cache[key].error);
+                }
+                // Otherwise create a promise to return and store the resolver
+                // and rejector in the cache entry, so that we can call then
+                // when the request is done
+                let storedResolve;
+                let storedReject;
+                const wait = new Promise((resolve, reject) => {
+                    storedResolve = resolve;
+                    storedReject = reject;
+                });
+                if (!Is.empty(storedResolve) && !Is.empty(storedReject)) {
+                    cache[key].promiseQueue.push({
+                        requestMethod,
+                        resolve: storedResolve,
+                        reject: storedReject
+                    });
+                }
+                return wait;
             }
-            return this._cache[key].response;
+            // If we don't have a cache entry, create a new one
+            cache[key] = {
+                promiseQueue: [],
+                expires: ttlMs === 0 ? 0 : Date.now() + ttlMs
+            };
+            // Return a promise that wraps the original request method
+            // so that we can store any results or errors in the cache
+            return new Promise((resolve, reject) => {
+                // Call the request method and store the result
+                requestMethod()
+                    // eslint-disable-next-line promise/prefer-await-to-then
+                    .then(res => {
+                    // If the request was successful, store the result
+                    cache[key].result = res;
+                    // and resolve both this promise and all the waiters
+                    resolve(res);
+                    for (const wait of cache[key].promiseQueue) {
+                        wait.resolve(res);
+                    }
+                    return res;
+                })
+                    // eslint-disable-next-line promise/prefer-await-to-then
+                    .catch((err) => {
+                    // Reject the promise
+                    reject(err);
+                    // Handle the waiters based on the cacheFailures flag
+                    if (cacheFailures ?? false) {
+                        // If we are caching failures, store the error and reject the waiters
+                        cache[key].error = err;
+                        for (const wait of cache[key].promiseQueue) {
+                            wait.reject(err);
+                        }
+                        // Clear the waiters so we don't call them again
+                        cache[key].promiseQueue = [];
+                    }
+                    else {
+                        // If not caching failures for any queued requests we
+                        // have no value to either resolve or reject, so we
+                        // just resolve with the original request method
+                        for (const wait of cache[key].promiseQueue) {
+                            wait.resolve(wait.requestMethod());
+                        }
+                        delete cache[key];
+                    }
+                });
+            });
         }
     }
     /**
@@ -3971,7 +4094,15 @@ class AsyncCache {
      * @returns The item from the cache if it exists.
      */
     static async get(key) {
-        return AsyncCache._cache[key]?.response;
+        const cache = AsyncCache.getSharedCache();
+        if (!Is.empty(cache[key].result)) {
+            // If the cache has already resulted in a value, resolve it
+            return cache[key].result;
+        }
+        else if (!Is.empty(cache[key].error)) {
+            // If the cache has already resulted in an error, reject it
+            throw cache[key].error;
+        }
     }
     /**
      * Set an entry into the cache.
@@ -3981,8 +4112,10 @@ class AsyncCache {
      * @returns Nothing.
      */
     static async set(key, value, ttlMs) {
-        AsyncCache._cache[key] = {
-            response: Promise.resolve(value),
+        const cache = AsyncCache.getSharedCache();
+        cache[key] = {
+            result: value,
+            promiseQueue: [],
             expires: Date.now() + (ttlMs ?? 1000)
         };
     }
@@ -3991,34 +4124,50 @@ class AsyncCache {
      * @param key The key to remove from the cache.
      */
     static remove(key) {
-        delete AsyncCache._cache[key];
+        const cache = AsyncCache.getSharedCache();
+        delete cache[key];
     }
     /**
      * Clear the cache.
      * @param prefix Optional prefix to clear only entries with that prefix.
      */
     static clearCache(prefix) {
+        const cache = AsyncCache.getSharedCache();
         if (Is.stringValue(prefix)) {
-            for (const entry in this._cache) {
+            for (const entry in cache) {
                 if (entry.startsWith(prefix)) {
-                    delete this._cache[entry];
+                    delete cache[entry];
                 }
             }
         }
         else {
-            AsyncCache._cache = {};
+            SharedStore.set("asyncCache", {});
         }
     }
     /**
      * Perform a cleanup of the expired entries in the cache.
      */
     static cleanupExpired() {
-        for (const entry in this._cache) {
-            if (AsyncCache._cache[entry].expires > 0 && AsyncCache._cache[entry].expires < Date.now()) {
-                delete this._cache[entry];
+        const cache = AsyncCache.getSharedCache();
+        for (const entry in cache) {
+            if (cache[entry].expires > 0 && cache[entry].expires < Date.now()) {
+                delete cache[entry];
             }
         }
     }
+    /**
+     * Get the shared cache.
+     * @returns The shared cache.
+     * @internal
+     */
+    static getSharedCache() {
+        let sharedCache = SharedStore.get("asyncCache");
+        if (Is.undefined(sharedCache)) {
+            sharedCache = {};
+            SharedStore.set("asyncCache", sharedCache);
+        }
+        return sharedCache;
+    }
 }
 
 /**
@@ -4842,4 +4991,4 @@ class Validation {
     }
 }
 
-export { AlreadyExistsError, ArrayHelper, AsyncCache, Base32, Base58, Base64, Base64Url, BaseError, BitString, Coerce, CoerceType, ComponentFactory, Compression, CompressionType, ConflictError, Converter, EnvHelper, ErrorHelper, Factory, FilenameHelper, GeneralError, GuardError, Guards, HexHelper, I18n, Is, JsonHelper, NotFoundError, NotImplementedError, NotSupportedError, ObjectHelper, RandomHelper, StringHelper, Uint8ArrayHelper, UnauthorizedError, UnprocessableError, Url, Urn, Validation, ValidationError };
+export { AlreadyExistsError, ArrayHelper, AsyncCache, Base32, Base58, Base64, Base64Url, BaseError, BitString, Coerce, CoerceType, ComponentFactory, Compression, CompressionType, ConflictError, Converter, EnvHelper, ErrorHelper, Factory, FilenameHelper, GeneralError, GuardError, Guards, HexHelper, I18n, Is, JsonHelper, NotFoundError, NotImplementedError, NotSupportedError, ObjectHelper, RandomHelper, SharedStore, StringHelper, Uint8ArrayHelper, UnauthorizedError, UnprocessableError, Url, Urn, Validation, ValidationError };

package/dist/types/index.d.ts

@@ -29,6 +29,7 @@ export * from "./models/coerceType";
 export * from "./models/compressionType";
 export * from "./models/IComponent";
 export * from "./models/IError";
+export * from "./models/II18nShared";
 export * from "./models/IKeyValue";
 export * from "./models/ILabelledValue";
 export * from "./models/ILocale";
@@ -47,4 +48,5 @@ export * from "./utils/converter";
 export * from "./utils/guards";
 export * from "./utils/i18n";
 export * from "./utils/is";
+export * from "./utils/sharedStore";
 export * from "./utils/validation";

package/dist/types/models/II18nShared.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The shared state for the I18n global.
+ */
+export interface II18nShared {
+    /**
+     * Dictionaries for lookups.
+     */
+    localeDictionaries: {
+        [locale: string]: {
+            [key: string]: string;
+        };
+    };
+    /**
+     * The current locale.
+     */
+    currentLocale: string;
+    /**
+     * Change handler for the locale being updated.
+     */
+    localeChangedHandlers: {
+        [id: string]: (locale: string) => void;
+    };
+    /**
+     * Change handler for the dictionaries being updated.
+     */
+    dictionaryChangedHandlers: {
+        [id: string]: (locale: string) => void;
+    };
+}

package/dist/types/utils/asyncCache.d.ts

@@ -7,9 +7,10 @@ export declare class AsyncCache {
      * @param key The key for the entry in the cache.
      * @param ttlMs The TTL of the entry in the cache.
      * @param requestMethod The method to call if not cached.
+     * @param cacheFailures Cache failure results, defaults to false.
      * @returns The response.
      */
-    static exec<T = unknown>(key: string, ttlMs: number | undefined, requestMethod: () => Promise<T>): Promise<T> | undefined;
+    static exec<T = unknown>(key: string, ttlMs: number | undefined, requestMethod: () => Promise<T>, cacheFailures?: boolean): Promise<T> | undefined;
     /**
      * Get an entry from the cache.
      * @param key The key to get from the cache.

package/dist/types/utils/sharedStore.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Provide a store for shared objects which can be accesses through multiple
+ * instance loads of a packages.
+ */
+export declare class SharedStore {
+    /**
+     * Get a property from the shared store.
+     * @param prop The name of the property to get.
+     * @returns The property if it exists.
+     */
+    static get<T = unknown>(prop: string): T | undefined;
+    /**
+     * Set the property in the shared store.
+     * @param prop The name of the property to set.
+     * @param value The value to set.
+     */
+    static set<T = unknown>(prop: string, value: T): void;
+    /**
+     * Remove a property from the shared store.
+     * @param prop The name of the property to remove.
+     */
+    static remove(prop: string): void;
+}

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # @twin.org/core - Changelog
 
+## [0.0.1-next.53](https://github.com/twinfoundation/framework/compare/core-v0.0.1-next.52...core-v0.0.1-next.53) (2025-05-01)
+
+
+### Features
+
+* async cache don't cache failures unless requested ([658ec4b](https://github.com/twinfoundation/framework/commit/658ec4b67a58a075de4702a3886d151e25ad3ddc))
+
+## [0.0.1-next.52](https://github.com/twinfoundation/framework/compare/core-v0.0.1-next.51...core-v0.0.1-next.52) (2025-04-17)
+
+
+### Features
+
+* use new shared store mechanism ([#131](https://github.com/twinfoundation/framework/issues/131)) ([934385b](https://github.com/twinfoundation/framework/commit/934385b2fbaf9f5c00a505ebf9d093bd5a425f55))
+
 ## [0.0.1-next.51](https://github.com/twinfoundation/framework/compare/core-v0.0.1-next.50...core-v0.0.1-next.51) (2025-03-27)
 
 

package/docs/reference/classes/AlreadyExistsError.md

@@ -8,9 +8,9 @@ Class to handle errors which are triggered by data already existing.
 
 ## Constructors
 
-### new AlreadyExistsError()
+### Constructor
 
-> **new AlreadyExistsError**(`source`, `message`, `existingId`?, `inner`?): [`AlreadyExistsError`](AlreadyExistsError.md)
+> **new AlreadyExistsError**(`source`, `message`, `existingId?`, `inner?`): `AlreadyExistsError`
 
 Create a new instance of AlreadyExistsError.
 
@@ -42,11 +42,11 @@ The inner error if we have wrapped another error.
 
 #### Returns
 
-[`AlreadyExistsError`](AlreadyExistsError.md)
+`AlreadyExistsError`
 
 #### Overrides
 
-[`BaseError`](BaseError.md).[`constructor`](BaseError.md#constructors)
+[`BaseError`](BaseError.md).[`constructor`](BaseError.md#constructor)
 
 ## Properties
 
@@ -66,7 +66,7 @@ The source of the error.
 
 #### Inherited from
 
-[`BaseError`](BaseError.md).[`source`](BaseError.md#source-1)
+[`BaseError`](BaseError.md).[`source`](BaseError.md#source)
 
 ***
 
@@ -82,7 +82,7 @@ Any additional information for the error.
 
 #### Inherited from
 
-[`BaseError`](BaseError.md).[`properties`](BaseError.md#properties-1)
+[`BaseError`](BaseError.md).[`properties`](BaseError.md#properties)
 
 ***
 
@@ -94,7 +94,7 @@ The inner error if there was one.
 
 #### Inherited from
 
-[`BaseError`](BaseError.md).[`inner`](BaseError.md#inner-1)
+[`BaseError`](BaseError.md).[`inner`](BaseError.md#inner)
 
 ## Methods
 

package/docs/reference/classes/ArrayHelper.md

@@ -4,13 +4,13 @@ Class to help with arrays.
 
 ## Constructors
 
-### new ArrayHelper()
+### Constructor
 
-> **new ArrayHelper**(): [`ArrayHelper`](ArrayHelper.md)
+> **new ArrayHelper**(): `ArrayHelper`
 
 #### Returns
 
-[`ArrayHelper`](ArrayHelper.md)
+`ArrayHelper`
 
 ## Methods