Agent skill

iii-state-reactions

Registers state-type triggers that automatically fire functions when key-value state is created, updated, or deleted within a scope. Use when building reactive side effects, change watchers, audit logs, cache invalidation, notification dispatchers, or any observer pattern where data changes should trigger downstream processing.

Stars 15,297
Forks 1,022

Install this agent skill to your Project

npx add-skill https://github.com/iii-hq/iii/tree/main/skills/iii-state-reactions

SKILL.md

State Reactions

Comparable to: Firebase onSnapshot, Convex mutations

Key Concepts

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

  • A state trigger fires whenever a value changes within a watched scope
  • The handler receives { new_value, old_value, key, event_type } describing the change
  • condition_function_id gates execution — the reaction only fires if the condition returns truthy
  • Multiple reactions can independently watch the same scope
  • Reactions fire on state::set, state::update, and state::delete operations

Architecture

state::set, state::update, or state::delete
  → iii-state emits change event
    → registerTrigger type:'state' (scope match)
      → condition_function_id check (if configured)
        → registerFunction handler ({ new_value, old_value, key, event_type })

iii Primitives Used

Primitive Purpose
registerFunction Define the reaction handler
registerTrigger({ type: 'state' }) Watch a scope for changes
config: { scope, key, condition_function_id } Scope filter and optional condition gate
Event payload: { new_value, old_value, key, event_type } Change details passed to the handler

Reference Implementation

See ../references/state-reactions.js for the full working example — a reaction that watches a state scope and fires side effects when values change, with an optional condition gate.

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

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

Common Patterns

Code using this pattern commonly includes, when relevant:

  • registerWorker(url, { workerName }) — worker initialization
  • registerFunction(id, handler) — define the reaction handler
  • registerTrigger({ type: 'state', function_id, config: { scope, key, condition_function_id } }) — watch for changes
  • payload.new_value / payload.old_value — compare before and after
  • payload.event_type — distinguish between set, update, and delete events
  • trigger({ function_id: 'state::set', payload }) — write derived state from the reaction
  • const logger = new Logger() — structured logging per reaction

Adapting This Pattern

Use the adaptations below when they apply to the task.

  • Set scope to watch a specific domain (e.g. orders, user-profiles)
  • Use key to narrow reactions to a single key within a scope
  • Add a condition_function_id to filter — only react when the condition function returns truthy
  • Chain reactions by writing state in one handler that triggers another reaction on a different scope

Engine Configuration

iii-state must be enabled in iii-config.yaml for state triggers to fire. See ../references/iii-config.yaml for the full annotated config reference.

Pattern Boundaries

  • If the task is about directly reading or writing state without reactions, prefer iii-state-management.
  • If the task needs conditional trigger logic shared across trigger types, prefer iii-trigger-conditions.
  • Stay with iii-state-reactions when the primary need is automatic side effects on state changes.

When to Use

  • Use this skill when the task is primarily about iii-state-reactions in the iii engine.
  • Use this skill 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.

Expand your agent's capabilities with these related and highly-rated skills.

iii-hq/iii

iii-dead-letter-queues

Inspects and redrives jobs that exhausted all retries. Use when handling failed queue jobs, debugging processing errors, or implementing retry strategies.

15,297 1,022
Explore
iii-hq/iii

iii-cron-scheduling

Registers cron triggers with 7-field expressions to run functions on recurring schedules. Use when scheduling periodic jobs, timed automation, crontab replacements, cleanup routines, report generation, health checks, batch processing, or any task that should run every N seconds, minutes, hours, or on a weekly/monthly calendar.

15,297 1,022
Explore
iii-hq/iii

iii-http-invoked-functions

Registers external HTTP endpoints as iii functions using registerFunction(id, HttpInvocationConfig). Use when adapting legacy APIs, third-party webhooks, or immutable services into triggerable iii functions, especially when prompts ask for endpoint maps like { path, id } iterated into registerFunction calls.

15,297 1,022
Explore
iii-hq/iii

iii-channels

Binary streaming between workers via channels. Use when building data pipelines, file transfers, streaming responses, or any pattern requiring binary data transfer between functions.

15,297 1,022
Explore
iii-hq/iii

iii-event-driven-cqrs

Implements CQRS with event sourcing on the iii engine. Use when building command/query separation, event-sourced systems, or fan-out architectures where commands publish domain events and multiple read model projections subscribe independently.

15,297 1,022
Explore
iii-hq/iii

iii-agentic-backend

Creates and orchestrates multi-agent pipelines on the iii engine. Use when building AI agent collaboration, agent orchestration, research/review/synthesis chains, or any system where specialized agents hand off work through queues and shared state.

15,297 1,022
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results