pg-workflows 0.13.2 → 0.14.0

package/dist/index.cjs

@@ -97,7 +97,7 @@ var isInvokeChildWorkflowTimelineEntry = (entry) => !!entry && typeof entry ===
 
 // src/db/migration.ts
 var MIGRATION_LOCK_ID = 738291645;
-var CURRENT_SCHEMA_VERSION = 5;
+var CURRENT_SCHEMA_VERSION = 6;
 async function runMigrations(db) {
   if (await isSchemaUpToDate(db)) {
     return;
@@ -173,6 +173,9 @@ async function runMigrations(db) {
   if (currentVersion < 5) {
     commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS scheduled_at timestamp with time zone");
   }
+  if (currentVersion < 6) {
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS priority integer DEFAULT 0 NOT NULL");
+  }
   if (currentVersion === 0) {
     commands.push(`INSERT INTO workflow_schema_version (version) VALUES (${CURRENT_SCHEMA_VERSION})`);
   } else {
@@ -234,6 +237,7 @@ function mapRowToWorkflowRun(row) {
     timeoutAt: row.timeout_at ? new Date(row.timeout_at) : null,
     retryCount: row.retry_count,
     maxRetries: row.max_retries,
+    priority: row.priority,
     jobId: row.job_id,
     idempotencyKey: row.idempotency_key,
     parentRunId: row.parent_run_id,
@@ -249,6 +253,7 @@ async function insertWorkflowRun({
   status,
   input,
   maxRetries,
+  priority,
   timeoutAt,
   idempotencyKey,
   parentRunId,
@@ -266,6 +271,7 @@ async function insertWorkflowRun({
       status,
       input,
       max_retries,
+      priority,
       timeout_at,
       created_at,
       updated_at,
@@ -277,7 +283,7 @@ async function insertWorkflowRun({
       parent_resource_id,
       scheduled_at
     )
-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18)
     ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
     RETURNING *`, [
     runId,
@@ -287,6 +293,7 @@ async function insertWorkflowRun({
     status,
     JSON.stringify(input),
     maxRetries,
+    priority,
     timeoutAt,
     now,
     now,
@@ -566,6 +573,30 @@ class WorkflowRunNotFoundError extends WorkflowEngineError {
   }
 }
 
+// src/priority.ts
+var PRIORITY_LEVELS = { high: 100, normal: 0, low: -100 };
+function priorityToInt(value) {
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) {
+      throw new WorkflowEngineError(`Invalid priority ${value}: numeric priority must be an integer.`);
+    }
+    return value;
+  }
+  const mapped = PRIORITY_LEVELS[value];
+  if (mapped === undefined) {
+    throw new WorkflowEngineError(`Invalid priority "${value}": expected one of ${Object.keys(PRIORITY_LEVELS).map((k) => `"${k}"`).join(", ")} or an integer.`);
+  }
+  return mapped;
+}
+function resolvePriority(...candidates) {
+  for (const candidate of candidates) {
+    if (candidate !== undefined) {
+      return priorityToInt(candidate);
+    }
+  }
+  return PRIORITY_LEVELS.normal;
+}
+
 // src/types.ts
 var WorkflowStatus;
 ((WorkflowStatus2) => {
@@ -681,6 +712,7 @@ class WorkflowClient {
         status: "running" /* RUNNING */,
         input,
         maxRetries: options?.retries ?? 0,
+        priority: resolvePriority(options?.priority),
         timeoutAt,
         idempotencyKey
       }, _db);
@@ -694,6 +726,7 @@ class WorkflowClient {
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: new Date,
           expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+          priority: insertedRun.priority,
           db: _db
         });
       }
@@ -722,7 +755,8 @@ class WorkflowClient {
       }
     };
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
-      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds
+      expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+      priority: run.priority
     });
     this.logger.log(`${LOG_PREFIX} Event ${eventName} sent for workflow run ${runId}`);
     return run;
@@ -901,6 +935,7 @@ function createWorkflowRef(id, options) {
     inputSchema: options?.inputSchema,
     timeout: defineOptions?.timeout,
     retries: defineOptions?.retries,
+    priority: defineOptions?.priority,
     schedule: defineOptions?.schedule,
     timezone: defineOptions?.timezone
   });
@@ -912,12 +947,13 @@ function createWorkflowRef(id, options) {
   return ref;
 }
 function createWorkflowFactory(plugins = []) {
-  const factory = (id, handler, { inputSchema, timeout, retries, schedule, timezone } = {}) => ({
+  const factory = (id, handler, { inputSchema, timeout, retries, priority, schedule, timezone } = {}) => ({
     id,
     handler,
     inputSchema,
     timeout,
     retries,
+    priority,
     schedule,
     timezone,
     plugins: plugins.length > 0 ? plugins : undefined
@@ -1300,6 +1336,7 @@ class WorkflowEngine {
     parentRunId,
     parentStepId,
     parentResourceId,
+    parentPriority,
     scheduledAt,
     enqueue = true,
     db
@@ -1330,6 +1367,7 @@ class WorkflowEngine {
       status: "running" /* RUNNING */,
       input,
       maxRetries: options?.retries ?? workflow2.retries ?? 0,
+      priority: resolvePriority(options?.priority, workflow2.priority, parentPriority),
       timeoutAt,
       idempotencyKey,
       parentRunId,
@@ -1357,6 +1395,7 @@ class WorkflowEngine {
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
       startAfter: new Date,
       expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds2,
+      priority: run.priority,
       ...retrySendOptions(run.maxRetries),
       ...db ? { db } : {}
     });
@@ -1506,6 +1545,7 @@ class WorkflowEngine {
     };
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
       expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds2,
+      priority: run.priority,
       ...retrySendOptions(run.maxRetries)
     });
     this.logger.log(`event ${eventName} sent for workflow run with id ${runId}`);
@@ -1915,6 +1955,7 @@ class WorkflowEngine {
         parentRunId: run.id,
         parentStepId: stepId,
         parentResourceId: run.resourceId ?? undefined,
+        parentPriority: run.priority,
         enqueue: true,
         db
       });
@@ -2113,6 +2154,7 @@ ${error.stack}` : String(error)
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: timeoutDate.getTime() <= Date.now() ? new Date : timeoutDate,
           expireInSeconds: defaultExpireInSeconds2,
+          priority: run.priority,
           ...retrySendOptions(run.maxRetries)
         });
       } catch (error) {
@@ -2231,6 +2273,7 @@ ${error.stack}` : String(error)
       }, {
         startAfter: new Date(Date.now() + intervalMs),
         expireInSeconds: defaultExpireInSeconds2,
+        priority: run.priority,
         ...retrySendOptions(run.maxRetries)
       });
     } catch (error) {
@@ -2458,5 +2501,5 @@ function otelPlugin(options = {}) {
   };
 }
 
-//# debugId=EB0357F84B3B4EF764756E2164756E21
+//# debugId=5FA47CDFF028114064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.d.cts

@@ -18,6 +18,8 @@ type WorkflowRun = {
 	timeoutAt: Date | null;
 	retryCount: number;
 	maxRetries: number;
+	/** Resolved scheduling priority (pg-boss integer; higher runs first). */
+	priority: number;
 	jobId: string | null;
 	idempotencyKey: string | null;
 	parentRunId: string | null;
@@ -35,6 +37,18 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
+/**
+* Named priority levels mapped to pg-boss integer priorities. Higher numbers
+* are fetched first (pg-boss orders by `priority DESC`), and `normal = 0`
+* matches pg-boss's own default. The ±100 spacing leaves room for numeric
+* tuning between tiers via the escape hatch.
+*/
+declare const PRIORITY_LEVELS: {
+	readonly high: 100;
+	readonly normal: 0;
+	readonly low: -100;
+};
+type WorkflowPriority = keyof typeof PRIORITY_LEVELS | number;
 type Schedule = string | Exclude<Duration, string>;
 declare enum WorkflowStatus {
 	PENDING = "pending",
@@ -61,11 +75,13 @@ type StartWorkflowOptions = {
 	retries?: number;
 	expireInSeconds?: number;
 	idempotencyKey?: string;
+	priority?: WorkflowPriority;
 };
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
+	priority?: WorkflowPriority;
 	/**
 	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
 	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
@@ -173,6 +189,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	priority?: WorkflowPriority;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -504,4 +521,4 @@ type OtelPluginOptions = {
 	attributes?: (context: WorkflowContext) => Record<string, AttributeValue>;
 };
 declare function otelPlugin(options?: OtelPluginOptions): WorkflowPlugin<StepBaseContext, object>;
-export { workflow, otelPlugin, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };
+export { workflow, otelPlugin, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPriority, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };

package/dist/index.d.ts

@@ -18,6 +18,8 @@ type WorkflowRun = {
 	timeoutAt: Date | null;
 	retryCount: number;
 	maxRetries: number;
+	/** Resolved scheduling priority (pg-boss integer; higher runs first). */
+	priority: number;
 	jobId: string | null;
 	idempotencyKey: string | null;
 	parentRunId: string | null;
@@ -35,6 +37,18 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
+/**
+* Named priority levels mapped to pg-boss integer priorities. Higher numbers
+* are fetched first (pg-boss orders by `priority DESC`), and `normal = 0`
+* matches pg-boss's own default. The ±100 spacing leaves room for numeric
+* tuning between tiers via the escape hatch.
+*/
+declare const PRIORITY_LEVELS: {
+	readonly high: 100;
+	readonly normal: 0;
+	readonly low: -100;
+};
+type WorkflowPriority = keyof typeof PRIORITY_LEVELS | number;
 type Schedule = string | Exclude<Duration, string>;
 declare enum WorkflowStatus {
 	PENDING = "pending",
@@ -61,11 +75,13 @@ type StartWorkflowOptions = {
 	retries?: number;
 	expireInSeconds?: number;
 	idempotencyKey?: string;
+	priority?: WorkflowPriority;
 };
 type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
+	priority?: WorkflowPriority;
 	/**
 	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
 	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
@@ -173,6 +189,7 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	priority?: WorkflowPriority;
 	schedule?: Schedule;
 	timezone?: string;
 	plugins?: WorkflowPlugin[];
@@ -504,4 +521,4 @@ type OtelPluginOptions = {
 	attributes?: (context: WorkflowContext) => Record<string, AttributeValue>;
 };
 declare function otelPlugin(options?: OtelPluginOptions): WorkflowPlugin<StepBaseContext, object>;
-export { workflow, otelPlugin, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };
+export { workflow, otelPlugin, createWorkflowRef, WorkflowStatus, WorkflowRunProgress, WorkflowRunNotFoundError, WorkflowRun, WorkflowRef, WorkflowPriority, WorkflowPlugin, WorkflowOptions, WorkflowLogger, WorkflowEngineOptions, WorkflowEngineError, WorkflowEngine, WorkflowDefinition, WorkflowContext, WorkflowClientOptions, WorkflowClient, StepBaseContext, StartWorkflowOptions, ScheduleContext, Schedule, OtelPluginOptions, InputParameters, InferInputParameters, Duration };

package/dist/index.js

@@ -15,6 +15,7 @@ import {
   insertWorkflowRun,
   invokeChildWorkflowTimelineKey,
   isInvokeChildWorkflowTimelineEntry,
+  resolvePriority,
   runMigrations,
   scheduleQueueNameFor,
   updateWorkflowRun,
@@ -23,7 +24,7 @@ import {
   waitForTimelineKey,
   withPostgresTransaction,
   workflow
-} from "./shared/chunk-hjycwrsq.js";
+} from "./shared/chunk-w3qcrrwx.js";
 // src/engine.ts
 import { merge } from "es-toolkit";
 import pg from "pg";
@@ -394,6 +395,7 @@ class WorkflowEngine {
     parentRunId,
     parentStepId,
     parentResourceId,
+    parentPriority,
     scheduledAt,
     enqueue = true,
     db
@@ -424,6 +426,7 @@ class WorkflowEngine {
       status: "running" /* RUNNING */,
       input,
       maxRetries: options?.retries ?? workflow2.retries ?? 0,
+      priority: resolvePriority(options?.priority, workflow2.priority, parentPriority),
       timeoutAt,
       idempotencyKey,
       parentRunId,
@@ -451,6 +454,7 @@ class WorkflowEngine {
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
       startAfter: new Date,
       expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+      priority: run.priority,
       ...retrySendOptions(run.maxRetries),
       ...db ? { db } : {}
     });
@@ -600,6 +604,7 @@ class WorkflowEngine {
     };
     await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
       expireInSeconds: options?.expireInSeconds ?? defaultExpireInSeconds,
+      priority: run.priority,
       ...retrySendOptions(run.maxRetries)
     });
     this.logger.log(`event ${eventName} sent for workflow run with id ${runId}`);
@@ -1009,6 +1014,7 @@ class WorkflowEngine {
         parentRunId: run.id,
         parentStepId: stepId,
         parentResourceId: run.resourceId ?? undefined,
+        parentPriority: run.priority,
         enqueue: true,
         db
       });
@@ -1207,6 +1213,7 @@ ${error.stack}` : String(error)
         await this.boss.send(WORKFLOW_RUN_QUEUE_NAME, job, {
           startAfter: timeoutDate.getTime() <= Date.now() ? new Date : timeoutDate,
           expireInSeconds: defaultExpireInSeconds,
+          priority: run.priority,
           ...retrySendOptions(run.maxRetries)
         });
       } catch (error) {
@@ -1325,6 +1332,7 @@ ${error.stack}` : String(error)
       }, {
         startAfter: new Date(Date.now() + intervalMs),
         expireInSeconds: defaultExpireInSeconds,
+        priority: run.priority,
         ...retrySendOptions(run.maxRetries)
       });
     } catch (error) {
@@ -1566,5 +1574,5 @@ export {
   WorkflowClient
 };
 
-//# debugId=EE11F9509955D59264756E2164756E21
+//# debugId=A6C8F39FA22E601264756E2164756E21
 //# sourceMappingURL=index.js.map