events

events(
  paths: text | [text]
  events: text | [text]
): [{
  event: text
  data: value
}]

The events function subscribes to Hantera's event bus and returns an iterator that yields events as they occur. This enables real-time streaming in HTTP ingresses when used with Server-Sent Events (SSE).

Availability

Discount	Rule	Reactor
		✓

Parameters

paths

The event path(s) to subscribe to. Can be a single text value or an array of paths.

Paths typically follow the resource pattern (for example actors/{actorType}/{actorId} for actor-related events), but other path patterns may be used by different event sources.

// Single path
events('actors/order/91ba49b2-14a4-41e7-8c1c-b02597edc169', 'checkpoint')

// Multiple paths
events(['actors/order/91ba49b2-14a4-41e7-8c1c-b02597edc169', 'actors/payment/2ef75af8-4383-4b0b-9ae2-e4645dbea0fb'], 'checkpoint')

// Path with interpolation
events($'actors/order/{orderId}', 'checkpoint')

events

The event type(s) to filter by. Can be a single text value or an array of event types.

Common event types include:

• checkpoint - Emitted when an actor's state changes

// Single event type
events('actors/order/3cd8554b-6150-4cda-9766-f62fd2825f2e', 'checkpoint')

// Multiple event types
events('jobs', ['jobStarted', 'jobCompleted'])

Return Value

Returns an iterator of Event records. Each event has:

Field	Type	Description
event	text	The event type name
data	value	The event payload, including the path where the event originated

The data field contains the full event payload which varies by event type. For checkpoint events, it typically contains actor state information.

Usage with SSE

The events function is designed to work with Server-Sent Events (SSE). When an HTTP ingress returns an iterator (like the one from events), and the client requests SSE with Accept: text/event-stream, Hantera streams each yielded value as an SSE message.

param orderId: uuid

// Send initial state immediately
from { event = 'init', data = { orderId } }

// Stream updates as they occur
from events ($'actors/order/{orderId}', 'checkpoint')
  select e => { event = 'updated', data = e.data }

Examples

Basic Order Tracking

Stream updates for a single order:

param orderId: uuid

from events ($'actors/order/{orderId}', 'checkpoint')

Multi-Entity Streaming

Subscribe to events from multiple actors:

param orderId: uuid
param paymentId: uuid

from { event = 'init', data = { orderId, paymentId } }

from events ($'actors/order/{orderId}', 'checkpoint')
  select e => { event = 'orderUpdated', data = e.data }

from events ($'actors/payment/{paymentId}', 'checkpoint')
  select e => { event = 'paymentUpdated', data = e.data }

SKU Stock Updates

A complete example that queries for a SKU and streams stock changes:

param skuNumber: text

let safeSkuNumber = skuNumber replace("''", "''''")
let skuQuery = query skus(skuId, skuNumber) 
  filter $'skuNumber == ''{safeSkuNumber}'''

from skuQuery match
  (e: QueryError) |> { error = { code = 'QUERY_ERROR', message = e.message } }
  |>
    let sku = skuQuery first

    from sku match
      nothing |> { error = { code = 'NOT_FOUND', message = 'SKU not found' } }
      |>
        let initialStock = messageActor(
          'sku'
          sku.skuId
          [{ type = 'calculateAvailableStock' }]
        )
        
        from { event = 'init', data = initialStock }
        
        from events ($'actors/sku/{sku.skuId}', 'checkpoint')
          select e => 
            let stock = messageActor(
              'sku'
              sku.skuId
              [{ type = 'calculateAvailableStock' }]
            )
            from { event = 'stockUpdated', data = stock }

See Also

• Server-Sent Events (SSE) - How to use events with HTTP streaming
• Event Streaming - Overview of Hantera's event system
• messageActor - Sending messages to actors