@zajno/common 2.8.0 → 2.8.2

package/cjs/lazy/extensions.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCacheExtension = createCacheExtension;
+const extendObject_js_1 = require("../structures/extendObject.js");
+function createCacheExtension(storage) {
+    return {
+        overrideFactory: (original) => {
+            return async (refreshing) => {
+                if (!refreshing) {
+                    // read cached value first
+                    const cached = await storage.getValue();
+                    if (cached != null) {
+                        return cached;
+                    }
+                }
+                const value = await original(refreshing);
+                // cache the fresh result
+                storage.setValue(value);
+                return value;
+            };
+        },
+        extendShape: (previous) => {
+            return (0, extendObject_js_1.extendObject)(previous, {
+                cache: {
+                    get: () => storage,
+                },
+                resetWithCache: {
+                    value: () => {
+                        storage.removeValue();
+                        previous.reset();
+                    },
+                },
+                setCachedInstance: {
+                    value: (value) => {
+                        if (value == null) {
+                            storage.removeValue();
+                        }
+                        else {
+                            storage.setValue(value);
+                        }
+                        return previous.setInstance(value);
+                    },
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=extensions.js.map

package/cjs/lazy/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../../src/lazy/extensions.ts"],"names":[],"mappings":";;AAcA,oDAoDC;AAjED,mEAA6D;AAa7D,SAAgB,oBAAoB,CAA8D,OAAiB;IAC/G,OAAO;QACH,eAAe,EAAE,CACb,QAA8C,EACR,EAAE;YACxC,OAAO,KAAK,EAAE,UAAoB,EAAc,EAAE;gBAC9C,IAAI,CAAC,UAAU,EAAE,CAAC;oBACd,0BAA0B;oBAC1B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;oBACxC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;wBACjB,OAAO,MAAM,CAAC;oBAClB,CAAC;gBACL,CAAC;gBAED,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,CAAC;gBAEzC,yBAAyB;gBACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAExB,OAAO,KAAK,CAAC;YACjB,CAAC,CAAC;QACN,CAAC;QACD,WAAW,EAAE,CACT,QAA+C,EACjD,EAAE;YACA,OAAO,IAAA,8BAAY,EACf,QAAQ,EACR;gBACI,KAAK,EAAE;oBACH,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO;iBACrB;gBACD,cAAc,EAAE;oBACZ,KAAK,EAAE,GAAG,EAAE;wBACR,OAAO,CAAC,WAAW,EAAE,CAAC;wBACtB,QAAQ,CAAC,KAAK,EAAE,CAAC;oBACrB,CAAC;iBACJ;gBACD,iBAAiB,EAAE;oBACf,KAAK,EAAE,CAAC,KAAQ,EAAE,EAAE;wBAChB,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;4BAChB,OAAO,CAAC,WAAW,EAAE,CAAC;wBAC1B,CAAC;6BAAM,CAAC;4BACJ,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;wBAC5B,CAAC;wBAED,OAAO,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;oBACvC,CAAC;iBACJ;aACJ,CACJ,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC"}

package/cjs/lazy/lazy.js

@@ -2,11 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Lazy = void 0;
 const disposer_js_1 = require("../functions/disposer.js");
+/**
+ * Synchronous lazy-loading container that initializes a value on first access.
+ * The value is cached until reset or expired. Supports custom disposal and cache expiration.
+ */
 class Lazy {
     _factory;
     _instance = undefined;
     _expireTracker;
     _disposer;
+    _error = null;
     constructor(_factory) {
         this._factory = _factory;
     }
@@ -15,9 +20,8 @@ class Lazy {
         this.ensureInstance();
         return this._instance;
     }
-    get currentValue() {
-        return this._instance;
-    }
+    get currentValue() { return this._instance; }
+    get error() { return this._error; }
     /** Override me: additional way to make sure instance is valid */
     get isValid() {
         if (!this.hasValue) {
@@ -31,27 +35,22 @@ class Lazy {
         }
         return true;
     }
+    /** Provides custom cleanup logic when the instance is reset or disposed. */
     withDisposer(disposer) {
         this._disposer = disposer;
         return this;
     }
+    /** Configures automatic cache expiration using an expire tracker. */
     withExpire(tracker) {
         this._expireTracker = tracker;
         return this;
     }
-    ensureInstance() {
-        if (this.isValid) {
-            return;
-        }
-        // additional reset to make sure previous instance has been disposed
-        this.reset();
-        const res = this._factory();
-        this.setInstance(res);
-    }
+    /** Eagerly loads the value without accessing it. Useful for preloading. */
     prewarm() {
         this.ensureInstance();
         return this;
     }
+    /** Manually sets the cached value. */
     setInstance(instance) {
         this._instance = instance;
         if (this._instance !== undefined && this._expireTracker) {
@@ -68,8 +67,32 @@ class Lazy {
             }
         }
         this.setInstance(undefined);
+        this._error = null;
     }
     dispose() { this.reset(); }
+    ensureInstance() {
+        if (this.isValid) {
+            return;
+        }
+        // additional reset to make sure previous instance has been disposed
+        this.reset();
+        try {
+            const res = this._factory();
+            this.setInstance(res);
+        }
+        catch (e) {
+            this._error = this.parseError(e);
+        }
+    }
+    parseError(err) {
+        if (typeof err === 'string') {
+            return err;
+        }
+        if (err instanceof Error) {
+            return err.message;
+        }
+        return String(err) || 'Unknown error';
+    }
 }
 exports.Lazy = Lazy;
 //# sourceMappingURL=lazy.js.map

package/cjs/lazy/lazy.js.map

@@ -1 +1 @@
-{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../../../src/lazy/lazy.ts"],"names":[],"mappings":";;;AAAA,0DAAwE;AAKxE,MAAa,IAAI;IAMkB;IAJrB,SAAS,GAAkB,SAAS,CAAC;IACvC,cAAc,CAA6B;IAC3C,SAAS,CAAqB;IAEtC,YAA+B,QAAmB;QAAnB,aAAQ,GAAR,QAAQ,CAAW;IAAI,CAAC;IAEvD,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC;IAEvD,IAAI,KAAK;QACL,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,SAAU,CAAC;IAC3B,CAAC;IAED,IAAI,YAAY;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED,iEAAiE;IACjE,IAAc,OAAO;QACjB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,KAAK,CAAC;YACjB,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC;IAChB,CAAC;IAEM,YAAY,CAAC,QAA2B;QAC3C,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,OAAO,IAAI,CAAC;IAChB,CAAC;IAEM,UAAU,CAAC,OAAmC;QACjD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAC9B,OAAO,IAAI,CAAC;IAChB,CAAC;IAEO,cAAc;QAClB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO;QACX,CAAC;QAED,oEAAoE;QACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO;QACH,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,WAAW,CAAC,QAAuB;QAC/B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAE1B,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtD,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;QAClC,CAAC;IACL,CAAC;IAED,KAAK;QACD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACjB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACJ,IAAA,wBAAU,EAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;CAC9B;AAjFD,oBAiFC"}
+{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../../../src/lazy/lazy.ts"],"names":[],"mappings":";;;AAAA,0DAAwE;AAKxE;;;GAGG;AACH,MAAa,IAAI;IAOkB;IALrB,SAAS,GAAkB,SAAS,CAAC;IACvC,cAAc,CAA6B;IAC3C,SAAS,CAAqB;IAC9B,MAAM,GAAkB,IAAI,CAAC;IAErC,YAA+B,QAAmB;QAAnB,aAAQ,GAAR,QAAQ,CAAW;IAAI,CAAC;IAEvD,IAAW,QAAQ,KAAK,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC;IAE9D,IAAW,KAAK;QACZ,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,SAAc,CAAC;IAC/B,CAAC;IAED,IAAW,YAAY,KAAK,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACpD,IAAW,KAAK,KAAK,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAE1C,iEAAiE;IACjE,IAAc,OAAO;QACjB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,KAAK,CAAC;YACjB,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,4EAA4E;IACrE,YAAY,CAAC,QAA2B;QAC3C,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,qEAAqE;IAC9D,UAAU,CAAC,OAAmC;QACjD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAC9B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,2EAA2E;IACpE,OAAO;QACV,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,sCAAsC;IAC/B,WAAW,CAAC,QAAuB;QACtC,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAE1B,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtD,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;QAClC,CAAC;IACL,CAAC;IAEM,KAAK;QACR,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACjB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACJ,IAAA,wBAAU,EAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACvB,CAAC;IAEM,OAAO,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE1B,cAAc;QAClB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO;QACX,CAAC;QAED,oEAAoE;QACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAU,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACrC,CAAC;IACL,CAAC;IAES,UAAU,CAAC,GAAY;QAC7B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO,GAAG,CAAC;QACf,CAAC;QACD,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACvB,OAAO,GAAG,CAAC,OAAO,CAAC;QACvB,CAAC;QACD,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC;IAC1C,CAAC;CACJ;AApGD,oBAoGC"}

package/cjs/lazy/light.js

@@ -4,17 +4,27 @@ exports.createLazy = createLazy;
 function createLazy(factory) {
     const _factory = factory;
     let _instance = undefined;
+    let _error = null;
     const res = {
         get value() {
             if (_instance === undefined) {
-                _instance = _factory();
+                _error = null;
+                try {
+                    _instance = _factory();
+                }
+                catch (e) {
+                    _error = e instanceof Error ? e.message : String(e);
+                    throw e;
+                }
             }
             return _instance;
         },
         get currentValue() { return _instance; },
         get hasValue() { return _instance !== undefined; },
+        get error() { return _error; },
         reset: () => {
             _instance = undefined;
+            _error = null;
         },
         dispose: () => res.reset(),
     };

package/cjs/lazy/light.js.map

@@ -1 +1 @@
-{"version":3,"file":"light.js","sourceRoot":"","sources":["../../../src/lazy/light.ts"],"names":[],"mappings":";;AAIA,gCAoBC;AApBD,SAAgB,UAAU,CAAI,OAAgB;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC;IACzB,IAAI,SAAS,GAAkB,SAAS,CAAC;IAEzC,MAAM,GAAG,GAA8C;QACnD,IAAI,KAAK;YACL,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC1B,SAAS,GAAG,QAAQ,EAAE,CAAC;YAC3B,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,YAAY,KAAK,OAAO,SAAS,CAAC,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC;QAClD,KAAK,EAAE,GAAG,EAAE;YACR,SAAS,GAAG,SAAS,CAAC;QAC1B,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE;KAC7B,CAAC;IAEF,OAAO,GAAG,CAAC;AACf,CAAC"}
+{"version":3,"file":"light.js","sourceRoot":"","sources":["../../../src/lazy/light.ts"],"names":[],"mappings":";;AAIA,gCA6BC;AA7BD,SAAgB,UAAU,CAAI,OAAgB;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC;IACzB,IAAI,SAAS,GAAkB,SAAS,CAAC;IACzC,IAAI,MAAM,GAAkB,IAAI,CAAC;IAEjC,MAAM,GAAG,GAA8C;QACnD,IAAI,KAAK;YACL,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,GAAG,IAAI,CAAC;gBACd,IAAI,CAAC;oBACD,SAAS,GAAG,QAAQ,EAAE,CAAC;gBAC3B,CAAC;gBAAC,OAAO,CAAU,EAAE,CAAC;oBAClB,MAAM,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBACpD,MAAM,CAAC,CAAC;gBACZ,CAAC;YACL,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,YAAY,KAAK,OAAO,SAAS,CAAC,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,OAAO,MAAM,CAAC,CAAC,CAAC;QAC9B,KAAK,EAAE,GAAG,EAAE;YACR,SAAS,GAAG,SAAS,CAAC;YACtB,MAAM,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE;KAC7B,CAAC;IAEF,OAAO,GAAG,CAAC;AACf,CAAC"}

package/cjs/lazy/promise.js

@@ -2,20 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LazyPromise = void 0;
 const disposer_js_1 = require("../functions/disposer.js");
+/**
+ * Asynchronous lazy-loading container that initializes via a promise-based factory.
+ * Handles concurrent operations with "latest wins" semantics: multiple refreshes are automatically
+ * coordinated so all awaiting promises receive the final value. Supports extensions for custom behavior.
+ */
 class LazyPromise {
     _factory;
-    initial;
-    _instance = undefined;
+    _initial;
+    _instance;
     _isLoading = null;
     _promise;
     _expireTracker;
-    constructor(_factory, initial = undefined) {
-        this._factory = _factory;
-        this.initial = initial;
-        this._instance = initial;
+    // Track the active factory promise to determine "latest wins"
+    _activeFactoryPromise = null;
+    _error = null;
+    _ownDisposer;
+    constructor(factory, initial) {
+        this._factory = factory;
+        this._initial = initial;
+        this._instance = initial; // as ILazyValue<T, TInitial>;
     }
     get isLoading() { return this._isLoading; }
     get hasValue() { return this._isLoading === false; }
+    get error() { return this._error; }
     get promise() {
         this.ensureInstanceLoading();
         return this._promise;
@@ -24,50 +34,106 @@ class LazyPromise {
         this.ensureInstanceLoading();
         return this._instance;
     }
-    /** does not calls factory */
+    /** Returns current value without triggering loading. */
     get currentValue() {
         return this._instance;
     }
+    /** Configures automatic cache expiration using an expire tracker. */
     withExpire(tracker) {
         this._expireTracker = tracker;
         return this;
     }
-    ensureInstanceLoading() {
-        if (this.isLoading === false && this._instance !== undefined && this._expireTracker?.isExpired) {
-            // do not reset the instance, just make sure it will be reloaded
-            this._isLoading = null;
+    /**
+     * Extends this instance with additional functionality via in-place mutation.
+     *
+     * **Capabilities:**
+     * - `overrideFactory`: Wrap the factory (logging, retry, caching, etc.)
+     * - `extendShape`: Add custom properties/methods
+     * - `dispose`: Cleanup resources when disposed
+     *
+     * **Type Safety:**
+     * - Use `ILazyPromiseExtension<any>` for universal extensions
+     * - Use `ILazyPromiseExtension<ConcreteType>` for type-specific extensions
+     *
+     * **Note:** Extensions mutate the instance and can be chained.
+     *
+     * @param extension - Extension configuration
+     * @returns The same instance with applied extensions
+     *
+     * @example
+     * ```typescript
+     * const logged = lazy.extend({
+     *   overrideFactory: (factory) => async (refreshing) => {
+     *     console.log('Loading...');
+     *     return await factory(refreshing);
+     *   }
+     * });
+     * ```
+     */
+    extend(
+    // Partial allows extensions with extra properties beyond the interface
+    // 'any' type parameter doesn't affect return type since we return 'this'
+    extension) {
+        let extended = this;
+        // Apply shape extension if provided
+        if (extension.extendShape) {
+            extended = extension.extendShape(this);
         }
-        if (this._isLoading === null) {
-            this._isLoading = true;
-            this._promise = this._factory().then(this.onResolved.bind(this));
+        // Override the factory if provided
+        if (extension.overrideFactory) {
+            this._factory = extension.overrideFactory(this._factory, extended);
         }
-    }
-    onResolved(res) {
-        // case: during the promise `setInstance` was called
-        if (!this._isLoading && this._instance !== undefined) {
-            return this._instance;
+        if (extension.dispose) {
+            const previousDisposer = this._ownDisposer;
+            const nextDisposer = extension.dispose;
+            this._ownDisposer = () => {
+                nextDisposer(extended);
+                previousDisposer?.();
+            };
         }
-        this.setInstance(res);
-        return res;
+        return extended;
     }
+    /**
+     * Manually sets the value and marks loading as complete.
+     * Clears any errors and restarts the expiration tracker if configured.
+     *
+     * @param res - The value to set
+     * @returns The value that was set
+     */
     setInstance(res) {
         this._isLoading = false;
+        this.clearError(); // clear error on successful set
         // refresh promise so it won't keep old callbacks
         // + make sure it's resolved with the freshest value
         // also do this before setting the instance... just in case :)
         this._promise = Promise.resolve(res);
+        this._activeFactoryPromise = null;
         this._instance = res;
-        if (this._expireTracker) {
-            this._expireTracker.restart();
-        }
+        this._expireTracker?.restart();
         return res;
     }
+    /**
+     * Re-executes the factory to get fresh data.
+     *
+     * **Concurrency handling:**
+     * - Supersedes any in-progress load or refresh
+     * - Multiple concurrent refreshes: latest wins
+     * - All awaiting promises receive the final refreshed value
+     *
+     * @returns Promise resolving to the refreshed value
+     */
+    async refresh() {
+        this.startLoading(true);
+        return this._promise;
+    }
     reset() {
         this._isLoading = null;
+        this.clearError();
         const wasDisposed = (0, disposer_js_1.tryDispose)(this._instance);
-        this._instance = this.initial;
+        this._instance = this._initial;
         const p = this._promise;
         this._promise = undefined;
+        this._activeFactoryPromise = null; // Clear active promise reference
         // check if loading is still in progress
         // need to dispose abandoned value
         if (p && !wasDisposed) {
@@ -77,8 +143,82 @@ class LazyPromise {
         }
     }
     dispose() {
+        this._ownDisposer?.();
         this.reset();
     }
+    ensureInstanceLoading() {
+        if (this.isLoading === false && this._instance !== undefined && this._expireTracker?.isExpired) {
+            // do not reset the instance, just make sure it will be reloaded
+            this._isLoading = null;
+        }
+        if (this._isLoading === null) {
+            this._isLoading = true;
+            this.startLoading(false);
+        }
+    }
+    startLoading(refreshing) {
+        if (!refreshing && this._activeFactoryPromise) {
+            // Case when refreshing already is happening - we have an active promise
+            return;
+        }
+        const factoryPromise = this._factory(refreshing)
+            .then(res => {
+            if (!this._activeFactoryPromise) {
+                // this promise was abandoned: was superseded or reset called
+                return this._instance ?? this._initial;
+            }
+            if (this._activeFactoryPromise === factoryPromise) {
+                // case: during the promise `setInstance` was called manually
+                if (!refreshing && !this._isLoading && this._instance !== undefined) {
+                    return this._instance;
+                }
+                this.setInstance(res);
+                return res;
+            }
+            // Stale promise - return the latest active promise instead
+            // This ensures anyone awaiting this old promise gets the fresh value
+            return this._activeFactoryPromise;
+        })
+            .catch(err => {
+            if (!this._activeFactoryPromise || this._activeFactoryPromise === factoryPromise) {
+                return this.onRejected(err);
+            }
+            throw err;
+        });
+        const hadActive = !!this._activeFactoryPromise;
+        // This is now the active promise - any previous one is superseded
+        this._activeFactoryPromise = factoryPromise;
+        // don't overwrite an existing promise (e.g., from refresh)
+        // it should pick up the new active promise automatically
+        if (!this._promise || !hadActive) {
+            this._promise = factoryPromise;
+        }
+    }
+    onRejected(e) {
+        this._isLoading = false;
+        // Keep the current instance on error (don't reset to initial)
+        // This allows retaining the last successful value
+        const currentInstance = this._instance !== undefined ? this._instance : this._initial;
+        this._promise = Promise.resolve(currentInstance);
+        this._activeFactoryPromise = null;
+        this.setError(e);
+        return currentInstance;
+    }
+    setError(err) {
+        this._error = this.parseError(err);
+    }
+    clearError() {
+        this._error = null;
+    }
+    parseError(err) {
+        if (typeof err === 'string') {
+            return err;
+        }
+        if (err instanceof Error) {
+            return err.message;
+        }
+        return String(err) || 'Unknown error';
+    }
 }
 exports.LazyPromise = LazyPromise;
 //# sourceMappingURL=promise.js.map

package/cjs/lazy/promise.js.map

@@ -1 +1 @@
-{"version":3,"file":"promise.js","sourceRoot":"","sources":["../../../src/lazy/promise.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"promise.js","sourceRoot":"","sources":["../../../src/lazy/promise.ts"],"names":[],"mappings":"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"}

package/cjs/lazy/types.js

@@ -1,5 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-;
-;
 //# sourceMappingURL=types.js.map

package/cjs/lazy/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lazy/types.ts"],"names":[],"mappings":";;AAWC,CAAC;AASD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lazy/types.ts"],"names":[],"mappings":""}

package/cjs/structures/extendObject.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extendObject = extendObject;
+/** Type-safe version of `Object.defineProperties` */
+function extendObject(base, extensionDescriptorsMap) {
+    return Object.defineProperties(base, extensionDescriptorsMap);
+}
+//# sourceMappingURL=extendObject.js.map

package/cjs/structures/extendObject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extendObject.js","sourceRoot":"","sources":["../../../src/structures/extendObject.ts"],"names":[],"mappings":";;AAeA,oCAKC;AAND,qDAAqD;AACrD,SAAgB,YAAY,CAC1B,IAAO,EACP,uBAAiD;IAEjD,OAAO,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,CAAmB,CAAC;AAClF,CAAC"}

package/esm/lazy/extensions.js

@@ -0,0 +1,45 @@
+import { extendObject } from '../structures/extendObject.js';
+export function createCacheExtension(storage) {
+    return {
+        overrideFactory: (original) => {
+            return async (refreshing) => {
+                if (!refreshing) {
+                    // read cached value first
+                    const cached = await storage.getValue();
+                    if (cached != null) {
+                        return cached;
+                    }
+                }
+                const value = await original(refreshing);
+                // cache the fresh result
+                storage.setValue(value);
+                return value;
+            };
+        },
+        extendShape: (previous) => {
+            return extendObject(previous, {
+                cache: {
+                    get: () => storage,
+                },
+                resetWithCache: {
+                    value: () => {
+                        storage.removeValue();
+                        previous.reset();
+                    },
+                },
+                setCachedInstance: {
+                    value: (value) => {
+                        if (value == null) {
+                            storage.removeValue();
+                        }
+                        else {
+                            storage.setValue(value);
+                        }
+                        return previous.setInstance(value);
+                    },
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=extensions.js.map

package/esm/lazy/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../../src/lazy/extensions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAa7D,MAAM,UAAU,oBAAoB,CAA8D,OAAiB;IAC/G,OAAO;QACH,eAAe,EAAE,CACb,QAA8C,EACR,EAAE;YACxC,OAAO,KAAK,EAAE,UAAoB,EAAc,EAAE;gBAC9C,IAAI,CAAC,UAAU,EAAE,CAAC;oBACd,0BAA0B;oBAC1B,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;oBACxC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;wBACjB,OAAO,MAAM,CAAC;oBAClB,CAAC;gBACL,CAAC;gBAED,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,CAAC;gBAEzC,yBAAyB;gBACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAExB,OAAO,KAAK,CAAC;YACjB,CAAC,CAAC;QACN,CAAC;QACD,WAAW,EAAE,CACT,QAA+C,EACjD,EAAE;YACA,OAAO,YAAY,CACf,QAAQ,EACR;gBACI,KAAK,EAAE;oBACH,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO;iBACrB;gBACD,cAAc,EAAE;oBACZ,KAAK,EAAE,GAAG,EAAE;wBACR,OAAO,CAAC,WAAW,EAAE,CAAC;wBACtB,QAAQ,CAAC,KAAK,EAAE,CAAC;oBACrB,CAAC;iBACJ;gBACD,iBAAiB,EAAE;oBACf,KAAK,EAAE,CAAC,KAAQ,EAAE,EAAE;wBAChB,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;4BAChB,OAAO,CAAC,WAAW,EAAE,CAAC;wBAC1B,CAAC;6BAAM,CAAC;4BACJ,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;wBAC5B,CAAC;wBAED,OAAO,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;oBACvC,CAAC;iBACJ;aACJ,CACJ,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC"}

package/esm/lazy/lazy.js

@@ -1,9 +1,14 @@
 import { tryDispose } from '../functions/disposer.js';
+/**
+ * Synchronous lazy-loading container that initializes a value on first access.
+ * The value is cached until reset or expired. Supports custom disposal and cache expiration.
+ */
 export class Lazy {
     _factory;
     _instance = undefined;
     _expireTracker;
     _disposer;
+    _error = null;
     constructor(_factory) {
         this._factory = _factory;
     }
@@ -12,9 +17,8 @@ export class Lazy {
         this.ensureInstance();
         return this._instance;
     }
-    get currentValue() {
-        return this._instance;
-    }
+    get currentValue() { return this._instance; }
+    get error() { return this._error; }
     /** Override me: additional way to make sure instance is valid */
     get isValid() {
         if (!this.hasValue) {
@@ -28,27 +32,22 @@ export class Lazy {
         }
         return true;
     }
+    /** Provides custom cleanup logic when the instance is reset or disposed. */
     withDisposer(disposer) {
         this._disposer = disposer;
         return this;
     }
+    /** Configures automatic cache expiration using an expire tracker. */
     withExpire(tracker) {
         this._expireTracker = tracker;
         return this;
     }
-    ensureInstance() {
-        if (this.isValid) {
-            return;
-        }
-        // additional reset to make sure previous instance has been disposed
-        this.reset();
-        const res = this._factory();
-        this.setInstance(res);
-    }
+    /** Eagerly loads the value without accessing it. Useful for preloading. */
     prewarm() {
         this.ensureInstance();
         return this;
     }
+    /** Manually sets the cached value. */
     setInstance(instance) {
         this._instance = instance;
         if (this._instance !== undefined && this._expireTracker) {
@@ -65,7 +64,31 @@ export class Lazy {
             }
         }
         this.setInstance(undefined);
+        this._error = null;
     }
     dispose() { this.reset(); }
+    ensureInstance() {
+        if (this.isValid) {
+            return;
+        }
+        // additional reset to make sure previous instance has been disposed
+        this.reset();
+        try {
+            const res = this._factory();
+            this.setInstance(res);
+        }
+        catch (e) {
+            this._error = this.parseError(e);
+        }
+    }
+    parseError(err) {
+        if (typeof err === 'string') {
+            return err;
+        }
+        if (err instanceof Error) {
+            return err.message;
+        }
+        return String(err) || 'Unknown error';
+    }
 }
 //# sourceMappingURL=lazy.js.map

package/esm/lazy/lazy.js.map

@@ -1 +1 @@
-{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../../../src/lazy/lazy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,0BAA0B,CAAC;AAKxE,MAAM,OAAO,IAAI;IAMkB;IAJrB,SAAS,GAAkB,SAAS,CAAC;IACvC,cAAc,CAA6B;IAC3C,SAAS,CAAqB;IAEtC,YAA+B,QAAmB;QAAnB,aAAQ,GAAR,QAAQ,CAAW;IAAI,CAAC;IAEvD,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC;IAEvD,IAAI,KAAK;QACL,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,SAAU,CAAC;IAC3B,CAAC;IAED,IAAI,YAAY;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED,iEAAiE;IACjE,IAAc,OAAO;QACjB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,IAAI,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,KAAK,CAAC;YACjB,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC;IAChB,CAAC;IAEM,YAAY,CAAC,QAA2B;QAC3C,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,OAAO,IAAI,CAAC;IAChB,CAAC;IAEM,UAAU,CAAC,OAAmC;QACjD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;QAC9B,OAAO,IAAI,CAAC;IAChB,CAAC;IAEO,cAAc;QAClB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO;QACX,CAAC;QAED,oEAAoE;QACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO;QACH,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,WAAW,CAAC,QAAuB;QAC/B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAE1B,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACtD,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;QAClC,CAAC;IACL,CAAC;IAED,KAAK;QACD,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACjB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACJ,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;CAC9B"}
+{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../../../src/lazy/lazy.ts"],"names":[],"mappings":"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"}