@shivaedev/jobs 0.30.0 → 0.31.0

package/src/server/definition.ts

@@ -1,18 +1,16 @@
 import { Clock, Duration, Effect, Schema } from "effect";
-import type { Job, policies, Queue, ScheduleOptions, WorkOptions } from "pg-boss";
-import { maxDeferrals, nativeQueueOptions } from "#internal/definitionOptions.ts";
+import type { QueueDisplay, SubjectColumn } from "#display.ts";
+import type { ScheduleOptions } from "#server/enqueueOptions.ts";
+import { maxDeferrals, nativeQueueOptions } from "#server/internal/definitionOptions.ts";
+import type { WorkerJob } from "#server/job.ts";
+import type { QueueOptions, QueuePolicy } from "#server/queueOptions.ts";
+import type { WorkerOptions } from "#server/workerOptions.ts";
 
 export class RetryAt extends Schema.TaggedError<RetryAt>()("RetryAt", {
 	at: Schema.DateTimeUtc,
 	reason: Schema.String,
 }) {}
 
-export type QueuePolicy = (typeof policies)[keyof typeof policies];
-export type QueueOptions = Omit<Queue, "name" | "deadLetter" | "policy"> & {
-	readonly maxDeferrals?: number;
-	readonly policy?: QueuePolicy;
-};
-
 export interface JobPayloadSchema extends Schema.Top {
 	readonly Encoded: object;
 	readonly Type: object;
@@ -29,7 +27,7 @@ export interface JobContext {
 	readonly signal: AbortSignal;
 }
 
-export interface QueueDefinition<TName extends string = string, TPayload extends JobPayloadSchema = JobPayloadSchema> {
+export interface QueueDefinition<TName extends string = string, TPayload extends JobPayloadSchema = JobPayloadSchema> extends QueueDisplay {
 	readonly _tag: "QueueDefinition";
 	readonly handle: <E, R>(
 		handler: (payload: Schema.Schema.Type<TPayload>, job: JobContext) => Effect.Effect<unknown, E, R>,
@@ -37,9 +35,9 @@ export interface QueueDefinition<TName extends string = string, TPayload extends
 	readonly key?: ((payload: Schema.Schema.Type<TPayload>) => string) | undefined;
 	readonly maxDeferrals: number;
 	readonly name: TName;
-	readonly queueOptions: Omit<Queue, "name" | "deadLetter">;
+	readonly queueOptions: Omit<QueueOptions, "maxDeferrals">;
 	readonly schema: TPayload;
-	readonly workerOptions: WorkOptions;
+	readonly workerOptions: WorkerOptions;
 }
 
 export interface QueueWorker<TPayload extends JobPayloadSchema = JobPayloadSchema, TRequirements = unknown> {
@@ -53,15 +51,15 @@ export type JobRegistration<TRequirements = unknown> =
 	| QueueWorker<JobPayloadSchema & { readonly DecodingServices: TRequirements }, TRequirements>
 	| ScheduledWorker<TRequirements>;
 
-export interface ScheduleDefinition<TName extends string = string> {
+export interface ScheduleDefinition<TName extends string = string> extends QueueDisplay {
 	readonly _tag: "ScheduleDefinition";
 	readonly cron: string;
 	readonly maxDeferrals: number;
 	readonly name: TName;
-	readonly queueOptions: Omit<Queue, "name" | "deadLetter">;
+	readonly queueOptions: Omit<QueueOptions, "maxDeferrals">;
 	readonly run: <E, R>(effect: Effect.Effect<unknown, E, R>) => ScheduledWorker<R>;
 	readonly scheduleOptions: ScheduleOptions;
-	readonly workerOptions: WorkOptions;
+	readonly workerOptions: WorkerOptions;
 }
 
 export interface ScheduledWorker<TRequirements = unknown> {
@@ -79,9 +77,11 @@ export type RegistrationRequirements<TRegistrations extends readonly JobRegistra
 	: never;
 
 export type DefineQueueOptions<TName extends string, TPayload extends JobPayloadSchema> = {
+	readonly label?: string;
 	readonly name: TName;
 	readonly schema: TPayload;
-	readonly worker?: WorkOptions;
+	readonly subject?: readonly SubjectColumn<NoInfer<TPayload>>[];
+	readonly worker?: WorkerOptions;
 } & (
 	| { readonly key: (payload: Schema.Schema.Type<TPayload>) => string; readonly queue: QueueOptions & { readonly policy: "singleton" } }
 	| { readonly key?: never; readonly queue?: QueueOptions & { readonly policy?: Exclude<QueuePolicy, "singleton"> } }
@@ -102,6 +102,8 @@ export function defineQueue<const TName extends string, const TPayload extends J
 	const definition: QueueDefinition<TName, TPayload> = {
 		_tag: "QueueDefinition",
 		...(options.key === undefined ? {} : { key: options.key }),
+		...(options.label === undefined ? {} : { label: options.label }),
+		...(options.subject === undefined ? {} : { subject: Object.freeze(options.subject.map((column) => Object.freeze({ ...column }))) }),
 		handle: (handler) =>
 			Object.freeze({
 				_tag: "QueueWorker" as const,
@@ -119,13 +121,14 @@ export function defineQueue<const TName extends string, const TPayload extends J
 
 export interface DefineScheduleOptions<TName extends string> {
 	readonly cron: string;
+	readonly label?: string;
 	readonly name: TName;
 	readonly queue?: QueueOptions;
 	readonly schedule?: ScheduleOptions;
-	readonly worker?: WorkOptions;
+	readonly worker?: WorkerOptions;
 }
 
-export function jobContext(job: Job<unknown>, deadline: number, deferralCount = 0): JobContext {
+export function jobContext(job: WorkerJob<unknown>, deadline: number, deferralCount = 0): JobContext {
 	return {
 		deferralCount,
 		expireInSeconds: job.expireInSeconds,

package/src/server/engineClient.ts

@@ -0,0 +1,24 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+import type { JobReadOptions, PgBossClient } from "#server/client.ts";
+import type { ScheduleOptions } from "#server/enqueueOptions.ts";
+import type { Job } from "#server/job.ts";
+
+export interface EngineSchedule {
+	cron: string;
+	data?: object;
+	key: string;
+	name: string;
+	options?: ScheduleOptions;
+	timezone: string;
+}
+
+export interface EngineClient extends Required<PgBossClient> {
+	readonly emit: (event: "error", error: Error) => boolean;
+	readonly findJobs: <T = unknown>(name: string, options?: JobReadOptions) => Promise<Job<T>[]>;
+	readonly getDb: () => ClientDatabase;
+	readonly getJobById: <T = unknown>(name: string, id: string) => Promise<Job<T> | null>;
+	readonly getSchedules: (name?: string, key?: string) => Promise<EngineSchedule[]>;
+	readonly getSpy: (name: string) => { clear: () => void; waitForJob: (selector: () => boolean, state: "completed" | "failed") => Promise<unknown> };
+	readonly schemaVersion: () => Promise<number | null>;
+	readonly supervise: (name?: string) => Promise<void>;
+}

package/src/server/enqueueOptions.ts

@@ -0,0 +1,20 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+import type { RetryOptions } from "#server/queueOptions.ts";
+
+export interface EnqueueOptions extends RetryOptions {
+	readonly db?: ClientDatabase;
+	readonly deadLetter?: string;
+	readonly group?: { readonly id: string; readonly tier?: string };
+	readonly id?: string;
+	readonly priority?: number;
+	readonly singletonKey?: string;
+	readonly singletonNextSlot?: boolean;
+	readonly singletonSeconds?: number;
+	readonly startAfter?: number | string | Date;
+}
+
+export interface ScheduleOptions extends EnqueueOptions {
+	readonly key?: string;
+	readonly missed?: "skip" | "once";
+	readonly tz?: string;
+}

package/src/server/error.ts

@@ -1,19 +1,34 @@
 import { Cause, Data, Duration, Redacted } from "effect";
-import { failureOutput } from "#internal/failureOutput.ts";
+import { failureOutput } from "#server/internal/failureOutput.ts";
 
 export type PgBossOperation =
 	| "counts"
 	| "deadLetteredJobs"
+	| "deleteQueue"
 	| "enqueue"
 	| "failedJobs"
 	| "getJob"
 	| "health"
 	| "install"
 	| "register"
+	| "refreshQueueStats"
 	| "retry"
 	| "settle"
 	| "start"
-	| "stop";
+	| "stop"
+	| "unschedule";
+
+export class PgBossNotFoundError extends Data.TaggedError("PgBossNotFoundError")<{
+	readonly operation: "deleteQueue" | "unschedule";
+	readonly queue: string;
+	readonly key?: string;
+}> {
+	override get message(): string {
+		return this.operation === "deleteQueue"
+			? `Queue ${this.queue} does not exist`
+			: `Schedule ${this.queue} with key ${JSON.stringify(this.key ?? "")} does not exist`;
+	}
+}
 
 export class PgBossError extends Data.TaggedError("PgBossError")<{
 	readonly operation: PgBossOperation;

package/src/server/health.ts

@@ -1,6 +1,6 @@
 import type { DateTime, Option } from "effect";
-import type { JobWithMetadata } from "pg-boss";
 import type { JobFailure } from "#JobFailure.ts";
+import type { JobState } from "#server/job.ts";
 
 export interface QueueCounts {
 	readonly activeCount: number;
@@ -42,7 +42,7 @@ export interface ListedJob<TData> {
 	readonly retryCount: number;
 	readonly retryLimit: number;
 	readonly startedOn: Option.Option<DateTime.Utc>;
-	readonly state: JobWithMetadata["state"];
+	readonly state: JobState;
 }
 
 export interface DeadLetteredJob<TData> extends ListedJob<TData> {

package/src/server/internal/acquireClient.ts

@@ -0,0 +1,26 @@
+import { Effect, Redacted } from "effect";
+import { clientErrorLogger } from "#server/adapters/clientErrorLogger.ts";
+import type { PgBossOptions } from "#server/service.ts";
+import { ClientEngine } from "./lifecycle.ts";
+
+export const acquireClient = Effect.fnUntraced(function* (options: PgBossOptions) {
+	const { connectionString, clientFactory, clientCacheKey, stop, ...settings } = options;
+	const constructorOptions = {
+		...settings,
+		idleTimeoutMillis: settings.idleTimeoutMillis ?? 60_000,
+		maxLifetimeSeconds: settings.maxLifetimeSeconds ?? 600,
+		...(connectionString === undefined ? {} : { connectionString: Redacted.value(connectionString) }),
+	};
+	const report = yield* clientErrorLogger();
+	const engine = yield* ClientEngine;
+	const acquired = yield* engine.acquire(
+		{
+			clientCacheKey,
+			clientFactory,
+			constructor: constructorOptions,
+		},
+		report,
+		stop,
+	);
+	return { ...acquired, schema: settings.schema, stop };
+});

package/src/server/internal/adapters/testingFetches.ts

@@ -1,4 +1,4 @@
-import type { PgBoss } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
 
 // pg-boss offers no hook for a worker fetch that finds nothing, so the controller recognizes its claim statement on the client's database.
 const claim = /UPDATE\s+\S+\s+j\s+SET\s+state\s*=\s*'active'/u;
@@ -9,7 +9,7 @@ export interface TestingFetches {
 	readonly passedSince: (queue: string, begun: number) => number;
 }
 
-export function testingFetches(db: ReturnType<PgBoss["getDb"]>, changed: () => void): TestingFetches {
+export function testingFetches(db: ReturnType<EngineClient["getDb"]>, changed: () => void): TestingFetches {
 	const begun = new Map<string, number>();
 	const passed = new Map<string, number[]>();
 	const executeSql = db.executeSql.bind(db);

package/src/server/internal/clientErrors.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 import { isSensitiveKey, redactText } from "@shivaedev/errors/sensitive.ts";
-import type { PgBossClient } from "#client.ts";
+import type { PgBossClient } from "#server/client.ts";
 
 type Listener = (error: Error) => void;
 

package/src/server/internal/countsFor.ts

@@ -1,8 +1,8 @@
 import { Effect, Schema } from "effect";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
-import type { QueueCounts } from "#health.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import type { QueueCounts } from "#server/health.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 const Counts = Schema.Struct({
 	activeCount: Schema.Number,
@@ -11,7 +11,7 @@ const Counts = Schema.Struct({
 	totalCount: Schema.Number,
 });
 
-export function countsFor(client: PgBossClient, schema: string, name: string): Effect.Effect<QueueCounts, import("#error.ts").PgBossError> {
+export function countsFor(client: PgBossClient, schema: string, name: string): Effect.Effect<QueueCounts, import("#server/error.ts").PgBossError> {
 	return Effect.tryPromise({
 		catch: (error) => toPgBossError("counts", error, name),
 		try: async () => {

package/src/server/internal/deadLetterResolutionPlan.ts

@@ -1,4 +1,4 @@
-import { quotedSchema } from "#internal/storedRows.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 export function deadLetterResolutionPlan(schema: string): string {
 	const quoted = quotedSchema(schema);

package/src/server/internal/deadlineOf.ts

@@ -1,6 +1,6 @@
-import type { Job } from "pg-boss";
+import type { WorkerJob } from "#server/job.ts";
 
-export function deadlineOf(job: Job<unknown>): number {
+export function deadlineOf(job: WorkerJob<unknown>): number {
 	if (!("startedOn" in job && job.startedOn instanceof Date && Number.isFinite(job.startedOn.getTime()))) {
 		throw new TypeError("Worker jobs must include pg-boss startedOn metadata");
 	}

package/src/server/internal/deferrableAttempt.ts

@@ -1,42 +1,25 @@
 import { Clock, DateTime, Effect, Schema } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
-import { RetryAt } from "#definition.ts";
-import { toPgBossError } from "#error.ts";
-import { deferralObservers, deferredAttempt } from "#internal/deferral.ts";
-import { settleDeferral } from "#internal/settleDeferral.ts";
+import { RetryAt } from "#server/definition.ts";
+import { deferredAttempt } from "#server/internal/deferral.ts";
+import { type JobAttempt, JobEngine } from "#server/internal/engine.ts";
 
 const recordDeferral = Effect.fnUntraced(function* (at: string, reason: string) {
 	const span = yield* Effect.currentSpan.pipe(Effect.orDie);
 	span.event("job.deferred", yield* Clock.currentTimeNanos, { at, reason });
 });
 
-export function deferrableAttempt<A, E, R>(
-	effect: Effect.Effect<A, E, R>,
-	client: PgBossClient,
-	schema: string,
-	job: Job<unknown>,
-	maxDeferrals: number,
-) {
+export function deferrableAttempt<A, E, R>(effect: Effect.Effect<A, E, R>, job: JobAttempt, maxDeferrals: number) {
 	return effect.pipe(
 		Effect.catchIf(Schema.is(RetryAt), (error) => {
 			if (maxDeferrals === 0) {
 				return Effect.fail(error);
 			}
 			const at = DateTime.formatIso(error.at);
-			return Effect.tryPromise({
-				catch: (failure) => toPgBossError("settle", failure, job.name),
-				try: () => settleDeferral(client, schema, job, at, error.reason, maxDeferrals),
-			}).pipe(
+			return Effect.flatMap(JobEngine, (engine) => engine.settleDeferral(job, at, error.reason, maxDeferrals)).pipe(
 				Effect.flatMap((settled) => {
 					if (settled.claimed && !settled.deferred) {
 						return Effect.fail(error);
 					}
-					// Native batch settlement must not match a sibling's new claim at the unchanged retry count.
-					job.retryCount = Number.MAX_SAFE_INTEGER;
-					if (settled.deferred) {
-						deferralObservers.get(client)?.();
-					}
 					return (settled.deferred ? recordDeferral(at, error.reason) : Effect.void).pipe(Effect.as(deferredAttempt));
 				}),
 			);

package/src/server/internal/deferral.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export const deferredAttempt = Symbol("deferredAttempt");
 export const deferralObservers = new WeakMap<PgBossClient, () => void>();
@@ -13,7 +13,7 @@ export const Deferral = Schema.Struct({
 
 const Output = Schema.Struct({ jobDeferral: Deferral });
 
-export function deferralOf(job: Job<unknown>) {
+export function deferralOf(job: WorkerJob<unknown>) {
 	const output: unknown = Reflect.get(job, "output");
 	return Schema.is(Output)(output) ? output.jobDeferral : undefined;
 }

package/src/server/internal/deferralStorePlan.ts

@@ -1,5 +1,5 @@
-import { STATELY_DEFERRAL_POLICY } from "#internal/deferral.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import { STATELY_DEFERRAL_POLICY } from "#server/internal/deferral.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 export function deferralStorePlan(schema: string): string {
 	const quoted = quotedSchema(schema);

package/src/server/internal/definitionOptions.ts

@@ -1,4 +1,4 @@
-import type { QueueOptions } from "#definition.ts";
+import type { QueueOptions } from "#server/queueOptions.ts";
 
 export function maxDeferrals(options: QueueOptions | undefined): number {
 	const limit = options?.maxDeferrals ?? 10;

package/src/server/internal/engine.ts

@@ -0,0 +1,41 @@
+import { Context, type Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import type { PgBossError, PgBossTestingError } from "#server/error.ts";
+import type { PgBossService } from "#server/service.ts";
+
+export type StoredJob = Awaited<ReturnType<NonNullable<PgBossClient["findJobs"]>>>[number];
+export type JobAttempt = Pick<StoredJob, "name" | "id" | "retryCount">;
+export type Listing = "deadLetteredJobs" | "failedJobs";
+
+export class JobEngine extends Context.Service<
+	JobEngine,
+	Pick<PgBossService, "deleteQueue" | "refreshQueueStats" | "unschedule"> & {
+		readonly getJob: (queue: string, id: string) => Effect.Effect<StoredJob | undefined, PgBossError>;
+		readonly retry: (queue: string, id: string) => Effect.Effect<void, PgBossError>;
+		readonly listJobs: (
+			listing: Listing,
+			queue: string,
+			after: readonly [string, string] | undefined,
+			limit: number,
+		) => Effect.Effect<readonly unknown[], PgBossError>;
+		readonly settleDeferral: (
+			job: JobAttempt,
+			at: string,
+			reason: string,
+			maxDeferrals: number,
+		) => Effect.Effect<{ readonly claimed: boolean; readonly deferred: boolean }, PgBossError>;
+	}
+>()("@shivaedev/jobs/JobEngine") {}
+
+export interface TestingSettlements {
+	readonly close: Effect.Effect<void>;
+	readonly watch: (name: string) => Effect.Effect<void, PgBossTestingError>;
+}
+
+export class TestingEngine extends Context.Service<
+	TestingEngine,
+	{
+		readonly expireAttempt: (job: JobAttempt, cause?: "expiry" | "heartbeat") => Effect.Effect<void, PgBossTestingError>;
+		readonly observeSettlements: (settled: (name: string) => void) => Effect.Effect<TestingSettlements>;
+	}
+>()("@shivaedev/jobs/TestingEngine") {}

package/src/server/internal/enqueueFor.ts

@@ -1,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 };
+});