@sovereignbase/convergent-replicated-list 1.0.9 → 1.2.0

package/dist/index.d.ts

@@ -31,6 +31,10 @@ type CRListState<T> = {
     size: number;
     /** Current live entry used as the walking cursor. */
     cursor: CRListStateEntry<T>;
+    /** Current zero-based index of `cursor`. */
+    cursorIndex?: number;
+    /** Opportunistic live-entry cache keyed by observed zero-based index. */
+    index?: Map<number, NonNullable<CRListStateEntry<T>>>;
     /** Deleted UUIDv7 entries retained for gossip and convergence. */
     tombstones: Set<string>;
     /** Live entries by UUIDv7. */
@@ -39,7 +43,10 @@ type CRListState<T> = {
     childrenMap: Map<string, Array<NonNullable<CRListStateEntry<T>>>>;
 };
 /**
- * Serializable value entry used by snapshots and deltas.
+ * Value entry used by snapshots and deltas.
+ *
+ * `value` is a live payload reference. Consumers that mutate values outside
+ * CRList operations must provide their own isolation first.
  */
 type CRListSnapshotEntry<T> = {
     /** Stable UUIDv7 identity for this entry. */
@@ -50,10 +57,10 @@ type CRListSnapshotEntry<T> = {
     predecessor: string;
 };
 /**
- * Full serializable CRList state.
+ * Full CRList state snapshot.
  */
 type CRListSnapshot<T> = {
-    /** Serializable live values. */
+    /** Live values with stable CRDT metadata. */
     values: Array<CRListSnapshotEntry<T>>;
     /** Retained deleted UUIDv7 entries. */
     tombstones: Array<string>;
@@ -67,6 +74,8 @@ type CRListSnapshot<T> = {
 type CRListChange<T> = Record<number, T | undefined>;
 /**
  * Partial CRList state gossiped between replicas.
+ *
+ * Delta value payloads are live references.
  */
 type CRListDelta<T> = Partial<CRListSnapshot<T>>;
 type CRListAck = string;
@@ -96,11 +105,12 @@ type CRListEventListenerFor<T, K extends string> = K extends keyof CRListEventMa
  * A convergent replicated list.
  *
  * Numeric property access reads and mutates the live list projection:
- * `list[0]` reads a detached copy of an entry, `list[0] = value` writes an
- * entry, and `delete list[0]` removes one entry. Iteration and `forEach()`
- * likewise expose detached copies rather than mutable references into the
- * replica state. Local mutations emit `delta` and `change` events; remote
- * merges emit `change` events.
+ * `list[0]` reads the live value reference, `list[0] = value` writes an
+ * entry, and `delete list[0]` removes one entry. Iteration, `find()`, and
+ * `forEach()` expose the same live value references. Mutating returned objects
+ * directly can mutate replica state without producing a CRDT delta, so callers
+ * must isolate values before out-of-band mutation. Local mutations emit `delta`
+ * and `change` events; remote merges emit `change` events.
  *
  * @typeParam T - The value type stored in the list.
  */
@@ -108,13 +118,13 @@ declare class CRList<T> {
     /**
      * Reads or overwrites an entry in the live list projection by index.
      *
-     * Reads return detached copies.
+     * Reads return live value references.
      */
     [index: number]: T;
     private readonly state;
     private readonly eventTarget;
     /**
-     * Creates a replicated list from an optional detached structured-clone-compatible snapshot.
+     * Creates a replicated list from an optional CRList snapshot.
      *
      * @param snapshot - A previously emitted CRList snapshot.
      */
@@ -147,6 +157,16 @@ declare class CRList<T> {
      * @param index - The index to remove.
      */
     remove(index: number): void;
+    /**
+     * Returns the first live value matching a predicate in index order.
+     *
+     * Predicate values are live references. Mutating them directly can mutate the
+     * list without emitting a delta.
+     *
+     * @param predicate - Function to test each live value.
+     * @param thisArg - Optional `this` value for the predicate.
+     */
+    find(predicate: (this: unknown, value: T, index: number, list: this) => unknown, thisArg?: unknown): T | undefined;
     /**
      * Applies a remote gossip delta to this list.
      *
@@ -166,7 +186,10 @@ declare class CRList<T> {
      */
     garbageCollect(frontiers: Array<CRListAck>): void;
     /**
-     * Emits the current detached structured-clone-compatible list snapshot.
+     * Emits the current CRList snapshot.
+     *
+     * Snapshot value payloads are live references. Mutating them can mutate
+     * replica state without emitting a delta.
      */
     snapshot(): void;
     /**
@@ -186,7 +209,10 @@ declare class CRList<T> {
      */
     removeEventListener<K extends keyof CRListEventMap<T>>(type: K, listener: CRListEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
     /**
-     * Returns a detached structured-clone-compatible snapshot of this list.
+     * Returns a CRList snapshot of this list.
+     *
+     * Snapshot value payloads are live references. Mutating them can mutate
+     * replica state without emitting a delta.
      *
      * Called automatically by `JSON.stringify`.
      */
@@ -198,16 +224,16 @@ declare class CRList<T> {
      */
     toString(): string;
     /**
-     * Iterates over detached copies of the current live values in index order.
+     * Iterates over current live values in index order.
      */
     [Symbol.iterator](): IterableIterator<T>;
     /**
-     * Calls a function once for each live value copy in index order.
+     * Calls a function once for each live value in index order.
      *
-     * Callback values are detached copies, so mutating them does not mutate the
-     * list.
+     * Callback values are live references. Mutating them directly can mutate the
+     * list without emitting a delta.
      *
-     * @param callback - Function to call for each value copy.
+     * @param callback - Function to call for each live value.
      * @param thisArg - Optional `this` value for the callback.
      */
     forEach(callback: (value: T, index: number, list: this) => void, thisArg?: unknown): void;
@@ -237,33 +263,33 @@ declare class CRListError extends Error {
 /**
  * Creates a local CRList replica from an optional snapshot.
  *
- * Invalid snapshot records are ignored. Accepted values are cloned, indexed by
- * UUIDv7, linked through their predecessor buckets, and exposed as a live
- * doubly-linked list.
+ * Invalid snapshot records are ignored. Accepted values are kept by reference,
+ * indexed by UUIDv7, linked through their predecessor buckets, and exposed as a
+ * live doubly-linked list projection.
  *
- * @param snapshot - Optional detached structured-clone-compatible CRList snapshot.
+ * @param snapshot - Optional CRList snapshot.
  * @returns - A hydrated CRList replica.
  *
- * Time complexity: O(n log n + t + c), worst case O(n^2 + t + c)
+ * Time complexity: O(n log n + t), worst case O(n^2 + t)
  * - n = snapshot value entry count
  * - t = snapshot tombstone count
- * - c = cloned value payload
  *
- * Space complexity: O(n + t + c)
+ * Space complexity: O(n + t)
  */
 declare function __create<T>(snapshot?: CRListSnapshot<T>): CRListState<T>;
 
 /**
  * Reads the value at an index in the replica live view.
  *
- * The replica cursor is moved as part of the lookup. Successful reads return a
- * detached structured clone of the visible value, so mutating the returned
- * value does not mutate the replica itself. Out-of-bounds and empty list reads
- * resolve to `undefined` instead of throwing.
+ * The replica cursor is moved as part of the lookup. Successful reads return
+ * the live value reference stored by the replica. Mutating that value directly
+ * can mutate replica state and should only be done when the caller owns an
+ * independent value object. Out-of-bounds and empty list reads resolve to
+ * `undefined` instead of throwing.
  *
  * @param targetIndex - Index in the live list.
  * @param crListReplica - Replica to read from.
- * @returns - A detached copy of the value at `targetIndex`, or `undefined` when
+ * @returns - The live value at `targetIndex`, or `undefined` when
  * no value is present.
  *
  * Time complexity: O(d), worst case O(n)
@@ -287,14 +313,13 @@ declare function __read<T>(targetIndex: number, crListReplica: CRListState<T>):
  * @param mode - Mutation mode relative to `listIndex`.
  * @returns - A local change and gossip delta, or `false` if no mutation occurred.
  *
- * Time complexity: O(d + v + r + vk + c), worst case O(vn + c)
+ * Time complexity: O(d + v + r + vk), worst case O(vn)
  * - d = distance from cursor to target index
  * - v = amount of input values
  * - r = amount of nodes after inserted values whose indexes must be shifted
  * - k = sibling bucket size when predecessor bucket is updated
- * - c = cloned value payload size across all input values
  *
- * Space complexity: O(v + c)
+ * Space complexity: O(v)
  */
 declare function __update<T>(listIndex: number, listValues: Array<T>, crListReplica: CRListState<T>, mode: 'overwrite' | 'before' | 'after'): {
     change: CRListChange<T>;
@@ -337,17 +362,16 @@ declare function __delete<T>(crListReplica: CRListState<T>, startIndex?: number,
  * @param crListDelta - Remote gossip delta.
  * @returns - A minimal local change patch, or `false` when the delta is ignored.
  *
- * Time complexity: O(v + t + c) for tail-append deltas; O(n + t + qk) for tombstone-only deletes; otherwise O(n log n + v + t + m*k + c)
- * Worst case: O(n^2 + (v + t)n + c)
+ * Time complexity: O(v + t) for tail-append deltas; O(n + t + qk) for tombstone-only deletes; otherwise O(n log n + v + t + m*k)
+ * Worst case: O(n^2 + (v + t)n)
  * - n = replica value entry count after merge
  * - v = delta value entry count
  * - t = delta tombstone count
  * - q = amount of live entries deleted by tombstones
  * - m = entries moved between predecessor buckets
  * - k = sibling bucket size when entries are removed from buckets
- * - c = cloned delta value payload size
  *
- * Space complexity: O(n + v + t + c)
+ * Space complexity: O(n + v + t)
  */
 declare function __merge<T>(crListReplica: CRListState<T>, crListDelta: CRListDelta<T>): CRListChange<T> | false;
 
@@ -386,20 +410,20 @@ declare function __acknowledge<T>(crListReplica: CRListState<T>): CRListAck | fa
 declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica: CRListState<T>): void;
 
 /**
- * Creates a full detached structured-clone-compatible CRList snapshot from the current replica state.
+ * Creates a full CRList snapshot from the current replica state.
  *
  * The snapshot contains every live value entry and all retained tombstones. Value
- * payloads are cloned so callers cannot mutate the replica through the snapshot.
+ * payloads are live references, so callers must not mutate snapshot values
+ * unless they have first isolated them from replica state.
  *
  * @param crListReplica - Replica to snapshot.
  * @returns - A full snapshot suitable for hydration or transport.
  *
- * Time complexity: O(n + t + c)
+ * Time complexity: O(n + t)
  * - n = replica value entry count
  * - t = replica tombstone count
- * - c = cloned value payload size
  *
- * Space complexity: O(n + t + c)
+ * Space complexity: O(n + t)
  */
 declare function __snapshot<T>(crListReplica: CRListState<T>): CRListSnapshot<T>;