@shivaedev/jobs 0.29.2 → 0.31.0

package/src/server/internal/enqueueFor.ts

@@ -1,9 +1,9 @@
 import { Effect, Option, Redacted, Schema } from "effect";
-import { transactionDb } from "#adapters/transactionDb.ts";
-import type { PgBossClient } from "#client.ts";
-import { PgBossPayloadError, toPgBossError } from "#error.ts";
-import { capturePayload } from "#internal/tracing.ts";
-import type { PgBossService } from "#service.ts";
+import { transactionDb } from "#server/adapters/transactionDb.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { PgBossPayloadError, toPgBossError } from "#server/error.ts";
+import { capturePayload } from "#server/internal/tracing.ts";
+import type { PgBossService } from "#server/service.ts";
 
 export function enqueueFor(client: PgBossClient): PgBossService["enqueue"] {
 	return (queue, payload, options) =>

package/src/server/internal/ensureQueue.ts

@@ -1,15 +1,14 @@
 import { Effect, Schedule } from "effect";
-import type { Queue } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { PgBossQueueOptionsError } from "#error.ts";
-import { deadLetterQueueName } from "#health.ts";
+import type { ClientQueueOptions, PgBossClient } from "#server/client.ts";
+import { PgBossQueueOptionsError } from "#server/error.ts";
+import { deadLetterQueueName } from "#server/health.ts";
 
 const DEADLOCK_DETECTED = "40P01";
 const CREATE_QUEUE_ATTEMPTS = 6;
 
 // A partitioned queue attaches its table to pg-boss's job table, which can deadlock with job traffic on other queues.
 // PostgreSQL rolls the whole creation back, so trying it again is safe.
-function createQueue(client: PgBossClient, name: string, options?: Omit<Queue, "name">) {
+function createQueue(client: PgBossClient, name: string, options?: ClientQueueOptions) {
 	return Effect.tryPromise({ catch: (error) => error, try: () => client.createQueue(name, options) }).pipe(
 		Effect.retry({
 			schedule: Schedule.exponential(25).pipe(Schedule.upTo({ times: CREATE_QUEUE_ATTEMPTS - 1 })),
@@ -18,7 +17,7 @@ function createQueue(client: PgBossClient, name: string, options?: Omit<Queue, "
 	);
 }
 
-export const ensureQueue = Effect.fnUntraced(function* (client: PgBossClient, name: string, options: Omit<Queue, "name" | "deadLetter">) {
+export const ensureQueue = Effect.fnUntraced(function* (client: PgBossClient, name: string, options: Omit<ClientQueueOptions, "deadLetter">) {
 	const deadLetter = deadLetterQueueName(name);
 	const desired = { retryBackoff: true, retryLimit: 3, ...options, deadLetter };
 	yield* createQueue(client, deadLetter);

package/src/server/internal/healthFor.ts

@@ -1,9 +1,9 @@
 import { Effect } from "effect";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
-import { deadLetterQueueName, type JobsHealth, type QueueHealth } from "#health.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deadLetterQueueName, type JobsHealth, type QueueHealth } from "#server/health.ts";
 
-export function healthFor(client: PgBossClient, names: readonly string[]): Effect.Effect<JobsHealth, import("#error.ts").PgBossError> {
+export function healthFor(client: PgBossClient, names: readonly string[]): Effect.Effect<JobsHealth, import("#server/error.ts").PgBossError> {
 	return Effect.forEach(
 		names,
 		(name) =>

package/src/server/internal/jobControl.ts

@@ -1,62 +1,27 @@
-import { Effect, Option, Redacted, Schema } from "effect";
+import { Effect, Option } from "effect";
 import { redact } from "@shivaedev/errors/redact.ts";
-import type { PgBossClient } from "#client.ts";
-import { PgBossPayloadError, toPgBossError } from "#error.ts";
-import { deferralOf } from "#internal/deferral.ts";
-import { decodeStoredData } from "#internal/storedRows.ts";
-import { JobFailure } from "#JobFailure.ts";
-import type { PgBossService } from "#service.ts";
+import { deferralOf } from "#server/internal/deferral.ts";
+import { JobEngine } from "#server/internal/engine.ts";
+import { decodeStoredData } from "#server/internal/storedRows.ts";
+import { readJobFailure } from "#server/readJobFailure.ts";
+import type { PgBossService } from "#server/service.ts";
 
-const StoredFailure = Schema.Union([JobFailure, Schema.Struct({ value: JobFailure })]);
-
-function decodeFailure(queue: string, output: unknown) {
-	return Schema.decodeUnknownEffect(StoredFailure)(output).pipe(
-		Effect.map((failure) => ("value" in failure ? failure.value : failure)),
-		Effect.mapError((error) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(error), queue })),
-	);
-}
-
-export function getJobFor(client: PgBossClient): PgBossService["getJob"] {
-	return (queue, id) =>
-		Effect.tryPromise({
-			catch: (error) => toPgBossError("getJob", error, queue.name),
-			try: async () => {
-				if (client.findJobs === undefined) {
-					throw new TypeError("This pg-boss client does not support findJobs");
-				}
-				return (await client.findJobs(queue.name, { id }))[0];
-			},
-		}).pipe(
+export const jobControl = Effect.gen(function* () {
+	const engine = yield* JobEngine;
+	const getJob: PgBossService["getJob"] = (queue, id) =>
+		engine.getJob(queue.name, id).pipe(
 			Effect.flatMap(
 				Effect.fnUntraced(function* (job) {
 					if (job === undefined) {
 						return Option.none();
 					}
 					const data = yield* decodeStoredData(queue, job.data);
-					const output = job.output === null || deferralOf(job) !== undefined ? job.output : yield* decodeFailure(queue.name, job.output);
-					const sourceOutput = job.sourceOutput === null ? null : yield* decodeFailure(queue.name, job.sourceOutput);
+					const output = deferralOf(job) === undefined ? yield* readJobFailure(queue.name, job.output) : job.output;
+					const sourceOutput = yield* readJobFailure(queue.name, job.sourceOutput);
 					return Option.some({ ...job, data: redact(data), output, sourceOutput });
 				}),
 			),
 		);
-}
-
-export function retryFor(client: PgBossClient): PgBossService["retry"] {
-	return (queue, id) =>
-		Effect.tryPromise({
-			catch: (error) => toPgBossError("retry", error, queue.name),
-			try: async () => {
-				if (client.findJobs === undefined || client.retry === undefined || client.update === undefined) {
-					throw new TypeError("This pg-boss client does not support findJobs, retry and update");
-				}
-				const job = (await client.findJobs(queue.name, { id }))[0];
-				if (job?.state !== "failed" && job?.state !== "retry") {
-					return;
-				}
-				if (job.state === "failed") {
-					await client.retry(queue.name, id);
-				}
-				await client.update(queue.name, undefined, { id, startAfter: 0 });
-			},
-		});
-}
+	const retry: PgBossService["retry"] = (queue, id) => engine.retry(queue.name, id);
+	return { getJob, retry };
+});

package/src/server/internal/jobListings.ts

@@ -0,0 +1,85 @@
+import { type Context, Effect, Option, Redacted, Schema } from "effect";
+import { redact } from "@shivaedev/errors/redact.ts";
+import type { JobPayloadSchema } from "#server/definition.ts";
+import { type PgBossError, PgBossPayloadError } from "#server/error.ts";
+import type { DeadLetteredJob, JobPage, JobPageOptions } from "#server/health.ts";
+import { JobEngine, type Listing } from "#server/internal/engine.ts";
+import { decodeStoredData } from "#server/internal/storedRows.ts";
+import { readJobFailure } from "#server/readJobFailure.ts";
+import type { PgBossService } from "#server/service.ts";
+
+const Cursor = Schema.StringFromBase64Url.pipe(
+	Schema.decodeTo(
+		Schema.fromJsonString(
+			Schema.Tuple([
+				Schema.String.check(Schema.makeFilter((value) => Option.isSome(Schema.decodeUnknownOption(Schema.DateTimeUtcFromString)(value)))),
+				Schema.String.check(Schema.isUUID()),
+			]),
+		),
+	),
+);
+const PageOptions = Schema.Struct({
+	cursor: Schema.optionalKey(Schema.UndefinedOr(Cursor)),
+	limit: Schema.Number.check(Schema.isInt(), Schema.isGreaterThan(0)),
+});
+
+const Row = Schema.Struct({
+	completedOn: Schema.OptionFromNullOr(Schema.DateTimeUtcFromDate),
+	createdOn: Schema.DateTimeUtcFromDate,
+	cursorAt: Schema.String,
+	data: Schema.Unknown,
+	id: Schema.String,
+	output: Schema.Unknown,
+	queue: Schema.String,
+	retryCount: Schema.Number,
+	retryLimit: Schema.Number,
+	sourceId: Schema.OptionFromNullOr(Schema.String),
+	sourceOutput: Schema.Unknown,
+	startedOn: Schema.OptionFromNullOr(Schema.DateTimeUtcFromDate),
+	state: Schema.Literals(["created", "retry", "active", "completed", "cancelled", "failed"]),
+});
+
+const Rows = Schema.Array(Row);
+
+export const jobListings = Effect.gen(function* () {
+	const engine = yield* JobEngine;
+	const failedJobs: PgBossService["failedJobs"] = (queue, options) =>
+		listJobs(engine, "failedJobs", queue, options).pipe(
+			Effect.map(({ jobs, next }) => ({ jobs: jobs.map(({ sourceId: _id, sourceOutput: _output, ...job }) => job), next })),
+		);
+	const deadLetteredJobs: PgBossService["deadLetteredJobs"] = (queue, options) =>
+		listJobs(engine, "deadLetteredJobs", queue, options).pipe(
+			Effect.map(({ jobs, next }) => ({ jobs: jobs.map((job) => ({ ...job, sourceQueue: queue.name })), next })),
+		);
+	return { deadLetteredJobs, failedJobs };
+});
+
+const listJobs = Effect.fnUntraced(function* <const TName extends string, const TPayload extends JobPayloadSchema | typeof Schema.Null>(
+	engine: Context.Service.Shape<typeof JobEngine>,
+	listing: Listing,
+	queue: { readonly name: TName; readonly schema: TPayload },
+	options: JobPageOptions,
+): Effect.fn.Return<
+	JobPage<Omit<DeadLetteredJob<unknown>, "sourceQueue">>,
+	PgBossError | PgBossPayloadError | Schema.SchemaError,
+	TPayload["DecodingServices"]
+> {
+	const { cursor: after, limit } = yield* Schema.decodeUnknownEffect(PageOptions)(options);
+	const rows = yield* engine.listJobs(listing, queue.name, after, limit);
+	const decodedRows = yield* Schema.decodeUnknownEffect(Rows)(rows).pipe(
+		Effect.mapError((error) => new PgBossPayloadError({ direction: "decode", original: Redacted.make(error), queue: queue.name })),
+	);
+	const page = decodedRows.slice(0, limit);
+	const last = page.at(-1);
+	const next = decodedRows.length > limit && last !== undefined ? Option.some(Schema.encodeSync(Cursor)([last.cursorAt, last.id])) : Option.none();
+	const jobs = yield* Effect.forEach(
+		page,
+		Effect.fnUntraced(function* ({ cursorAt: _, data, ...row }) {
+			const decoded = yield* decodeStoredData(queue, data);
+			const output = yield* readJobFailure(queue.name, row.output);
+			const sourceOutput = yield* readJobFailure(queue.name, row.sourceOutput);
+			return { ...row, attempt: Option.isSome(row.startedOn) ? row.retryCount + 1 : 0, data: redact(decoded), output, sourceOutput };
+		}),
+	);
+	return { jobs, next };
+});

package/src/server/internal/jobStorePlans.ts

@@ -1,5 +1,5 @@
-import { deadLetterResolutionPlan } from "#internal/deadLetterResolutionPlan.ts";
-import { deferralStorePlan } from "#internal/deferralStorePlan.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)];

package/src/server/internal/lifecycle.ts

@@ -1,16 +1,12 @@
-import { Effect } from "effect";
-import type { ConstructorOptions, StopOptions } from "pg-boss";
-import type { PgBossClient, PgBossClientFactory } from "#client.ts";
-import { defaultClientFactory } from "#defaultClientFactory.ts";
-import { PgBossClientOptionsError, type PgBossError, toPgBossError } from "#error.ts";
-import { jobStorePlans } from "#internal/jobStorePlans.ts";
-import { acquireCachedClient, releaseCachedClient } from "./clientCache.ts";
-import { observeClientErrors } from "./clientErrors.ts";
+import { Context, type Effect, type Scope } from "effect";
+import type { PgBossClient, PgBossClientFactory } from "#server/client.ts";
+import type { ClientOptions, StopOptions } from "#server/clientOptions.ts";
+import type { PgBossClientOptionsError, PgBossError } from "#server/error.ts";
 
 export interface AcquireClientOptions {
 	readonly clientCacheKey?: string | symbol | undefined;
 	readonly clientFactory?: PgBossClientFactory | undefined;
-	readonly constructor: ConstructorOptions;
+	readonly constructor: ClientOptions;
 }
 
 export interface AcquiredClient {
@@ -19,50 +15,13 @@ export interface AcquiredClient {
 	readonly reused: boolean;
 }
 
-async function startClient(options: AcquireClientOptions, report: (error: Error) => void): Promise<PgBossClient> {
-	const client = (options.clientFactory ?? defaultClientFactory)(options.constructor);
-	observeClientErrors(client, report);
-	try {
-		await client.start();
-		if (options.constructor.migrate !== false && client.getDb !== undefined) {
-			for (const plan of jobStorePlans(options.constructor.schema ?? "pgboss")) {
-				await client.getDb().executeSql(plan);
-			}
-		}
-		return client;
-	} catch (error) {
-		try {
-			await client.stop();
-		} catch {
-			// Preserve the startup failure; stop is best effort on failed acquisition.
-		}
-		throw error;
+export class ClientEngine extends Context.Service<
+	ClientEngine,
+	{
+		readonly acquire: (
+			options: AcquireClientOptions,
+			report: (error: Error) => void,
+			stop?: StopOptions,
+		) => Effect.Effect<AcquiredClient, PgBossError | PgBossClientOptionsError, Scope.Scope>;
 	}
-}
-
-export function acquireClient(
-	options: AcquireClientOptions,
-	report: (error: Error) => void,
-): Effect.Effect<AcquiredClient, PgBossError | PgBossClientOptionsError> {
-	return Effect.tryPromise({
-		catch: (error) => (error instanceof PgBossClientOptionsError ? error : toPgBossError("start", error)),
-		try: async () => {
-			const cacheKey = options.clientCacheKey;
-			return cacheKey === undefined
-				? { client: await startClient(options, report), reused: false }
-				: { cacheKey, ...(await acquireCachedClient(cacheKey, options.constructor, () => startClient(options, report))) };
-		},
-	});
-}
-
-export function releaseClient(acquired: AcquiredClient, stopOptions?: StopOptions): Effect.Effect<void> {
-	return Effect.tryPromise({
-		catch: (error) => toPgBossError("stop", error),
-		try: async () => {
-			const client = acquired.cacheKey === undefined ? acquired.client : await releaseCachedClient(acquired.cacheKey);
-			if (client !== undefined) {
-				await client.stop(stopOptions);
-			}
-		},
-	}).pipe(Effect.catch((error) => Effect.logError(error)));
-}
+>()("@shivaedev/jobs/ClientEngine") {}

package/src/server/internal/makeService.ts

@@ -1,19 +1,27 @@
-import type { PgBossClient } from "#client.ts";
-import { countsFor } from "#internal/countsFor.ts";
-import { enqueueFor } from "#internal/enqueueFor.ts";
-import { healthFor } from "#internal/healthFor.ts";
-import { getJobFor, retryFor } from "#internal/jobControl.ts";
-import { deadLetteredJobsFor, failedJobsFor } from "#internal/listJobs.ts";
-import type { PgBossService } from "#service.ts";
+import { Effect } from "effect";
+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 function makeService(client: PgBossClient, names: readonly string[], schema = "pgboss"): PgBossService {
+export const makeService = Effect.fnUntraced(function* (
+	client: PgBossClient,
+	names: readonly string[],
+	schema = "pgboss",
+): Effect.fn.Return<PgBossService, never, JobEngine> {
+	const engine = yield* JobEngine;
 	return {
 		counts: (queue) => countsFor(client, schema, queue.name),
-		deadLetteredJobs: deadLetteredJobsFor(client, schema),
+		deleteQueue: engine.deleteQueue,
+		...(yield* jobListings),
 		enqueue: enqueueFor(client),
-		failedJobs: failedJobsFor(client, schema),
-		getJob: getJobFor(client),
+		...(yield* jobControl),
 		health: (queues) => healthFor(client, queues === undefined ? names : queues.map((queue) => queue.name)),
-		retry: retryFor(client),
+		refreshQueueStats: engine.refreshQueueStats,
+		unschedule: engine.unschedule,
 	};
-}
+});

package/src/server/internal/register.ts

@@ -1,36 +1,22 @@
 import { type Context, Effect, Scope } from "effect";
-import type { StopOptions } from "pg-boss";
-import { registerWorker } from "#adapters/registerWorker.ts";
-import { workerDiagnostics } from "#adapters/workerDiagnostics.ts";
-import type { PgBossClient } from "#client.ts";
-import type { JobRegistration, QueueDefinition, QueueWorker, ScheduleDefinition, ScheduledWorker } from "#definition.ts";
-import { PgBossQueueOptionsError, toPgBossError } from "#error.ts";
-import { ensureQueue } from "#internal/ensureQueue.ts";
-import { runQueueWorker } from "#internal/runQueueWorker.ts";
-
-function isQueueWorker(registration: JobRegistration): registration is QueueWorker {
-	return registration._tag === "QueueWorker";
-}
-
-function isScheduledWorker(registration: JobRegistration): registration is ScheduledWorker {
-	return registration._tag === "ScheduledWorker";
-}
-
-function isQueueDefinition(registration: JobRegistration): registration is QueueDefinition {
-	return registration._tag === "QueueDefinition";
-}
+import { registerWorker } from "#server/adapters/registerWorker.ts";
+import { workerDiagnostics } from "#server/adapters/workerDiagnostics.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import type { JobPayloadSchema, JobRegistration, QueueDefinition, QueueWorker, ScheduleDefinition, ScheduledWorker } from "#server/definition.ts";
+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 (isQueueDefinition(registration)) {
+	if (registration._tag === "QueueDefinition") {
 		return registration;
 	}
-	if (isQueueWorker(registration)) {
+	if (registration._tag === "QueueWorker") {
 		return registration.queue;
 	}
-	if (isScheduledWorker(registration)) {
-		return registration.schedule;
-	}
-	throw new TypeError(`Unknown pg-boss registration: ${registration._tag}`);
+	return registration.schedule;
 }
 
 export function registrationName(registration: JobRegistration): string {
@@ -39,7 +25,7 @@ export function registrationName(registration: JobRegistration): string {
 
 const prepareQueues = Effect.fnUntraced(function* (client: PgBossClient, registrations: readonly JobRegistration[], replaceWorkers: boolean) {
 	for (const registration of registrations) {
-		if (replaceWorkers && !isQueueDefinition(registration)) {
+		if (replaceWorkers && registration._tag !== "QueueDefinition") {
 			yield* Effect.tryPromise({ catch: (error) => toPgBossError("register", error), try: () => client.offWork(registrationName(registration)) });
 		}
 	}
@@ -51,16 +37,10 @@ const prepareQueues = Effect.fnUntraced(function* (client: PgBossClient, registr
 	}
 });
 
-// The layer requires RegistrationRequirements of its jobs, so its context provides every registered worker.
-function workerContext<R>(context: Context.Context<R>): Context.Context<unknown>;
-function workerContext(context: unknown): unknown {
-	return context;
-}
-
-const registerQueue = Effect.fnUntraced(function* (
+const registerQueue = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	registration: QueueWorker | QueueDefinition,
-	context: Context.Context<unknown>,
+	registration: QueueWorker<JobPayloadSchema & { readonly DecodingServices: R }, R> | QueueDefinition,
+	context: Context.Context<R>,
 	scope: Scope.Scope,
 	schema: string,
 	stop: StopOptions | undefined,
@@ -82,10 +62,10 @@ const registerQueue = Effect.fnUntraced(function* (
 	).pipe(Effect.provide(context));
 });
 
-const registerSchedule = Effect.fnUntraced(function* (
+const registerSchedule = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	worker: ScheduledWorker,
-	context: Context.Context<unknown>,
+	worker: ScheduledWorker<R>,
+	context: Context.Context<R>,
 	scope: Scope.Scope,
 	schema: string,
 	stop: StopOptions | undefined,
@@ -117,7 +97,7 @@ export function registrationNames(registrations: readonly JobRegistration[]): re
 
 export const registerJobs = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	registrations: readonly JobRegistration[],
+	registrations: readonly JobRegistration<R>[],
 	context: Context.Context<R>,
 	replaceWorkers: boolean,
 	schema = "pgboss",
@@ -127,15 +107,17 @@ 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;
 	}
-	const provided = workerContext(context);
 	for (const registration of registrations) {
-		if (isQueueWorker(registration) || isQueueDefinition(registration)) {
-			yield* registerQueue(client, registration, provided, scope, schema, stop);
-		} else if (isScheduledWorker(registration)) {
-			yield* registerSchedule(client, registration, provided, scope, schema, stop);
+		if (registration._tag === "QueueWorker" || registration._tag === "QueueDefinition") {
+			yield* registerQueue(client, registration, context, scope, schema, stop);
+		} else {
+			yield* registerSchedule(client, registration, context, scope, schema, stop);
 		}
 	}
 });

package/src/server/internal/registerReleasedJobs.ts

@@ -1,15 +1,15 @@
 import { type Context, Effect, Option, Scope } from "effect";
-import type { StopOptions } from "pg-boss";
 import { WorkerRelease } from "@shivaedev/sql/WorkerRelease.ts";
-import { retireJobs } from "#adapters/retireJobs.ts";
-import type { PgBossClient } from "#client.ts";
-import type { JobRegistration } from "#definition.ts";
-import { toPgBossError } from "#error.ts";
+import { retireJobs } from "#server/adapters/retireJobs.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import type { JobRegistration } from "#server/definition.ts";
+import { toPgBossError } from "#server/error.ts";
 import { registerJobs, registrationName } from "./register.ts";
 
 export const registerReleasedJobs = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
-	jobs: readonly JobRegistration[],
+	jobs: readonly JobRegistration<R>[],
 	context: Context.Context<R>,
 	replaceWorkers: boolean,
 	schema: string | undefined,

package/src/server/internal/retryWake.ts

@@ -1,8 +1,8 @@
 import { Clock, Effect } from "effect";
 import { redactDiagnosticCause } from "@shivaedev/errors/redactCause.ts";
-import { batchClockOffset } from "#adapters/batchClockOffset.ts";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
+import { batchClockOffset } from "#server/adapters/batchClockOffset.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
 
 export function retryWake(client: PgBossClient, schema: string, name: string, id: string, registration: Promise<string>): Effect.Effect<void> {
 	return Effect.gen(function* () {

package/src/server/internal/runQueueWorker.ts

@@ -1,13 +1,19 @@
 import { Effect, Redacted, Schema } from "effect";
-import type { Job } from "pg-boss";
-import { deferralCount } from "#adapters/deferralCount.ts";
-import { workerDiagnostics } from "#adapters/workerDiagnostics.ts";
-import type { PgBossClient } from "#client.ts";
-import { jobContext, type QueueWorker } from "#definition.ts";
-import { PgBossPayloadError } from "#error.ts";
-import { payloadOf } from "#internal/tracing.ts";
+import { deferralCount } from "#server/adapters/deferralCount.ts";
+import { workerDiagnostics } from "#server/adapters/workerDiagnostics.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { type JobPayloadSchema, jobContext, type QueueWorker } from "#server/definition.ts";
+import { PgBossPayloadError } from "#server/error.ts";
+import { payloadOf } from "#server/internal/tracing.ts";
+import type { WorkerJob } from "#server/job.ts";
 
-export function runQueueWorker(worker: QueueWorker, job: Job<unknown>, deadline: number, client: PgBossClient, schema: string) {
+export function runQueueWorker<R>(
+	worker: QueueWorker<JobPayloadSchema & { readonly DecodingServices: R }, R>,
+	job: WorkerJob<unknown>,
+	deadline: number,
+	client: PgBossClient,
+	schema: string,
+) {
 	return Schema.decodeUnknownEffect(Schema.toCodecJson(worker.queue.schema))(payloadOf(job.data)).pipe(
 		Effect.mapError(
 			(error) =>

package/src/server/internal/storedRows.ts

@@ -1,7 +1,7 @@
 import { Effect, Redacted, Schema } from "effect";
-import type { JobPayloadSchema } from "#definition.ts";
-import { PgBossPayloadError } from "#error.ts";
-import { payloadOf } from "#internal/tracing.ts";
+import type { JobPayloadSchema } from "#server/definition.ts";
+import { PgBossPayloadError } from "#server/error.ts";
+import { payloadOf } from "#server/internal/tracing.ts";
 
 export function quotedSchema(schema: string): string {
 	return `"${schema.replaceAll('"', '""')}"`;

package/src/server/internal/testingDeferrals.ts

@@ -1,10 +1,10 @@
 import { DateTime } from "effect";
-import type { PgBoss } from "pg-boss";
-import type { QueueDefinition } from "#definition.ts";
-import { deferralOf } from "#internal/deferral.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import { deferralOf } from "#server/internal/deferral.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
 
-export function testingDeferrals(client: () => PgBoss) {
+export function testingDeferrals(client: () => EngineClient) {
 	return {
 		deferred: (queue: Pick<QueueDefinition, "name">) =>
 			testingOperation(

package/src/server/internal/testingIdle.ts

@@ -1,8 +1,8 @@
-import { Effect, Schema } from "effect";
-import type { PgBoss } from "pg-boss";
-import type { PgBossTestingError } from "#error.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
+import { Clock, Effect, Schema } from "effect";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { PgBossTestingError } from "#server/error.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+import { testingOperation } from "#server/internal/testingReadout.ts";
 
 export interface TestingBatch {
 	readonly name: string;
@@ -17,7 +17,7 @@ export interface TestingWork {
 const Busy = Schema.Struct({ busy: Schema.Boolean });
 
 export function testingIdle(
-	client: () => PgBoss,
+	client: () => EngineClient,
 	schema: () => string,
 	work: TestingWork,
 	signal: { readonly revision: Effect.Effect<number>; readonly waitForChange: (after: number) => Effect.Effect<number> },
@@ -46,7 +46,12 @@ export function testingIdle(
 			if (work.queues.size === 0 || !(unsettled || (yield* busy))) {
 				return;
 			}
-			yield* signal.waitForChange(revision);
+			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"));
+			}
 		}
-	});
+	}).pipe(Effect.provideService(Clock.Clock, Clock.Clock.defaultValue()));
 }

package/src/server/internal/testingReadout.ts

@@ -1,8 +1,11 @@
 import { Effect, Redacted } from "effect";
-import type { FindJobsOptions, PgBoss } from "pg-boss";
-import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
-import { PgBossTestingError } from "#error.ts";
-import { decodeStoredData } from "#internal/storedRows.ts";
+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 { decodeStoredData } from "#server/internal/storedRows.ts";
+import type { Job } from "#server/job.ts";
 
 export function testingOperation<A>(operation: string, run: () => Promise<A>, queue?: string) {
 	return Effect.tryPromise({
@@ -11,8 +14,11 @@ export function testingOperation<A>(operation: string, run: () => Promise<A>, qu
 	});
 }
 
-export function testingReadout(client: () => PgBoss) {
-	return <TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, options?: FindJobsOptions) =>
+export function testingReadout(client: () => EngineClient) {
+	return <TName extends string, TPayload extends JobPayloadSchema>(
+		queue: QueueDefinition<TName, TPayload>,
+		options?: JobReadOptions,
+	): Effect.Effect<Job<TPayload["Type"]>[], PgBossTestingError | PgBossPayloadError, TPayload["DecodingServices"]> =>
 		testingOperation("jobs", () => client().findJobs<unknown>(queue.name, options), queue.name).pipe(
 			Effect.flatMap((jobs) => Effect.forEach(jobs, (job) => decodeStoredData(queue, job.data).pipe(Effect.map((data) => ({ ...job, data }))))),
 		);