@getuserfeedback/protocol 0.6.1 → 0.8.0

package/src/host/lazy-handle-client.ts

@@ -0,0 +1,207 @@
+type Subscriber<THandleId extends string> = (handleId: THandleId) => void;
+type StageSubscriber<TStage extends string> = (stage: TStage) => void;
+
+type LifecycleStage = "uninitialized" | "ready" | "invalidated";
+type StageMap<TStage extends string> = {
+	uninitialized: TStage;
+	ready: TStage;
+	invalidated: TStage;
+};
+
+const DEFAULT_LIFECYCLE_STAGES: StageMap<LifecycleStage> = {
+	uninitialized: "uninitialized",
+	ready: "ready",
+	invalidated: "invalidated",
+};
+
+export type LazyHandleClient<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string = LifecycleStage,
+> = {
+	runCommand<TPayload>(
+		buildPayload: (handleId: THandleId | undefined) => TPayload,
+		dispatchAndWait: (payload: TPayload) => Promise<TSettlement>,
+	): Promise<TSettlement>;
+	getHandleId(): THandleId | undefined;
+	subscribeHandle(subscriber: Subscriber<THandleId>): () => void;
+	getStage(): TStage;
+	setStage(stage: TStage): void;
+	subscribeStage(subscriber: StageSubscriber<TStage>): () => void;
+	reset(): void;
+	invalidate(): void;
+};
+
+export type CreateLazyHandleClientOptions<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string = LifecycleStage,
+> = {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	stages?: StageMap<TStage>;
+	initialStage?: TStage;
+};
+
+type CreateLazyHandleClientDefaultOptions<
+	THandleId extends string,
+	TSettlement,
+> = {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	initialStage?: LifecycleStage;
+	stages?: undefined;
+};
+
+type CreateLazyHandleClientCustomOptions<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string,
+> = {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	stages: StageMap<TStage>;
+	initialStage?: TStage;
+};
+
+/**
+ * Serializes commands for a lazily initialized handle.
+ * Each command payload is built only when its turn runs, so it always sees
+ * the latest settled handle id from prior commands.
+ */
+const createLazyHandleClientWithStages = <
+	THandleId extends string,
+	TSettlement,
+	TStage extends string,
+>(input: {
+	getHandleIdFromSettlement: (settlement: TSettlement) => THandleId | undefined;
+	stages: StageMap<TStage>;
+	initialStage?: TStage;
+}): LazyHandleClient<THandleId, TSettlement, TStage> => {
+	let handleId: THandleId | undefined;
+	let tail = Promise.resolve();
+	let isIdle = true;
+	let epoch = 0;
+	const { stages } = input;
+	let stage = input.initialStage ?? stages.uninitialized;
+	const subscribers = new Set<Subscriber<THandleId>>();
+	const stageSubscribers = new Set<StageSubscriber<TStage>>();
+
+	const setStage = (nextStage: TStage): void => {
+		if (stage === nextStage) {
+			return;
+		}
+		if (stage === stages.invalidated && nextStage !== stages.invalidated) {
+			return;
+		}
+		stage = nextStage;
+		stageSubscribers.forEach((subscriber) => {
+			subscriber(nextStage);
+		});
+	};
+
+	const publishHandle = (nextHandleId: THandleId): void => {
+		if (stage === stages.invalidated) {
+			return;
+		}
+		handleId = nextHandleId;
+		setStage(stages.ready);
+		subscribers.forEach((subscriber) => {
+			subscriber(nextHandleId);
+		});
+	};
+
+	const runCommand: LazyHandleClient<
+		THandleId,
+		TSettlement,
+		TStage
+	>["runCommand"] = (buildPayload, dispatchAndWait) => {
+		const execute = async (): Promise<TSettlement> => {
+			if (stage === stages.invalidated) {
+				throw new Error("Handle client is invalidated");
+			}
+			const commandEpoch = epoch;
+			const payload = buildPayload(handleId);
+			const settlement = await dispatchAndWait(payload);
+			const settledHandleId = input.getHandleIdFromSettlement(settlement);
+			if (settledHandleId && commandEpoch === epoch) {
+				publishHandle(settledHandleId);
+			}
+			return settlement;
+		};
+
+		const run = isIdle ? execute() : tail.then(execute, execute);
+		isIdle = false;
+		tail = run.then(
+			() => {
+				isIdle = true;
+			},
+			() => {
+				isIdle = true;
+			},
+		);
+		return run;
+	};
+
+	return {
+		runCommand,
+		getHandleId: () => handleId,
+		subscribeHandle: (subscriber) => {
+			subscribers.add(subscriber);
+			if (handleId) {
+				subscriber(handleId);
+			}
+			return () => {
+				subscribers.delete(subscriber);
+			};
+		},
+		getStage: () => stage,
+		setStage,
+		subscribeStage: (subscriber) => {
+			stageSubscribers.add(subscriber);
+			subscriber(stage);
+			return () => {
+				stageSubscribers.delete(subscriber);
+			};
+		},
+		reset: () => {
+			epoch += 1;
+			handleId = undefined;
+			stage = stages.uninitialized;
+			stageSubscribers.forEach((subscriber) => {
+				subscriber(stage);
+			});
+		},
+		invalidate: () => {
+			epoch += 1;
+			handleId = undefined;
+			setStage(stages.invalidated);
+		},
+	};
+};
+
+export function createLazyHandleClient<THandleId extends string, TSettlement>(
+	options: CreateLazyHandleClientDefaultOptions<THandleId, TSettlement>,
+): LazyHandleClient<THandleId, TSettlement, LifecycleStage>;
+export function createLazyHandleClient<
+	THandleId extends string,
+	TSettlement,
+	TStage extends string,
+>(
+	options: CreateLazyHandleClientCustomOptions<THandleId, TSettlement, TStage>,
+): LazyHandleClient<THandleId, TSettlement, TStage>;
+export function createLazyHandleClient<THandleId extends string, TSettlement>(
+	options:
+		| CreateLazyHandleClientDefaultOptions<THandleId, TSettlement>
+		| CreateLazyHandleClientCustomOptions<THandleId, TSettlement, string>,
+): LazyHandleClient<THandleId, TSettlement, string> {
+	if ("stages" in options && options.stages) {
+		return createLazyHandleClientWithStages({
+			getHandleIdFromSettlement: options.getHandleIdFromSettlement,
+			stages: options.stages,
+			initialStage: options.initialStage,
+		});
+	}
+	return createLazyHandleClientWithStages({
+		getHandleIdFromSettlement: options.getHandleIdFromSettlement,
+		stages: DEFAULT_LIFECYCLE_STAGES,
+		initialStage: options.initialStage,
+	});
+}

package/src/host/request-id.ts

@@ -0,0 +1,3 @@
+import { createUniqueId } from "./unique-id.js";
+
+export const createCommandRequestId = (): string => createUniqueId("req");