State

Distributed key-value state management with reactive change triggers.

Distributed key-value state storage with scope-based organization and reactive triggers that fire on any state change.

iii-state

Architecture

State is server-side key-value storage with trigger-based reactivity. Unlike streams, state does not push updates to WebSocket clients — it fires triggers that workers handle server-side.

Sample Configuration

- name: iii-state
  config:
    adapter:
      name: kv
      config:
        store_method: file_based
        file_path: ./data/state_store
        save_interval_ms: 5000

Configuration

adapter · Adapter

The adapter to use for state persistence and distribution. Defaults to kv when not specified.

Adapters

kv

Built-in key-value store. Supports both in-memory and file-based persistence.

name: kv
config:
  store_method: file_based
  file_path: ./data/state_store
  save_interval_ms: 5000

Configuration

store_method · string

Storage method. Options: in_memory (lost on restart) or file_based (persisted to disk).

file_path · string

Directory path for file-based storage. Each scope is stored as a separate file.

save_interval_ms · number

Interval in milliseconds between automatic disk saves. Defaults to 5000.

redis

Uses Redis as the state backend.

name: redis
config:
  redis_url: ${REDIS_URL:redis://localhost:6379}

Configuration

redis_url · string

The URL of the Redis instance to use.

bridge

Forwards state operations to a remote III Engine instance via the Bridge Client.

name: bridge

Functions

state::set · function

Set a value in state. Fires a state:created trigger if the key did not exist, or state:updated if it did.

Parameters

scope · string · required

The scope (namespace) to organize state within.

key · string · required

The key to store the value under.

value · any · required

The value to store. Can be any JSON-serializable value. Also accepted as data (backward-compatible alias).

Returns

old_value · any

The previous value, or null if the key did not exist.

new_value · any

The value that was stored.

state::get · function

Get a value from state.

Parameters

scope · string · required

The scope to read from.

key · string · required

The key to retrieve.

Returns

value · any

The stored value, or null if the key does not exist.

state::delete · function

Delete a value from state. Fires a state:deleted trigger.

Parameters

scope · string · required

The scope to delete from.

key · string · required

The key to delete.

Returns

value · any

The deleted value, or null if the key did not exist.

state::update · function

Atomically update a value using one or more operations. Fires state:created or state:updated depending on whether the key existed.

Parameters

scope · string · required

The scope to update within.

key · string · required

The key to update.

ops · UpdateOp[] · required

Array of update operations applied in order. Each operation is a tagged object with a type field and a path. Use path: "" (or omit path) to target the root value.

Operation	Shape	Description
set	{ "type": "set", "path": "status", "value": "active" }	Set a field or replace the root value.
merge	{ "type": "merge", "path": ["sessions", "abc"], "value": { "ts": "chunk" } }	Shallow-merge an object at the root or at any nested path.
increment	{ "type": "increment", "path": "count", "by": 1 }	Add by to a numeric field.
decrement	{ "type": "decrement", "path": "count", "by": 1 }	Subtract by from a numeric field.
append	{ "type": "append", "path": ["sessions", "abc", "events"], "value": { "kind": "chunk" } }	Push one element to an array (or concatenate a string) at the root, a first-level field, or any nested path.
remove	{ "type": "remove", "path": "status" }	Remove a field from the current object.

For set, increment, decrement, and remove, paths are first-level field names. For example, user.name updates the field named user.name; it does not traverse into { "user": { "name": ... } }.

For merge and append, path accepts either a single string (legacy / first-level field) or an array of literal segments for nested traversal:

// Root merge / append (existing behavior, unchanged).
{ "type": "merge", "path": "", "value": { "status": "active" } }
{ "type": "append", "path": "", "value": "first" }

// First-level merge / append into the field named "session-abc".
{ "type": "merge", "path": "session-abc", "value": { "author": "alice" } }
{ "type": "append", "path": "events", "value": { "kind": "chunk" } }

// Nested merge / append: walks the segments, auto-creating
// missing or non-object intermediates along the way.
{ "type": "merge", "path": ["sessions", "abc"], "value": { "ts": "chunk" } }
{ "type": "append", "path": ["sessions", "abc", "events"], "value": { "kind": "chunk" } }

Each array element is a literal key. ["a.b"] writes a single key named "a.b", not a → b.

For root operations (no path), the SDK encoders omit the path field from the wire payload entirely (e.g. { "type": "append", "value": "first" }) rather than emitting "path": null. Servers accept either form on input — null, missing, and empty string all route to the root.

Append at a nested missing leaf is always an array. When append walks to a missing leaf at the end of an array-form path, it creates [value] regardless of the value’s type — including string values, which would be kept as a string under the legacy single-string path’s string-concat tier. This is the core fix for issue #1552.

Append walks through array intermediates by replacing them with objects. When the path traverses an existing non-object intermediate (array, scalar, or null), the engine replaces it with a fresh {} and continues — mirroring merge’s walk_or_create semantics. So {"a": [1,2,3]} + append(["a", "b"], 42) yields {"a": {"b": [42]}} (the prior array at a is dropped). Callers that need to preserve the array should pre-check with state.get rather than relying on append to error.

Note on append.type_mismatch for nested paths: the structured append.type_mismatch error for object/scalar leaves shipped in #1555 for the single-string-path case. The nested-path form added here returns the same error code with the same shape, so consumers parsing errors[] need no new branches. Callers using path: "" or path: "field" against array, string, null, or missing-field leaves are unaffected.

Validation: invalid update inputs are rejected with a structured error in the response’s errors array. Reasons include path depth > 32 segments, segment > 256 bytes, value depth > 16, > 1024 top-level keys, type mismatches, non-object targets, or any segment / top-level key matching __proto__ / constructor / prototype. Successfully applied ops still reflect in new_value.

Returns

old_value · any

The value before the operations were applied, or null if the key did not exist.

new_value · any

The value after all operations were applied.

errors · UpdateOpError[]

Per-op validation errors. Field is omitted when empty. Each entry has op_index, code, message, and an optional doc_url.

Error codes

Each state::update op may add an entry to the response errors array. Operations are best-effort: successfully applied ops still reflect in new_value, and failed ops are skipped.

Code	Triggered when	Fix
set.target_not_object	set tried to write a field while the current value is not an object	Set the root to an object first, or use path: "" to replace the root.
append.target_not_object	append used a field path while the current value is not an object	Set the root to an object first, or append at path: "".
append.type_mismatch	append targeted an incompatible existing value, such as appending to a number or appending a non-string to a string	Match the appended value to the existing field type, or initialize the field to an array, string, or null.
increment.target_not_object	increment used a field path while the current value is not an object	Set the root to an object first.
increment.not_number	increment targeted an existing field that is not a number	Initialize the field as a number first, for example with set to 0.
decrement.target_not_object	decrement used a field path while the current value is not an object	Set the root to an object first.
decrement.not_number	decrement targeted an existing field that is not a number	Initialize the field as a number first, for example with set to 0.
remove.target_not_object	remove used a field path while the current value is not an object	Set the root to an object first. Removing a missing field from an object remains silent.
<op>.path.proto_polluted	A path segment is __proto__, constructor, or prototype	Use a different field name.
<op>.path.segment_too_long	A path segment is longer than 256 bytes	Shorten the field name or merge path segment.
merge.path.too_deep	A nested merge path has more than 32 segments	Reduce the nested path depth.
merge.path.empty_segment	A nested merge path array contains an empty segment	Remove the empty segment.
append.path.too_deep	A nested append path has more than 32 segments	Reduce the nested path depth.
append.path.empty_segment	A nested append path array contains an empty segment	Remove the empty segment.
merge.value.not_an_object	merge value is not a JSON object	Pass an object as the merge value.
merge.value.too_deep	merge value has JSON nesting deeper than 16 levels	Flatten the value.
merge.value.too_many_keys	merge value has more than 1024 top-level keys	Split the write into smaller updates.
merge.value.proto_polluted	A top-level key in the merge value is __proto__, constructor, or prototype	Use a different key name.

Each error includes op_index, code, and message; doc_url is optional.

{
  "old_value": { "name": "Ada" },
  "new_value": { "name": "Ada" },
  "errors": [
    {
      "op_index": 0,
      "code": "increment.not_number",
      "message": "Expected number at path 'name', got string.",
      "doc_url": "https://iii.dev/docs/workers/iii-state#error-codes"
    }
  ]
}

{
  "old_value": {},
  "new_value": {},
  "errors": [
    {
      "op_index": 0,
      "code": "set.path.proto_polluted",
      "message": "Path segment '__proto__' is not allowed (prototype pollution).",
      "doc_url": "https://iii.dev/docs/workers/iii-state#error-codes"
    }
  ]
}

state::list · function

List all values within a scope.

Parameters

scope · string · required

The scope to list entries from.

Returns

A flat JSON array of all stored values within the scope: any[].

state::list_groups · function

List all scopes that contain state data.

Returns

An object with a single groups field:

groups · string[]

A sorted, deduplicated array of all scope names that contain at least one key.

Trigger Type

This worker adds a new Trigger Type: state.

When a state value is created, updated, or deleted, all registered state triggers are evaluated and fired if they match.

Show Trigger Config

scope · string

Only fire for state changes within this scope. When omitted, fires for all scopes.

key · string

Only fire for state changes to this specific key. When omitted, fires for all keys.

condition_function_id · string

Function ID for conditional execution. The engine invokes it with the state event; if it returns false, the handler function is not called.

State Event Payload

When the trigger fires, the handler receives a state event object:

type · string

Always "state".

event_type · string

The kind of change: "state:created", "state:updated", or "state:deleted".

scope · string

The scope where the change occurred.

key · string

The key that changed.

old_value · any

The previous value before the change, or null for newly created keys.

new_value · any

The new value after the change. null for deleted keys.

Sample Code

Node / TypeScript

const fn = iii.registerFunction(
  { id: 'state::onUserUpdated' },
  async (event) => {
    console.log('State changed:', event.event_type, event.key)
    console.log('Previous:', event.old_value)
    console.log('Current:', event.new_value)
    return {}
  },
)

iii.registerTrigger({
  type: 'state',
  function_id: fn.id,
  config: { scope: 'users', key: 'profile' },
})

Python

def on_user_updated(event):
    print('State changed:', event['event_type'], event['key'])
    print('Previous:', event.get('old_value'))
    print('Current:', event.get('new_value'))
    return {}

iii.register_function("state::onUserUpdated", on_user_updated)
iii.register_trigger({'type': 'state', 'function_id': 'state::onUserUpdated', 'config': {'scope': 'users', 'key': 'profile'}})

Rust

use iii_sdk::RegisterFunctionMessage;

iii.register_function(
    RegisterFunctionMessage::with_id("state::onUserUpdated".into()),
    |event| async move {
        println!("State changed: {} {}", event["event_type"], event["key"]);
        println!("Previous: {:?}", event.get("old_value"));
        println!("Current: {:?}", event.get("new_value"));
        Ok(json!({}))
    },
);

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "state".into(),
    function_id: "state::onUserUpdated".into(),
    config: json!({
        "scope": "users",
        "key": "profile"
    }),
    metadata: None,
})?;

Usage Example: User Profile with Reactive Sync

Store user profiles in state and react when they change:

Node / TypeScript

await iii.trigger({
  function_id: 'state::set',
  payload: {
    scope: 'users',
    key: 'user-123',
    value: { name: 'Alice', email: '[e-mail]', preferences: { theme: 'dark' } },
  },
  action: TriggerAction.Void(),
})

const profile = await iii.trigger({
  function_id: 'state::get',
  payload: { scope: 'users', key: 'user-123' },
})

await iii.trigger({
  function_id: 'state::set',
  payload: {
    scope: 'users',
    key: 'user-123',
    value: { name: 'Alice', email: '[e-mail]', preferences: { theme: 'light' } },
  },
  action: TriggerAction.Void(),
})

const allUsers = await iii.trigger({
  function_id: 'state::list',
  payload: { scope: 'users' },
})
const scopes = await iii.trigger({
  function_id: 'state::list_groups',
  payload: {},
})

Python

iii.trigger({
    'function_id': 'state::set',
    'payload': {
        'scope': 'users',
        'key': 'user-123',
        'value': {'name': 'Alice', 'email': '[e-mail]', 'preferences': {'theme': 'dark'}},
    },
    'action': {'type': 'void'},
})

profile = iii.trigger({
    'function_id': 'state::get',
    'payload': {'scope': 'users', 'key': 'user-123'},
})

iii.trigger({
    'function_id': 'state::set',
    'payload': {
        'scope': 'users',
        'key': 'user-123',
        'value': {'name': 'Alice', 'email': '[e-mail]', 'preferences': {'theme': 'light'}},
    },
    'action': {'type': 'void'},
})

all_users = iii.trigger({
    'function_id': 'state::list',
    'payload': {'scope': 'users'},
})
scopes = iii.trigger({
    'function_id': 'state::list_groups',
    'payload': {},
})

Rust

use iii_sdk::{TriggerRequest, TriggerAction};
use serde_json::json;

iii.trigger(TriggerRequest {
    function_id: "state::set".into(),
    payload: json!({
        "scope": "users",
        "key": "user-123",
        "value": { "name": "Alice", "email": "[e-mail]", "preferences": { "theme": "dark" } }
    }),
    action: Some(TriggerAction::Void),
    timeout_ms: None,
}).await?;

let profile = iii.trigger(TriggerRequest {
    function_id: "state::get".into(),
    payload: json!({ "scope": "users", "key": "user-123" }),
    action: None,
    timeout_ms: None,
}).await?;

iii.trigger(TriggerRequest {
    function_id: "state::set".into(),
    payload: json!({
        "scope": "users",
        "key": "user-123",
        "value": { "name": "Alice", "email": "[e-mail]", "preferences": { "theme": "light" } }
    }),
    action: Some(TriggerAction::Void),
    timeout_ms: None,
}).await?;

let all_users = iii.trigger(TriggerRequest {
    function_id: "state::list".into(),
    payload: json!({ "scope": "users" }),
    action: None,
    timeout_ms: None,
}).await?;

let scopes = iii.trigger(TriggerRequest {
    function_id: "state::list_groups".into(),
    payload: json!({}),
    action: None,
    timeout_ms: None,
}).await?;

Usage Example: Conditional Trigger

Only process profile updates when the email field changed:

Node / TypeScript

const conditionFn = iii.registerFunction(
  { id: 'conditions::emailChanged' },
  async (event) =>
    event.event_type === 'state:updated' &&
    event.old_value?.email !== event.new_value?.email,
)

const fn = iii.registerFunction('state::onEmailChange', async (event) => {
  await sendVerificationEmail(event.new_value.email)
  return {}
})

iii.registerTrigger({
  type: 'state',
  function_id: fn.id,
  config: {
    scope: 'users',
    key: 'profile',
    condition_function_id: conditionFn.id,
  },
})

Python

def email_changed(event):
    if event.get('event_type') != 'state:updated':
        return False
    old = event.get('old_value', {})
    new = event.get('new_value', {})
    return old.get('email') != new.get('email')

iii.register_function("conditions::emailChanged", email_changed)

def on_email_change(event):
    send_verification_email(event['new_value']['email'])
    return {}

iii.register_function("state::onEmailChange", on_email_change)
iii.register_trigger({
    'type': 'state',
    'function_id': 'state::onEmailChange',
    'config': {
        'scope': 'users',
        'key': 'profile',
        'condition_function_id': 'conditions::emailChanged',
    },
})

Rust

use iii_sdk::{RegisterFunctionMessage, RegisterTriggerInput};
use serde_json::json;

iii.register_function(
    RegisterFunctionMessage::with_id("conditions::emailChanged".into()),
    |event| async move {
        let is_update = event["event_type"].as_str() == Some("state:updated");
        let old_email = event.get("old_value").and_then(|v| v.get("email"));
        let new_email = event.get("new_value").and_then(|v| v.get("email"));
        Ok(json!(is_update && old_email != new_email))
    },
);

iii.register_function(
    RegisterFunctionMessage::with_id("state::onEmailChange".into()),
    |event| async move {
        let email = event["new_value"]["email"].as_str().unwrap_or("");
        send_verification_email(email).await?;
        Ok(json!({}))
    },
);

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "state".into(),
    function_id: "state::onEmailChange".into(),
    config: json!({
        "scope": "users",
        "key": "profile",
        "condition_function_id": "conditions::emailChanged"
    }),
    metadata: None,
})?;

State Flow