@shivaedev/jobs 0.31.0 → 0.34.0

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/deferralChanges.ts

@@ -0,0 +1,3 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+
+export const deferralChanges = new WeakMap<ClientDatabase, () => void>();

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 { 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,13 @@ 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> },
+	wake: Effect.Effect<void> = Effect.void,
 ): 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 +29,8 @@ 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* wake;
+			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 })),
+		),
+	);
+}

package/src/server/internal/testingSchedules.ts

@@ -1,23 +1,35 @@
+import { Effect, Redacted } from "effect";
+import type { PgBossClient } from "#server/client.ts";
 import type { ScheduleDefinition } from "#server/definition.ts";
-import type { EngineClient } from "#server/engineClient.ts";
-import { testingOperation } from "#server/internal/testingReadout.ts";
+import { PgBossTestingError } from "#server/error.ts";
+import type { PgBossInspectionService } from "#server/inspection.ts";
+import { testingInspection, testingOperation } from "#server/internal/testingOperation.ts";
 
-export function testingSchedules(client: () => EngineClient, changed: () => void) {
+export function testingSchedules(client: () => PgBossClient, inspection: () => PgBossInspectionService) {
 	return {
 		schedules: () =>
-			testingOperation("schedules", async () => (await client().getSchedules()).map(({ name, cron, timezone }) => ({ cron, name, timezone }))),
-		trigger: (schedule: Pick<ScheduleDefinition, "name" | "scheduleOptions">) =>
-			testingOperation(
-				"trigger",
-				async () => {
-					const [registered] = await client().getSchedules(schedule.name, schedule.scheduleOptions.key ?? "");
-					if (registered === undefined) {
-						throw new Error("Schedule is not registered");
-					}
-					await client().send(registered.name, registered.data, { ...registered.options, startAfter: 0 });
-					changed();
-				},
-				schedule.name,
+			Effect.suspend(() => testingInspection("schedules", inspection().schedules())).pipe(
+				Effect.map((schedules) => schedules.map(({ name, cron, timezone }) => ({ cron, name, timezone }))),
 			),
+		trigger: (schedule: Pick<ScheduleDefinition, "name" | "scheduleOptions">) =>
+			Effect.gen(function* () {
+				const [registered] = yield* testingInspection(
+					"trigger",
+					inspection().schedules(schedule.name, schedule.scheduleOptions.key ?? ""),
+					schedule.name,
+				);
+				if (registered === undefined) {
+					return yield* new PgBossTestingError({
+						operation: "trigger",
+						original: Redacted.make(new Error("Schedule is not registered")),
+						queue: schedule.name,
+					});
+				}
+				return yield* testingOperation(
+					"trigger",
+					() => client().send(registered.name, registered.data, { ...registered.options, startAfter: 0 }),
+					schedule.name,
+				);
+			}),
 	};
 }

package/src/server/internal/testingWaits.ts

@@ -1,10 +1,9 @@
-import { Clock, Duration, Effect, Option, Redacted } from "effect";
+import { Duration, Effect, Option, Redacted, type Schema } from "effect";
 import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
-import type { EngineClient } from "#server/engineClient.ts";
 import { type PgBossPayloadError, PgBossTestingError, PgBossWaitError } from "#server/error.ts";
+import type { PgBossInspectionService } from "#server/inspection.ts";
 import type { TestingFetches } from "#server/internal/adapters/testingFetches.ts";
-import { decodeStoredData } from "#server/internal/storedRows.ts";
-import { testingOperation } from "#server/internal/testingReadout.ts";
+import { testingInspection } from "#server/internal/testingOperation.ts";
 import type { Job, JobState } from "#server/job.ts";
 import type { PgBossTestingWaitOptions } from "#server/testing.ts";
 
@@ -38,11 +37,7 @@ function waitUntil<A, E, R>(
 				yield* signal.waitForChange(revision);
 			}
 		});
-		return wait.pipe(
-			Effect.timeoutOrElse({ duration: within, orElse: () => Effect.fail(new PgBossWaitError({ lastSeen, waitingFor, within })) }),
-			// The budget is wall time, so a story's TestClock neither ends the wait early nor holds it open.
-			Effect.provideService(Clock.Clock, Clock.Clock.defaultValue()),
-		);
+		return wait.pipe(Effect.timeoutOrElse({ duration: within, orElse: () => Effect.fail(new PgBossWaitError({ lastSeen, waitingFor, within })) }));
 	});
 }
 
@@ -50,7 +45,7 @@ function fetchesRefused(queue: Pick<QueueDefinition, "name">, original: Error) {
 	return new PgBossTestingError({ operation: "fetchesPass", original: Redacted.make(original), queue: queue.name });
 }
 
-export function testingWaits(client: () => EngineClient, fetches: () => TestingFetches | undefined, signal: Signal) {
+export function testingWaits(inspection: () => PgBossInspectionService, fetches: () => TestingFetches | undefined, signal: Signal) {
 	return {
 		fetchesPass: (queue: Pick<QueueDefinition, "name">, count: number, options?: PgBossTestingWaitOptions) =>
 			Effect.gen(function* () {
@@ -73,8 +68,8 @@ export function testingWaits(client: () => EngineClient, fetches: () => TestingF
 					options,
 				);
 			}),
-		untilJob: <TName extends string, TPayload extends JobPayloadSchema>(
-			queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">,
+		untilJob: <TName extends string, TPayload extends JobPayloadSchema | typeof Schema.Null>(
+			queue: { readonly name: TName; readonly schema: TPayload },
 			id: string,
 			state: JobState,
 			options?: PgBossTestingWaitOptions,
@@ -82,15 +77,15 @@ export function testingWaits(client: () => EngineClient, fetches: () => TestingF
 			waitUntil(
 				signal,
 				`job ${id} in ${queue.name} is ${state}`,
-				testingOperation("untilJob", () => client().getJobById<unknown>(queue.name, id), queue.name).pipe(
-					Effect.flatMap((job): Effect.Effect<Reading<Job<TPayload["Type"]>>, PgBossPayloadError, TPayload["DecodingServices"]> => {
-						if (job === null) {
+				Effect.suspend(() => testingInspection("untilJob", inspection().jobs(queue, { id }), queue.name)).pipe(
+					Effect.flatMap(([job]): Effect.Effect<Reading<Job<TPayload["Type"]>>, PgBossPayloadError, TPayload["DecodingServices"]> => {
+						if (job === undefined) {
 							return Effect.succeed({ arrived: Option.none(), seen: "no such job" });
 						}
 						if (job.state !== state) {
 							return Effect.succeed({ arrived: Option.none(), seen: job.state });
 						}
-						return Effect.map(decodeStoredData(queue, job.data), (data) => ({ arrived: Option.some({ ...job, data }), seen: job.state }));
+						return Effect.succeed({ arrived: Option.some(job), seen: job.state });
 					}),
 				),
 				options,

package/src/server/schema.ts

@@ -43,10 +43,15 @@ export function pgBossSchema(options: PgBossSchemaOptions = {}): SchemaComponent
 			const deferrals = sql`${sql(schema)}.${sql("effect_job_deferral")}`;
 			const cleanup = sql`${sql(schema)}.${sql("effect_job_deferral_keep_until")}`;
 			const stately = sql`${sql(schema)}.${sql("effect_stately_deferral")}()`;
+			const changed = sql`${sql(schema)}.${sql("effect_job_changed")}()`;
 			const missing = yield* sql`SELECT name FROM (VALUES
 				('dead-letter resolution trigger', EXISTS (
 					SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass(${job.compile()[0]}) AND tgname = 'effect_dead_letter_resolution'
 				)),
+				('effect_job_changed()', to_regprocedure(${changed.compile()[0]}) IS NOT NULL),
+				('effect_job_changed trigger', EXISTS (
+					SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass(${job.compile()[0]}) AND tgname = 'effect_job_changed'
+				)),
 				('effect_job_deferral', to_regclass(${deferrals.compile()[0]}) IS NOT NULL),
 				('effect_job_deferral_keep_until', to_regclass(${cleanup.compile()[0]}) IS NOT NULL),
 				('effect_stately_deferral()', to_regprocedure(${stately.compile()[0]}) IS NOT NULL),

package/src/server/service.ts

@@ -7,7 +7,7 @@ import { clientEngine } from "#server/adapters/lifecycle.ts";
 import type { PgBossClientFactory } from "#server/client.ts";
 import type { ClientOptions, StopOptions } from "#server/clientOptions.ts";
 import type { JobPayloadSchema, JobRegistration, QueueDefinition, RegistrationRequirements, ScheduleDefinition } from "#server/definition.ts";
-import type { EnqueueOptions } from "#server/enqueueOptions.ts";
+import type { QueueEnqueueOptions } from "#server/enqueueOptions.ts";
 import type {
 	PgBossClientOptionsError,
 	PgBossError,
@@ -17,6 +17,7 @@ import type {
 	PgBossQueueOptionsError,
 } from "#server/error.ts";
 import type { DeadLetteredJob, JobPage, JobPageOptions, JobsHealth, ListedJob, QueueCounts } from "#server/health.ts";
+import type { PgBossInspectionService } from "#server/inspection.ts";
 import { acquireClient } from "#server/internal/acquireClient.ts";
 import { logClientError, subscribeClientErrors } from "#server/internal/clientErrors.ts";
 import { JobEngine } from "#server/internal/engine.ts";
@@ -38,7 +39,7 @@ export interface PgBossService {
 	readonly enqueue: <const TName extends string, const TPayload extends JobPayloadSchema, const TQueue extends QueueDefinition<TName, TPayload>>(
 		queue: QueueDefinition<TName, TPayload> & TQueue,
 		payload: NoInfer<Schema.Schema.Type<TPayload>>,
-		options?: NoInfer<TQueue["key"] extends undefined ? EnqueueOptions : Omit<EnqueueOptions, "singletonKey"> & { readonly singletonKey?: never }>,
+		options?: NoInfer<QueueEnqueueOptions<TQueue>>,
 	) => Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError, TPayload["EncodingServices"]>;
 	readonly failedJobs: <const TName extends string, const TPayload extends JobPayloadSchema | typeof Schema.Null>(
 		queue: { readonly name: TName; readonly schema: TPayload },
@@ -49,6 +50,7 @@ export interface PgBossService {
 		id: string,
 	) => Effect.Effect<Option.Option<Job<unknown>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
 	readonly health: (queues?: readonly Pick<QueueDefinition, "name">[]) => Effect.Effect<JobsHealth, PgBossError>;
+	readonly inspection: () => Effect.Effect<PgBossInspectionService>;
 	readonly refreshQueueStats: (queue?: Pick<QueueDefinition, "name">) => Effect.Effect<void, PgBossError>;
 	readonly retry: (queue: Pick<QueueDefinition, "name">, id: string) => Effect.Effect<void, PgBossError>;
 	readonly unschedule: (schedule: Pick<ScheduleDefinition, "name" | "scheduleOptions">) => Effect.Effect<void, PgBossError | PgBossNotFoundError>;
@@ -117,6 +119,7 @@ export function makePgBoss<const TIdentifier extends string>(identifier: TIdenti
 				failedJobs: genericMethod(service.failedJobs),
 				getJob: genericMethod(service.getJob),
 				health: service.health,
+				inspection: service.inspection,
 				refreshQueueStats: service.refreshQueueStats,
 				retry: service.retry,
 				unschedule: service.unschedule,

package/src/server/testing.ts

@@ -1,21 +1,11 @@
-import { type DateTime, type Duration, Effect, type Tracer } from "effect";
+import { type Duration, Effect, type Tracer } from "effect";
+import type { TestClock } from "effect/testing";
 import { testingController } from "#server/adapters/testingController.ts";
-import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
 
 export function makePgBossTesting(options: PgBossTestingOptions = {}) {
 	return testingController(options);
 }
 
-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 interface PgBossTestingWaitOptions {
 	readonly within?: Duration.Input;
 }
@@ -23,6 +13,7 @@ export interface PgBossTestingWaitOptions {
 export const testRetryPolicy = Object.freeze({ retryBackoff: false, retryDelay: 0 });
 
 export interface PgBossTestingOptions {
+	readonly clock?: TestClock.TestClock;
 	readonly retryPolicy?: typeof testRetryPolicy;
 }
 

package/dist/server/adapters/observeTestingSettlements.d.ts

@@ -1,6 +0,0 @@
-import type { EngineClient } from "#server/engineClient.ts";
-export declare function observeTestingSettlements(client: EngineClient, settled: (name: string) => void): {
-    close(): void;
-    watch(name: string): void;
-};
-//# sourceMappingURL=observeTestingSettlements.d.ts.map

package/dist/server/adapters/observeTestingSettlements.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"observeTestingSettlements.d.ts","sourceRoot":"","sources":["../../../src/server/adapters/observeTestingSettlements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;IAG7F,KAAK;IAML,KAAK,OAAO,MAAM;EAwBnB"}

package/dist/server/adapters/observeTestingSettlements.js

@@ -1,35 +0,0 @@
-export function observeTestingSettlements(client, settled) {
-    const observers = new Map();
-    return {
-        close() {
-            for (const close of observers.values()) {
-                close();
-            }
-            observers.clear();
-        },
-        watch(name) {
-            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();
-                    settled(name);
-                }
-            }
-            observers.set(name, () => {
-                open = false;
-                spy.clear();
-            });
-            void observe().catch((error) => client.emit("error", error instanceof Error ? error : new Error(String(error))));
-        },
-    };
-}
-//# sourceMappingURL=observeTestingSettlements.js.map

package/dist/server/adapters/observeTestingSettlements.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"observeTestingSettlements.js","sourceRoot":"","sources":["../../../src/server/adapters/observeTestingSettlements.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,yBAAyB,CAAC,MAAoB,EAAE,OAA+B;IAC9F,MAAM,SAAS,GAAG,IAAI,GAAG,EAAsB,CAAC;IAChD,OAAO;QACN,KAAK;YACJ,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;gBACxC,KAAK,EAAE,CAAC;YACT,CAAC;YACD,SAAS,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QACD,KAAK,CAAC,IAAY;YACjB,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,OAAO;YACR,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,IAAI,GAAG,IAAI,CAAC;YAChB,KAAK,UAAU,OAAO;gBACrB,OAAO,IAAI,EAAE,CAAC;oBACb,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;oBACpG,IAAI,CAAC,IAAI,EAAE,CAAC;wBACX,OAAO;oBACR,CAAC;oBACD,iGAAiG;oBACjG,GAAG,CAAC,KAAK,EAAE,CAAC;oBACZ,OAAO,CAAC,IAAI,CAAC,CAAC;gBACf,CAAC;YACF,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE;gBACxB,IAAI,GAAG,KAAK,CAAC;gBACb,GAAG,CAAC,KAAK,EAAE,CAAC;YACb,CAAC,CAAC,CAAC;YACH,KAAK,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3H,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/server/internal/testingDeferrals.d.ts

@@ -1,10 +0,0 @@
-import { DateTime } from "effect";
-import type { QueueDefinition } from "#server/definition.ts";
-import type { EngineClient } from "#server/engineClient.ts";
-export declare function testingDeferrals(client: () => EngineClient): {
-    deferred: (queue: Pick<QueueDefinition, "name">) => import("effect/Effect").Effect<{
-        at: DateTime.Utc;
-        reason: string;
-    }[], import("../error.ts").PgBossTestingError, never>;
-};
-//# sourceMappingURL=testingDeferrals.d.ts.map

package/dist/server/internal/testingDeferrals.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"testingDeferrals.d.ts","sourceRoot":"","sources":["../../../src/server/internal/testingDeferrals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAI5D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,YAAY;IAEzD,QAAQ,UAAU,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC;;;;EAahD"}

package/dist/server/internal/testingDeferrals.js

@@ -1,15 +0,0 @@
-import { DateTime } from "effect";
-import { deferralOf } from "#server/internal/deferral.ts";
-import { testingOperation } from "#server/internal/testingReadout.ts";
-export function testingDeferrals(client) {
-    return {
-        deferred: (queue) => testingOperation("deferred", async () => {
-            const jobs = await client().findJobs(queue.name);
-            return jobs.flatMap((job) => {
-                const deferral = job.state === "retry" && job.startedOn === null ? deferralOf(job) : undefined;
-                return deferral === undefined ? [] : [{ at: DateTime.makeUnsafe(job.startAfter), reason: deferral.reason }];
-            });
-        }, queue.name),
-    };
-}
-//# sourceMappingURL=testingDeferrals.js.map

package/dist/server/internal/testingDeferrals.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"testingDeferrals.js","sourceRoot":"","sources":["../../../src/server/internal/testingDeferrals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGlC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAEtE,MAAM,UAAU,gBAAgB,CAAC,MAA0B;IAC1D,OAAO;QACN,QAAQ,EAAE,CAAC,KAAoC,EAAE,EAAE,CAClD,gBAAgB,CACf,UAAU,EACV,KAAK,IAAI,EAAE;YACV,MAAM,IAAI,GAAG,MAAM,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;gBAC3B,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,KAAK,OAAO,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC/F,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YAC7G,CAAC,CAAC,CAAC;QACJ,CAAC,EACD,KAAK,CAAC,IAAI,CACV;KACF,CAAC;AACH,CAAC"}

package/dist/server/internal/testingReadout.d.ts

@@ -1,10 +0,0 @@
-import { Effect } from "effect";
-import type { JobReadOptions } from "#server/client.ts";
-import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
-import type { EngineClient } from "#server/engineClient.ts";
-import type { PgBossPayloadError } from "#server/error.ts";
-import { PgBossTestingError } from "#server/error.ts";
-import type { Job } from "#server/job.ts";
-export declare function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string): Effect.Effect<A, PgBossTestingError, never>;
-export declare function testingReadout(client: () => EngineClient): <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: JobReadOptions) => Effect.Effect<Job<TPayload["Type"]>[], PgBossTestingError | PgBossPayloadError, TPayload["DecodingServices"]>;
-//# sourceMappingURL=testingReadout.d.ts.map

package/dist/server/internal/testingReadout.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"testingReadout.d.ts","sourceRoot":"","sources":["../../../src/server/internal/testingReadout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAY,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAE1C,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,+CAK3F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,YAAY,IAChD,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,gBAAgB,SACvD,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,YAC7B,cAAc,KACtB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAIhH"}