@sovereignbase/convergent-replicated-list 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * The `predecessor` field is the stable ordering anchor used for convergence;
  * `prev` and `next` are local projection links for indexed reads and mutations.
  */
-type DoublyLinkedListEntry<T> = {
+type CRListStateEntry<T> = {
     /** Stable UUIDv7 identity for this entry. */
     uuidv7: string;
     /** User payload stored in the list. */
@@ -14,9 +14,9 @@ type DoublyLinkedListEntry<T> = {
     /** Current zero-based index in the local live view. */
     index: number;
     /** Previous live entry in the local projection. */
-    prev: DoublyLinkedListEntry<T> | undefined;
+    prev: CRListStateEntry<T> | undefined;
     /** Next live entry in the local projection. */
-    next: DoublyLinkedListEntry<T> | undefined;
+    next: CRListStateEntry<T> | undefined;
 } | undefined;
 /**
  * Mutable CRList replica state.
@@ -26,22 +26,22 @@ type DoublyLinkedListEntry<T> = {
  * UUIDv7 entries until they are garbage collected through acknowledgement
  * frontiers.
  */
-type CRListReplica<T> = {
+type CRListState<T> = {
     /** Number of live entries in the local projection. */
     size: number;
     /** Current live entry used as the walking cursor. */
-    cursor: DoublyLinkedListEntry<T>;
+    cursor: CRListStateEntry<T>;
     /** Deleted UUIDv7 entries retained for gossip and convergence. */
     tombstones: Set<string>;
     /** Live entries by UUIDv7. */
-    parentMap: Map<string, DoublyLinkedListEntry<T>>;
+    parentMap: Map<string, CRListStateEntry<T>>;
     /** Live entries grouped by stable predecessor identifier. */
-    childrenMap: Map<string, Array<NonNullable<DoublyLinkedListEntry<T>>>>;
+    childrenMap: Map<string, Array<NonNullable<CRListStateEntry<T>>>>;
 };
 /**
  * Serializable value entry used by snapshots and deltas.
  */
-type CRListSnapshotValueEntry<T> = {
+type CRListSnapshotEntry<T> = {
     /** Stable UUIDv7 identity for this entry. */
     uuidv7: string;
     /** User payload for this entry. */
@@ -54,14 +54,10 @@ type CRListSnapshotValueEntry<T> = {
  */
 type CRListSnapshot<T> = {
     /** Serializable live values. */
-    values: Array<CRListSnapshotValueEntry<T>>;
+    values: Array<CRListSnapshotEntry<T>>;
     /** Retained deleted UUIDv7 entries. */
     tombstones: Array<string>;
 };
-/**
- * Partial CRList state gossiped between replicas.
- */
-type CRListDelta<T> = Partial<CRListSnapshot<T>>;
 /**
  * Minimal local live-view patch keyed by list index.
  *
@@ -70,8 +66,9 @@ type CRListDelta<T> = Partial<CRListSnapshot<T>>;
  */
 type CRListChange<T> = Record<number, T | undefined>;
 /**
- * Tombstone acknowledgement frontier.
+ * Partial CRList state gossiped between replicas.
  */
+type CRListDelta<T> = Partial<CRListSnapshot<T>>;
 type CRListAck = string;
 /**
  * Maps CRList event names to their event payload shapes.
@@ -95,6 +92,130 @@ type CRListEventListener<T, K extends keyof CRListEventMap<T>> = ((event: Custom
  */
 type CRListEventListenerFor<T, K extends string> = K extends keyof CRListEventMap<T> ? CRListEventListener<T, K> : EventListenerOrEventListenerObject;
 
+/**
+ * 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.
+ *
+ * @typeParam T - The value type stored in the list.
+ */
+declare class CRList<T> {
+    /**
+     * Reads or overwrites an entry in the live list projection by index.
+     *
+     * Reads return detached copies.
+     */
+    [index: number]: T;
+    private readonly state;
+    private readonly eventTarget;
+    /**
+     * Creates a replicated list from an optional serializable snapshot.
+     *
+     * @param snapshot - A previously emitted CRList snapshot.
+     */
+    constructor(snapshot?: CRListSnapshot<T>);
+    /**
+     * The current number of live entries.
+     */
+    get size(): number;
+    /**
+     * Inserts a value before an index.
+     *
+     * If `beforeIndex` is omitted, the value is inserted at the start of the list.
+     *
+     * @param value - The value to insert.
+     * @param beforeIndex - The index to insert before.
+     */
+    prepend(value: T, beforeIndex?: number): void;
+    /**
+     * Inserts a value after an index.
+     *
+     * If `afterIndex` is omitted, the value is appended at the end of the list.
+     *
+     * @param value - The value to insert.
+     * @param afterIndex - The index to insert after.
+     */
+    append(value: T, afterIndex?: number): void;
+    /**
+     * Removes the entry at an index.
+     *
+     * @param index - The index to remove.
+     */
+    remove(index: number): void;
+    /**
+     * Applies a remote gossip delta to this list.
+     *
+     * Emits a `change` event when the merge changes the live projection.
+     *
+     * @param delta - The remote CRList delta to merge.
+     */
+    merge(delta: CRListDelta<T>): void;
+    /**
+     * Emits an acknowledgement frontier for currently retained tombstones.
+     */
+    acknowledge(): void;
+    /**
+     * Garbage-collects tombstones that are covered by acknowledgement frontiers.
+     *
+     * @param frontiers - Replica acknowledgement frontiers.
+     */
+    garbageCollect(frontiers: Array<CRListAck>): void;
+    /**
+     * Emits the current serializable list snapshot.
+     */
+    snapshot(): void;
+    /**
+     * Registers an event listener.
+     *
+     * @param type - The event type to listen for.
+     * @param listener - The listener to register.
+     * @param options - Listener registration options.
+     */
+    addEventListener<K extends keyof CRListEventMap<T>>(type: K, listener: CRListEventListenerFor<T, K> | null, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Removes an event listener.
+     *
+     * @param type - The event type to stop listening for.
+     * @param listener - The listener to remove.
+     * @param options - Listener removal options.
+     */
+    removeEventListener<K extends keyof CRListEventMap<T>>(type: K, listener: CRListEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
+    /**
+     * Returns a serializable snapshot representation of this list.
+     *
+     * Called automatically by `JSON.stringify`.
+     */
+    toJSON(): CRListSnapshot<T>;
+    /**
+     * Returns this list as a JSON string.
+     */
+    toString(): string;
+    /**
+     * Iterates over detached copies of the current live values in index order.
+     */
+    [Symbol.iterator](): IterableIterator<T>;
+    /**
+     * Calls a function once for each live value copy in index order.
+     *
+     * Callback values are detached copies, so mutating them does not mutate the
+     * list.
+     *
+     * @param callback - Function to call for each value copy.
+     * @param thisArg - Optional `this` value for the callback.
+     */
+    forEach(callback: (value: T, index: number, list: this) => void, thisArg?: unknown): void;
+}
+
+/**
+ * Error codes thrown by {@link CRList}.
+ */
+type CRListErrorCode = 'VALUE_NOT_CLONEABLE' | 'INDEX_OUT_OF_BOUNDS' | 'LIST_EMPTY' | 'LIST_INTEGRITY_VIOLATION' | 'UPDATE_EXPECTED_AN_ARRAY';
+
 /**
  * Creates a local CRList replica from an optional snapshot.
  *
@@ -112,17 +233,20 @@ type CRListEventListenerFor<T, K extends string> = K extends keyof CRListEventMa
  *
  * Space complexity: O(n + t + c)
  */
-declare function __create<T>(snapshot?: CRListSnapshot<T>): CRListReplica<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. 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 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.
  *
  * @param targetIndex Index in the live list.
  * @param crListReplica Replica to read from.
- * @returns The value at `targetIndex`, or `undefined` when no value is present.
+ * @returns A detached copy of the value at `targetIndex`, or `undefined` when
+ * no value is present.
  *
  * Time complexity: O(d), worst case O(n)
  * - d = distance from cursor to target index
@@ -130,7 +254,7 @@ declare function __create<T>(snapshot?: CRListSnapshot<T>): CRListReplica<T>;
  *
  * Space complexity: O(1)
  */
-declare function __read<T>(targetIndex: number, crListReplica: CRListReplica<T>): T | undefined;
+declare function __read<T>(targetIndex: number, crListReplica: CRListState<T>): T | undefined;
 
 /**
  * Applies a local value mutation to the replica live view.
@@ -154,7 +278,7 @@ declare function __read<T>(targetIndex: number, crListReplica: CRListReplica<T>)
  *
  * Space complexity: O(v + c)
  */
-declare function __update<T>(listIndex: number, listValues: Array<T>, crListReplica: CRListReplica<T>, mode: 'overwrite' | 'before' | 'after'): {
+declare function __update<T>(listIndex: number, listValues: Array<T>, crListReplica: CRListState<T>, mode: 'overwrite' | 'before' | 'after'): {
     change: CRListChange<T>;
     delta: CRListDelta<T>;
 } | false;
@@ -179,7 +303,7 @@ declare function __update<T>(listIndex: number, listValues: Array<T>, crListRepl
  *
  * Space complexity: O(q)
  */
-declare function __delete<T>(crListReplica: CRListReplica<T>, startIndex?: number, endIndex?: number): {
+declare function __delete<T>(crListReplica: CRListState<T>, startIndex?: number, endIndex?: number): {
     change: CRListChange<T>;
     delta: CRListDelta<T>;
 } | false;
@@ -207,7 +331,7 @@ declare function __delete<T>(crListReplica: CRListReplica<T>, startIndex?: numbe
  *
  * Space complexity: O(n + v + t + c)
  */
-declare function __merge<T>(crListReplica: CRListReplica<T>, crListDelta: CRListDelta<T>): CRListChange<T> | false;
+declare function __merge<T>(crListReplica: CRListState<T>, crListDelta: CRListDelta<T>): CRListChange<T> | false;
 
 /**
  * Returns the replica tombstone acknowledgement frontier.
@@ -223,7 +347,7 @@ declare function __merge<T>(crListReplica: CRListReplica<T>, crListDelta: CRList
  *
  * Space complexity: O(1)
  */
-declare function __acknowledge<T>(crListReplica: CRListReplica<T>): CRListAck | false;
+declare function __acknowledge<T>(crListReplica: CRListState<T>): CRListAck | false;
 
 /**
  * Removes tombstones acknowledged by all supplied frontiers.
@@ -240,7 +364,7 @@ declare function __acknowledge<T>(crListReplica: CRListReplica<T>): CRListAck |
  *
  * Space complexity: O(1)
  */
-declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica: CRListReplica<T>): void;
+declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica: CRListState<T>): void;
 
 /**
  * Creates a full serializable CRList snapshot from the current replica state.
@@ -258,123 +382,6 @@ declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica:
  *
  * Space complexity: O(n + t + c)
  */
-declare function __snapshot<T>(crListReplica: CRListReplica<T>): CRListSnapshot<T>;
-
-/**
- * Error codes thrown by {@link CRList}.
- */
-type CRListErrorCode = 'VALUE_NOT_CLONEABLE' | 'INDEX_OUT_OF_BOUNDS' | 'LIST_EMPTY' | 'LIST_INTEGRITY_VIOLATION' | 'UPDATE_EXPECTED_AN_ARRAY';
-
-/**
- * A convergent replicated list.
- *
- * Numeric property access reads and mutates the live list projection:
- * `list[0]` reads an entry, `list[0] = value` writes an entry, and `delete
- * list[0]` removes one entry. Local mutations emit `delta` and `change` events;
- * remote merges emit `change` events.
- *
- * @typeParam T - The value type stored in the list.
- */
-declare class CRList<T> {
-    /**
-     * Reads or overwrites an entry in the live list projection by index.
-     */
-    [index: number]: T;
-    private readonly state;
-    private readonly eventTarget;
-    /**
-     * Creates a replicated list from an optional serializable snapshot.
-     *
-     * @param snapshot - A previously emitted CRList snapshot.
-     */
-    constructor(snapshot?: CRListSnapshot<T>);
-    /**
-     * The current number of live entries.
-     */
-    get size(): number;
-    /**
-     * Inserts a value before an index.
-     *
-     * If `beforeIndex` is omitted, the value is inserted at the start of the list.
-     *
-     * @param value - The value to insert.
-     * @param beforeIndex - The index to insert before.
-     */
-    prepend(value: T, beforeIndex?: number): void;
-    /**
-     * Inserts a value after an index.
-     *
-     * If `afterIndex` is omitted, the value is appended at the end of the list.
-     *
-     * @param value - The value to insert.
-     * @param afterIndex - The index to insert after.
-     */
-    append(value: T, afterIndex?: number): void;
-    /**
-     * Removes the entry at an index.
-     *
-     * @param index - The index to remove.
-     */
-    remove(index: number): void;
-    /**
-     * Applies a remote gossip delta to this list.
-     *
-     * Emits a `change` event when the merge changes the live projection.
-     *
-     * @param delta - The remote CRList delta to merge.
-     */
-    merge(delta: CRListDelta<T>): void;
-    /**
-     * Emits an acknowledgement frontier for currently retained tombstones.
-     */
-    acknowledge(): void;
-    /**
-     * Garbage-collects tombstones that are covered by acknowledgement frontiers.
-     *
-     * @param frontiers - Replica acknowledgement frontiers.
-     */
-    garbageCollect(frontiers: Array<CRListAck>): void;
-    /**
-     * Emits the current serializable list snapshot.
-     */
-    snapshot(): void;
-    /**
-     * Registers an event listener.
-     *
-     * @param type - The event type to listen for.
-     * @param listener - The listener to register.
-     * @param options - Listener registration options.
-     */
-    addEventListener<K extends keyof CRListEventMap<T>>(type: K, listener: CRListEventListenerFor<T, K> | null, options?: boolean | AddEventListenerOptions): void;
-    /**
-     * Removes an event listener.
-     *
-     * @param type - The event type to stop listening for.
-     * @param listener - The listener to remove.
-     * @param options - Listener removal options.
-     */
-    removeEventListener<K extends keyof CRListEventMap<T>>(type: K, listener: CRListEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
-    /**
-     * Returns a serializable snapshot representation of this list.
-     *
-     * Called automatically by `JSON.stringify`.
-     */
-    toJSON(): CRListSnapshot<T>;
-    /**
-     * Returns this list as a JSON string.
-     */
-    toString(): string;
-    /**
-     * Iterates over the current live values in index order.
-     */
-    [Symbol.iterator](): IterableIterator<T>;
-    /**
-     * Calls a function once for each live value in index order.
-     *
-     * @param callback - Function to call for each value.
-     * @param thisArg - Optional `this` value for the callback.
-     */
-    forEach(callback: (value: T, index: number, list: this) => void, thisArg?: unknown): void;
-}
+declare function __snapshot<T>(crListReplica: CRListState<T>): CRListSnapshot<T>;
 
-export { CRList, type CRListAck, type CRListChange, type CRListDelta, type CRListErrorCode, type CRListReplica, type CRListSnapshot, __acknowledge, __create, __delete, __garbageCollect, __merge, __read, __snapshot, __update };
+export { CRList, type CRListAck, type CRListChange, type CRListDelta, type CRListErrorCode, type CRListEventListener, type CRListEventListenerFor, type CRListEventMap, type CRListSnapshot, type CRListSnapshotEntry, type CRListState, type CRListStateEntry, __acknowledge, __create, __delete, __garbageCollect, __merge, __read, __snapshot, __update };

package/dist/index.js

@@ -15,9 +15,6 @@
  */
 
 
-// src/core/crud/create/index.ts
-import { isUuidV7 as isUuidV72, prototype } from "@sovereignbase/utils";
-
 // src/.helpers/assertListIndices/index.ts
 function assertListIndices(crListReplica) {
   if (!crListReplica.cursor) return;
@@ -218,6 +215,7 @@ function indexFromPropertyKey(index) {
 }
 
 // src/core/crud/create/index.ts
+import { isUuidV7 as isUuidV72, prototype } from "@sovereignbase/utils";
 function __create(snapshot) {
   const crListReplica = {
     size: 0,
@@ -253,7 +251,7 @@ function __create(snapshot) {
 function __read(targetIndex, crListReplica) {
   try {
     void walkToIndex(targetIndex, crListReplica);
-    return crListReplica?.cursor?.value;
+    return structuredClone(crListReplica?.cursor?.value);
   } catch {
     return void 0;
   }
@@ -825,7 +823,7 @@ var CRList = class {
     return this.toJSON();
   }
   /**
-   * Iterates over the current live values in index order.
+   * Iterates over detached copies of the current live values in index order.
    */
   *[Symbol.iterator]() {
     for (let index = 0; index < this.size; index++) {
@@ -834,9 +832,12 @@ var CRList = class {
     }
   }
   /**
-   * Calls a function once for each live value in index order.
+   * Calls a function once for each live value copy in index order.
+   *
+   * Callback values are detached copies, so mutating them does not mutate the
+   * list.
    *
-   * @param callback - Function to call for each value.
+   * @param callback - Function to call for each value copy.
    * @param thisArg - Optional `this` value for the callback.
    */
   forEach(callback, thisArg) {