@adviser/cement 0.4.61 → 0.4.63

package/src/resolve-once.ts

@@ -1,3 +1,19 @@
+/**
+ * Utilities for executing functions once and caching results, with support for both
+ * synchronous and asynchronous operations, sequential execution, and keyed collections.
+ *
+ * ## Main Classes
+ *
+ * - **ResolveOnce**: Ensures a function executes only once, automatically handling sync/async
+ * - **ResolveSeq**: Executes functions sequentially, maintaining order even with concurrent calls
+ * - **Keyed**: Base class for managing keyed instances with LRU caching
+ * - **KeyedResolveOnce**: Map of ResolveOnce instances indexed by keys
+ * - **KeyedResolveSeq**: Map of ResolveSeq instances indexed by keys
+ * - **Lazy**: Function wrapper that executes once and caches the result
+ *
+ * @module resolve-once
+ */
+
 import { Future } from "./future.js";
 import { UnPromisify } from "./is-promise.js";
 import { isPromise } from "./is-promise.js";
@@ -5,13 +21,39 @@ import { LRUMap, LRUParam, UnregFn } from "./lru-map-set.js";
 import { Result } from "./result.js";
 import { Option } from "./option.js";
 
-// interface ResolveSeqItem<C, R extends NonPromise<X>, X = string | number | boolean | symbol | object> {
+/**
+ * Internal item representing a queued function in a ResolveSeq sequence.
+ * @internal
+ */
 interface ResolveSeqItem<C, T, R> {
   readonly future: Future<T>;
   readonly fn: (c: C) => R;
   readonly id?: number;
 }
 
+/**
+ * Executes functions sequentially, one at a time, ensuring order of execution.
+ *
+ * ResolveSeq maintains a queue of functions and executes them in order, waiting for each
+ * to complete before starting the next. This is useful when you need to ensure operations
+ * happen in a specific sequence, even when multiple operations are queued concurrently.
+ *
+ * @template T - The return type of the functions
+ * @template CTX - Optional context type passed to each function
+ *
+ * @example
+ * ```typescript
+ * const seq = new ResolveSeq<number>();
+ *
+ * // Multiple calls are queued and executed in order
+ * const p1 = seq.add(() => asyncOperation1());
+ * const p2 = seq.add(() => asyncOperation2());
+ * const p3 = seq.add(() => asyncOperation3());
+ *
+ * // Operations execute sequentially: op1 -> op2 -> op3
+ * await Promise.all([p1, p2, p3]);
+ * ```
+ */
 export class ResolveSeq<T, CTX extends NonNullable<object> = object> {
   readonly ctx?: CTX;
   readonly _seqFutures: ResolveSeqItem<CTX, T, unknown>[] = [];
@@ -19,11 +61,21 @@ export class ResolveSeq<T, CTX extends NonNullable<object> = object> {
   constructor(ctx?: CTX) {
     this.ctx = ctx;
   }
+
+  /**
+   * Resets the sequence (currently a no-op).
+   */
   reset(): void {
     /* noop */
   }
 
   readonly _flushWaiting: Future<void>[] = [];
+
+  /**
+   * Returns a promise that resolves when all currently queued items complete.
+   *
+   * @returns A promise that resolves when the queue is empty
+   */
   flush(): Promise<void> {
     if (this._seqFutures.length > 0) {
       const waitForFlush = new Future<void>();
@@ -32,6 +84,11 @@ export class ResolveSeq<T, CTX extends NonNullable<object> = object> {
     }
     return Promise.resolve();
   }
+
+  /**
+   * Internal method to process items in the queue sequentially.
+   * @internal
+   */
   async _step(item?: ResolveSeqItem<CTX, T, Promise<T> | T>): Promise<void> {
     if (!item) {
       // done
@@ -55,6 +112,17 @@ export class ResolveSeq<T, CTX extends NonNullable<object> = object> {
     }
     return this._step(this._seqFutures[0] as ResolveSeqItem<CTX, T, Promise<T> | T>);
   }
+
+  /**
+   * Adds a function to the sequence queue for sequential execution.
+   *
+   * The function will be executed after all previously queued functions complete.
+   * Returns a promise that resolves with the function's result.
+   *
+   * @param fn - The function to execute
+   * @param id - Optional identifier for tracking
+   * @returns A promise that resolves with the function's result
+   */
   add<R extends Promise<T> | T>(fn: (c: CTX) => R, id?: number): R {
     const future = new Future<T>();
     this._seqFutures.push({ future, fn, id });
@@ -65,22 +133,33 @@ export class ResolveSeq<T, CTX extends NonNullable<object> = object> {
   }
 }
 
-// readonly _onceFutures: Future<T>[] = [];
-// _onceDone = false;
-// _onceOk = false;
-// _onceValue?: T;
-// _onceError?: Error;
-// _isPromise = false;
-// _inProgress?: Future<T>;
-
-// ResolveOnce
-// cases SyncMode, AsyncMode
-
+/**
+ * Represents the current state of a resolve operation.
+ * - `initial`: Not yet started
+ * - `processed`: Completed
+ * - `waiting`: Waiting for async operation
+ * - `processing`: Currently executing
+ */
 type ResolveState = "initial" | "processed" | "waiting" | "processing";
 
-// export type VoidEqualUndefined<T> = T extends undefined ? void : T
+/**
+ * Type helper that unwraps Promise types to their resolved value type.
+ *
+ * @template R - The type to unwrap
+ *
+ * @example
+ * ```typescript
+ * type A = ResultOnce<Promise<number>>; // Promise<number>
+ * type B = ResultOnce<string>;          // string
+ * ```
+ */
 export type ResultOnce<R> = R extends Promise<infer T> ? Promise<T> : R;
 
+/**
+ * Interface defining the contract for ResolveOnce-like objects.
+ * @template R - The return type
+ * @template CTX - Optional context type
+ */
 export interface ResolveOnceIf<R, CTX = void> {
   get ready(): boolean;
   get value(): UnPromisify<R> | undefined;
@@ -91,6 +170,16 @@ export interface ResolveOnceIf<R, CTX = void> {
   reset<R>(fn?: (c?: CTX) => R): ResultOnce<R>;
 }
 
+/**
+ * Synchronous version of ResolveOnce for functions that return non-promise values.
+ *
+ * This class is used internally by ResolveOnce when it detects a synchronous function.
+ * It executes the function once and caches the result or error for subsequent calls.
+ *
+ * @template T - The return type
+ * @template CTX - Optional context type
+ * @internal
+ */
 export class SyncResolveOnce<T, CTX = void> {
   state: ResolveState = "initial";
 
@@ -99,14 +188,23 @@ export class SyncResolveOnce<T, CTX = void> {
 
   readonly queueLength = 0;
 
+  /**
+   * Gets the cached value if available.
+   */
   get value(): T | undefined {
     return this.#value;
   }
 
+  /**
+   * Gets the cached error if one occurred.
+   */
   get error(): Error | undefined {
     return this.#error;
   }
 
+  /**
+   * Returns true if the function has been executed.
+   */
   get ready(): boolean {
     return this.state === "processed";
   }
@@ -116,6 +214,14 @@ export class SyncResolveOnce<T, CTX = void> {
     this.#ctx = ctx;
   }
 
+  /**
+   * Executes the function once and caches the result.
+   * Subsequent calls return the cached value without re-executing.
+   *
+   * @param fn - The function to execute
+   * @returns The result of the function
+   * @throws Error if the function returned a promise (use AsyncResolveOnce instead)
+   */
   resolve(fn: (ctx?: CTX) => T): T {
     if (this.state === "initial") {
       this.state = "processed";
@@ -134,6 +240,12 @@ export class SyncResolveOnce<T, CTX = void> {
     return this.#value as T;
   }
 
+  /**
+   * Resets the cached state, allowing the function to be executed again.
+   *
+   * @param fn - Optional function to execute immediately after reset
+   * @returns The result if fn provided, undefined otherwise
+   */
   reset(fn?: (c?: CTX) => T): T | undefined {
     this.state = "initial";
     this.#value = undefined;
@@ -145,6 +257,11 @@ export class SyncResolveOnce<T, CTX = void> {
   }
 }
 
+/**
+ * Internal helper for AsyncResolveOnce that manages a single async resolution.
+ * Handles queuing of multiple concurrent requests for the same async operation.
+ * @internal
+ */
 class AsyncResolveItem<T> {
   readonly id = Math.random();
   #state: ResolveState = "initial";
@@ -170,6 +287,9 @@ class AsyncResolveItem<T> {
     return this.#queue.length;
   }
 
+  /**
+   * Returns true if this item has completed and has no pending futures.
+   */
   isDisposable(): boolean {
     return this.#state === "processed" && this.#queue.length === 0;
   }
@@ -197,11 +317,13 @@ class AsyncResolveItem<T> {
     throw new Error("AsyncResolveItem.#promiseResult impossible");
   }
 
+  /**
+   * Resolves the async operation, queuing the request if already in progress.
+   */
   resolve(): T {
     if (this.#state === "initial") {
       this.#state = "waiting";
       const future = new Future<UnPromisify<T>>();
-      // console.log("asyncItem addQueue#initial", this.id, this.#queue.length);
       this.#queue.push(future);
       this.#toResolve
         .then((value) => {
@@ -223,7 +345,6 @@ class AsyncResolveItem<T> {
     }
     if (this.#state === "waiting") {
       const future = new Future<UnPromisify<T>>();
-      // console.log("asyncItem addQueue#waiting", this.id, this.#queue.length);
       this.#queue.push(future);
       return future.asPromise() as T;
     }
@@ -231,8 +352,18 @@ class AsyncResolveItem<T> {
   }
 }
 
+/**
+ * Asynchronous version of ResolveOnce for functions that return promises.
+ *
+ * This class is used internally by ResolveOnce when it detects an async function.
+ * It executes the async function once and caches the result for subsequent calls.
+ * Multiple concurrent calls while waiting will all receive the same promise result.
+ *
+ * @template T - The return type (Promise or value)
+ * @template CTX - Optional context type
+ * @internal
+ */
 export class AsyncResolveOnce<T, CTX = void> {
-  // readonly id = Math.random();
   state: ResolveState = "initial";
 
   readonly #queue: AsyncResolveItem<T>[] = [];
@@ -250,13 +381,23 @@ export class AsyncResolveOnce<T, CTX = void> {
     return r;
   }
 
+  /**
+   * Returns the total number of queued futures across all items.
+   */
   get queueLength(): number {
     return this.#queue.reduce((acc, r) => acc + r.queuelength, this.#queue.length);
   }
 
+  /**
+   * Returns true if the async operation has started.
+   */
   get ready(): boolean {
     return this.state !== "initial";
   }
+
+  /**
+   * Gets the cached resolved value if available.
+   */
   get value(): UnPromisify<T> | undefined {
     if (this.state === "initial") {
       return undefined;
@@ -264,6 +405,9 @@ export class AsyncResolveOnce<T, CTX = void> {
     return this.#active().value;
   }
 
+  /**
+   * Gets the cached error if one occurred.
+   */
   get error(): Error | undefined {
     if (this.state === "initial") {
       return undefined;
@@ -271,6 +415,13 @@ export class AsyncResolveOnce<T, CTX = void> {
     return this.#active().error;
   }
 
+  /**
+   * Executes the async function once and caches the result.
+   * Subsequent calls return the cached promise without re-executing.
+   *
+   * @param fn - The async function to execute
+   * @returns A promise that resolves to the function's result
+   */
   resolve(fn: (ctx?: CTX) => T): T {
     if (this.state === "initial") {
       this.state = "waiting";
@@ -285,7 +436,6 @@ export class AsyncResolveOnce<T, CTX = void> {
       } catch (e) {
         promiseResult = Promise.reject(e as Error);
       }
-      // console.log("asyncOnce addQueue#initial", this.id, this.#queue.length);
       this.#queue.push(new AsyncResolveItem(promiseResult));
     }
     // remove all disposable items
@@ -299,6 +449,12 @@ export class AsyncResolveOnce<T, CTX = void> {
     return this.#active().resolve();
   }
 
+  /**
+   * Resets the cached state, allowing the function to be executed again.
+   *
+   * @param fn - Optional function to execute immediately after reset
+   * @returns The result if fn provided, undefined otherwise
+   */
   reset(fn?: (c?: CTX) => T): T {
     this.state = "initial";
     if (fn) {
@@ -308,6 +464,30 @@ export class AsyncResolveOnce<T, CTX = void> {
   }
 }
 
+/**
+ * Ensures a function is executed only once, caching and returning the result for subsequent calls.
+ *
+ * ResolveOnce automatically detects whether the function returns a synchronous value or a Promise,
+ * and handles both cases appropriately. All subsequent calls will receive the same cached result.
+ * Supports optional context parameter and can be reset to allow re-execution.
+ *
+ * @template T - The return type of the function (can be synchronous or Promise)
+ * @template CTX - Optional context type passed to the function
+ *
+ * @example
+ * ```typescript
+ * const expensiveOp = new ResolveOnce<number>();
+ *
+ * // First call executes the function
+ * const result1 = expensiveOp.once(() => computeExpensiveValue());
+ *
+ * // Subsequent calls return cached result
+ * const result2 = expensiveOp.once(() => computeExpensiveValue()); // Not executed
+ *
+ * // Reset to allow re-execution
+ * expensiveOp.reset();
+ * ```
+ */
 export class ResolveOnce<T, CTX = void> implements ResolveOnceIf<T, CTX> {
   #state: ResolveState = "initial";
 
@@ -393,15 +573,142 @@ export class ResolveOnce<T, CTX = void> implements ResolveOnceIf<T, CTX> {
   }
 }
 
+/**
+ * Configuration parameters for Keyed instances.
+ * @template K - The key type
+ * @template V - The value type
+ */
 export interface KeyedParam<K, V> {
   readonly lru: Partial<LRUParam<V, K>>;
 }
 
+/**
+ * Extended configuration that includes context.
+ * @template K - The key type
+ * @template V - The value type
+ * @template CTX - The context type
+ */
 export type AddKeyedParam<K, V, CTX extends NonNullable<object>> = KeyedParam<K, V> & { readonly ctx: CTX };
 
-export class Keyed<T extends { reset: () => void }, K = string, CTX extends NonNullable<object> = object> {
+export interface KeyedIf<T extends { reset: () => void }, K = string> {
+  /**
+   * Registers a callback that fires when a new entry is added to the map.
+   *
+   * @param fn - Callback function receiving key and value
+   * @returns Unregister function to remove the callback
+   */
+  onSet(fn: (key: K, value: T) => void): UnregFn;
+
+  /**
+   * Registers a callback that fires when an entry is deleted from the map.
+   *
+   * @param fn - Callback function receiving key and value
+   * @returns Unregister function to remove the callback
+   */
+  onDelete(fn: (key: K, value: T) => void): UnregFn;
+
+  /**
+   * Updates the LRU parameters of the underlying map.
+   *
+   * @param params - New parameters to apply
+   */
+  setParam(params: KeyedParam<K, T>): void;
+
+  /**
+   * Async variant of get() that accepts a function returning a promise for the key.
+   *
+   * @param key - Function that returns a promise resolving to the key
+   * @returns Promise resolving to the value
+   */
+  asyncGet(key: () => Promise<K>): Promise<T>;
+
+  /**
+   * Gets or creates a value for the given key.
+   *
+   * If the key doesn't exist, creates a new instance using the factory function.
+   *
+   * @param key - The key or function returning the key
+   * @returns The value associated with the key
+   */
+  get(key: K | (() => K)): T;
+
+  /**
+   * Checks if a key exists in the map.
+   *
+   * @param key - The key or function returning the key
+   * @returns True if the key exists
+   */
+  has(key: K | (() => K)): boolean;
+
+  /**
+   * Deletes an entry from the map.
+   *
+   * @param key - The key to delete
+   */
+  delete(key: K): void;
+
+  /**
+   * Resets and deletes an entry from the map.
+   *
+   * Calls the value's reset() method before removing it.
+   *
+   * @param key - The key to reset and delete
+   */
+  unget(key: K): void;
+
+  /**
+   * Resets all entries and clears the map.
+   *
+   * Calls reset() on all values before clearing.
+   */
+  reset(): void;
+
+  /**
+   * Returns all values in the map.
+   *
+   * @returns Array of all values
+   */
+  values(): T[];
+
+  /**
+   * Returns all keys in the map.
+   *
+   * @returns Array of all keys
+   */
+  keys(): K[];
+
+  /**
+   * Iterates over all entries in the map.
+   *
+   * @yields Key-value pairs
+   */
+  forEach(fn: (k: K, v: T, idx: number) => void): void;
+
+  entries(): Iterable<[K, T]>;
+}
+
+/**
+ * Base class for managing keyed instances with LRU caching.
+ *
+ * Keyed provides a map-like interface where values are lazily created via a factory function
+ * and cached with optional LRU eviction. Values must have a `reset()` method for cleanup.
+ *
+ * @template T - The value type (must have a reset method)
+ * @template K - The key type
+ * @template CTX - Optional context type passed to the factory
+ *
+ * @example
+ * ```typescript
+ * const keyed = new Keyed(
+ *   (ctx) => new ResolveOnce(ctx),
+ *   { lru: { maxEntries: 100 } }
+ * );
+ *
+ * const instance = keyed.get('myKey');
+ * ```
+ */
+export class Keyed<T extends { reset: () => void }, K = string, CTX extends NonNullable<object> = object> implements KeyedIf<T, K> {
   protected readonly _map: LRUMap<K, T>;
-  // #lock = new ResolveSeq<T, K>();
   readonly #ctx: CTX;
 
   readonly factory: (ctx: AddKey<CTX, K>) => T;
@@ -412,22 +719,53 @@ export class Keyed<T extends { reset: () => void }, K = string, CTX extends NonN
     this._map = new LRUMap<K, T>(ctx?.lru ?? ({ maxEntries: -1 } as LRUParam<T, K>));
   }
 
+  /**
+   * Registers a callback that fires when a new entry is added to the map.
+   *
+   * @param fn - Callback function receiving key and value
+   * @returns Unregister function to remove the callback
+   */
   onSet(fn: (key: K, value: T) => void): UnregFn {
     return this._map.onSet(fn);
   }
 
+  /**
+   * Registers a callback that fires when an entry is deleted from the map.
+   *
+   * @param fn - Callback function receiving key and value
+   * @returns Unregister function to remove the callback
+   */
   onDelete(fn: (key: K, value: T) => void): UnregFn {
     return this._map.onDelete(fn);
   }
 
+  /**
+   * Updates the LRU parameters of the underlying map.
+   *
+   * @param params - New parameters to apply
+   */
   setParam(params: KeyedParam<K, T>): void {
     this._map.setParam(params.lru);
   }
 
+  /**
+   * Async variant of get() that accepts a function returning a promise for the key.
+   *
+   * @param key - Function that returns a promise resolving to the key
+   * @returns Promise resolving to the value
+   */
   async asyncGet(key: () => Promise<K>): Promise<T> {
     return this.get(await key());
   }
 
+  /**
+   * Gets or creates a value for the given key.
+   *
+   * If the key doesn't exist, creates a new instance using the factory function.
+   *
+   * @param key - The key or function returning the key
+   * @returns The value associated with the key
+   */
   get(key: K | (() => K)): T {
     if (typeof key === "function") {
       key = (key as () => K)();
@@ -440,6 +778,12 @@ export class Keyed<T extends { reset: () => void }, K = string, CTX extends NonN
     return keyed;
   }
 
+  /**
+   * Checks if a key exists in the map.
+   *
+   * @param key - The key or function returning the key
+   * @returns True if the key exists
+   */
   has(key: K | (() => K)): boolean {
     if (typeof key === "function") {
       key = (key as () => K)();
@@ -447,66 +791,243 @@ export class Keyed<T extends { reset: () => void }, K = string, CTX extends NonN
     return this._map.has(key);
   }
 
-  // lock<R extends Promisable<T>>(fn: (map: LRUMap<K, T>) => R): Promise<UnPromisify<R>>  {
-  //   return this.#lock.add(() => fn(this._map));
-  // }
-
+  /**
+   * Deletes an entry from the map.
+   *
+   * @param key - The key to delete
+   */
   delete(key: K): void {
     this._map.delete(key);
   }
 
+  /**
+   * Resets and deletes an entry from the map.
+   *
+   * Calls the value's reset() method before removing it.
+   *
+   * @param key - The key to reset and delete
+   */
   unget(key: K): void {
     const keyed = this._map.get(key);
     keyed?.reset();
     this._map.delete(key);
   }
 
+  /**
+   * Resets all entries and clears the map.
+   *
+   * Calls reset() on all values before clearing.
+   */
   reset(): void {
     this._map.forEach((keyed) => keyed.reset());
     this._map.clear();
   }
+
+  /**
+   * Returns all values in the map.
+   *
+   * @returns Array of all values
+   */
+  values(): T[] {
+    const results: T[] = [];
+    this.forEach((_, v) => {
+      results.push(v);
+    });
+    return results;
+  }
+
+  /**
+   * Returns all keys in the map.
+   *
+   * @returns Array of all keys
+   */
+  keys(): K[] {
+    const results: K[] = [];
+    this.forEach((k) => {
+      results.push(k);
+    });
+    return results;
+  }
+
+  /**
+   * Iterates over all entries in the map.
+   *
+   * @yields Key-value pairs
+   */
+  forEach(fn: (k: K, v: T, idx: number) => void): void {
+    let idx = 0;
+    for (const [k, v] of this._map.entries()) {
+      fn(k, v, idx++);
+    }
+  }
+
+  *entries(): Iterable<[K, T]> {
+    for (const [k, v] of this._map.entries()) {
+      yield [k, v];
+    }
+  }
 }
 
+/**
+ * Represents a key-value pair where the value is wrapped in a Result.
+ * @template K - The key type
+ * @template V - The value type
+ */
 export interface KeyItem<K, V> {
   readonly key: K;
   readonly value: Result<V>;
 }
 
-export class KeyedResolvOnce<T, K = string, CTX extends NonNullable<object> = object> extends Keyed<
-  ResolveOnce<T, AddKey<CTX, K>>,
-  K,
-  CTX
-> {
+/**
+ * Keyed collection of ResolveOnce instances.
+ *
+ * Manages a map of ResolveOnce instances indexed by keys, with optional LRU caching.
+ * Each key gets its own ResolveOnce instance that can be accessed and manipulated independently.
+ *
+ * @template T - The return type of the ResolveOnce instances
+ * @template K - The key type
+ * @template CTX - Optional context type
+ *
+ * @example
+ * ```typescript
+ * const cache = new KeyedResolvOnce<number, string>();
+ *
+ * // Each key gets its own ResolveOnce
+ * const result1 = cache.get('key1').once(() => expensiveCalc1());
+ * const result2 = cache.get('key2').once(() => expensiveCalc2());
+ * ```
+ */
+export class KeyedResolvOnce<T, K = string, CTX extends NonNullable<object> = object>
+  implements Omit<KeyedIf<ResolveOnce<T, AddKey<CTX, K>>, K>, "forEach" | "keys" | "values" | "entries">
+{
+  readonly _keyed: KeyedIf<ResolveOnce<T, AddKey<CTX, K>>, K>;
   constructor(kp: Partial<AddKeyedParam<K, ResolveOnce<T, CTX>, CTX>> = {}) {
-    // need the upcast we add to ResolvOnce CTX the Key
-    super((ctx) => new ResolveOnce<T, AddKey<CTX, K>>(ctx), kp as AddKeyedParam<K, ResolveOnce<T, AddKey<CTX, K>>, CTX>);
+    this._keyed = new Keyed(
+      (ctx) => new ResolveOnce<T, AddKey<CTX, K>>(ctx),
+      kp as AddKeyedParam<K, ResolveOnce<T, AddKey<CTX, K>>, CTX>,
+    );
+  }
+  keys(): K[] {
+    const results: K[] = [];
+    this.forEach((k) => {
+      results.push(k.key);
+    });
+    return results;
+  }
+  values(): KeyItem<K, T>[] {
+    const results: KeyItem<K, T>[] = [];
+    this.forEach((v) => {
+      results.push(v);
+    });
+    return results;
+  }
+  onSet(fn: (key: K, value: ResolveOnce<T, AddKey<CTX, K>>) => void): UnregFn {
+    return this._keyed.onSet(fn);
+  }
+  onDelete(fn: (key: K, value: ResolveOnce<T, AddKey<CTX, K>>) => void): UnregFn {
+    return this._keyed.onDelete(fn);
+  }
+  setParam(params: KeyedParam<K, ResolveOnce<T, AddKey<CTX, K>>>): void {
+    this._keyed.setParam(params);
+  }
+  asyncGet(key: () => Promise<K>): Promise<ResolveOnce<T, AddKey<CTX, K>>> {
+    return this._keyed.asyncGet(key);
+  }
+  get(key: K | (() => K)): ResolveOnce<T, AddKey<CTX, K>> {
+    return this._keyed.get(key);
+  }
+  has(key: K | (() => K)): boolean {
+    return this._keyed.has(key);
+  }
+  delete(key: K): void {
+    this._keyed.delete(key);
+  }
+  unget(key: K): void {
+    this._keyed.unget(key);
+  }
+  reset(): void {
+    this._keyed.reset();
   }
 
-  *entries(): IterableIterator<KeyItem<K, T>> {
-    for (const [k, v] of this._map.entries()) {
+  /**
+   * Iterates over all completed entries, yielding key-result pairs.
+   *
+   * Only yields entries that have been resolved (ready state).
+   * Values are wrapped in Result to distinguish success from error.
+   *
+   * @yields Key-result pairs for completed entries
+   */
+  forEach(fn: (ki: KeyItem<K, T>, idx: number) => void): void {
+    let idx = 0;
+    for (const [k, v] of this._keyed.entries()) {
       if (!v.ready) {
         continue;
       }
       if (v.error) {
-        yield { key: k, value: Result.Err<T>(v.error) };
+        fn({ key: k, value: Result.Err<T>(v.error) }, idx++);
       } else {
-        yield { key: k, value: Result.Ok<T>(v.value as T) };
+        fn({ key: k, value: Result.Ok<T>(v.value as T) }, idx++);
       }
     }
   }
 
-  /**
-   *
-   * @returns The values of the resolved keys
-   */
-  values(): KeyItem<K, T>[] {
-    return Array.from(this.entries());
+  *entries(): Iterable<KeyItem<K, T>> {
+    /* this is not optimal, but sufficient for now */
+    for (const [k, v] of this._keyed.entries()) {
+      if (!v.ready) {
+        continue;
+      }
+      if (v.error) {
+        yield { key: k, value: Result.Err<T>(v.error) };
+      } else {
+        yield { key: k, value: Result.Ok<T>(v.value as T) };
+      }
+    }
   }
 }
 
+/**
+ * Type helper that adds a key property to a context object.
+ *
+ * Used by keyed collections to provide the current key to factory functions and callbacks.
+ *
+ * @template X - The context type
+ * @template K - The key type
+ *
+ * @example
+ * ```typescript
+ * type MyContext = { userId: string };
+ * type WithKey = AddKey<MyContext, number>;
+ * // Result: { userId: string, key: number }
+ * ```
+ */
 export type AddKey<X extends NonNullable<object>, K> = X & { key: K };
+
+/**
+ * Configuration type for KeyedResolvSeq.
+ * @internal
+ */
 type WithCTX<K, T, CTX extends NonNullable<object>> = KeyedParam<K, ResolveSeq<T, AddKey<CTX, K>>> & { readonly ctx: CTX };
 
+/**
+ * Keyed collection of ResolveSeq instances.
+ *
+ * Manages a map of ResolveSeq instances indexed by keys, with optional LRU caching.
+ * Each key gets its own ResolveSeq instance for sequential execution of operations.
+ *
+ * @template T - The return type of the ResolveSeq instances
+ * @template K - The key type
+ * @template CTX - Optional context type
+ *
+ * @example
+ * ```typescript
+ * const sequences = new KeyedResolvSeq<number, string>();
+ *
+ * // Each key gets its own sequential executor
+ * sequences.get('user1').add(() => updateUser1());
+ * sequences.get('user2').add(() => updateUser2());
+ * ```
+ */
 export class KeyedResolvSeq<T extends NonNullable<unknown>, K = string, CTX extends NonNullable<object> = object> extends Keyed<
   ResolveSeq<T, AddKey<CTX, K>>,
   K,
@@ -517,6 +1038,10 @@ export class KeyedResolvSeq<T extends NonNullable<unknown>, K = string, CTX exte
   }
 }
 
+/**
+ * Internal helper class for the Lazy function.
+ * @internal
+ */
 class LazyContainer<T> {
   readonly resolveOnce = new ResolveOnce<T>();
 
@@ -526,8 +1051,29 @@ class LazyContainer<T> {
   }
 }
 
-// T extends (...args: infer P) => any
-// export function Lazy<R extends (...args: infer P) => infer X >(fn: R): (...args: P) =>infer
+/**
+ * Creates a lazy-evaluated version of a function that executes only once and caches the result.
+ *
+ * The returned function will execute the original function on first call and return
+ * the cached result for all subsequent calls, regardless of arguments. This is useful
+ * for expensive computations or resource initialization.
+ *
+ * @template Args - The argument types of the function
+ * @template Return - The return type of the function
+ * @param fn - The function to make lazy
+ * @returns A wrapped function that executes once and caches the result
+ *
+ * @example
+ * ```typescript
+ * const getConfig = Lazy(() => {
+ *   console.log('Loading config...');
+ *   return { apiKey: 'secret' };
+ * });
+ *
+ * getConfig(); // Logs "Loading config..." and returns config
+ * getConfig(); // Returns cached config without logging
+ * ```
+ */
 export function Lazy<Args extends readonly unknown[], Return>(fn: (...args: Args) => Return): (...args: Args) => Return {
   const lazy = new LazyContainer<Return>();
   return lazy.call(fn);