feat(collections): add replace

Author: crimx

src/collections/reactiveArray.ts

@@ -167,6 +167,22 @@ export class OwnedReactiveArray<V> extends Array<V> implements ReadableProvider<
     return this;
   }
 
+  /**
+   * Replaces the contents of the array with the provided items.
+   * @param items The new items to replace the contents of the array with.
+   * @returns The array itself.
+   */
+  public replace(items: Iterable<V>): this {
+    const isBatchTop = batchStart();
+    let i = 0;
+    for (const item of items) {
+      this.set(i++, item);
+    }
+    this.setLength(i);
+    isBatchTop && batchFlush();
+    return this;
+  }
+
   public dispose(): void {
     if (this._disposed_) return;
     if (process.env.NODE_ENV !== "production") {

src/collections/reactiveMap.ts

@@ -1,4 +1,5 @@
 import { batchFlush, batchStart, type BatchTask, batchTasks } from "../batch";
+import { context } from "../context";
 import { type EventObject, on, type RemoveListener, send, size } from "../event";
 import { type ReadableProvider, type OwnedWritable, type Readable } from "../interface";
 import { writable } from "../readable";
@@ -201,6 +202,28 @@ export class OwnedReactiveMap<K, V> extends Map<K, V> implements ReadableProvide
     }
   }
 
+  /**
+   * Replace the contents of the map with the given entries.
+   * @param entries - The new entries to replace the map with.
+   * @returns The map itself.
+   */
+  public replace(entries: Iterable<readonly [K, V]>): this {
+    const isBatchTop = batchStart();
+    const newKeys: Set<K> = (context.replaceMarkers_ ??= new Set());
+    for (const [key, value] of entries) {
+      newKeys.add(key);
+      this.set(key, value);
+    }
+    for (const key of this.keys()) {
+      if (!newKeys.has(key)) {
+        this.delete(key);
+      }
+    }
+    newKeys.clear();
+    isBatchTop && batchFlush();
+    return this;
+  }
+
   /** @internal */
   private _disposed_?: Error | true;
 

src/collections/reactiveSet.ts

@@ -1,4 +1,5 @@
 import { batchFlush, batchStart, type BatchTask, batchTasks } from "../batch";
+import { context } from "../context";
 import { type EventObject, on, type RemoveListener, send, size } from "../event";
 import { type ReadableProvider, type OwnedWritable, type Readable } from "../interface";
 import { writable } from "../readable";
@@ -186,6 +187,28 @@ export class OwnedReactiveSet<V> extends Set<V> implements ReadableProvider<Read
     }
   }
 
+  /**
+   * Replace the contents of the set with the given values.
+   * @param values - The new values to replace the set with.
+   * @returns The set itself.
+   */
+  public replace(values: Iterable<V>): this {
+    const isBatchTop = batchStart();
+    const newValues: Set<V> = (context.replaceMarkers_ ??= new Set());
+    for (const value of values) {
+      newValues.add(value);
+      this.add(value);
+    }
+    for (const value of this) {
+      if (!newValues.has(value)) {
+        this.delete(value);
+      }
+    }
+    newValues.clear();
+    isBatchTop && batchFlush();
+    return this;
+  }
+
   /** @internal */
   private _disposed_?: Error | true;
 

src/context.ts

@@ -4,6 +4,7 @@ import { BRAND } from "./utils";
 export interface Context {
   batching_: boolean;
   readonly batchTask_: Set<BatchTask>;
+  replaceMarkers_?: Set<any>;
 }
 
 declare const globalThis: {

test/collections/reactiveArray.test.ts

@@ -650,6 +650,103 @@ describe("ReactiveArray", () => {
     });
   });
 
+  describe("replace", () => {
+    it("should replace the array with the specified elements", () => {
+      const arr = reactiveArray([1, 2, 3]);
+      const spy = vi.fn();
+      arr.$.reaction(spy);
+
+      expect(spy).toHaveBeenCalledTimes(0);
+
+      arr.replace([4, 5, 6]);
+
+      expect(spy).toHaveBeenCalledTimes(1);
+
+      expect(arr).toEqual([4, 5, 6]);
+    });
+
+    it("should replace the array with less elements", () => {
+      const arr = reactiveArray([1, 2, 3]);
+      const spy = vi.fn();
+      arr.$.reaction(spy);
+
+      expect(spy).toHaveBeenCalledTimes(0);
+
+      arr.replace([1]);
+
+      expect(spy).toHaveBeenCalledTimes(1);
+
+      expect(arr).toEqual([1]);
+    });
+
+    it("should replace the array with different order", () => {
+      const arr = reactiveArray([1, 2, 3]);
+      const spy = vi.fn();
+      arr.$.reaction(spy);
+
+      expect(spy).toHaveBeenCalledTimes(0);
+
+      arr.replace([3, 2, 1]);
+
+      expect(spy).toHaveBeenCalledTimes(1);
+
+      expect(arr).toEqual([3, 2, 1]);
+    });
+
+    it("should replace an empty array with the specified elements", () => {
+      const arr = reactiveArray<number>([]);
+
+      const spy = vi.fn();
+      arr.$.reaction(spy);
+
+      expect(spy).toHaveBeenCalledTimes(0);
+
+      arr.replace([1, 2, 3]);
+
+      expect(spy).toHaveBeenCalledTimes(1);
+
+      expect(arr).toEqual([1, 2, 3]);
+    });
+
+    it("should notify on replace", () => {
+      const arr = reactiveArray(["a", "b", "c"]);
+      const mockNotify = vi.fn();
+      const dispose = arr.$.reaction(mockNotify);
+
+      arr.replace(["x", "y", "z"]);
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+      expect(mockNotify).lastCalledWith(arr);
+
+      dispose();
+    });
+
+    it("should not notify if not changed", () => {
+      const arr = reactiveArray([1]);
+      const mockNotify = vi.fn();
+      const dispose = arr.$.reaction(mockNotify);
+
+      arr.replace([2, 3]);
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+      expect(mockNotify).lastCalledWith(arr);
+
+      dispose();
+    });
+
+    it("should notify if some keys are removed", () => {
+      const arr = reactiveArray([1, 2, 3]);
+      const mockNotify = vi.fn();
+      const dispose = arr.$.reaction(mockNotify);
+
+      expect(arr).toEqual([1, 2, 3]);
+
+      arr.replace([1, 2]);
+      expect(mockNotify).toHaveBeenCalledTimes(1);
+      expect(arr).toEqual([1, 2]);
+
+      dispose();
+    });
+  });
+
   describe.each(["test", "production"])("dispose [%s]", NODE_ENV => {
     const originalEnv = process.env.NODE_ENV;