Struct StateSerialization 

pub struct StateSerialization { /* private fields */ }

Process-global field encoders, field decoders and tagged JSON decoders.

Registrations are exact names and replacements affect the next operation. Each operation retains one registry snapshot and invokes callbacks without holding its lock. The only construction entrypoint is Self::global.

use app_kit::workflow::StateSerialization;
StateSerialization::global().register_tag("text".into(), |value| {
value.get("value").cloned().ok_or("missing text value")
})?;

Only field/tag JSON codecs enter this registry; actions, hooks, child executors and lower backends remain concrete configuration values. Registration does not persist callable identity; callers version their own portable codec payloads.

Implementations

impl StateSerialization

pub fn global() -> &'static Self

Returns the one process-global registry, shared across all state owners.

use app_kit::workflow::{StateSerialization, WorkflowState};
assert!(std::ptr::eq(StateSerialization::global(), StateSerialization::global()));
StateSerialization::global().register_tag("global_counter".into(), |value| {
    value.get("count").cloned().ok_or("missing count")
})?;
let encoded = serde_json::from_str(r#"{"count":{"__burr_serde__":"global_counter","count":3}}"#)?;
assert_eq!(WorkflowState::deserialize(encoded)?.values()["count"], 3);

Examples found in repository

examples/state.rs (line 92)

fn main() -> Result<(), AppError> {
    let policy = CountPolicy { maximum: 100 };
    let initial = WorkflowState::new(Map::from_iter([
        ("count".into(), json!(1)),
        ("labels".into(), json!([])),
    ]))?;
    let counted = initial.apply(
        &StateChange::Increment {
            values: vec![("count".into(), json!(3)), ("count".into(), json!(4))],
        },
        &policy,
    )?;
    let labeled = counted.apply(
        &StateChange::Append {
            values: vec![
                ("labels".into(), json!("draft")),
                ("labels".into(), json!("queued")),
            ],
        },
        &policy,
    )?;
    assert_eq!(initial.values()["count"], 1);
    assert_eq!(labeled.values()["count"], 8);
    assert_eq!(labeled.values()["labels"], json!(["draft", "queued"]));

    // A later invalid entry rejects the complete operation, including count + 1.
    let rejected = labeled.apply(
        &StateChange::Increment {
            values: vec![("count".into(), json!(1)), ("labels".into(), json!(1))],
        },
        &policy,
    );
    assert!(matches!(rejected, Err(AppError::InvalidInput(_))));
    assert_eq!(labeled.values()["count"], 8);

    // This registration is process-global. This standalone example owns its
    // process; an application should choose registrations during its setup.
    StateSerialization::global().register_field(
        "labels".into(),
        |value| Ok::<_, &'static str>(json!({"version": 1, "items": value})),
        |value| value.get("items").cloned().ok_or("missing labels.items"),
    )?;
    let encoded = labeled.serialize()?;
    assert_eq!(
        encoded["labels"],
        json!({"version":1,"items":["draft","queued"]})
    );
    let decoded = WorkflowState::deserialize(encoded.clone())?;
    assert_eq!(decoded, labeled);

    StateSerialization::global().register_tag("example-money".into(), |value| {
        value.get("minor").cloned().ok_or("missing money.minor")
    })?;
    let tagged = WorkflowState::deserialize(Map::from_iter([(
        "amount".into(),
        json!({"__burr_serde__":"example-money","minor":120}),
    )]))?;
    assert_eq!(tagged.values()["amount"], 120);
    println!("{}", Value::Object(encoded));
    Ok(())
}

pub fn register_field<S, D, SE, DE>( &self, field: String, serialize: S, deserialize: D, ) -> Result<(), AppError>

where S: Fn(&Value) -> Result<Value, SE> + Send + Sync + 'static, D: Fn(&Value) -> Result<Value, DE> + Send + Sync + 'static, SE: Display, DE: Display,

Registers or replaces both transformations for one exact top-level field.

Encoders must return objects; decoders may return any valid JSON value. Callback errors retain their Display text plus field and direction context. Neither callback invocation nor destruction of replaced captures holds the registry lock. An in-flight operation keeps its original callbacks.

use app_kit::workflow::{StateSerialization, WorkflowState};
use serde_json::{json, Map, Value};
StateSerialization::global().register_field(
"distance_meters".into(),
|value| Ok::<_, String>(json!({"meters": value})),
|value| value.get("meters").cloned().ok_or("missing meters"),
)?;
let state = WorkflowState::new(Map::from_iter([
("distance_meters".into(), Value::from(12)),
]))?;
let encoded = state.serialize()?;
assert_eq!(encoded["distance_meters"], json!({"meters": 12}));
assert_eq!(WorkflowState::deserialize(encoded)?, state);

Errors

Returns Integration if the registry lock is poisoned. Callback results are validated when encoding/decoding, not during registration; exact field names replace prior registrations for future operations.

Examples found in repository

examples/state.rs (lines 92-96)

fn main() -> Result<(), AppError> {
    let policy = CountPolicy { maximum: 100 };
    let initial = WorkflowState::new(Map::from_iter([
        ("count".into(), json!(1)),
        ("labels".into(), json!([])),
    ]))?;
    let counted = initial.apply(
        &StateChange::Increment {
            values: vec![("count".into(), json!(3)), ("count".into(), json!(4))],
        },
        &policy,
    )?;
    let labeled = counted.apply(
        &StateChange::Append {
            values: vec![
                ("labels".into(), json!("draft")),
                ("labels".into(), json!("queued")),
            ],
        },
        &policy,
    )?;
    assert_eq!(initial.values()["count"], 1);
    assert_eq!(labeled.values()["count"], 8);
    assert_eq!(labeled.values()["labels"], json!(["draft", "queued"]));

    // A later invalid entry rejects the complete operation, including count + 1.
    let rejected = labeled.apply(
        &StateChange::Increment {
            values: vec![("count".into(), json!(1)), ("labels".into(), json!(1))],
        },
        &policy,
    );
    assert!(matches!(rejected, Err(AppError::InvalidInput(_))));
    assert_eq!(labeled.values()["count"], 8);

    // This registration is process-global. This standalone example owns its
    // process; an application should choose registrations during its setup.
    StateSerialization::global().register_field(
        "labels".into(),
        |value| Ok::<_, &'static str>(json!({"version": 1, "items": value})),
        |value| value.get("items").cloned().ok_or("missing labels.items"),
    )?;
    let encoded = labeled.serialize()?;
    assert_eq!(
        encoded["labels"],
        json!({"version":1,"items":["draft","queued"]})
    );
    let decoded = WorkflowState::deserialize(encoded.clone())?;
    assert_eq!(decoded, labeled);

    StateSerialization::global().register_tag("example-money".into(), |value| {
        value.get("minor").cloned().ok_or("missing money.minor")
    })?;
    let tagged = WorkflowState::deserialize(Map::from_iter([(
        "amount".into(),
        json!({"__burr_serde__":"example-money","minor":120}),
    )]))?;
    assert_eq!(tagged.values()["amount"], 120);
    println!("{}", Value::Object(encoded));
    Ok(())
}

pub fn register_tag<D, DE>( &self, tag: String, deserialize: D, ) -> Result<(), AppError>

where D: Fn(&Value) -> Result<Value, DE> + Send + Sync + 'static, DE: Display,

Registers or replaces a decoder for an exact __burr_serde__ tag string.

Empty strings are valid names. The decoder receives the complete original tagged object. Its output is terminal: it is not dispatched or recursively decoded again. Ordinary untagged containers are decoded recursively.

use app_kit::workflow::{StateSerialization, WorkflowState};
use serde_json::{json, Map};
StateSerialization::global().register_tag("distance".into(), |value| {
value.get("meters").cloned().ok_or("missing meters")
})?;
let state = WorkflowState::deserialize(Map::from_iter([(
"route".into(),
json!([{"__burr_serde__": "distance", "meters": 12}]),
)]))?;
assert_eq!(state.values()["route"], json!([12]));

Errors

Returns Integration if the registry lock is poisoned. Decoder failures occur at decode time and preserve caller error text with tag context.

Examples found in repository

examples/state.rs (lines 105-107)

fn main() -> Result<(), AppError> {
    let policy = CountPolicy { maximum: 100 };
    let initial = WorkflowState::new(Map::from_iter([
        ("count".into(), json!(1)),
        ("labels".into(), json!([])),
    ]))?;
    let counted = initial.apply(
        &StateChange::Increment {
            values: vec![("count".into(), json!(3)), ("count".into(), json!(4))],
        },
        &policy,
    )?;
    let labeled = counted.apply(
        &StateChange::Append {
            values: vec![
                ("labels".into(), json!("draft")),
                ("labels".into(), json!("queued")),
            ],
        },
        &policy,
    )?;
    assert_eq!(initial.values()["count"], 1);
    assert_eq!(labeled.values()["count"], 8);
    assert_eq!(labeled.values()["labels"], json!(["draft", "queued"]));

    // A later invalid entry rejects the complete operation, including count + 1.
    let rejected = labeled.apply(
        &StateChange::Increment {
            values: vec![("count".into(), json!(1)), ("labels".into(), json!(1))],
        },
        &policy,
    );
    assert!(matches!(rejected, Err(AppError::InvalidInput(_))));
    assert_eq!(labeled.values()["count"], 8);

    // This registration is process-global. This standalone example owns its
    // process; an application should choose registrations during its setup.
    StateSerialization::global().register_field(
        "labels".into(),
        |value| Ok::<_, &'static str>(json!({"version": 1, "items": value})),
        |value| value.get("items").cloned().ok_or("missing labels.items"),
    )?;
    let encoded = labeled.serialize()?;
    assert_eq!(
        encoded["labels"],
        json!({"version":1,"items":["draft","queued"]})
    );
    let decoded = WorkflowState::deserialize(encoded.clone())?;
    assert_eq!(decoded, labeled);

    StateSerialization::global().register_tag("example-money".into(), |value| {
        value.get("minor").cloned().ok_or("missing money.minor")
    })?;
    let tagged = WorkflowState::deserialize(Map::from_iter([(
        "amount".into(),
        json!({"__burr_serde__":"example-money","minor":120}),
    )]))?;
    assert_eq!(tagged.values()["amount"], 120);
    println!("{}", Value::Object(encoded));
    Ok(())
}