@shivaedev/jobs 0.0.0 → 0.20.0

package/src/server/service.ts

@@ -0,0 +1,100 @@
+import { Context, Effect, Layer, type Option, type Schema } from "effect";
+import type { ConstructorOptions, JobWithMetadata, SendOptions, StopOptions } from "pg-boss";
+import type { PgBossClientFactory } from "#client.ts";
+import type { JobPayloadSchema, JobRegistration, QueueDefinition, RegistrationRequirements } from "#definition.ts";
+import type { PgBossClientOptionsError, PgBossError, PgBossPayloadError, PgBossQueueOptionsError } from "#error.ts";
+import type { DeadLetteredJob, JobPage, JobPageOptions, JobsHealth, ListedJob, QueueCounts } from "#health.ts";
+import { logClientError, subscribeClientErrors } from "#internal/clientErrors.ts";
+import { acquireClient, releaseClient } from "#internal/lifecycle.ts";
+import { makeService } from "#internal/makeService.ts";
+import { registrationName } from "#internal/register.ts";
+import { registerReleasedJobs } from "#internal/registerReleasedJobs.ts";
+
+export interface PgBossService {
+	readonly counts: (queue: Pick<QueueDefinition, "name">) => Effect.Effect<QueueCounts, PgBossError>;
+	readonly deadLetteredJobs: <const TName extends string, const TPayload extends JobPayloadSchema>(
+		queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">,
+		options: JobPageOptions,
+	) => Effect.Effect<JobPage<DeadLetteredJob<TPayload["Type"]>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
+	readonly enqueue: <const TName extends string, const TPayload extends JobPayloadSchema, const TQueue extends QueueDefinition<TName, TPayload>>(
+		queue: QueueDefinition<TName, TPayload> & TQueue,
+		payload: NoInfer<Schema.Schema.Type<TPayload>>,
+		options?: NoInfer<TQueue["key"] extends undefined ? SendOptions : Omit<SendOptions, "singletonKey"> & { readonly singletonKey?: never }>,
+	) => Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError, TPayload["EncodingServices"]>;
+	readonly failedJobs: <const TName extends string, const TPayload extends JobPayloadSchema>(
+		queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">,
+		options: JobPageOptions,
+	) => Effect.Effect<JobPage<ListedJob<TPayload["Type"]>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
+	readonly getJob: <const TName extends string, const TPayload extends JobPayloadSchema>(
+		queue: Pick<QueueDefinition<TName, TPayload>, "name" | "schema">,
+		id: string,
+	) => Effect.Effect<Option.Option<JobWithMetadata<TPayload["Type"]>>, PgBossError | PgBossPayloadError, TPayload["DecodingServices"]>;
+	readonly health: Effect.Effect<JobsHealth, PgBossError>;
+	readonly retry: (queue: Pick<QueueDefinition, "name">, id: string) => Effect.Effect<void, PgBossError>;
+}
+
+export type PgBossLayerOptions<TRegistrations extends readonly JobRegistration[], TErrorRequirements> = ConstructorOptions & {
+	readonly clientFactory?: PgBossClientFactory;
+	// 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: TRegistrations;
+	readonly onError?: (error: Error) => Effect.Effect<unknown, never, TErrorRequirements>;
+	readonly stop?: StopOptions;
+};
+
+export interface PgBossDefinition<TIdentifier extends string = string> extends Context.Service<TIdentifier, PgBossService> {
+	readonly layer: <const TRegistrations extends readonly JobRegistration[], TErrorRequirements = never>(
+		options: PgBossLayerOptions<TRegistrations, TErrorRequirements>,
+	) => Layer.Layer<
+		TIdentifier,
+		PgBossError | PgBossQueueOptionsError | PgBossClientOptionsError,
+		Exclude<RegistrationRequirements<TRegistrations>, TIdentifier> | TErrorRequirements
+	>;
+}
+
+export function makePgBoss<const TIdentifier extends string>(identifier: TIdentifier): PgBossDefinition<TIdentifier> {
+	const Service = Context.Service<TIdentifier, PgBossService>(identifier);
+
+	function layer<const TRegistrations extends readonly JobRegistration[], TErrorRequirements = never>(
+		options: PgBossLayerOptions<TRegistrations, TErrorRequirements>,
+	): Layer.Layer<
+		TIdentifier,
+		PgBossError | PgBossQueueOptionsError | PgBossClientOptionsError,
+		Exclude<RegistrationRequirements<TRegistrations>, TIdentifier> | TErrorRequirements
+	> {
+		type Requirements = Exclude<RegistrationRequirements<TRegistrations>, TIdentifier> | TErrorRequirements;
+		const names = options.jobs.map(registrationName);
+		const { clientFactory, clientCacheKey, jobs, onError, stop, ...constructorOptions } = options;
+
+		const acquire = Effect.acquireRelease(
+			Effect.gen(function* () {
+				const dependencies = yield* Effect.context<Requirements>();
+				const acquired = yield* acquireClient({
+					clientCacheKey,
+					clientFactory,
+					constructor: constructorOptions,
+				});
+				const service = makeService(acquired.client, names, constructorOptions.schema);
+				const context = Context.add(dependencies, Service, service);
+				const reportError: (error: Error) => Effect.Effect<unknown, never, Requirements | TIdentifier> = onError ?? logClientError;
+				function errorListener(error: Error): void {
+					void Effect.runPromise(Effect.exit(Effect.provide(reportError(error), context)));
+				}
+				const unsubscribe = subscribeClientErrors(acquired.client, errorListener);
+				const registration = registerReleasedJobs(acquired.client, jobs, context, acquired.reused, constructorOptions.schema);
+				return yield* registration.pipe(
+					Effect.as({ acquired, service, unsubscribe }),
+					Effect.onError(() => releaseClient(acquired, stop).pipe(Effect.ensuring(Effect.sync(unsubscribe)))),
+				);
+			}),
+			(resource) => releaseClient(resource.acquired, stop).pipe(Effect.ensuring(Effect.sync(resource.unsubscribe))),
+		);
+
+		return Layer.effect(
+			Service,
+			Effect.map(acquire, ({ service }) => service),
+		);
+	}
+
+	return Object.assign(Service, { layer });
+}

package/src/server/testing.ts

@@ -0,0 +1,118 @@
+import { type DateTime, Duration, Effect, Redacted } from "effect";
+import type { PgBoss } from "pg-boss";
+import type { PgBossClientFactory } from "#client.ts";
+import type { JobPayloadSchema, QueueDefinition } from "#definition.ts";
+import { PgBossTestingError } from "#error.ts";
+import { nativeClient } from "#internal/nativeClient.ts";
+import { testingClient } from "#internal/testingClient.ts";
+import { testingDeferrals } from "#internal/testingDeferrals.ts";
+import { type TestingWork, testingIdle } from "#internal/testingIdle.ts";
+import { testingOperation, testingReadout } from "#internal/testingReadout.ts";
+import { testingSignal } from "#internal/testingSignal.ts";
+import { testingSnapshot } from "#internal/testingSnapshot.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" | "failed" | "retry";
+}
+
+export const testRetryPolicy = Object.freeze({ retryBackoff: false, retryDelay: 0 });
+
+export interface PgBossTestingOptions {
+	readonly retryPolicy?: typeof testRetryPolicy;
+}
+
+export function makePgBossTesting(options: PgBossTestingOptions = {}) {
+	let current: PgBoss | undefined;
+	let schema = "pgboss";
+	const signal = testingSignal();
+	const work: TestingWork = { batches: new Set(), queues: new Set() };
+	const controls = {
+		changed: signal.changed,
+		expirations: new Map<string, number>(),
+		expirySeconds: new Map<string, number>(),
+		failures: new Set<string>(),
+		retryPolicy: options.retryPolicy ?? {},
+		work,
+	};
+	function client(): PgBoss {
+		if (current === undefined) {
+			throw new Error("Provide the testing clientFactory to a jobs Layer first");
+		}
+		return current;
+	}
+	const clientFactory: PgBossClientFactory = (clientOptions) => {
+		if (current !== undefined) {
+			throw new Error("A testing controller owns one jobs client; create a controller per runtime");
+		}
+		schema = clientOptions.schema ?? "pgboss";
+		current = nativeClient({ ...clientOptions, "__test__enableSpies": true });
+		return testingClient(current, clientOptions.schema ?? "pgboss", controls);
+	};
+	return {
+		...testingDeferrals(client, () => schema, signal.changed),
+		checkBatchWindow: (queue: Pick<QueueDefinition, "name" | "workerOptions">, millisecondsPerJob: number) =>
+			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: number) =>
+			testingOperation("checkSchemaVersion", async () => {
+				if ((await client().schemaVersion()) !== expected) {
+					throw new Error(`Expected pg-boss schema version ${expected}`);
+				}
+			}),
+		clientFactory,
+		expireAfter: (queue: Pick<QueueDefinition, "name">, attempts: number) =>
+			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: Pick<QueueDefinition, "name">, duration: Duration.Input) =>
+			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: Pick<QueueDefinition, "name">) => 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),
+	};
+}
+
+export type PgBossTesting = ReturnType<typeof makePgBossTesting>;