@shivaedev/jobs 0.31.0 → 0.32.0

package/src/server/adapters/testingController.ts

@@ -1,32 +1,33 @@
-import { Duration, Effect, Redacted } from "effect";
+import { Duration, Effect, Redacted, type Schema } from "effect";
 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 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 = {}) {
 	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 +36,34 @@ 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);
 		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;
+		});
 	};
 	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 +82,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 +109,17 @@ 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: testingIdle(inspection, work, signal),
 	};
 }

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

package/src/server/enqueueOptions.ts

@@ -1,4 +1,5 @@
 import type { ClientDatabase } from "#server/ClientDatabase.ts";
+import type { QueueDefinition } from "#server/definition.ts";
 import type { RetryOptions } from "#server/queueOptions.ts";
 
 export interface EnqueueOptions extends RetryOptions {
@@ -13,6 +14,10 @@ export interface EnqueueOptions extends RetryOptions {
 	readonly startAfter?: number | string | Date;
 }
 
+export type QueueEnqueueOptions<TQueue extends QueueDefinition> = Omit<EnqueueOptions, "id" | "singletonKey"> &
+	(TQueue["id"] extends undefined ? Pick<EnqueueOptions, "id"> : { readonly id?: never }) &
+	(TQueue["key"] extends undefined ? Pick<EnqueueOptions, "singletonKey"> : { readonly singletonKey?: never });
+
 export interface ScheduleOptions extends EnqueueOptions {
 	readonly key?: string;
 	readonly missed?: "skip" | "once";

package/src/server/error.ts

@@ -10,6 +10,7 @@ export type PgBossOperation =
 	| "getJob"
 	| "health"
 	| "install"
+	| "inspect"
 	| "register"
 	| "refreshQueueStats"
 	| "retry"

package/src/server/inspection.ts

@@ -0,0 +1,50 @@
+import { type DateTime, Effect } from "effect";
+import { defineService } from "@shivaedev/service/defineService.ts";
+import { genericMethod } from "@shivaedev/service/genericMethod.ts";
+import { inspection } from "#server/adapters/inspection.ts";
+import type { inspectionChanges } from "#server/adapters/inspectionChanges.ts";
+import type { inspectionReads } from "#server/adapters/inspectionReads.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
+import { PgBoss } from "#server/PgBoss.ts";
+import type { PgBossService } from "#server/service.ts";
+
+export type SnapshotQueue = Pick<QueueDefinition<string, JobPayloadSchema>, "name" | "schema">;
+
+export interface UnfinishedJob<TQueue extends SnapshotQueue> {
+	readonly data: TQueue["schema"]["Type"];
+	readonly id: string;
+	readonly queue: TQueue["name"];
+	readonly startAfter: DateTime.Utc;
+	readonly state: "active" | "created" | "deferred" | "failed" | "retry";
+}
+
+export const PgBossInspection = defineService({
+	id: "@shivaedev/jobs/PgBossInspection",
+	initialize: Effect.gen(function* () {
+		const acquired = yield* PgBoss;
+		return yield* inspection(acquired.client, acquired.schema);
+	}),
+	methods: (service) => ({
+		busy: service.busy,
+		changes: service.changes,
+		counts: service.counts,
+		deadLetteredJobs: genericMethod(service.deadLetteredJobs),
+		deferred: service.deferred,
+		failedJobs: genericMethod(service.failedJobs),
+		getJob: genericMethod(service.getJob),
+		health: service.health,
+		jobs: genericMethod(service.jobs),
+		queue: service.queue,
+		schedules: service.schedules,
+		schemaVersion: service.schemaVersion,
+		snapshot: genericMethod(service.snapshot),
+		storedJobs: service.storedJobs,
+	}),
+	requires: [PgBoss] as const,
+});
+
+export type PgBossInspectionService = ReturnType<typeof inspectionReads> &
+	Pick<PgBossService, "counts" | "deadLetteredJobs" | "failedJobs" | "getJob"> & {
+		readonly health: (queues: readonly { readonly name: string }[]) => ReturnType<PgBossService["health"]>;
+		readonly changes: (queue?: { readonly name: string }) => ReturnType<typeof inspectionChanges>;
+	};

package/src/server/internal/adapters/testingFetches.ts

@@ -1,4 +1,4 @@
-import type { EngineClient } from "#server/engineClient.ts";
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
 
 // pg-boss offers no hook for a worker fetch that finds nothing, so the controller recognizes its claim statement on the client's database.
 const claim = /UPDATE\s+\S+\s+j\s+SET\s+state\s*=\s*'active'/u;
@@ -9,7 +9,7 @@ export interface TestingFetches {
 	readonly passedSince: (queue: string, begun: number) => number;
 }
 
-export function testingFetches(db: ReturnType<EngineClient["getDb"]>, changed: () => void): TestingFetches {
+export function testingFetches(db: ClientDatabase, changed: () => void): TestingFetches {
 	const begun = new Map<string, number>();
 	const passed = new Map<string, number[]>();
 	const executeSql = db.executeSql.bind(db);

package/src/server/internal/deferral.ts

@@ -1,9 +1,7 @@
 import { Schema } from "effect";
-import type { PgBossClient } from "#server/client.ts";
 import type { WorkerJob } from "#server/job.ts";
 
 export const deferredAttempt = Symbol("deferredAttempt");
-export const deferralObservers = new WeakMap<PgBossClient, () => void>();
 export const STATELY_DEFERRAL_POLICY = "effect-stately-deferred";
 
 export const Deferral = Schema.Struct({

package/src/server/internal/engine.ts

@@ -27,15 +27,9 @@ export class JobEngine extends Context.Service<
 	}
 >()("@shivaedev/jobs/JobEngine") {}
 
-export interface TestingSettlements {
-	readonly close: Effect.Effect<void>;
-	readonly watch: (name: string) => Effect.Effect<void, PgBossTestingError>;
-}
-
 export class TestingEngine extends Context.Service<
 	TestingEngine,
 	{
 		readonly expireAttempt: (job: JobAttempt, cause?: "expiry" | "heartbeat") => Effect.Effect<void, PgBossTestingError>;
-		readonly observeSettlements: (settled: (name: string) => void) => Effect.Effect<TestingSettlements>;
 	}
 >()("@shivaedev/jobs/TestingEngine") {}

package/src/server/internal/enqueueFor.ts

@@ -1,10 +1,23 @@
 import { Effect, Option, Redacted, Schema } from "effect";
+import { payloadJobId, payloadKey } from "#server/adapters/payloadIdentity.ts";
 import { transactionDb } from "#server/adapters/transactionDb.ts";
 import type { PgBossClient } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
 import { PgBossPayloadError, toPgBossError } from "#server/error.ts";
 import { capturePayload } from "#server/internal/tracing.ts";
 import type { PgBossService } from "#server/service.ts";
 
+function identityOptions(queue: Pick<QueueDefinition, "id" | "key" | "name">, payload: object, options?: EnqueueOptions) {
+	return queue.id === undefined && queue.key === undefined
+		? options
+		: {
+				...options,
+				...(queue.id === undefined ? {} : { id: payloadJobId(queue.name, queue.id, payload) }),
+				...(queue.key === undefined ? {} : { singletonKey: payloadKey(queue.key, payload) }),
+			};
+}
+
 export function enqueueFor(client: PgBossClient): PgBossService["enqueue"] {
 	return (queue, payload, options) =>
 		Effect.gen(function* () {
@@ -20,7 +33,7 @@ export function enqueueFor(client: PgBossClient): PgBossService["enqueue"] {
 			}
 			const data = yield* capturePayload(encoded);
 			const db = yield* transactionDb;
-			const sendOptions = queue.key === undefined ? options : { ...options, singletonKey: queue.key(payload) };
+			const sendOptions = identityOptions(queue, payload, options);
 			const send = Effect.tryPromise({
 				catch: (error) => toPgBossError("enqueue", error, queue.name),
 				try: () => client.send(queue.name, data, db === undefined ? sendOptions : { ...sendOptions, db }),

package/src/server/internal/jobStorePlans.ts

@@ -1,6 +1,7 @@
+import { inspectionPlan } from "#server/adapters/inspectionPlan.ts";
 import { deadLetterResolutionPlan } from "#server/internal/deadLetterResolutionPlan.ts";
 import { deferralStorePlan } from "#server/internal/deferralStorePlan.ts";
 
 export function jobStorePlans(schema: string): readonly string[] {
-	return [deferralStorePlan(schema), deadLetterResolutionPlan(schema)];
+	return [deferralStorePlan(schema), deadLetterResolutionPlan(schema), inspectionPlan(schema)];
 }

package/src/server/internal/makeService.ts

@@ -1,11 +1,9 @@
 import { Effect } from "effect";
+import { inspection } from "#server/adapters/inspection.ts";
 import type { PgBossClient } from "#server/client.ts";
-import { countsFor } from "#server/internal/countsFor.ts";
 import { JobEngine } from "#server/internal/engine.ts";
 import { enqueueFor } from "#server/internal/enqueueFor.ts";
-import { healthFor } from "#server/internal/healthFor.ts";
 import { jobControl } from "#server/internal/jobControl.ts";
-import { jobListings } from "#server/internal/jobListings.ts";
 import type { PgBossService } from "#server/service.ts";
 
 export const makeService = Effect.fnUntraced(function* (
@@ -14,13 +12,16 @@ export const makeService = Effect.fnUntraced(function* (
 	schema = "pgboss",
 ): Effect.fn.Return<PgBossService, never, JobEngine> {
 	const engine = yield* JobEngine;
+	const reads = yield* inspection(client, schema);
 	return {
-		counts: (queue) => countsFor(client, schema, queue.name),
+		counts: (queue) => reads.counts(queue),
+		deadLetteredJobs: reads.deadLetteredJobs,
 		deleteQueue: engine.deleteQueue,
-		...(yield* jobListings),
 		enqueue: enqueueFor(client),
+		failedJobs: reads.failedJobs,
+		inspection: () => Effect.succeed(reads),
 		...(yield* jobControl),
-		health: (queues) => healthFor(client, queues === undefined ? names : queues.map((queue) => queue.name)),
+		health: (queues) => reads.health(queues ?? names.map((name) => ({ name }))),
 		refreshQueueStats: engine.refreshQueueStats,
 		unschedule: engine.unschedule,
 	};

package/src/server/internal/register.ts

@@ -7,7 +7,6 @@ import type { JobPayloadSchema, JobRegistration, QueueDefinition, QueueWorker, S
 import { PgBossQueueOptionsError, toPgBossError } from "#server/error.ts";
 import { ensureQueue } from "#server/internal/ensureQueue.ts";
 import { runQueueWorker } from "#server/internal/runQueueWorker.ts";
-import { registerTestingQueue } from "#server/internal/testingRegistrations.ts";
 
 function registrationDefinition(registration: JobRegistration): QueueDefinition | ScheduleDefinition {
 	if (registration._tag === "QueueDefinition") {
@@ -107,9 +106,6 @@ export const registerJobs = Effect.fnUntraced(function* <R>(
 	const scope = yield* Scope.fork(yield* Effect.scope, "parallel");
 	yield* Effect.try({ catch: (error) => toPgBossError("register", error), try: () => registrationNames(registrations) });
 	yield* prepareQueues(client, registrations, replaceWorkers);
-	for (const registration of registrations) {
-		registerTestingQueue(client, registrationName(registration));
-	}
 	if (!startWorkers) {
 		return;
 	}

package/src/server/internal/testingIdle.ts

@@ -1,10 +1,10 @@
-import { Clock, Effect, Schema } from "effect";
-import type { EngineClient } from "#server/engineClient.ts";
+import { Clock, Effect } from "effect";
 import type { PgBossTestingError } from "#server/error.ts";
-import { quotedSchema } from "#server/internal/storedRows.ts";
-import { testingOperation } from "#server/internal/testingReadout.ts";
+import type { PgBossInspectionService } from "#server/inspection.ts";
+import { testingInspection } from "#server/internal/testingOperation.ts";
 
 export interface TestingBatch {
+	readonly jobs: ReadonlyMap<string, number>;
 	readonly name: string;
 	settled: boolean;
 }
@@ -14,30 +14,12 @@ export interface TestingWork {
 	readonly queues: Set<string>;
 }
 
-const Busy = Schema.Struct({ busy: Schema.Boolean });
-
 export function testingIdle(
-	client: () => EngineClient,
-	schema: () => string,
+	inspection: () => PgBossInspectionService,
 	work: TestingWork,
 	signal: { readonly revision: Effect.Effect<number>; readonly waitForChange: (after: number) => Effect.Effect<number> },
 ): Effect.Effect<void, PgBossTestingError> {
-	const busy = testingOperation("waitForIdle", async () => {
-		const quoted = quotedSchema(schema());
-		const { rows } = await client()
-			.getDb()
-			.executeSql(
-				`/* jobs testing idle */ 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`,
-				[[...work.queues]],
-			);
-		return (await Schema.decodeUnknownPromise(Busy)(rows[0])).busy;
-	});
+	const busy = Effect.suspend(() => testingInspection("waitForIdle", inspection().busy([...work.queues].map((name) => ({ name })))));
 	return Effect.gen(function* () {
 		while (true) {
 			const revision = yield* signal.revision;
@@ -46,12 +28,7 @@ export function testingIdle(
 			if (work.queues.size === 0 || !(unsettled || (yield* busy))) {
 				return;
 			}
-			if (unsettled) {
-				yield* signal.waitForChange(revision);
-			} else {
-				// Other clients have no local callback; PostgreSQL remains the source of idle state.
-				yield* Effect.raceFirst(signal.waitForChange(revision), Effect.sleep("50 millis"));
-			}
+			yield* signal.waitForChange(revision);
 		}
 	}).pipe(Effect.provideService(Clock.Clock, Clock.Clock.defaultValue()));
 }

package/src/server/internal/testingOperation.ts

@@ -0,0 +1,18 @@
+import { Effect, Redacted } from "effect";
+import { PgBossError, PgBossTestingError } from "#server/error.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 testingInspection<A, E, R>(operation: string, effect: Effect.Effect<A, E | PgBossError, R>, queue?: string) {
+	return effect.pipe(
+		Effect.catchIf(
+			(error): error is PgBossError => error instanceof PgBossError,
+			(error) => Effect.fail(new PgBossTestingError({ operation, original: error.original, queue: queue ?? error.queue })),
+		),
+	);
+}