Skip to content
Sign in

state

v0.23.2

Distributed key-value state management — registers the `state::*` functions and `state::on-changed`, a private function observers watch for every committed change.

license: Apache-2.0Used in 3 kitscachedistributedkey-valuekvstate

Install

bash
iii trigger compose::add worker=state@0.23.2

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

skill doc

SKILL.md

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/key watched and reacted to only when that slot changes.

Boundaries

  • Schema-free by design — every value is opaque JSON. Use the configuration worker when entries need a registered JSON Schema and validation.
  • Reads (state::get, state::list, state::list_groups) never emit state::on-changed; only set/update/delete and a swapped compare-and-set do.
  • 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:deleted with 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 kv in_memory backend is lost when the worker stops. The default file_based backend (and redis) survives restarts.

Functions

  • state::set — write or replace the value at a scope/key; emits state:created or state:updated.
  • state::get — read one value by scope and key.
  • state::delete — remove a key and emit state:deleted with 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

  1. Register a handler: iii.registerFunction('orders::on-status-change', handler).
  2. 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.

Search the registry

Find workers, kits and executables, or jump to a page.