@falcondev-oss/workflow 0.1.2 → 0.3.0

package/dist/index.d.mts

@@ -1,10 +1,11 @@
 import { ConnectionOptions, Job, JobsOptions, Queue, QueueEvents, QueueEventsOptions, QueueOptions, UnrecoverableError, WorkerOptions } from "bullmq";
 import "@antfu/utils";
 import IORedis from "ioredis";
+import { Span } from "@opentelemetry/api";
 import { SuperJSONResult } from "superjson";
 import { Options } from "p-retry";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-import { SetOptional, Tagged } from "type-fest";
+import { Except, IsUnknown, SetOptional, Tagged } from "type-fest";
 
 //#region src/errors.d.ts
 declare class WorkflowInputError extends UnrecoverableError {
@@ -16,6 +17,7 @@ declare class WorkflowInputError extends UnrecoverableError {
 declare const Settings: {
   defaultPrefix: string;
   defaultConnection: IORedis | undefined;
+  defaultCronTimezone: string | undefined;
 };
 //#endregion
 //#region src/serializer.d.ts
@@ -35,14 +37,20 @@ declare class WorkflowStep {
   private workflowId;
   private queue;
   private workflowJobId;
+  private stepNamePrefix;
   constructor(opts: {
     queue: WorkflowQueueInternal<any, any>;
     workflowJobId: string;
     workflowId: string;
+    stepNamePrefix?: string;
   });
-  do<R>(name: string, run: () => R, options?: WorkflowStepOptions): Promise<R>;
-  wait(name: string, durationMs: number): Promise<void>;
-  waitUntil(name: string, date: Date): Promise<void>;
+  private addNamePrefix;
+  do<R>(stepName: string, run: (ctx: {
+    step: WorkflowStep;
+    span: Span;
+  }) => R, options?: WorkflowStepOptions): Promise<R>;
+  wait(stepName: string, durationMs: number): Promise<void>;
+  waitUntil(stepName: string, date: Date): Promise<void>;
   private getStepData;
   private updateStepData;
   private getWorkflowJob;
@@ -55,6 +63,7 @@ interface WorkflowStepOptions {
 type WorkflowJobInternal<Input, Output> = Job<Serialized<{
   input: Input;
   stepData: Record<string, WorkflowStepData>;
+  tracingHeaders: unknown;
 }>, Serialized<Output>, string>;
 type WorkflowQueueInternal<Input, Output> = Queue<WorkflowJobInternal<Input, Output>>;
 //#endregion
@@ -72,8 +81,8 @@ declare class WorkflowJob<Output> {
 //#region src/workflow.d.ts
 interface WorkflowOptions<RunInput, Input, Output> {
   id: string;
-  input: StandardSchemaV1<RunInput, Input>;
-  run: (context: WorkflowRunContext<Input>) => Promise<Output>;
+  schema?: StandardSchemaV1<RunInput, Input>;
+  run: (ctx: WorkflowRunContext<Input>) => Promise<Output>;
   queueOptions?: SetOptional<QueueOptions, 'connection'>;
   queueEventsOptions?: SetOptional<QueueEventsOptions, 'connection'>;
   connection?: ConnectionOptions;
@@ -85,12 +94,16 @@ declare class Workflow<RunInput, Input, Output> {
   constructor(opts: WorkflowOptions<RunInput, Input, Output>);
   work(opts?: Omit<SetOptional<WorkerOptions, 'connection'>, 'autorun'>): Promise<this>;
   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 getOrCreateQueue;
   private getOrCreateQueueEvents;
 }
 interface WorkflowRunContext<Input> {
-  input: Input;
+  input: IsUnknown<Input> extends true ? undefined : Input;
   step: WorkflowStep;
+  span: Span;
 }
 //#endregion
 export { Settings, Workflow, WorkflowInputError, WorkflowOptions, WorkflowRunContext };

package/dist/index.mjs

@@ -1,10 +1,10 @@
 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 { deserialize, serialize } from "superjson";
 import { setTimeout } from "node:timers/promises";
 import pRetry from "p-retry";
-import { SpanStatusCode, trace } from "@opentelemetry/api";
 
 //#region src/errors.ts
 var WorkflowInputError = class extends UnrecoverableError {
@@ -19,7 +19,8 @@ var WorkflowInputError = class extends UnrecoverableError {
 //#region src/settings.ts
 const Settings = {
 	defaultPrefix: "falcondev-oss-workflow",
-	defaultConnection: void 0
+	defaultConnection: void 0,
+	defaultCronTimezone: void 0
 };
 const defaultRedisConnection = createSingletonPromise(async () => {
 	if (Settings.defaultConnection) return Settings.defaultConnection;
@@ -59,53 +60,65 @@ var WorkflowJob = class {
 function getTracer() {
 	return trace.getTracer("falcondev-oss-workflow");
 }
-async function runWithTracing(spanName, attributes, fn) {
-	return getTracer().startActiveSpan(spanName, async (span) => {
-		try {
-			span.setAttributes(attributes);
-			const result = await fn();
-			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();
-		}
-	});
+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();
+	}
 }
 
 //#endregion
 //#region src/step.ts
-var WorkflowStep = class {
+var WorkflowStep = class WorkflowStep {
 	workflowId;
 	queue;
 	workflowJobId;
+	stepNamePrefix;
 	constructor(opts) {
 		this.queue = opts.queue;
 		this.workflowJobId = opts.workflowJobId;
 		this.workflowId = opts.workflowId;
+		this.stepNamePrefix = opts.stepNamePrefix ? `${opts.stepNamePrefix}|` : "";
 	}
-	async do(name, run, options) {
-		const stepData = await this.getStepData("do", "name");
-		if (stepData && "result" in stepData) return stepData.result;
+	addNamePrefix(name) {
+		return `${this.stepNamePrefix}${name}`;
+	}
+	async do(stepName, run, options) {
+		const name = this.addNamePrefix(stepName);
+		const stepData = await this.getStepData("do", name);
+		if (stepData?.result) return stepData.result;
 		const initialAttempt = stepData?.attempt ?? 0;
 		await this.updateStepData(name, {
 			type: "do",
 			attempt: initialAttempt
 		});
 		return pRetry(async (attempt) => {
-			const result = await runWithTracing(`step:${name}`, {
+			const result = await runWithTracing(`step:${name}`, { attributes: {
 				"workflow.id": this.workflowId,
 				"workflow.job_id": this.workflowJobId,
 				"workflow.step_name": name,
 				"workflow.step.attempt": attempt
-			}, run);
+			} }, async (span) => run({
+				step: new WorkflowStep({
+					queue: this.queue,
+					workflowId: this.workflowId,
+					workflowJobId: this.workflowJobId,
+					stepNamePrefix: name
+				}),
+				span
+			}));
 			await this.updateStepData(name, {
 				type: "do",
 				result,
@@ -115,16 +128,17 @@ var WorkflowStep = class {
 		}, {
 			...options?.retry,
 			retries: (options?.retry?.retries ?? 0) - initialAttempt,
-			onFailedAttempt: async (context) => {
+			onFailedAttempt: async (ctx) => {
 				await this.updateStepData(name, {
 					type: "do",
-					attempt: initialAttempt + context.attemptNumber
+					attempt: initialAttempt + ctx.attemptNumber
 				});
-				return options?.retry?.onFailedAttempt?.(context);
+				return options?.retry?.onFailedAttempt?.(ctx);
 			}
 		});
 	}
-	async wait(name, durationMs) {
+	async wait(stepName, durationMs) {
+		const name = this.addNamePrefix(stepName);
 		const job = await this.getWorkflowJob();
 		const existingStepData = await this.getStepData("wait", name);
 		const now = Date.now();
@@ -134,11 +148,11 @@ var WorkflowStep = class {
 			startedAt: now
 		};
 		await this.updateStepData(name, stepData);
-		await runWithTracing(`step:${name}`, {
+		await runWithTracing(`step:${name}`, { attributes: {
 			"workflow.id": this.workflowId,
 			"workflow.job_id": this.workflowJobId,
 			"workflow.step_name": name
-		}, async () => {
+		} }, async () => {
 			const remainingMs = Math.max(0, stepData.startedAt + stepData.durationMs - now);
 			const interval = setInterval(() => {
 				job.updateProgress(name);
@@ -147,11 +161,11 @@ var WorkflowStep = class {
 			clearInterval(interval);
 		});
 	}
-	async waitUntil(name, date) {
+	async waitUntil(stepName, date) {
 		const now = Date.now();
 		const targetTime = date.getTime();
 		const durationMs = Math.max(0, targetTime - now);
-		return this.wait(name, durationMs);
+		return this.wait(stepName, durationMs);
 	}
 	async getStepData(type, stepName) {
 		const stepData = deserialize$1((await this.getWorkflowJob()).data).stepData[stepName];
@@ -186,21 +200,25 @@ var Workflow = class {
 			const jobId = job.id;
 			if (!jobId) throw new Error("Job ID is missing");
 			const deserializedData = deserialize$1(job.data);
-			const parsedData = await this.opts.input["~standard"].validate(deserializedData.input);
-			if (parsedData.issues) throw new WorkflowInputError("Invalid workflow input", parsedData.issues);
-			return runWithTracing(`workflow:${this.opts.id}`, {
-				"workflow.id": this.opts.id,
-				"workflow.job_id": jobId
-			}, async () => {
+			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}`, {
+				attributes: {
+					"workflow.id": this.opts.id,
+					"workflow.job_id": jobId
+				},
+				kind: SpanKind.CONSUMER
+			}, async (span) => {
 				return serialize$1(await this.opts.run({
-					input: parsedData.value,
+					input: parsedData?.value,
 					step: new WorkflowStep({
 						queue,
 						workflowJobId: jobId,
 						workflowId: this.opts.id
-					})
+					}),
+					span
 				}));
-			});
+			}, propagation.extract(ROOT_CONTEXT, deserializedData.tracingHeaders));
 		}, {
 			connection: this.opts.connection ?? await defaultRedisConnection(),
 			prefix: Settings.defaultPrefix,
@@ -209,14 +227,42 @@ var Workflow = class {
 		return this;
 	}
 	async run(input, opts) {
-		const parsedInput = await this.opts.input["~standard"].validate(input);
-		if (parsedInput.issues) throw new WorkflowInputError("Invalid workflow input", parsedInput.issues);
-		return new WorkflowJob({
-			job: await (await this.getOrCreateQueue()).add("workflow-job", serialize$1({
-				input: parsedInput.value,
-				stepData: {}
-			}), opts),
-			queueEvents: await this.getOrCreateQueueEvents()
+		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}`, {
+			attributes: { "workflow.id": this.opts.id },
+			kind: SpanKind.PRODUCER
+		}, async () => {
+			const tracingHeaders = {};
+			propagation.inject(context.active(), tracingHeaders);
+			return new WorkflowJob({
+				job: await queue.add("workflow-job", serialize$1({
+					input: parsedInput?.value,
+					stepData: {},
+					tracingHeaders
+				}), opts),
+				queueEvents: await this.getOrCreateQueueEvents()
+			});
+		});
+	}
+	async runIn(input, delayMs, opts) {
+		return this.run(input, {
+			delay: delayMs,
+			...opts
+		});
+	}
+	async runAt(input, date, opts) {
+		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 getOrCreateQueue() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falcondev-oss/workflow",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Simple type-safe queue worker with durable execution based on BullMQ.",
   "license": "MIT",
   "repository": "github:falcondev-oss/workflow",