@falcondev-oss/workflow 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ConnectionOptions, Job, JobsOptions, Queue, QueueEvents, QueueEventsOptions, QueueOptions, UnrecoverableError, WorkerOptions } from "bullmq";
+import { ConnectionOptions, Job, JobSchedulerTemplateOptions, JobsOptions, Queue, QueueEvents, QueueEventsOptions, QueueOptions, UnrecoverableError, WorkerOptions } from "bullmq";
 import "@antfu/utils";
 import IORedis from "ioredis";
 import { Span } from "@opentelemetry/api";
@@ -14,10 +14,15 @@ declare class WorkflowInputError extends UnrecoverableError {
 }
 //#endregion
 //#region src/settings.d.ts
+type WorkflowLogger = {
+  info?: (...data: any[]) => void;
+  success?: (...data: any[]) => void;
+};
 declare const Settings: {
   defaultPrefix: string;
-  defaultConnection: IORedis | undefined;
+  defaultConnection: (() => Promise<IORedis> | IORedis) | undefined;
   defaultCronTimezone: string | undefined;
+  logger: WorkflowLogger | undefined;
 };
 //#endregion
 //#region src/serializer.d.ts
@@ -61,7 +66,7 @@ interface WorkflowStepOptions {
 //#endregion
 //#region src/types.d.ts
 type WorkflowJobInternal<Input, Output> = Job<Serialized<{
-  input: Input;
+  input: Input | undefined;
   stepData: Record<string, WorkflowStepData>;
   tracingHeaders: unknown;
 }>, Serialized<Output>, string>;
@@ -97,7 +102,10 @@ declare class Workflow<RunInput, Input, Output> {
   run(input: RunInput, opts?: JobsOptions): Promise<WorkflowJob<Output>>;
   runIn(input: RunInput, delayMs: number, opts?: Except<JobsOptions, 'delay'>): Promise<WorkflowJob<Output>>;
   runAt(input: RunInput, date: Date, opts?: Except<JobsOptions, 'delay'>): Promise<WorkflowJob<Output>>;
-  repeat(input: RunInput, cronOrInterval: string | number, opts?: Except<JobsOptions, 'repeat'>): Promise<WorkflowJob<Output>>;
+  private runSchedule;
+  runCron(schedulerId: string, cron: string, input: RunInput, opts?: JobSchedulerTemplateOptions): Promise<void>;
+  runEvery(schedulerId: string, everyMs: number, input: RunInput, opts?: JobSchedulerTemplateOptions): Promise<void>;
+  exportPrometheusMetrics(globalVariables?: Record<string, string>): Promise<string>;
   private getOrCreateQueue;
   private getOrCreateQueueEvents;
 }

package/dist/index.mjs

@@ -2,6 +2,7 @@ import { Queue, QueueEvents, UnrecoverableError, Worker } from "bullmq";
 import { createSingletonPromise } from "@antfu/utils";
 import IORedis from "ioredis";
 import { ROOT_CONTEXT, SpanKind, SpanStatusCode, context, propagation, trace } from "@opentelemetry/api";
+import { asyncExitHook } from "exit-hook";
 import { deserialize, serialize } from "superjson";
 import { setTimeout } from "node:timers/promises";
 import pRetry from "p-retry";
@@ -20,14 +21,18 @@ var WorkflowInputError = class extends UnrecoverableError {
 const Settings = {
 	defaultPrefix: "falcondev-oss-workflow",
 	defaultConnection: void 0,
-	defaultCronTimezone: void 0
+	defaultCronTimezone: void 0,
+	logger: void 0
+};
+const defaultRedisOptions = {
+	lazyConnect: true,
+	maxRetriesPerRequest: null,
+	retryStrategy: (times) => Math.max(Math.min(Math.exp(times), 2e4), 1e3),
+	enableOfflineQueue: false
 };
 const defaultRedisConnection = createSingletonPromise(async () => {
-	if (Settings.defaultConnection) return Settings.defaultConnection;
-	const redis = new IORedis({
-		lazyConnect: true,
-		maxRetriesPerRequest: null
-	});
+	if (Settings.defaultConnection) return Settings.defaultConnection();
+	const redis = new IORedis(defaultRedisOptions);
 	await redis.connect();
 	return redis;
 });
@@ -61,22 +66,26 @@ function getTracer() {
 	return trace.getTracer("falcondev-oss-workflow");
 }
 async function runWithTracing(spanName, options, fn, context$1) {
-	const span = getTracer().startSpan(spanName, options, context$1);
-	try {
-		const result = await fn(span);
-		span.setStatus({ code: SpanStatusCode.OK });
-		return result;
-	} catch (err_) {
-		const err = err_;
-		span.recordException(err);
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: err.message
-		});
-		throw err_;
-	} finally {
-		span.end();
-	}
+	return context$1 ? getTracer().startActiveSpan(spanName, options, context$1, runWithSpan(fn)) : getTracer().startActiveSpan(spanName, options, runWithSpan(fn));
+}
+function runWithSpan(fn) {
+	return async (span) => {
+		try {
+			const result = await fn(span);
+			span.setStatus({ code: SpanStatusCode.OK });
+			return result;
+		} catch (err_) {
+			const err = err_;
+			span.recordException(err);
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: err.message
+			});
+			throw err_;
+		} finally {
+			span.end();
+		}
+	};
 }
 
 //#endregion
@@ -105,7 +114,7 @@ var WorkflowStep = class WorkflowStep {
 			attempt: initialAttempt
 		});
 		return pRetry(async (attempt) => {
-			const result = await runWithTracing(`step:${name}`, { attributes: {
+			const result = await runWithTracing(`workflow-worker/${this.workflowId}/step/${name}`, { attributes: {
 				"workflow.id": this.workflowId,
 				"workflow.job_id": this.workflowJobId,
 				"workflow.step_name": name,
@@ -148,7 +157,7 @@ var WorkflowStep = class WorkflowStep {
 			startedAt: now
 		};
 		await this.updateStepData(name, stepData);
-		await runWithTracing(`step:${name}`, { attributes: {
+		await runWithTracing(`workflow-worker/${this.workflowId}/step/${name}`, { attributes: {
 			"workflow.id": this.workflowId,
 			"workflow.job_id": this.workflowJobId,
 			"workflow.step_name": name
@@ -198,20 +207,22 @@ var Workflow = class {
 	}
 	async work(opts) {
 		const queue = await this.getOrCreateQueue();
-		await new Worker(this.opts.id, async (job) => {
+		const worker = new Worker(this.opts.id, async (job) => {
+			Settings.logger?.info?.(`Processing workflow job ${job.id} of workflow ${this.opts.id}`);
 			const jobId = job.id;
 			if (!jobId) throw new Error("Job ID is missing");
 			const deserializedData = deserialize$1(job.data);
 			const parsedData = this.opts.schema && await this.opts.schema["~standard"].validate(deserializedData.input);
 			if (parsedData?.issues) throw new WorkflowInputError("Invalid workflow input", parsedData.issues);
-			return runWithTracing(`workflow:work:${this.opts.id}`, {
+			return runWithTracing(`workflow-worker/${this.opts.id}`, {
 				attributes: {
 					"workflow.id": this.opts.id,
 					"workflow.job_id": jobId
 				},
 				kind: SpanKind.CONSUMER
 			}, async (span) => {
-				return serialize$1(await this.opts.run({
+				const start = performance.now();
+				const result = await this.opts.run({
 					input: parsedData?.value,
 					step: new WorkflowStep({
 						queue,
@@ -219,20 +230,29 @@ var Workflow = class {
 						workflowId: this.opts.id
 					}),
 					span
-				}));
+				});
+				const end = performance.now();
+				Settings.logger?.success?.(`Completed workflow job ${job.id} of workflow ${this.opts.id} in ${(end - start).toFixed(2)} ms`);
+				return serialize$1(result);
 			}, propagation.extract(ROOT_CONTEXT, deserializedData.tracingHeaders));
 		}, {
 			connection: this.opts.connection ?? await defaultRedisConnection(),
 			prefix: Settings.defaultPrefix,
 			...opts
-		}).waitUntilReady();
+		});
+		await worker.waitUntilReady();
+		Settings.logger?.info?.(`Worker started for workflow ${this.opts.id}`);
+		asyncExitHook(async (signal) => {
+			Settings.logger?.info?.(`Received ${signal}, shutting down worker for workflow ${this.opts.id}...`);
+			await worker.close();
+		}, { wait: 1e4 });
 		return this;
 	}
 	async run(input, opts) {
 		const parsedInput = this.opts.schema && await this.opts.schema["~standard"].validate(input);
 		if (parsedInput?.issues) throw new WorkflowInputError("Invalid workflow input", parsedInput.issues);
 		const queue = await this.getOrCreateQueue();
-		return runWithTracing(`workflow:run:${this.opts.id}`, {
+		return runWithTracing(`workflow-producer/${this.opts.id}`, {
 			attributes: { "workflow.id": this.opts.id },
 			kind: SpanKind.PRODUCER
 		}, async () => {
@@ -258,19 +278,41 @@ var Workflow = class {
 		const now = Date.now();
 		return date.getTime() < now ? this.run(input, opts) : this.runIn(input, date.getTime() - Date.now(), opts);
 	}
-	async repeat(input, cronOrInterval, opts) {
-		return this.run(input, {
-			repeat: {
-				tz: Settings.defaultCronTimezone,
-				...typeof cronOrInterval === "string" ? { pattern: cronOrInterval } : { every: cronOrInterval }
-			},
-			...opts
+	async runSchedule(schedulerId, repeatOpts, input, opts) {
+		const parsedInput = this.opts.schema && await this.opts.schema["~standard"].validate(input);
+		if (parsedInput?.issues) throw new WorkflowInputError("Invalid workflow input", parsedInput.issues);
+		await (await this.getOrCreateQueue()).upsertJobScheduler(schedulerId, repeatOpts, {
+			name: "workflow-job",
+			data: serialize$1({
+				input: parsedInput?.value,
+				stepData: {},
+				tracingHeaders: {}
+			}),
+			opts
+		});
+	}
+	async runCron(schedulerId, cron, input, opts) {
+		return this.runSchedule(schedulerId, { pattern: cron }, input, opts);
+	}
+	async runEvery(schedulerId, everyMs, input, opts) {
+		return this.runSchedule(schedulerId, { every: everyMs }, input, opts);
+	}
+	async exportPrometheusMetrics(globalVariables) {
+		return (await this.getOrCreateQueue()).exportPrometheusMetrics({
+			workflowId: this.id,
+			workflowPrefix: Settings.defaultPrefix,
+			...globalVariables
 		});
 	}
 	async getOrCreateQueue() {
 		if (!this.queue) this.queue = new Queue(this.opts.id, {
 			prefix: Settings.defaultPrefix,
 			connection: this.opts.connection ?? await defaultRedisConnection(),
+			defaultJobOptions: {
+				removeOnComplete: true,
+				removeOnFail: { age: 1440 * 60 },
+				...this.opts.queueOptions?.defaultJobOptions
+			},
 			...this.opts.queueOptions
 		});
 		await this.queue.waitUntilReady();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falcondev-oss/workflow",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Simple type-safe queue worker with durable execution based on BullMQ.",
   "license": "MIT",
   "repository": "github:falcondev-oss/workflow",
@@ -39,6 +39,7 @@
     "@standard-schema/spec": "^1.1.0",
     "@types/node": "^25.0.3",
     "bullmq": "^5.66.4",
+    "exit-hook": "^5.0.1",
     "ioredis": "^5.8.2",
     "p-retry": "^7.1.1",
     "superjson": "^2.2.6",