@shivaedev/jobs 0.30.0 → 0.32.0

package/src/server/clientOptions.ts

@@ -0,0 +1,80 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+
+export interface ClientOptions {
+	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,

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,17 +27,18 @@ 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>,
 	) => QueueWorker<TPayload, R>;
-	readonly key?: ((payload: Schema.Schema.Type<TPayload>) => string) | undefined;
+	readonly id?: readonly string[] | undefined;
+	readonly key?: readonly 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 +52,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> {
@@ -78,30 +77,39 @@ export type RegistrationRequirements<TRegistrations extends readonly JobRegistra
 			: never
 	: never;
 
+export type PayloadParts<TPayload extends JobPayloadSchema> = readonly {
+	[TField in Extract<keyof TPayload["Type"], string>]: TPayload["Type"][TField] extends string | number | boolean | null ? TField : never;
+}[Extract<keyof TPayload["Type"], string>][];
+
 export type DefineQueueOptions<TName extends string, TPayload extends JobPayloadSchema> = {
+	readonly id?: PayloadParts<NoInfer<TPayload>>;
+	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: PayloadParts<NoInfer<TPayload>>; readonly queue: QueueOptions & { readonly policy: "singleton" } }
 	| { readonly key?: never; readonly queue?: QueueOptions & { readonly policy?: Exclude<QueuePolicy, "singleton"> } }
 );
 
-export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
-	options: DefineQueueOptions<TName, TPayload> & { readonly key: (payload: Schema.Schema.Type<TPayload>) => string },
-): QueueDefinition<TName, TPayload> & { readonly key: (payload: Schema.Schema.Type<TPayload>) => string };
-export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
-	options: DefineQueueOptions<TName, TPayload> & { readonly key?: never },
-): QueueDefinition<TName, TPayload> & { readonly key?: never };
-export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
-	options: DefineQueueOptions<TName, TPayload>,
-): QueueDefinition<TName, TPayload>;
+export function defineQueue<
+	const TName extends string,
+	const TPayload extends JobPayloadSchema,
+	const TId extends readonly string[] | undefined = undefined,
+	const TKey extends readonly string[] | undefined = undefined,
+>(
+	options: DefineQueueOptions<TName, TPayload> & { readonly id?: TId; readonly key?: TKey },
+): QueueDefinition<TName, TPayload> & { readonly id?: TId; readonly key?: TKey };
 export function defineQueue<const TName extends string, const TPayload extends JobPayloadSchema>(
 	options: DefineQueueOptions<TName, TPayload>,
 ): QueueDefinition<TName, TPayload> {
 	const definition: QueueDefinition<TName, TPayload> = {
 		_tag: "QueueDefinition",
-		...(options.key === undefined ? {} : { key: options.key }),
+		id: options.id === undefined ? undefined : Object.freeze([...options.id]),
+		...(options.key === undefined ? {} : { key: Object.freeze([...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 +127,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,22 @@
+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 getSchedules: (name?: string, key?: string) => Promise<EngineSchedule[]>;
+	readonly schemaVersion: () => Promise<number | null>;
+	readonly supervise: (name?: string) => Promise<void>;
+}

package/src/server/enqueueOptions.ts

@@ -0,0 +1,25 @@
+import type { ClientDatabase } from "#server/ClientDatabase.ts";
+import type { QueueDefinition } from "#server/definition.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 type QueueEnqueueOptions<TQueue extends QueueDefinition> = Omit<EnqueueOptions, "id" | "singletonKey"> &
+	(TQueue["id"] extends undefined ? Pick<EnqueueOptions, "id"> : { readonly id?: never }) &
+	(TQueue["key"] extends undefined ? Pick<EnqueueOptions, "singletonKey"> : { readonly singletonKey?: never });
+
+export interface ScheduleOptions extends EnqueueOptions {
+	readonly key?: string;
+	readonly missed?: "skip" | "once";
+	readonly tz?: string;
+}

package/src/server/error.ts

@@ -1,19 +1,35 @@
 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"
+	| "inspect"
 	| "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/inspection.ts

@@ -0,0 +1,50 @@
+import { type DateTime, Effect } from "effect";
+import { defineService } from "@shivaedev/service/defineService.ts";
+import { genericMethod } from "@shivaedev/service/genericMethod.ts";
+import { inspection } from "#server/adapters/inspection.ts";
+import type { inspectionChanges } from "#server/adapters/inspectionChanges.ts";
+import type { inspectionReads } from "#server/adapters/inspectionReads.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#server/definition.ts";
+import { PgBoss } from "#server/PgBoss.ts";
+import type { PgBossService } from "#server/service.ts";
+
+export type SnapshotQueue = Pick<QueueDefinition<string, JobPayloadSchema>, "name" | "schema">;
+
+export interface UnfinishedJob<TQueue extends SnapshotQueue> {
+	readonly data: TQueue["schema"]["Type"];
+	readonly id: string;
+	readonly queue: TQueue["name"];
+	readonly startAfter: DateTime.Utc;
+	readonly state: "active" | "created" | "deferred" | "failed" | "retry";
+}
+
+export const PgBossInspection = defineService({
+	id: "@shivaedev/jobs/PgBossInspection",
+	initialize: Effect.gen(function* () {
+		const acquired = yield* PgBoss;
+		return yield* inspection(acquired.client, acquired.schema);
+	}),
+	methods: (service) => ({
+		busy: service.busy,
+		changes: service.changes,
+		counts: service.counts,
+		deadLetteredJobs: genericMethod(service.deadLetteredJobs),
+		deferred: service.deferred,
+		failedJobs: genericMethod(service.failedJobs),
+		getJob: genericMethod(service.getJob),
+		health: service.health,
+		jobs: genericMethod(service.jobs),
+		queue: service.queue,
+		schedules: service.schedules,
+		schemaVersion: service.schemaVersion,
+		snapshot: genericMethod(service.snapshot),
+		storedJobs: service.storedJobs,
+	}),
+	requires: [PgBoss] as const,
+});
+
+export type PgBossInspectionService = ReturnType<typeof inspectionReads> &
+	Pick<PgBossService, "counts" | "deadLetteredJobs" | "failedJobs" | "getJob"> & {
+		readonly health: (queues: readonly { readonly name: string }[]) => ReturnType<PgBossService["health"]>;
+		readonly changes: (queue?: { readonly name: string }) => ReturnType<typeof inspectionChanges>;
+	};

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 { ClientDatabase } from "#server/ClientDatabase.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: ClientDatabase, 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,9 +1,7 @@
 import { Schema } from "effect";
-import type { Job } from "pg-boss";
-import type { PgBossClient } from "#client.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 export const deferredAttempt = Symbol("deferredAttempt");
-export const deferralObservers = new WeakMap<PgBossClient, () => void>();
 export const STATELY_DEFERRAL_POLICY = "effect-stately-deferred";
 
 export const Deferral = Schema.Struct({
@@ -13,7 +11,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,35 @@
+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 class TestingEngine extends Context.Service<
+	TestingEngine,
+	{
+		readonly expireAttempt: (job: JobAttempt, cause?: "expiry" | "heartbeat") => Effect.Effect<void, PgBossTestingError>;
+	}
+>()("@shivaedev/jobs/TestingEngine") {}

package/src/server/internal/enqueueFor.ts

@@ -1,9 +1,22 @@
 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 { payloadJobId, payloadKey } from "#server/adapters/payloadIdentity.ts";
+import { transactionDb } from "#server/adapters/transactionDb.ts";
+import type { PgBossClient } from "#server/client.ts";
+import type { QueueDefinition } from "#server/definition.ts";
+import type { EnqueueOptions } from "#server/enqueueOptions.ts";
+import { PgBossPayloadError, toPgBossError } from "#server/error.ts";
+import { capturePayload } from "#server/internal/tracing.ts";
+import type { PgBossService } from "#server/service.ts";
+
+function identityOptions(queue: Pick<QueueDefinition, "id" | "key" | "name">, payload: object, options?: EnqueueOptions) {
+	return queue.id === undefined && queue.key === undefined
+		? options
+		: {
+				...options,
+				...(queue.id === undefined ? {} : { id: payloadJobId(queue.name, queue.id, payload) }),
+				...(queue.key === undefined ? {} : { singletonKey: payloadKey(queue.key, payload) }),
+			};
+}
 
 export function enqueueFor(client: PgBossClient): PgBossService["enqueue"] {
 	return (queue, payload, options) =>
@@ -20,7 +33,7 @@ export function enqueueFor(client: PgBossClient): PgBossService["enqueue"] {
 			}
 			const data = yield* capturePayload(encoded);
 			const db = yield* transactionDb;
-			const sendOptions = queue.key === undefined ? options : { ...options, singletonKey: queue.key(payload) };
+			const sendOptions = identityOptions(queue, payload, options);
 			const send = Effect.tryPromise({
 				catch: (error) => toPgBossError("enqueue", error, queue.name),
 				try: () => client.send(queue.name, data, db === undefined ? sendOptions : { ...sendOptions, db }),