Runtime Events

Runtime Events

SwiftLexicon is the runtime used by the swift generator. It provides generated values and async event streams keyed by generated lemmas.

Use it when vocabulary should drive event matching, analytics routing, UI state transitions, or reactive workflows.

Basic Event Stream

import SwiftLexicon

let events = Events()

let subscription = commerce.ux.type.action >> events.then { event in
	print(event.description)
}

commerce.ui.product.card.buy >> events

subscription.cancel()
events.finish()

Keyed Events

Generated lemmas can carry keyed values:

commerce.ui.product.card.buy["birthday_001"] >> events

The payload is JSON-backed. Decode it through JSONDecoder:

let subscription = commerce.ui.product.card.buy >> events.then { event in
	let value: String = try event[type: String.self]
	print(value)
}

Match by Type

If a generated lemma is typed as commerce.ux.type.action, you can subscribe to the type:

let subscription = commerce.ux.type.action >> events.then { event in
	print("action:", event.description)
}

This lets different UI events share handling through vocabulary types instead of switch statements over strings.

Snapshot

Events expose a sendable snapshot:

let snapshot = event.snapshot

print(snapshot.id)
print(snapshot.description)
print(snapshot.lemma)
print(snapshot.values)

Use snapshots at concurrency boundaries or when storing an event log.

Practical Pattern

1. Define product actions and state transitions in .lexicon.
2. Generate Swift with --type swift.
3. Use generated lemmas when sending events.
4. Subscribe by concrete lemma for narrow behavior.
5. Subscribe by generated type for broad behavior.
6. Persist exact IDs and JSON values, not generated class names.

The generated source is the compile-time surface. The dot-path ID is the stable runtime contract.