A framework for creating updatable data structures with diff, update, and merge capabilities.

structupdate provides a derive macro and runtime types for building complex data structures that support:

• Type-safe updates: Modify structures through strongly-typed update operations
• Efficient diffing: Compute minimal differences between two instances
• Merge operations: Combine structures for templating scenarios
• Serialization: Full serde support for all types

Quick Start

use structupdate::{structupdate, Node, Value, ValueMap};

#[structupdate]
// #[structupdate] only works on types that are Clone + PartialEq + Default
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Config {
    pub name: Value<String>,
    pub settings: ValueMap<String, u32>,
}

// Create a default instance
let mut config = Config::default();
// Keep a copy of the original value for the sake of the example
let original = config.clone();

// Build an update
let mut update = Config::build_update();
update
    .name_set("my-config".to_string())
    .settings_set("timeout".to_string(), 30);

// Apply the update
config.apply_update(update);

// Compute diff between instances
if let Some(diff) = original.compute_diff(&config) {
    // diff contains only the changes
}

Values vs Records

This crate distinguishes between values and records:

• A value is a leaf type (e.g., String, u32, bool) that is replaced atomically when updated. Values are wrapped in types like [Value<V>], [OptValue<V>], [ValueList<V>], [ValueSet<K>], or [ValueMap<K, V>].

• A record is a nested struct that also uses #[structupdate] and implements the [Node] trait. Records support in-place updates to their fields without replacing the entire struct. Records appear in types like [OptRecord<R>], [RecordMap<K, R>], or directly as struct fields.

This distinction matters for updates: when you update a value, you replace it entirely; when you update a record, you can modify individual fields within it.

Field Types

The macro recognizes these wrapper types for struct fields:

The #[structupdate] Macro

When applied to a struct, the macro generates:

• A {StructName}Update that represents a set of changes to update a StructName value
• A {StructName}Diff type for representing differences between two StructName values
• Implementation of the [Node] trait
• Builder methods on the {StructName}Update type

Macro Attributes

Struct-level: #[mark(...)]

This is an optional attribute which adds a metadata field to the struct for tracking purposes:

# use structupdate::structupdate;
# use structupdate::Value;

#[structupdate]
#[mark(serde_skip, type = bool)]
#[derive(Debug, PartialEq, Clone, serde::Serialize, serde::Deserialize)]
pub struct Record {
    pub field: Value<String>,
}

Options:

• type = T: The type of the mark field (required)
• serde_skip: Skip the mark field when serializing/deserializing the type. This option is only valid when the type derives the serde::Serialize and/or serde::Deserialize

Field-level: #[structupdate(init_with = ...)]

Specify a custom default value constructor for [Value<V>] fields:

# use structupdate::structupdate;
# use structupdate::Value;
fn default_timeout() -> u32 { 30 }

#[structupdate]
#[derive(Debug, PartialEq, Eq, Clone)]
pub struct Config {
    #[structupdate(init_with = default_timeout)]
    pub timeout: Value<u32>,
}

Generated Update API

For each field, the macro generates builder methods on the update type:

The Node Trait

All updatable types implement the [Node] trait, which provides:

• apply_update: Apply an update to modify the structure
• compute_diff: Calculate differences between instances
• apply_diff: Apply a diff to transform the structure
• merge: Merge values for templating

Default Value Helpers

The [defaults] module provides helper functions for creating [Value] instances with custom defaults:

use structupdate::defaults::{value_true, default_string, default_u32};

// These return closures suitable for init_with
let make_name = default_string("unnamed");
let make_timeout = default_u32(30);