> ## Documentation Index
> Fetch the complete documentation index at: https://motiadev-docs-deployment-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# React to State Changes

> How to run a Function automatically when a state value changes.

## Goal

Run a Function whenever a specific state value changes, using a `state` trigger.

## Steps

### 1. Enable the State module

```yaml title="iii-config.yaml" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
modules:
  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::KvStore
        config:
          store_method: file_based  # Options: in_memory, file_based
          file_path: ./data/state_store.db  # required for file_based
```

### 2. Register the Function

The `state` trigger fires whenever the watched `scope`/`key` pair changes. The handler receives an event with `key`, `new_value`, `old_value`, `scope`, and `event_type` properties.

<Tabs>
  <Tab title="Node / TypeScript">
    ```typescript title="state-watcher.ts" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    import { registerWorker, Logger } from 'iii-sdk'

    const iii = registerWorker(process.env.III_URL ?? 'ws://localhost:49134')

    iii.registerFunction({ id: 'orders::on-status-change' }, async (event) => {
      const logger = new Logger()
      logger.info('Order status changed', { key: event.key, new_value: event.new_value })
      // ...react to the change here...
      return { handled: true }
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python title="state_watcher.py" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    import os

    from iii import Logger, register_worker

    iii = register_worker(os.environ.get("III_URL", "ws://localhost:49134"))


    def on_status_change(event):
        logger = Logger()
        logger.info("Order status changed", {"key": event["key"], "new_value": event["new_value"]})
        # ...react to the change here...
        return {"handled": True}


    iii.register_function({"id": "orders::on-status-change"}, on_status_change)
    ```
  </Tab>

  <Tab title="Rust">
    ```rust title="state_watcher.rs" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    use iii_sdk::{register_worker, InitOptions, Logger, RegisterFunctionMessage};
    use serde_json::json;
    use tokio::signal;

    #[tokio::main]
    async fn main() -> Result<(), Box<dyn std::error::Error>> {
        let url = std::env::var("III_URL").unwrap_or_else(|_| "ws://127.0.0.1:49134".to_string());
        let iii = register_worker(&url, InitOptions::default());

        iii.register_function(
            RegisterFunctionMessage::with_id("orders::on-status-change".into()),
            |event| async move {
                let logger = Logger::new();
                logger.info("Order status changed", Some(json!({ "key": event["key"], "new_value": event["new_value"] })));
                // ...react to the change here...
                Ok(json!({ "handled": true }))
            },
        );

        println!("Watching orders/status for changes");
        signal::ctrl_c().await?;
        Ok(())
    }
    ```
  </Tab>
</Tabs>

### 3. Register the state trigger

Each state trigger watches a single `scope`/`key` pair. To react to multiple keys, register a function and trigger for each.

<Tabs>
  <Tab title="Node / TypeScript">
    ```typescript title="state-trigger.ts" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    iii.registerTrigger({
      type: 'state',
      function_id: 'orders::on-status-change',
      config: { scope: 'orders', key: 'status' },
    })

    // Then run iii.trigger() from another function or worker to trigger the state change
    await iii.trigger({
      function_id: 'state::set',
      payload: {
        scope: 'orders',
        key: 'status',
        value: { orderId: 'order-123', status: 'shipped' },
      },
    })
    ```
  </Tab>

  <Tab title="Python">
    ```python title="state_trigger.py" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    iii.register_trigger({
        "type": "state",
        "function_id": "orders::on-status-change",
        "config": {"scope": "orders", "key": "status"},
    })

    # Then run iii.trigger() from another function or worker to trigger the state change
    iii.trigger({
        "function_id": "state::set",
        "payload": {
            "scope": "orders",
            "key": "status",
            "value": {"orderId": "order-123", "status": "shipped"},
        },
    })
    ```
  </Tab>

  <Tab title="Rust">
    ```rust title="state_trigger.rs" theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
    use iii_sdk::{RegisterTriggerInput, TriggerRequest};
    use serde_json::json;

    iii.register_trigger(RegisterTriggerInput {
        trigger_type: "state".into(),
        function_id: "orders::on-status-change".into(),
        config: json!({ "scope": "orders", "key": "status" }),
    })?;

    // Then run iii.trigger() from another function or worker to trigger the state change
    iii.trigger(TriggerRequest {
        function_id: "state::set".into(),
        payload: json!({
            "scope": "orders",
            "key": "status",
            "value": { "orderId": "order-123", "status": "shipped" },
        }),
        action: None,
        timeout_ms: None,
    }).await?;
    ```
  </Tab>
</Tabs>

## Result

When any Function writes to the watched `scope`/`key` pair via `state::set` or `state::update`, the Engine automatically invokes the registered handler with the new value.

{/* <Info title="See also">
For advanced state operations and adapter options, see the [State module reference](../modules/module-state).
</Info> */}