batch-queue.ts · Source

batch-queue.tsapps/web/src/lib/batch-queue.tsraw ← lib3,314 B← Back to the app
1"use client";
2 
3/**
4 * BlockBatchQueue — the debounced, order-preserving block-save queue.
5 *
6 * Domain logic is kept OUT of React (AGENTS.md: keep domain logic
7 * independent of UI): the queue is a plain class, one instance per page
8 * (shared between the editor's useBlockSaveQueue and the useBatchSave hook
9 * so they never double-flush). Ops are appended FIFO and flushed as ONE
10 * POST /blocks/batch at most `debounceMs` after the last enqueue. On a
11 * failed flush the ops are re-queued (ahead of any newer ops) so a
12 * transient failure retries on the next change / unmount flush.
13 */
14import { blockApi, type BatchBlockOp } from "./api";
15import { BLOCK_SAVE_DEBOUNCE_MS } from "./constants";
16 
17export class BlockBatchQueue {
18  private ops: BatchBlockOp[] = [];
19  private timer: ReturnType<typeof setTimeout> | null = null;
20  private inFlight: Promise<void> | null = null;
21 
22  constructor(
23    private readonly pageId: string,
24    private readonly debounceMs: number = BLOCK_SAVE_DEBOUNCE_MS
25  ) {}
26 
27  get pendingCount(): number {
28    return this.ops.length;
29  }
30 
31  /** Enqueue one or more ops; (re)arms the debounce timer. */
32  queue(op: BatchBlockOp | BatchBlockOp[]): void {
33    this.ops.push(...(Array.isArray(op) ? op : [op]));
34    if (this.timer) clearTimeout(this.timer);
35    this.timer = setTimeout(() => {
36      void this.flush();
37    }, this.debounceMs);
38  }
39 
40  /** Flush immediately (navigation, unmount). Resolves when the batch lands. */
41  flush(): Promise<void> {
42    if (this.timer) {
43      clearTimeout(this.timer);
44      this.timer = null;
45    }
46    if (this.ops.length === 0) return Promise.resolve();
47    const ops = this.ops.splice(0, this.ops.length);
48    this.inFlight = blockApi
49      .batch(this.pageId, ops)
50      .catch(() => {
51        // Re-queue ahead of anything newer; the next change or unmount
52        // flush retries. (Block content is last-writer-wins, so replaying
53        // the same ops is safe.)
54        this.ops = [...ops, ...this.ops];
55      })
56      .finally(() => {
57        this.inFlight = null;
58      });
59    return this.inFlight;
60  }
61 
62  /**
63   * Drop all pending (not-yet-flushed) ops that touch one block — e.g. the
64   * editor's delete-on-blur cleanup removed a block that still has a
65   * debounced content save queued. Without this the next flush would send a
66   * `update` for a deleted id and the batch endpoint 400s (the op is
67   * validated against the row), aborting the whole batch including the
68   * delete's own flush.
69   */
70  dropBlock(blockId: string): void {
71    if (this.ops.length === 0) return;
72    this.ops = this.ops.filter((op) => op.blockId !== blockId && op.block?.id !== blockId);
73  }
74 
75  /** Cancel any pending debounce without flushing (page discarded). */
76  dispose(): void {
77    if (this.timer) {
78      clearTimeout(this.timer);
79      this.timer = null;
80    }
81  }
82}
83 
84const queues = new Map<string, BlockBatchQueue>();
85 
86/** Shared per-page queue instance (the whole tab edits one page at a time). */
87export function getBlockBatchQueue(pageId: string, debounceMs?: number): BlockBatchQueue {
88  let q = queues.get(pageId);
89  if (!q) {
90    q = new BlockBatchQueue(pageId, debounceMs);
91    queues.set(pageId, q);
92  }
93  return q;
94}
95 
96/** Test hook: drop all page queues. */
97export function resetBlockBatchQueues(): void {
98  queues.clear();
99}
100