Getting Started

Event-Driven Order Processing


The most common event-driven pattern is reacting to domain events and triggering side effects. When an order is created, reserve inventory. When payment is received, create a shipment. When an order is cancelled, release the reservation. Each event handler is a workflow that executes tasks durably — if the worker crashes after reserving inventory but before emitting the confirmation event, replay picks up from the last checkpoint.

How it works

One workflow, handle_order_event, is the dispatcher: it matches on the event type and runs the matching reaction chain. Each incoming event starts its own execution of this workflow, so a thousand orders a minute is a thousand independent, individually-journaled runs.

handle_order_event
one execution per event · matches on event_type
match event_type
order.created
reserve_inventory → notify
payment.received
create_shipment → notify
order.cancelled
release_inventory → notify

Unmatched event types fall through the _ arm and are ignored — new events don't break old handlers.

Example: an order event dispatcher

1
import {
2
Workflow,
3
Tasks,
4
Task,
5
WorkflowContext,
6
createTaskRefs,
7
} from '@orcher/sdk';
8
9
@Tasks()
10
class OrderEventTasks {
11
@Task()
12
async reserveInventory(items: OrderItem[]): Promise<string> {
13
return await inventoryClient.reserve(items);
14
}
15
16
@Task()
17
async createShipment(orderId: string): Promise<string> {
18
return await shippingClient.createShipment(orderId);
19
}
20
21
@Task()
22
async releaseInventory(orderId: string): Promise<void> {
23
await inventoryClient.release(orderId);
24
}
25
26
@Task()
27
async sendNotification(input: NotificationInput): Promise<void> {
28
await notificationClient.send(input);
29
}
30
}
31
32
const tasks = createTaskRefs(OrderEventTasks);
33
34
@Workflow({ name: 'handle_order_event', version: '1.0.0' })
35
class HandleOrderEvent {
36
async run(ctx: WorkflowContext, event: OrderEvent): Promise<void> {
37
switch (event.eventType) {
38
case 'order.created': {
39
const reservation = await ctx.executeTask(
40
tasks.reserveInventory, event.items!,
41
);
42
await ctx.executeTask(tasks.sendNotification, {
43
userId: event.userId,
44
message: `Order ${event.orderId} confirmed, reservation ${reservation}`,
45
});
46
break;
47
}
48
case 'payment.received': {
49
const tracking = await ctx.executeTask(
50
tasks.createShipment, event.orderId,
51
);
52
await ctx.executeTask(tasks.sendNotification, {
53
userId: event.userId,
54
message: `Order ${event.orderId} shipped, tracking ${tracking}`,
55
});
56
break;
57
}
58
case 'order.cancelled': {
59
await ctx.executeTask(tasks.releaseInventory, event.orderId);
60
await ctx.executeTask(tasks.sendNotification, {
61
userId: event.userId,
62
message: `Order ${event.orderId} cancelled`,
63
});
64
break;
65
}
66
}
67
}
68
}

Each event triggers a new workflow execution. If your service processes 1,000 order.created events per minute, that's 1,000 independent workflow executions — each with its own journal, its own retry logic, and its own crash recovery. You can trigger these workflows from any external source (webhook endpoint, message queue consumer, or the CLI).

The two guarantees an event bus won't give you

Durable execution makes each reaction reliable, but the delivery still comes from your event source — and real event buses are at-least-once and unordered. Both leak into this handler:

What the Handler Must Tolerate
Duplicate delivery
The same event, twice

At-least-once means order.created can arrive twice — two executions, two reservations, unless reserve_inventory is idempotent on the order ID.

Out-of-order arrival
payment before created

Separate executions have no ordering. A shipment handler that assumes the order already exists will fail if payment lands first.

Durable reactions ≠ ordered, deduplicated delivery — the handler owns those.

When ordering actually matters, don't try to sort events in the dispatcher — route them to a per-entity actor, whose single-writer guarantee applies each event against the entity's current state regardless of arrival order.

Design notes

  • Make each reaction idempotent. Derive downstream keys from the event (order ID, a dedupe key on the event itself) so a redelivered event is a no-op — the same defense as payment processing.
  • The _ arm is a feature. Ignoring unknown event types lets producers add new events before this consumer learns to handle them — forward compatibility for free. Log the ignored type so a genuinely-missed handler is visible.
  • One handler per event keeps failures isolated. A poison event that always fails retries and parks its own execution; the other 999 orders that minute are untouched. Contrast a single loop consuming a partition, where one bad message can stall everything behind it.
  • The dispatcher grows into child workflows. As each arm gains steps, a fat match becomes hard to read and test. Give each event type its own child workflow and let the dispatcher just route.

Next Steps