Options, Stores, and Events

Architectural guide for selecting the correct state management paradigm between Options (predefined datasets), Stores (runtime truth), and Events (decoupled triggers).
Published: 7/10/2026

To build robust Aircada projects, you must choose between the Store System (runtime truth), the Options System (data-driven configuration), or the Event System (discrete triggers).

Hierarchy of Choice:

1. Is it a predefined choice in options.registry.ts? -> Options System

2. Is it an ongoing state or persisted value? -> Store System

3. Is it a one-time, discrete action or trigger? -> Event System

3. The Event System (The Action Bus)#

A strictly typed, global message bus for transient 'fire and forget' actions.

How it works: Events defined in registry.generated.ts. React uses useAirEvent(). Engine operators use @Input({ onEvent }) and @Output({ emits }).

When to use: One-time, discrete actions or commands. If you need a trigger that doesn't persist (unlike a store property), use an Event.

Examples: Add-to-cart notifications, 'Reset Camera' animation triggers, analytics beacons.

2. The Options System (The Configurator Pipeline)#

A specialized architecture connecting Cloud Datasets and Merchandising Rules directly to the Store and Engine.

How it works: Uses OptionsRegistry. React components use useAirOptions(optionSet). Engine operators use @DatasetMapping to automatically pull columns into properties.

When to use: Predefined choices, variations, or configurable attributes that exist in options.registry.ts. If the data lives in a spreadsheet, it flows through here.

Examples: Swapping model types, choosing predefined colors/materials, selecting engraving font styles.

1. The Store System (The Default Choice)#

The Singular Source of Runtime Truth using the Twin-Proxy Vault for global, strictly typed state.

How it works: React uses useAirStore(). Engine operators use @Property({ store: 'path' }) or this.air.store.patch().

When to use: For anything that represents 'what is'. Persisted values, values driving UI state, or data shared between independent systems.

Examples: Cart panel open/close state, current configuration step, continuous pedestal rotation values.

note
Always prefer setting up a listener (@Input({ onStore: 'path' })) to react to state changes rather than firing a separate custom event. The Store handles reactivity automatically.