@shivaedev/jobs 0.30.0 → 0.32.0

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

@@ -1,11 +1,11 @@
 import { isDeepStrictEqual } from "node:util";
-import type { ConstructorOptions } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { PgBossClientOptionsError } from "#error.ts";
+import type { ClientOptions } from "#server/clientOptions.ts";
+import { PgBossClientOptionsError } from "#server/error.ts";
+import type { StartingClient } from "./lifecycle.ts";
 
 interface CachedClient {
-	readonly client: Promise<PgBossClient>;
-	readonly constructorOptions: ConstructorOptions;
+	readonly client: StartingClient;
+	readonly constructorOptions: ClientOptions;
 	references: number;
 }
 
@@ -23,13 +23,13 @@ function isCachedClient(value: unknown): value is CachedClient {
 	return (
 		typeof value === "object"
 		&& value !== null
-		&& Reflect.get(value, "client") instanceof Promise
+		&& typeof Reflect.get(value, "client") === "object"
 		&& typeof Reflect.get(value, "constructorOptions") === "object"
 		&& typeof Reflect.get(value, "references") === "number"
 	);
 }
 
-export async function acquireCachedClient(key: string | symbol, constructorOptions: ConstructorOptions, start: () => Promise<PgBossClient>) {
+export function acquireCachedClient(key: string | symbol, constructorOptions: ClientOptions, start: () => StartingClient) {
 	const existing = entryFor(key);
 	if (existing !== undefined) {
 		const options = [...new Set([...Object.keys(existing.constructorOptions), ...Object.keys(constructorOptions)])]
@@ -39,27 +39,15 @@ export async function acquireCachedClient(key: string | symbol, constructorOptio
 			throw new PgBossClientOptionsError({ key, options });
 		}
 		existing.references += 1;
-		try {
-			return { client: await existing.client, reused: true };
-		} catch (error) {
-			existing.references -= 1;
-			throw error;
-		}
+		return { ...existing.client, reused: true };
 	}
 	const settings = { ...constructorOptions };
 	const entry: CachedClient = { client: start(), constructorOptions: settings, references: 1 };
 	clients.set(key, entry);
-	try {
-		return { client: await entry.client, reused: false };
-	} catch (error) {
-		if (clients.get(key) === entry) {
-			clients.delete(key);
-		}
-		throw error;
-	}
+	return { ...entry.client, reused: false };
 }
 
-export function releaseCachedClient(key: string | symbol): Promise<PgBossClient> | undefined {
+export function releaseCachedClient(key: string | symbol): StartingClient | undefined {
 	const entry = entryFor(key);
 	if (entry === undefined) {
 		return;

package/src/server/adapters/clientErrorLogger.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect";
-import { logClientError } from "#internal/clientErrors.ts";
+import { logClientError } from "#server/internal/clientErrors.ts";
 
 export const clientErrorLogger = Effect.fnUntraced(function* () {
 	const run = Effect.runForkWith(yield* Effect.context<never>());

package/src/server/{defaultClientFactory.ts → adapters/defaultClientFactory.ts}

@@ -1,7 +1,9 @@
 import { Socket } from "node:net";
-import { type ConstructorOptions, PgBoss } from "pg-boss";
+import { PgBoss } from "pg-boss";
+import type { ClientOptions } from "#server/clientOptions.ts";
+import type { EngineClient } from "#server/engineClient.ts";
 
-export function defaultClientFactory(options: ConstructorOptions) {
+export function defaultClientFactory(options: ClientOptions): EngineClient {
 	const disconnected = new Set<Promise<void>>();
 	const config = {
 		...options,

package/src/server/adapters/deferralCount.ts

@@ -1,12 +1,12 @@
 import { Effect, Schema } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 const Count = Schema.Struct({ count: Schema.NumberFromString });
 
-export const deferralCount = Effect.fnUntraced(function* (client: PgBossClient, schema: string, job: Job<unknown>) {
+export const deferralCount = Effect.fnUntraced(function* (client: PgBossClient, schema: string, job: WorkerJob<unknown>) {
 	const quoted = quotedSchema(schema);
 	return yield* Effect.tryPromise({
 		catch: (error) => toPgBossError("settle", error, job.name),

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

@@ -1,7 +1,8 @@
-import type { Job, PgBoss } from "pg-boss";
-import { quotedSchema } from "#internal/storedRows.ts";
+import type { EngineClient } from "#server/engineClient.ts";
+import type { JobAttempt } from "#server/internal/engine.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
-export async function expireAttempt(client: PgBoss, schema: string, job: Job<unknown>, cause: "expiry" | "heartbeat" = "expiry"): Promise<void> {
+export async function expireAttempt(client: EngineClient, schema: string, job: JobAttempt, cause: "expiry" | "heartbeat" = "expiry"): Promise<void> {
 	if ((await client.schemaVersion()) !== 46) {
 		throw new Error("Testing expiry requires pg-boss schema version 46");
 	}

package/src/server/adapters/inspection.ts

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+import { jobEngine } from "#server/adapters/jobEngine.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { PgBossInspectionService } from "#server/inspection.ts";
+import { countsFor } from "#server/internal/countsFor.ts";
+import { JobEngine } from "#server/internal/engine.ts";
+import { healthFor } from "#server/internal/healthFor.ts";
+import { jobControl } from "#server/internal/jobControl.ts";
+import { jobListings } from "#server/internal/jobListings.ts";
+import { inspectionChanges } from "./inspectionChanges.ts";
+import { inspectionReads } from "./inspectionReads.ts";
+
+export function inspection(client: PgBossClient, schema = "pgboss"): Effect.Effect<PgBossInspectionService> {
+	const engine = jobEngine(client, schema);
+	return Effect.gen(function* () {
+		const listings = yield* jobListings;
+		const { getJob } = yield* jobControl;
+		return {
+			...inspectionReads(client, schema),
+			...listings,
+			changes: (queue?: { readonly name: string }) => inspectionChanges(client, schema, queue?.name),
+			counts: (queue: { readonly name: string }) => countsFor(client, schema, queue.name),
+			getJob,
+			health: (queues: readonly { readonly name: string }[]) =>
+				healthFor(
+					client,
+					queues.map((queue) => queue.name),
+				),
+		};
+	}).pipe(Effect.provideService(JobEngine, engine));
+}

package/src/server/adapters/inspectionChanges.ts

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+import { inspectionChannel } from "#server/adapters/inspectionPlan.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { queueSignal } from "./queueSignal.ts";
+
+export const inspectionChanges = Effect.fnUntraced(function* (client: PgBossClient, schema: string, queue?: string) {
+	const signal = queueSignal();
+	yield* Effect.acquireRelease(
+		Effect.tryPromise({
+			catch: (error) => toPgBossError("inspect", error, queue),
+			try: () => {
+				const db = client.getDb?.();
+				if (db?.listen === undefined) {
+					throw new TypeError("This pg-boss client does not support listen");
+				}
+				return db.listen(
+					inspectionChannel(schema),
+					(name) => {
+						if (queue === undefined || name === queue) {
+							signal.changed();
+						}
+					},
+					signal.changed,
+				);
+			},
+		}),
+		(listener) => Effect.promise(() => listener.close()),
+	);
+	return { revision: signal.revision, waitForChange: signal.waitForChange };
+});

package/src/server/adapters/inspectionDeferrals.ts

@@ -0,0 +1,20 @@
+import { DateTime, Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import { deferralOf } from "#server/internal/deferral.ts";
+import { inspectionJobs } from "./inspectionJobs.ts";
+
+export function inspectionDeferrals(client: PgBossClient) {
+	const { storedJobs } = inspectionJobs(client);
+	return {
+		deferred: (queue: Pick<QueueDefinition, "name">) =>
+			storedJobs(queue).pipe(
+				Effect.map((jobs) =>
+					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 }];
+					}),
+				),
+			),
+	};
+}

package/src/server/adapters/inspectionJobs.ts

@@ -0,0 +1,28 @@
+import { Effect, type Schema } from "effect";
+import type { JobReadOptions, PgBossClient } from "#server/client.ts";
+import type { JobPayloadSchema } from "#server/definition.ts";
+import { toPgBossError } from "#server/error.ts";
+import { decodeStoredData } from "#server/internal/storedRows.ts";
+
+export function inspectionJobs(client: PgBossClient) {
+	function storedJobs(queue: { readonly name: string }, options?: JobReadOptions) {
+		return Effect.tryPromise({
+			catch: (error) => toPgBossError("inspect", error, queue.name),
+			try: () => {
+				if (client.findJobs === undefined) {
+					throw new TypeError("This pg-boss client does not support findJobs");
+				}
+				return client.findJobs(queue.name, options);
+			},
+		});
+	}
+	function jobs<TName extends string, TPayload extends JobPayloadSchema | typeof Schema.Null>(
+		queue: { readonly name: TName; readonly schema: TPayload },
+		options?: JobReadOptions,
+	) {
+		return storedJobs(queue, options).pipe(
+			Effect.flatMap((rows) => Effect.forEach(rows, (job) => decodeStoredData(queue, job.data).pipe(Effect.map((data) => ({ ...job, data }))))),
+		);
+	}
+	return { jobs, storedJobs };
+}

package/src/server/adapters/inspectionOperation.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import { toPgBossError } from "#server/error.ts";
+
+export function inspectionOperation<A>(run: () => Promise<A>, queue?: string) {
+	return Effect.tryPromise({ catch: (error) => toPgBossError("inspect", error, queue), try: run });
+}

package/src/server/adapters/inspectionPlan.ts

@@ -0,0 +1,21 @@
+import { quotedSchema } from "#server/internal/storedRows.ts";
+
+export function inspectionChannel(schema: string): string {
+	return `jobs:${schema}`;
+}
+
+export function inspectionPlan(schema: string): string {
+	const quoted = quotedSchema(schema);
+	const channel = inspectionChannel(schema).replaceAll("'", "''");
+	const body = `BEGIN
+	CREATE OR REPLACE FUNCTION ${quoted}.effect_job_changed() RETURNS trigger LANGUAGE plpgsql AS $body$
+	BEGIN
+		PERFORM pg_notify('${channel}', COALESCE(NEW.name, OLD.name));
+		RETURN NULL;
+	END
+	$body$;
+	CREATE OR REPLACE TRIGGER effect_job_changed AFTER INSERT OR UPDATE OR DELETE ON ${quoted}.job
+	FOR EACH ROW EXECUTE FUNCTION ${quoted}.effect_job_changed();
+	END`;
+	return `DO '${body.replaceAll("'", "''")}'`;
+}

package/src/server/adapters/inspectionReads.ts

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import { inspectionDeferrals } from "#server/adapters/inspectionDeferrals.ts";
+import { inspectionJobs } from "#server/adapters/inspectionJobs.ts";
+import { inspectionOperation } from "#server/adapters/inspectionOperation.ts";
+import { inspectionSnapshot } from "#server/adapters/inspectionSnapshot.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+
+const Busy = Schema.Struct({ busy: Schema.Boolean });
+export function inspectionReads(client: PgBossClient, schema: string) {
+	const quoted = quotedSchema(schema);
+	function query(text: string, values?: unknown[]) {
+		const db = client.getDb?.();
+		if (db === undefined) {
+			throw new TypeError("This pg-boss client does not support getDb");
+		}
+		return db.executeSql(text, values);
+	}
+	return {
+		...inspectionDeferrals(client),
+		busy: (queues: readonly Pick<QueueDefinition, "name">[]) =>
+			inspectionOperation(async () => {
+				const { rows } = await query(
+					`/* jobs inspection busy */ 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`,
+					[queues.map(({ name }) => name)],
+				);
+				return Schema.decodeUnknownSync(Busy)(rows[0]).busy;
+			}),
+		...inspectionJobs(client),
+		queue: (queue: Pick<QueueDefinition, "name">) => inspectionOperation(() => client.getQueue(queue.name), queue.name),
+		schedules: (name?: string, key?: string) =>
+			inspectionOperation(() => {
+				if (client.getSchedules === undefined) {
+					throw new TypeError("This pg-boss client does not support getSchedules");
+				}
+				return client.getSchedules(name, key);
+			}),
+		schemaVersion: () =>
+			inspectionOperation(() => {
+				if (client.schemaVersion === undefined) {
+					throw new TypeError("This pg-boss client does not support schemaVersion");
+				}
+				return client.schemaVersion();
+			}),
+		snapshot: inspectionSnapshot(
+			() => client,
+			() => schema,
+		),
+	};
+}

package/src/server/{internal/testingSnapshot.ts → adapters/inspectionSnapshot.ts}

@@ -1,9 +1,9 @@
 import { Effect, Schema } from "effect";
-import type { PgBoss } from "pg-boss";
-import type { PgBossPayloadError, PgBossTestingError } from "#error.ts";
-import { decodeStoredData, quotedSchema } from "#internal/storedRows.ts";
-import { testingOperation } from "#internal/testingReadout.ts";
-import type { SnapshotQueue, UnfinishedJob } from "#testing.ts";
+import { inspectionOperation } from "#server/adapters/inspectionOperation.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { PgBossError, PgBossPayloadError } from "#server/error.ts";
+import type { SnapshotQueue, UnfinishedJob } from "#server/inspection.ts";
+import { decodeStoredData, quotedSchema } from "#server/internal/storedRows.ts";
 
 const Rows = Schema.Array(
 	Schema.Struct({
@@ -15,29 +15,27 @@ const Rows = Schema.Array(
 	}),
 );
 
-export function testingSnapshot(client: () => PgBoss, schema: () => string) {
+export function inspectionSnapshot(client: () => PgBossClient, schema: () => string) {
 	return <const TQueues extends readonly SnapshotQueue[]>(
 		queues: TQueues,
-	): Effect.Effect<
-		readonly UnfinishedJob<TQueues[number]>[],
-		PgBossPayloadError | PgBossTestingError,
-		TQueues[number]["schema"]["DecodingServices"]
-	> => {
+	): Effect.Effect<readonly UnfinishedJob<TQueues[number]>[], PgBossPayloadError | PgBossError, TQueues[number]["schema"]["DecodingServices"]> => {
 		const byName = new Map<string, TQueues[number]>(queues.map((queue) => [queue.name, queue]));
-		return testingOperation("snapshot", async () => {
+		return inspectionOperation(async () => {
 			const quoted = quotedSchema(schema());
-			const { rows } = await client()
-				.getDb()
-				.executeSql(
-					`SELECT id, name AS queue, data, start_after AS "startAfter",
+			const db = client().getDb?.();
+			if (db === undefined) {
+				throw new TypeError("This pg-boss client does not support getDb");
+			}
+			const { rows } = await db.executeSql(
+				`SELECT id, name AS queue, data, start_after AS "startAfter",
 					CASE WHEN state = 'retry' AND started_on IS NULL AND start_after > ${quoted}.job_now()
 						AND output ? 'jobDeferral'
 					THEN 'deferred' ELSE state::text END AS state
 					FROM ${quoted}.job
 					WHERE name = ANY($1::text[]) AND state IN ('created', 'retry', 'active', 'failed')
 					ORDER BY created_on, id`,
-					[[...byName.keys()]],
-				);
+				[[...byName.keys()]],
+			);
 			return Schema.decodeUnknownPromise(Rows)(rows);
 		}).pipe(
 			Effect.flatMap((rows) =>

package/src/server/adapters/installSchema.ts

@@ -3,8 +3,8 @@ import { SqlClient } from "effect/sql";
 import type { Connection } from "effect/sql/SqlConnection";
 import { getConstructionPlans, getMigrationPlans, PgBoss } from "pg-boss";
 import pgBossPackage from "pg-boss/package.json" with { type: "json" };
-import { jobStorePlans } from "#internal/jobStorePlans.ts";
-import type { PgBossSchemaOptions } from "#schema.ts";
+import { jobStorePlans } from "#server/internal/jobStorePlans.ts";
+import type { PgBossSchemaOptions } from "#server/schema.ts";
 import { runSchemaPlan } from "./runSchemaPlan.ts";
 import { resumeSchemaIndexes } from "./schemaIndexBuilds.ts";
 

package/src/server/adapters/jobEngine.ts

@@ -0,0 +1,55 @@
+import { type Context, Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import type { JobEngine } from "#server/internal/engine.ts";
+import { listJobs } from "./listJobs.ts";
+import { queueAdministration } from "./queueAdministration.ts";
+import { settleDeferral } from "./settleDeferral.ts";
+
+export function jobEngine(client: PgBossClient, schema = "pgboss"): Context.Service.Shape<typeof JobEngine> {
+	return {
+		...queueAdministration(client),
+		getJob: (queue, id) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("getJob", error, queue),
+				try: async () => {
+					if (client.findJobs === undefined) {
+						throw new TypeError("This pg-boss client does not support findJobs");
+					}
+					return (await client.findJobs(queue, { id }))[0];
+				},
+			}),
+		listJobs: listJobs(client, schema),
+		retry: (queue, id) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("retry", error, queue),
+				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, { id }))[0];
+					if (job?.state !== "failed" && job?.state !== "retry") {
+						return;
+					}
+					if (job.state === "failed") {
+						await client.retry(queue, id);
+					}
+					await client.update(queue, undefined, { id, startAfter: 0 });
+				},
+			}),
+		settleDeferral: (job, at, reason, maxDeferrals) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("settle", error, job.name),
+				try: () => settleDeferral(client, schema, job, at, reason, maxDeferrals),
+			}).pipe(
+				Effect.tap((settled) =>
+					Effect.sync(() => {
+						if (!settled.claimed || settled.deferred) {
+							// Native batch settlement must not match a sibling's new claim at the unchanged retry count.
+							job.retryCount = Number.MAX_SAFE_INTEGER;
+						}
+					}),
+				),
+			),
+	};
+}

package/src/server/adapters/lifecycle.ts

@@ -0,0 +1,67 @@
+import { type Context, Effect, Exit, Scope } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import { PgBossClientOptionsError, toPgBossError } from "#server/error.ts";
+import { observeClientErrors } from "#server/internal/clientErrors.ts";
+import { jobStorePlans } from "#server/internal/jobStorePlans.ts";
+import type { AcquireClientOptions, ClientEngine } from "#server/internal/lifecycle.ts";
+import { acquireCachedClient, releaseCachedClient } from "./clientCache.ts";
+import { defaultClientFactory } from "./defaultClientFactory.ts";
+
+export interface StartingClient {
+	readonly client: PgBossClient;
+	readonly ready: Promise<void>;
+	readonly stop: (options?: StopOptions) => Promise<void>;
+}
+
+function startClient(options: AcquireClientOptions, report: (error: Error) => void): StartingClient {
+	const client = (options.clientFactory ?? defaultClientFactory)(options.constructor);
+	observeClientErrors(client, report);
+	let closing = false;
+	const ready = (async () => {
+		await client.start();
+		if (!closing && options.constructor.migrate !== false && client.getDb !== undefined) {
+			for (const plan of jobStorePlans(options.constructor.schema ?? "pgboss")) {
+				await client.getDb().executeSql(plan);
+			}
+		}
+	})();
+	return {
+		client,
+		ready,
+		stop: (settings) => {
+			closing = true;
+			return client.stop(settings);
+		},
+	};
+}
+
+const acquire = Effect.fnUntraced(function* (options: AcquireClientOptions, report: (error: Error) => void, stop?: StopOptions) {
+	const scope = yield* Scope.fork(yield* Scope.Scope);
+	return yield* Effect.gen(function* () {
+		const lease = yield* Effect.acquireRelease(
+			Effect.try({
+				catch: (error) => (error instanceof PgBossClientOptionsError ? error : toPgBossError("start", error)),
+				try: () =>
+					options.clientCacheKey === undefined
+						? { ...startClient(options, report), reused: false }
+						: acquireCachedClient(options.clientCacheKey, options.constructor, () => startClient(options, report)),
+			}),
+			(acquired) =>
+				Effect.tryPromise({
+					catch: (error) => toPgBossError("stop", error),
+					try: async () => {
+						const client = options.clientCacheKey === undefined ? acquired : releaseCachedClient(options.clientCacheKey);
+						await client?.stop(stop);
+					},
+				}).pipe(Effect.catch(Effect.logError)),
+		);
+		yield* Effect.tryPromise({ catch: (error) => toPgBossError("start", error), try: () => lease.ready });
+		return { ...(options.clientCacheKey === undefined ? {} : { cacheKey: options.clientCacheKey }), client: lease.client, reused: lease.reused };
+	}).pipe(
+		Effect.provideService(Scope.Scope, scope),
+		Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))),
+	);
+});
+
+export const clientEngine: Context.Service.Shape<typeof ClientEngine> = { acquire };

package/src/server/adapters/listJobs.ts

@@ -0,0 +1,43 @@
+import { type Context, Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deadLetterQueueName } from "#server/health.ts";
+import type { JobEngine } from "#server/internal/engine.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
+
+export function listJobs(client: PgBossClient, schema: string): Context.Service.Shape<typeof JobEngine>["listJobs"] {
+	return (listing, queue, after, limit) =>
+		Effect.tryPromise({
+			catch: (error) => toPgBossError(listing, error, queue),
+			try: async () => {
+				if (client.getDb === undefined) {
+					throw new TypeError("This pg-boss client does not support getDb");
+				}
+				const quoted = quotedSchema(schema);
+				const { rows: storedRows } = await client.getDb().executeSql(
+					`SELECT
+					id,
+					name AS queue,
+					state,
+					retry_count AS "retryCount",
+					retry_limit AS "retryLimit",
+					created_on AS "createdOn",
+					started_on AS "startedOn",
+					completed_on AS "completedOn",
+					output,
+					data,
+					source_id AS "sourceId",
+					source_output AS "sourceOutput",
+					to_json(created_on) #>> '{}' AS "cursorAt"
+				FROM ${quoted}.job
+				WHERE name = $1
+					${listing === "failedJobs" ? "AND state = 'failed'" : ""}
+					AND ($2::timestamptz IS NULL OR (created_on, id) < ($2::timestamptz, $3::uuid))
+				ORDER BY created_on DESC, id DESC
+				LIMIT $4`,
+					[listing === "failedJobs" ? queue : deadLetterQueueName(queue), after?.[0] ?? null, after?.[1] ?? null, limit + 1],
+				);
+				return storedRows;
+			},
+		});
+}

package/src/server/adapters/payloadIdentity.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+
+export function payloadKey(parts: readonly string[], payload: object): string {
+	return JSON.stringify(parts.map((part) => [part, typeof Reflect.get(payload, part), String(Reflect.get(payload, part))]));
+}
+
+export function payloadJobId(queue: string, parts: readonly string[], payload: object): string {
+	const bytes = createHash("sha256")
+		.update(JSON.stringify([queue, payloadKey(parts, payload)]))
+		.digest();
+	bytes.writeUInt8((bytes.readUInt8(6) & 0x0f) | 0x80, 6);
+	bytes.writeUInt8((bytes.readUInt8(8) & 0x3f) | 0x80, 8);
+	const hex = bytes.subarray(0, 16).toString("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

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/{internal/testingSignal.ts → adapters/queueSignal.ts}

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 
-export function testingSignal() {
+export function queueSignal() {
 	let revision = 0;
 	const listeners = new Set<(revision: number) => void>();
 	return {