@shivaedev/jobs 0.30.0 → 0.32.0

package/src/server/adapters/registerWorker.ts

@@ -1,17 +1,21 @@
 import { Effect, Fiber, Scope } from "effect";
-import type { Job, StopOptions, WorkOptions } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
-import { batchHandler } from "#internal/batchHandler.ts";
-import { deferrableAttempt } from "#internal/deferrableAttempt.ts";
-import { retryWake } from "#internal/retryWake.ts";
-import { traceJob } from "#internal/tracing.ts";
+import { batchHandler } from "#server/adapters/batchHandler.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deferrableAttempt } from "#server/internal/deferrableAttempt.ts";
+import { JobEngine } from "#server/internal/engine.ts";
+import { retryWake } from "#server/internal/retryWake.ts";
+import { traceJob } from "#server/internal/tracing.ts";
+import type { WorkerJob } from "#server/job.ts";
+import type { WorkerOptions } from "#server/workerOptions.ts";
+import { jobEngine } from "./jobEngine.ts";
 
 export const registerWorker = Effect.fnUntraced(function* <R>(
 	client: PgBossClient,
 	name: string,
-	options: WorkOptions,
-	run: (job: Job<unknown>, deadline: number) => Effect.Effect<unknown, unknown, R>,
+	options: WorkerOptions,
+	run: (job: WorkerJob<unknown>, deadline: number) => Effect.Effect<unknown, unknown, R>,
 	scope: Scope.Scope,
 	schema: string,
 	maxDeferrals: number,
@@ -20,10 +24,11 @@ export const registerWorker = Effect.fnUntraced(function* <R>(
 	const execute = Effect.runPromiseWith(yield* Effect.context<R>());
 	const workerScope = yield* Scope.fork(scope);
 	const fibers = yield* Scope.fork(workerScope);
-	function runJob(job: Job<unknown>, deadline: number) {
-		return traceJob(deferrableAttempt(run(job, deadline), client, schema, job, maxDeferrals), job, name);
+	const engine = jobEngine(client, schema);
+	function runJob(job: WorkerJob<unknown>, deadline: number) {
+		return traceJob(deferrableAttempt(run(job, deadline), job, maxDeferrals).pipe(Effect.provideService(JobEngine, engine)), job, name);
 	}
-	function afterRetry(attempt: Job<unknown>) {
+	function afterRetry(attempt: WorkerJob<unknown>) {
 		return retryWake(client, schema, name, attempt.id, registration).pipe(Effect.forkIn(fibers), Effect.asVoid);
 	}
 	const handle = yield* Effect.try({

package/src/server/adapters/retireJobs.ts

@@ -1,9 +1,9 @@
 import { Effect } from "effect";
-import type { PgBossClient } from "#client.ts";
-import type { JobRegistration } from "#definition.ts";
-import { toPgBossError } from "#error.ts";
-import { deadLetterQueueName } from "#health.ts";
-import { registrationNames } from "#internal/register.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { JobRegistration } from "#server/definition.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deadLetterQueueName } from "#server/health.ts";
+import { registrationNames } from "#server/internal/register.ts";
 
 export const retireJobs = Effect.fnUntraced(function* (client: PgBossClient, jobs: readonly JobRegistration[], retired: readonly string[]) {
 	yield* Effect.try({

package/src/server/adapters/schemaIndexBuilds.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import type { PgBoss } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
 
 const IndexBuilds = Schema.Array(Schema.Struct({ command: Schema.String, id: Schema.String }));
 const IndexValidity = Schema.Array(Schema.Struct({ invalid: Schema.Boolean }));
@@ -28,7 +28,7 @@ export function pendingIndexInserts(schema: string, version: number, commands: r
 		.join("\n");
 }
 
-export async function resumeSchemaIndexes(client: PgBoss, schema: string): Promise<void> {
+export async function resumeSchemaIndexes(client: EngineClient, schema: string): Promise<void> {
 	const db = client.getDb();
 	const { rows } = await db.executeSql(
 		`SELECT id, command FROM ${schema}.bam WHERE starts_with(name, $1) AND status <> 'completed' ORDER BY created_on, name`,

package/src/server/{internal → adapters}/settleDeferral.ts

@@ -1,12 +1,12 @@
 import { Schema } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { STATELY_DEFERRAL_POLICY } from "#internal/deferral.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { STATELY_DEFERRAL_POLICY } from "#server/internal/deferral.ts";
+import type { JobAttempt } from "#server/internal/engine.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 const Settlement = Schema.Struct({ claimed: Schema.Boolean, deferred: Schema.Boolean });
 
-export async function settleDeferral(client: PgBossClient, schema: string, job: Job<unknown>, at: string, reason: string, maxDeferrals: number) {
+export async function settleDeferral(client: PgBossClient, schema: string, job: JobAttempt, at: string, reason: string, maxDeferrals: number) {
 	if (client.getDb === undefined) {
 		throw new TypeError("This pg-boss client does not support getDb for RetryAt");
 	}

package/src/server/{internal → adapters}/testingClient.ts

@@ -1,34 +1,28 @@
-import type { Job, PgBoss, SendOptions, UpdateOptions, UpdateRequest, UpdateResponse } from "pg-boss";
-import { testingExpirations } from "#adapters/testingExpirations.ts";
-import type { PgBossClient } from "#client.ts";
-import { deferralObservers } from "#internal/deferral.ts";
-import { expireAttempt } from "#internal/expireAttempt.ts";
-import { observeTestingSettlements } from "#internal/observeTestingSettlements.ts";
-import type { TestingBatch, TestingWork } from "#internal/testingIdle.ts";
-import { testingRegistration } from "#internal/testingRegistrations.ts";
+import { Effect } from "effect";
+import { testingEngine } from "#server/adapters/testingEngine.ts";
+import { testingExpirations } from "#server/adapters/testingExpirations.ts";
+import type { ClientUpdateOptions, ClientUpdateRequest, ClientUpdateResult, PgBossClient } from "#server/client.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
+import type { TestingBatch, TestingWork } from "#server/internal/testingIdle.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export interface TestingControls {
 	readonly changed: () => void;
 	readonly expirations: Map<string, number>;
 	readonly expirySeconds: Map<string, number>;
 	readonly failures: Set<string>;
-	readonly retryPolicy: Pick<SendOptions, "retryBackoff" | "retryDelay">;
+	readonly retryPolicy: Pick<EnqueueOptions, "retryBackoff" | "retryDelay">;
 	readonly work: TestingWork;
 }
 
-export function testingClient(client: PgBoss, schema: string, controls: TestingControls): PgBossClient {
-	const settlements = observeTestingSettlements(client, (name) => {
-		for (const batch of controls.work.batches) {
-			if (batch.name === name) {
-				batch.settled = true;
-			}
-		}
-		controls.changed();
-	});
+export function testingClient(client: EngineClient, schema: string, controls: TestingControls): EngineClient {
+	const engine = testingEngine(client, schema);
+
 	const expirations = testingExpirations(client);
-	function update(request: UpdateRequest): Promise<UpdateResponse>;
-	function update(name: string, data: object | null | undefined, options?: UpdateOptions): Promise<UpdateResponse>;
-	async function update(request: string | UpdateRequest, data?: object | null, options?: UpdateOptions): Promise<UpdateResponse> {
+	function update(request: ClientUpdateRequest): Promise<ClientUpdateResult>;
+	function update(name: string, data: object | null | undefined, options?: ClientUpdateOptions): Promise<ClientUpdateResult>;
+	async function update(request: string | ClientUpdateRequest, data?: object | null, options?: ClientUpdateOptions): Promise<ClientUpdateResult> {
 		const result = typeof request === "string" ? await client.update(request, data, options) : await client.update(request);
 		controls.changed();
 		return result;
@@ -40,6 +34,9 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 			return result;
 		},
 		createQueue: (name, options) => {
+			if (options?.deadLetter !== undefined) {
+				controls.work.queues.add(name);
+			}
 			const { retryDelayMax, ...rest } = options ?? {};
 			return client.createQueue(name, {
 				...rest,
@@ -79,13 +76,6 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 			controls.changed();
 			return id;
 		},
-		stop: async (options) => {
-			try {
-				await client.stop(options);
-			} finally {
-				settlements.close();
-			}
-		},
 		update,
 		updateQueue: (name, options) =>
 			client.updateQueue(name, {
@@ -93,18 +83,17 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 				...controls.retryPolicy,
 				...(controls.retryPolicy.retryBackoff === false ? { retryDelayMax: null } : {}),
 			}),
-		work: (name, options, handler) => {
-			settlements.watch(name);
-			return client.work(name, options, async (jobs: Job<unknown>[]) => {
-				const batch: TestingBatch = { name, settled: false };
+		work: async (name, options, handler) =>
+			client.work(name, options, async (jobs: readonly WorkerJob<unknown>[]) => {
+				const batch: TestingBatch = { jobs: new Map(jobs.map((job) => [job.id, job.retryCount])), name, settled: false };
 				controls.work.batches.add(batch);
 				controls.changed();
 				try {
-					const ready: Job<unknown>[] = [];
+					const ready: WorkerJob<unknown>[] = [];
 					for (const job of jobs) {
 						const attempts = await expirations.attemptsFor(job);
 						if (attempts !== undefined && job.retryCount + 1 >= attempts) {
-							await expireAttempt(client, schema, job);
+							await Effect.runPromise(engine.expireAttempt(job));
 						} else {
 							ready.push(job);
 						}
@@ -116,14 +105,10 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 					controls.work.batches.delete(batch);
 					controls.changed();
 				}
-			});
-		},
+			}),
 	};
 	const wrapped = new Proxy(client, {
 		get(target, property) {
-			if (property === testingRegistration) {
-				return (name: string) => controls.work.queues.add(name);
-			}
 			if (Object.hasOwn(overrides, property)) {
 				const override: unknown = Reflect.get(overrides, property);
 				return override;
@@ -132,6 +117,5 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 			return typeof value === "function" ? value.bind(target) : value;
 		},
 	});
-	deferralObservers.set(wrapped, controls.changed);
 	return wrapped;
 }

package/src/server/adapters/testingController.ts

@@ -0,0 +1,125 @@
+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 { 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 { type TestingWork, testingIdle } from "#server/internal/testingIdle.ts";
+import { testingInspection, testingOperation } from "#server/internal/testingOperation.ts";
+import { testingSchedules } from "#server/internal/testingSchedules.ts";
+import { testingWaits } from "#server/internal/testingWaits.ts";
+import type { PgBossTestingOptions } from "#server/testing.ts";
+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 = 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: settings.retryPolicy ?? {},
+		work,
+	};
+	function client(): EngineClient {
+		if (current === undefined) {
+			throw new Error("Provide the testing clientFactory to a jobs Layer first");
+		}
+		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);
+		fetches = testingFetches(current.getDb(), signal.changed);
+		current = testingClient(current, schema, controls);
+		return testingInspectionClient(current, schema, work, signal.changed, (reads) => {
+			observed = reads;
+		});
+	};
+	return {
+		deferred: (queue: Pick<QueueDefinition, "name">) => Effect.suspend(() => testingInspection("deferred", inspection().deferred(queue), queue.name)),
+		...testingDueNow(client, () => schema, signal.changed),
+		...testingSchedules(client, inspection),
+		...testingWaits(inspection, () => fetches, signal),
+		checkBatchWindow: (queue: Pick<QueueDefinition, "name" | "workerOptions">, millisecondsPerJob: number) =>
+			testingOperation(
+				"checkBatchWindow",
+				async () => {
+					const stored = await Effect.runPromise(inspection().queue(queue));
+					if (stored === null) {
+						throw new Error("Queue is not registered");
+					}
+					if (stored.expireInSeconds === undefined) {
+						throw new Error("Queue has no expiry window");
+					}
+					if (!Number.isFinite(millisecondsPerJob) || millisecondsPerJob < 0) {
+						throw new RangeError("Job duration must be nonnegative and finite");
+					}
+					const required = (queue.workerOptions.batchSize ?? 10) * millisecondsPerJob;
+					if (required >= stored.expireInSeconds * 1000) {
+						throw new Error("Sequential batch work must fit within the queue expiry window");
+					}
+				},
+				queue.name,
+			),
+		checkSchemaVersion: (expected: number) =>
+			testingOperation("checkSchemaVersion", async () => {
+				if ((await Effect.runPromise(inspection().schemaVersion())) !== expected) {
+					throw new Error(`Expected pg-boss schema version ${expected}`);
+				}
+			}),
+		clientFactory,
+		expireAfter: (queue: Pick<QueueDefinition, "name">, attempts: number) =>
+			Effect.try({
+				catch: (original) => new PgBossTestingError({ operation: "expireAfter", original: Redacted.make(original), queue: queue.name }),
+				try: () => {
+					if (!Number.isSafeInteger(attempts) || attempts < 1) {
+						throw new RangeError("Attempts must be a positive integer");
+					}
+					controls.expirations.set(queue.name, attempts);
+				},
+			}),
+		expireIn: (queue: Pick<QueueDefinition, "name">, duration: Duration.Input) =>
+			Effect.try({
+				catch: (original) => new PgBossTestingError({ operation: "expireIn", original: Redacted.make(original), queue: queue.name }),
+				try: () => {
+					const milliseconds = Duration.toMillis(Duration.fromInputUnsafe(duration));
+					if (!Number.isFinite(milliseconds) || milliseconds < 1000) {
+						throw new RangeError("Expiry must be finite and at least one second");
+					}
+					controls.expirySeconds.set(queue.name, Math.ceil(milliseconds / 1000));
+				},
+			}),
+		failNextSend: (queue: Pick<QueueDefinition, "name">) => Effect.sync(() => controls.failures.add(queue.name)).pipe(Effect.asVoid),
+		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: 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(inspection, work, signal),
+	};
+}

package/src/server/adapters/testingDueNow.ts

@@ -1,9 +1,9 @@
-import type { PgBoss } from "pg-boss";
-import type { QueueDefinition } from "#definition.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
+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/testingOperation.ts";
 
-export function testingDueNow(client: () => PgBoss, schema: () => string, changed: () => void) {
+export function testingDueNow(client: () => EngineClient, schema: () => string, changed: () => void) {
 	function makeDue(queue: Pick<QueueDefinition, "name">, deferredOnly: boolean) {
 		return testingOperation(
 			deferredOnly ? "runDeferredNow" : "runDueNow",

package/src/server/adapters/testingEngine.ts

@@ -0,0 +1,15 @@
+import { type Context, Effect, Redacted } from "effect";
+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";
+
+export function testingEngine(client: EngineClient, schema: string): Context.Service.Shape<typeof TestingEngine> {
+	return {
+		expireAttempt: (job, cause) =>
+			Effect.tryPromise({
+				catch: (original) => new PgBossTestingError({ operation: "expireAttempt", original: Redacted.make(original), queue: job.name }),
+				try: () => expireAttempt(client, schema, job, cause),
+			}),
+	};
+}

package/src/server/adapters/testingExpirations.ts

@@ -1,10 +1,12 @@
-import type { Job, PgBoss, SendOptions } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
+import type { WorkerJob } from "#server/job.ts";
 
-export function testingExpirations(client: PgBoss) {
+export function testingExpirations(client: EngineClient) {
 	const snapshots = new Map<string, Promise<number | undefined>>();
 	return {
-		attemptsFor: (job: Job<unknown>) => snapshots.get(`${job.name}:${job.id}`),
-		send(name: string, data: object | null | undefined, options: SendOptions, attempts: number | undefined) {
+		attemptsFor: (job: WorkerJob<unknown>) => snapshots.get(`${job.name}:${job.id}`),
+		send(name: string, data: object | null | undefined, options: EnqueueOptions, attempts: number | undefined) {
 			if (attempts === undefined && options.id === undefined) {
 				return client.send(name, data, options);
 			}

package/src/server/adapters/testingInspectionClient.ts

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

package/src/server/adapters/transactionDb.ts

@@ -1,8 +1,8 @@
 import { Effect, Option } from "effect";
 import { SqlClient } from "effect/sql";
-import type { SendOptions } from "pg-boss";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
 
-export const transactionDb: Effect.Effect<SendOptions["db"]> = Effect.gen(function* () {
+export const transactionDb: Effect.Effect<EnqueueOptions["db"]> = Effect.gen(function* () {
 	const sql = yield* Effect.serviceOption(SqlClient.SqlClient);
 	if (Option.isNone(sql)) {
 		return undefined;

package/src/server/client.ts

@@ -1,39 +1,95 @@
-import type {
-	ConstructorOptions,
-	FindJobsOptions,
-	Job,
-	JobWithMetadata,
-	PgBoss,
-	Queue,
-	QueueResult,
-	ScheduleOptions,
-	SendOptions,
-	StopOptions,
-	WorkOptions,
-} from "pg-boss";
+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";
+import type { WorkerOptions } from "#server/workerOptions.ts";
+
+export interface JobReadOptions {
+	readonly after?: string;
+	readonly data?: object;
+	readonly db?: ClientDatabase;
+	readonly id?: string;
+	readonly key?: string;
+	readonly limit?: number;
+	readonly queued?: boolean;
+}
+
+export interface ClientQueueOptions extends Omit<QueueOptions, "maxDeferrals" | "policy"> {
+	readonly deadLetter?: string;
+	readonly policy?: string;
+}
+
+export interface ClientQueue extends ClientQueueOptions {
+	readonly activeCount: number;
+	readonly blockedCount: number;
+	readonly deferredCount: number;
+	readonly failedCount: number;
+	readonly name: string;
+	readonly queuedCount: number;
+	readonly readyCount: number;
+	readonly totalCount: number;
+}
+
+export type JobTarget = string | string[] | { id: string; retryCount: number } | { id: string; retryCount: number }[];
+export interface ClientConnectionOptions {
+	readonly db?: ClientDatabase;
+}
+export interface ClientUpdateOptions extends Omit<EnqueueOptions, "singletonSeconds" | "singletonNextSlot"> {
+	readonly match?: "newest" | "oldest" | "all";
+}
+export interface ClientUpdateRequest {
+	data?: object | null;
+	name: string;
+	options?: ClientUpdateOptions;
+}
+export interface ClientUpdateResult {
+	jobs: string[];
+	updated: number;
+}
 
 export interface PgBossClient {
-	readonly complete?: PgBoss["complete"];
-	readonly createQueue: (name: string, options?: Omit<Queue, "name">) => Promise<void>;
-	readonly deleteQueue?: PgBoss["deleteQueue"];
-	readonly fail?: PgBoss["fail"];
-	readonly findJobs?: (name: string, options?: FindJobsOptions) => Promise<readonly JobWithMetadata<unknown>[]>;
-	readonly getDb?: PgBoss["getDb"];
-	readonly getQueue: (name: string) => Promise<QueueResult | null>;
-	readonly getWipData?: PgBoss["getWipData"];
-	readonly notifyWorker?: PgBoss["notifyWorker"];
+	readonly complete?: (
+		name: string,
+		id: JobTarget,
+		data?: object | null,
+		options?: ClientConnectionOptions & { includeQueued?: boolean },
+	) => Promise<object>;
+	readonly createQueue: (name: string, options?: ClientQueueOptions) => Promise<void>;
+	readonly deleteQueue?: (name: string) => Promise<void>;
+	readonly fail?: (name: string, id: JobTarget, data?: object | null, options?: ClientConnectionOptions) => Promise<object>;
+	readonly findJobs?: (name: string, options?: JobReadOptions) => Promise<readonly Job<unknown>[]>;
+	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;
-	readonly offWork: PgBoss["offWork"];
+	readonly offWork: (name: string, options?: { id?: string; wait?: boolean }) => Promise<void>;
 	readonly on: (event: "error", listener: (error: Error) => void) => unknown;
-	readonly retry?: PgBoss["retry"];
+	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 send: (name: string, data?: object | null, options?: SendOptions) => Promise<string | null>;
+	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>;
-	readonly unschedule?: PgBoss["unschedule"];
-	readonly update?: PgBoss["update"];
-	readonly updateQueue?: PgBoss["updateQueue"];
-	readonly work: (name: string, options: WorkOptions, handler: (jobs: readonly Job<unknown>[]) => Promise<unknown>) => Promise<string>;
+	readonly supervise?: (name?: string) => Promise<void>;
+	readonly unschedule?: (name: string, key?: string, options?: ClientConnectionOptions) => Promise<void>;
+	readonly update?: {
+		(request: ClientUpdateRequest): Promise<ClientUpdateResult>;
+		(name: string, data: object | null | undefined, options?: ClientUpdateOptions): Promise<ClientUpdateResult>;
+	};
+	readonly updateQueue?: (
+		name: string,
+		options: Omit<QueueOptions, "policy" | "partition" | "maxDeferrals" | "heartbeatSeconds" | "retryDelayMax"> & {
+			deadLetter?: string | null;
+			heartbeatSeconds?: number | null;
+			retryDelayMax?: number | null;
+		},
+	) => Promise<void>;
+	readonly work: (name: string, options: WorkerOptions, handler: (jobs: readonly WorkerJob<unknown>[]) => Promise<unknown>) => Promise<string>;
 }
 
-export type PgBossClientFactory = (options: ConstructorOptions) => PgBossClient;
+export type PgBossClientFactory = (options: ClientOptions) => PgBossClient;