@adviser/cement 0.4.62 → 0.4.64-dev

package/src/resolve-once.ts

@@ -1,17 +1,60 @@
+/**
+ * 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";
-import { LRUMap, LRUParam, UnregFn } from "./lru-map-set.js";
+import { UnregFn } from "./lru-map-set.js";
 import { Result } from "./result.js";
 import { Option } from "./option.js";
+import { KeyedIf, KeyedNg, KeyedNgItem, KeyedNgItemWithoutValue, KeyedNgOptions } from "./keyed-ng.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 +62,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 +85,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 +113,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 +134,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 +171,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 +189,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 +215,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 +241,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 +258,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 +288,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 +318,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 +346,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 +353,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 +382,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 +406,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 +416,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 +437,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 +450,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 +465,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";
 
@@ -382,6 +563,11 @@ export class ResolveOnce<T, CTX = void> implements ResolveOnceIf<T, CTX> {
 
   reset<R>(fn?: (c: CTX) => R): ResultOnce<R> {
     if (this.#state === "initial") {
+      if (!fn) {
+        // eslint-disable-next-line no-console
+        console.warn("ResolveOnce.reset called but not yet resolved and no fn given");
+        return undefined as ResultOnce<R>;
+      }
       return this.once(fn as (c: CTX) => R);
     }
     if (this.#state === "processing") {
@@ -393,97 +579,364 @@ export class ResolveOnce<T, CTX = void> implements ResolveOnceIf<T, CTX> {
   }
 }
 
-export interface KeyedParam<K, V> {
-  readonly lru: Partial<LRUParam<V, K>>;
+// /**
+//  * 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>>;
+// }
+
+/**
+ * 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 type AddKeyedParam<K, V, CTX extends NonNullable<object>> = KeyedParam<K, V> & { readonly ctx: CTX };
+/**
+ * Configuration parameters for KeyedResolvOnce, excluding the createValue factory.
+ * @template K - The key type
+ * @template V - The value type
+ * @template CTX - The context type
+ */
+export type AddKeyedParam<K, V, CTX extends NonNullable<object>> = Omit<KeyedNgOptions<K, V, CTX>, "createValue">;
+
+/**
+ * Type helper that adds a key property to a context object.
+ * @template X - The context type
+ * @template K - The key type
+ */
+export type WithKey<X extends NonNullable<object>, K> = X & { readonly key: K };
+
+/**
+ * Type helper that adds an optional reset method to a value type.
+ * @template V - The value type
+ */
+export type WithOptionalReset<V> = V & { readonly reset?: () => void };
+
+/**
+ * Represents an item in a KeyedResolvOnce collection with its resolved result.
+ * @template K - The key type
+ * @template T - The value type
+ * @template CTX - The context type
+ */
+export interface KeyedResolveOnceItem<K, T, CTX extends NonNullable<object>> {
+  /** The key associated with this item */
+  readonly key: K;
+  /** The resolved value wrapped in a Result (Ok or Err) */
+  readonly value: Result<T>;
+  /** The complete KeyedNgItem containing metadata */
+  readonly item: KeyedNgItem<K, ResolveOnce<WithOptionalReset<T>, KeyedNgItemWithoutValue<K, CTX>>, CTX>;
+}
 
-export class Keyed<T extends { reset: () => void }, K = string, CTX extends NonNullable<object> = object> {
-  protected readonly _map: LRUMap<K, T>;
-  // #lock = new ResolveSeq<T, K>();
-  readonly #ctx: 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.
+ * Values can optionally have a reset() method for cleanup on deletion.
+ *
+ * @template T - The return type of the ResolveOnce instances (must include optional reset)
+ * @template K - The key type (defaults to string)
+ * @template CTX - Optional context type (defaults to empty object)
+ * @template PT - Plain type of T without reset (for internal use)
+ *
+ * @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());
+ *
+ * // Delete specific key
+ * cache.delete('key1');
+ *
+ * // Iterate over all resolved entries
+ * cache.forEach((item) => {
+ *   console.log(item.key, item.value.Ok);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom key type and context
+ * interface UserKey { org: string; id: string; }
+ * interface UserContext { apiKey: string; }
+ *
+ * const users = new KeyedResolvOnce<User, UserKey, UserContext>({
+ *   key2string: (key) => `${key.org}:${key.id}`,
+ *   ctx: { apiKey: 'default' },
+ *   lru: { max: 100 }
+ * });
+ *
+ * const user = users.get({ org: 'acme', id: '123' })
+ *   .once(({ givenKey, ctx }) => fetchUser(givenKey, ctx));
+ * ```
+ */
+export class KeyedResolvOnce<T extends WithOptionalReset<PT>, K = string, CTX extends NonNullable<object> = object, PT = T>
+  implements
+    Omit<
+      // KeyedIf<ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>, WithOptionalReset<T>, K>
+      KeyedIf<
+        KeyedNgItem<K, ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>, CTX>,
+        ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>,
+        K,
+        CTX
+      >,
+      "entries" | "forEach" | "onSet" | "onDelete" | "values" | "setParam"
+    >
+{
+  /** @internal */
+  readonly _keyed: KeyedNg<K, ResolveOnce<WithOptionalReset<T>, KeyedNgItemWithoutValue<K, CTX>>, CTX>;
 
-  readonly factory: (ctx: AddKey<CTX, K>) => T;
+  /**
+   * Creates a new KeyedResolvOnce instance.
+   *
+   * @param kp - Configuration options (key2string, ctx, lru)
+   */
+  constructor(kp: Partial<AddKeyedParam<K, T, CTX>> = {}) {
+    this._keyed = new KeyedNg({
+      createValue: (
+        item: KeyedNgItem<K, ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>, CTX>,
+      ): ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>> => {
+        return new ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>({
+          ...item,
+          ctx: kp.ctx ?? item.ctx,
+        });
+      },
+      key2string: kp.key2string,
+      ctx: kp.ctx as CTX,
+      lru: kp.lru,
+    });
+  }
 
-  constructor(factory: (ctx: AddKey<CTX, K>) => T, ctx: Partial<AddKeyedParam<K, T, CTX>>) {
-    this.#ctx = ctx.ctx || ({} as CTX);
-    this.factory = factory;
-    this._map = new LRUMap<K, T>(ctx?.lru ?? ({ maxEntries: -1 } as LRUParam<T, K>));
+  /**
+   * Returns all keys currently in the collection.
+   *
+   * @returns Array of all keys
+   */
+  keys(): K[] {
+    return this._keyed.keys();
   }
 
-  onSet(fn: (key: K, value: T) => void): UnregFn {
-    return this._map.onSet(fn);
+  /**
+   * Returns all resolved items with their values wrapped in Result.
+   *
+   * Only includes items that have been resolved (ready state).
+   * Each item contains the key, Result-wrapped value, and full item metadata.
+   *
+   * @returns Array of all resolved items
+   *
+   * @example
+   * ```typescript
+   * const items = cache.values();
+   * items.forEach(({ key, value }) => {
+   *   if (value.Ok) {
+   *     console.log(key, value.unwrap());
+   *   } else {
+   *     console.error(key, value.unwrapErr());
+   *   }
+   * });
+   * ```
+   */
+  values(): KeyedResolveOnceItem<K, T, CTX>[] {
+    return this._keyed
+      .values()
+      .filter((i) => i.value.ready)
+      .map((item) => ({
+        key: item.givenKey,
+        value: item.value.error ? Result.Err<T>(item.value.error) : Result.Ok<T>(item.value.value as T),
+        item,
+      }));
+  }
+
+  /**
+   * Registers a callback that fires when a new ResolveOnce instance is created.
+   *
+   * @param fn - Callback receiving the key and ResolveOnce instance
+   * @returns Unregister function
+   */
+  onSet(fn: (key: K, value: ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>) => void): UnregFn {
+    return this._keyed.onSet((item) => {
+      fn(item.givenKey, item.value);
+    });
   }
 
-  onDelete(fn: (key: K, value: T) => void): UnregFn {
-    return this._map.onDelete(fn);
+  /**
+   * Registers a callback that fires when a ResolveOnce instance is deleted.
+   *
+   * @param fn - Callback receiving the key and ResolveOnce instance
+   * @returns Unregister function
+   */
+  onDelete(fn: (key: K, value: ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>) => void): UnregFn {
+    return this._keyed.onDelete((item) => {
+      fn(item.givenKey, item.value);
+    });
   }
 
-  setParam(params: KeyedParam<K, T>): void {
-    this._map.setParam(params.lru);
+  /**
+   * Updates the LRU parameters dynamically.
+   *
+   * @param params - New LRU parameters
+   */
+  setParam(params: Partial<AddKeyedParam<K, ResolveOnce<T, CTX>, CTX>>): void {
+    this._keyed.setParam({ lru: params.lru });
   }
 
-  async asyncGet(key: () => Promise<K>): Promise<T> {
-    return this.get(await key());
+  /**
+   * Asynchronously gets or creates a ResolveOnce for a key resolved from a promise.
+   *
+   * @param key - Function returning a promise that resolves to the key
+   * @returns Promise resolving to the ResolveOnce instance
+   */
+  asyncGet(key: () => Promise<K>): Promise<ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>> {
+    return this._keyed.asyncGet(key);
   }
 
-  get(key: K | (() => K)): T {
+  /**
+   * Gets or creates a ResolveOnce instance for the given key.
+   *
+   * This is the primary method for accessing ResolveOnce instances. Each unique
+   * key gets its own instance that persists across calls.
+   *
+   * @param key - The key or function returning the key
+   * @param ctx - Optional context override for this operation
+   * @returns The ResolveOnce instance for this key
+   *
+   * @example
+   * ```typescript
+   * const result = cache.get('myKey').once(({ refKey, givenKey, ctx }) => {
+   *   return computeValue(givenKey, ctx);
+   * });
+   * ```
+   */
+  get(key: K | (() => K), ctx?: CTX): ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>> {
     if (typeof key === "function") {
       key = (key as () => K)();
     }
-    let keyed = this._map.get(key);
-    if (!keyed) {
-      keyed = this.factory({ ...this.#ctx, key: key });
-      this._map.set(key, keyed);
-    }
-    return keyed;
+    return this._keyed.getItem(key, ctx).value;
   }
 
-  has(key: K | (() => K)): boolean {
-    if (typeof key === "function") {
-      key = (key as () => K)();
-    }
-    return this._map.has(key);
+  /**
+   * Gets or creates the complete KeyedNgItem for a key.
+   *
+   * Useful when you need access to the full item structure including metadata.
+   *
+   * @param key - The key to get
+   * @param ctx - Optional context override
+   * @returns The complete KeyedNgItem
+   */
+  getItem(key: K, ctx?: CTX): KeyedNgItem<K, ResolveOnce<T, KeyedNgItemWithoutValue<K, CTX>>, CTX> {
+    return this._keyed.getItem(key, ctx);
   }
 
-  // lock<R extends Promisable<T>>(fn: (map: LRUMap<K, T>) => R): Promise<UnPromisify<R>>  {
-  //   return this.#lock.add(() => fn(this._map));
-  // }
+  /**
+   * Checks if a key exists in the collection.
+   *
+   * @param key - The key or function returning the key
+   * @returns True if the key exists
+   */
+  has(key: K | (() => K)): boolean {
+    return this._keyed.has(key);
+  }
 
+  /**
+   * Deletes an entry from the collection.
+   *
+   * Triggers onDelete callbacks before removal.
+   *
+   * @param key - The key to delete
+   */
   delete(key: K): void {
-    this._map.delete(key);
+    this._keyed.delete(key);
   }
 
+  /**
+   * Resets and removes an entry from the collection.
+   *
+   * Calls the optional reset() method on the value before deletion,
+   * allowing for cleanup operations.
+   *
+   * @param key - The key to reset and delete
+   */
   unget(key: K): void {
-    const keyed = this._map.get(key);
-    keyed?.reset();
-    this._map.delete(key);
+    const item = this._keyed.getItem(key);
+    item.value.reset?.();
+    return this._keyed.delete(item.givenKey);
   }
 
+  /**
+   * Resets all entries by calling their optional reset() methods.
+   *
+   * Does not remove entries from the collection, only resets their state.
+   * Useful for cleanup without losing the collection structure.
+   */
   reset(): void {
-    this._map.forEach((keyed) => keyed.reset());
-    this._map.clear();
+    for (const v of this._keyed.values()) {
+      v.value.reset?.();
+    }
   }
-}
-
-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
-> {
-  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>);
+  /**
+   * 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.
+   *
+   * @param fn - Callback receiving KeyItem and index
+   *
+   * @example
+   * ```typescript
+   * cache.forEach((item, idx) => {
+   *   console.log(idx, item.key);
+   *   if (item.value.Ok) {
+   *     console.log('Success:', item.value.unwrap());
+   *   } else {
+   *     console.error('Error:', item.value.unwrapErr());
+   *   }
+   * });
+   * ```
+   */
+  forEach(fn: (ki: KeyItem<K, T>, idx: number) => void): void {
+    for (const [item, idx] of this._keyed.entries()) {
+      const v = item.value;
+      const k = item.givenKey;
+      if (!v.ready) {
+        continue;
+      }
+      if (v.error) {
+        fn({ key: k, value: Result.Err<T>(v.error) }, idx);
+      } else {
+        fn({ key: k, value: Result.Ok<T>(v.value as T) }, idx);
+      }
+    }
   }
 
-  *entries(): IterableIterator<KeyItem<K, T>> {
-    for (const [k, v] of this._map.entries()) {
+  /**
+   * Returns an iterable of all completed entries.
+   *
+   * Only yields entries that have been resolved. Values are wrapped in Result.
+   *
+   * @returns Iterable of KeyItem entries
+   *
+   * @example
+   * ```typescript
+   * for (const item of cache.entries()) {
+   *   console.log(item.key, item.value.Ok);
+   * }
+   * ```
+   */
+  *entries(): Iterable<KeyItem<K, T>> {
+    /* this is not optimal, but sufficient for now */
+    for (const [item] of this._keyed.entries()) {
+      const v = item.value;
+      const k = item.givenKey;
       if (!v.ready) {
         continue;
       }
@@ -494,29 +947,58 @@ export class KeyedResolvOnce<T, K = string, CTX extends NonNullable<object> = ob
       }
     }
   }
+}
 
+/**
+ * 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 VALUEType - The return type of the ResolveSeq instances
+ * @template KEYType - 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<
+  VALUEType extends NonNullable<unknown>,
+  KEYType = string,
+  CTX extends NonNullable<object> = object,
+> extends KeyedNg<KEYType, ResolveSeq<VALUEType, KeyedNgItemWithoutValue<KEYType, CTX>>, CTX> {
   /**
+   * Creates a new KeyedResolvSeq instance.
    *
-   * @returns The values of the resolved keys
+   * @param kp - Configuration options (key2string, ctx, lru)
    */
-  values(): KeyItem<K, T>[] {
-    return Array.from(this.entries());
-  }
-}
-
-export type AddKey<X extends NonNullable<object>, K> = X & { key: K };
-type WithCTX<K, T, CTX extends NonNullable<object>> = KeyedParam<K, ResolveSeq<T, AddKey<CTX, K>>> & { readonly ctx: CTX };
-
-export class KeyedResolvSeq<T extends NonNullable<unknown>, K = string, CTX extends NonNullable<object> = object> extends Keyed<
-  ResolveSeq<T, AddKey<CTX, K>>,
-  K,
-  CTX
-> {
-  constructor(kp: Partial<WithCTX<K, T, CTX>> = {}) {
-    super((ctx) => new ResolveSeq<T, AddKey<CTX, K>>(ctx), kp);
+  constructor(kp: Partial<Omit<KeyedNgOptions<KEYType, VALUEType, CTX>, "createValue">> = {}) {
+    super({
+      createValue: (
+        item: KeyedNgItem<KEYType, ResolveSeq<VALUEType, KeyedNgItemWithoutValue<KEYType, CTX>>, CTX>,
+      ): ResolveSeq<VALUEType, KeyedNgItemWithoutValue<KEYType, CTX>> => {
+        return new ResolveSeq<VALUEType, KeyedNgItemWithoutValue<KEYType, CTX>>({
+          ...item,
+          ctx: kp.ctx ?? item.ctx,
+        });
+      },
+      key2string: kp.key2string,
+      ctx: kp.ctx as CTX,
+      lru: kp.lru,
+    });
   }
 }
 
+/**
+ * Internal helper class for the Lazy function.
+ * @internal
+ */
 class LazyContainer<T> {
   readonly resolveOnce = new ResolveOnce<T>();
 
@@ -526,8 +1008,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);