@shivaedev/jobs 0.31.0 → 0.34.0

package/src/server/adapters/inspectionReads.ts

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import { inspectionDeferrals } from "#server/adapters/inspectionDeferrals.ts";
+import { inspectionJobs } from "#server/adapters/inspectionJobs.ts";
+import { inspectionOperation } from "#server/adapters/inspectionOperation.ts";
+import { inspectionSnapshot } from "#server/adapters/inspectionSnapshot.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+
+const Busy = Schema.Struct({ busy: Schema.Boolean });
+export function inspectionReads(client: PgBossClient, schema: string) {
+	const quoted = quotedSchema(schema);
+	function query(text: string, values?: unknown[]) {
+		const db = client.getDb?.();
+		if (db === undefined) {
+			throw new TypeError("This pg-boss client does not support getDb");
+		}
+		return db.executeSql(text, values);
+	}
+	return {
+		...inspectionDeferrals(client),
+		busy: (queues: readonly Pick<QueueDefinition, "name">[]) =>
+			inspectionOperation(async () => {
+				const { rows } = await query(
+					`/* jobs inspection busy */ SELECT EXISTS (
+				SELECT 1 FROM ${quoted}.job WHERE name = ANY($1::text[]) AND (
+					(state < 'active' AND NOT blocked AND start_after <= ${quoted}.job_now()) OR state = 'active'
+				)
+			) AS busy`,
+					[queues.map(({ name }) => name)],
+				);
+				return Schema.decodeUnknownSync(Busy)(rows[0]).busy;
+			}),
+		...inspectionJobs(client),
+		queue: (queue: Pick<QueueDefinition, "name">) => inspectionOperation(() => client.getQueue(queue.name), queue.name),
+		schedules: (name?: string, key?: string) =>
+			inspectionOperation(() => {
+				if (client.getSchedules === undefined) {
+					throw new TypeError("This pg-boss client does not support getSchedules");
+				}
+				return client.getSchedules(name, key);
+			}),
+		schemaVersion: () =>
+			inspectionOperation(() => {
+				if (client.schemaVersion === undefined) {
+					throw new TypeError("This pg-boss client does not support schemaVersion");
+				}
+				return client.schemaVersion();
+			}),
+		snapshot: inspectionSnapshot(
+			() => client,
+			() => schema,
+		),
+	};
+}

package/src/server/{internal/testingSnapshot.ts → adapters/inspectionSnapshot.ts}

@@ -1,9 +1,9 @@
 import { Effect, Schema } from "effect";
-import type { EngineClient } from "#server/engineClient.ts";
-import type { PgBossPayloadError, PgBossTestingError } from "#server/error.ts";
+import { inspectionOperation } from "#server/adapters/inspectionOperation.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { PgBossError, PgBossPayloadError } from "#server/error.ts";
+import type { SnapshotQueue, UnfinishedJob } from "#server/inspection.ts";
 import { decodeStoredData, quotedSchema } from "#server/internal/storedRows.ts";
-import { testingOperation } from "#server/internal/testingReadout.ts";
-import type { SnapshotQueue, UnfinishedJob } from "#server/testing.ts";
 
 const Rows = Schema.Array(
 	Schema.Struct({
@@ -15,29 +15,27 @@ const Rows = Schema.Array(
 	}),
 );
 
-export function testingSnapshot(client: () => EngineClient, schema: () => string) {
+export function inspectionSnapshot(client: () => PgBossClient, schema: () => string) {
 	return <const TQueues extends readonly SnapshotQueue[]>(
 		queues: TQueues,
-	): Effect.Effect<
-		readonly UnfinishedJob<TQueues[number]>[],
-		PgBossPayloadError | PgBossTestingError,
-		TQueues[number]["schema"]["DecodingServices"]
-	> => {
+	): Effect.Effect<readonly UnfinishedJob<TQueues[number]>[], PgBossPayloadError | PgBossError, TQueues[number]["schema"]["DecodingServices"]> => {
 		const byName = new Map<string, TQueues[number]>(queues.map((queue) => [queue.name, queue]));
-		return testingOperation("snapshot", async () => {
+		return inspectionOperation(async () => {
 			const quoted = quotedSchema(schema());
-			const { rows } = await client()
-				.getDb()
-				.executeSql(
-					`SELECT id, name AS queue, data, start_after AS "startAfter",
+			const db = client().getDb?.();
+			if (db === undefined) {
+				throw new TypeError("This pg-boss client does not support getDb");
+			}
+			const { rows } = await db.executeSql(
+				`SELECT id, name AS queue, data, start_after AS "startAfter",
 					CASE WHEN state = 'retry' AND started_on IS NULL AND start_after > ${quoted}.job_now()
 						AND output ? 'jobDeferral'
 					THEN 'deferred' ELSE state::text END AS state
 					FROM ${quoted}.job
 					WHERE name = ANY($1::text[]) AND state IN ('created', 'retry', 'active', 'failed')
 					ORDER BY created_on, id`,
-					[[...byName.keys()]],
-				);
+				[[...byName.keys()]],
+			);
 			return Schema.decodeUnknownPromise(Rows)(rows);
 		}).pipe(
 			Effect.flatMap((rows) =>

package/src/server/adapters/jobEngine.ts

@@ -1,7 +1,6 @@
 import { type Context, Effect } from "effect";
 import type { PgBossClient } from "#server/client.ts";
 import { toPgBossError } from "#server/error.ts";
-import { deferralObservers } from "#server/internal/deferral.ts";
 import type { JobEngine } from "#server/internal/engine.ts";
 import { listJobs } from "./listJobs.ts";
 import { queueAdministration } from "./queueAdministration.ts";
@@ -49,9 +48,6 @@ export function jobEngine(client: PgBossClient, schema = "pgboss"): Context.Serv
 							// Native batch settlement must not match a sibling's new claim at the unchanged retry count.
 							job.retryCount = Number.MAX_SAFE_INTEGER;
 						}
-						if (settled.deferred) {
-							deferralObservers.get(client)?.();
-						}
 					}),
 				),
 			),

package/src/server/adapters/payloadIdentity.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+
+export function payloadKey(parts: readonly string[], payload: object): string {
+	return JSON.stringify(parts.map((part) => [part, typeof Reflect.get(payload, part), String(Reflect.get(payload, part))]));
+}
+
+export function payloadJobId(queue: string, parts: readonly string[], payload: object): string {
+	const bytes = createHash("sha256")
+		.update(JSON.stringify([queue, payloadKey(parts, payload)]))
+		.digest();
+	bytes.writeUInt8((bytes.readUInt8(6) & 0x0f) | 0x80, 6);
+	bytes.writeUInt8((bytes.readUInt8(8) & 0x3f) | 0x80, 8);
+	const hex = bytes.subarray(0, 16).toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/server/{internal/testingSignal.ts → adapters/queueSignal.ts}

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 
-export function testingSignal() {
+export function queueSignal() {
 	let revision = 0;
 	const listeners = new Set<(revision: number) => void>();
 	return {

package/src/server/adapters/settleDeferral.ts

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import type { PgBossClient } from "#server/client.ts";
+import { deferralChanges } from "#server/internal/adapters/deferralChanges.ts";
 import { STATELY_DEFERRAL_POLICY } from "#server/internal/deferral.ts";
 import type { JobAttempt } from "#server/internal/engine.ts";
 import { quotedSchema } from "#server/internal/storedRows.ts";
@@ -11,8 +12,9 @@ export async function settleDeferral(client: PgBossClient, schema: string, job:
 		throw new TypeError("This pg-boss client does not support getDb for RetryAt");
 	}
 	const quoted = quotedSchema(schema);
+	const db = client.getDb();
 	// Native failure settlement deletes and reinserts jobs, so a cascading job foreign key would erase the counter.
-	const { rows } = await client.getDb().executeSql(
+	const { rows } = await db.executeSql(
 		`WITH claimed AS MATERIALIZED (
 			SELECT name, id, created_on,
 				GREATEST(keep_until, $4::timestamptz + (keep_until - start_after)) AS keep_until
@@ -50,5 +52,9 @@ export async function settleDeferral(client: PgBossClient, schema: string, job:
 		SELECT EXISTS (SELECT 1 FROM claimed) AS claimed, EXISTS (SELECT 1 FROM deferred) AS deferred`,
 		[job.name, job.id, job.retryCount, at, reason, Reflect.get(job, "startedOn"), maxDeferrals],
 	);
-	return Schema.decodeUnknownSync(Settlement)(rows[0]);
+	const settled = Schema.decodeUnknownSync(Settlement)(rows[0]);
+	if (settled.deferred) {
+		deferralChanges.get(db)?.();
+	}
+	return settled;
 }

package/src/server/adapters/testingClient.ts

@@ -4,9 +4,8 @@ import { testingExpirations } from "#server/adapters/testingExpirations.ts";
 import type { ClientUpdateOptions, ClientUpdateRequest, ClientUpdateResult, PgBossClient } from "#server/client.ts";
 import type { EngineClient } from "#server/engineClient.ts";
 import type { EnqueueOptions } from "#server/enqueueOptions.ts";
-import { deferralObservers } from "#server/internal/deferral.ts";
+import { deferralChanges } from "#server/internal/adapters/deferralChanges.ts";
 import type { TestingBatch, TestingWork } from "#server/internal/testingIdle.ts";
-import { testingRegistration } from "#server/internal/testingRegistrations.ts";
 import type { WorkerJob } from "#server/job.ts";
 
 export interface TestingControls {
@@ -18,18 +17,10 @@ export interface TestingControls {
 	readonly work: TestingWork;
 }
 
-export function testingClient(client: EngineClient, schema: string, controls: TestingControls): PgBossClient {
+export function testingClient(client: EngineClient, schema: string, controls: TestingControls): EngineClient {
 	const engine = testingEngine(client, schema);
-	const settlements = Effect.runSync(
-		engine.observeSettlements((name) => {
-			for (const batch of controls.work.batches) {
-				if (batch.name === name) {
-					batch.settled = true;
-				}
-			}
-			controls.changed();
-		}),
-	);
+	deferralChanges.set(client.getDb(), controls.changed);
+
 	const expirations = testingExpirations(client);
 	function update(request: ClientUpdateRequest): Promise<ClientUpdateResult>;
 	function update(name: string, data: object | null | undefined, options?: ClientUpdateOptions): Promise<ClientUpdateResult>;
@@ -45,6 +36,9 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 			return result;
 		},
 		createQueue: (name, options) => {
+			if (options?.deadLetter !== undefined) {
+				controls.work.queues.add(name);
+			}
 			const { retryDelayMax, ...rest } = options ?? {};
 			return client.createQueue(name, {
 				...rest,
@@ -84,13 +78,6 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 			controls.changed();
 			return id;
 		},
-		stop: async (options) => {
-			try {
-				await client.stop(options);
-			} finally {
-				await Effect.runPromise(settlements.close);
-			}
-		},
 		update,
 		updateQueue: (name, options) =>
 			client.updateQueue(name, {
@@ -98,10 +85,9 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 				...controls.retryPolicy,
 				...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
 			}),
-		work: async (name, options, handler) => {
-			await Effect.runPromise(settlements.watch(name));
-			return client.work(name, options, async (jobs: readonly WorkerJob<unknown>[]) => {
-				const batch: TestingBatch = { name, settled: false };
+		work: async (name, options, handler) =>
+			client.work(name, options, async (jobs: readonly WorkerJob<unknown>[]) => {
+				const batch: TestingBatch = { jobs: new Map(jobs.map((job) => [job.id, job.retryCount])), name, settled: false };
 				controls.work.batches.add(batch);
 				controls.changed();
 				try {
@@ -121,14 +107,10 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 					controls.work.batches.delete(batch);
 					controls.changed();
 				}
-			});
-		},
+			}),
 	};
 	const wrapped = new Proxy(client, {
 		get(target, property) {
-			if (property === testingRegistration) {
-				return (name: string) => controls.work.queues.add(name);
-			}
 			if (Object.hasOwn(overrides, property)) {
 				const override: unknown = Reflect.get(overrides, property);
 				return override;
@@ -137,6 +119,5 @@ export function testingClient(client: EngineClient, schema: string, controls: Te
 			return typeof value === "function" ? value.bind(target) : value;
 		},
 	});
-	deferralObservers.set(wrapped, controls.changed);
 	return wrapped;
 }

package/src/server/adapters/testingController.ts

@@ -1,32 +1,36 @@
-import { Duration, Effect, Redacted } from "effect";
+import { Duration, Effect, Redacted, type Schema } from "effect";
+import { TestClock as PgBossTestClock } from "pg-boss";
 import { defaultClientFactory } from "#server/adapters/defaultClientFactory.ts";
 import { testingClient } from "#server/adapters/testingClient.ts";
 import { testingDueNow } from "#server/adapters/testingDueNow.ts";
-import type { PgBossClientFactory } from "#server/client.ts";
-import type { QueueDefinition } from "#server/definition.ts";
+import { testingTime } from "#server/adapters/testingTime.ts";
+import type { JobReadOptions, PgBossClientFactory } from "#server/client.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
 import type { EngineClient } from "#server/engineClient.ts";
 import { PgBossTestingError } from "#server/error.ts";
+import type { PgBossInspectionService, SnapshotQueue } from "#server/inspection.ts";
 import { type TestingFetches, testingFetches } from "#server/internal/adapters/testingFetches.ts";
-import { testingDeferrals } from "#server/internal/testingDeferrals.ts";
 import { type TestingWork, testingIdle } from "#server/internal/testingIdle.ts";
-import { testingOperation, testingReadout } from "#server/internal/testingReadout.ts";
+import { testingInspection, testingOperation } from "#server/internal/testingOperation.ts";
 import { testingSchedules } from "#server/internal/testingSchedules.ts";
-import { testingSignal } from "#server/internal/testingSignal.ts";
-import { testingSnapshot } from "#server/internal/testingSnapshot.ts";
 import { testingWaits } from "#server/internal/testingWaits.ts";
 import type { PgBossTestingOptions } from "#server/testing.ts";
-export function testingController(options: PgBossTestingOptions = {}) {
+import { queueSignal } from "./queueSignal.ts";
+import { testingInspectionClient } from "./testingInspectionClient.ts";
+export function testingController(settings: PgBossTestingOptions = {}) {
+	const clock = settings.clock === undefined ? undefined : new PgBossTestClock(settings.clock.currentTimeMillisUnsafe());
 	let current: EngineClient | undefined;
 	let fetches: TestingFetches | undefined;
 	let schema = "pgboss";
-	const signal = testingSignal();
+	const signal = queueSignal();
+	let observed: PgBossInspectionService | undefined;
 	const work: TestingWork = { batches: new Set(), queues: new Set() };
 	const controls = {
 		changed: signal.changed,
 		expirations: new Map<string, number>(),
 		expirySeconds: new Map<string, number>(),
 		failures: new Set<string>(),
-		retryPolicy: options.retryPolicy ?? {},
+		retryPolicy: settings.retryPolicy ?? {},
 		work,
 	};
 	function client(): EngineClient {
@@ -35,25 +39,42 @@ export function testingController(options: PgBossTestingOptions = {}) {
 		}
 		return current;
 	}
+	function inspection(): PgBossInspectionService {
+		if (observed === undefined) {
+			throw new Error("Provide the testing clientFactory to a jobs Layer first");
+		}
+		return observed;
+	}
 	const clientFactory: PgBossClientFactory = (clientOptions) => {
 		if (current !== undefined) {
 			throw new Error("A testing controller owns one jobs client; create a controller per runtime");
 		}
 		schema = clientOptions.schema ?? "pgboss";
-		current = defaultClientFactory({ ...clientOptions, "__test__enableSpies": true });
+		current = defaultClientFactory({ ...clientOptions, ...(clock === undefined ? {} : { clock }) });
 		fetches = testingFetches(current.getDb(), signal.changed);
-		return testingClient(current, clientOptions.schema ?? "pgboss", controls);
+		current = testingClient(current, schema, controls);
+		return testingInspectionClient(current, schema, work, signal.changed, (reads) => {
+			observed = reads;
+		});
 	};
+	const wake = Effect.sync(() => {
+		if (clock !== undefined) {
+			for (const worker of client().getWipData()) {
+				client().notifyWorker(worker.id);
+			}
+		}
+	});
+	const idle = testingIdle(inspection, work, signal, wake);
 	return {
-		...testingDeferrals(client),
+		deferred: (queue: Pick<QueueDefinition, "name">) => Effect.suspend(() => testingInspection("deferred", inspection().deferred(queue), queue.name)),
 		...testingDueNow(client, () => schema, signal.changed),
-		...testingSchedules(client, signal.changed),
-		...testingWaits(client, () => fetches, signal),
+		...testingSchedules(client, inspection),
+		...testingWaits(inspection, () => fetches, signal),
 		checkBatchWindow: (queue: Pick<QueueDefinition, "name" | "workerOptions">, millisecondsPerJob: number) =>
 			testingOperation(
 				"checkBatchWindow",
 				async () => {
-					const stored = await client().getQueue(queue.name);
+					const stored = await Effect.runPromise(inspection().queue(queue));
 					if (stored === null) {
 						throw new Error("Queue is not registered");
 					}
@@ -72,7 +93,7 @@ export function testingController(options: PgBossTestingOptions = {}) {
 			),
 		checkSchemaVersion: (expected: number) =>
 			testingOperation("checkSchemaVersion", async () => {
-				if ((await client().schemaVersion()) !== expected) {
+				if ((await Effect.runPromise(inspection().schemaVersion())) !== expected) {
 					throw new Error(`Expected pg-boss schema version ${expected}`);
 				}
 			}),
@@ -99,11 +120,18 @@ export function testingController(options: PgBossTestingOptions = {}) {
 				},
 			}),
 		failNextSend: (queue: Pick<QueueDefinition, "name">) => Effect.sync(() => controls.failures.add(queue.name)).pipe(Effect.asVoid),
-		jobs: testingReadout(client),
+		jobs: <TName extends string, TPayload extends JobPayloadSchema | typeof Schema.Null>(
+			queue: { readonly name: TName; readonly schema: TPayload },
+			readOptions?: JobReadOptions,
+		) => Effect.suspend(() => testingInspection("jobs", inspection().jobs(queue, readOptions), queue.name)),
+		refreshQueueStats: (queue?: Pick<QueueDefinition, "name">) =>
+			testingOperation("refreshQueueStats", () => client().supervise(queue?.name), queue?.name),
 		revision: signal.revision,
-		schemaVersion: testingOperation("schemaVersion", () => client().schemaVersion()),
-		snapshot: testingSnapshot(client, () => schema),
+		schemaVersion: Effect.suspend(() => testingInspection("schemaVersion", inspection().schemaVersion())),
+		snapshot: <const TQueues extends readonly SnapshotQueue[]>(queues: TQueues) =>
+			Effect.suspend(() => testingInspection("snapshot", inspection().snapshot(queues))),
 		waitForChange: signal.waitForChange,
-		waitForIdle: testingIdle(client, () => schema, work, signal),
+		waitForIdle: idle,
+		...testingTime(settings.clock, clock, idle),
 	};
 }

package/src/server/adapters/testingDueNow.ts

@@ -1,7 +1,7 @@
 import type { QueueDefinition } from "#server/definition.ts";
 import type { EngineClient } from "#server/engineClient.ts";
 import { quotedSchema } from "#server/internal/storedRows.ts";
-import { testingOperation } from "#server/internal/testingReadout.ts";
+import { testingOperation } from "#server/internal/testingOperation.ts";
 
 export function testingDueNow(client: () => EngineClient, schema: () => string, changed: () => void) {
 	function makeDue(queue: Pick<QueueDefinition, "name">, deferredOnly: boolean) {

package/src/server/adapters/testingEngine.ts

@@ -3,7 +3,6 @@ import type { EngineClient } from "#server/engineClient.ts";
 import { PgBossTestingError } from "#server/error.ts";
 import type { TestingEngine } from "#server/internal/engine.ts";
 import { expireAttempt } from "./expireAttempt.ts";
-import { observeTestingSettlements } from "./observeTestingSettlements.ts";
 
 export function testingEngine(client: EngineClient, schema: string): Context.Service.Shape<typeof TestingEngine> {
 	return {
@@ -12,17 +11,5 @@ export function testingEngine(client: EngineClient, schema: string): Context.Ser
 				catch: (original) => new PgBossTestingError({ operation: "expireAttempt", original: Redacted.make(original), queue: job.name }),
 				try: () => expireAttempt(client, schema, job, cause),
 			}),
-		observeSettlements: (settled) =>
-			Effect.sync(() => {
-				const observer = observeTestingSettlements(client, settled);
-				return {
-					close: Effect.sync(() => observer.close()),
-					watch: (name: string) =>
-						Effect.try({
-							catch: (original) => new PgBossTestingError({ operation: "observeSettlements", original: Redacted.make(original), queue: name }),
-							try: () => observer.watch(name),
-						}),
-				};
-			}),
 	};
 }

package/src/server/adapters/testingInspectionClient.ts

@@ -0,0 +1,70 @@
+import { Context, Effect, Exit, Layer, Scope } from "effect";
+import type { EngineClient } from "#server/engineClient.ts";
+import { PgBossInspection, type PgBossInspectionService } from "#server/inspection.ts";
+import type { TestingWork } from "#server/internal/testingIdle.ts";
+import { PgBoss } from "#server/PgBoss.ts";
+
+const settleBatches = Effect.fnUntraced(function* (inspection: PgBossInspectionService, work: TestingWork) {
+	for (const batch of work.batches) {
+		if (batch.settled) {
+			continue;
+		}
+		const stored = yield* inspection.storedJobs({ name: batch.name });
+		batch.settled = !stored.some((job) => job.state === "active" && batch.jobs.get(job.id) === job.retryCount);
+	}
+});
+
+export function testingInspectionClient(
+	source: EngineClient,
+	schema: string,
+	work: TestingWork,
+	changed: () => void,
+	observe: (inspection: PgBossInspectionService) => void,
+): EngineClient {
+	const scope = Effect.runSync(Scope.make());
+	const start = source.start.bind(source);
+	const stop = source.stop.bind(source);
+	async function startObserved() {
+		const result = await start();
+		const context = await Effect.runPromise(
+			Layer.buildWithScope(
+				PgBossInspection.layer.pipe(Layer.provide(Layer.succeed(PgBoss, { client: source, reused: false, schema, stop: undefined }))),
+				scope,
+			),
+		);
+		const inspection = Context.get(context, PgBossInspection);
+		observe(inspection);
+		await Effect.runPromise(
+			Effect.gen(function* () {
+				const changes = yield* inspection.changes();
+				const from = yield* changes.revision;
+				yield* Effect.forkScoped(
+					Effect.gen(function* () {
+						let revision = from;
+						while (true) {
+							revision = yield* changes.waitForChange(revision);
+							yield* settleBatches(inspection, work);
+							changed();
+						}
+					}),
+				);
+			}).pipe(Effect.provideService(Scope.Scope, scope)),
+		);
+		return result;
+	}
+	const stopObserved: EngineClient["stop"] = async (options) => {
+		await Promise.all([Effect.runPromise(Scope.close(scope, Exit.void)), stop(options)]);
+	};
+	return new Proxy(source, {
+		get(target, property) {
+			if (property === "start") {
+				return startObserved;
+			}
+			if (property === "stop") {
+				return stopObserved;
+			}
+			const value: unknown = Reflect.get(target, property);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+	});
+}

package/src/server/adapters/testingTime.ts

@@ -0,0 +1,25 @@
+import { Duration, Effect } from "effect";
+import type { TestClock } from "effect/testing";
+import type { PgBossTestingError } from "#server/error.ts";
+import { testingOperation } from "#server/internal/testingOperation.ts";
+
+export function testingTime(
+	clock: TestClock.TestClock | undefined,
+	jobs: { readonly setTime: (time: number) => Promise<void>; readonly tick: (milliseconds: number) => Promise<void> } | undefined,
+	idle: Effect.Effect<void, PgBossTestingError>,
+) {
+	return {
+		timePasses: (duration: Duration.Input) =>
+			Effect.gen(function* () {
+				if (clock === undefined || jobs === undefined) {
+					return yield* Effect.die(new Error("Provide the story's TestClock to makePgBossTesting before passing time"));
+				}
+				yield* idle;
+				const next = clock.currentTimeMillisUnsafe() + Duration.toMillis(Duration.fromInputUnsafe(duration));
+				yield* testingOperation("timePasses", () => jobs.setTime(next));
+				yield* clock.adjust(duration);
+				yield* testingOperation("timePasses", () => jobs.tick(0));
+				yield* idle;
+			}),
+	};
+}

package/src/server/client.ts

@@ -1,5 +1,6 @@
 import type { ClientDatabase } from "#server/ClientDatabase.ts";
 import type { ClientOptions, StopOptions } from "#server/clientOptions.ts";
+import type { EngineSchedule } from "#server/engineClient.ts";
 import type { EnqueueOptions, ScheduleOptions } from "#server/enqueueOptions.ts";
 import type { Job, WorkerJob } from "#server/job.ts";
 import type { QueueOptions } from "#server/queueOptions.ts";
@@ -62,6 +63,7 @@ export interface PgBossClient {
 	readonly getDb?: () => ClientDatabase;
 	readonly getQueue: (name: string) => Promise<ClientQueue | null>;
 	readonly getSchedule?: (name: string, key?: string) => Promise<{ readonly name: string; readonly key: string } | null>;
+	readonly getSchedules?: (name?: string, key?: string) => Promise<EngineSchedule[]>;
 	readonly getWipData?: (options?: { includeInternal?: boolean }) => { id: string; workId: string; name: string; count: number }[];
 	readonly notifyWorker?: (workerId: string) => void;
 	readonly off: (event: "error", listener: (error: Error) => void) => unknown;
@@ -69,6 +71,7 @@ export interface PgBossClient {
 	readonly on: (event: "error", listener: (error: Error) => void) => unknown;
 	readonly retry?: (name: string, id: string | string[], options?: ClientConnectionOptions) => Promise<object>;
 	readonly schedule: (name: string, cron: string, data?: object | null, options?: ScheduleOptions) => Promise<void>;
+	readonly schemaVersion?: () => Promise<number | null>;
 	readonly send: (name: string, data?: object | null, options?: EnqueueOptions) => Promise<string | null>;
 	readonly start: () => Promise<unknown>;
 	readonly stop: (options?: StopOptions) => Promise<void>;

package/src/server/clientOptions.ts

@@ -1,7 +1,6 @@
 import type { ClientDatabase } from "#server/ClientDatabase.ts";
 
 export interface ClientOptions {
-	"__test__enableSpies"?: boolean;
 	allowSchemaCaseVariant?: boolean;
 	"application_name"?: string;
 

package/src/server/definition.ts

@@ -32,7 +32,8 @@ export interface QueueDefinition<TName extends string = string, TPayload extends
 	readonly handle: <E, R>(
 		handler: (payload: Schema.Schema.Type<TPayload>, job: JobContext) => Effect.Effect<unknown, E, R>,
 	) => QueueWorker<TPayload, R>;
-	readonly key?: ((payload: Schema.Schema.Type<TPayload>) => string) | undefined;
+	readonly id?: readonly string[] | undefined;
+	readonly key?: readonly string[] | undefined;
 	readonly maxDeferrals: number;
 	readonly name: TName;
 	readonly queueOptions: Omit<QueueOptions, "maxDeferrals">;
@@ -76,32 +77,37 @@ export type RegistrationRequirements<TRegistrations extends readonly JobRegistra
 			: never
 	: never;
 
+export type PayloadParts<TPayload extends JobPayloadSchema> = readonly {
+	[TField in Extract<keyof TPayload["Type"], string>]: TPayload["Type"][TField] extends string | number | boolean | null ? TField : never;
+}[Extract<keyof TPayload["Type"], string>][];
+
 export type DefineQueueOptions<TName extends string, TPayload extends JobPayloadSchema> = {
+	readonly id?: PayloadParts<NoInfer<TPayload>>;
 	readonly label?: string;
 	readonly name: TName;
 	readonly schema: TPayload;
 	readonly subject?: readonly SubjectColumn<NoInfer<TPayload>>[];
 	readonly worker?: WorkerOptions;
 } & (
-	| { readonly key: (payload: Schema.Schema.Type<TPayload>) => string; readonly queue: QueueOptions & { readonly policy: "singleton" } }
+	| { readonly key: PayloadParts<NoInfer<TPayload>>; readonly queue: QueueOptions & { readonly policy: "singleton" } }
 	| { readonly key?: never; readonly queue?: QueueOptions & { readonly policy?: Exclude<QueuePolicy, "singleton"> } }
 );
 
-export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
-	options: DefineQueueOptions<TName, TPayload> & { readonly key: (payload: Schema.Schema.Type<TPayload>) => string },
-): QueueDefinition<TName, TPayload> & { readonly key: (payload: Schema.Schema.Type<TPayload>) => string };
-export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
-	options: DefineQueueOptions<TName, TPayload> & { readonly key?: never },
-): QueueDefinition<TName, TPayload> & { readonly key?: never };
-export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
-	options: DefineQueueOptions<TName, TPayload>,
-): QueueDefinition<TName, TPayload>;
+export function defineQueue<
+	const TName extends string,
+	const TPayload extends JobPayloadSchema,
+	const TId extends readonly string[] | undefined = undefined,
+	const TKey extends readonly string[] | undefined = undefined,
+>(
+	options: DefineQueueOptions<TName, TPayload> & { readonly id?: TId; readonly key?: TKey },
+): QueueDefinition<TName, TPayload> & { readonly id?: TId; readonly key?: TKey };
 export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
 	options: DefineQueueOptions<TName, TPayload>,
 ): QueueDefinition<TName, TPayload> {
 	const definition: QueueDefinition<TName, TPayload> = {
 		_tag: "QueueDefinition",
-		...(options.key === undefined ? {} : { key: options.key }),
+		id: options.id === undefined ? undefined : Object.freeze([...options.id]),
+		...(options.key === undefined ? {} : { key: Object.freeze([...options.key]) }),
 		...(options.label === undefined ? {} : { label: options.label }),
 		...(options.subject === undefined ? {} : { subject: Object.freeze(options.subject.map((column) => Object.freeze({ ...column }))) }),
 		handle: (handler) =>

package/src/server/engineClient.ts

@@ -16,9 +16,7 @@ export interface EngineClient extends Required<PgBossClient> {
 	readonly emit: (event: "error", error: Error) => boolean;
 	readonly findJobs: <T = unknown>(name: string, options?: JobReadOptions) => Promise<Job<T>[]>;
 	readonly getDb: () => ClientDatabase;
-	readonly getJobById: <T = unknown>(name: string, id: string) => Promise<Job<T> | null>;
 	readonly getSchedules: (name?: string, key?: string) => Promise<EngineSchedule[]>;
-	readonly getSpy: (name: string) => { clear: () => void; waitForJob: (selector: () => boolean, state: "completed" | "failed") => Promise<unknown> };
 	readonly schemaVersion: () => Promise<number | null>;
 	readonly supervise: (name?: string) => Promise<void>;
 }