@shivaedev/effect-pg-boss 0.0.0

package/src/internal/lifecycle.ts

@@ -0,0 +1,121 @@
+import { Effect } from "effect";
+import type { ConstructorOptions, StopOptions } from "pg-boss";
+import { toPgBossError } from "../error.js";
+import {
+	defaultClientFactory,
+	type PgBossClient,
+	type PgBossClientFactory,
+} from "./client.js";
+
+interface CachedClient {
+	readonly client: Promise<PgBossClient>;
+	references: number;
+}
+
+const CacheKey = Symbol.for("@shivaedev/effect-pg-boss/client-cache");
+const globalCache = globalThis as typeof globalThis & {
+	[CacheKey]?: Map<string | symbol, CachedClient>;
+};
+const clientCache =
+	globalCache[CacheKey] ?? new Map<string | symbol, CachedClient>();
+globalCache[CacheKey] = clientCache;
+
+export interface AcquireClientOptions {
+	readonly clientFactory?: PgBossClientFactory;
+	readonly constructor: ConstructorOptions;
+	readonly developmentCacheKey?: string | symbol;
+}
+
+export interface AcquiredClient {
+	readonly client: PgBossClient;
+	readonly cacheKey?: string | symbol;
+	readonly reused: boolean;
+}
+
+const startClient = (options: AcquireClientOptions): Promise<PgBossClient> => {
+	const client = (options.clientFactory ?? defaultClientFactory)(
+		options.constructor,
+	);
+	return client.start().then(
+		() => client,
+		async (error) => {
+			try {
+				await client.stop();
+			} catch {
+				// Preserve the startup failure; stop is best effort on failed acquisition.
+			}
+			throw error;
+		},
+	);
+};
+
+export const acquireClient = (
+	options: AcquireClientOptions,
+): Effect.Effect<AcquiredClient, import("../error.js").PgBossError> =>
+	Effect.tryPromise({
+		try: async () => {
+			const cacheKey =
+				process.env.NODE_ENV === "production"
+					? undefined
+					: options.developmentCacheKey;
+			if (cacheKey === undefined) {
+				return {
+					client: await startClient(options),
+					reused: false,
+				};
+			}
+
+			const existing = clientCache.get(cacheKey);
+			if (existing !== undefined) {
+				existing.references += 1;
+				try {
+					return {
+						cacheKey,
+						client: await existing.client,
+						reused: true,
+					};
+				} catch (error) {
+					existing.references -= 1;
+					throw error;
+				}
+			}
+
+			const entry: CachedClient = {
+				client: startClient(options),
+				references: 1,
+			};
+			clientCache.set(cacheKey, entry);
+			try {
+				return {
+					cacheKey,
+					client: await entry.client,
+					reused: false,
+				};
+			} catch (error) {
+				if (clientCache.get(cacheKey) === entry) clientCache.delete(cacheKey);
+				throw error;
+			}
+		},
+		catch: (error) => toPgBossError("start", error),
+	});
+
+export const releaseClient = (
+	acquired: AcquiredClient,
+	stopOptions?: StopOptions,
+): Effect.Effect<void> =>
+	Effect.tryPromise({
+		try: async () => {
+			if (acquired.cacheKey === undefined) {
+				await acquired.client.stop(stopOptions);
+				return;
+			}
+
+			const entry = clientCache.get(acquired.cacheKey);
+			if (entry === undefined) return;
+			entry.references -= 1;
+			if (entry.references > 0) return;
+			clientCache.delete(acquired.cacheKey);
+			await acquired.client.stop(stopOptions);
+		},
+		catch: (error) => toPgBossError("stop", error),
+	}).pipe(Effect.catch((error) => Effect.logError(error)));

package/src/internal/register.ts

@@ -0,0 +1,135 @@
+import { Effect, Redacted, Schema } from "effect";
+import type { Job } from "pg-boss";
+import {
+	type JobPayloadSchema,
+	type JobRegistration,
+	jobContext,
+	type QueueWorker,
+	type ScheduledWorker,
+} from "../definition.js";
+import { PgBossPayloadError, toPgBossError } from "../error.js";
+import { deadLetterQueueName } from "../health.js";
+import type { PgBossClient } from "./client.js";
+
+const queueOptions = (options: Readonly<Record<string, unknown>>) => ({
+	retryBackoff: true,
+	retryLimit: 3,
+	...options,
+});
+
+const runQueueWorker = <R>(
+	worker: QueueWorker<JobPayloadSchema, R>,
+	job: Job<unknown>,
+	context: import("effect").Context.Context<R>,
+): Promise<unknown> =>
+	Effect.runPromise(
+		Schema.decodeUnknownEffect(worker.queue.schema)(job.data).pipe(
+			Effect.mapError(
+				(error) =>
+					new PgBossPayloadError({
+						direction: "decode",
+						original: Redacted.make(error),
+						queue: worker.queue.name,
+					}),
+			),
+			Effect.flatMap((payload) => worker.handler(payload, jobContext(job))),
+			Effect.provide(context),
+		) as Effect.Effect<unknown, unknown>,
+		{ signal: job.signal },
+	);
+
+const registerQueue = async <R>(
+	client: PgBossClient,
+	worker: QueueWorker<JobPayloadSchema, R>,
+	context: import("effect").Context.Context<R>,
+	replaceWorker: boolean,
+): Promise<void> => {
+	const name = worker.queue.name;
+	const deadLetter = deadLetterQueueName(name);
+	if (replaceWorker) await client.offWork(name);
+	await client.createQueue(deadLetter);
+	await client.createQueue(name, {
+		...queueOptions(worker.queue.queueOptions),
+		deadLetter,
+	});
+	await client.work(name, worker.queue.workerOptions, async (jobs) => {
+		for (const job of jobs) await runQueueWorker(worker, job, context);
+	});
+};
+
+const registerSchedule = async <R>(
+	client: PgBossClient,
+	worker: ScheduledWorker<R>,
+	context: import("effect").Context.Context<R>,
+	replaceWorker: boolean,
+): Promise<void> => {
+	const { schedule } = worker;
+	const deadLetter = deadLetterQueueName(schedule.name);
+	if (replaceWorker) await client.offWork(schedule.name);
+	await client.createQueue(deadLetter);
+	await client.createQueue(schedule.name, {
+		...queueOptions(schedule.queueOptions),
+		deadLetter,
+	});
+	await client.work(
+		schedule.name,
+		schedule.workerOptions,
+		async (jobs: readonly Job<unknown>[]) => {
+			for (const job of jobs) {
+				await Effect.runPromise(Effect.provide(worker.effect, context), {
+					signal: job.signal,
+				});
+			}
+		},
+	);
+	await client.schedule(
+		schedule.name,
+		schedule.cron,
+		null,
+		schedule.scheduleOptions,
+	);
+};
+
+export const registrationNames = (
+	registrations: readonly JobRegistration[],
+): readonly string[] => {
+	const names = registrations.map((registration) =>
+		registration._tag === "QueueWorker"
+			? (registration as QueueWorker).queue.name
+			: (registration as ScheduledWorker).schedule.name,
+	);
+	if (new Set(names).size !== names.length) {
+		throw new TypeError("pg-boss job names must be unique");
+	}
+	return names;
+};
+
+export const registerJobs = <R>(
+	client: PgBossClient,
+	registrations: readonly JobRegistration[],
+	context: import("effect").Context.Context<R>,
+	replaceWorkers: boolean,
+): Effect.Effect<void, import("../error.js").PgBossError> =>
+	Effect.tryPromise({
+		try: async () => {
+			registrationNames(registrations);
+			for (const registration of registrations) {
+				if (registration._tag === "QueueWorker") {
+					await registerQueue(
+						client,
+						registration as QueueWorker<JobPayloadSchema, R>,
+						context,
+						replaceWorkers,
+					);
+				} else {
+					await registerSchedule(
+						client,
+						registration as ScheduledWorker<R>,
+						context,
+						replaceWorkers,
+					);
+				}
+			}
+		},
+		catch: (error) => toPgBossError("register", error),
+	});

package/src/internal/service.ts

@@ -0,0 +1,51 @@
+import { Effect, Option, Redacted, Schema } from "effect";
+import {
+	type PgBossError,
+	PgBossPayloadError,
+	toPgBossError,
+} from "../error.js";
+import type { PgBossService } from "../service.js";
+import type { PgBossClient } from "./client.js";
+import { healthFor } from "./health.js";
+
+export const makeService = (
+	client: PgBossClient,
+	names: readonly string[],
+): PgBossService => ({
+	enqueue: (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 Effect.tryPromise({
+						try: () => client.send(queue.name, encoded, options),
+						catch: (error) => toPgBossError("enqueue", error, queue.name),
+					}).pipe(Effect.map(Option.fromNullishOr));
+				},
+			),
+		),
+	health: healthFor(client, names),
+});

package/src/service.ts

@@ -0,0 +1,148 @@
+import { Context, Effect, Layer, type Option, type Schema } from "effect";
+import type { ConstructorOptions, SendOptions, StopOptions } from "pg-boss";
+import type {
+	JobPayloadSchema,
+	JobRegistration,
+	QueueDefinition,
+	RegistrationRequirements,
+} from "./definition.js";
+import type { PgBossError, PgBossPayloadError } from "./error.js";
+import type { JobsHealth } from "./health.js";
+import type { PgBossClientFactory } from "./internal/client.js";
+import { acquireClient, releaseClient } from "./internal/lifecycle.js";
+import { registerJobs } from "./internal/register.js";
+import { makeService } from "./internal/service.js";
+
+export interface PgBossService {
+	readonly enqueue: <
+		const Name extends string,
+		const Payload extends JobPayloadSchema,
+	>(
+		queue: QueueDefinition<Name, Payload>,
+		payload: Schema.Schema.Type<Payload>,
+		options?: SendOptions,
+	) => Effect.Effect<
+		Option.Option<string>,
+		PgBossError | PgBossPayloadError,
+		Payload["EncodingServices"]
+	>;
+	readonly health: Effect.Effect<JobsHealth, PgBossError>;
+}
+
+interface PgBossIdentifier {
+	readonly _pgBossIdentifier: unique symbol;
+}
+
+export type PgBossLayerOptions<
+	Registrations extends readonly JobRegistration[],
+	ErrorRequirements,
+> = ConstructorOptions & {
+	/** Override client construction for compatible clients or deterministic tests. */
+	readonly clientFactory?: PgBossClientFactory;
+	readonly developmentCacheKey?: string | symbol;
+	readonly jobs: Registrations;
+	readonly onError?: (
+		error: Error,
+	) => Effect.Effect<unknown, never, ErrorRequirements>;
+	readonly stop?: StopOptions;
+};
+
+export interface PgBossDefinition
+	extends Context.Service<PgBossIdentifier, PgBossService> {
+	readonly layer: <
+		const Registrations extends readonly JobRegistration[],
+		ErrorRequirements = never,
+	>(
+		options: PgBossLayerOptions<Registrations, ErrorRequirements>,
+	) => Layer.Layer<
+		PgBossIdentifier,
+		PgBossError,
+		RegistrationRequirements<Registrations> | ErrorRequirements
+	>;
+}
+
+export const makePgBoss = (identifier: string): PgBossDefinition => {
+	const Service = Context.Service<PgBossIdentifier, PgBossService>(identifier);
+
+	const layer = <
+		const Registrations extends readonly JobRegistration[],
+		ErrorRequirements = never,
+	>(
+		options: PgBossLayerOptions<Registrations, ErrorRequirements>,
+	): Layer.Layer<
+		PgBossIdentifier,
+		PgBossError,
+		RegistrationRequirements<Registrations> | ErrorRequirements
+	> => {
+		type Requirements =
+			| RegistrationRequirements<Registrations>
+			| ErrorRequirements;
+		const names = options.jobs.map((registration) =>
+			registration._tag === "QueueWorker"
+				? (registration as import("./definition.js").QueueWorker).queue.name
+				: (registration as import("./definition.js").ScheduledWorker).schedule
+						.name,
+		);
+		const {
+			clientFactory,
+			developmentCacheKey,
+			jobs,
+			onError,
+			stop,
+			...constructorOptions
+		} = options;
+
+		const acquire = Effect.acquireRelease(
+			Effect.gen(function* () {
+				const context = yield* Effect.context<Requirements>();
+				const acquired = yield* acquireClient({
+					clientFactory,
+					constructor: constructorOptions,
+					developmentCacheKey,
+				});
+				const reportError: (
+					error: Error,
+				) => Effect.Effect<unknown, never, Requirements> =
+					onError === undefined
+						? (error) =>
+								Effect.logError({
+									event: "pg_boss_error",
+									message: error.message,
+								})
+						: onError;
+				const errorListener = (error: Error) => {
+					void Effect.runPromise(
+						Effect.exit(Effect.provide(reportError(error), context)),
+					);
+				};
+				acquired.client.on("error", errorListener);
+				const registration = registerJobs(
+					acquired.client,
+					jobs,
+					context,
+					acquired.reused,
+				);
+				return yield* registration.pipe(
+					Effect.as({ acquired, context, errorListener }),
+					Effect.onError(() => {
+						acquired.client.off("error", errorListener);
+						return releaseClient(acquired, stop);
+					}),
+				);
+			}),
+			(resource) => {
+				resource.acquired.client.off("error", resource.errorListener);
+				return releaseClient(resource.acquired, stop);
+			},
+		);
+
+		return Layer.effect(
+			Service,
+			Effect.map(acquire, ({ acquired }) =>
+				makeService(acquired.client, names),
+			),
+		);
+	};
+
+	return Object.assign(Service, { layer }) as PgBossDefinition;
+};