@shivaedev/effect-pg-boss 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/effect-pg-boss",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Effect-native jobs and lifecycle management for pg-boss",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/effect-pg-boss#readme",
   "bugs": {
@@ -43,17 +43,19 @@
     "README.md"
   ],
   "devDependencies": {
-    "@shivaedev/quality": "0.22.0",
-    "@types/node": "24.19.1",
+    "@shivaedev/effect-test-sql": "0.5.4",
+    "@shivaedev/quality": "0.23.0",
+    "@shivaedev/test-story": "0.6.0",
+    "@types/node": "24.19.2",
     "@typescript/native": "npm:typescript@7.0.2",
     "effect": "4.0.4",
-    "pg-boss": "12.37.0",
+    "pg-boss": "12.37.1",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "vitest": "5.0.3"
   },
   "peerDependencies": {
     "effect": "4.0.4",
-    "pg-boss": "12.37.0"
+    "pg-boss": "12.37.1"
   },
   "engines": {
     "node": ">=24"

package/src/server/error.ts

@@ -6,7 +6,21 @@ export class PgBossError extends Data.TaggedError("PgBossError")<{
 	readonly operation: PgBossOperation;
 	readonly queue?: string | undefined;
 	readonly original: Redacted.Redacted<unknown>;
-}> {}
+}> {
+	// The original's message can quote payloads or connection strings, so only its class and code are shown.
+	override get message(): string {
+		const target = this.queue === undefined ? "" : ` for queue ${this.queue}`;
+		return `pg-boss ${this.operation}${target} failed: ${originalKind(Redacted.value(this.original))}`;
+	}
+}
+
+function originalKind(original: unknown): string {
+	if (!(original instanceof Error)) {
+		return typeof original;
+	}
+	const code: unknown = Reflect.get(original, "code");
+	return typeof code === "string" ? `${original.constructor.name} ${code}` : original.constructor.name;
+}
 
 export class PgBossQueueOptionsError extends Data.TaggedError("PgBossQueueOptionsError")<{
 	readonly queue: string;
@@ -23,6 +37,12 @@ export class PgBossPayloadError extends Data.TaggedError("PgBossPayloadError")<{
 	readonly original: Redacted.Redacted<unknown>;
 }> {}
 
+export class PgBossTestingError extends Data.TaggedError("PgBossTestingError")<{
+	readonly operation: string;
+	readonly original: Redacted.Redacted<unknown>;
+	readonly queue?: string | undefined;
+}> {}
+
 export const toPgBossError = (operation: PgBossOperation, error: unknown, queue?: string): PgBossError =>
 	new PgBossError({
 		operation,

package/src/server/internal/clientCache.ts

@@ -0,0 +1,61 @@
+import type { PgBossClient } from "#client.ts";
+
+interface CachedClient {
+	readonly client: Promise<PgBossClient>;
+	references: number;
+}
+
+const cacheSymbol = Symbol.for("@shivaedev/effect-pg-boss/client-cache");
+const shared: unknown = Reflect.get(globalThis, cacheSymbol);
+const clients: Map<string | symbol, unknown> = shared instanceof Map ? shared : new Map<string | symbol, unknown>();
+Reflect.set(globalThis, cacheSymbol, clients);
+
+function entryFor(key: string | symbol): CachedClient | undefined {
+	const value = clients.get(key);
+	return isCachedClient(value) ? value : undefined;
+}
+
+function isCachedClient(value: unknown): value is CachedClient {
+	return (
+		typeof value === "object"
+		&& value !== null
+		&& Reflect.get(value, "client") instanceof Promise
+		&& typeof Reflect.get(value, "references") === "number"
+	);
+}
+
+export async function acquireCachedClient(key: string | symbol, start: () => Promise<PgBossClient>) {
+	const existing = entryFor(key);
+	if (existing !== undefined) {
+		existing.references += 1;
+		try {
+			return { client: await existing.client, reused: true };
+		} catch (error) {
+			existing.references -= 1;
+			throw error;
+		}
+	}
+	const entry: CachedClient = { client: start(), references: 1 };
+	clients.set(key, entry);
+	try {
+		return { client: await entry.client, reused: false };
+	} catch (error) {
+		if (clients.get(key) === entry) {
+			clients.delete(key);
+		}
+		throw error;
+	}
+}
+
+export function releaseCachedClient(key: string | symbol): Promise<PgBossClient> | undefined {
+	const entry = entryFor(key);
+	if (entry === undefined) {
+		return;
+	}
+	entry.references -= 1;
+	if (entry.references > 0) {
+		return;
+	}
+	clients.delete(key);
+	return entry.client;
+}

package/src/server/internal/clientErrors.ts

@@ -0,0 +1,64 @@
+import { Effect } from "effect";
+import type { PgBossClient } from "#client.ts";
+
+type Listener = (error: Error) => void;
+
+interface Observer {
+	readonly dispose: () => void;
+	readonly listeners: Set<Listener>;
+}
+
+const key = Symbol.for("@shivaedev/effect-pg-boss/error-observers");
+const shared: unknown = Reflect.get(globalThis, key);
+const observers: WeakMap<WeakKey, unknown> = shared instanceof WeakMap ? shared : new WeakMap<WeakKey, unknown>();
+Reflect.set(globalThis, key, observers);
+
+export function logClientError(error: Error): Effect.Effect<void> {
+	const message = { event: "pg_boss_error", message: error.message };
+	return Reflect.get(error, "code") === "57P01" ? Effect.logDebug(message) : Effect.logError(message);
+}
+
+export function observeClientErrors(client: PgBossClient, fallback: Listener): void {
+	closeClientErrors(client);
+	const listeners = new Set<Listener>();
+	const listener: Listener = (error) => {
+		if (listeners.size === 0) {
+			fallback(error);
+		} else {
+			for (const report of listeners) {
+				report(error);
+			}
+		}
+	};
+	// Pool shutdown can resolve before its clients finish disconnecting.
+	client.on("error", listener);
+	observers.set(client, { dispose: () => client.off("error", listener), listeners });
+}
+
+export function subscribeClientErrors(client: PgBossClient, listener: Listener): () => void {
+	const observer = observerFor(client);
+	if (observer === undefined) {
+		throw new Error("pg-boss client has no error observer");
+	}
+	observer.listeners.add(listener);
+	return () => observer.listeners.delete(listener);
+}
+
+function closeClientErrors(client: PgBossClient): void {
+	observerFor(client)?.dispose();
+	observers.delete(client);
+}
+
+function observerFor(client: PgBossClient): Observer | undefined {
+	const value = observers.get(client);
+	return isObserver(value) ? value : undefined;
+}
+
+function isObserver(value: unknown): value is Observer {
+	return (
+		typeof value === "object"
+		&& value !== null
+		&& typeof Reflect.get(value, "dispose") === "function"
+		&& Reflect.get(value, "listeners") instanceof Set
+	);
+}

package/src/server/internal/ensureQueue.ts

@@ -3,11 +3,29 @@ import type { PgBossClient } from "#client.ts";
 import { PgBossQueueOptionsError } from "#error.ts";
 import { deadLetterQueueName } from "#health.ts";
 
+const DEADLOCK_DETECTED = "40P01";
+const CREATE_QUEUE_ATTEMPTS = 6;
+
+// A partitioned queue attaches its table to pg-boss's job table, which can deadlock with job traffic on other queues.
+// PostgreSQL rolls the whole creation back, so trying it again is safe.
+async function createQueue(client: PgBossClient, name: string, options?: Omit<Queue, "name">): Promise<void> {
+	for (let attempt = 1; ; attempt += 1) {
+		try {
+			return await client.createQueue(name, options);
+		} catch (error) {
+			if (attempt === CREATE_QUEUE_ATTEMPTS || !(error instanceof Error) || Reflect.get(error, "code") !== DEADLOCK_DETECTED) {
+				throw error;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 25 * 2 ** (attempt - 1)));
+		}
+	}
+}
+
 export async function ensureQueue(client: PgBossClient, name: string, options: Omit<Queue, "name" | "deadLetter">): Promise<void> {
 	const deadLetter = deadLetterQueueName(name);
 	const desired = { retryBackoff: true, retryLimit: 3, ...options, deadLetter };
-	await client.createQueue(deadLetter);
-	await client.createQueue(name, desired);
+	await createQueue(client, deadLetter);
+	await createQueue(client, name, desired);
 	const existing = await client.getQueue(name);
 	if (existing === null) {
 		return;

package/src/server/internal/expireAttempt.ts

@@ -0,0 +1,18 @@
+import type { Job, PgBoss } from "pg-boss";
+
+export async function expireAttempt(client: PgBoss, schema: string, job: Job<unknown>): Promise<void> {
+	if ((await client.schemaVersion()) !== 45) {
+		throw new Error("Testing expiry requires pg-boss schema version 45");
+	}
+	const quoted = `"${schema.replaceAll('"', '""')}"`;
+	await client.getDb().executeSql(
+		`UPDATE ${quoted}.job SET started_on = ${quoted}.job_now() - (expire_seconds + 1) * interval '1 second'
+		WHERE name = $1 AND id = $2 AND retry_count = $3 AND state = 'active'`,
+		[job.name, job.id, job.retryCount],
+	);
+	// Supervision owns expiry and dead lettering; make its claim due with the job's deadline.
+	await client
+		.getDb()
+		.executeSql(`UPDATE ${quoted}.queue SET monitor_claim_on = ${quoted}.job_now() - interval '1 week' WHERE name = $1`, [job.name]);
+	await client.supervise(job.name);
+}

package/src/server/internal/lifecycle.ts

@@ -2,30 +2,8 @@ import { Effect } from "effect";
 import type { ConstructorOptions, StopOptions } from "pg-boss";
 import { defaultClientFactory, type PgBossClient, type PgBossClientFactory } from "#client.ts";
 import { toPgBossError } from "#error.ts";
-
-interface CachedClient {
-	readonly client: Promise<PgBossClient>;
-	references: number;
-}
-
-const CacheKey = Symbol.for("@shivaedev/effect-pg-boss/client-cache");
-const sharedCache: unknown = Reflect.get(globalThis, CacheKey);
-const clientCache: Map<string | symbol, unknown> = sharedCache instanceof Map ? sharedCache : new Map<string | symbol, unknown>();
-Reflect.set(globalThis, CacheKey, clientCache);
-
-function isCachedClient(value: unknown): value is CachedClient {
-	return (
-		typeof value === "object"
-		&& value !== null
-		&& Reflect.get(value, "client") instanceof Promise
-		&& typeof Reflect.get(value, "references") === "number"
-	);
-}
-
-function cachedClient(key: string | symbol): CachedClient | undefined {
-	const entry = clientCache.get(key);
-	return isCachedClient(entry) ? entry : undefined;
-}
+import { acquireCachedClient, releaseCachedClient } from "./clientCache.ts";
+import { logClientError, observeClientErrors } from "./clientErrors.ts";
 
 export interface AcquireClientOptions {
 	readonly clientCacheKey?: string | symbol | undefined;
@@ -39,86 +17,48 @@ export interface AcquiredClient {
 	readonly reused: boolean;
 }
 
-function startClient(options: AcquireClientOptions): Promise<PgBossClient> {
+async function startClient(options: AcquireClientOptions, report: (error: Error) => void): Promise<PgBossClient> {
 	const client = (options.clientFactory ?? defaultClientFactory)(options.constructor);
-	return client.start().then(
-		() => client,
-		async (error) => {
-			try {
-				await client.stop();
-			} catch {
-				// Preserve the startup failure; stop is best effort on failed acquisition.
-			}
-			throw error;
-		},
-	);
+	observeClientErrors(client, report);
+	try {
+		await client.start();
+		return client;
+	} catch (error) {
+		try {
+			await client.stop();
+		} catch {
+			// Preserve the startup failure; stop is best effort on failed acquisition.
+		}
+		throw error;
+	}
 }
 
-export const acquireClient = (options: AcquireClientOptions): Effect.Effect<AcquiredClient, import("#error.ts").PgBossError> =>
-	Effect.tryPromise({
-		catch: (error) => toPgBossError("start", error),
-		try: async () => {
-			const cacheKey = options.clientCacheKey;
-			if (cacheKey === undefined) {
-				return {
-					client: await startClient(options),
-					reused: false,
-				};
-			}
-
-			const existing = cachedClient(cacheKey);
-			if (existing !== undefined) {
-				existing.references += 1;
-				try {
-					return {
-						cacheKey,
-						client: await existing.client,
-						reused: true,
-					};
-				} catch (error) {
-					existing.references -= 1;
-					throw error;
-				}
-			}
-
-			const entry: CachedClient = {
-				client: startClient(options),
-				references: 1,
-			};
-			clientCache.set(cacheKey, entry);
-			try {
-				return {
-					cacheKey,
-					client: await entry.client,
-					reused: false,
-				};
-			} catch (error) {
-				if (clientCache.get(cacheKey) === entry) {
-					clientCache.delete(cacheKey);
-				}
-				throw error;
-			}
-		},
+export function acquireClient(options: AcquireClientOptions): Effect.Effect<AcquiredClient, import("#error.ts").PgBossError> {
+	return Effect.contextWith((context) => {
+		const run = Effect.runForkWith(context);
+		function report(error: Error) {
+			run(logClientError(error));
+		}
+		return Effect.tryPromise({
+			catch: (error) => toPgBossError("start", error),
+			try: async () => {
+				const cacheKey = options.clientCacheKey;
+				return cacheKey === undefined
+					? { client: await startClient(options, report), reused: false }
+					: { cacheKey, ...(await acquireCachedClient(cacheKey, () => startClient(options, report))) };
+			},
+		});
 	});
+}
 
-export const releaseClient = (acquired: AcquiredClient, stopOptions?: StopOptions): Effect.Effect<void> =>
-	Effect.tryPromise({
+export function releaseClient(acquired: AcquiredClient, stopOptions?: StopOptions): Effect.Effect<void> {
+	return Effect.tryPromise({
 		catch: (error) => toPgBossError("stop", error),
 		try: async () => {
-			if (acquired.cacheKey === undefined) {
-				await acquired.client.stop(stopOptions);
-				return;
-			}
-
-			const entry = cachedClient(acquired.cacheKey);
-			if (entry === undefined) {
-				return;
+			const client = acquired.cacheKey === undefined ? acquired.client : await releaseCachedClient(acquired.cacheKey);
+			if (client !== undefined) {
+				await client.stop(stopOptions);
 			}
-			entry.references -= 1;
-			if (entry.references > 0) {
-				return;
-			}
-			clientCache.delete(acquired.cacheKey);
-			await acquired.client.stop(stopOptions);
 		},
 	}).pipe(Effect.catch((error) => Effect.logError(error)));
+}

package/src/server/internal/observeTestingSettlements.ts

@@ -0,0 +1,36 @@
+import type { PgBoss } from "pg-boss";
+
+export function observeTestingSettlements(client: PgBoss, changed: () => void) {
+	const observers = new Map<string, () => void>();
+	return {
+		close() {
+			for (const close of observers.values()) {
+				close();
+			}
+			observers.clear();
+		},
+		watch(name: string) {
+			if (observers.has(name)) {
+				return;
+			}
+			const spy = client.getSpy(name);
+			let open = true;
+			async function observe() {
+				while (true) {
+					await Promise.race([spy.waitForJob(() => true, "completed"), spy.waitForJob(() => true, "failed")]);
+					if (!open) {
+						return;
+					}
+					// This controller owns the spy; clear history and the losing wait before rearming both outcomes.
+					spy.clear();
+					changed();
+				}
+			}
+			observers.set(name, () => {
+				open = false;
+				spy.clear();
+			});
+			void observe().catch((error: unknown) => client.emit("error", error instanceof Error ? error : new Error(String(error))));
+		},
+	};
+}

package/src/server/internal/register.ts

@@ -9,7 +9,7 @@ import {
 	type ScheduleDefinition,
 	type ScheduledWorker,
 } from "#definition.ts";
-import { PgBossPayloadError, PgBossQueueOptionsError, toPgBossError } from "#error.ts";
+import { PgBossError, PgBossPayloadError, PgBossQueueOptionsError, toPgBossError } from "#error.ts";
 import { batchHandler } from "#internal/batchHandler.ts";
 import { ensureQueue } from "#internal/ensureQueue.ts";
 import { payloadOf, traceJob } from "#internal/tracing.ts";
@@ -51,7 +51,11 @@ async function prepareQueues(client: PgBossClient, registrations: readonly JobRe
 	}
 	for (const registration of registrations) {
 		const definition = registrationDefinition(registration);
-		await ensureQueue(client, definition.name, definition.queueOptions);
+		try {
+			await ensureQueue(client, definition.name, definition.queueOptions);
+		} catch (error) {
+			throw error instanceof PgBossQueueOptionsError ? error : toPgBossError("register", error, definition.name);
+		}
 	}
 }
 
@@ -113,9 +117,9 @@ export const registerJobs = <R>(
 	registrations: readonly JobRegistration[],
 	context: Context.Context<R>,
 	replaceWorkers: boolean,
-): Effect.Effect<void, import("#error.ts").PgBossError | PgBossQueueOptionsError> =>
+): Effect.Effect<void, PgBossError | PgBossQueueOptionsError> =>
 	Effect.tryPromise({
-		catch: (error) => (error instanceof PgBossQueueOptionsError ? error : toPgBossError("register", error)),
+		catch: (error) => (error instanceof PgBossQueueOptionsError || error instanceof PgBossError ? error : toPgBossError("register", error)),
 		try: async () => {
 			registrationNames(registrations);
 			await prepareQueues(client, registrations, replaceWorkers);

package/src/server/internal/testingClient.ts

@@ -0,0 +1,115 @@
+import type { Job, PgBoss, SendOptions, UpdateOptions, UpdateRequest, UpdateResponse } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { expireAttempt } from "#internal/expireAttempt.ts";
+import { observeTestingSettlements } from "#internal/observeTestingSettlements.ts";
+import { testingExpirations } from "#internal/testingExpirations.ts";
+
+export interface TestingControls {
+	readonly changed: () => void;
+	readonly expirations: Map<string, number>;
+	readonly failures: Set<string>;
+	readonly retryPolicy: Pick<SendOptions, "retryBackoff" | "retryDelay">;
+}
+
+export function testingClient(client: PgBoss, schema: string, controls: TestingControls): PgBossClient {
+	const settlements = observeTestingSettlements(client, controls.changed);
+	const expirations = testingExpirations(client);
+	function update(request: UpdateRequest): Promise<UpdateResponse>;
+	function update(name: string, data: object | null | undefined, options?: UpdateOptions): Promise<UpdateResponse>;
+	async function update(request: string | UpdateRequest, data?: object | null, options?: UpdateOptions): Promise<UpdateResponse> {
+		const result = typeof request === "string" ? await client.update(request, data, options) : await client.update(request);
+		controls.changed();
+		return result;
+	}
+	const overrides: Partial<PgBossClient> = {
+		complete: async (...args) => {
+			const result = await client.complete(...args);
+			controls.changed();
+			return result;
+		},
+		createQueue: (name, options) => {
+			const { retryDelayMax, ...rest } = options ?? {};
+			return client.createQueue(name, {
+				...rest,
+				...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+				...controls.retryPolicy,
+			});
+		},
+		fail: async (...args) => {
+			const result = await client.fail(...args);
+			controls.changed();
+			return result;
+		},
+		retry: async (...args) => {
+			const result = await client.retry(...args);
+			controls.changed();
+			return result;
+		},
+		send: async (name, data, options) => {
+			if (controls.failures.delete(name)) {
+				throw new Error("Injected pg-boss send failure");
+			}
+			const attempts = controls.expirations.get(name);
+			const { retryDelayMax, ...rest } = options ?? {};
+			const id = await expirations.send(
+				name,
+				data,
+				{
+					...rest,
+					...(controls.retryPolicy.retryBackoff === false || retryDelayMax === undefined ? {} : { retryDelayMax }),
+					...controls.retryPolicy,
+					...(attempts === undefined ? {} : { retryLimit: attempts - 1 }),
+				},
+				attempts,
+			);
+			controls.changed();
+			return id;
+		},
+		stop: async (options) => {
+			try {
+				await client.stop(options);
+			} finally {
+				settlements.close();
+			}
+		},
+		update,
+		updateQueue: (name, options) =>
+			client.updateQueue(name, {
+				...options,
+				...controls.retryPolicy,
+				...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
+			}),
+		work: (name, options, handler) => {
+			settlements.watch(name);
+			return client.work(name, options, async (jobs: Job<unknown>[]) => {
+				controls.changed();
+				try {
+					const ready: Job<unknown>[] = [];
+					for (const job of jobs) {
+						const attempts = await expirations.attemptsFor(job);
+						if (attempts !== undefined && job.retryCount + 1 >= attempts) {
+							await expireAttempt(client, schema, job);
+						} else {
+							ready.push(job);
+						}
+					}
+					if (ready.length > 0) {
+						await handler(ready);
+					}
+				} finally {
+					controls.changed();
+				}
+			});
+		},
+	};
+	return new Proxy(client, {
+		get(target, property) {
+			if (Object.hasOwn(overrides, property)) {
+				const override: unknown = Reflect.get(overrides, property);
+				return override;
+			}
+			const value: unknown = Reflect.get(target, property);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}

package/src/server/internal/testingExpirations.ts

@@ -0,0 +1,31 @@
+import type { Job, PgBoss, SendOptions } from "pg-boss";
+
+export function testingExpirations(client: PgBoss) {
+	const snapshots = new Map<string, Promise<number | undefined>>();
+	return {
+		attemptsFor: (job: Job<unknown>) => snapshots.get(`${job.name}:${job.id}`),
+		send(name: string, data: object | null | undefined, options: SendOptions, attempts: number | undefined) {
+			if (attempts === undefined && options.id === undefined) {
+				return client.send(name, data, options);
+			}
+			const id = options.id ?? crypto.randomUUID();
+			const key = `${name}:${id}`;
+			const previous = snapshots.get(key);
+			const sending = client.send(name, data, { ...options, id });
+			// A worker may claim the row before send returns. Wait for its result before applying the snapshot.
+			const snapshot = sending
+				.then(
+					(sent) => (sent === id ? attempts : previous),
+					() => previous,
+				)
+				.then((value) => {
+					if (value === undefined && snapshots.get(key) === snapshot) {
+						snapshots.delete(key);
+					}
+					return value;
+				});
+			snapshots.set(key, snapshot);
+			return sending;
+		},
+	};
+}

package/src/server/internal/testingReadout.ts

@@ -0,0 +1,26 @@
+import { Effect, Redacted, Schema } from "effect";
+import type { FindJobsOptions, PgBoss } from "pg-boss";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { PgBossPayloadError, PgBossTestingError } from "#error.ts";
+import { payloadOf } from "#internal/tracing.ts";
+
+export function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string) {
+	return Effect.tryPromise({
+		catch: (original) => new PgBossTestingError({ operation, original: Redacted.make(original), queue }),
+		try: run,
+	});
+}
+
+export function testingReadout(client: () => PgBoss) {
+	return <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: FindJobsOptions) =>
+		testingOperation("jobs", () => client().findJobs<unknown>(queue.name, options), queue.name).pipe(
+			Effect.flatMap((jobs) =>
+				Effect.forEach(jobs, (job) =>
+					Schema.decodeUnknownEffect(queue.schema)(payloadOf(job.data)).pipe(
+						Effect.mapError((original) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(original), queue: queue.name })),
+						Effect.map((data) => ({ ...job, data })),
+					),
+				),
+			),
+		);
+}

package/src/server/internal/testingSignal.ts

@@ -0,0 +1,28 @@
+import { Effect } from "effect";
+
+export function testingSignal() {
+	let revision = 0;
+	const listeners = new Set<(revision: number) => void>();
+	return {
+		changed() {
+			revision += 1;
+			for (const listener of listeners) {
+				listener(revision);
+			}
+			listeners.clear();
+		},
+		revision: Effect.sync(() => revision),
+		waitForChange: (after: number): Effect.Effect<number> =>
+			Effect.callback((resume) => {
+				if (revision !== after) {
+					resume(Effect.succeed(revision));
+					return;
+				}
+				function listener(current: number) {
+					resume(Effect.succeed(current));
+				}
+				listeners.add(listener);
+				return Effect.sync(() => listeners.delete(listener));
+			}),
+	};
+}