@shivaedev/jobs 0.30.0 → 0.31.0

package/src/server/adapters/queueAdministration.ts

@@ -0,0 +1,47 @@
+import { Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { PgBossNotFoundError, toPgBossError } from "#server/error.ts";
+import type { PgBossService } from "#server/service.ts";
+
+export function queueAdministration(client: PgBossClient): Pick<PgBossService, "deleteQueue" | "refreshQueueStats" | "unschedule"> {
+	return {
+		deleteQueue: (queue) =>
+			Effect.tryPromise({
+				catch: (error) => (error instanceof PgBossNotFoundError ? error : toPgBossError("deleteQueue", error, queue.name)),
+				try: async () => {
+					if (client.deleteQueue === undefined) {
+						throw new TypeError("This pg-boss client does not support deleteQueue");
+					}
+					if ((await client.getQueue(queue.name)) === null) {
+						throw new PgBossNotFoundError({ operation: "deleteQueue", queue: queue.name });
+					}
+					await client.offWork(queue.name);
+					await client.deleteQueue(queue.name);
+				},
+			}),
+		refreshQueueStats: (queue) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("refreshQueueStats", error, queue?.name),
+				try: async () => {
+					if (client.supervise === undefined) {
+						throw new TypeError("This pg-boss client does not support supervise");
+					}
+					await client.supervise(queue?.name);
+				},
+			}),
+		unschedule: (schedule) =>
+			Effect.tryPromise({
+				catch: (error) => (error instanceof PgBossNotFoundError ? error : toPgBossError("unschedule", error, schedule.name)),
+				try: async () => {
+					if (client.getSchedule === undefined || client.unschedule === undefined) {
+						throw new TypeError("This pg-boss client does not support getSchedule and unschedule");
+					}
+					const key = schedule.scheduleOptions.key ?? "";
+					if ((await client.getSchedule(schedule.name, key)) === null) {
+						throw new PgBossNotFoundError({ key, operation: "unschedule", queue: schedule.name });
+					}
+					await client.unschedule(schedule.name, key);
+				},
+			}),
+	};
+}

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,39 @@
-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 { deferralObservers } from "#server/internal/deferral.ts";
+import type { TestingBatch, TestingWork } from "#server/internal/testingIdle.ts";
+import { testingRegistration } from "#server/internal/testingRegistrations.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export interface TestingControls {
 	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;
+export function testingClient(client: EngineClient, schema: string, controls: TestingControls): PgBossClient {
+	const engine = testingEngine(client, schema);
+	const settlements = Effect.runSync(
+		engine.observeSettlements((name) => {
+			for (const batch of controls.work.batches) {
+				if (batch.name === name) {
+					batch.settled = true;
+				}
 			}
-		}
-		controls.changed();
-	});
+			controls.changed();
+		}),
+	);
 	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;
@@ -83,7 +88,7 @@ export function testingClient(client: PgBoss, schema: string, controls: TestingC
 			try {
 				await client.stop(options);
 			} finally {
-				settlements.close();
+				await Effect.runPromise(settlements.close);
 			}
 		},
 		update,
@@ -93,18 +98,18 @@ 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>[]) => {
+		work: async (name, options, handler) => {
+			await Effect.runPromise(settlements.watch(name));
+			return client.work(name, options, async (jobs: readonly WorkerJob<unknown>[]) => {
 				const batch: TestingBatch = { name, settled: false };
 				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);
 						}

package/src/server/adapters/testingController.ts

@@ -0,0 +1,109 @@
+import { Duration, Effect, Redacted } from "effect";
+import { defaultClientFactory } from "#server/adapters/defaultClientFactory.ts";
+import { testingClient } from "#server/adapters/testingClient.ts";
+import { testingDueNow } from "#server/adapters/testingDueNow.ts";
+import type { PgBossClientFactory } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import { PgBossTestingError } from "#server/error.ts";
+import { type TestingFetches, testingFetches } from "#server/internal/adapters/testingFetches.ts";
+import { testingDeferrals } from "#server/internal/testingDeferrals.ts";
+import { type TestingWork, testingIdle } from "#server/internal/testingIdle.ts";
+import { testingOperation, testingReadout } from "#server/internal/testingReadout.ts";
+import { testingSchedules } from "#server/internal/testingSchedules.ts";
+import { testingSignal } from "#server/internal/testingSignal.ts";
+import { testingSnapshot } from "#server/internal/testingSnapshot.ts";
+import { testingWaits } from "#server/internal/testingWaits.ts";
+import type { PgBossTestingOptions } from "#server/testing.ts";
+export function testingController(options: PgBossTestingOptions = {}) {
+	let current: EngineClient | undefined;
+	let fetches: TestingFetches | undefined;
+	let schema = "pgboss";
+	const signal = testingSignal();
+	const work: TestingWork = { batches: new Set(), queues: new Set() };
+	const controls = {
+		changed: signal.changed,
+		expirations: new Map<string, number>(),
+		expirySeconds: new Map<string, number>(),
+		failures: new Set<string>(),
+		retryPolicy: options.retryPolicy ?? {},
+		work,
+	};
+	function client(): EngineClient {
+		if (current === undefined) {
+			throw new Error("Provide the testing clientFactory to a jobs Layer first");
+		}
+		return current;
+	}
+	const clientFactory: PgBossClientFactory = (clientOptions) => {
+		if (current !== undefined) {
+			throw new Error("A testing controller owns one jobs client; create a controller per runtime");
+		}
+		schema = clientOptions.schema ?? "pgboss";
+		current = defaultClientFactory({ ...clientOptions, "__test__enableSpies": true });
+		fetches = testingFetches(current.getDb(), signal.changed);
+		return testingClient(current, clientOptions.schema ?? "pgboss", controls);
+	};
+	return {
+		...testingDeferrals(client),
+		...testingDueNow(client, () => schema, signal.changed),
+		...testingSchedules(client, signal.changed),
+		...testingWaits(client, () => fetches, signal),
+		checkBatchWindow: (queue: Pick<QueueDefinition, "name" | "workerOptions">, millisecondsPerJob: number) =>
+			testingOperation(
+				"checkBatchWindow",
+				async () => {
+					const stored = await client().getQueue(queue.name);
+					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 client().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: testingReadout(client),
+		revision: signal.revision,
+		schemaVersion: testingOperation("schemaVersion", () => client().schemaVersion()),
+		snapshot: testingSnapshot(client, () => schema),
+		waitForChange: signal.waitForChange,
+		waitForIdle: testingIdle(client, () => schema, 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/testingReadout.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,28 @@
+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";
+import { observeTestingSettlements } from "./observeTestingSettlements.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),
+			}),
+		observeSettlements: (settled) =>
+			Effect.sync(() => {
+				const observer = observeTestingSettlements(client, settled);
+				return {
+					close: Effect.sync(() => observer.close()),
+					watch: (name: string) =>
+						Effect.try({
+							catch: (original) => new PgBossTestingError({ operation: "observeSettlements", original: Redacted.make(original), queue: name }),
+							try: () => observer.watch(name),
+						}),
+				};
+			}),
+	};
+}

package/src/server/adapters/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/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,92 @@
-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 { 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 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 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;

package/src/server/clientOptions.ts

@@ -0,0 +1,81 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+
+export interface ClientOptions {
+	"__test__enableSpies"?: boolean;
+	allowSchemaCaseVariant?: boolean;
+	"application_name"?: string;
+
+	backend?: "postgres" | "cockroachdb" | "yugabytedb" | "citus" | "pglite";
+	bamIntervalSeconds?: number;
+
+	clock?: Clock;
+	clockMonitorIntervalSeconds?: number;
+	connectionString?: string;
+	connectionTimeoutMillis?: number;
+	createSchema?: boolean;
+	cronMonitorIntervalSeconds?: number;
+	cronWorkerIntervalSeconds?: number;
+	database?: string;
+	db?: ClientDatabase;
+	flowIntervalSeconds?: number;
+	host?: string;
+	instanceHeartbeatSeconds?: number;
+	instanceName?: string;
+	maintenanceIntervalSeconds?: number;
+	max?: number;
+	migrate?: boolean;
+	monitorIntervalSeconds?: number;
+	monitorVacuum?: boolean;
+	notifyHeartbeatIntervalMs?: number;
+	notifyHeartbeatTimeoutMs?: number;
+	notifyKeepAliveInitialDelayMs?: number;
+	openTelemetry?: { enabled?: boolean; propagateContext?: boolean };
+	options?: string;
+	password?: string | (() => string | Promise<string>);
+	persistQueueStats?: boolean;
+	persistWarnings?: boolean;
+	port?: number;
+	queueCacheIntervalSeconds?: number;
+	queueStatRetentionDays?: number;
+
+	registerInstance?: boolean;
+	reindex?: boolean | ReindexOptions;
+	reindexIntervalSeconds?: number;
+
+	schedule?: boolean;
+	schema?: string;
+	ssl?: boolean | import("node:tls").ConnectionOptions;
+
+	supervise?: boolean;
+	superviseIntervalSeconds?: number;
+	useListenNotify?: boolean;
+	user?: string;
+	warningQueueSize?: number;
+	warningRetentionDays?: number;
+	warningSlowQuerySeconds?: number;
+}
+
+export interface ReindexOptions extends IndexBloatOptions {
+	force?: boolean;
+	maxIndexBytes?: number;
+}
+
+export interface IndexBloatOptions {
+	maxEntriesPerPage?: number;
+	minPages?: number;
+	minSizeRatio?: number;
+}
+
+export interface Clock {
+	clearInterval: (handle: unknown) => void;
+	clearTimeout: (handle: unknown) => void;
+	now: () => number;
+	setInterval: (fn: () => void, ms: number) => unknown;
+	setTimeout: (fn: () => void, ms: number) => unknown;
+}
+
+export interface StopOptions {
+	close?: boolean;
+	graceful?: boolean;
+	timeout?: number;
+}

package/src/server/defineSchedule.ts

@@ -1,9 +1,10 @@
-import type { DefineScheduleOptions, ScheduleDefinition } from "#definition.ts";
-import { maxDeferrals, nativeQueueOptions } from "#internal/definitionOptions.ts";
+import type { DefineScheduleOptions, ScheduleDefinition } from "#server/definition.ts";
+import { maxDeferrals, nativeQueueOptions } from "#server/internal/definitionOptions.ts";
 
 export function defineSchedule<const TName extends string>(options: DefineScheduleOptions<TName>): ScheduleDefinition<TName> {
 	const definition: ScheduleDefinition<TName> = {
 		_tag: "ScheduleDefinition",
+		...(options.label === undefined ? {} : { label: options.label }),
 		cron: options.cron,
 		maxDeferrals: maxDeferrals(options.queue),
 		name: options.name,