@shivaedev/jobs 0.30.0 → 0.31.0

package/dist/server/testing.js

@@ -1,104 +1,12 @@
-import { Duration, Effect, Redacted } from "effect";
-import { testingDueNow } from "#adapters/testingDueNow.ts";
-import { defaultClientFactory } from "#defaultClientFactory.ts";
-import { PgBossTestingError } from "#error.ts";
-import { testingFetches } from "#internal/adapters/testingFetches.ts";
-import { testingClient } from "#internal/testingClient.ts";
-import { testingDeferrals } from "#internal/testingDeferrals.ts";
-import { testingIdle } from "#internal/testingIdle.ts";
-import { testingOperation, testingReadout } from "#internal/testingReadout.ts";
-import { testingSchedules } from "#internal/testingSchedules.ts";
-import { testingSignal } from "#internal/testingSignal.ts";
-import { testingSnapshot } from "#internal/testingSnapshot.ts";
-import { testingWaits } from "#internal/testingWaits.ts";
+import { Effect } from "effect";
+import { testingController } from "#server/adapters/testingController.ts";
+export function makePgBossTesting(options = {}) {
+    return testingController(options);
+}
 export const testRetryPolicy = Object.freeze({ retryBackoff: false, retryDelay: 0 });
 export function linkedWorkerSpans(sender, spans) {
     return Effect.sync(() => spans.filter((span) => span.kind === "consumer"
         && span.attributes.get("messaging.system") === "pg-boss"
         && span.links.some((link) => link.span.spanId === sender.spanId && link.span.traceId === sender.traceId)));
 }
-export function makePgBossTesting(options = {}) {
-    let current;
-    let fetches;
-    let schema = "pgboss";
-    const signal = testingSignal();
-    const work = { batches: new Set(), queues: new Set() };
-    const controls = {
-        changed: signal.changed,
-        expirations: new Map(),
-        expirySeconds: new Map(),
-        failures: new Set(),
-        retryPolicy: options.retryPolicy ?? {},
-        work,
-    };
-    function client() {
-        if (current === undefined) {
-            throw new Error("Provide the testing clientFactory to a jobs Layer first");
-        }
-        return current;
-    }
-    const clientFactory = (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, millisecondsPerJob) => 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) => testingOperation("checkSchemaVersion", async () => {
-            if ((await client().schemaVersion()) !== expected) {
-                throw new Error(`Expected pg-boss schema version ${expected}`);
-            }
-        }),
-        clientFactory,
-        expireAfter: (queue, attempts) => 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, duration) => 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) => 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),
-    };
-}
 //# sourceMappingURL=testing.js.map

package/dist/server/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAe,MAAM,QAAQ,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAuB,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAC3F,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAoB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAgBzD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;AAMrF,MAAM,UAAU,iBAAiB,CAAC,MAAkD,EAAE,KAA6B;IAClH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CACvB,KAAK,CAAC,MAAM,CACX,CAAC,IAAI,EAAE,EAAE,CACR,IAAI,CAAC,IAAI,KAAK,UAAU;WACrB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,SAAS;WACrD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CACzG,CACD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAyB,EAAE;IACnE,IAAI,OAA2B,CAAC;IAChC,IAAI,OAAmC,CAAC;IACxC,IAAI,MAAM,GAAG,QAAQ,CAAC;IACtB,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAgB,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IACpE,MAAM,QAAQ,GAAG;QAChB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,IAAI,GAAG,EAAkB;QACtC,aAAa,EAAE,IAAI,GAAG,EAAkB;QACxC,QAAQ,EAAE,IAAI,GAAG,EAAU;QAC3B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;QACtC,IAAI;KACJ,CAAC;IACF,SAAS,MAAM;QACd,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,MAAM,aAAa,GAAwB,CAAC,aAAa,EAAE,EAAE;QAC5D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,GAAG,aAAa,CAAC,MAAM,IAAI,QAAQ,CAAC;QAC1C,OAAO,GAAG,oBAAoB,CAAC,EAAE,GAAG,aAAa,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC,CAAC;QAClF,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1D,OAAO,aAAa,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,IAAI,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3E,CAAC,CAAC;IACF,OAAO;QACN,GAAG,gBAAgB,CAAC,MAAM,CAAC;QAC3B,GAAG,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;QACtD,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC;QAC3C,GAAG,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;QAC9C,gBAAgB,EAAE,CAAC,KAAsD,EAAE,kBAA0B,EAAE,EAAE,CACxG,gBAAgB,CACf,kBAAkB,EAClB,KAAK,IAAI,EAAE;YACV,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC5C,CAAC;YACD,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;gBAC1C,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;YAC/C,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;gBACpE,MAAM,IAAI,UAAU,CAAC,6CAA6C,CAAC,CAAC;YACrE,CAAC;YACD,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,SAAS,IAAI,EAAE,CAAC,GAAG,kBAAkB,CAAC;YAC5E,IAAI,QAAQ,IAAI,MAAM,CAAC,eAAe,GAAG,IAAI,EAAE,CAAC;gBAC/C,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;YAClF,CAAC;QACF,CAAC,EACD,KAAK,CAAC,IAAI,CACV;QACF,kBAAkB,EAAE,CAAC,QAAgB,EAAE,EAAE,CACxC,gBAAgB,CAAC,oBAAoB,EAAE,KAAK,IAAI,EAAE;YACjD,IAAI,CAAC,MAAM,MAAM,EAAE,CAAC,aAAa,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACnD,MAAM,IAAI,KAAK,CAAC,mCAAmC,QAAQ,EAAE,CAAC,CAAC;YAChE,CAAC;QACF,CAAC,CAAC;QACH,aAAa;QACb,WAAW,EAAE,CAAC,KAAoC,EAAE,QAAgB,EAAE,EAAE,CACvE,MAAM,CAAC,GAAG,CAAC;YACV,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YAC/H,GAAG,EAAE,GAAG,EAAE;gBACT,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;oBACrD,MAAM,IAAI,UAAU,CAAC,qCAAqC,CAAC,CAAC;gBAC7D,CAAC;gBACD,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChD,CAAC;SACD,CAAC;QACH,QAAQ,EAAE,CAAC,KAAoC,EAAE,QAAwB,EAAE,EAAE,CAC5E,MAAM,CAAC,GAAG,CAAC;YACV,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YAC5H,GAAG,EAAE,GAAG,EAAE;gBACT,MAAM,YAAY,GAAG,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAC3E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,IAAI,EAAE,CAAC;oBAC3D,MAAM,IAAI,UAAU,CAAC,+CAA+C,CAAC,CAAC;gBACvE,CAAC;gBACD,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC;YACxE,CAAC;SACD,CAAC;QACH,YAAY,EAAE,CAAC,KAAoC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAChI,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,EAAE,gBAAgB,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,aAAa,EAAE,CAAC;QAChF,QAAQ,EAAE,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC;QAC/C,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;KAC5D,CAAC;AACH,CAAC"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/server/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,MAAM,EAAe,MAAM,QAAQ,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG1E,MAAM,UAAU,iBAAiB,CAAC,OAAO,GAAyB,EAAE;IACnE,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAgBD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;AAMrF,MAAM,UAAU,iBAAiB,CAAC,MAAkD,EAAE,KAA6B;IAClH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CACvB,KAAK,CAAC,MAAM,CACX,CAAC,IAAI,EAAE,EAAE,CACR,IAAI,CAAC,IAAI,KAAK,UAAU;WACrB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,kBAAkB,CAAC,KAAK,SAAS;WACrD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CACzG,CACD,CAAC;AACH,CAAC"}

package/dist/server/workerOptions.d.ts

@@ -0,0 +1,25 @@
+export interface GroupConcurrencyConfig {
+    default: number;
+    tiers?: Record<string, number>;
+}
+export interface WorkerOptions {
+    batchSize?: number;
+    burstWhenBatchFull?: boolean;
+    burstWhenReadyExceeds?: number;
+    groupConcurrency?: number | GroupConcurrencyConfig;
+    heartbeatRefreshSeconds?: number;
+    ignoreStartAfter?: boolean;
+    includeMetadata?: boolean;
+    localConcurrency?: number;
+    localGroupConcurrency?: number | GroupConcurrencyConfig;
+    maxPriority?: number;
+    minPriority?: number;
+    notifyPollingIntervalSeconds?: number;
+    orderByCreatedOn?: boolean;
+    perJobResults?: boolean;
+    pollingIntervalSeconds?: number;
+    priority?: boolean;
+    transactional?: boolean;
+    transactionTimeoutSeconds?: number;
+}
+//# sourceMappingURL=workerOptions.d.ts.map

package/dist/server/workerOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerOptions.d.ts","sourceRoot":"","sources":["../../src/server/workerOptions.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAAC;IAEnD,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAAC;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACnC"}

package/dist/server/workerOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workerOptions.js.map

package/dist/server/workerOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerOptions.js","sourceRoot":"","sources":["../../src/server/workerOptions.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/jobs",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Effect-native jobs and lifecycle management for pg-boss",
   "keywords": [
     "effect"
@@ -20,14 +20,9 @@
   "imports": {
     "#test/*": "./src/test-support/*",
     "#*.ts": {
-      "source": "./src/server/*.ts",
-      "types": "./dist/server/*.d.ts",
-      "default": "./dist/server/*.js"
-    },
-    "#JobFailure.ts": {
-      "source": "./src/JobFailure.ts",
-      "types": "./dist/JobFailure.d.ts",
-      "default": "./dist/JobFailure.js"
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
     }
   },
   "exports": {
@@ -48,16 +43,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@shivaedev/errors": "0.5.0",
+    "@shivaedev/errors": "0.6.0",
     "@shivaedev/service": "0.6.1",
-    "@shivaedev/sql": "0.33.0"
+    "@shivaedev/sql": "0.34.0"
   },
   "devDependencies": {
-    "@shivaedev/http": "0.4.0",
-    "@shivaedev/quality": "0.56.0",
-    "@shivaedev/test": "0.13.0",
-    "@shivaedev/test-sql": "0.16.2",
-    "@shivaedev/test-story": "0.34.0",
+    "@shivaedev/http": "0.5.0",
+    "@shivaedev/quality": "0.57.0",
+    "@shivaedev/test": "0.14.0",
+    "@shivaedev/test-sql": "0.17.0",
+    "@shivaedev/test-story": "0.35.0",
     "@types/node": "24.19.2",
     "effect": "4.0.6",
     "pg-boss": "12.38.0",

package/src/display.ts

@@ -0,0 +1,12 @@
+import type { Schema } from "effect";
+
+export interface SubjectColumn<TPayload extends Schema.Top> {
+	readonly field: Extract<keyof TPayload["Type"], string>;
+	readonly label: string;
+}
+
+export interface QueueDisplay {
+	readonly label?: string;
+	readonly name: string;
+	readonly subject?: readonly { readonly field: string; readonly label: string }[];
+}

package/src/server/ClientDatabase.ts

@@ -0,0 +1,7 @@
+export interface ClientDatabase {
+	beginTransaction?: () => Promise<{ db: ClientDatabase; commit: () => Promise<void>; rollback: () => Promise<void> }>;
+	executeSql: (text: string, values?: unknown[]) => Promise<{ rows: Record<string, unknown>[] }>;
+	listen?: (channel: string, onNotification: (payload: string) => void, onReconnect: () => void) => Promise<{ close: () => Promise<void> }>;
+	poolCounts?: () => { max: number; total: number; idle: number; waiting: number } | null;
+	setSessionStatements?: (statements: string[]) => Promise<void>;
+}

package/src/server/PgBoss.ts

@@ -1,6 +1,6 @@
 import { Context } from "effect";
-import type { StopOptions } from "pg-boss";
-import type { AcquiredClient } from "#internal/lifecycle.ts";
+import type { StopOptions } from "#server/clientOptions.ts";
+import type { AcquiredClient } from "#server/internal/lifecycle.ts";
 
 export class PgBoss extends Context.Service<
 	PgBoss,

package/src/server/adapters/batchClockOffset.ts

@@ -1,7 +1,7 @@
-import { Clock, Effect } from "effect";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
-import { quotedSchema } from "#internal/storedRows.ts";
+import { Clock, Effect, Schema } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { quotedSchema } from "#server/internal/storedRows.ts";
 
 export const batchClockOffset = Effect.fnUntraced(function* (client: PgBossClient, schema: string, name: string) {
 	const { rows } = yield* Effect.tryPromise({
@@ -13,5 +13,8 @@ export const batchClockOffset = Effect.fnUntraced(function* (client: PgBossClien
 			return client.getDb().executeSql(`SELECT EXTRACT(EPOCH FROM ${quotedSchema(schema)}.job_now()) * 1000 AS now`);
 		},
 	});
-	return (yield* Clock.currentTimeMillis) - Number(rows[0].now);
+	const row = yield* Schema.decodeUnknownEffect(Schema.Struct({ now: Schema.Union([Schema.String, Schema.Number]) }))(rows[0]).pipe(
+		Effect.mapError((error) => toPgBossError("settle", error, name)),
+	);
+	return (yield* Clock.currentTimeMillis) - Number(row.now);
 });

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

@@ -1,18 +1,18 @@
 import { Cause, Clock, Effect, Exit } from "effect";
-import type { Job } from "pg-boss";
-import { batchClockOffset } from "#adapters/batchClockOffset.ts";
-import type { PgBossClient } from "#client.ts";
-import { toPgBossError } from "#error.ts";
-import { deadlineOf } from "#internal/deadlineOf.ts";
-import { deferredAttempt } from "#internal/deferral.ts";
-import { failureOutput } from "#internal/failureOutput.ts";
-import { waitForBatchExpiry } from "#internal/waitForBatchExpiry.ts";
+import { batchClockOffset } from "#server/adapters/batchClockOffset.ts";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deadlineOf } from "#server/internal/deadlineOf.ts";
+import { deferredAttempt } from "#server/internal/deferral.ts";
+import { failureOutput } from "#server/internal/failureOutput.ts";
+import { waitForBatchExpiry } from "#server/internal/waitForBatchExpiry.ts";
+import type { WorkerJob } from "#server/job.ts";
 
 function settleAttempt(
 	complete: NonNullable<PgBossClient["complete"]>,
 	fail: NonNullable<PgBossClient["fail"]>,
 	name: string,
-	job: Job<unknown>,
+	job: WorkerJob<unknown>,
 	exit: Exit.Exit<unknown, unknown>,
 ) {
 	if (Exit.isSuccess(exit) && exit.value === deferredAttempt) {
@@ -51,15 +51,15 @@ export function batchHandler<R>(
 	client: PgBossClient,
 	name: string,
 	schema: string,
-	run: (job: Job<unknown>, deadline: number) => Effect.Effect<unknown, unknown, R>,
-	afterRetry: (job: Job<unknown>) => Effect.Effect<void, unknown> = () => Effect.void,
+	run: (job: WorkerJob<unknown>, deadline: number) => Effect.Effect<unknown, unknown, R>,
+	afterRetry: (job: WorkerJob<unknown>) => Effect.Effect<void, unknown> = () => Effect.void,
 ) {
 	const complete = client.complete?.bind(client);
 	const fail = client.fail?.bind(client);
 	if (complete === undefined || fail === undefined) {
 		throw new TypeError("This pg-boss client does not support complete and fail");
 	}
-	const handle = Effect.fnUntraced(function* (job: Job<unknown>, offset: number) {
+	const handle = Effect.fnUntraced(function* (job: WorkerJob<unknown>, offset: number) {
 		if (job.signal.aborted) {
 			return "interrupted";
 		}
@@ -78,7 +78,7 @@ export function batchHandler<R>(
 		}
 		return "settled";
 	});
-	return (jobs: readonly Job<unknown>[]) =>
+	return (jobs: readonly WorkerJob<unknown>[]) =>
 		Effect.gen(function* () {
 			const offset = yield* batchClockOffset(client, schema, name);
 			const deadline = Math.max(...jobs.map((job) => deadlineOf(job) + offset));

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/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,59 @@
+import { type Context, Effect } from "effect";
+import type { PgBossClient } from "#server/client.ts";
+import { toPgBossError } from "#server/error.ts";
+import { deferralObservers } from "#server/internal/deferral.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;
+						}
+						if (settled.deferred) {
+							deferralObservers.get(client)?.();
+						}
+					}),
+				),
+			),
+	};
+}

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

@@ -1,6 +1,6 @@
-import type { PgBoss } from "pg-boss";
+import type { EngineClient } from "#server/engineClient.ts";
 
-export function observeTestingSettlements(client: PgBoss, settled: (name: string) => void) {
+export function observeTestingSettlements(client: EngineClient, settled: (name: string) => void) {
 	const observers = new Map<string, () => void>();
 	return {
 		close() {