128 lines
4.6 KiB
TypeScript
128 lines
4.6 KiB
TypeScript
// 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<EditPreviewResponse>;
|
|
|
|
/**
|
|
* 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<EditPreviewRequest, 'constraints' | 'operations'>;
|
|
|
|
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<typeof setTimeout> | 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<void> {
|
|
// 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);
|
|
}
|
|
}
|