atomirx 0.0.1

package/src/core/batch.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, vi } from "vitest";
+import { batch } from "./batch";
+import { atom } from "./atom";
+
+describe("batch", () => {
+  describe("basic batching", () => {
+    it("should batch multiple updates into single notification", () => {
+      const count = atom(0);
+      const listener = vi.fn();
+      count.on(listener);
+
+      batch(() => {
+        count.set(1);
+        count.set(2);
+        count.set(3);
+      });
+
+      // All updates batched - listener called once at the end
+      expect(count.value).toBe(3);
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should return the function result", () => {
+      const result = batch(() => {
+        return "hello";
+      });
+
+      expect(result).toBe("hello");
+    });
+
+    it("should return complex values", () => {
+      const result = batch(() => {
+        return { value: 42, items: [1, 2, 3] };
+      });
+
+      expect(result).toEqual({ value: 42, items: [1, 2, 3] });
+    });
+  });
+
+  describe("nested batching", () => {
+    it("should support nested batch calls", () => {
+      const count = atom(0);
+      const listener = vi.fn();
+      count.on(listener);
+
+      batch(() => {
+        count.set(1);
+
+        batch(() => {
+          count.set(2);
+          count.set(3);
+        });
+
+        count.set(4);
+      });
+
+      expect(count.value).toBe(4);
+      // All updates batched together
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should return value from nested batch", () => {
+      const result = batch(() => {
+        const inner = batch(() => {
+          return "inner";
+        });
+        return `outer-${inner}`;
+      });
+
+      expect(result).toBe("outer-inner");
+    });
+  });
+
+  describe("multiple atoms", () => {
+    it("should batch updates across multiple atoms", () => {
+      const a = atom(0);
+      const b = atom(0);
+      const listenerA = vi.fn();
+      const listenerB = vi.fn();
+      a.on(listenerA);
+      b.on(listenerB);
+
+      batch(() => {
+        a.set(1);
+        b.set(1);
+        a.set(2);
+        b.set(2);
+      });
+
+      expect(a.value).toBe(2);
+      expect(b.value).toBe(2);
+      expect(listenerA).toHaveBeenCalledTimes(1);
+      expect(listenerB).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("error handling", () => {
+    it("should propagate errors", () => {
+      expect(() => {
+        batch(() => {
+          throw new Error("test error");
+        });
+      }).toThrow("test error");
+    });
+
+    it("should still process notifications after error in nested batch", () => {
+      const count = atom(0);
+      const listener = vi.fn();
+      count.on(listener);
+
+      expect(() => {
+        batch(() => {
+          count.set(1);
+
+          try {
+            batch(() => {
+              count.set(2);
+              throw new Error("inner error");
+            });
+          } catch {
+            // Catch inner error
+          }
+
+          count.set(3);
+        });
+      }).not.toThrow();
+
+      expect(count.value).toBe(3);
+    });
+  });
+
+  describe("cascading updates", () => {
+    it("should handle cascading updates within batch", () => {
+      const a = atom(0);
+      const b = atom(0);
+      const listenerA = vi.fn();
+      const listenerB = vi.fn();
+
+      // When a changes, update b
+      a.on(() => {
+        if (a.value !== undefined && a.value > 0) {
+          b.set(a.value * 2);
+        }
+      });
+
+      a.on(listenerA);
+      b.on(listenerB);
+
+      batch(() => {
+        a.set(5);
+      });
+
+      expect(a.value).toBe(5);
+      expect(b.value).toBe(10);
+    });
+  });
+
+  describe("without batch", () => {
+    it("should notify immediately without batch", () => {
+      const count = atom(0);
+      const listener = vi.fn();
+      count.on(listener);
+
+      count.set(1);
+      expect(listener).toHaveBeenCalledTimes(1);
+
+      count.set(2);
+      expect(listener).toHaveBeenCalledTimes(2);
+
+      count.set(3);
+      expect(listener).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("listener deduping", () => {
+    it("should dedupe same listener subscribed to multiple atoms", () => {
+      const a = atom(0);
+      const b = atom(0);
+      const c = atom(0);
+
+      // Same listener subscribed to all three atoms
+      const sharedListener = vi.fn();
+      a.on(sharedListener);
+      b.on(sharedListener);
+      c.on(sharedListener);
+
+      batch(() => {
+        a.set(1);
+        b.set(1);
+        c.set(1);
+      });
+
+      // Listener should only be called once (deduped), not 3 times
+      expect(sharedListener).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call different listeners separately", () => {
+      const a = atom(0);
+      const b = atom(0);
+
+      const listenerA = vi.fn();
+      const listenerB = vi.fn();
+      a.on(listenerA);
+      b.on(listenerB);
+
+      batch(() => {
+        a.set(1);
+        b.set(1);
+      });
+
+      // Different listeners should each be called once
+      expect(listenerA).toHaveBeenCalledTimes(1);
+      expect(listenerB).toHaveBeenCalledTimes(1);
+    });
+
+    it("should dedupe listener when same atom updated multiple times", () => {
+      const count = atom(0);
+      const listener = vi.fn();
+      count.on(listener);
+
+      batch(() => {
+        count.set(1);
+        count.set(2);
+        count.set(3);
+      });
+
+      // Listener called once at the end with final value
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(count.value).toBe(3);
+    });
+
+    it("should handle mixed scenario with shared and unique listeners", () => {
+      const a = atom(0);
+      const b = atom(0);
+
+      const sharedListener = vi.fn();
+      const uniqueListenerA = vi.fn();
+      const uniqueListenerB = vi.fn();
+
+      a.on(sharedListener);
+      a.on(uniqueListenerA);
+      b.on(sharedListener);
+      b.on(uniqueListenerB);
+
+      batch(() => {
+        a.set(1);
+        b.set(1);
+      });
+
+      // Shared listener deduped to 1 call
+      expect(sharedListener).toHaveBeenCalledTimes(1);
+      // Unique listeners called once each
+      expect(uniqueListenerA).toHaveBeenCalledTimes(1);
+      expect(uniqueListenerB).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/core/batch.ts

@@ -0,0 +1,172 @@
+import { hook } from "./hook";
+import { scheduleNotifyHook } from "./scheduleNotifyHook";
+
+let batchDepth = 0;
+
+/**
+ * Batches multiple state updates into a single reactive update cycle.
+ *
+ * Without batching, each `atom.set()` call triggers immediate notifications to all
+ * subscribers. With `batch()`, all updates are collected and subscribers are notified
+ * once at the end with the final values.
+ *
+ * ## Key Behavior
+ *
+ * 1. **Multiple updates to same atom**: Only 1 notification with final value
+ * 2. **Listener deduplication**: Same listener subscribed to multiple atoms = 1 call
+ * 3. **Nested batches**: Inner batches are merged into outer batch
+ * 4. **Cascading updates**: Updates triggered by listeners are also batched
+ *
+ * ## When to Use
+ *
+ * - Updating multiple related atoms together
+ * - Preventing intermediate render states
+ * - Performance optimization for bulk updates
+ * - Ensuring consistent state during complex operations
+ *
+ * ## How It Works
+ *
+ * ```
+ * batch(() => {
+ *   a.set(1);  // Queued, no notification yet
+ *   b.set(2);  // Queued, no notification yet
+ *   c.set(3);  // Queued, no notification yet
+ * });
+ * // All listeners notified once here (deduped)
+ * ```
+ *
+ * @template T - Return type of the batched function
+ * @param fn - Function containing multiple state updates
+ * @returns The return value of fn
+ *
+ * @example Basic batching - prevent intermediate states
+ * ```ts
+ * const firstName = atom("John");
+ * const lastName = atom("Doe");
+ *
+ * // Without batch: component renders twice (once per set)
+ * firstName.set("Jane");
+ * lastName.set("Smith");
+ *
+ * // With batch: component renders once with final state
+ * batch(() => {
+ *   firstName.set("Jane");
+ *   lastName.set("Smith");
+ * });
+ * ```
+ *
+ * @example Multiple updates to same atom
+ * ```ts
+ * const counter = atom(0);
+ *
+ * counter.on(() => console.log("Counter:", counter.value));
+ *
+ * batch(() => {
+ *   counter.set(1);
+ *   counter.set(2);
+ *   counter.set(3);
+ * });
+ * // Logs once: "Counter: 3"
+ * ```
+ *
+ * @example Listener deduplication
+ * ```ts
+ * const a = atom(0);
+ * const b = atom(0);
+ *
+ * // Same listener subscribed to both atoms
+ * const listener = () => console.log("Changed!", a.value, b.value);
+ * a.on(listener);
+ * b.on(listener);
+ *
+ * batch(() => {
+ *   a.set(1);
+ *   b.set(2);
+ * });
+ * // Logs once: "Changed! 1 2" (not twice)
+ * ```
+ *
+ * @example Nested batches
+ * ```ts
+ * batch(() => {
+ *   a.set(1);
+ *   batch(() => {
+ *     b.set(2);
+ *     c.set(3);
+ *   });
+ *   d.set(4);
+ * });
+ * // All updates batched together, listeners notified once at outer batch end
+ * ```
+ *
+ * @example Return value
+ * ```ts
+ * const result = batch(() => {
+ *   counter.set(10);
+ *   return counter.value * 2;
+ * });
+ * console.log(result); // 20
+ * ```
+ *
+ * @example With async operations (be careful!)
+ * ```ts
+ * // ❌ Wrong: async operations escape the batch
+ * batch(async () => {
+ *   a.set(1);
+ *   await delay(100);
+ *   b.set(2); // This is OUTSIDE the batch!
+ * });
+ *
+ * // ✅ Correct: batch sync operations only
+ * batch(() => {
+ *   a.set(1);
+ *   b.set(2);
+ * });
+ * await delay(100);
+ * batch(() => {
+ *   c.set(3);
+ * });
+ * ```
+ */
+export function batch<T>(fn: () => T): T {
+  batchDepth++;
+
+  // First batch - set up the notification hook with deduping
+  if (batchDepth === 1) {
+    // Use Set to dedupe listeners - if same listener is scheduled multiple times,
+    // it only gets called once (e.g., component subscribed to multiple atoms)
+    let pendingListeners = new Set<VoidFunction>();
+
+    // Schedule listener to be called at batch end (deduped by Set)
+    const scheduleListener = (listener: VoidFunction) => {
+      pendingListeners.add(listener);
+    };
+
+    try {
+      return hook.use([scheduleNotifyHook(() => scheduleListener)], fn);
+    } finally {
+      batchDepth--;
+
+      // Process pending listeners, handling cascading updates
+      // Keep the hook active so any updates triggered by listeners are also batched
+      hook.use([scheduleNotifyHook(() => scheduleListener)], () => {
+        while (pendingListeners.size > 0) {
+          // Snapshot and clear before calling to handle re-entrancy
+          const listeners = pendingListeners;
+          pendingListeners = new Set();
+
+          for (const listener of listeners) {
+            listener();
+          }
+        }
+      });
+    }
+  }
+
+  // Nested batch - just run the function (outer batch handles notifications)
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+  }
+}