@shivaedev/effect-pg-boss 0.1.3 → 0.2.1

package/src/internal/lifecycle.ts

@@ -1,11 +1,7 @@
 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";
+import { toPgBossError } from "#error.ts";
+import { defaultClientFactory, type PgBossClient, type PgBossClientFactory } from "./client.ts";
 
 interface CachedClient {
 	readonly client: Promise<PgBossClient>;
@@ -13,29 +9,35 @@ interface CachedClient {
 }
 
 const CacheKey = Symbol.for("@shivaedev/effect-pg-boss/client-cache");
-const globalCache = globalThis as typeof globalThis & {
-	[CacheKey]?: Map<string | symbol, CachedClient>;
+const sharedCache: unknown = Reflect.get(globalThis, CacheKey);
+const clientCache: Map<string | symbol, unknown> = sharedCache instanceof Map ? sharedCache : new Map<string | symbol, unknown>();
+Reflect.set(globalThis, CacheKey, clientCache);
+
+const isCachedClient = (value: unknown): value is CachedClient =>
+	typeof value === "object"
+	&& value !== null
+	&& Reflect.get(value, "client") instanceof Promise
+	&& typeof Reflect.get(value, "references") === "number";
+
+const cachedClient = (key: string | symbol): CachedClient | undefined => {
+	const entry = clientCache.get(key);
+	return isCachedClient(entry) ? entry : undefined;
 };
-const clientCache =
-	globalCache[CacheKey] ?? new Map<string | symbol, CachedClient>();
-globalCache[CacheKey] = clientCache;
 
 export interface AcquireClientOptions {
-	readonly clientFactory?: PgBossClientFactory;
+	readonly clientCacheKey?: string | symbol | undefined;
+	readonly clientFactory?: PgBossClientFactory | undefined;
 	readonly constructor: ConstructorOptions;
-	readonly developmentCacheKey?: string | symbol;
 }
 
 export interface AcquiredClient {
-	readonly client: PgBossClient;
 	readonly cacheKey?: string | symbol;
+	readonly client: PgBossClient;
 	readonly reused: boolean;
 }
 
 const startClient = (options: AcquireClientOptions): Promise<PgBossClient> => {
-	const client = (options.clientFactory ?? defaultClientFactory)(
-		options.constructor,
-	);
+	const client = (options.clientFactory ?? defaultClientFactory)(options.constructor);
 	return client.start().then(
 		() => client,
 		async (error) => {
@@ -49,15 +51,11 @@ const startClient = (options: AcquireClientOptions): Promise<PgBossClient> => {
 	);
 };
 
-export const acquireClient = (
-	options: AcquireClientOptions,
-): Effect.Effect<AcquiredClient, import("../error.js").PgBossError> =>
+export const acquireClient = (options: AcquireClientOptions): Effect.Effect<AcquiredClient, import("#error.ts").PgBossError> =>
 	Effect.tryPromise({
+		catch: (error) => toPgBossError("start", error),
 		try: async () => {
-			const cacheKey =
-				process.env.NODE_ENV === "production"
-					? undefined
-					: options.developmentCacheKey;
+			const cacheKey = options.clientCacheKey;
 			if (cacheKey === undefined) {
 				return {
 					client: await startClient(options),
@@ -65,7 +63,7 @@ export const acquireClient = (
 				};
 			}
 
-			const existing = clientCache.get(cacheKey);
+			const existing = cachedClient(cacheKey);
 			if (existing !== undefined) {
 				existing.references += 1;
 				try {
@@ -92,30 +90,32 @@ export const acquireClient = (
 					reused: false,
 				};
 			} catch (error) {
-				if (clientCache.get(cacheKey) === entry) clientCache.delete(cacheKey);
+				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> =>
+export const releaseClient = (acquired: AcquiredClient, stopOptions?: StopOptions): Effect.Effect<void> =>
 	Effect.tryPromise({
+		catch: (error) => toPgBossError("stop", error),
 		try: async () => {
 			if (acquired.cacheKey === undefined) {
 				await acquired.client.stop(stopOptions);
 				return;
 			}
 
-			const entry = clientCache.get(acquired.cacheKey);
-			if (entry === undefined) return;
+			const entry = cachedClient(acquired.cacheKey);
+			if (entry === undefined) {
+				return;
+			}
 			entry.references -= 1;
-			if (entry.references > 0) return;
+			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

@@ -1,15 +1,9 @@
-import { Effect, Redacted, Schema } from "effect";
+import { type Context, 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";
+import { type JobRegistration, jobContext, type QueueWorker, type ScheduledWorker } from "#definition.ts";
+import { PgBossPayloadError, toPgBossError } from "#error.ts";
+import { deadLetterQueueName } from "#health.ts";
+import type { PgBossClient } from "./client.ts";
 
 const queueOptions = (options: Readonly<Record<string, unknown>>) => ({
 	retryBackoff: true,
@@ -17,11 +11,27 @@ const queueOptions = (options: Readonly<Record<string, unknown>>) => ({
 	...options,
 });
 
-const runQueueWorker = <R>(
-	worker: QueueWorker<JobPayloadSchema, R>,
-	job: Job<unknown>,
-	context: import("effect").Context.Context<R>,
-): Promise<unknown> =>
+const isQueueWorker = (registration: JobRegistration): registration is QueueWorker => registration._tag === "QueueWorker";
+
+const isScheduledWorker = (registration: JobRegistration): registration is ScheduledWorker => registration._tag === "ScheduledWorker";
+
+export const registrationName = (registration: JobRegistration): string => {
+	if (isQueueWorker(registration)) {
+		return registration.queue.name;
+	}
+	if (isScheduledWorker(registration)) {
+		return registration.schedule.name;
+	}
+	throw new TypeError(`Unknown pg-boss registration: ${registration._tag}`);
+};
+
+// The layer requires RegistrationRequirements of its jobs, so its context provides every registered worker.
+function workerContext<R>(context: Context.Context<R>): Context.Context<unknown>;
+function workerContext(context: unknown): unknown {
+	return context;
+}
+
+const runQueueWorker = (worker: QueueWorker, job: Job<unknown>, context: Context.Context<unknown>): Promise<unknown> =>
 	Effect.runPromise(
 		Schema.decodeUnknownEffect(worker.queue.schema)(job.data).pipe(
 			Effect.mapError(
@@ -34,70 +44,56 @@ const runQueueWorker = <R>(
 			),
 			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 registerQueue = async (client: PgBossClient, worker: QueueWorker, context: Context.Context<unknown>, replaceWorker: boolean): Promise<void> => {
 	const name = worker.queue.name;
 	const deadLetter = deadLetterQueueName(name);
-	if (replaceWorker) await client.offWork(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);
+		for (const job of jobs) {
+			await runQueueWorker(worker, job, context);
+		}
 	});
 };
 
-const registerSchedule = async <R>(
+const registerSchedule = async (
 	client: PgBossClient,
-	worker: ScheduledWorker<R>,
-	context: import("effect").Context.Context<R>,
+	worker: ScheduledWorker,
+	context: Context.Context<unknown>,
 	replaceWorker: boolean,
 ): Promise<void> => {
 	const { schedule } = worker;
 	const deadLetter = deadLetterQueueName(schedule.name);
-	if (replaceWorker) await client.offWork(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,
-	);
+	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,
-	);
+export const registrationNames = (registrations: readonly JobRegistration[]): readonly string[] => {
+	const names = registrations.map(registrationName);
 	if (new Set(names).size !== names.length) {
 		throw new TypeError("pg-boss job names must be unique");
 	}
@@ -107,29 +103,20 @@ export const registrationNames = (
 export const registerJobs = <R>(
 	client: PgBossClient,
 	registrations: readonly JobRegistration[],
-	context: import("effect").Context.Context<R>,
+	context: Context.Context<R>,
 	replaceWorkers: boolean,
-): Effect.Effect<void, import("../error.js").PgBossError> =>
+): Effect.Effect<void, import("#error.ts").PgBossError> =>
 	Effect.tryPromise({
+		catch: (error) => toPgBossError("register", error),
 		try: async () => {
 			registrationNames(registrations);
+			const provided = workerContext(context);
 			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,
-					);
+				if (isQueueWorker(registration)) {
+					await registerQueue(client, registration, provided, replaceWorkers);
+				} else if (isScheduledWorker(registration)) {
+					await registerSchedule(client, registration, provided, replaceWorkers);
 				}
 			}
 		},
-		catch: (error) => toPgBossError("register", error),
 	});

package/src/internal/service.ts

@@ -1,17 +1,10 @@
 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";
+import { type PgBossError, PgBossPayloadError, toPgBossError } from "#error.ts";
+import type { PgBossService } from "#service.ts";
+import type { PgBossClient } from "./client.ts";
+import { healthFor } from "./health.ts";
 
-export const makeService = (
-	client: PgBossClient,
-	names: readonly string[],
-): PgBossService => ({
+export const makeService = (client: PgBossClient, names: readonly string[]): PgBossService => ({
 	enqueue: (queue, payload, options) =>
 		Schema.encodeUnknownEffect(queue.schema)(payload).pipe(
 			Effect.mapError(
@@ -22,30 +15,21 @@ export const makeService = (
 						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));
-				},
-			),
+			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({
+					catch: (error) => toPgBossError("enqueue", error, queue.name),
+					try: () => client.send(queue.name, encoded, options),
+				}).pipe(Effect.map(Option.fromNullishOr));
+			}),
 		),
 	health: healthFor(client, names),
 });

package/src/service.ts

@@ -1,31 +1,19 @@
 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";
+import type { PgBossClientFactory } from "#internal/client.ts";
+import { acquireClient, releaseClient } from "#internal/lifecycle.ts";
+import { registerJobs, registrationName } from "#internal/register.ts";
+import { makeService } from "#internal/service.ts";
+import type { JobPayloadSchema, JobRegistration, QueueDefinition, RegistrationRequirements } from "./definition.ts";
+import type { PgBossError, PgBossPayloadError } from "./error.ts";
+import type { JobsHealth } from "./health.ts";
 
 export interface PgBossService {
-	readonly enqueue: <
-		const Name extends string,
-		const Payload extends JobPayloadSchema,
-	>(
+	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"]
-	>;
+	) => Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError, Payload["EncodingServices"]>;
 	readonly health: Effect.Effect<JobsHealth, PgBossError>;
 }
 
@@ -33,95 +21,47 @@ interface PgBossIdentifier {
 	readonly _pgBossIdentifier: unique symbol;
 }
 
-export type PgBossLayerOptions<
-	Registrations extends readonly JobRegistration[],
-	ErrorRequirements,
-> = ConstructorOptions & {
-	/** Override client construction for compatible clients or deterministic tests. */
+export type PgBossLayerOptions<Registrations extends readonly JobRegistration[], ErrorRequirements> = ConstructorOptions & {
 	readonly clientFactory?: PgBossClientFactory;
-	readonly developmentCacheKey?: string | symbol;
+	// One started client is reference-counted per key, so development module reloads reuse it instead of starting another.
+	readonly clientCacheKey?: string | symbol | undefined;
 	readonly jobs: Registrations;
-	readonly onError?: (
-		error: Error,
-	) => Effect.Effect<unknown, never, ErrorRequirements>;
+	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,
-	>(
+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
-	>;
+	) => Layer.Layer<PgBossIdentifier, PgBossError, RegistrationRequirements<Registrations> | ErrorRequirements>;
 }
 
+const logClientError = (error: Error): Effect.Effect<void> => Effect.logError({ event: "pg_boss_error", message: error.message });
+
 export const makePgBoss = (identifier: string): PgBossDefinition => {
 	const Service = Context.Service<PgBossIdentifier, PgBossService>(identifier);
 
-	const layer = <
-		const Registrations extends readonly JobRegistration[],
-		ErrorRequirements = never,
-	>(
+	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;
+	): Layer.Layer<PgBossIdentifier, PgBossError, RegistrationRequirements<Registrations> | ErrorRequirements> => {
+		type Requirements = RegistrationRequirements<Registrations> | ErrorRequirements;
+		const names = options.jobs.map(registrationName);
+		const { clientFactory, clientCacheKey, jobs, onError, stop, ...constructorOptions } = options;
 
 		const acquire = Effect.acquireRelease(
 			Effect.gen(function* () {
 				const context = yield* Effect.context<Requirements>();
 				const acquired = yield* acquireClient({
+					clientCacheKey,
 					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 reportError: (error: Error) => Effect.Effect<unknown, never, Requirements> = onError ?? logClientError;
 				const errorListener = (error: Error) => {
-					void Effect.runPromise(
-						Effect.exit(Effect.provide(reportError(error), context)),
-					);
+					void Effect.runPromise(Effect.exit(Effect.provide(reportError(error), context)));
 				};
 				acquired.client.on("error", errorListener);
-				const registration = registerJobs(
-					acquired.client,
-					jobs,
-					context,
-					acquired.reused,
-				);
+				const registration = registerJobs(acquired.client, jobs, context, acquired.reused);
 				return yield* registration.pipe(
 					Effect.as({ acquired, context, errorListener }),
 					Effect.onError(() => {
@@ -138,11 +78,9 @@ export const makePgBoss = (identifier: string): PgBossDefinition => {
 
 		return Layer.effect(
 			Service,
-			Effect.map(acquire, ({ acquired }) =>
-				makeService(acquired.client, names),
-			),
+			Effect.map(acquire, ({ acquired }) => makeService(acquired.client, names)),
 		);
 	};
 
-	return Object.assign(Service, { layer }) as PgBossDefinition;
+	return Object.assign(Service, { layer });
 };