@zelgadis87/utils-core 5.3.0 → 5.3.1

package/.rollup/index.cjs

@@ -415,32 +415,32 @@ function doGroupByWith(arr, getter) {
     }, {});
 }
 
-function indexByString(arr, field) {
-    return indexByStringWith(arr, t => t[field]);
+function indexByString(arr, field, valueMapper = v => v) {
+    return indexByStringWith(arr, t => t[field], valueMapper);
 }
-function indexByNumber(arr, field) {
-    return indexByNumberWith(arr, t => t[field]);
+function indexByNumber(arr, field, valueMapper = v => v) {
+    return indexByNumberWith(arr, t => t[field], valueMapper);
 }
-function indexBySymbol(arr, field) {
-    return indexBySymbolWith(arr, t => t[field]);
+function indexBySymbol(arr, field, valueMapper = v => v) {
+    return indexBySymbolWith(arr, t => t[field], valueMapper);
 }
-function indexByStringWith(arr, getter) {
-    return doIndexByWith(arr, getter);
+function indexByStringWith(arr, keyGetter, valueMapper = v => v) {
+    return doIndexByWith(arr, keyGetter, valueMapper);
 }
-function indexByNumberWith(arr, getter) {
-    return doIndexByWith(arr, getter);
+function indexByNumberWith(arr, keyGetter, valueMapper = v => v) {
+    return doIndexByWith(arr, keyGetter, valueMapper);
 }
-function indexBySymbolWith(arr, getter) {
-    return doIndexByWith(arr, getter);
+function indexBySymbolWith(arr, keyGetter, valueMapper = v => v) {
+    return doIndexByWith(arr, keyGetter, valueMapper);
 }
-function doIndexByWith(arr, getter) {
+function doIndexByWith(arr, keyGetter, valueMapper = v => v) {
     return arr.reduce((dict, cur) => {
-        const key = getter(cur);
+        const key = keyGetter(cur);
         if (key !== null && key !== undefined) {
             if (dict[key]) {
                 throw new Error(`Multiple values indexed by same key "${String(key)}".`);
             }
-            dict[key] = cur;
+            dict[key] = valueMapper(cur);
         }
         return dict;
     }, {});
@@ -1317,6 +1317,9 @@ class Lazy {
             fnEmpty();
         }
     }
+    empty() {
+        this._initialized = false;
+    }
     static of(generator) {
         return new Lazy(generator);
     }
@@ -1398,6 +1401,9 @@ class LazyAsync {
             throw new Error(errorMessage);
         return this._promise;
     }
+    empty() {
+        this._promise = undefined;
+    }
     static of(generator) {
         return new LazyAsync(generator);
     }
@@ -2612,6 +2618,180 @@ class Logger {
     }
 }
 
+const logger = new Logger('Cached');
+/**
+ * A cached value with stale-while-revalidate pattern.
+ * On initialization, the class starts calculating the async result (isPending() === true).
+ * When complete, the class will store the generated value (isReady() === true).
+ * After maxStale duration, the value becomes stale and will refresh in background on next access (isStale() === true).
+ * After maxAge has passed, the cached value is no longer used (isExpired() === true).
+ */
+class Cached {
+    /** Current promise for the value generation. */
+    _promise = undefined;
+    /** Flag indicating if a generation is currently in progress. */
+    _pending = false;
+    /** The last successfully generated value. */
+    _resolvedValue = undefined;
+    /** Function that generates the cached value. */
+    _generator;
+    /** Timestamp of the last successful value generation. */
+    _generatedAt = TimeInstant.ZERO;
+    /** The duration for which value should be kept cached. After maxAge from the last generated value, this object is considered empty. */
+    _maxAge;
+    /** The duration for which the value should be served from cache, even if stale. Has no effect if greater or equal to maxAge. */
+    _maxStale;
+    /** Callback invoked when new data becomes available. */
+    _onNewDataAvailable = noop;
+    /** Callback invoked when generation fails. */
+    _onError = err => logger.error('Cache generation failed:', err);
+    constructor(generator, maxAge, maxStale) {
+        this._generator = ensureDefined(generator);
+        this._maxAge = ensureDefined(maxAge);
+        this._maxStale = ensureDefined(TimeDuration.lowest(maxAge, maxStale));
+    }
+    /**
+     * Gets the cached value.
+     * Returns fresh data if available, stale data while revalidating, or triggers generation if empty/expired.
+     * @returns Promise resolving to the cached value.
+     */
+    async get() {
+        if (this.isPending()) {
+            return this._promise;
+        }
+        else if (this.isEmpty() || this.isExpired()) {
+            this._promise = this.generate();
+            return this._promise;
+        }
+        else {
+            if (this.isStale()) {
+                // Start re-generating the contents, while serving stale data.
+                void this.generate();
+            }
+            return this._resolvedValue;
+        }
+    }
+    /**
+     * Generates a new value using the generator function.
+     * Sets up promise handlers for success and error cases.
+     * @returns The generation promise.
+     */
+    generate() {
+        if (this._pending)
+            return this._promise;
+        this._pending = true;
+        const deferred = new Deferred();
+        this._generator().then(value => {
+            this._pending = false;
+            this._resolvedValue = value;
+            this._generatedAt = TimeInstant.now();
+            deferred.resolve(value);
+            withTryCatch(() => this._onNewDataAvailable(value));
+        }, error => {
+            const err = asError(error);
+            this._pending = false;
+            deferred.reject(err);
+            withTryCatch(() => this._onError(err));
+        });
+        return deferred.asPromise();
+    }
+    /**
+     * Checks if value has been requested at least once.
+     * @returns True if a promise exists.
+     */
+    isPresent() {
+        return this._promise !== undefined;
+    }
+    /**
+     * Checks value has never been requested.
+     * @returns True if empty.
+     */
+    isEmpty() {
+        return this._promise === undefined;
+    }
+    /**
+     * Checks if value generation is currently in progress.
+     * @returns True if generation is pending.
+     */
+    isPending() {
+        return this.isPresent() && this._pending === true;
+    }
+    /**
+     * Checks if value is stored and fresh.
+     * @returns True if stored and fresh.
+     */
+    isReady() {
+        return this.isPresent() && this.getAge().isLessThan(this._maxAge);
+    }
+    // protected isResolved() {
+    // 	return this.isReady() && this._error === undefined;
+    // }
+    // protected isError() {
+    // 	return this.isReady() && this._error !== undefined;
+    // }
+    /**
+     * Checks if cached value is stale (older than maxStale duration).
+     * @returns True if value is stale.
+     */
+    isStale() {
+        return this.isPresent() && this.getAge().isGreaterThan(this._maxStale);
+    }
+    /**
+     * Checks if cached value is expired (older than maxAge duration).
+     * @returns True if value is expired.
+     */
+    isExpired() {
+        return this.isPresent() && this.getAge().isGreaterThan(this._maxAge);
+    }
+    /**
+     * Gets the timestamp when the value was last successfully generated.
+     * @returns The last update timestamp.
+     */
+    getLastUpdated() {
+        return this._generatedAt;
+    }
+    /**
+     * Gets the age of the cached value.
+     * @returns The duration since the value was last generated.
+     */
+    getAge() {
+        return this._generatedAt.distanceFromNow();
+    }
+    /**
+     * Invalidates the cache by resetting the generation timestamp.
+     * Next access will trigger fresh generation.
+     */
+    invalidate() {
+        this._generatedAt = TimeInstant.ZERO;
+    }
+    /**
+     * Sets a callback to be invoked when new data becomes available.
+     * @param callback Function to call with the new value.
+     */
+    onNewDataAvailable(callback) {
+        this._onNewDataAvailable = ensureDefined(callback);
+    }
+    /**
+     * Sets a callback to be invoked when generation fails.
+     * @param callback Function to call with the error.
+     */
+    onError(callback) {
+        this._onError = ensureDefined(callback);
+    }
+    /**
+     * Creates a new Cached instance.
+     * @param generator Function that generates the value to cache.
+     * @param maxAge Maximum duration for which cached value is considered valid.
+     * @param maxStale Maximum duration for which stale value is served while revalidating. Defaults to maxAge.
+     * @returns A new Cached instance.
+     */
+    static of(generator, maxAge, maxStale = maxAge) {
+        const cached = new Cached(generator, maxAge, maxStale);
+        void cached.get();
+        return cached;
+    }
+}
+
 const defaultCompareValuesOptions = {
     nullsFirst: false,
 };
@@ -3086,6 +3266,7 @@ function isUpgradable(obj) {
     return isDefined(obj) && typeof obj === "object" && VERSION_FIELD in obj && isNumber(obj.$version) && isPositiveNumber(obj.$version);
 }
 
+exports.Cached = Cached;
 exports.DataUpgrader = DataUpgrader;
 exports.Deferred = Deferred;
 exports.DeferredCanceledError = DeferredCanceledError;