/** One changed leaf of a settings document. */ export interface Change { path: string; before: unknown; after: unknown; } const isRecord = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); // The server decodes an absent field as its zero value, so a document that // omits one and a draft that holds the zero are the same setting. const isZero = (v: unknown) => v === false || v === 0 || v === ""; const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b) || (a === undefined && isZero(b)) || (b === undefined && isZero(a)); /** * diffValues lists what changed between two settings documents, one entry per * changed leaf. Objects recurse by key and arrays of objects by index; an * array of plain values is one leaf, because its entries have no identity of * their own. A row added or removed is a single change. */ export function diffValues(before: unknown, after: unknown, path = "", expandRows = false): Change[] { if (same(before, after)) return []; const at = (key: string | number) => (path ? `${path}.${key}` : String(key)); if ((isRecord(before) && isRecord(after)) || (expandRows && (isRecord(before) || isRecord(after)))) { const left = isRecord(before) ? before : {}; const right = isRecord(after) ? after : {}; const keys = [...new Set([...Object.keys(left), ...Object.keys(right)])]; return keys.flatMap((key) => diffValues(left[key], right[key], at(key), expandRows)); } const rows = (v: unknown) => Array.isArray(v) && v.some(isRecord); if (Array.isArray(before) && Array.isArray(after) && (rows(before) || rows(after))) { const length = Math.max(before.length, after.length); return Array.from({ length }, (_, i) => diffValues(before[i], after[i], at(i), expandRows)).flat(); } return [{ path, before, after }]; } /** * saveInOrder saves each kind in turn and stops at the first failure: saves * are not atomic across kinds, so the ones after a failure stay unsaved * rather than landing on top of a half-applied set. */ export async function saveInOrder( kinds: string[], save: (kind: string) => Promise, ): Promise<{ saved: string[]; failed: string | undefined; untouched: string[] }> { const saved: string[] = []; for (const [i, kind] of kinds.entries()) { if (!(await save(kind))) return { saved, failed: kind, untouched: kinds.slice(i + 1) }; saved.push(kind); } return { saved, failed: undefined, untouched: [] }; } /** formatValue renders one side of a change for the review diff. */ export function formatValue(value: unknown): string { if (value === undefined) return "unset"; if (typeof value === "string") return value === "" ? '""' : value; return JSON.stringify(value); } /** pathSegments splits a change path into keys, with row indexes as numbers. */ export function pathSegments(path: string): (string | number)[] { return path === "" ? [] : path.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : part)); } /** * setAt returns a copy of doc with value written at path. An undefined value * removes the key or row, and a parent it leaves empty, so reverting an * added row deletes it rather than leaving a hole. */ export function setAt(doc: unknown, path: (string | number)[], value: unknown): unknown { if (path.length === 0) return value; const [head, ...rest] = path; if (typeof head === "number") { const rows = Array.isArray(doc) ? [...doc] : []; const next = setAt(rows[head], rest, value); if (next === undefined) rows.splice(head, 1); else if (rest.length === 0 && head >= rows.length) rows.push(next); else rows[head] = next; return next === undefined && rows.length === 0 ? undefined : rows; } const record = isRecord(doc) ? { ...doc } : {}; const next = setAt(record[head], rest, value); if (next === undefined) delete record[head]; else record[head] = next; return next === undefined && Object.keys(record).length === 0 ? undefined : record; } /** revertChange puts one change's before value back into doc, leaving every * other change in place: the surgical half of accept all. */ export function revertChange(doc: unknown, change: Change): unknown { return setAt(doc, pathSegments(change.path), change.before); }