codec.ts · Source

codec.tspackages/editor/src/codec.tsraw ← src13,715 B← Back to the app
1/**
2 * @factory/editor — the block tree ↔ document codec (TASK-0047 R3).
3 *
4 * The canonical editor document is a nested object in which every block is
5 * one `factoryBlock` node carrying `{id, position, type, content, properties}`
6 * as attrs and child blocks as `content`. The codec is:
7 *
8 *   - **pure** — no I/O, no DOM, no tiptap;
9 *   - **deterministic** — siblings are always ordered by fractional
10 *     `position` (`comparePositions` from `@factory/shared/positions`);
11 *   - **lossless** — `docToBlocks(blocksToDoc(forest))` reproduces the
12 *     forest's ids, parent links, positions, content and properties
13 *     byte-identically (unit-tested as a property test).
14 *
15 * The document shape is ProseMirror-compatible (so a real `ProseMirror.Doc`
16 * built from it round-trips through `doc.toJSON()`), but this module never
17 * imports ProseMirror — it operates on the JSON representation.
18 *
19 * Persistence note: `docToBlocks` returns the canonical block set (not ops);
20 * the wire op set for autosave is produced by {@link diffBlocks} (insert /
21 * update / move / delete), which is what the 800 ms autosave batch emits.
22 */
23 
24import { comparePositions, type Position } from "@factory/shared/positions";
25import type { BlockContentByType, BlockType } from "@factory/shared/dto";
26 
27import type { BlockDto, EditorBlockOperation, NewBlock } from "./types.js";
28 
29/** A node of the canonical (JSON) document. */
30export interface FactoryDocNode {
31  readonly type: string;
32  readonly attrs?: Readonly<Record<string, unknown>>;
33  readonly content?: readonly FactoryDocNode[];
34}
35 
36/** The canonical document root. */
37export interface FactoryDoc {
38  readonly type: "doc";
39  readonly content: readonly FactoryDocNode[];
40}
41 
42/** Node type name for every block in the canonical document. */
43export const BLOCK_NODE_TYPE = "factoryBlock";
44 
45/**
46 * Generate a client-side block id. The server assigns ids on insert; the
47 * client only mints ids for optimistic local state and pasted external
48 * content (TASK-0047 R2 — never regenerated for an existing block).
49 */
50export function generateBlockId(): string {
51  // Client-local optimistic ids only (the server assigns authoritative
52  // ids on insert — TASK-0047 R2). 32 hex chars from the PRNG; no crypto
53  // dependency (this module is pure + node-testable).
54  let suffix = "";
55  for (let i = 0; i < 32; i += 1) {
56    suffix += Math.floor(Math.random() * 16).toString(16);
57  }
58  return `blk_${suffix}`;
59}
60 
61/** Sibling sort key: fractional position (never array index, ADR-002). */
62function byPosition(a: { position: Position }, b: { position: Position }): number {
63  return comparePositions(a.position, b.position);
64}
65 
66function isDoc(node: unknown): node is FactoryDoc {
67  return (
68    typeof node === "object" &&
69    node !== null &&
70    (node as { type?: unknown }).type === "doc" &&
71    Array.isArray((node as { content?: unknown }).content)
72  );
73}
74 
75function isBlockNode(node: unknown): node is FactoryDocNode {
76  return (
77    typeof node === "object" &&
78    node !== null &&
79    (node as { type?: unknown }).type === BLOCK_NODE_TYPE
80  );
81}
82 
83function attrsOf(node: FactoryDocNode): Record<string, unknown> {
84  return (node.attrs ?? {}) as Record<string, unknown>;
85}
86 
87/**
88 * Build the canonical nested document from a flat block forest.
89 *
90 * Siblings are sorted by `position`; children nest under their parent's
91 * `content`. Throws on duplicate ids or a block whose parent is missing
92 * (invalid input — fail loud rather than guess).
93 */
94export function blocksToDoc(blocks: readonly BlockDto[]): FactoryDoc {
95  const seen = new Set<string>();
96  for (const block of blocks) {
97    if (seen.has(block.id)) {
98      throw new Error(`blocksToDoc: duplicate block id "${block.id}"`);
99    }
100    seen.add(block.id);
101  }
102 
103  const childrenByParent = new Map<string | null, BlockDto[]>();
104  for (const block of blocks) {
105    const parent = block.parentId;
106    if (parent !== null && !seen.has(parent)) {
107      throw new Error(
108        `blocksToDoc: block "${block.id}" references missing parent "${parent}"`,
109      );
110    }
111    const list = childrenByParent.get(parent) ?? [];
112    list.push(block);
113    childrenByParent.set(parent, list);
114  }
115 
116  const toNode = (block: BlockDto): FactoryDocNode => {
117    const attrs: Record<string, unknown> = {
118      id: block.id,
119      position: block.position,
120      type: block.type,
121      content: block.content,
122    };
123    if (block.properties !== undefined) {
124      attrs.properties = block.properties;
125    }
126    const children = (childrenByParent.get(block.id) ?? []).slice().sort(byPosition);
127    // FactoryDocNode is fully readonly — build the complete literal (a
128    // `node.content = …` assignment is not allowed on it).
129    const node: FactoryDocNode = {
130      type: BLOCK_NODE_TYPE,
131      attrs,
132      ...(children.length > 0 ? { content: children.map(toNode) } : {}),
133    };
134    return node;
135  };
136 
137  const roots = (childrenByParent.get(null) ?? []).slice().sort(byPosition);
138  return { type: "doc", content: roots.map(toNode) };
139}
140 
141/**
142 * Flatten the canonical document back to the block forest (DFS, children
143 * immediately after their parent, siblings in `position` order). Unknown
144 * node types throw (a Factory document contains only `factoryBlock`).
145 */
146export function docToBlocks(doc: unknown): BlockLike[] {
147  if (!isDoc(doc)) {
148    throw new Error("docToBlocks: expected a {type: 'doc', content: []} document");
149  }
150  const out: BlockLike[] = [];
151  const walk = (nodes: readonly FactoryDocNode[] | undefined, parentId: string | null): void => {
152    for (const node of nodes ?? []) {
153      if (!isBlockNode(node)) {
154        throw new Error(`docToBlocks: unexpected node type "${String((node as { type?: unknown }).type)}"`);
155      }
156      const attrs = attrsOf(node);
157      const type = attrs.type as BlockType | undefined;
158      const position = attrs.position as Position | undefined;
159      const content = attrs.content as BlockContentByType[BlockType] | undefined;
160      const id = attrs.id as string | undefined;
161      if (type === undefined || position === undefined || content === undefined || id === undefined) {
162        throw new Error(
163          `docToBlocks: block node "${String(attrs.id)}" is missing id/type/position/content attrs`,
164        );
165      }
166      const properties = attrs.properties as Record<string, unknown> | undefined;
167      // Returns id-bearing blocks (BlockLike, not NewBlock): the codec's
168      // lossless contract reproduces the forest's ids — the wire op set
169      // (toOperations) is what drops the id (insert carries no id).
170      const block: BlockLike = {
171        id,
172        type,
173        content,
174        parentId,
175        position,
176        ...(properties !== undefined ? { properties } : {}),
177      };
178      out.push(block);
179      walk(node.content, id);
180    }
181  };
182  walk(doc.content, null);
183  return out;
184}
185 
186/** Deep, deterministic equality for plain-JSON values (content/properties). */
187export function jsonEqual(a: unknown, b: unknown): boolean {
188  if (a === b) return true;
189  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") {
190    return false;
191  }
192  const ka = Object.keys(a as Record<string, unknown>).sort();
193  const kb = Object.keys(b as Record<string, unknown>).sort();
194  if (ka.length !== kb.length || ka.some((k, i) => k !== kb[i])) return false;
195  return ka.every((k) =>
196    jsonEqual(
197      (a as Record<string, unknown>)[k],
198      (b as Record<string, unknown>)[k],
199    ),
200  );
201}
202 
203export interface BlockDiff {
204  readonly deletes: readonly string[];
205  readonly updates: readonly {
206    readonly id: string;
207    readonly patch: {
208      readonly content?: Record<string, unknown>;
209      readonly properties?: Record<string, unknown>;
210    };
211  }[];
212  readonly moves: readonly {
213    readonly id: string;
214    readonly before?: string;
215    readonly after?: string;
216    readonly toPageId?: string;
217  }[];
218  readonly inserts: readonly BlockLike[];
219  /** Deletes + updates + moves + inserts, in send order (see {@link toOperations}). */
220  readonly operations: EditorBlockOperation[];
221}
222 
223type BlockLike = Pick<BlockDto, "id" | "type" | "content" | "properties" | "parentId" | "position">;
224 
225/**
226 * Minimal op diff between two same-page block sets, in the exact wire
227 * format of `@factory/shared`'s `blockOperationSchema`
228 * (`insert | update | move | delete`).
229 *
230 * - `move.before` / `move.after` are sibling ids in the *destination* order
231 *   (at most one — the wire contract); the parent is implicit from the
232 *   anchor sibling. (Wire gap, recorded: the shared `moveOp` has no
233 *   `parentId` field, so a move into an *empty* new parent cannot be
234 *   anchored — see the package README; the API's `move target.parentId`
235 *   variant is not modeled by the shared DTO yet.)
236 * - A block may appear in both `updates` and `moves` (content and placement
237 *   changed) — independent, both idempotent.
238 * - Send order: deletes → updates → moves → inserts (inserts last so their
239 *   `before`/`after` anchors exist after the moves applied).
240 */
241export function diffBlocks(
242  previous: readonly BlockLike[],
243  next: readonly BlockLike[],
244): BlockDiff {
245  const prevById = new Map<string, BlockLike>();
246  for (const b of previous) prevById.set(b.id, b);
247  const nextById = new Map<string, BlockLike>();
248  for (const b of next) nextById.set(b.id, b);
249 
250  const deletes = previous.filter((b) => !nextById.has(b.id)).map((b) => b.id);
251  const inserts = next.filter((b) => !prevById.has(b.id));
252 
253  const updates: {
254    id: string;
255    patch: { content?: Record<string, unknown>; properties?: Record<string, unknown> };
256  }[] = [];
257  const moves: { id: string; before?: string; after?: string; toPageId?: string }[] = [];
258 
259  // Sibling order in `next` (per parent) → before/after anchor ids.
260  const byParent = new Map<string | null, BlockLike[]>();
261  for (const b of next) {
262    const list = byParent.get(b.parentId) ?? [];
263    list.push(b);
264    byParent.set(b.parentId, list);
265  }
266  for (const list of byParent.values()) list.sort(byPosition);
267 
268  for (const [id, nb] of nextById) {
269    const pb = prevById.get(id);
270    if (pb === undefined) continue;
271    const contentChanged = !jsonEqual(pb.content, nb.content);
272    const propertiesChanged =
273      (pb.properties === undefined) !== (nb.properties === undefined) ||
274      (pb.properties !== undefined &&
275        nb.properties !== undefined &&
276        !jsonEqual(pb.properties, nb.properties));
277    if (contentChanged || propertiesChanged) {
278      const patch: { content?: Record<string, unknown>; properties?: Record<string, unknown> } = {};
279      if (contentChanged) patch.content = nb.content as Record<string, unknown>;
280      if (propertiesChanged && nb.properties !== undefined) patch.properties = nb.properties;
281      updates.push({ id, patch });
282    }
283    const moved = pb.position !== nb.position || pb.parentId !== nb.parentId;
284    if (moved) {
285      const siblings = byParent.get(nb.parentId) ?? [];
286      const idx = siblings.findIndex((s) => s.id === id);
287      const before = idx > 0 ? siblings[idx - 1]?.id : undefined;
288      const after = idx >= 0 && idx < siblings.length - 1 ? siblings[idx + 1]?.id : undefined;
289      // A cross-parent move with no anchors on the destination side is
290      // still a move (the server resolves end-of-list for that parent).
291      if (before !== undefined || after !== undefined || pb.parentId !== nb.parentId) {
292        const move: { id: string; before?: string; after?: string } = { id };
293        if (before !== undefined) move.before = before;
294        if (after !== undefined) move.after = after;
295        moves.push(move);
296      }
297    }
298  }
299 
300  return { deletes, updates, moves, inserts, operations: toOperations(deletes, updates, moves, inserts) };
301}
302 
303/** Assemble the diff into wire `BlockOperation`s (the autosave batch body). */
304export function toOperations(
305  deletes: readonly string[],
306  updates: readonly {
307    readonly id: string;
308    readonly patch: {
309      readonly content?: Record<string, unknown>;
310      readonly properties?: Record<string, unknown>;
311    };
312  }[],
313  moves: readonly {
314    readonly id: string;
315    readonly before?: string;
316    readonly after?: string;
317    readonly toPageId?: string;
318  }[],
319  // Accepts both the id-bearing `BlockLike` (from diffBlocks.inserts) and
320  // the id-less `NewBlock` (a client-built insert); the wire op drops the id.
321  inserts: readonly (NewBlock | BlockLike)[],
322): EditorBlockOperation[] {
323  const ops: EditorBlockOperation[] = [];
324  for (const id of deletes) ops.push({ op: "delete", id });
325  for (const u of updates) ops.push({ op: "update", id: u.id, patch: u.patch });
326  for (const m of moves) {
327    // Wire contract: at most one of before/after (the shared
328    // blockOperationSchema's superRefine). Prefer the `before` anchor;
329    // fall back to `after` when the block leads its destination siblings.
330    const move: { op: "move"; id: string; before?: string; after?: string } = { op: "move", id: m.id };
331    if (m.before !== undefined) move.before = m.before;
332    else if (m.after !== undefined) move.after = m.after;
333    ops.push(move);
334  }
335  for (const b of inserts) {
336    const block: {
337      op: "insert";
338      block: {
339        type: BlockType;
340        content: Record<string, unknown>;
341        properties?: Record<string, unknown>;
342        parentId?: string;
343        position: Position;
344      };
345    } = {
346      op: "insert",
347      block: {
348        type: b.type,
349        content: b.content as Record<string, unknown>,
350        position: b.position,
351      },
352    };
353    if (b.properties !== undefined) block.block.properties = b.properties;
354    if (b.parentId !== null) block.block.parentId = b.parentId;
355    ops.push(block);
356  }
357  return ops;
358}
359