iii-state-management

name	iii-state-management
description	Creates scoped key-value stores, reads and writes state entries, lists keys, and performs partial updates across functions. Use when persisting data between invocations, managing user sessions, caching computed values, storing feature flags, sharing state between workers, or building a KV data layer as an alternative to Redis or DynamoDB.

State Management

Comparable to: Redis, DynamoDB, Memcached

Key Concepts

Use the concepts below when they fit the task. Not every state operation needs all of them.

• State is a scoped key-value store accessed via built-in trigger functions
• Install or enable state with iii worker add iii-state
• state::set writes a value; state::get reads it (returns null for missing keys)
• state::list retrieves all keys in a scope; state::delete removes a key
• state::list_groups lists scopes that contain state data
• state::update performs a partial merge using an ops array for fine-grained changes
• Payloads use scope, key, and value to address state entries
• State is shared across all functions — use meaningful scope names to avoid collisions

Architecture

Function
  → trigger('state::set', { scope, key, value })
  → trigger('state::get', { scope, key })
  → trigger('state::update', { scope, key, ops })
  → trigger('state::delete', { scope, key })
  → trigger('state::list', { scope })
    → iii-state → KvStore / Redis adapter

iii Primitives Used

Primitive	Purpose
trigger({ function_id: 'state::set', payload })	Write a value to state
trigger({ function_id: 'state::get', payload })	Read a value from state
trigger({ function_id: 'state::list', payload })	List all keys in a scope
trigger({ function_id: 'state::list_groups', payload })	List state scopes
trigger({ function_id: 'state::delete', payload })	Remove a key from state
trigger({ function_id: 'state::update', payload: { ops } })	Partial merge with operations array

Reference Implementation

See ../references/state-management.js for the full working example — functions that read, write, update, and delete state entries across a shared scope.

Also available in Python: ../references/state-management.py

Also available in Rust: ../references/state-management.rs

Common Patterns

Code using this pattern commonly includes, when relevant:

• registerWorker(url, { workerName }) — worker initialization
• trigger({ function_id: 'state::set', payload: { scope, key, value } }) — write state
• trigger({ function_id: 'state::get', payload: { scope, key } }) — read state (returns null if missing)
• trigger({ function_id: 'state::update', payload: { scope, key, ops } }) — partial merge
• trigger({ function_id: 'state::list', payload: { scope } }) — enumerate keys
• trigger({ function_id: 'state::list_groups', payload: {} }) — enumerate scopes
• trigger({ function_id: 'state::delete', payload: { scope, key } }) — remove entry
• const logger = new Logger() — structured logging

Adapting This Pattern

Use the adaptations below when they apply to the task.

• Name scopes after your domain (e.g. user-sessions, order-data, config)
• Use state::get with a null check to handle missing keys gracefully
• Use state::update with ops for partial updates instead of read-modify-write cycles
• Combine with iii-queue-processing to persist results after async job completion

Engine Configuration

Install/enable iii-state with iii worker add iii-state. Configure either the kv adapter (file-based or in-memory) or Redis. See ../references/iii-config.yaml for the full annotated config reference.

Pattern Boundaries

• If the task needs reactive side effects when state changes, prefer iii-state-reactions.
• If the task needs real-time client push when data updates, prefer iii-realtime-streams.
• Stay with iii-state-management when the primary need is reading and writing persistent key-value data.

When to Use

• Use this skill when the task is primarily about iii-state-management in the iii engine.
• Triggers when the request directly asks for this pattern or an equivalent implementation.

Boundaries

• Never use this skill as a generic fallback for unrelated tasks.
• You must not apply this skill when a more specific iii skill is a better fit.
• Always verify environment and safety constraints before applying examples from this skill.