Files
road-compiler/workbench/client/src/edit/preview-request.ts
T

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);
}
}