state
v0.23.1Distributed key-value state management — registers the `state::*` functions and `state::on-changed`, a private function observers watch for every committed change.
Install
iii trigger compose::add worker=state@nextRun in your project with the iii engine running. Exact versions are immutable and digest-pinned.
skill doc
state
The state worker is a server-side key/value store. Values are addressed by a scope (namespace) and a key, shared across every worker connected to the engine, and persisted through a pluggable adapter (kv or redis). Callers reach the core store through six state::* functions called with iii.call({ function_id: 'state::...', payload }). The worker also exposes state::list_keys and the internal state::ui-content function. Install it with iii call compose::add worker=state; it replaces the engine's legacy built-in state service, which must be removed from the engine config first.
State does not push updates to SDK clients. After every successful mutation the worker calls state::on-changed with a state:created, state:updated, or state:deleted event; functions that observe it react to data changes without polling. The kv adapter (default) supports file_based persistence (the default) or a volatile in_memory mode; redis proxies to a Redis backend. The function surface is identical across adapters.
When to Use
- Two or more functions need shared state without standing up a separate database.
- A counter or per-entity document needs atomic partial updates instead of read-modify-write.
- A write in one function should cause side effects elsewhere (cache invalidation, audit logs, notifications, projections).
- You want a specific
scope/keywatched and reacted to only when that slot changes.
Boundaries
- Schema-free by design — every value is opaque JSON. Use the
configurationworker when entries need a registered JSON Schema and validation. - Reads (
state::get,state::list,state::list_groups) never emitstate::on-changed; onlyset/update/deleteand a swappedcompare-and-setdo. - Delivery to observers is asynchronous and does not roll back the write on a target's failure; a delete of a missing key still emits
state:deletedwith a null old value. - Stream-shaped, broadcast-to-subscribers data belongs in the engine's stream surface, not here.
- The store lives in the worker process: the
kvin_memorybackend is lost when the worker stops. The defaultfile_basedbackend (andredis) survives restarts.
Functions
state::set— write or replace the value at ascope/key; emitsstate:createdorstate:updated.state::get— read one value byscopeandkey.state::delete— remove a key and emitstate:deletedwith the prior value.state::update— apply ordered atomic ops (set,merge,increment,decrement,append,remove) to the stored value.state::list— enumerate every value stored in a scope.state::list_groups— enumerate which scopes currently contain data.state::on-changed— the change event: observe it, never call it (private to the state worker).
Observing changes
Observe state::on-changed when a function should run automatically after a value changes — without polling state::get. It takes no args: select changes with filters on input.scope, input.key and input.event_type (any event field works, including input.new_value.*).
Reach for it when:
- A write in one worker should drive side effects in another (audit logs, cache invalidation, notifications, projections).
- You want only some changes: filters select them, for example
{ 'input.event_type': { $eq: 'state:deleted' } }.
If you only need the new value inside the same function that wrote it, use the mutator's returned old_value / new_value instead of observing.
How to observe
- Register a handler:
iii.registerFunction('orders::on-status-change', handler). - Observe the change event with it:
iii.observe(
{
function_id: 'state::on-changed',
filters: {
'input.scope': { $eq: 'orders' }, // omit to match every scope
'input.key': { $eq: 'status' }, // omit to match every key in the scope
},
capture: ['output'],
},
'orders::on-status-change',
)Filters take explicit operators ($eq, $in, $ne, …). To watch several specific keys, use { 'input.key': { $in: ['status', 'total'] } }. Mutations that emit: state::set, state::update, state::delete, a swapped state::compare-and-set.
The handler receives the Observed envelope; with capture: ['output'] its output is the event { type: "state", event_type, scope, key, old_value, new_value }, where event_type is one of state:created, state:updated, or state:deleted. Add 'caller' to the capture to also get caller.parent, the worker that wrote. Pass { metadata } as the third argument of iii.observe to hand the handler a sidecar with every event.