@haneinfo/domain-events
Transaction-bound domain event recording and database-backed delivery for Haneinfo Apps. See the Prisma model pattern for the App-owned schema and drift checks.
Register stable handlers with DomainEventRegistry. Call DomainEventsService.record(tx, input)
inside the same transaction as the business write; event creation and delivery fanout then commit
or roll back together. Handler-key contributors receive that same transaction.
The dispatcher claims bounded batches with PostgreSQL FOR UPDATE SKIP LOCKED. Each claim has a
unique lease, and completion compares that lease so a stale worker cannot overwrite another claim
or an administrator's decision. Delivery is at least once: retries and stale-lock recovery may
repeat external effects, so handlers must be idempotent.
Resolver and handler errors use the same per-delivery classification. Ignored errors become
IGNORED, terminal errors become DEAD_LETTER, and other failures retry with bounded backoff
until maxAttempts. An absent handler is ignored. A resolver failure does not stop later deliveries
in the claimed batch. Disabled integration bindings remain pending without consuming attempts.
DomainEventsModule.forRoot({ dispatcher }) accepts dispatcher options. Environment-based
configuration is also available through dispatcherOptionsFromEnvironment(). Use autoStart: false
for explicit test/operator ticks. Stopping the dispatcher clears its poll timer; handlers already
in progress remain responsible for finishing safely.
Polling intervals must be integers from 1 through 2,147,483,647 milliseconds. Invalid environment
intervals use the default; invalid direct options fail at startup. Explicitly undefined options
retain their defaults, including auto-start.
Integration events pin their payload schema, binding and digests when recorded. Webhook helpers validate destinations and signatures; inbound receipt processing joins the business transaction. Do not put secrets in event payloads or handler errors.
Dispatcher shutdown
The dispatcher stops accepting ticks at shutdown and waits for an active batch. shutdownTimeoutMs defaults to 30000 and accepts integers from 1 to 2147483647. A timeout logs a warning and does not cancel the batch or an external handler.