@zajno/common 2.8.1 → 2.8.2

package/cjs/lazy/lazy.js

@@ -2,6 +2,10 @@
 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;
@@ -31,18 +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;
     }
+    /** 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) {

package/cjs/lazy/lazy.js.map

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

package/cjs/lazy/promise.js

@@ -2,6 +2,11 @@
 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;
@@ -9,8 +14,10 @@ class LazyPromise {
     _isLoading = null;
     _promise;
     _expireTracker;
-    _lastRefreshingPromise = null;
+    // Track the active factory promise to determine "latest wins"
+    _activeFactoryPromise = null;
     _error = null;
+    _ownDisposer;
     constructor(factory, initial) {
         this._factory = factory;
         this._initial = initial;
@@ -27,99 +34,72 @@ 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;
     }
     /**
-     * Extends this instance with additional functionality by applying extensions in place.
+     * Extends this instance with additional functionality via in-place mutation.
      *
      * **Capabilities:**
-     * - `overrideFactory`: Wrap the factory function (logging, retry, caching, etc.)
-     * - `extendShape`: Add custom properties/methods to the instance
+     * - `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 (e.g., number-only)
+     * - Use `ILazyPromiseExtension<ConcreteType>` for type-specific extensions
      *
-     * **Note:** Extensions mutate the instance and can be chained. Subclasses preserve their type.
+     * **Note:** Extensions mutate the instance and can be chained.
      *
-     * @param extension - Configuration with factory override and/or shape extensions
-     * @returns The same instance (this) with applied extensions
+     * @param extension - Extension configuration
+     * @returns The same instance with applied extensions
      *
      * @example
      * ```typescript
-     * // Universal logging extension
      * const logged = lazy.extend({
      *   overrideFactory: (factory) => async (refreshing) => {
      *     console.log('Loading...');
      *     return await factory(refreshing);
      *   }
      * });
-     *
-     * // Type-specific extension with custom methods
-     * const enhanced = lazyNumber.extend<{ double: () => number | undefined }>({
-     *   extendShape: (instance) => Object.assign(instance, {
-     *     double: () => instance.currentValue !== undefined
-     *       ? instance.currentValue * 2
-     *       : undefined
-     *   })
-     * });
-     *
-     * // Chaining multiple extensions
-     * const composed = lazy
-     *   .extend(cacheExtension)
-     *   .extend(loggingExtension);
      * ```
      */
     extend(
     // Partial allows extensions with extra properties beyond the interface
     // 'any' type parameter doesn't affect return type since we return 'this'
     extension) {
-        // Override the factory if provided
-        if (extension.overrideFactory) {
-            this._factory = extension.overrideFactory(this._factory, this);
-        }
+        let extended = this;
         // Apply shape extension if provided
         if (extension.extendShape) {
-            return extension.extendShape(this);
+            extended = extension.extendShape(this);
         }
-        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;
+        // Override the factory if provided
+        if (extension.overrideFactory) {
+            this._factory = extension.overrideFactory(this._factory, extended);
         }
-        if (this._isLoading === null) {
-            this._isLoading = true;
-            this.doLoad();
+        if (extension.dispose) {
+            const previousDisposer = this._ownDisposer;
+            const nextDisposer = extension.dispose;
+            this._ownDisposer = () => {
+                nextDisposer(extended);
+                previousDisposer?.();
+            };
         }
+        return extended;
     }
-    doLoad() {
-        this._promise = this._factory(false)
-            .then(this.onResolved.bind(this))
-            .catch(this.onRejected.bind(this));
-    }
-    onResolved(res) {
-        // case: during the promise `setInstance` was called
-        if (!this._isLoading && this._instance !== undefined) {
-            return this._instance;
-        }
-        this.setInstance(res);
-        return res;
-    }
-    onRejected(e) {
-        this._isLoading = false;
-        this._instance = this._initial;
-        this._promise = Promise.resolve(this._initial);
-        this.setError(e);
-        return this._initial;
-    }
+    /**
+     * 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
@@ -127,41 +107,24 @@ class LazyPromise {
         // + 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;
     }
-    setError(err) {
-        this._error = this.parseError(err);
-    }
-    clearError() {
-        this._error = null;
-    }
+    /**
+     * 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() {
-        let myPromise = null;
-        try {
-            myPromise = this._factory(true);
-            // every new refresh overrides the previous one
-            // so this one becomes "last"
-            // and previous becomes stale and won't update the value when it resolves
-            this._lastRefreshingPromise = myPromise;
-            const fresh = await myPromise;
-            if (this._lastRefreshingPromise === myPromise) {
-                this.setInstance(fresh);
-            }
-            return fresh;
-        }
-        catch (e) {
-            this.setError(e);
-            return this._instance;
-        }
-        finally {
-            if (myPromise != null && this._lastRefreshingPromise === myPromise) {
-                this._lastRefreshingPromise = null;
-            }
-        }
+        this.startLoading(true);
+        return this._promise;
     }
     reset() {
         this._isLoading = null;
@@ -170,6 +133,7 @@ class LazyPromise {
         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) {
@@ -179,8 +143,73 @@ 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;

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/esm/lazy/lazy.js

@@ -1,4 +1,8 @@
 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;
@@ -28,18 +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;
     }
+    /** 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) {

package/esm/lazy/lazy.js.map

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

package/esm/lazy/promise.js

@@ -1,4 +1,9 @@
 import { tryDispose } from '../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.
+ */
 export class LazyPromise {
     _factory;
     _initial;
@@ -6,8 +11,10 @@ export class LazyPromise {
     _isLoading = null;
     _promise;
     _expireTracker;
-    _lastRefreshingPromise = null;
+    // Track the active factory promise to determine "latest wins"
+    _activeFactoryPromise = null;
     _error = null;
+    _ownDisposer;
     constructor(factory, initial) {
         this._factory = factory;
         this._initial = initial;
@@ -24,99 +31,72 @@ export 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;
     }
     /**
-     * Extends this instance with additional functionality by applying extensions in place.
+     * Extends this instance with additional functionality via in-place mutation.
      *
      * **Capabilities:**
-     * - `overrideFactory`: Wrap the factory function (logging, retry, caching, etc.)
-     * - `extendShape`: Add custom properties/methods to the instance
+     * - `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 (e.g., number-only)
+     * - Use `ILazyPromiseExtension<ConcreteType>` for type-specific extensions
      *
-     * **Note:** Extensions mutate the instance and can be chained. Subclasses preserve their type.
+     * **Note:** Extensions mutate the instance and can be chained.
      *
-     * @param extension - Configuration with factory override and/or shape extensions
-     * @returns The same instance (this) with applied extensions
+     * @param extension - Extension configuration
+     * @returns The same instance with applied extensions
      *
      * @example
      * ```typescript
-     * // Universal logging extension
      * const logged = lazy.extend({
      *   overrideFactory: (factory) => async (refreshing) => {
      *     console.log('Loading...');
      *     return await factory(refreshing);
      *   }
      * });
-     *
-     * // Type-specific extension with custom methods
-     * const enhanced = lazyNumber.extend<{ double: () => number | undefined }>({
-     *   extendShape: (instance) => Object.assign(instance, {
-     *     double: () => instance.currentValue !== undefined
-     *       ? instance.currentValue * 2
-     *       : undefined
-     *   })
-     * });
-     *
-     * // Chaining multiple extensions
-     * const composed = lazy
-     *   .extend(cacheExtension)
-     *   .extend(loggingExtension);
      * ```
      */
     extend(
     // Partial allows extensions with extra properties beyond the interface
     // 'any' type parameter doesn't affect return type since we return 'this'
     extension) {
-        // Override the factory if provided
-        if (extension.overrideFactory) {
-            this._factory = extension.overrideFactory(this._factory, this);
-        }
+        let extended = this;
         // Apply shape extension if provided
         if (extension.extendShape) {
-            return extension.extendShape(this);
+            extended = extension.extendShape(this);
         }
-        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;
+        // Override the factory if provided
+        if (extension.overrideFactory) {
+            this._factory = extension.overrideFactory(this._factory, extended);
         }
-        if (this._isLoading === null) {
-            this._isLoading = true;
-            this.doLoad();
+        if (extension.dispose) {
+            const previousDisposer = this._ownDisposer;
+            const nextDisposer = extension.dispose;
+            this._ownDisposer = () => {
+                nextDisposer(extended);
+                previousDisposer?.();
+            };
         }
+        return extended;
     }
-    doLoad() {
-        this._promise = this._factory(false)
-            .then(this.onResolved.bind(this))
-            .catch(this.onRejected.bind(this));
-    }
-    onResolved(res) {
-        // case: during the promise `setInstance` was called
-        if (!this._isLoading && this._instance !== undefined) {
-            return this._instance;
-        }
-        this.setInstance(res);
-        return res;
-    }
-    onRejected(e) {
-        this._isLoading = false;
-        this._instance = this._initial;
-        this._promise = Promise.resolve(this._initial);
-        this.setError(e);
-        return this._initial;
-    }
+    /**
+     * 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
@@ -124,41 +104,24 @@ export class LazyPromise {
         // + 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;
     }
-    setError(err) {
-        this._error = this.parseError(err);
-    }
-    clearError() {
-        this._error = null;
-    }
+    /**
+     * 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() {
-        let myPromise = null;
-        try {
-            myPromise = this._factory(true);
-            // every new refresh overrides the previous one
-            // so this one becomes "last"
-            // and previous becomes stale and won't update the value when it resolves
-            this._lastRefreshingPromise = myPromise;
-            const fresh = await myPromise;
-            if (this._lastRefreshingPromise === myPromise) {
-                this.setInstance(fresh);
-            }
-            return fresh;
-        }
-        catch (e) {
-            this.setError(e);
-            return this._instance;
-        }
-        finally {
-            if (myPromise != null && this._lastRefreshingPromise === myPromise) {
-                this._lastRefreshingPromise = null;
-            }
-        }
+        this.startLoading(true);
+        return this._promise;
     }
     reset() {
         this._isLoading = null;
@@ -167,6 +130,7 @@ export class LazyPromise {
         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) {
@@ -176,8 +140,73 @@ export 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;

package/esm/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zajno/common",
-  "version": "2.8.1",
+  "version": "2.8.2",
   "description": "Zajno's re-usable utilities for JS/TS projects",
   "private": false,
   "type": "module",

package/types/lazy/lazy.d.ts

@@ -2,6 +2,10 @@ import { type IDisposable } from '../functions/disposer.js';
 import type { IResettableModel } from '../models/types.js';
 import type { IExpireTracker } from '../structures/expire.js';
 import type { ILazy } from './types.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 declare class Lazy<T> implements ILazy<T>, IDisposable, IResettableModel {
     protected readonly _factory: (() => T);
     protected _instance: T | undefined;
@@ -15,9 +19,13 @@ export declare class Lazy<T> implements ILazy<T>, IDisposable, IResettableModel
     get error(): string | null;
     /** Override me: additional way to make sure instance is valid */
     protected get isValid(): boolean;
+    /** Provides custom cleanup logic when the instance is reset or disposed. */
     withDisposer(disposer: (prev: T) => void): this;
+    /** Configures automatic cache expiration using an expire tracker. */
     withExpire(tracker: IExpireTracker | undefined): this;
+    /** Eagerly loads the value without accessing it. Useful for preloading. */
     prewarm(): this;
+    /** Manually sets the cached value. */
     setInstance(instance: T | undefined): void;
     reset(): void;
     dispose(): void;

package/types/lazy/promise.d.ts

@@ -2,6 +2,11 @@ import { type IDisposable } from '../functions/disposer.js';
 import type { IResettableModel } from '../models/types.js';
 import type { IExpireTracker } from '../structures/expire.js';
 import type { IControllableLazyPromise, ILazyPromiseExtension, LazyFactory } from './types.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.
+ */
 export declare class LazyPromise<T, TInitial extends T | undefined = undefined> implements IControllableLazyPromise<T, TInitial>, IDisposable, IResettableModel {
     private _factory;
     private readonly _initial;
@@ -9,68 +14,72 @@ export declare class LazyPromise<T, TInitial extends T | undefined = undefined>
     private _isLoading;
     private _promise;
     private _expireTracker;
-    private _lastRefreshingPromise;
+    private _activeFactoryPromise;
     private _error;
+    private _ownDisposer?;
     constructor(factory: LazyFactory<T>, initial?: TInitial);
     get isLoading(): boolean | null;
     get hasValue(): boolean;
     get error(): string | null;
     get promise(): Promise<T>;
     get value(): T | TInitial;
-    /** does not calls factory */
+    /** Returns current value without triggering loading. */
     get currentValue(): T | TInitial;
+    /** Configures automatic cache expiration using an expire tracker. */
     withExpire(tracker: IExpireTracker | undefined): this;
     /**
-     * Extends this instance with additional functionality by applying extensions in place.
+     * Extends this instance with additional functionality via in-place mutation.
      *
      * **Capabilities:**
-     * - `overrideFactory`: Wrap the factory function (logging, retry, caching, etc.)
-     * - `extendShape`: Add custom properties/methods to the instance
+     * - `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 (e.g., number-only)
+     * - Use `ILazyPromiseExtension<ConcreteType>` for type-specific extensions
      *
-     * **Note:** Extensions mutate the instance and can be chained. Subclasses preserve their type.
+     * **Note:** Extensions mutate the instance and can be chained.
      *
-     * @param extension - Configuration with factory override and/or shape extensions
-     * @returns The same instance (this) with applied extensions
+     * @param extension - Extension configuration
+     * @returns The same instance with applied extensions
      *
      * @example
      * ```typescript
-     * // Universal logging extension
      * const logged = lazy.extend({
      *   overrideFactory: (factory) => async (refreshing) => {
      *     console.log('Loading...');
      *     return await factory(refreshing);
      *   }
      * });
-     *
-     * // Type-specific extension with custom methods
-     * const enhanced = lazyNumber.extend<{ double: () => number | undefined }>({
-     *   extendShape: (instance) => Object.assign(instance, {
-     *     double: () => instance.currentValue !== undefined
-     *       ? instance.currentValue * 2
-     *       : undefined
-     *   })
-     * });
-     *
-     * // Chaining multiple extensions
-     * const composed = lazy
-     *   .extend(cacheExtension)
-     *   .extend(loggingExtension);
      * ```
      */
     extend<TExtShape extends object = object>(extension: Partial<ILazyPromiseExtension<any, TExtShape>>): object extends TExtShape ? this : this & TExtShape;
-    protected ensureInstanceLoading(): void;
-    protected doLoad(): void;
-    protected onResolved(res: T): T;
-    protected onRejected(e: unknown): T;
+    /**
+     * 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: T): T;
-    protected setError(err: unknown): void;
-    protected clearError(): void;
+    /**
+     * 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
+     */
     refresh(): Promise<T>;
     reset(): void;
     dispose(): void;
+    protected ensureInstanceLoading(): void;
+    private startLoading;
+    protected onRejected(e: unknown): T | TInitial;
+    protected setError(err: unknown): void;
+    protected clearError(): void;
     protected parseError(err: unknown): string;
 }

package/types/lazy/types.d.ts

@@ -1,58 +1,54 @@
 import type { IResettableModel } from '../models/types.js';
-/** Represents a lazily loaded value. */
+/** Represents a lazily loaded value that initializes on first access. */
 export interface ILazy<T> {
-    /** Returns current value. If not loaded, loading is triggered. */
+    /** Returns current value, triggering loading if not yet loaded. */
     readonly value: T;
-    /** Returns whether has current value. Accessing this property does not trigger loading. */
+    /** Returns true if value has been loaded. Does not trigger loading. */
     readonly hasValue: boolean;
-    /** Returns current value or undefined if not present. Accessing this property does not trigger loading. */
+    /** Returns current value or undefined if not loaded. Does not trigger loading. */
     readonly currentValue: T | undefined;
-    /** Returns error message if loading failed, null otherwise. Accessing this property does not trigger loading. */
+    /** Returns error message if loading failed, null otherwise. Does not trigger loading. */
     readonly error: string | null;
 }
-/** Represents a lazily asynchronously loaded value. */
+/** Represents a lazily asynchronously loaded value with promise-based access. */
 export interface ILazyPromise<T, TInitial extends T | undefined = undefined> extends ILazy<T | TInitial> {
     /**
-     * Returns true if loading is in progress, false if loading is completed, null if loading was not initiated.
-     *
-     * Accessing this property does not trigger loading.
+     * Returns loading state: true (loading), false (loaded), null (not started).
+     * Does not trigger loading.
      */
     readonly isLoading: boolean | null;
-    /** Returns the promise for the current value. If not loaded, accessing this property triggers loading. */
+    /** Returns the promise for the value, triggering loading if not started. */
     readonly promise: Promise<T>;
     /**
-     * Refreshes the value by re-executing the factory function.
-     * The factory will be called with `refreshing: true` parameter.
-     * If multiple refreshes are called concurrently, only the last one will update the instance.
+     * Re-executes the factory to get fresh data. If concurrent refreshes occur, the latest wins.
+     * All awaiting promises will resolve to the final refreshed value.
      *
-     * **⚠️ Use sparingly:** This method should only be called when you explicitly need fresh data.
-     * Over-using refresh defeats the purpose of lazy loading and caching.
+     * **⚠️ Use sparingly:** Only refresh when explicitly needed for fresh data.
+     * Over-use defeats lazy loading and caching benefits.
      *
-     * **Common valid use cases:**
-     * - User-initiated refresh action (pull-to-refresh, refresh button)
-     * - Cache invalidation after a mutation (e.g., after updating data on server)
-     * - Time-based refresh with proper debouncing/throttling
-     * - Recovery from an error state
+     * **Valid use cases:**
+     * - User-initiated refresh (pull-to-refresh, refresh button)
+     * - Cache invalidation after mutation
+     * - Time-based refresh with throttling
+     * - Error recovery
      *
-     * **Anti-patterns to avoid:**
-     * - Calling refresh on every render or component mount
-     * - Using refresh instead of proper cache expiration (use `withExpire` instead)
-     * - Calling refresh in loops or high-frequency events without debouncing
-     * - Using refresh as a substitute for real-time updates (consider WebSockets/polling instead)
+     * **Avoid:**
+     * - Refreshing on every render/mount
+     * - Using instead of cache expiration (use `withExpire`)
+     * - Calling in loops or high-frequency events without debouncing
      *
-     * @returns Promise that resolves to the refreshed value, or current value if refresh fails.
+     * @returns Promise resolving to the refreshed value
      */
     refresh(): Promise<T>;
 }
 /**
- * Represents a controllable lazy promise with manual state management capabilities.
- * Extends ILazyPromise and IResettableModel with methods to manually set values and reset state.
- * Use this interface in extensions that need direct control over the lazy value lifecycle.
+ * Controllable lazy promise with manual state management.
+ * Extends ILazyPromise with methods to manually set values and reset state.
  */
 export interface IControllableLazyPromise<T, TInitial extends T | undefined = undefined> extends ILazyPromise<T, TInitial>, IResettableModel {
     /**
-     * Manually sets the instance value and marks loading as complete.
-     * Useful for cache synchronization and manual state management.
+     * Manually sets the value and marks loading as complete.
+     * Useful for cache synchronization and manual state updates.
      *
      * @param value - The value to set
      * @returns The value that was set
@@ -60,28 +56,20 @@ export interface IControllableLazyPromise<T, TInitial extends T | undefined = un
     setInstance(value: T): T;
 }
 /**
- * Factory function to retrieve the fresh value.
+ * Factory function that retrieves the value for LazyPromise.
  *
- * @param refreshing - indicates whether manual refresh is requested
- * */
+ * @param refreshing - True when called via refresh(), false on initial load
+ */
 export type LazyFactory<T> = (refreshing?: boolean) => Promise<T>;
 /**
- * Extension for LazyPromise instances.
+ * Extension for LazyPromise instances, enabling factory wrapping and instance augmentation.
  *
- * @template T - The type of value the extension is compatible with. Use `any` for universal extensions.
- * @template TExtShape - Additional shape added to the extended instance (properties/methods).
+ * @template T - Value type the extension is compatible with (use `any` for universal extensions)
+ * @template TExtShape - Additional properties/methods added to the instance
  *
  * @example
  * ```typescript
- * // Type-specific extension (only for numbers)
- * const doublingExtension: ILazyPromiseExtension<number> = {
- *   overrideFactory: (original) => async (refreshing) => {
- *     const result = await original(refreshing);
- *     return result * 2;
- *   }
- * };
- *
- * // Universal extension (works with any type)
+ * // Universal logging extension
  * const loggingExtension: ILazyPromiseExtension<any> = {
  *   overrideFactory: (original) => async (refreshing) => {
  *     console.log('Loading...');
@@ -92,19 +80,40 @@ export type LazyFactory<T> = (refreshing?: boolean) => Promise<T>;
  */
 export interface ILazyPromiseExtension<T = any, TExtShape extends object = object> {
     /**
-     * Override or wrap the factory function.
+     * Augment the instance with additional properties/methods.
+     * Receives IControllableLazyPromise with setInstance() and reset() for manual control.
+     *
+     * @param previous - The controllable LazyPromise instance
+     * @returns The instance with additional shape
+     */
+    extendShape?: <TInitial extends T | undefined = undefined>(previous: IControllableLazyPromise<T, TInitial>) => IControllableLazyPromise<T, TInitial> & TExtShape;
+    /**
+     * Wrap or replace the factory function.
+     *
      * @param original - The original factory function
      * @param target - The LazyPromise instance being extended
      * @returns A new factory function
      */
-    overrideFactory?: <TInitial extends T | undefined = undefined>(original: LazyFactory<T>, target: ILazyPromise<T, TInitial>) => LazyFactory<T>;
+    overrideFactory?: <TInitial extends T | undefined = undefined>(original: LazyFactory<T>, target: ILazyPromise<T, TInitial> & TExtShape) => LazyFactory<T>;
     /**
-     * Extend the instance with additional properties/methods.
-     * Receives IControllableLazyPromise which includes setInstance() and reset() methods
-     * for manual state management and cache synchronization.
+     * Cleanup function called when the LazyPromise is disposed.
+     * Use for cleaning up resources (timers, subscriptions, listeners).
+     * Executes in reverse order: newest extension first, oldest last.
      *
-     * @param previous - The controllable LazyPromise instance to extend
-     * @returns The instance with additional shape
+     * @param instance - The extended LazyPromise instance being disposed
+     *
+     * @example
+     * ```typescript
+     * const intervalExtension: ILazyPromiseExtension<any, { stopTimer: () => void }> = {
+     *   extendShape: (instance) => {
+     *     let intervalId: NodeJS.Timeout | null = null;
+     *     return Object.assign(instance, {
+     *       stopTimer: () => { if (intervalId) clearInterval(intervalId); }
+     *     });
+     *   },
+     *   dispose: (instance) => instance.stopTimer()
+     * };
+     * ```
      */
-    extendShape?: <TInitial extends T | undefined = undefined>(previous: IControllableLazyPromise<T, TInitial>) => IControllableLazyPromise<T, TInitial> & TExtShape;
+    dispose?: (instance: ILazyPromise<T, any> & TExtShape) => void;
 }