Skip to content

feat(processes): run a process after the change is saved - #234

Merged
artem-broccoli merged 4 commits into
mainfrom
artem/bro-264-run-a-process-after-the-change-is-saved
Nov 15, 2026
Merged

artem-broccoli merged 4 commits into
mainfrom
artem/bro-264-run-a-process-after-the-change-is-saved

Conversation

@artem-broccoli

Copy link
Copy Markdown
Contributor

Summary

A process can now run after the change that triggers it is saved, so slow steps or steps that reach outside systems never hold up or fail the save.

  • An on_event trigger takes "run": "after_commit" (no faultMode). Before the change commits, each matching after-commit process gets one processes.startRunsAfterCommit job per event, queued in the change's transaction: a rollback drops it, the commit makes it runnable.
  • The job starts the runs in its own transaction with the process version that matched the event. It locks the process, so its jobs take turns, and skips a process turned off in the meantime, records that are gone or have a run in progress, and records that already have this event's run (start_key). A retry or a second delivery starts nothing.
  • Failures are retried by the job runner (three attempts); a last failure is logged with the process, version and event ids.
  • Transactions carry a hop count (tx.hop, set with transact(work, { hop })). A job queued from a job's transaction is one hop further; none is queued past 10 hops, so after-commit processes that trigger each other stop.
  • In-transaction triggers are unchanged. Jobs run in no particular order.

Testing

  • New integration tests: the change commits with only a job queued, the job starts one run and a second delivery starts none; in-transaction and after-commit processes on the same event; a non-matching when queues nothing; a gone record, a turned-off process, a carried older version; a self-triggering process stops after 10 hops. Domain tests for the trigger shapes, a transaction test for the hop.
  • Manually with pnpm dev: turned on an after-commit process on employees.added, added a person and killed the API container straight away. The person was saved, one job waited (hop 1), no run existed. After restarting the API the job completed and started exactly one run with its task. A copy of the same job then completed and started nothing (already_started logged). A job with a broken version id failed three attempts and logged one error with its ids.
  • pnpm check, pnpm test:integration and pnpm test:e2e pass.

Release Notes:

  • N/A

An on_event trigger with run "after_commit" queues one pg-boss job per
process and event inside the change's transaction. After the commit the
job starts the runs of the version it carries, in its own transaction and
under the process's lock, skipping a turned-off process, gone records,
runs in progress and starts already taken, so retries start nothing twice.
Jobs carry a hop count and stop after 10 hops.
@artem-broccoli
artem-broccoli requested a review from a team as a code owner November 15, 2026 07:20
@artem-broccoli
artem-broccoli merged commit f25cc4a into main Nov 15, 2026
9 checks passed
@artem-broccoli
artem-broccoli deleted the artem/bro-264-run-a-process-after-the-change-is-saved branch November 15, 2026 07:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant