feat: add cron workflow scheduling with overlap protection and schedule context

[marcelom97]

Summary

• Cron-based workflow scheduling via cron option (expression + optional timezone)
• schedule context on cron runs with timestamp, lastTimestamp, timezone — enables incremental sync without manual state tracking
• getRuns() supports triggerSource filter ('api' | 'cron')
• Overlap protection via pg-boss schedule()

Usage

const sync = workflow('sync-data', async ({ step, schedule }) => {
  const since = schedule?.lastTimestamp ?? new Date(0);
  const data = await step.run('fetch', async () => fetchSince(since));
  await step.run('write', async () => writeToDB(data));
}, {
  cron: { expression: '*/15 * * * *', timezone: 'UTC' },
});

Test plan

• 14 new tests covering cron scheduling, schedule context, timezone defaults, trigger source filtering, and post-start registration

[SokratisVidros]

@marcelom97 thanks for submitting this. Can you please elaborate on the incremental sync?

Other than that, I need to think about the DX a bit more. I will start by adding inline comments.

[SokratisVidros]

How about using a cron: string column and a timezone, both being optional to avoid a nesting object?

[SokratisVidros]

Instead of a specific getLastCronCompletedAt method, I'd suggest introducing a getWorkflowLastRun that works for all workflows. This feels more generic and aligns with the naming of the rest of the methods.

[SokratisVidros]

Suggested change

	private async setupCronSchedule(wf: InternalWorkflowDefinition): Promise<void> {
	private async scheduleCronWorkflow(wf: InternalWorkflowDefinition): Promise<void> {

[SokratisVidros]

Please refer to my previous comment about modeling scheduleContext.

[SokratisVidros]

Following on the modeling, lastTimestamp comes from the workflow_runs table. We can replace it with the timestamp of the latest record.

[SokratisVidros]

Do we need triggerSource? If not let's remove it.

[SokratisVidros]

Let's create the following DX:

1. The cron expression can be a valid cron string or a human friendly cron string such as https://github.com/rainder/human-to-cron. Note, this library is quite old. Let's see if there is a modern one.

2. Cron can be either a string or an object of the expression and the timezone. If the timezone is not specified, we assume UTC or the current timezone of the running container.

[marcelom97]

I looked into this — human-to-cron has critical bugs (e.g. "every hour" produces * */1 * * * which fires every minute, and unrecognized input silently becomes * * * * *). I couldn't find a modern,
well-maintained alternative either.

I'd suggest we defer this and stick with standard cron expressions for now. We can revisit if a reliable library comes along, or build a small parser ourselves for a limited set of human-friendly strings (e.g.
"every 5 minutes", "daily at 9am").

[SokratisVidros]

@marcelom97 Any updates on this?

[marcelom97]

Hey @SokratisVidros, thanks for the review and for your suggestions.

I will take care of this over the weekend.

[marcelom97]

@SokratisVidros incremental sync is about only processing data that changed since the last cron run, instead of re-processing everything each time.

The schedule context gives cron workflows a lastTimestamp (derived from the previous completed run's completedAt), so the workflow can use it as a cursor:

const sync = workflow('sync-data', async ({ step, schedule }) => {
const since = schedule?.lastTimestamp ?? new Date(0);
const data = await step.run('fetch', async () => fetchSince(since));
await step.run('write', async () => writeToDB(data));
}, { cron: '*/15 * * * *' });

Without this, each cron run would need to either re-process all data or manually track its own high-water mark somewhere. lastTimestamp makes that built-in.

If you think it's not useful we can remove it, but I find it quite useful to have it.

[SokratisVidros]

@marcelom97 Thanks for the updates. I will review them by the end of this week and get back to you.

[marcelom97]

@SokratisVidros any news for this PR?