feat(trigger-record-change): record-after-write fires one flow on create OR update (#3427)

[os-zhuang]

Summary

Closes#3427.

A record_change flow's start node bound to exactly one lifecycle event via triggerType (record-after-create, record-after-update, …). A rule meant to run on both create and update — "recompute the SLA whenever a case is created or its priority changes" — forced authors to duplicate the whole flow into two near-identical definitions that drift, or drop out of the visual-flow layer into an object lifecycle hook.

This adds record-after-write (and its record-before-write before-phase form): the create-OR-update union. One start node, both lifecycle events — mirroring Salesforce's "created or updated" record-trigger option and Rails' after_save.

{id: 'start',type: 'start',config: {objectName: 'crm_case',triggerType: 'record-after-write'}}

write is exactly insert + update — the two mutations that persist field data. delete is deliberately excluded (a write persists a row, a delete removes it). One start node binds both hooks (afterInsert + afterUpdate) under the same flow; exactly one fires per mutation (a write is an insert xor an update), so it is not a double run.

To branch on which event fired inside the flow, test previous — empty on create, populated on update. e.g. edge condition previous == null selects the create path.

How it works

The engine's resolveTriggerBinding already forwards anyrecord-* token straight through to this trigger, so no engine, lint, or spec change is needed — the trigger owns the record-event vocabulary. The change is localized to @objectstack/trigger-record-change:

• triggerTypeToHookEvents(triggerType) (new, plural) is now the canonical mapper: it returns the list of ObjectQL hook events a token binds, expanding write → ['afterInsert', 'afterUpdate'].
• triggerTypeToHookEvent (singular) is kept for back-compat and now returns null for the multi-event write tokens rather than silently dropping a binding.
• RecordChangeTrigger.start registers one hook per mapped event, all under the same per-flow packageId, so a single stop() (unregisterHooksByPackage) tears both down together.
• A record-after-write flow whose action updates its own trigger record does not loop: the engine's existing flowName::recordId re-entrancy guard suppresses the self-fire (now covered by an end-to-end test).

Tests

• Unit (record-change-trigger.test.ts): triggerTypeToHookEvents maps write → both events for both phases; the singular mapper returns null for write; start() binds bothafterInsert + afterUpdate (same object, same packageId), fires on each, and stop() tears both down.
• End-to-end (record-change-integration.test.ts): a single record-after-write flow booted on a real kernel fires on both an insert and a subsequent update, and its own write-back does not loop.

All 33 tests in the package pass; the package builds clean (DTS typecheck).

Docs

• Automation › Flows: new Create-or-update flow section with the full triggerType → event table and the previous-based create/update discrimination pattern.
• Getting-started common patterns + the trigger README.md updated.

Changeset

minor bump for @objectstack/trigger-record-change.

---

Companion UI PR (objectui): the Studio flow designer's start-node trigger picker gains a "Record created or updated" option, with record + previous correctly in scope for it.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Building	Preview, Comment	Jul 24, 2026 2:50pm

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 1 changed package(s). ✅