@inox-tools/utils 0.6.0 → 0.8.0

package/dist/lazy.d.ts

@@ -1,14 +1,43 @@
+/**
+ * Callback type for attaching side effects to lazy values with a name identifier.
+ *
+ * @template T - The type of the lazy value
+ * @template O - The return type of the attachment callback (defaults to void)
+ */
+type LazyMapping<T, O = void> = (name: string, value: T) => O;
+/**
+ * Utility type that extracts the inner types from an array of Lazy instances.
+ *
+ * @template T - A tuple of Lazy instances
+ */
+type UnwrapLazies<T extends Lazy<any>[]> = T extends [
+    Lazy<infer First>,
+    ...infer Rest extends Lazy<any>[]
+] ? [First, ...UnwrapLazies<Rest>] : [];
 /**
  * A lazily computed memoized value.
  *
  * The given factory is only constructed on first use of the value.
  * Any subsequent use retrieves the same instance of the value.
+ *
+ * If the value is accessed while it is being created, an error is thrown to prevent circular dependencies.
+ * When that happens, the Lazy instance becomes unusable.
+ *
+ * Lazy implements the Promise interface, allowing it to be awaited directly.
+ *
+ * @template T - The type of the lazily computed value
  */
-declare class Lazy<T> {
+declare class Lazy<T> implements Promise<T> {
     private factory;
-    private initialized;
-    private value?;
+    private value;
+    private attachments?;
     private constructor();
+    /**
+     * Creates a new Lazy instance from a factory function.
+     *
+     * @param factory - A function that produces the value when first accessed
+     * @returns A new Lazy instance wrapping the factory
+     */
     static of<T>(factory: () => T): Lazy<T>;
     /**
      * Wrap the given factory into a lazily computed memoized value.
@@ -16,7 +45,156 @@ declare class Lazy<T> {
      * The function will at most be called once, on the first use of the value.
      */
     static wrap<T>(factory: () => T): () => T;
+    /**
+     * Gets the lazily computed value, creating it if necessary.
+     *
+     * @returns The computed value
+     * @throws Error if a circular dependency is detected during value creation
+     */
     get(): T;
+    ensureInitialized(): void;
+    /**
+     * Implements Promise.then() for Promise compatibility.
+     * Allows the Lazy instance to be awaited.
+     */
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+    /**
+     * Implements Promise.catch() for Promise compatibility.
+     */
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+    /**
+     * Implements Promise.finally() for Promise compatibility.
+     */
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    /** String tag for Object.prototype.toString */
+    [Symbol.toStringTag]: string;
+    /**
+     * Registers a callback to be executed when, and if, the lazy value is computed.
+     * If the value is already computed, the callback is invoked immediately.
+     *
+     * @param attach - Callback to execute with the computed value
+     * @returns This instance for chaining
+     */
+    attach(attach: (value: T) => void): this;
+    /**
+     * Creates a new Lazy that transforms this value using the provided function.
+     * The new Lazy is automatically evaluated when this one is evaluated.
+     * This way, if either Lazy is evaluated, both values are computed.
+     *
+     * @template O - The type of the transformed value
+     * @param mapper - Transformation function to apply to the value
+     * @returns A new Lazy instance containing the transformed value
+     */
+    chain<O>(mapper: (value: T) => O): Lazy<O>;
+    /**
+     * Attaches a callback to multiple named lazy values.
+     * The callback receives both the name and value for each lazy when evaluated.
+     *
+     * @template T - The type of the lazy values
+     * @param lazies - Record of named Lazy instances
+     * @param attach - Callback to execute for each lazy value
+     */
+    static attachMulti<T>(lazies: Record<string, Lazy<T>>, attach: LazyMapping<T>): void;
+    /**
+     * Chains a transformation across multiple named lazy values.
+     * Creates a new record of Lazy instances with transformed values.
+     *
+     * @template T - The type of the input lazy values
+     * @template R - The record type containing the lazy instances
+     * @template O - The type of the transformed values
+     * @param lazies - Record of named Lazy instances
+     * @param mapper - Transformation function receiving name and value
+     * @returns A new record of Lazy instances with the same keys
+     */
+    static chainMulti<T, const R extends Record<string, Lazy<T>>, O>(lazies: R, mapper: LazyMapping<T, O>): Record<keyof R, Lazy<O>>;
+    /**
+     * Attaches a callback that is invoked when all lazy values in the array are evaluated.
+     * The callback receives all values as arguments in order.
+     *
+     * @template Ts - Tuple type of Lazy instances
+     * @param lazies - Array of Lazy instances to wait for
+     * @param attach - Callback receiving all unwrapped values
+     */
+    static attachAll<const Ts extends Lazy<any>[]>(lazies: Ts, attach: (...args: UnwrapLazies<Ts>) => void): void;
+    /**
+     * Creates a new Lazy that combines all values from the given lazy instances.
+     * The transformation is invoked when all input lazies are evaluated.
+     *
+     * @template Ts - Tuple type of Lazy instances
+     * @template O - The type of the combined result
+     * @param lazies - Array of Lazy instances to combine
+     * @param mapper - Transformation function receiving all unwrapped values
+     * @returns A new Lazy instance containing the combined result
+     */
+    static chainAll<const Ts extends Lazy<any>[], O>(lazies: Ts, mapper: (...args: UnwrapLazies<Ts>) => O): Lazy<O>;
+}
+/**
+ * A keyed lazy value store that memoizes values by string key.
+ *
+ * Each key maps to a lazily computed value that is only created on first access.
+ * Supports attachments that are notified when new values are created.
+ * @template T - The type of values stored
+ */
+declare class LazyKeyed<T> {
+    private factory;
+    /** Map of key to either a tuple containing the value or CREATING symbol */
+    private readonly instances;
+    /** List of callbacks to invoke when any value is created */
+    private readonly attachments;
+    private constructor();
+    /**
+     * Creates a new LazyKeyed instance from a factory function.
+     * @param factory - A function that produces a value for a given key
+     * @returns A new LazyKeyed instance
+     */
+    static of<T>(factory: (key: string) => T): LazyKeyed<T>;
+    /**
+     * Gets the value for the given key, creating it if necessary.
+     * @param key - The key to look up or create
+     * @returns The value associated with the key
+     * @throws Error if a circular dependency is detected during value creation
+     */
+    get(key: string): T;
+    /**
+     * Pre-initializes values for the given keys.
+     * Useful for eagerly creating values that will be needed later.
+     * @param key - The first key to reserve
+     * @param keys - Additional keys to reserve
+     * @returns This instance for chaining
+     */
+    reserve(key: string, ...keys: string[]): this;
+    /**
+     * Registers a callback to be executed for each value when created.
+     * Immediately invokes the callback for any already-created values.
+     * @param attach - Callback receiving the key and value
+     * @returns This instance for chaining
+     */
+    attach(attach: LazyMapping<T>): this;
+    /**
+     * Registers a callback for a specific key only.
+     * The callback is invoked when the value for that key is created.
+     * @param key - The key to watch
+     * @param attach - Callback receiving the value
+     * @returns This instance for chaining
+     */
+    attachOne(key: string, attach: (value: T) => void): this;
+    /**
+     * Creates a new LazyKeyed that transforms values using the provided function.
+     * Values in the new LazyKeyed are automatically created when source values are created.
+     * @template O - The type of the transformed values
+     * @param mapper - Transformation function receiving key and value
+     * @returns A new LazyKeyed instance with transformed values
+     */
+    chain<O>(mapper: LazyMapping<T, O>): LazyKeyed<O>;
+    /**
+     * Creates a Lazy that transforms the value for a specific key.
+     * The Lazy is automatically evaluated when the source value is created.
+     * @template O - The type of the transformed value
+     * @param key - The key to transform
+     * @param mapper - Transformation function receiving the value
+     * @returns A Lazy instance containing the transformed value
+     */
+    chainOne<O>(key: string, mapper: (value: T) => O): Lazy<O>;
 }
 
-export { Lazy };
+export { Lazy, LazyKeyed };

package/dist/lazy.js

@@ -1,2 +1,2 @@
-class a{constructor(i){this.factory=i;}initialized=false;value;static of(i){return new this(i)}static wrap(i){const t=a.of(i);return t.get.bind(t)}get(){return this.initialized||(this.value=this.factory(),this.initialized=true),this.value}}export{a as Lazy};//# sourceMappingURL=lazy.js.map
+const s=Symbol("creating"),c=Symbol("missing"),l=()=>{throw new Error("This Lazy value has already been consumed.")};class a{constructor(t){this.factory=t;}value=c;attachments=[];static of(t){return new a(t)}static wrap(t){const e=a.of(t);return e.get.bind(e)}get(){if(this.value===c){this.value=s;const t=this.factory();this.factory=l,this.value=t;for(const e of this.attachments)e(t);delete this.attachments;}if(this.value===s)throw new Error("Circular dependency detected during Lazy value creation.");return this.value}ensureInitialized(){this.value!==s&&this.get();}then(t,e){return Promise.resolve().then(()=>this.get()).then(t,e)}catch(t){return this.then(void 0,t)}finally(t){return this.then().finally(t)}[Symbol.toStringTag]="Lazy";attach(t){return this.value!==c&&this.value!==s?t(this.value):this.attachments.push(t),this}chain(t){const e=a.of(()=>t(this.get()));return this.attach(()=>e.ensureInitialized()),e}static attachMulti(t,e){for(const[i,n]of Object.entries(t))n.attach(r=>e(i,r));}static chainMulti(t,e){const i={};for(const[n,r]of Object.entries(t))i[n]=r.chain(o=>e(n,o));return i}static attachAll(t,e){function i(n=0){if(n>=t.length){e(...t.map(r=>r.get()));return}t[n].attach(()=>{i(n+1);});}i();}static chainAll(t,e){const i=a.of(()=>e(...t.map(n=>n.get())));return this.attachAll(t,()=>i.ensureInitialized()),i}}class u{constructor(t){this.factory=t;}instances=new Map;attachments=[];static of(t){return new this(t)}get(t){const e=this.instances.get(t);if(e===s)throw new Error("Circular dependency detected during LazyKeyed value creation with value: "+t);if(e!==void 0)return e[0];this.instances.set(t,s);const i=this.factory(t);this.instances.set(t,[i]);for(const n of this.attachments)n(t,i);return i}reserve(t,...e){e.unshift(t);for(const i of e)this.instances.get(i)===void 0&&this.get(i);return this}attach(t){for(const[e,i]of this.instances.entries())i!==s&&t(e,i[0]);return this.attachments.push(t),this}attachOne(t,e){return this.attach((i,n)=>{i===t&&e(n);})}chain(t){const e=u.of(i=>t(i,this.get(i)));return this.attach(i=>{e.reserve(i);}),e}chainOne(t,e){const i=a.of(()=>e(this.get(t)));return this.attachOne(t,()=>i.ensureInitialized()),i}}export{a as Lazy,u as LazyKeyed};//# sourceMappingURL=lazy.js.map
 //# sourceMappingURL=lazy.js.map

package/dist/lazy.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/lazy.ts"],"names":["Lazy","factory","lazy"],"mappings":"AAMO,MAAMA,CAAQ,CAIZ,WAAA,CAAoBC,CAAAA,CAAkB,CAAlB,aAAAA,EAAmB,CAHvC,WAAA,CAAc,KAAA,CACd,KAAA,CAIR,OAAc,GAAMA,CAAAA,CAA2B,CAC9C,OAAO,IAAI,IAAA,CAAKA,CAAO,CACxB,CAOA,OAAc,IAAA,CAAQA,CAAAA,CAA2B,CAChD,MAAMC,EAAOF,CAAAA,CAAK,EAAA,CAAGC,CAAO,CAAA,CAC5B,OAAOC,CAAAA,CAAK,IAAI,IAAA,CAAKA,CAAI,CAC1B,CAEO,GAAA,EAAS,CACf,OAAK,IAAA,CAAK,WAAA,GACT,IAAA,CAAK,KAAA,CAAQ,IAAA,CAAK,OAAA,EAAQ,CAC1B,IAAA,CAAK,WAAA,CAAc,IAAA,CAAA,CAGb,IAAA,CAAK,KACb,CACD","file":"lazy.js","sourcesContent":["/**\n * A lazily computed memoized value.\n *\n * The given factory is only constructed on first use of the value.\n * Any subsequent use retrieves the same instance of the value.\n */\nexport class Lazy<T> {\n\tprivate initialized = false;\n\tprivate value?: T;\n\n\tprivate constructor(private factory: () => T) {}\n\n\tpublic static of<T>(factory: () => T): Lazy<T> {\n\t\treturn new this(factory);\n\t}\n\n\t/**\n\t * Wrap the given factory into a lazily computed memoized value.\n\t *\n\t * The function will at most be called once, on the first use of the value.\n\t */\n\tpublic static wrap<T>(factory: () => T): () => T {\n\t\tconst lazy = Lazy.of(factory);\n\t\treturn lazy.get.bind(lazy);\n\t}\n\n\tpublic get(): T {\n\t\tif (!this.initialized) {\n\t\t\tthis.value = this.factory();\n\t\t\tthis.initialized = true;\n\t\t}\n\n\t\treturn this.value!;\n\t}\n}\n"]}
+{"version":3,"sources":["../src/lazy.ts"],"names":["CREATING","MISSING","SPENT_FACTORY","Lazy","factory","lazy","value","attach","onfulfilled","onrejected","onfinally","mapper","other","lazies","name","result","attachNext","index","l","LazyKeyed","key","stored","newInstance","keys","k","instance","newKeyed"],"mappings":"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","file":"lazy.js","sourcesContent":["/**\n * Callback type for attaching side effects to lazy values with a name identifier.\n *\n * @template T - The type of the lazy value\n * @template O - The return type of the attachment callback (defaults to void)\n */\ntype LazyMapping<T, O = void> = (name: string, value: T) => O;\n\n/**\n * Utility type that extracts the inner types from an array of Lazy instances.\n *\n * @template T - A tuple of Lazy instances\n */\ntype UnwrapLazies<T extends Lazy<any>[]> = T extends [\n\tLazy<infer First>,\n\t...infer Rest extends Lazy<any>[],\n]\n\t? [First, ...UnwrapLazies<Rest>]\n\t: [];\n\n/** Symbol indicating a lazy value is currently being created (for circular dependency detection) */\nconst CREATING = Symbol('creating');\n/** Symbol indicating a lazy value has not yet been initialized */\nconst MISSING = Symbol('missing');\n\nconst SPENT_FACTORY = (): never => {\n\tthrow new Error('This Lazy value has already been consumed.');\n};\n\n/**\n * A lazily computed memoized value.\n *\n * The given factory is only constructed on first use of the value.\n * Any subsequent use retrieves the same instance of the value.\n *\n * If the value is accessed while it is being created, an error is thrown to prevent circular dependencies.\n * When that happens, the Lazy instance becomes unusable.\n *\n * Lazy implements the Promise interface, allowing it to be awaited directly.\n *\n * @template T - The type of the lazily computed value\n */\nexport class Lazy<T> implements Promise<T> {\n\tprivate value: T | typeof CREATING | typeof MISSING = MISSING;\n\n\tprivate attachments?: ((value: T) => void)[] = [];\n\n\tprivate constructor(private factory: () => T) {}\n\n\t/**\n\t * Creates a new Lazy instance from a factory function.\n\t *\n\t * @param factory - A function that produces the value when first accessed\n\t * @returns A new Lazy instance wrapping the factory\n\t */\n\tpublic static of<T>(factory: () => T): Lazy<T> {\n\t\treturn new Lazy(factory);\n\t}\n\n\t/**\n\t * Wrap the given factory into a lazily computed memoized value.\n\t *\n\t * The function will at most be called once, on the first use of the value.\n\t */\n\tpublic static wrap<T>(factory: () => T): () => T {\n\t\tconst lazy = Lazy.of(factory);\n\t\treturn lazy.get.bind(lazy);\n\t}\n\n\t/**\n\t * Gets the lazily computed value, creating it if necessary.\n\t *\n\t * @returns The computed value\n\t * @throws Error if a circular dependency is detected during value creation\n\t */\n\tpublic get(): T {\n\t\tif (this.value === MISSING) {\n\t\t\tthis.value = CREATING;\n\t\t\tconst value = this.factory();\n\t\t\t// Mark factory as spent to prevent reuse and release references to closure.\n\t\t\tthis.factory = SPENT_FACTORY;\n\t\t\tthis.value = value;\n\t\t\tfor (const attach of this.attachments!) {\n\t\t\t\tattach(value);\n\t\t\t}\n\t\t\tdelete this.attachments;\n\t\t}\n\t\tif (this.value === CREATING) {\n\t\t\tthrow new Error('Circular dependency detected during Lazy value creation.');\n\t\t}\n\n\t\treturn this.value;\n\t}\n\n\tpublic ensureInitialized(): void {\n\t\tif (this.value === CREATING) {\n\t\t\t// this Lazy is already being created; do nothing to avoid circular dependency\n\t\t\treturn;\n\t\t}\n\t\tthis.get();\n\t}\n\n\t/**\n\t * Implements Promise.then() for Promise compatibility.\n\t * Allows the Lazy instance to be awaited.\n\t */\n\tpublic then<TResult1 = T, TResult2 = never>(\n\t\tonfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,\n\t\tonrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined\n\t): Promise<TResult1 | TResult2> {\n\t\treturn Promise.resolve()\n\t\t\t.then(() => this.get())\n\t\t\t.then(onfulfilled, onrejected);\n\t}\n\n\t/**\n\t * Implements Promise.catch() for Promise compatibility.\n\t */\n\tpublic catch<TResult = never>(\n\t\tonrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined\n\t): Promise<T | TResult> {\n\t\treturn this.then(undefined, onrejected);\n\t}\n\n\t/**\n\t * Implements Promise.finally() for Promise compatibility.\n\t */\n\tpublic finally(onfinally?: (() => void) | null | undefined): Promise<T> {\n\t\treturn this.then().finally(onfinally);\n\t}\n\n\t/** String tag for Object.prototype.toString */\n\t[Symbol.toStringTag]: string = 'Lazy';\n\n\t/**\n\t * Registers a callback to be executed when, and if, the lazy value is computed.\n\t * If the value is already computed, the callback is invoked immediately.\n\t *\n\t * @param attach - Callback to execute with the computed value\n\t * @returns This instance for chaining\n\t */\n\tpublic attach(attach: (value: T) => void): this {\n\t\tif (this.value !== MISSING && this.value !== CREATING) {\n\t\t\tattach(this.value as T); // Force evaluation if already present\n\t\t} else {\n\t\t\tthis.attachments!.push(attach);\n\t\t}\n\t\treturn this;\n\t}\n\n\t/**\n\t * Creates a new Lazy that transforms this value using the provided function.\n\t * The new Lazy is automatically evaluated when this one is evaluated.\n\t * This way, if either Lazy is evaluated, both values are computed.\n\t *\n\t * @template O - The type of the transformed value\n\t * @param mapper - Transformation function to apply to the value\n\t * @returns A new Lazy instance containing the transformed value\n\t */\n\tpublic chain<O>(mapper: (value: T) => O): Lazy<O> {\n\t\tconst other = Lazy.of(() => mapper(this.get()));\n\n\t\tthis.attach(() => other.ensureInitialized());\n\n\t\treturn other;\n\t}\n\n\t/**\n\t * Attaches a callback to multiple named lazy values.\n\t * The callback receives both the name and value for each lazy when evaluated.\n\t *\n\t * @template T - The type of the lazy values\n\t * @param lazies - Record of named Lazy instances\n\t * @param attach - Callback to execute for each lazy value\n\t */\n\tpublic static attachMulti<T>(lazies: Record<string, Lazy<T>>, attach: LazyMapping<T>): void {\n\t\tfor (const [name, lazy] of Object.entries(lazies)) {\n\t\t\tlazy.attach((value) => attach(name, value));\n\t\t}\n\t}\n\n\t/**\n\t * Chains a transformation across multiple named lazy values.\n\t * Creates a new record of Lazy instances with transformed values.\n\t *\n\t * @template T - The type of the input lazy values\n\t * @template R - The record type containing the lazy instances\n\t * @template O - The type of the transformed values\n\t * @param lazies - Record of named Lazy instances\n\t * @param mapper - Transformation function receiving name and value\n\t * @returns A new record of Lazy instances with the same keys\n\t */\n\tpublic static chainMulti<T, const R extends Record<string, Lazy<T>>, O>(\n\t\tlazies: R,\n\t\tmapper: LazyMapping<T, O>\n\t): Record<keyof R, Lazy<O>> {\n\t\tconst result: Record<string, Lazy<O>> = {};\n\t\tfor (const [name, lazy] of Object.entries(lazies)) {\n\t\t\tresult[name] = lazy.chain((value) => mapper(name, value));\n\t\t}\n\n\t\treturn result as Record<keyof R, Lazy<O>>;\n\t}\n\n\t/**\n\t * Attaches a callback that is invoked when all lazy values in the array are evaluated.\n\t * The callback receives all values as arguments in order.\n\t *\n\t * @template Ts - Tuple type of Lazy instances\n\t * @param lazies - Array of Lazy instances to wait for\n\t * @param attach - Callback receiving all unwrapped values\n\t */\n\tpublic static attachAll<const Ts extends Lazy<any>[]>(\n\t\tlazies: Ts,\n\t\tattach: (...args: UnwrapLazies<Ts>) => void\n\t): void {\n\t\tfunction attachNext(index = 0) {\n\t\t\tif (index >= lazies.length) {\n\t\t\t\tattach(...(lazies.map((l) => l.get()) as UnwrapLazies<Ts>));\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tlazies[index].attach(() => {\n\t\t\t\tattachNext(index + 1);\n\t\t\t});\n\t\t}\n\n\t\tattachNext();\n\t}\n\n\t/**\n\t * Creates a new Lazy that combines all values from the given lazy instances.\n\t * The transformation is invoked when all input lazies are evaluated.\n\t *\n\t * @template Ts - Tuple type of Lazy instances\n\t * @template O - The type of the combined result\n\t * @param lazies - Array of Lazy instances to combine\n\t * @param mapper - Transformation function receiving all unwrapped values\n\t * @returns A new Lazy instance containing the combined result\n\t */\n\tpublic static chainAll<const Ts extends Lazy<any>[], O>(\n\t\tlazies: Ts,\n\t\tmapper: (...args: UnwrapLazies<Ts>) => O\n\t): Lazy<O> {\n\t\tconst lazy = Lazy.of(() => mapper(...(lazies.map((l) => l.get()) as UnwrapLazies<Ts>)));\n\n\t\tthis.attachAll(lazies, () => lazy.ensureInitialized());\n\n\t\treturn lazy;\n\t}\n}\n\n/**\n * A keyed lazy value store that memoizes values by string key.\n *\n * Each key maps to a lazily computed value that is only created on first access.\n * Supports attachments that are notified when new values are created.\n * @template T - The type of values stored\n */\nexport class LazyKeyed<T> {\n\t/** Map of key to either a tuple containing the value or CREATING symbol */\n\tprivate readonly instances = new Map<string, [T] | typeof CREATING>();\n\n\t/** List of callbacks to invoke when any value is created */\n\tprivate readonly attachments: LazyMapping<T>[] = [];\n\n\tprivate constructor(private factory: (key: string) => T) {}\n\n\t/**\n\t * Creates a new LazyKeyed instance from a factory function.\n\t * @param factory - A function that produces a value for a given key\n\t * @returns A new LazyKeyed instance\n\t */\n\tpublic static of<T>(factory: (key: string) => T): LazyKeyed<T> {\n\t\treturn new this(factory);\n\t}\n\n\t/**\n\t * Gets the value for the given key, creating it if necessary.\n\t * @param key - The key to look up or create\n\t * @returns The value associated with the key\n\t * @throws Error if a circular dependency is detected during value creation\n\t */\n\tpublic get(key: string): T {\n\t\tconst stored = this.instances.get(key);\n\n\t\tif (stored === CREATING) {\n\t\t\tthrow new Error(\n\t\t\t\t'Circular dependency detected during LazyKeyed value creation with value: ' + key\n\t\t\t);\n\t\t}\n\n\t\tif (stored !== undefined) {\n\t\t\treturn stored[0];\n\t\t}\n\n\t\tthis.instances.set(key, CREATING);\n\n\t\tconst newInstance = this.factory(key);\n\n\t\tthis.instances.set(key, [newInstance]);\n\n\t\tfor (const attach of this.attachments) {\n\t\t\tattach(key, newInstance);\n\t\t}\n\n\t\treturn newInstance;\n\t}\n\n\t/**\n\t * Pre-initializes values for the given keys.\n\t * Useful for eagerly creating values that will be needed later.\n\t * @param key - The first key to reserve\n\t * @param keys - Additional keys to reserve\n\t * @returns This instance for chaining\n\t */\n\tpublic reserve(key: string, ...keys: string[]): this {\n\t\tkeys.unshift(key);\n\t\tfor (const k of keys) {\n\t\t\tif (this.instances.get(k) === undefined) {\n\t\t\t\tthis.get(k);\n\t\t\t}\n\t\t}\n\t\treturn this;\n\t}\n\n\t/**\n\t * Registers a callback to be executed for each value when created.\n\t * Immediately invokes the callback for any already-created values.\n\t * @param attach - Callback receiving the key and value\n\t * @returns This instance for chaining\n\t */\n\tpublic attach(attach: LazyMapping<T>): this {\n\t\tfor (const [name, instance] of this.instances.entries()) {\n\t\t\tif (instance !== CREATING) {\n\t\t\t\tattach(name, instance[0]);\n\t\t\t}\n\t\t}\n\t\tthis.attachments.push(attach);\n\t\treturn this;\n\t}\n\n\t/**\n\t * Registers a callback for a specific key only.\n\t * The callback is invoked when the value for that key is created.\n\t * @param key - The key to watch\n\t * @param attach - Callback receiving the value\n\t * @returns This instance for chaining\n\t */\n\tpublic attachOne(key: string, attach: (value: T) => void): this {\n\t\treturn this.attach((name, value) => {\n\t\t\tif (name === key) {\n\t\t\t\tattach(value);\n\t\t\t}\n\t\t});\n\t}\n\n\t/**\n\t * Creates a new LazyKeyed that transforms values using the provided function.\n\t * Values in the new LazyKeyed are automatically created when source values are created.\n\t * @template O - The type of the transformed values\n\t * @param mapper - Transformation function receiving key and value\n\t * @returns A new LazyKeyed instance with transformed values\n\t */\n\tpublic chain<O>(mapper: LazyMapping<T, O>): LazyKeyed<O> {\n\t\tconst newKeyed = LazyKeyed.of((key) => mapper(key, this.get(key)));\n\n\t\tthis.attach((key) => {\n\t\t\tnewKeyed.reserve(key);\n\t\t});\n\n\t\treturn newKeyed;\n\t}\n\n\t/**\n\t * Creates a Lazy that transforms the value for a specific key.\n\t * The Lazy is automatically evaluated when the source value is created.\n\t * @template O - The type of the transformed value\n\t * @param key - The key to transform\n\t * @param mapper - Transformation function receiving the value\n\t * @returns A Lazy instance containing the transformed value\n\t */\n\tpublic chainOne<O>(key: string, mapper: (value: T) => O): Lazy<O> {\n\t\tconst lazy = Lazy.of(() => mapper(this.get(key)));\n\t\tthis.attachOne(key, () => lazy.ensureInitialized());\n\t\treturn lazy;\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inox-tools/utils",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A collection of utilities used throughout Inox Tools",
   "keywords": [
     "utilities"
@@ -22,18 +22,18 @@
   "devDependencies": {
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^24.0.15",
+    "@types/node": "^24.3.0",
     "@types/unist": "^3.0.3",
     "@types/xast": "^2.0.4",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
-    "astro": "^5.12.0",
+    "astro": "^5.13.3",
     "jest-extended": "^6.0.0",
     "mdast-util-from-markdown": "^2.0.2",
     "tsup": "8.5.0",
-    "typescript": "^5.8.3",
+    "typescript": "^5.9.2",
     "unist-util-is": "^6.0.0",
-    "vite": "^7.0.5",
+    "vite": "^7.1.3",
     "vitest": "^3.2.4"
   },
   "scripts": {

package/src/lazy.ts

@@ -1,17 +1,60 @@
+/**
+ * Callback type for attaching side effects to lazy values with a name identifier.
+ *
+ * @template T - The type of the lazy value
+ * @template O - The return type of the attachment callback (defaults to void)
+ */
+type LazyMapping<T, O = void> = (name: string, value: T) => O;
+
+/**
+ * Utility type that extracts the inner types from an array of Lazy instances.
+ *
+ * @template T - A tuple of Lazy instances
+ */
+type UnwrapLazies<T extends Lazy<any>[]> = T extends [
+	Lazy<infer First>,
+	...infer Rest extends Lazy<any>[],
+]
+	? [First, ...UnwrapLazies<Rest>]
+	: [];
+
+/** Symbol indicating a lazy value is currently being created (for circular dependency detection) */
+const CREATING = Symbol('creating');
+/** Symbol indicating a lazy value has not yet been initialized */
+const MISSING = Symbol('missing');
+
+const SPENT_FACTORY = (): never => {
+	throw new Error('This Lazy value has already been consumed.');
+};
+
 /**
  * A lazily computed memoized value.
  *
  * The given factory is only constructed on first use of the value.
  * Any subsequent use retrieves the same instance of the value.
+ *
+ * If the value is accessed while it is being created, an error is thrown to prevent circular dependencies.
+ * When that happens, the Lazy instance becomes unusable.
+ *
+ * Lazy implements the Promise interface, allowing it to be awaited directly.
+ *
+ * @template T - The type of the lazily computed value
  */
-export class Lazy<T> {
-	private initialized = false;
-	private value?: T;
+export class Lazy<T> implements Promise<T> {
+	private value: T | typeof CREATING | typeof MISSING = MISSING;
+
+	private attachments?: ((value: T) => void)[] = [];
 
 	private constructor(private factory: () => T) {}
 
+	/**
+	 * Creates a new Lazy instance from a factory function.
+	 *
+	 * @param factory - A function that produces the value when first accessed
+	 * @returns A new Lazy instance wrapping the factory
+	 */
 	public static of<T>(factory: () => T): Lazy<T> {
-		return new this(factory);
+		return new Lazy(factory);
 	}
 
 	/**
@@ -24,12 +67,322 @@ export class Lazy<T> {
 		return lazy.get.bind(lazy);
 	}
 
+	/**
+	 * Gets the lazily computed value, creating it if necessary.
+	 *
+	 * @returns The computed value
+	 * @throws Error if a circular dependency is detected during value creation
+	 */
 	public get(): T {
-		if (!this.initialized) {
-			this.value = this.factory();
-			this.initialized = true;
+		if (this.value === MISSING) {
+			this.value = CREATING;
+			const value = this.factory();
+			// Mark factory as spent to prevent reuse and release references to closure.
+			this.factory = SPENT_FACTORY;
+			this.value = value;
+			for (const attach of this.attachments!) {
+				attach(value);
+			}
+			delete this.attachments;
+		}
+		if (this.value === CREATING) {
+			throw new Error('Circular dependency detected during Lazy value creation.');
+		}
+
+		return this.value;
+	}
+
+	public ensureInitialized(): void {
+		if (this.value === CREATING) {
+			// this Lazy is already being created; do nothing to avoid circular dependency
+			return;
 		}
+		this.get();
+	}
+
+	/**
+	 * Implements Promise.then() for Promise compatibility.
+	 * Allows the Lazy instance to be awaited.
+	 */
+	public then<TResult1 = T, TResult2 = never>(
+		onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
+		onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined
+	): Promise<TResult1 | TResult2> {
+		return Promise.resolve()
+			.then(() => this.get())
+			.then(onfulfilled, onrejected);
+	}
 
-		return this.value!;
+	/**
+	 * Implements Promise.catch() for Promise compatibility.
+	 */
+	public catch<TResult = never>(
+		onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined
+	): Promise<T | TResult> {
+		return this.then(undefined, onrejected);
+	}
+
+	/**
+	 * Implements Promise.finally() for Promise compatibility.
+	 */
+	public finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+		return this.then().finally(onfinally);
+	}
+
+	/** String tag for Object.prototype.toString */
+	[Symbol.toStringTag]: string = 'Lazy';
+
+	/**
+	 * Registers a callback to be executed when, and if, the lazy value is computed.
+	 * If the value is already computed, the callback is invoked immediately.
+	 *
+	 * @param attach - Callback to execute with the computed value
+	 * @returns This instance for chaining
+	 */
+	public attach(attach: (value: T) => void): this {
+		if (this.value !== MISSING && this.value !== CREATING) {
+			attach(this.value as T); // Force evaluation if already present
+		} else {
+			this.attachments!.push(attach);
+		}
+		return this;
+	}
+
+	/**
+	 * Creates a new Lazy that transforms this value using the provided function.
+	 * The new Lazy is automatically evaluated when this one is evaluated.
+	 * This way, if either Lazy is evaluated, both values are computed.
+	 *
+	 * @template O - The type of the transformed value
+	 * @param mapper - Transformation function to apply to the value
+	 * @returns A new Lazy instance containing the transformed value
+	 */
+	public chain<O>(mapper: (value: T) => O): Lazy<O> {
+		const other = Lazy.of(() => mapper(this.get()));
+
+		this.attach(() => other.ensureInitialized());
+
+		return other;
+	}
+
+	/**
+	 * Attaches a callback to multiple named lazy values.
+	 * The callback receives both the name and value for each lazy when evaluated.
+	 *
+	 * @template T - The type of the lazy values
+	 * @param lazies - Record of named Lazy instances
+	 * @param attach - Callback to execute for each lazy value
+	 */
+	public static attachMulti<T>(lazies: Record<string, Lazy<T>>, attach: LazyMapping<T>): void {
+		for (const [name, lazy] of Object.entries(lazies)) {
+			lazy.attach((value) => attach(name, value));
+		}
+	}
+
+	/**
+	 * Chains a transformation across multiple named lazy values.
+	 * Creates a new record of Lazy instances with transformed values.
+	 *
+	 * @template T - The type of the input lazy values
+	 * @template R - The record type containing the lazy instances
+	 * @template O - The type of the transformed values
+	 * @param lazies - Record of named Lazy instances
+	 * @param mapper - Transformation function receiving name and value
+	 * @returns A new record of Lazy instances with the same keys
+	 */
+	public static chainMulti<T, const R extends Record<string, Lazy<T>>, O>(
+		lazies: R,
+		mapper: LazyMapping<T, O>
+	): Record<keyof R, Lazy<O>> {
+		const result: Record<string, Lazy<O>> = {};
+		for (const [name, lazy] of Object.entries(lazies)) {
+			result[name] = lazy.chain((value) => mapper(name, value));
+		}
+
+		return result as Record<keyof R, Lazy<O>>;
+	}
+
+	/**
+	 * Attaches a callback that is invoked when all lazy values in the array are evaluated.
+	 * The callback receives all values as arguments in order.
+	 *
+	 * @template Ts - Tuple type of Lazy instances
+	 * @param lazies - Array of Lazy instances to wait for
+	 * @param attach - Callback receiving all unwrapped values
+	 */
+	public static attachAll<const Ts extends Lazy<any>[]>(
+		lazies: Ts,
+		attach: (...args: UnwrapLazies<Ts>) => void
+	): void {
+		function attachNext(index = 0) {
+			if (index >= lazies.length) {
+				attach(...(lazies.map((l) => l.get()) as UnwrapLazies<Ts>));
+				return;
+			}
+
+			lazies[index].attach(() => {
+				attachNext(index + 1);
+			});
+		}
+
+		attachNext();
+	}
+
+	/**
+	 * Creates a new Lazy that combines all values from the given lazy instances.
+	 * The transformation is invoked when all input lazies are evaluated.
+	 *
+	 * @template Ts - Tuple type of Lazy instances
+	 * @template O - The type of the combined result
+	 * @param lazies - Array of Lazy instances to combine
+	 * @param mapper - Transformation function receiving all unwrapped values
+	 * @returns A new Lazy instance containing the combined result
+	 */
+	public static chainAll<const Ts extends Lazy<any>[], O>(
+		lazies: Ts,
+		mapper: (...args: UnwrapLazies<Ts>) => O
+	): Lazy<O> {
+		const lazy = Lazy.of(() => mapper(...(lazies.map((l) => l.get()) as UnwrapLazies<Ts>)));
+
+		this.attachAll(lazies, () => lazy.ensureInitialized());
+
+		return lazy;
+	}
+}
+
+/**
+ * A keyed lazy value store that memoizes values by string key.
+ *
+ * Each key maps to a lazily computed value that is only created on first access.
+ * Supports attachments that are notified when new values are created.
+ * @template T - The type of values stored
+ */
+export class LazyKeyed<T> {
+	/** Map of key to either a tuple containing the value or CREATING symbol */
+	private readonly instances = new Map<string, [T] | typeof CREATING>();
+
+	/** List of callbacks to invoke when any value is created */
+	private readonly attachments: LazyMapping<T>[] = [];
+
+	private constructor(private factory: (key: string) => T) {}
+
+	/**
+	 * Creates a new LazyKeyed instance from a factory function.
+	 * @param factory - A function that produces a value for a given key
+	 * @returns A new LazyKeyed instance
+	 */
+	public static of<T>(factory: (key: string) => T): LazyKeyed<T> {
+		return new this(factory);
+	}
+
+	/**
+	 * Gets the value for the given key, creating it if necessary.
+	 * @param key - The key to look up or create
+	 * @returns The value associated with the key
+	 * @throws Error if a circular dependency is detected during value creation
+	 */
+	public get(key: string): T {
+		const stored = this.instances.get(key);
+
+		if (stored === CREATING) {
+			throw new Error(
+				'Circular dependency detected during LazyKeyed value creation with value: ' + key
+			);
+		}
+
+		if (stored !== undefined) {
+			return stored[0];
+		}
+
+		this.instances.set(key, CREATING);
+
+		const newInstance = this.factory(key);
+
+		this.instances.set(key, [newInstance]);
+
+		for (const attach of this.attachments) {
+			attach(key, newInstance);
+		}
+
+		return newInstance;
+	}
+
+	/**
+	 * Pre-initializes values for the given keys.
+	 * Useful for eagerly creating values that will be needed later.
+	 * @param key - The first key to reserve
+	 * @param keys - Additional keys to reserve
+	 * @returns This instance for chaining
+	 */
+	public reserve(key: string, ...keys: string[]): this {
+		keys.unshift(key);
+		for (const k of keys) {
+			if (this.instances.get(k) === undefined) {
+				this.get(k);
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * Registers a callback to be executed for each value when created.
+	 * Immediately invokes the callback for any already-created values.
+	 * @param attach - Callback receiving the key and value
+	 * @returns This instance for chaining
+	 */
+	public attach(attach: LazyMapping<T>): this {
+		for (const [name, instance] of this.instances.entries()) {
+			if (instance !== CREATING) {
+				attach(name, instance[0]);
+			}
+		}
+		this.attachments.push(attach);
+		return this;
+	}
+
+	/**
+	 * Registers a callback for a specific key only.
+	 * The callback is invoked when the value for that key is created.
+	 * @param key - The key to watch
+	 * @param attach - Callback receiving the value
+	 * @returns This instance for chaining
+	 */
+	public attachOne(key: string, attach: (value: T) => void): this {
+		return this.attach((name, value) => {
+			if (name === key) {
+				attach(value);
+			}
+		});
+	}
+
+	/**
+	 * Creates a new LazyKeyed that transforms values using the provided function.
+	 * Values in the new LazyKeyed are automatically created when source values are created.
+	 * @template O - The type of the transformed values
+	 * @param mapper - Transformation function receiving key and value
+	 * @returns A new LazyKeyed instance with transformed values
+	 */
+	public chain<O>(mapper: LazyMapping<T, O>): LazyKeyed<O> {
+		const newKeyed = LazyKeyed.of((key) => mapper(key, this.get(key)));
+
+		this.attach((key) => {
+			newKeyed.reserve(key);
+		});
+
+		return newKeyed;
+	}
+
+	/**
+	 * Creates a Lazy that transforms the value for a specific key.
+	 * The Lazy is automatically evaluated when the source value is created.
+	 * @template O - The type of the transformed value
+	 * @param key - The key to transform
+	 * @param mapper - Transformation function receiving the value
+	 * @returns A Lazy instance containing the transformed value
+	 */
+	public chainOne<O>(key: string, mapper: (value: T) => O): Lazy<O> {
+		const lazy = Lazy.of(() => mapper(this.get(key)));
+		this.attachOne(key, () => lazy.ensureInitialized());
+		return lazy;
 	}
 }