block-save-queue.ts

block-save-queue.tsapps/web/src/components/editor/block-save-queue.tsraw ← editor2,635 B← Back to the app
1"use client";
2 
3/**
4 * useBlockSaveQueue — React binding for the shared per-page
5 * BlockBatchQueue (lib/batch-queue.ts).
6 *
7 * `queueChange(blockId, content)` debounces (500 ms) into one
8 * POST /blocks/batch. `saveNow(blockId, content)` persists a single block
9 * immediately (blur fallback) and drops the queued copy of it so the final
10 * state never depends on the debounce window closing. The shared queue is
11 * also flushed on unmount.
12 */
13import { useCallback, useEffect, useRef } from "react";
14import { useQueryClient } from "@tanstack/react-query";
15import { blockApi, isApiError } from "@/lib/api";
16import { getBlockBatchQueue } from "@/lib/batch-queue";
17 
18export function useBlockSaveQueue(pageId: string) {
19  const qc = useQueryClient();
20  const pageIdRef = useRef(pageId);
21  pageIdRef.current = pageId;
22 
23  const invalidate = useCallback(
24    (pid: string) => qc.invalidateQueries({ queryKey: ["pages", pid, "blocks"] }),
25    [qc]
26  );
27 
28  const queueChange = useCallback(
29    (blockId: string, content: unknown) => {
30      const id = pageIdRef.current;
31      if (!id) return;
32      getBlockBatchQueue(id).queue({ op: "update", blockId, patch: { content } });
33    },
34    []
35  );
36 
37  const saveNow = useCallback(
38    async (blockId: string, content: unknown) => {
39      const id = pageIdRef.current;
40      if (!id) return;
41      try {
42        await blockApi.update(blockId, { content });
43        invalidate(id);
44      } catch (err) {
45        // TASK-0136: a 404 is NOT transient — the block is gone (the
46        // delete-on-blur cleanup removed it while this blur save was
47        // in flight, or a concurrent peer deleted it). Re-queueing would
48        // poison the next batch flush (the batch endpoint 400s on a
49        // missing id and aborts the whole batch). Drop it instead.
50        if (isApiError(err) && err.status === 404) return;
51        // Transient failure: re-queue so the next flush retries.
52        getBlockBatchQueue(id).queue({ op: "update", blockId, patch: { content } });
53      }
54    },
55    [invalidate]
56  );
57 
58  // Flush pending ops when this page unmounts (no lost edits on navigation).
59  useEffect(() => {
60    const id = pageIdRef.current;
61    return () => {
62      if (!id) return;
63      void getBlockBatchQueue(id).flush().then(() => invalidate(id));
64    };
65    // eslint-disable-next-line react-hooks/exhaustive-deps
66  }, [pageId]);
67 
68  // Exposed for property-only updates (e.g. the table grid's add/remove
69  // row/col, which patch `properties` directly and otherwise leave the
70  // ["pages", pageId, "blocks"] cache stale until the next refetch).
71  return { queueChange, saveNow, invalidate };
72}
73