Skip to content

Write HTML. Render video. Built for agents.

fix(sdk): drain pending saves and adapter storage on flush (#5285)

Abdullah M. Nazif8efd9ca52326
diff --git a/docs/sdk/reference/utilities.mdx b/docs/sdk/reference/utilities.mdx
index 88144b32f9..a4cbea42ed 100644
--- a/docs/sdk/reference/utilities.mdx
+++ b/docs/sdk/reference/utilities.mdx
@@ -162,7 +162,7 @@ interface PersistQueueModule {
```
<ParamField path="flush" type="() => Promise<void>">
- Cancels any pending debounced write and immediately writes the current serialized HTML to the adapter. Resolves when the write commits. Use before app close or page unload.
+ Immediately saves any pending edit, waits for in-flight saves, and flushes the adapter's storage before resolving. With no pending edit, it flushes storage without writing another version. Use before app close or page unload.
</ParamField>
<ParamField path="dispose" type="() => void">
@@ -183,7 +183,7 @@ interface PersistQueueOptions {
</ParamField>
<ParamField path="onError" type="(e: PersistErrorEvent) => void">
- Called when `adapter.write()` rejects. Receives a `PersistErrorEvent` with `{ error: { message, cause? } }`. Use this to surface persistence failures in your UI or logging layer.
+ Called when `adapter.write()` or `adapter.flush()` rejects. Receives a `PersistErrorEvent` with `{ error: { message, cause? } }`. Use this to surface persistence failures in your UI or logging layer.
</ParamField>
---
diff --git a/packages/sdk/src/persist-queue.ts b/packages/sdk/src/persist-queue.ts
index d8b9d8a7f9..b16598716b 100644
--- a/packages/sdk/src/persist-queue.ts
+++ b/packages/sdk/src/persist-queue.ts
@@ -12,7 +12,7 @@ import type { Composition, PersistErrorEvent } from "./types.js";
import type { PersistAdapter } from "./adapters/types.js";
export interface PersistQueueModule {
- /** Force an immediate write (e.g. before app close). */
+ /** Drain pending writes and adapter storage before app close. */
flush(): Promise<void>;
dispose(): void;
}
@@ -20,7 +20,7 @@ export interface PersistQueueModule {
export interface PersistQueueOptions {
/** Adapter path to write to. Default: "composition.html" */
path?: string;
- /** Called when adapter.write() rejects. */
+ /** Called when adapter.write() or adapter.flush() rejects. */
onError?: (e: PersistErrorEvent) => void;
}
@@ -63,12 +63,22 @@ export function createPersistQueue(
});
return {
- async flush(): Promise<void> {
+ flush(): Promise<void> {
+ if (disposed) return writeChain;
if (pendingWrite !== null) {
clearTimeout(pendingWrite);
pendingWrite = null;
+ void doWrite();
}
- await doWrite();
+ writeChain = writeChain.then(async () => {
+ try {
+ await adapter.flush();
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ opts.onError?.({ error: { message, cause: err } });
+ }
+ });
+ return writeChain;
},
dispose(): void {
diff --git a/packages/sdk/src/smoke.test.ts b/packages/sdk/src/smoke.test.ts
index 9292826165..6b2a0e6837 100644
--- a/packages/sdk/src/smoke.test.ts
+++ b/packages/sdk/src/smoke.test.ts
@@ -9,7 +9,7 @@
* If it breaks, the SDK's public contract has changed.
*/
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, afterEach } from "vitest";
import {
openComposition,
ORIGIN_APPLY_PATCHES,
@@ -221,6 +221,142 @@ describe("undo / redo", () => {
// ─── persist adapter ─────────────────────────────────────────────────────────
describe("persist adapter", () => {
+ function deferredSave() {
+ const adapter = createMemoryAdapter();
+ let release = () => {};
+ const gate = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ return { adapter, write: adapter.write.bind(adapter), gate, release: () => release() };
+ }
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("flushes storage without writing a new version when no edit is pending", async () => {
+ const adapter = createMemoryAdapter();
+ const writeSpy = vi.spyOn(adapter, "write");
+ const flushSpy = vi.spyOn(adapter, "flush");
+ const comp = await openComposition(BASE_HTML, { persist: adapter });
+
+ await comp.flush();
+ expect(writeSpy).not.toHaveBeenCalled();
+ expect(flushSpy).toHaveBeenCalledOnce();
+ expect(await adapter.listVersions("composition.html")).toEqual([]);
+ comp.dispose();
+ });
+
+ it("does not duplicate a saved edit on repeated flushes", async () => {
+ const adapter = createMemoryAdapter();
+ const writeSpy = vi.spyOn(adapter, "write");
+ const comp = await openComposition(BASE_HTML, { persist: adapter });
+ comp.setText("hf-title", "Saved once");
+
+ await comp.flush();
+ await comp.flush();
+ await comp.flush();
+ expect(writeSpy).toHaveBeenCalledOnce();
+ expect(await adapter.listVersions("composition.html")).toHaveLength(1);
+ comp.dispose();
+ });
+
+ it("commits an adapter's buffered save before flush resolves", async () => {
+ const adapter = createMemoryAdapter();
+ const write = adapter.write.bind(adapter);
+ const pending: Array<{ path: string; content: string }> = [];
+ vi.spyOn(adapter, "write").mockImplementation(async (path, content) => {
+ pending.push({ path, content });
+ });
+ const flushSpy = vi.spyOn(adapter, "flush").mockImplementation(async () => {
+ for (const save of pending.splice(0)) await write(save.path, save.content);
+ });
+ const comp = await openComposition(BASE_HTML, { persist: adapter });
+ comp.setText("hf-title", "Durably saved");
+
+ await comp.flush();
+ expect(flushSpy).toHaveBeenCalledOnce();
+ expect(pending).toEqual([]);
+ expect(await adapter.read("composition.html")).toContain("Durably saved");
+ comp.dispose();
+ });
+
+ it("waits for an in-flight autosave without queuing another copy", async () => {
+ vi.useFakeTimers();
+ const { adapter, write, gate, release } = deferredSave();
+ const writeSpy = vi.spyOn(adapter, "write").mockImplementation(async (path, content) => {
+ await gate;
+ await write(path, content);
+ });
+ const flushSpy = vi.spyOn(adapter, "flush");
+ const comp = await openComposition(BASE_HTML, { persist: adapter });
+ comp.setText("hf-title", "In flight");
+ await vi.advanceTimersByTimeAsync(0);
+
+ let settled = false;
+ const flushing = comp.flush().then(() => {
+ settled = true;
+ });
+ await Promise.resolve();
+ expect(settled).toBe(false);
+ expect(flushSpy).not.toHaveBeenCalled();
+ release();
+ await flushing;
+ expect(writeSpy).toHaveBeenCalledOnce();
+ expect(flushSpy).toHaveBeenCalledOnce();
+ expect(await adapter.read("composition.html")).toContain("In flight");
+ comp.dispose();
+ });
+
+ it("keeps adapter flushes and later saves in order", async () => {
+ vi.useFakeTimers();
+ const { adapter, write, gate, release } = deferredSave();
+ const events: string[] = [];
+ vi.spyOn(adapter, "write").mockImplementation(async (path, content) => {
+ events.push(content.includes("First edit") ? "write:first" : "write:second");
+ await write(path, content);
+ });
+ vi.spyOn(adapter, "flush").mockImplementationOnce(async () => {
+ events.push("flush:start");
+ await gate;
+ events.push("flush:end");
+ });
+ const comp = await openComposition(BASE_HTML, { persist: adapter });
+ comp.setText("hf-title", "First edit");
+ const first = comp.flush();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(events).toEqual(["write:first", "flush:start"]);
+
+ comp.setText("hf-title", "Second edit");
+ const second = comp.flush();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(events).toEqual(["write:first", "flush:start"]);
+ release();
+ await Promise.all([first, second]);
+ expect(events).toEqual(["write:first", "flush:start", "flush:end", "write:second"]);
+ expect(await adapter.read("composition.html")).toContain("Second edit");
+ comp.dispose();
+ });
+
+ it("reports an adapter flush failure and permits the next save", async () => {
+ const adapter = createMemoryAdapter();
+ vi.spyOn(adapter, "flush").mockRejectedValueOnce(new Error("storage unavailable"));
+ const comp = await openComposition(BASE_HTML, { persist: adapter });
+ const onError = vi.fn();
+ comp.on("persist:error", onError);
+ comp.setText("hf-title", "First save");
+
+ await expect(comp.flush()).resolves.toBeUndefined();
+ expect(onError).toHaveBeenCalledWith({
+ error: { message: "storage unavailable", cause: expect.any(Error) },
+ });
+ comp.setText("hf-title", "Recovered save");
+ await comp.flush();
+ expect(await adapter.read("composition.html")).toContain("Recovered save");
+ expect(onError).toHaveBeenCalledOnce();
+ comp.dispose();
+ });
+
it("writes serialized HTML to the adapter on mutation", async () => {
const adapter = createMemoryAdapter();
const writeSpy = vi.spyOn(adapter, "write");