Crate morphix 

morphix

A Rust library for observing and serializing mutations.

Installation

Add this to your Cargo.toml:

[dependencies]
morphix = { version = "0.12", features = ["json"] }

Basic Usage

use serde::Serialize;
use serde_json::json;
use morphix::adapter::Json;
use morphix::{Mutation, MutationKind, Observe, observe};

// 1. Define any data structure with `#[derive(Observe)]`.
#[derive(Serialize, PartialEq, Debug, Observe)]
struct Foo {
    pub bar: Bar,
    pub qux: String,
}

#[derive(Serialize, PartialEq, Debug, Observe)]
struct Bar {
    pub baz: i32,
}

let mut foo = Foo {
    bar: Bar { baz: 42 },
    qux: "hello".to_string(),
};

// 2. Use `observe!` to mutate data and track mutations.
let Json(mutation) = observe!(foo => {
    foo.bar.baz += 1;
    foo.qux.push(' ');
    foo.qux += "world";
}).unwrap();

// 3. Inspect the mutations.
assert_eq!(
    mutation,
    Some(Mutation {
        path: vec![].into(),
        kind: MutationKind::Batch(vec![
            Mutation {
                path: vec!["bar".into(), "baz".into()].into(),
                kind: MutationKind::Replace(json!(43)),
            },
            Mutation {
                path: vec!["qux".into()].into(),
                kind: MutationKind::Append(json!(" world")),
            },
        ]),
    }),
);

// 4. The original data structure is also mutated.
assert_eq!(
    foo,
    Foo {
        bar: Bar { baz: 43 },
        qux: "hello world".to_string(),
    },
);

Mutation Types

Morphix recognizes three types of mutations:

Replace

The most general mutation type, used for any mutation that replaces a value:

foo.a.b = 1;        // Replace at .a.b
foo.num *= 2;       // Replace at .num
foo.vec.clear();    // Replace at .vec

Append

Optimized for appending to strings and vectors:

foo.a.b += "text";          // Append to .a.b
foo.a.b.push_str("text");   // Append to .a.b
foo.vec.push(1);            // Append to .vec
foo.vec.extend(iter);       // Append to .vec

Truncate

Optimized for truncating strings and vectors:

foo.a.b.truncate(5);        // Truncate n-5 chars from .a.b
foo.vec.pop();              // Truncate 1 element from .vec

Batch

Multiple mutations combined into a single operation.

Features

• derive (default): Enables the Observe derive macro
• Mutation kinds:
  • append (default): Enables Append mutation kind
  • truncate (default): Enables Truncate mutation kind
• Adapters:
  • json: Includes JSON serialization support via serde_json
  • yaml: Includes YAML serialization support via serde_yaml_ng

Re-exports

pub use adapter::Adapter;

pub use observe::Observe;

Modules

adapter

Adapters for serializing mutations to different formats.

helper

Helper utilities for internal implementation details.

observe

Types and traits for observing mutations to data structures.

Macros

observederive

Observe and collect mutations within a closure.

Structs

BatchTree

A batch collector for aggregating and optimizing multiple mutations.

Mutation

A mutation representing a change to a value at a specific path.

Path

Enums

MutationError

Error types for mutation operations.

MutationKind

The kind of mutation that occurred.

PathSegment

Derive Macros

Observederive

Derive the Observe trait for structs to enable mutation tracking.