@assistant-ui/core 0.3.15 → 0.3.16

package/src/react/interactables-legacy/Interactables.ts

@@ -17,8 +17,7 @@ import { toJSONSchema, toPartialJSONSchema } from "assistant-stream";
 import { ModelContext } from "../../store";
 import { buildInteractableModelContext } from "./interactable-model-context";
 import { notifySubscribers as notifyStateSubscribers } from "../../subscribable/subscribable";
-
-const PERSISTENCE_DEBOUNCE_MS = 500;
+import { useInteractablePersistenceQueue } from "../interactables-shared/useInteractablePersistenceQueue";
 
 const useInteractables = (): ClientOutput<"interactables"> => {
   const [state, setState] = useState<InteractablesState>(() => ({
@@ -48,26 +47,6 @@ const useInteractables = (): ClientOutput<"interactables"> => {
   const adapterRef = useRef<InteractablePersistenceAdapter | undefined>(
     undefined,
   );
-  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
-    undefined,
-  );
-  const syncSeqRef = useRef(0);
-  const latestSyncSeqByIdRef = useRef(new Map<string, number>());
-  const inFlightPersistenceRef = useRef(0);
-  const flushResolversRef = useRef<Array<() => void>>([]);
-  const dirtyIdsRef = useRef(new Set<string>());
-
-  type PersistenceBatch = {
-    adapter: InteractablePersistenceAdapter;
-    payload: InteractablePersistedState;
-    dirtyIds: Set<string>;
-    seq: number;
-  };
-
-  const outgoingQueueRef = useRef<PersistenceBatch[]>([]);
-  const runPersistenceRef = useRef<(batch?: PersistenceBatch) => void>(
-    () => {},
-  );
 
   const exportState = useCallback((): InteractablePersistedState => {
     const result: InteractablePersistedState = {};
@@ -77,139 +56,28 @@ const useInteractables = (): ClientOutput<"interactables"> => {
     return result;
   }, []);
 
-  const takeDirtyBatch = useCallback(
-    (adapter: InteractablePersistenceAdapter): PersistenceBatch | undefined => {
-      if (dirtyIdsRef.current.size === 0) return;
-      const dirtyIds = new Set(dirtyIdsRef.current);
-      dirtyIdsRef.current.clear();
-      const seq = ++syncSeqRef.current;
-      for (const id of dirtyIds) latestSyncSeqByIdRef.current.set(id, seq);
-      return { adapter, payload: exportState(), dirtyIds, seq };
-    },
-    [exportState],
-  );
-
-  const enqueuePersistence = useCallback(
-    (adapter: InteractablePersistenceAdapter) => {
-      const batch = takeDirtyBatch(adapter);
-      if (!batch) return;
-      if (inFlightPersistenceRef.current === 0) {
-        runPersistenceRef.current(batch);
-      } else {
-        outgoingQueueRef.current.push(batch);
-      }
-    },
-    [takeDirtyBatch],
-  );
-
-  const runPersistence = useCallback(
-    async (batch?: PersistenceBatch) => {
-      const resolved =
-        batch ??
-        (adapterRef.current ? takeDirtyBatch(adapterRef.current) : undefined);
-      if (!resolved) {
-        if (inFlightPersistenceRef.current === 0) {
-          for (const resolve of flushResolversRef.current) resolve();
-          flushResolversRef.current = [];
-        }
-        return;
-      }
-
-      const { adapter, payload, dirtyIds, seq } = resolved;
-      inFlightPersistenceRef.current += 1;
-
-      setStateAndRef((prev) => ({
-        ...prev,
-        persistence: {
-          ...prev.persistence,
-          ...Object.fromEntries(
-            [...dirtyIds].map((id) => [
-              id,
-              { isPending: true, error: undefined },
-            ]),
-          ),
-        },
-      }));
-
-      try {
-        await adapter.save(payload);
-        setStateAndRef((prev) => {
-          let changed = false;
-          const persistence = { ...prev.persistence };
-          for (const id of dirtyIds) {
-            if (
-              latestSyncSeqByIdRef.current.get(id) !== seq ||
-              dirtyIdsRef.current.has(id)
-            )
-              continue;
-            latestSyncSeqByIdRef.current.delete(id);
-            delete persistence[id];
-            changed = true;
-          }
-          return changed ? { ...prev, persistence } : prev;
-        });
-      } catch (e) {
-        setStateAndRef((prev) => {
-          let changed = false;
-          const persistence = { ...prev.persistence };
-          for (const id of dirtyIds) {
-            if (
-              latestSyncSeqByIdRef.current.get(id) !== seq ||
-              dirtyIdsRef.current.has(id)
-            )
-              continue;
-            latestSyncSeqByIdRef.current.delete(id);
-            persistence[id] = { isPending: false, error: e };
-            changed = true;
-          }
-          return changed ? { ...prev, persistence } : prev;
-        });
-      } finally {
-        inFlightPersistenceRef.current -= 1;
-        const next =
-          outgoingQueueRef.current.shift() ??
-          (adapterRef.current && dirtyIdsRef.current.size > 0
-            ? takeDirtyBatch(adapterRef.current)
-            : undefined);
-        if (next) {
-          if (debounceTimerRef.current !== undefined) {
-            clearTimeout(debounceTimerRef.current);
-            debounceTimerRef.current = undefined;
-          }
-          runPersistenceRef.current(next);
-        } else if (inFlightPersistenceRef.current === 0) {
-          for (const resolve of flushResolversRef.current) resolve();
-          flushResolversRef.current = [];
-        }
-      }
+  const updatePersistenceStatus = useCallback(
+    (
+      updater: (
+        prev: InteractablesState["persistence"],
+      ) => InteractablesState["persistence"],
+    ) => {
+      setStateAndRef((prev) => {
+        const persistence = updater(prev.persistence);
+        return persistence === prev.persistence
+          ? prev
+          : { ...prev, persistence };
+      });
     },
-    [setStateAndRef, takeDirtyBatch],
+    [setStateAndRef],
   );
-  runPersistenceRef.current = (nextBatch) => {
-    void runPersistence(nextBatch);
-  };
 
-  const schedulePersistence = useCallback(
-    (id: string) => {
-      if (!adapterRef.current) return;
-      dirtyIdsRef.current.add(id);
-      if (debounceTimerRef.current !== undefined) {
-        clearTimeout(debounceTimerRef.current);
-      }
-      debounceTimerRef.current = setTimeout(() => {
-        debounceTimerRef.current = undefined;
-        if (inFlightPersistenceRef.current === 0 && adapterRef.current) {
-          enqueuePersistence(adapterRef.current);
-        } else {
-          debounceTimerRef.current = setTimeout(() => {
-            debounceTimerRef.current = undefined;
-            if (adapterRef.current) enqueuePersistence(adapterRef.current);
-          }, PERSISTENCE_DEBOUNCE_MS);
-        }
-      }, PERSISTENCE_DEBOUNCE_MS);
-    },
-    [enqueuePersistence],
-  );
+  const { flushIfPending, schedulePersistence, flush } =
+    useInteractablePersistenceQueue({
+      adapterRef,
+      snapshot: exportState,
+      updatePersistenceStatus,
+    });
 
   const importState = useCallback(
     (saved: InteractablePersistedState) => {
@@ -231,31 +99,6 @@ const useInteractables = (): ClientOutput<"interactables"> => {
     [setStateAndRef],
   );
 
-  const flushIfPending = useCallback(() => {
-    if (debounceTimerRef.current !== undefined) {
-      clearTimeout(debounceTimerRef.current);
-      debounceTimerRef.current = undefined;
-    }
-    if (adapterRef.current) enqueuePersistence(adapterRef.current);
-  }, [enqueuePersistence]);
-
-  const flush = useCallback(async () => {
-    if (debounceTimerRef.current !== undefined) {
-      clearTimeout(debounceTimerRef.current);
-      debounceTimerRef.current = undefined;
-    }
-    const hasWork =
-      inFlightPersistenceRef.current > 0 ||
-      dirtyIdsRef.current.size > 0 ||
-      outgoingQueueRef.current.length > 0;
-    if (!hasWork) return;
-    const p = new Promise<void>((resolve) => {
-      flushResolversRef.current.push(resolve);
-    });
-    if (adapterRef.current) enqueuePersistence(adapterRef.current);
-    return p;
-  }, [enqueuePersistence]);
-
   const setPersistenceAdapter = useCallback(
     (adapter: InteractablePersistenceAdapter | undefined) => {
       if (adapterRef.current !== adapter) flushIfPending();

package/src/react/interactables-shared/useInteractablePersistenceQueue.test.tsx

@@ -0,0 +1,161 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useInteractablePersistenceQueue } from "./useInteractablePersistenceQueue";
+
+type TestState = Record<string, number>;
+
+type PersistenceStatus = {
+  isPending: boolean;
+  error: unknown;
+};
+
+type PersistenceStatusMap = Record<string, PersistenceStatus>;
+
+const createDeferred = () => {
+  let resolve!: () => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<void>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+};
+
+const renderQueue = (save: (state: TestState) => void | Promise<void>) => {
+  let snapshot: TestState = {};
+  let persistence: PersistenceStatusMap = {};
+  const adapterRef = { current: { save } };
+  const updatePersistenceStatus = (
+    updater: (prev: PersistenceStatusMap) => PersistenceStatusMap,
+  ) => {
+    persistence = updater(persistence);
+  };
+  const hook = renderHook(() =>
+    useInteractablePersistenceQueue({
+      adapterRef,
+      snapshot: () => snapshot,
+      updatePersistenceStatus,
+    }),
+  );
+
+  return {
+    ...hook,
+    setState(id: string, value: number) {
+      snapshot = { ...snapshot, [id]: value };
+    },
+    removeStatus(id: string) {
+      const { [id]: _, ...rest } = persistence;
+      persistence = rest;
+    },
+    getStatus() {
+      return persistence;
+    },
+  };
+};
+
+const flushMicrotasks = () => vi.advanceTimersByTimeAsync(0);
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("useInteractablePersistenceQueue", () => {
+  it("coalesces dirty marks inside the debounce window into one save", async () => {
+    const save = vi.fn<(state: TestState) => void>();
+    const queue = renderQueue(save);
+
+    queue.setState("a", 1);
+    act(() => queue.result.current.schedulePersistence("a"));
+    await act(() => vi.advanceTimersByTimeAsync(200));
+
+    queue.setState("b", 2);
+    act(() => queue.result.current.schedulePersistence("b"));
+    await act(() => vi.advanceTimersByTimeAsync(200));
+
+    queue.setState("a", 3);
+    act(() => queue.result.current.schedulePersistence("a"));
+    await act(() => vi.advanceTimersByTimeAsync(499));
+
+    expect(save).not.toHaveBeenCalled();
+
+    await act(() => vi.advanceTimersByTimeAsync(1));
+
+    expect(save).toHaveBeenCalledOnce();
+    expect(save).toHaveBeenCalledWith({ a: 3, b: 2 });
+  });
+
+  it("attributes errors by batch sequence and lets a newer save supersede an older error", async () => {
+    const first = createDeferred();
+    const second = createDeferred();
+    const firstError = new Error("first save failed");
+    const secondError = new Error("second save failed");
+    const save = vi
+      .fn<(state: TestState) => Promise<void>>()
+      .mockImplementationOnce(() => first.promise)
+      .mockImplementationOnce(() => second.promise);
+    const queue = renderQueue(save);
+
+    queue.setState("a", 1);
+    queue.setState("b", 1);
+    act(() => {
+      queue.result.current.schedulePersistence("a");
+      queue.result.current.schedulePersistence("b");
+    });
+    await act(() => vi.advanceTimersByTimeAsync(500));
+
+    queue.setState("a", 2);
+    act(() => queue.result.current.schedulePersistence("a"));
+    let flushPromise!: Promise<void>;
+    act(() => {
+      flushPromise = queue.result.current.flush();
+    });
+
+    first.reject(firstError);
+    await act(flushMicrotasks);
+
+    expect(save).toHaveBeenCalledTimes(2);
+    expect(queue.getStatus()).toEqual({
+      a: { isPending: true, error: undefined },
+      b: { isPending: false, error: firstError },
+    });
+
+    second.reject(secondError);
+    await act(flushMicrotasks);
+    await flushPromise;
+
+    expect(queue.getStatus()).toEqual({
+      a: { isPending: false, error: secondError },
+      b: { isPending: false, error: firstError },
+    });
+  });
+
+  it("does not recreate a removed status when an in-flight save rejects", async () => {
+    const pending = createDeferred();
+    const save = vi
+      .fn<(state: TestState) => Promise<void>>()
+      .mockImplementationOnce(() => pending.promise);
+    const queue = renderQueue(save);
+
+    queue.setState("removed", 1);
+    act(() => queue.result.current.schedulePersistence("removed"));
+    await act(() => vi.advanceTimersByTimeAsync(500));
+
+    expect(queue.getStatus()).toEqual({
+      removed: { isPending: true, error: undefined },
+    });
+
+    queue.removeStatus("removed");
+    pending.reject(new Error("save failed"));
+    await act(flushMicrotasks);
+
+    expect(queue.getStatus()).toEqual({});
+  });
+});

package/src/react/interactables-shared/useInteractablePersistenceQueue.ts

@@ -0,0 +1,206 @@
+import { useCallback, useRef, type RefObject } from "react";
+
+const PERSISTENCE_DEBOUNCE_MS = 500;
+
+type PersistenceAdapter<State> = {
+  save(state: State): void | Promise<void>;
+};
+
+type PersistenceStatus = {
+  isPending: boolean;
+  error: unknown;
+};
+
+type PersistenceStatusMap = Record<string, PersistenceStatus>;
+
+type PersistenceStatusUpdater = (
+  updater: (prev: PersistenceStatusMap) => PersistenceStatusMap,
+) => void;
+
+type UseInteractablePersistenceQueueOptions<State> = {
+  adapterRef: RefObject<PersistenceAdapter<State> | undefined>;
+  snapshot: () => State;
+  updatePersistenceStatus: PersistenceStatusUpdater;
+};
+
+export const useInteractablePersistenceQueue = <State>({
+  adapterRef,
+  snapshot,
+  updatePersistenceStatus,
+}: UseInteractablePersistenceQueueOptions<State>) => {
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+  const syncSeqRef = useRef(0);
+  const latestSyncSeqByIdRef = useRef(new Map<string, number>());
+  const inFlightPersistenceRef = useRef(0);
+  const flushResolversRef = useRef<Array<() => void>>([]);
+  const dirtyIdsRef = useRef(new Set<string>());
+
+  type PersistenceBatch = {
+    adapter: PersistenceAdapter<State>;
+    payload: State;
+    dirtyIds: Set<string>;
+    seq: number;
+  };
+
+  const outgoingQueueRef = useRef<PersistenceBatch[]>([]);
+  const runPersistenceRef = useRef<(batch?: PersistenceBatch) => void>(
+    () => {},
+  );
+
+  const takeDirtyBatch = useCallback(
+    (adapter: PersistenceAdapter<State>): PersistenceBatch | undefined => {
+      if (dirtyIdsRef.current.size === 0) return;
+      const dirtyIds = new Set(dirtyIdsRef.current);
+      dirtyIdsRef.current.clear();
+      const seq = ++syncSeqRef.current;
+      for (const id of dirtyIds) latestSyncSeqByIdRef.current.set(id, seq);
+      return { adapter, payload: snapshot(), dirtyIds, seq };
+    },
+    [snapshot],
+  );
+
+  const enqueuePersistence = useCallback(
+    (adapter: PersistenceAdapter<State>) => {
+      const batch = takeDirtyBatch(adapter);
+      if (!batch) return;
+      if (inFlightPersistenceRef.current === 0) {
+        runPersistenceRef.current(batch);
+      } else {
+        outgoingQueueRef.current.push(batch);
+      }
+    },
+    [takeDirtyBatch],
+  );
+
+  const runPersistence = useCallback(
+    async (batch?: PersistenceBatch) => {
+      const resolved =
+        batch ??
+        (adapterRef.current ? takeDirtyBatch(adapterRef.current) : undefined);
+      if (!resolved) {
+        if (inFlightPersistenceRef.current === 0) {
+          for (const resolve of flushResolversRef.current) resolve();
+          flushResolversRef.current = [];
+        }
+        return;
+      }
+
+      const { adapter, payload, dirtyIds, seq } = resolved;
+      inFlightPersistenceRef.current += 1;
+
+      updatePersistenceStatus((prev) => ({
+        ...prev,
+        ...Object.fromEntries(
+          [...dirtyIds].map((id) => [
+            id,
+            { isPending: true, error: undefined },
+          ]),
+        ),
+      }));
+
+      const settleBatch = (status: PersistenceStatus | undefined) => {
+        const settledIds: string[] = [];
+        for (const id of dirtyIds) {
+          if (
+            latestSyncSeqByIdRef.current.get(id) !== seq ||
+            dirtyIdsRef.current.has(id)
+          )
+            continue;
+          latestSyncSeqByIdRef.current.delete(id);
+          settledIds.push(id);
+        }
+        if (settledIds.length === 0) return;
+        updatePersistenceStatus((prev) => {
+          let changed = false;
+          const persistence = { ...prev };
+          for (const id of settledIds) {
+            if (prev[id] === undefined) continue;
+            if (status === undefined) delete persistence[id];
+            else persistence[id] = status;
+            changed = true;
+          }
+          return changed ? persistence : prev;
+        });
+      };
+
+      try {
+        await adapter.save(payload);
+        settleBatch(undefined);
+      } catch (e) {
+        settleBatch({ isPending: false, error: e });
+      } finally {
+        inFlightPersistenceRef.current -= 1;
+        const next =
+          outgoingQueueRef.current.shift() ??
+          (adapterRef.current && dirtyIdsRef.current.size > 0
+            ? takeDirtyBatch(adapterRef.current)
+            : undefined);
+        if (next) {
+          if (debounceTimerRef.current !== undefined) {
+            clearTimeout(debounceTimerRef.current);
+            debounceTimerRef.current = undefined;
+          }
+          runPersistenceRef.current(next);
+        } else if (inFlightPersistenceRef.current === 0) {
+          for (const resolve of flushResolversRef.current) resolve();
+          flushResolversRef.current = [];
+        }
+      }
+    },
+    [adapterRef, takeDirtyBatch, updatePersistenceStatus],
+  );
+  runPersistenceRef.current = (nextBatch) => {
+    void runPersistence(nextBatch);
+  };
+
+  const flushIfPending = useCallback(() => {
+    if (debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+    }
+    if (adapterRef.current) enqueuePersistence(adapterRef.current);
+  }, [adapterRef, enqueuePersistence]);
+
+  const schedulePersistence = useCallback(
+    (id: string) => {
+      if (!adapterRef.current) return;
+      dirtyIdsRef.current.add(id);
+      if (debounceTimerRef.current !== undefined) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        debounceTimerRef.current = undefined;
+        if (inFlightPersistenceRef.current === 0 && adapterRef.current) {
+          enqueuePersistence(adapterRef.current);
+        } else {
+          debounceTimerRef.current = setTimeout(() => {
+            debounceTimerRef.current = undefined;
+            if (adapterRef.current) enqueuePersistence(adapterRef.current);
+          }, PERSISTENCE_DEBOUNCE_MS);
+        }
+      }, PERSISTENCE_DEBOUNCE_MS);
+    },
+    [adapterRef, enqueuePersistence],
+  );
+
+  const flush = useCallback(async () => {
+    if (debounceTimerRef.current !== undefined) {
+      clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = undefined;
+    }
+    const hasWork =
+      inFlightPersistenceRef.current > 0 ||
+      dirtyIdsRef.current.size > 0 ||
+      outgoingQueueRef.current.length > 0;
+    if (!hasWork) return;
+    const p = new Promise<void>((resolve) => {
+      flushResolversRef.current.push(resolve);
+    });
+    if (adapterRef.current) enqueuePersistence(adapterRef.current);
+    return p;
+  }, [adapterRef, enqueuePersistence]);
+
+  return { flushIfPending, schedulePersistence, flush };
+};