pg-workflows 0.12.0 → 0.13.0

package/dist/index.cjs

@@ -84,6 +84,8 @@ var import_pg_boss = require("pg-boss");
 var PAUSE_EVENT_NAME = "__internal_pause";
 var WORKFLOW_RUN_QUEUE_NAME = "workflow-run";
 var WORKFLOW_RUN_DLQ_QUEUE_NAME = "workflow_run_dlq";
+var SCHEDULE_QUEUE_PREFIX = "__pgw_schedule_";
+var scheduleQueueNameFor = (workflowId) => `${SCHEDULE_QUEUE_PREFIX}${workflowId}`;
 var DEFAULT_PGBOSS_SCHEMA = "pgboss_v12_pgworkflow";
 var MAX_WORKFLOW_ID_LENGTH = 256;
 var MAX_RESOURCE_ID_LENGTH = 256;
@@ -95,7 +97,7 @@ var isInvokeChildWorkflowTimelineEntry = (entry) => !!entry && typeof entry ===
 
 // src/db/migration.ts
 var MIGRATION_LOCK_ID = 738291645;
-var CURRENT_SCHEMA_VERSION = 4;
+var CURRENT_SCHEMA_VERSION = 5;
 async function runMigrations(db) {
   if (await isSchemaUpToDate(db)) {
     return;
@@ -158,6 +160,9 @@ async function runMigrations(db) {
     commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_step_id varchar(256)");
     commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS parent_resource_id varchar(256)");
   }
+  if (currentVersion < 5) {
+    commands.push("ALTER TABLE workflow_runs ADD COLUMN IF NOT EXISTS scheduled_at timestamp with time zone");
+  }
   if (currentVersion === 0) {
     commands.push(`INSERT INTO workflow_schema_version (version) VALUES (${CURRENT_SCHEMA_VERSION})`);
   } else {
@@ -223,7 +228,8 @@ function mapRowToWorkflowRun(row) {
     idempotencyKey: row.idempotency_key,
     parentRunId: row.parent_run_id,
     parentStepId: row.parent_step_id,
-    parentResourceId: row.parent_resource_id
+    parentResourceId: row.parent_resource_id,
+    scheduledAt: row.scheduled_at ? new Date(row.scheduled_at) : null
   };
 }
 async function insertWorkflowRun({
@@ -237,7 +243,8 @@ async function insertWorkflowRun({
   idempotencyKey,
   parentRunId,
   parentStepId,
-  parentResourceId
+  parentResourceId,
+  scheduledAt
 }, db) {
   const runId = generateKSUID("run");
   const now = new Date;
@@ -257,9 +264,10 @@ async function insertWorkflowRun({
       idempotency_key,
       parent_run_id,
       parent_step_id,
-      parent_resource_id
+      parent_resource_id,
+      scheduled_at
     )
-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)
     ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
     RETURNING *`, [
     runId,
@@ -277,7 +285,8 @@ async function insertWorkflowRun({
     idempotencyKey ?? null,
     parentRunId ?? null,
     parentStepId ?? null,
-    parentResourceId ?? null
+    parentResourceId ?? null,
+    scheduledAt ?? null
   ]);
   if (result.rows[0]) {
     return { run: mapRowToWorkflowRun(result.rows[0]), created: true };
@@ -306,6 +315,23 @@ async function getWorkflowRun({
   }
   return mapRowToWorkflowRun(run);
 }
+async function getWorkflowLastRun({
+  workflowId,
+  resourceId
+}, db) {
+  const result = resourceId ? await db.executeSql(`SELECT * FROM workflow_runs
+         WHERE workflow_id = $1 AND resource_id = $2
+         ORDER BY created_at DESC
+         LIMIT 1`, [workflowId, resourceId]) : await db.executeSql(`SELECT * FROM workflow_runs
+         WHERE workflow_id = $1
+         ORDER BY created_at DESC
+         LIMIT 1`, [workflowId]);
+  const run = result.rows[0];
+  if (!run) {
+    return null;
+  }
+  return mapRowToWorkflowRun(run);
+}
 async function updateWorkflowRun({
   runId,
   resourceId,
@@ -853,7 +879,9 @@ function createWorkflowRef(id, options) {
     handler,
     inputSchema: options?.inputSchema,
     timeout: defineOptions?.timeout,
-    retries: defineOptions?.retries
+    retries: defineOptions?.retries,
+    schedule: defineOptions?.schedule,
+    timezone: defineOptions?.timezone
   });
   Object.defineProperty(ref, "id", { value: id, enumerable: true });
   Object.defineProperty(ref, "inputSchema", {
@@ -863,12 +891,14 @@ function createWorkflowRef(id, options) {
   return ref;
 }
 function createWorkflowFactory(plugins = []) {
-  const factory = (id, handler, { inputSchema, timeout, retries } = {}) => ({
+  const factory = (id, handler, { inputSchema, timeout, retries, schedule, timezone } = {}) => ({
     id,
     handler,
     inputSchema,
     timeout,
     retries,
+    schedule,
+    timezone,
     plugins: plugins.length > 0 ? plugins : undefined
   });
   factory.use = (plugin) => createWorkflowFactory([
@@ -980,6 +1010,56 @@ function parseDuration(duration) {
   return ms;
 }
 
+// src/schedule.ts
+var import_cron_parser = require("cron-parser");
+var CRON_TOKEN = /^[0-9*/,?\-LW#]+$/;
+function looksLikeCronString(value) {
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.length !== 5 && tokens.length !== 6)
+    return false;
+  return tokens.every((t) => CRON_TOKEN.test(t));
+}
+function validateCronExpression(expression, timezone) {
+  try {
+    import_cron_parser.CronExpressionParser.parse(expression, { tz: timezone });
+  } catch (e) {
+    throw new WorkflowEngineError(`Invalid cron expression "${expression}" (timezone: ${timezone}): ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+function durationMsToCron(ms, original) {
+  if (ms < MS_PER_MINUTE) {
+    throw new WorkflowEngineError(`Schedule interval must be at least 1 minute; got ${ms}ms from ${JSON.stringify(original)}`);
+  }
+  if (ms % MS_PER_DAY === 0) {
+    const days = ms / MS_PER_DAY;
+    if (days === 1)
+      return "0 0 * * *";
+    throw cronStepError(original, `${days} days`);
+  }
+  if (ms % MS_PER_HOUR === 0) {
+    const hours = ms / MS_PER_HOUR;
+    if (24 % hours === 0)
+      return `0 */${hours} * * *`;
+    throw cronStepError(original, `${hours} hours`);
+  }
+  const minutes = ms / MS_PER_MINUTE;
+  if (Number.isInteger(minutes) && 60 % minutes === 0)
+    return `*/${minutes} * * * *`;
+  throw cronStepError(original, `${minutes} minutes`);
+}
+function cronStepError(original, label) {
+  return new WorkflowEngineError(`Schedule interval ${JSON.stringify(original)} (${label}) doesn't map cleanly to a recurring cron expression. Use a value that divides 60 minutes, 24 hours, or 1 day — or pass an explicit cron string.`);
+}
+function resolveSchedule(schedule, timezone) {
+  const tz = timezone ?? "UTC";
+  if (typeof schedule === "string" && looksLikeCronString(schedule)) {
+    validateCronExpression(schedule, tz);
+    return { cron: schedule, timezone: tz };
+  }
+  const ms = parseDuration(schedule);
+  return { cron: durationMsToCron(ms, schedule), timezone: tz };
+}
+
 // src/engine.ts
 var LOG_PREFIX2 = "[WorkflowEngine]";
 var StepTypeToIcon = {
@@ -1066,10 +1146,41 @@ class WorkflowEngine {
       await this.boss.work(WORKFLOW_RUN_DLQ_QUEUE_NAME, { pollingIntervalSeconds: 0.5, batchSize: 1 }, (jobs) => this.handleWorkflowRunDlq(jobs));
       this.logger.log(`Worker started for queue ${WORKFLOW_RUN_DLQ_QUEUE_NAME}`);
     }
+    if (asEngine) {
+      const scheduled = Array.from(this.workflows.values()).flatMap((wf) => wf.schedule == null ? [] : [{ id: wf.id, resolved: resolveSchedule(wf.schedule, wf.timezone) }]);
+      await Promise.allSettled(scheduled.map(({ id, resolved }) => this.registerWorkflowSchedule(id, resolved).catch((error) => {
+        this.logger.error(`Failed to register schedule for "${id}", skipping`, error instanceof Error ? error : new Error(String(error)), { workflowId: id });
+      })));
+    }
     this._started = true;
     this.logger.log("Workflow engine started!");
   }
+  async registerWorkflowSchedule(workflowId, resolvedSchedule) {
+    const scheduleQueueName = scheduleQueueNameFor(workflowId);
+    await this.boss.createQueue(scheduleQueueName);
+    await this.boss.schedule(scheduleQueueName, resolvedSchedule.cron, null, {
+      tz: resolvedSchedule.timezone
+    });
+    await this.boss.work(scheduleQueueName, { batchSize: 1, includeMetadata: true }, async (jobs) => {
+      const scheduledAt = jobs[0]?.startAfter ?? new Date;
+      try {
+        await this.createWorkflowRun({ workflowId, input: {}, scheduledAt });
+      } catch (error) {
+        this.logger.error(`Schedule fire failed to start a run for workflow "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+        throw error;
+      }
+    });
+    this.logger.log(`Schedule registered for workflow "${workflowId}": ${resolvedSchedule.cron} (${resolvedSchedule.timezone})`, { workflowId });
+  }
+  async unscheduleWorkflow(workflowId) {
+    try {
+      await this.boss.unschedule(scheduleQueueNameFor(workflowId));
+    } catch (error) {
+      this.logger.error(`Failed to unschedule "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+    }
+  }
   async stop() {
+    await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
     await this.boss.stop();
     if (this._ownsPool) {
       await this.pool.end();
@@ -1082,10 +1193,14 @@ class WorkflowEngine {
       throw new WorkflowEngineError(`Workflow ${definition.id} is already registered`, definition.id);
     }
     const { steps } = parseWorkflowHandler(definition.handler);
+    const resolvedSchedule = definition.schedule ? resolveSchedule(definition.schedule, definition.timezone) : undefined;
     this.workflows.set(definition.id, {
       ...definition,
       steps
     });
+    if (this._started && resolvedSchedule) {
+      await this.registerWorkflowSchedule(definition.id, resolvedSchedule);
+    }
     this.logger.log(`Registered workflow "${definition.id}" with steps:`);
     for (const step of steps.values()) {
       const tags = [];
@@ -1100,10 +1215,17 @@ class WorkflowEngine {
     return this;
   }
   async unregisterWorkflow(workflowId) {
+    const existing = this.workflows.get(workflowId);
+    if (existing?.schedule != null && this._started) {
+      await this.unscheduleWorkflow(workflowId);
+    }
     this.workflows.delete(workflowId);
     return this;
   }
   async unregisterAllWorkflows() {
+    if (this._started) {
+      await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
+    }
     this.workflows.clear();
     return this;
   }
@@ -1153,6 +1275,7 @@ class WorkflowEngine {
     parentRunId,
     parentStepId,
     parentResourceId,
+    scheduledAt,
     enqueue = true,
     db
   }) {
@@ -1186,7 +1309,8 @@ class WorkflowEngine {
       idempotencyKey,
       parentRunId,
       parentStepId,
-      parentResourceId
+      parentResourceId,
+      scheduledAt
     }, targetDb);
     const insertAndEnqueue = async (targetDb) => {
       const result = await insertRun(targetDb);
@@ -1369,6 +1493,14 @@ class WorkflowEngine {
     }
     return run;
   }
+  async getWorkflowLastRun({
+    workflowId,
+    resourceId
+  }) {
+    validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
+    return getWorkflowLastRun({ workflowId, resourceId }, this.db);
+  }
   async updateRun({
     runId,
     resourceId,
@@ -1600,7 +1732,8 @@ class WorkflowEngine {
           return run?.timeline ?? {};
         },
         logger: this.logger,
-        step
+        step,
+        schedule: run.scheduledAt ? { timestamp: run.scheduledAt } : undefined
       };
       for (const plugin of plugins) {
         const extra = plugin.methods(step, context);
@@ -2319,5 +2452,5 @@ function otelPlugin(options = {}) {
   };
 }
 
-//# debugId=BCF84547491115D464756E2164756E21
+//# debugId=12905C6BC12C3A1664756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.d.cts

@@ -23,6 +23,8 @@ type WorkflowRun = {
 	parentRunId: string | null;
 	parentStepId: string | null;
 	parentResourceId: string | null;
+	/** Set when the run was started by a recurring schedule; the timestamp the schedule fired. */
+	scheduledAt: Date | null;
 };
 import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
@@ -33,6 +35,7 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
+type Schedule = string | Exclude<Duration, string>;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -63,6 +66,18 @@ type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
+	/**
+	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
+	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
+	*/
+	schedule?: Schedule;
+	/** IANA timezone for cron expressions. Defaults to UTC. Ignored for duration-based schedules. */
+	timezone?: string;
+};
+/** Metadata about a scheduled fire, exposed on `ctx.schedule` for runs triggered by a schedule. */
+type ScheduleContext = {
+	/** Time the schedule fired this run. */
+	timestamp: Date;
 };
 type StepBaseContext = {
 	run: <T>(stepId: string, handler: () => Promise<T>) => Promise<T>;
@@ -148,6 +163,8 @@ type WorkflowContext<
 	attempt: number;
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
+	/** Set only for runs triggered by a recurring schedule. */
+	schedule?: ScheduleContext;
 };
 type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	id: string;
@@ -156,6 +173,8 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	schedule?: Schedule;
+	timezone?: string;
 	plugins?: WorkflowPlugin[];
 };
 type StepInternalDefinition = {
@@ -331,6 +350,8 @@ declare class WorkflowEngine {
 		batchSize?: number;
 		heartbeatSeconds?: number;
 	}): Promise<void>;
+	private registerWorkflowSchedule;
+	private unscheduleWorkflow;
 	stop(): Promise<void>;
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
@@ -383,6 +404,15 @@ declare class WorkflowEngine {
 		exclusiveLock?: boolean;
 		db?: Db;
 	}): Promise<WorkflowRun>;
+	/**
+	* Fetch the most recently created run for a workflow, optionally scoped to a
+	* `resourceId`. Useful for cron-style incremental syncs where the next run
+	* needs the previous run's completion timestamp as a cursor.
+	*/
+	getWorkflowLastRun({ workflowId, resourceId }: {
+		workflowId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun | null>;
 	updateRun({ runId, resourceId, data, expectedStatuses }: {
 		runId: string;
 		resourceId?: string;
@@ -472,4 +502,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, OtelPluginOptions, InputParameters, InferInputParameters, Duration };
+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 };

package/dist/index.d.ts

@@ -23,6 +23,8 @@ type WorkflowRun = {
 	parentRunId: string | null;
 	parentStepId: string | null;
 	parentResourceId: string | null;
+	/** Set when the run was started by a recurring schedule; the timestamp the schedule fired. */
+	scheduledAt: Date | null;
 };
 import { StandardSchemaV1 } from "@standard-schema/spec";
 type DurationObject = {
@@ -33,6 +35,7 @@ type DurationObject = {
 	seconds?: number;
 };
 type Duration = string | DurationObject;
+type Schedule = string | Exclude<Duration, string>;
 declare enum WorkflowStatus {
 	PENDING = "pending",
 	RUNNING = "running",
@@ -63,6 +66,18 @@ type WorkflowOptions<I extends InputParameters> = {
 	timeout?: number;
 	retries?: number;
 	inputSchema?: I;
+	/**
+	* Recurring schedule. Accepts a cron expression (`'0 9 * * 1-5'`),
+	* a duration string (`'5m'`, `'1 hour'`), or a `DurationObject`.
+	*/
+	schedule?: Schedule;
+	/** IANA timezone for cron expressions. Defaults to UTC. Ignored for duration-based schedules. */
+	timezone?: string;
+};
+/** Metadata about a scheduled fire, exposed on `ctx.schedule` for runs triggered by a schedule. */
+type ScheduleContext = {
+	/** Time the schedule fired this run. */
+	timestamp: Date;
 };
 type StepBaseContext = {
 	run: <T>(stepId: string, handler: () => Promise<T>) => Promise<T>;
@@ -148,6 +163,8 @@ type WorkflowContext<
 	attempt: number;
 	timeline: Record<string, unknown>;
 	logger: WorkflowLogger;
+	/** Set only for runs triggered by a recurring schedule. */
+	schedule?: ScheduleContext;
 };
 type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	id: string;
@@ -156,6 +173,8 @@ type WorkflowDefinition<TInput extends InputParameters = InputParameters> = {
 	inputSchema?: TInput;
 	timeout?: number;
 	retries?: number;
+	schedule?: Schedule;
+	timezone?: string;
 	plugins?: WorkflowPlugin[];
 };
 type StepInternalDefinition = {
@@ -331,6 +350,8 @@ declare class WorkflowEngine {
 		batchSize?: number;
 		heartbeatSeconds?: number;
 	}): Promise<void>;
+	private registerWorkflowSchedule;
+	private unscheduleWorkflow;
 	stop(): Promise<void>;
 	registerWorkflow(definition: WorkflowDefinition<InputParameters>): Promise<WorkflowEngine>;
 	unregisterWorkflow(workflowId: string): Promise<WorkflowEngine>;
@@ -383,6 +404,15 @@ declare class WorkflowEngine {
 		exclusiveLock?: boolean;
 		db?: Db;
 	}): Promise<WorkflowRun>;
+	/**
+	* Fetch the most recently created run for a workflow, optionally scoped to a
+	* `resourceId`. Useful for cron-style incremental syncs where the next run
+	* needs the previous run's completion timestamp as a cursor.
+	*/
+	getWorkflowLastRun({ workflowId, resourceId }: {
+		workflowId: string;
+		resourceId?: string;
+	}): Promise<WorkflowRun | null>;
 	updateRun({ runId, resourceId, data, expectedStatuses }: {
 		runId: string;
 		resourceId?: string;
@@ -472,4 +502,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, OtelPluginOptions, InputParameters, InferInputParameters, Duration };
+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 };

package/dist/index.js

@@ -8,19 +8,21 @@ import {
   WorkflowRunNotFoundError,
   WorkflowStatus,
   createWorkflowRef,
+  getWorkflowLastRun,
   getWorkflowRun,
   getWorkflowRuns,
   insertWorkflowRun,
   invokeChildWorkflowTimelineKey,
   isInvokeChildWorkflowTimelineEntry,
   runMigrations,
+  scheduleQueueNameFor,
   updateWorkflowRun,
   validateResourceId,
   validateWorkflowId,
   waitForTimelineKey,
   withPostgresTransaction,
   workflow
-} from "./shared/chunk-ahxqsytt.js";
+} from "./shared/chunk-5xswmve7.js";
 // src/engine.ts
 import { merge } from "es-toolkit";
 import pg from "pg";
@@ -122,6 +124,56 @@ function parseDuration(duration) {
   return ms;
 }
 
+// src/schedule.ts
+import { CronExpressionParser } from "cron-parser";
+var CRON_TOKEN = /^[0-9*/,?\-LW#]+$/;
+function looksLikeCronString(value) {
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.length !== 5 && tokens.length !== 6)
+    return false;
+  return tokens.every((t) => CRON_TOKEN.test(t));
+}
+function validateCronExpression(expression, timezone) {
+  try {
+    CronExpressionParser.parse(expression, { tz: timezone });
+  } catch (e) {
+    throw new WorkflowEngineError(`Invalid cron expression "${expression}" (timezone: ${timezone}): ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+function durationMsToCron(ms, original) {
+  if (ms < MS_PER_MINUTE) {
+    throw new WorkflowEngineError(`Schedule interval must be at least 1 minute; got ${ms}ms from ${JSON.stringify(original)}`);
+  }
+  if (ms % MS_PER_DAY === 0) {
+    const days = ms / MS_PER_DAY;
+    if (days === 1)
+      return "0 0 * * *";
+    throw cronStepError(original, `${days} days`);
+  }
+  if (ms % MS_PER_HOUR === 0) {
+    const hours = ms / MS_PER_HOUR;
+    if (24 % hours === 0)
+      return `0 */${hours} * * *`;
+    throw cronStepError(original, `${hours} hours`);
+  }
+  const minutes = ms / MS_PER_MINUTE;
+  if (Number.isInteger(minutes) && 60 % minutes === 0)
+    return `*/${minutes} * * * *`;
+  throw cronStepError(original, `${minutes} minutes`);
+}
+function cronStepError(original, label) {
+  return new WorkflowEngineError(`Schedule interval ${JSON.stringify(original)} (${label}) doesn't map cleanly to a recurring cron expression. Use a value that divides 60 minutes, 24 hours, or 1 day — or pass an explicit cron string.`);
+}
+function resolveSchedule(schedule, timezone) {
+  const tz = timezone ?? "UTC";
+  if (typeof schedule === "string" && looksLikeCronString(schedule)) {
+    validateCronExpression(schedule, tz);
+    return { cron: schedule, timezone: tz };
+  }
+  const ms = parseDuration(schedule);
+  return { cron: durationMsToCron(ms, schedule), timezone: tz };
+}
+
 // src/engine.ts
 var LOG_PREFIX = "[WorkflowEngine]";
 var StepTypeToIcon = {
@@ -208,10 +260,41 @@ class WorkflowEngine {
       await this.boss.work(WORKFLOW_RUN_DLQ_QUEUE_NAME, { pollingIntervalSeconds: 0.5, batchSize: 1 }, (jobs) => this.handleWorkflowRunDlq(jobs));
       this.logger.log(`Worker started for queue ${WORKFLOW_RUN_DLQ_QUEUE_NAME}`);
     }
+    if (asEngine) {
+      const scheduled = Array.from(this.workflows.values()).flatMap((wf) => wf.schedule == null ? [] : [{ id: wf.id, resolved: resolveSchedule(wf.schedule, wf.timezone) }]);
+      await Promise.allSettled(scheduled.map(({ id, resolved }) => this.registerWorkflowSchedule(id, resolved).catch((error) => {
+        this.logger.error(`Failed to register schedule for "${id}", skipping`, error instanceof Error ? error : new Error(String(error)), { workflowId: id });
+      })));
+    }
     this._started = true;
     this.logger.log("Workflow engine started!");
   }
+  async registerWorkflowSchedule(workflowId, resolvedSchedule) {
+    const scheduleQueueName = scheduleQueueNameFor(workflowId);
+    await this.boss.createQueue(scheduleQueueName);
+    await this.boss.schedule(scheduleQueueName, resolvedSchedule.cron, null, {
+      tz: resolvedSchedule.timezone
+    });
+    await this.boss.work(scheduleQueueName, { batchSize: 1, includeMetadata: true }, async (jobs) => {
+      const scheduledAt = jobs[0]?.startAfter ?? new Date;
+      try {
+        await this.createWorkflowRun({ workflowId, input: {}, scheduledAt });
+      } catch (error) {
+        this.logger.error(`Schedule fire failed to start a run for workflow "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+        throw error;
+      }
+    });
+    this.logger.log(`Schedule registered for workflow "${workflowId}": ${resolvedSchedule.cron} (${resolvedSchedule.timezone})`, { workflowId });
+  }
+  async unscheduleWorkflow(workflowId) {
+    try {
+      await this.boss.unschedule(scheduleQueueNameFor(workflowId));
+    } catch (error) {
+      this.logger.error(`Failed to unschedule "${workflowId}"`, error instanceof Error ? error : new Error(String(error)), { workflowId });
+    }
+  }
   async stop() {
+    await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
     await this.boss.stop();
     if (this._ownsPool) {
       await this.pool.end();
@@ -224,10 +307,14 @@ class WorkflowEngine {
       throw new WorkflowEngineError(`Workflow ${definition.id} is already registered`, definition.id);
     }
     const { steps } = parseWorkflowHandler(definition.handler);
+    const resolvedSchedule = definition.schedule ? resolveSchedule(definition.schedule, definition.timezone) : undefined;
     this.workflows.set(definition.id, {
       ...definition,
       steps
     });
+    if (this._started && resolvedSchedule) {
+      await this.registerWorkflowSchedule(definition.id, resolvedSchedule);
+    }
     this.logger.log(`Registered workflow "${definition.id}" with steps:`);
     for (const step of steps.values()) {
       const tags = [];
@@ -242,10 +329,17 @@ class WorkflowEngine {
     return this;
   }
   async unregisterWorkflow(workflowId) {
+    const existing = this.workflows.get(workflowId);
+    if (existing?.schedule != null && this._started) {
+      await this.unscheduleWorkflow(workflowId);
+    }
     this.workflows.delete(workflowId);
     return this;
   }
   async unregisterAllWorkflows() {
+    if (this._started) {
+      await Promise.allSettled(Array.from(this.workflows.values()).filter((wf) => wf.schedule != null).map((wf) => this.unscheduleWorkflow(wf.id)));
+    }
     this.workflows.clear();
     return this;
   }
@@ -295,6 +389,7 @@ class WorkflowEngine {
     parentRunId,
     parentStepId,
     parentResourceId,
+    scheduledAt,
     enqueue = true,
     db
   }) {
@@ -328,7 +423,8 @@ class WorkflowEngine {
       idempotencyKey,
       parentRunId,
       parentStepId,
-      parentResourceId
+      parentResourceId,
+      scheduledAt
     }, targetDb);
     const insertAndEnqueue = async (targetDb) => {
       const result = await insertRun(targetDb);
@@ -511,6 +607,14 @@ class WorkflowEngine {
     }
     return run;
   }
+  async getWorkflowLastRun({
+    workflowId,
+    resourceId
+  }) {
+    validateWorkflowId(workflowId);
+    validateResourceId(resourceId);
+    return getWorkflowLastRun({ workflowId, resourceId }, this.db);
+  }
   async updateRun({
     runId,
     resourceId,
@@ -742,7 +846,8 @@ class WorkflowEngine {
           return run?.timeline ?? {};
         },
         logger: this.logger,
-        step
+        step,
+        schedule: run.scheduledAt ? { timestamp: run.scheduledAt } : undefined
       };
       for (const plugin of plugins) {
         const extra = plugin.methods(step, context);
@@ -1475,5 +1580,5 @@ export {
   WorkflowClient
 };
 
-//# debugId=3131CBB2B482181264756E2164756E21
+//# debugId=5BC543336A07527964756E2164756E21
 //# sourceMappingURL=index.js.map