skip to content
iii / worker
$worker

state

v0.22.3-rc.2

Distributed key-value state management with reactive change triggers — registers the `state` trigger type and the `state::*` functions.

iiiverified
4,788 installs1,207 in 7d7 today
install
$iii worker add state@0.22.3-rc.2
binarylicense: Apache-2.0key-valuekvstatedistributedcache
  • Linux: x64
12functions1triggers1skills1depsv0.22.3-rc.2version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

12

state::barrier

function

Fan-in gate: record one arrival against a barrier and answer the typed condition decision — `skip` until the expected set has arrived, then `allow` EXACTLY ONCE carrying every arrival's payload. Use as a binding condition so a coordinator wakes once when N producers finish instead of once per producer.

request
  • condition_configany of
    any of (2)
    variant 1
    • carrystring

      JSON pointer into the event for the value to accumulate (default: the whole event).

    • expectall ofrequired

      A count, or the exact set of arrival keys.

      … expand 1 nested
      all of (1)
      variant 1
      any of (2)
      variant 1
      valueinteger· uint641…10000
      variant 2
      itemsstring[]
    • idstringrequired

      Barrier identity. Two bindings sharing an id share the barrier — that is how several predecessors feed one downstream.

    • key_fromstring

      JSON pointer into the event for the arrival key (default `/key`, the state event's own key). A missing pointer is an error, not a silent unnamed arrival: two arrivals that both resolve to nothing would collapse into one and the barrier would never complete.

    variant 2
    valuenull
  • eventunknown
response
one of (2)
variant 1
  • decisionstringrequiredenum: allow
  • payloadunknown
  • reasonstringrequired
variant 2
  • decisionstringrequiredenum: skip
  • reasonstringrequired

state::claim-namespace

function

Reserve a PRIVATE state namespace for the calling worker: its scopes become invisible to public state::* and to trigger fan-out, and internal accessors `<functions_prefix>::state::{get, list, compare-and-set}` are registered. A worker may only claim the namespace matching its own worker name (engine-stamped caller identity). Idempotent; claims survive a state restart.

request
  • _caller_worker_idstring
  • functions_prefixstringrequired

    Must equal the calling worker's name.

  • scopesstring[]required

    Storage scopes to reserve for this namespace.

response
  • claimedbooleanrequired

    False when the namespace already owned everything asked for.

  • functionsstring[]required

    The accessor ids now serving this namespace.

  • scopesstring[]required

    Every scope this namespace owns after the call.

state::compare-and-set

function

Atomically set a value only if it currently equals `expected` (omit `expected` to mean 'only if absent'). Returns { swapped, current } — on a miss, `current` is what is actually there, so a caller can recompute and retry. The primitive for counters, claims and any read-modify-write that two callers might race.

request
  • expectedunknown

    The value the caller believes is there. Omit to mean "expect absent" — the set-if-absent form.

  • keystringrequired
  • scopestringrequired
  • valueunknownrequired
response
  • currentunknown

    What is actually stored, when the swap did not happen.

  • swappedbooleanrequired

state::delete

function

Delete a value from state

request
  • keystringrequired

    Identifier for the value to delete within the scope.

  • scopestringrequired

    Namespace that groups related keys.

response
valuestring

state::get

function

Get a value from state

request
  • keystringrequired

    Identifier for the value within the scope.

  • scopestringrequired

    Namespace that groups related keys.

response
valuestring

state::list

function

Get a group from state

request
  • scopestringrequired

    Namespace whose keys should be listed as a group.

response
valuestring

state::list_groups

function

List all state groups

request
empty object
response
  • groupsstring[]required

state::list_keys

function

List the keys stored in a scope

request
  • scopestringrequired

    Namespace whose keys should be listed as a group.

response
  • keysstring[]required

    Keys stored in the scope, in the adapter's natural order.

state::on-config-change

function

Internal: reload state configuration from the authoritative store on change.

request
empty object
response
  • okbooleanrequired

state::set

function

Set a value in state

request
  • keystringrequired

    Identifier for the value within the scope.

  • scopestringrequired

    Namespace that groups related keys (e.g. `users`, `orders`).

  • valueunknownrequired

    Arbitrary JSON value to store. Replaces any existing value at `scope`/`key`.

response
  • new_valueunknownrequired

    The value after the update

  • old_valueunknown

    Previous value (if it existed).

state::ui-content

function

Serve the state worker's injected console UI assets (content function for its console:script / console:style triggers).

request
  • pathstringrequired

    The asset path from the trigger config (e.g. `state/page.js`).

response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

state::update

function

Update a value in state

request
  • keystringrequired

    Identifier for the value to update within the scope.

  • opsone of[]required

    Ordered list of update operations applied atomically to the existing value.

    one of (6)
    variant 1
    • pathstringrequired
    • typestringrequiredenum: set
    • valueunknown
    variant 2
    • pathany of
      … expand 2 nested
      any of (2)
      variant 1
      any of (2)
      variant 1
      valuestring
      variant 2
      itemsstring[]
      variant 2
      valuenull
    • typestringrequiredenum: merge
    • valueunknownrequired
    variant 3
    • byinteger· int64required
    • pathstringrequired
    • typestringrequiredenum: increment
    variant 4
    • byinteger· int64required
    • pathstringrequired
    • typestringrequiredenum: decrement
    variant 5
    • pathany of
      … expand 2 nested
      any of (2)
      variant 1
      any of (2)
      variant 1
      valuestring
      variant 2
      itemsstring[]
      variant 2
      valuenull
    • typestringrequiredenum: append
    • valueunknownrequired
    variant 6
    • pathstringrequired
    • typestringrequiredenum: remove
  • scopestringrequired

    Namespace that groups related keys.

response
  • errorsobject[]

    Errors encountered while applying ops. Successfully applied ops are still reflected in `new_value`. Field is omitted from JSON when empty for backward compatibility.

    • codestringrequired

      Stable error code, e.g. `"merge.path.too_deep"`.

    • doc_urlstring

      Optional documentation URL for this error class.

    • messagestringrequired

      Human-readable description with concrete numbers when applicable.

    • op_indexinteger· uintrequiredmin 0

      Index of the offending op within the original `ops` array.

  • new_valueunknownrequired

    The value after the update

  • old_valueunknown

    Previous value (if it existed).

triggers

1

state

trigger

State trigger

invocation
  • condition_function_idstring

    Optional function evaluated per event; only an explicit `false` skips.

  • keystring

    Only fire for writes to this key (any key when unset).

  • scopestring

    Only fire for writes in this scope (any scope when unset).

return
  • event_typeall ofrequired

    Type of state change

    all of (1)
    variant 1
    valuestringenum: state:created, state:updated, state:deleted
  • keystringrequired

    State key

  • new_valueunknownrequired

    New value

  • old_valueunknown

    Previous value (null for created events)

  • scopestringrequired

    State scope

  • typestringrequired

    Always "state"