@shivaedev/jobs 0.0.0 → 0.20.0

package/src/server/error.ts

@@ -0,0 +1,73 @@
+import { Data, Redacted } from "effect";
+
+export type PgBossOperation =
+	| "counts"
+	| "deadLetteredJobs"
+	| "enqueue"
+	| "failedJobs"
+	| "getJob"
+	| "health"
+	| "install"
+	| "register"
+	| "retry"
+	| "settle"
+	| "start"
+	| "stop";
+
+export class PgBossError extends Data.TaggedError("PgBossError")<{
+	readonly operation: PgBossOperation;
+	readonly queue?: string | undefined;
+	readonly original: Redacted.Redacted<unknown>;
+}> {
+	// The original's message can quote payloads or connection strings, so only its class and code are shown.
+	override get message(): string {
+		const target = this.queue === undefined ? "" : ` for queue ${this.queue}`;
+		return `pg-boss ${this.operation}${target} failed: ${originalKind(Redacted.value(this.original))}`;
+	}
+}
+
+function originalKind(original: unknown): string {
+	if (!(original instanceof Error)) {
+		return typeof original;
+	}
+	const code: unknown = Reflect.get(original, "code");
+	return typeof code === "string" ? `${original.constructor.name} ${code}` : original.constructor.name;
+}
+
+export class PgBossQueueOptionsError extends Data.TaggedError("PgBossQueueOptionsError")<{
+	readonly queue: string;
+	readonly options: readonly ("partition" | "policy")[];
+}> {
+	override get message(): string {
+		return `Queue ${this.queue} cannot change options after creation: ${this.options.join(", ")}`;
+	}
+}
+
+export class PgBossClientOptionsError extends Data.TaggedError("PgBossClientOptionsError")<{
+	readonly key: string | symbol;
+	readonly options: readonly string[];
+}> {
+	override get message(): string {
+		return `Shared pg-boss client ${String(this.key)} has different constructor settings: ${this.options.join(", ")}`;
+	}
+}
+
+export class PgBossPayloadError extends Data.TaggedError("PgBossPayloadError")<{
+	readonly direction: "decode" | "encode";
+	readonly queue: string;
+	readonly original: Redacted.Redacted<unknown>;
+}> {}
+
+export class PgBossTestingError extends Data.TaggedError("PgBossTestingError")<{
+	readonly operation: string;
+	readonly original: Redacted.Redacted<unknown>;
+	readonly queue?: string | undefined;
+}> {}
+
+export function toPgBossError(operation: PgBossOperation, error: unknown, queue?: string): PgBossError {
+	return new PgBossError({
+		operation,
+		original: Redacted.make(error),
+		queue,
+	});
+}

package/src/server/health.ts

@@ -0,0 +1,60 @@
+import type { DateTime, Option } from "effect";
+import type { JobWithMetadata } from "pg-boss";
+
+export interface QueueCounts {
+	readonly activeCount: number;
+	readonly failedCount: number;
+	readonly queuedCount: number;
+	readonly totalCount: number;
+}
+
+export interface QueueHealth {
+	readonly activeCount: number;
+	readonly deadLetteredCount: number;
+	readonly failedCount: number;
+	readonly name: string;
+	readonly queuedCount: number;
+	readonly readyCount: number;
+}
+
+export interface JobsHealth {
+	readonly activeTotal: number;
+	readonly deadLetteredTotal: number;
+	readonly failedTotal: number;
+	readonly jobs: readonly QueueHealth[];
+	readonly queuedTotal: number;
+	readonly readyTotal: number;
+}
+
+export function deadLetterQueueName(queueName: string): string {
+	return `${queueName}-dlq`;
+}
+
+export interface ListedJob<TData> {
+	readonly attempt: number;
+	readonly completedOn: Option.Option<DateTime.Utc>;
+	readonly createdOn: DateTime.Utc;
+	readonly data: TData;
+	readonly id: string;
+	readonly output: unknown;
+	readonly queue: string;
+	readonly retryCount: number;
+	readonly retryLimit: number;
+	readonly startedOn: Option.Option<DateTime.Utc>;
+	readonly state: JobWithMetadata["state"];
+}
+
+export interface DeadLetteredJob<TData> extends ListedJob<TData> {
+	readonly sourceId: Option.Option<string>;
+	readonly sourceOutput: unknown;
+}
+
+export interface JobPageOptions {
+	readonly cursor?: string | undefined;
+	readonly limit: number;
+}
+
+export interface JobPage<TJob> {
+	readonly jobs: readonly TJob[];
+	readonly next: Option.Option<string>;
+}

package/src/server/internal/batchHandler.ts

@@ -0,0 +1,71 @@
+import { Cause, Clock, Effect, Exit } from "effect";
+import type { Job } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { deadlineOf } from "#internal/deadlineOf.ts";
+import { deferredAttempt } from "#internal/deferral.ts";
+import { waitForBatchExpiry } from "#internal/waitForBatchExpiry.ts";
+
+function failureOutput(cause: Cause.Cause<unknown>): object {
+	const error = Cause.squash(cause);
+	return typeof error === "object" && error !== null ? error : { message: String(error) };
+}
+
+async function settleAttempt(
+	complete: NonNullable<PgBossClient["complete"]>,
+	fail: NonNullable<PgBossClient["fail"]>,
+	name: string,
+	job: Job<unknown>,
+	exit: Exit.Exit<unknown, unknown>,
+	afterFailure?: (job: Job<unknown>) => Promise<void>,
+) {
+	if (Exit.isSuccess(exit)) {
+		if (exit.value !== deferredAttempt) {
+			await complete(name, job);
+		}
+	} else {
+		await fail(name, job, failureOutput(exit.cause));
+		await afterFailure?.(job);
+	}
+}
+
+export function batchHandler(
+	client: PgBossClient,
+	name: string,
+	run: (job: Job<unknown>) => Effect.Effect<unknown, unknown>,
+	afterFailure?: (job: Job<unknown>) => Promise<void>,
+	execute: typeof Effect.runPromise = Effect.runPromise,
+) {
+	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");
+	}
+	function waitForExpiry(jobs: readonly Job<unknown>[]) {
+		return execute(waitForBatchExpiry(client, name, jobs).pipe(Effect.tapError(Effect.logError)));
+	}
+
+	return async (jobs: readonly Job<unknown>[]): Promise<void> => {
+		let expired = false;
+		for (const job of jobs) {
+			const deadline = deadlineOf(job);
+			if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
+				expired = true;
+				continue;
+			}
+			const exit = await Effect.runPromiseExit(
+				Effect.flatMap(Clock.currentTimeMillis, (now) => {
+					const remaining = deadline - now;
+					return remaining <= 0 ? Effect.interrupt : run(job).pipe(Effect.timeoutOrElse({ duration: remaining, orElse: () => Effect.interrupt }));
+				}),
+				{ signal: job.signal },
+			);
+			if (job.signal.aborted || (Exit.isFailure(exit) && Cause.hasInterrupts(exit.cause))) {
+				return waitForExpiry(jobs);
+			}
+			await settleAttempt(complete, fail, name, job, exit, afterFailure);
+		}
+		if (expired) {
+			return waitForExpiry(jobs);
+		}
+	};
+}

package/src/server/internal/clientCache.ts

@@ -0,0 +1,73 @@
+import { isDeepStrictEqual } from "node:util";
+import type { ConstructorOptions } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { PgBossClientOptionsError } from "#error.ts";
+
+interface CachedClient {
+	readonly client: Promise<PgBossClient>;
+	readonly constructorOptions: ConstructorOptions;
+	references: number;
+}
+
+const cacheSymbol = Symbol.for("@shivaedev/jobs/server/client-cache");
+const shared: unknown = Reflect.get(globalThis, cacheSymbol);
+const clients: Map<string | symbol, unknown> = shared instanceof Map ? shared : new Map<string | symbol, unknown>();
+Reflect.set(globalThis, cacheSymbol, clients);
+
+function entryFor(key: string | symbol): CachedClient | undefined {
+	const value = clients.get(key);
+	return isCachedClient(value) ? value : undefined;
+}
+
+function isCachedClient(value: unknown): value is CachedClient {
+	return (
+		typeof value === "object"
+		&& value !== null
+		&& Reflect.get(value, "client") instanceof Promise
+		&& typeof Reflect.get(value, "constructorOptions") === "object"
+		&& typeof Reflect.get(value, "references") === "number"
+	);
+}
+
+export async function acquireCachedClient(key: string | symbol, constructorOptions: ConstructorOptions, start: () => Promise<PgBossClient>) {
+	const existing = entryFor(key);
+	if (existing !== undefined) {
+		const options = [...new Set([...Object.keys(existing.constructorOptions), ...Object.keys(constructorOptions)])]
+			.filter((option) => !isDeepStrictEqual(Reflect.get(existing.constructorOptions, option), Reflect.get(constructorOptions, option)))
+			.sort((first, second) => first.localeCompare(second));
+		if (options.length > 0) {
+			throw new PgBossClientOptionsError({ key, options });
+		}
+		existing.references += 1;
+		try {
+			return { client: await existing.client, reused: true };
+		} catch (error) {
+			existing.references -= 1;
+			throw error;
+		}
+	}
+	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;
+	}
+}
+
+export function releaseCachedClient(key: string | symbol): Promise<PgBossClient> | undefined {
+	const entry = entryFor(key);
+	if (entry === undefined) {
+		return;
+	}
+	entry.references -= 1;
+	if (entry.references > 0) {
+		return;
+	}
+	clients.delete(key);
+	return entry.client;
+}

package/src/server/internal/clientErrors.ts

@@ -0,0 +1,64 @@
+import { Effect } from "effect";
+import type { PgBossClient } from "#client.ts";
+
+type Listener = (error: Error) => void;
+
+interface Observer {
+	readonly dispose: () => void;
+	readonly listeners: Set<Listener>;
+}
+
+const key = Symbol.for("@shivaedev/jobs/server/error-observers");
+const shared: unknown = Reflect.get(globalThis, key);
+const observers: WeakMap<WeakKey, unknown> = shared instanceof WeakMap ? shared : new WeakMap<WeakKey, unknown>();
+Reflect.set(globalThis, key, observers);
+
+export function logClientError(error: Error): Effect.Effect<void> {
+	const message = { event: "pg_boss_error", message: error.message };
+	return Reflect.get(error, "code") === "57P01" ? Effect.logDebug(message) : Effect.logError(message);
+}
+
+export function observeClientErrors(client: PgBossClient, fallback: Listener): void {
+	closeClientErrors(client);
+	const listeners = new Set<Listener>();
+	const listener: Listener = (error) => {
+		if (listeners.size === 0) {
+			fallback(error);
+		} else {
+			for (const report of listeners) {
+				report(error);
+			}
+		}
+	};
+	// Pool shutdown can resolve before its clients finish disconnecting.
+	client.on("error", listener);
+	observers.set(client, { dispose: () => client.off("error", listener), listeners });
+}
+
+export function subscribeClientErrors(client: PgBossClient, listener: Listener): () => void {
+	const observer = observerFor(client);
+	if (observer === undefined) {
+		throw new Error("pg-boss client has no error observer");
+	}
+	observer.listeners.add(listener);
+	return () => observer.listeners.delete(listener);
+}
+
+function closeClientErrors(client: PgBossClient): void {
+	observerFor(client)?.dispose();
+	observers.delete(client);
+}
+
+function observerFor(client: PgBossClient): Observer | undefined {
+	const value = observers.get(client);
+	return isObserver(value) ? value : undefined;
+}
+
+function isObserver(value: unknown): value is Observer {
+	return (
+		typeof value === "object"
+		&& value !== null
+		&& typeof Reflect.get(value, "dispose") === "function"
+		&& Reflect.get(value, "listeners") instanceof Set
+	);
+}

package/src/server/internal/countsFor.ts

@@ -0,0 +1,34 @@
+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";
+
+const Counts = Schema.Struct({
+	activeCount: Schema.Number,
+	failedCount: Schema.Number,
+	queuedCount: Schema.Number,
+	totalCount: Schema.Number,
+});
+
+export function countsFor(client: PgBossClient, schema: string, name: string): Effect.Effect<QueueCounts, import("#error.ts").PgBossError> {
+	return Effect.tryPromise({
+		catch: (error) => toPgBossError("counts", error, name),
+		try: async () => {
+			if (client.getDb === undefined) {
+				throw new TypeError("This pg-boss client does not support getDb");
+			}
+			const quoted = quotedSchema(schema);
+			const { rows } = await client.getDb().executeSql(
+				`SELECT
+					count(*) FILTER (WHERE state = 'active')::int AS "activeCount",
+					count(*) FILTER (WHERE state = 'failed')::int AS "failedCount",
+					count(*) FILTER (WHERE state IN ('created', 'retry'))::int AS "queuedCount",
+					count(*)::int AS "totalCount"
+				FROM ${quoted}.job WHERE name = $1`,
+				[name],
+			);
+			return Schema.decodeUnknownPromise(Counts)(rows[0]);
+		},
+	});
+}

package/src/server/internal/deadlineOf.ts

@@ -0,0 +1,8 @@
+import type { Job } from "pg-boss";
+
+export function deadlineOf(job: Job<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");
+	}
+	return job.startedOn.getTime() + job.expireInSeconds * 1000;
+}

package/src/server/internal/deferrableAttempt.ts

@@ -0,0 +1,41 @@
+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 { deferralObservers, deferredAttempt } from "#internal/deferral.ts";
+import { settleDeferral } from "#internal/settleDeferral.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,
+) {
+	return effect.pipe(
+		Effect.catchIf(Schema.is(RetryAt), (error) => {
+			if (maxDeferrals === 0) {
+				return Effect.fail(error);
+			}
+			const at = DateTime.formatIso(error.at);
+			return Effect.promise(() => settleDeferral(client, schema, 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

@@ -0,0 +1,19 @@
+import { Schema } from "effect";
+import type { Job } from "pg-boss";
+import type { PgBossClient } from "#client.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({
+	at: Schema.String,
+	reason: Schema.String,
+});
+
+const Output = Schema.Struct({ jobDeferral: Deferral });
+
+export function deferralOf(job: Job<unknown>) {
+	const output: unknown = Reflect.get(job, "output");
+	return Schema.is(Output)(output) ? output.jobDeferral : undefined;
+}

package/src/server/internal/deferralStorePlan.ts

@@ -0,0 +1,35 @@
+import { STATELY_DEFERRAL_POLICY } from "#internal/deferral.ts";
+import { quotedSchema } from "#internal/storedRows.ts";
+
+export function deferralStorePlan(schema: string): string {
+	const quoted = quotedSchema(schema);
+	const jobTable = `${quoted}.job`.replaceAll("'", "''");
+	const key = `${schema}.effect_job_deferral`.replaceAll("'", "''");
+	const body = `BEGIN
+		PERFORM pg_advisory_xact_lock(hashtextextended('${key}', 0));
+		CREATE TABLE IF NOT EXISTS ${quoted}.effect_job_deferral (
+			name text NOT NULL,
+			id uuid NOT NULL,
+			created_on timestamptz NOT NULL,
+			count bigint NOT NULL,
+			keep_until timestamptz NOT NULL,
+			PRIMARY KEY (name, id)
+		);
+		CREATE INDEX IF NOT EXISTS effect_job_deferral_keep_until ON ${quoted}.effect_job_deferral (keep_until);
+		CREATE OR REPLACE FUNCTION ${quoted}.effect_stately_deferral() RETURNS trigger LANGUAGE plpgsql AS $claim$
+		BEGIN
+			IF NEW.policy = '${STATELY_DEFERRAL_POLICY}' AND NEW.state = 'active' THEN
+				NEW.policy := 'stately';
+			END IF;
+			RETURN NEW;
+		END
+		$claim$;
+		IF NOT EXISTS (
+			SELECT 1 FROM pg_trigger WHERE tgrelid = '${jobTable}'::regclass AND tgname = 'effect_stately_deferral'
+		) THEN
+			CREATE TRIGGER effect_stately_deferral BEFORE UPDATE OF state, policy ON ${quoted}.job
+			FOR EACH ROW EXECUTE FUNCTION ${quoted}.effect_stately_deferral();
+		END IF;
+	END`;
+	return `DO '${body.replaceAll("'", "''")}'`;
+}

package/src/server/internal/definitionOptions.ts

@@ -0,0 +1,14 @@
+import type { QueueOptions } from "#definition.ts";
+
+export function maxDeferrals(options: QueueOptions | undefined): number {
+	const limit = options?.maxDeferrals ?? 10;
+	if (!Number.isSafeInteger(limit) || limit < 0) {
+		throw new RangeError("maxDeferrals must be a nonnegative safe integer");
+	}
+	return limit;
+}
+
+export function nativeQueueOptions(options: QueueOptions | undefined) {
+	const { maxDeferrals: _limit, ...native } = options ?? {};
+	return Object.freeze(native);
+}

package/src/server/internal/enqueueFor.ts

@@ -0,0 +1,39 @@
+import { Effect, Option, Redacted, Schema } from "effect";
+import type { PgBossClient } from "#client.ts";
+import { type PgBossError, PgBossPayloadError, toPgBossError } from "#error.ts";
+import { capturePayload } from "#internal/tracing.ts";
+import type { PgBossService } from "#service.ts";
+
+export function enqueueFor(client: PgBossClient): PgBossService["enqueue"] {
+	return (queue, payload, options) =>
+		Schema.encodeUnknownEffect(queue.schema)(payload).pipe(
+			Effect.mapError(
+				(error) =>
+					new PgBossPayloadError({
+						direction: "encode",
+						original: Redacted.make(error),
+						queue: queue.name,
+					}),
+			),
+			Effect.flatMap((encoded): Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError> => {
+				if (typeof encoded !== "object" || encoded === null) {
+					return Effect.fail(
+						new PgBossPayloadError({
+							direction: "encode",
+							original: Redacted.make(new TypeError("pg-boss payloads must encode to objects")),
+							queue: queue.name,
+						}),
+					);
+				}
+				return capturePayload(encoded).pipe(
+					Effect.flatMap((data) =>
+						Effect.tryPromise({
+							catch: (error) => toPgBossError("enqueue", error, queue.name),
+							try: () => client.send(queue.name, data, queue.key === undefined ? options : { ...options, singletonKey: queue.key(payload) }),
+						}),
+					),
+					Effect.map(Option.fromNullishOr),
+				);
+			}),
+		);
+}

package/src/server/internal/ensureQueue.ts

@@ -0,0 +1,47 @@
+import type { Queue } from "pg-boss";
+import type { PgBossClient } from "#client.ts";
+import { PgBossQueueOptionsError } from "#error.ts";
+import { deadLetterQueueName } from "#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.
+async function createQueue(client: PgBossClient, name: string, options?: Omit<Queue, "name">): Promise<void> {
+	for (let attempt = 1; ; attempt += 1) {
+		try {
+			return await client.createQueue(name, options);
+		} catch (error) {
+			if (attempt === CREATE_QUEUE_ATTEMPTS || !(error instanceof Error) || Reflect.get(error, "code") !== DEADLOCK_DETECTED) {
+				throw error;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 25 * 2 ** (attempt - 1)));
+		}
+	}
+}
+
+export async function ensureQueue(client: PgBossClient, name: string, options: Omit<Queue, "name" | "deadLetter">): Promise<void> {
+	const deadLetter = deadLetterQueueName(name);
+	const desired = { retryBackoff: true, retryLimit: 3, ...options, deadLetter };
+	await createQueue(client, deadLetter);
+	await createQueue(client, name, desired);
+	const existing = await client.getQueue(name);
+	if (existing === null) {
+		return;
+	}
+	const immutable = (["partition", "policy"] as const).filter((key) => desired[key] !== undefined && desired[key] !== existing[key]);
+	if (immutable.length > 0) {
+		throw new PgBossQueueOptionsError({ options: immutable, queue: name });
+	}
+	const { partition: _partition, policy: _policy, ...mutable } = desired;
+	const changed = Object.entries(mutable).some(([key, value]) => value !== undefined && value !== Reflect.get(existing, key));
+	if (!changed) {
+		return;
+	}
+	if (client.updateQueue === undefined) {
+		throw new TypeError("This pg-boss client does not support updateQueue");
+	}
+	// pg-boss validates retryDelayMax against retryBackoff in the same update.
+	await client.updateQueue(name, mutable);
+}

package/src/server/internal/expireAttempt.ts

@@ -0,0 +1,21 @@
+import type { Job, PgBoss } from "pg-boss";
+import { quotedSchema } from "#internal/storedRows.ts";
+
+export async function expireAttempt(client: PgBoss, schema: string, job: Job<unknown>, cause: "expiry" | "heartbeat" = "expiry"): Promise<void> {
+	if ((await client.schemaVersion()) !== 46) {
+		throw new Error("Testing expiry requires pg-boss schema version 46");
+	}
+	const quoted = quotedSchema(schema);
+	const timestamp = cause === "expiry" ? "started_on" : "heartbeat_on";
+	const seconds = cause === "expiry" ? "expire_seconds" : "heartbeat_seconds";
+	await client.getDb().executeSql(
+		`UPDATE ${quoted}.job SET ${timestamp} = ${quoted}.job_now() - (${seconds} + 1) * interval '1 second'
+		WHERE name = $1 AND id = $2 AND retry_count = $3 AND state = 'active'`,
+		[job.name, job.id, job.retryCount],
+	);
+	// Supervision owns expiry and dead lettering; make its claim due with the job's deadline.
+	await client
+		.getDb()
+		.executeSql(`UPDATE ${quoted}.queue SET monitor_claim_on = ${quoted}.job_now() - interval '1 week' WHERE name = $1`, [job.name]);
+	await client.supervise(job.name);
+}

package/src/server/internal/healthFor.ts

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import type { PgBossClient } from "#client.ts";
+import { toPgBossError } from "#error.ts";
+import { deadLetterQueueName, type JobsHealth, type QueueHealth } from "#health.ts";
+
+export function healthFor(client: PgBossClient, names: readonly string[]): Effect.Effect<JobsHealth, import("#error.ts").PgBossError> {
+	return Effect.forEach(
+		names,
+		(name) =>
+			Effect.tryPromise({
+				catch: (error) => toPgBossError("health", error, name),
+				try: async (): Promise<QueueHealth> => {
+					const [queue, deadLetter] = await Promise.all([client.getQueue(name), client.getQueue(deadLetterQueueName(name))]);
+					return {
+						activeCount: queue?.activeCount ?? 0,
+						deadLetteredCount: deadLetter?.queuedCount ?? 0,
+						failedCount: queue?.failedCount ?? 0,
+						name,
+						queuedCount: queue?.queuedCount ?? 0,
+						readyCount: queue?.readyCount ?? 0,
+					};
+				},
+			}),
+		{ concurrency: "unbounded" },
+	).pipe(
+		Effect.map((jobs) => ({
+			activeTotal: jobs.reduce((sum, job) => sum + job.activeCount, 0),
+			deadLetteredTotal: jobs.reduce((sum, job) => sum + job.deadLetteredCount, 0),
+			failedTotal: jobs.reduce((sum, job) => sum + job.failedCount, 0),
+			jobs,
+			queuedTotal: jobs.reduce((sum, job) => sum + job.queuedCount, 0),
+			readyTotal: jobs.reduce((sum, job) => sum + job.readyCount, 0),
+		})),
+	);
+}