// Preview requests: debounce, cancel, and hand the response to EditSession. // // This layer only sends and cancels. Which responses count is `EditSession`'s // call — `acceptPreview()` owns the previewSeq watermark — because that decision // is the one worth unit-testing, and it must not depend on network timing. // // The transport is injected so the whole thing runs in node with fake timers. import type { EditSession, PreviewOutcome } from './session'; import type { EditPreviewRequest, EditPreviewResponse } from './types'; /** Trailing debounce while a drag is live, per design.md's latency budget. */ export const PREVIEW_DEBOUNCE_MS = 80; export type PreviewTransport = (request: EditPreviewRequest, signal: AbortSignal) => Promise; /** * One gesture's document fragment. Operations travel with constraints because * `validateEditDocument()` rejects a constraint whose `provenance.operationId` is * not a recorded operation — constraints alone come back as a 400. */ export type PreviewDraft = Pick; export interface PreviewRequesterOptions { session: EditSession; send: PreviewTransport; /** True from the first queued draft until its latest request has settled. */ onPendingChange?: (pending: boolean) => void; /** Called for every response the session accepted, stale ones excluded. */ onSettled: (outcome: PreviewOutcome, response: EditPreviewResponse) => void; /** Real failures only; an abort is expected and never reported. */ onError?: (error: unknown) => void; debounceMs?: number; } function isAbort(error: unknown): boolean { return error instanceof DOMException ? error.name === 'AbortError' : (error as Error)?.name === 'AbortError'; } export class PreviewRequester { private timer: ReturnType | null = null; private inFlight: AbortController | null = null; /** Changes whenever the owning map/junction scope changes. */ private generation = 0; private pending = false; private readonly debounceMs: number; constructor(private readonly options: PreviewRequesterOptions) { this.debounceMs = options.debounceMs ?? PREVIEW_DEBOUNCE_MS; } /** During a drag: coalesce to one request per debounce window. */ schedule(draft: PreviewDraft): void { this.setPending(true); if (this.timer) clearTimeout(this.timer); this.timer = setTimeout(() => { this.timer = null; void this.dispatch(draft); }, this.debounceMs); } /** * On pointerup: send now. The value the pointer settled on is what the user * meant, so it must not be dropped by a pending timer or lost to the debounce. */ flush(draft: PreviewDraft): void { this.setPending(true); if (this.timer) { clearTimeout(this.timer); this.timer = null; } void this.dispatch(draft); } /** Drops the pending timer and aborts anything in flight. */ cancel(): void { if (this.timer) { clearTimeout(this.timer); this.timer = null; } this.inFlight?.abort(); this.inFlight = null; this.setPending(false); } /** * Aborts the active scope and makes responses from it ineligible for apply. * * Abort is cooperative: a transport may resolve after the signal fires. The * generation check in `dispatch()` is therefore the authority that prevents * an A-scope response from replacing the UI after A -> B navigation. */ invalidate(): void { this.generation += 1; this.cancel(); } private async dispatch(draft: PreviewDraft): Promise { // Abort the older request before starting a newer one: its answer is already // obsolete, and leaving it running wastes a solve the user cannot see. this.inFlight?.abort(); const controller = new AbortController(); this.inFlight = controller; const previewSeq = this.options.session.nextPreviewSeq(); const generation = this.generation; try { const response = await this.options.send({ previewSeq, ...draft }, controller.signal); if (generation !== this.generation) return; const outcome = this.options.session.acceptPreview(response); // A stale response is dropped silently; that is the arbitration working. if (outcome.applied) this.options.onSettled(outcome, response); } catch (error) { if (!isAbort(error)) this.options.onError?.(error); } finally { if (this.inFlight === controller) { this.inFlight = null; if (!this.timer) this.setPending(false); } } } private setPending(pending: boolean): void { if (this.pending === pending) return; this.pending = pending; this.options.onPendingChange?.(pending); } }