deltapatcher
A Rust library for computing, composing, and applying deltas (diffs) between states, with built-in support for timelines, state caching, and efficient bidirectional seeking.
Overview
deltapatcher provides two core traits:
Differentiable<D>— implemented by any type that can compute a deltaDto/from another instance of itself, and apply one.Delta— implemented by the delta type itself, allowing deltas to be composed (aggregated) together.
Built-in implementations are provided for Vec<T>, slices [T], fixed-size arrays [T; N], and all primitive integer types (with more planned soon).
Features
| Feature | Description |
|---|---|
macros |
Enables the #[derive(Differentiable)] proc-macro to auto-generate delta types for structs/enums composed from differentiables |
serde |
Enables serde::Serialize/Deserialize on all delta and timeline types |
Core Concepts
Differentiable and Delta
use ;
let start = vec!;
let end = vec!;
// Compute the delta from `start` to `end`
let delta = end.diff;
// Apply it to a different starting state
let mut other = start.clone;
other.patch;
assert_eq!;
Delta Aggregation
Deltas can be composed together with aggregate / aggregate_owned. An aggregated delta A → C can reproduce the final state without ever materializing the intermediate state B:
let a_to_b = b.diff;
let b_to_c = c.diff;
let mut a_to_c = a_to_b;
a_to_c.aggregate_owned;
let mut result = a.clone;
result.patch;
assert_eq!;
This is especially useful in networking scenarios (e.g. game state sync, media streaming) where you want to send a single compact delta instead of multiple incremental ones or a full snapshot.
Built-in Delta Types
SliceDelta<T>— LCS-based diff forVec<T>,[T], and[T; N]. Stores changes as a compact set of non-overlapping splice entries that can be correctly aggregated without knowing the intermediate state.ArithmeticDelta<T>— wrapping-arithmetic delta for all primitive integer types. Any type implementing theWrappingArithmetictrait gets aDifferentiable<ArithmeticDelta<Self>>impl for free.
Full API details on docs.rs.
#[derive(Differentiable)] Macro
Enable the macros feature to derive Differentiable for your own structs. Each field is annotated with the delta type it should use, and the macro generates the delta struct along with its Delta and Differentiable impls.
# Cargo.toml
[]
= { = "*", = ["macros"] }
use ;
Run cargo expand to inspect the generated code.
Timelines
Timeline<D, M> is an ordered sequence of Commit<D, M> values (delta + optional metadata). It supports aggregate queries, range merging, and state replay. StateCachedTimeline<T, D, M> wraps it with periodic state snapshots, dropping arbitrary state-retrieval and delta-query cost from O(N) to O(interval).
Full API details on docs.rs.
Real-World Example: Video Scrubbing
StateCachedTimeline maps naturally onto a video player's seek model. Each frame is a commit; the server stores periodic keyframe-equivalent cached states and can answer any seek request with a lightweight delta rather than a full snapshot:
// Server: build a cached timeline from raw frames
let server_timeline = from_commits;
// Client: seek forward
let delta = server_timeline.delta_between.unwrap;
current_frame_data.patch;
// Client: seek backward — no full snapshot needed
let inv_delta = server_timeline.delta_between.unwrap;
current_frame_data.patch;
See example/src/bin/video_stream.rs for the full runnable version.
Utilities
ChangeBucket<T, D> holds "before" and "after" copies of a value. Mutate it freely through DerefMut, then call pop() to extract the accumulated delta and reset the baseline — useful for building pipelines that only emit commits when something actually changes.
Full API details on docs.rs.
Running the Examples
This repo uses a dedicated example crate with multiple binaries. Run any example with:
just run-example basic
just run-example macros
just run-example video_stream
Roadmap
- More built-in delta types
MapDelta— key-level insert/remove/update entriesSetDelta— insertion and removal sets forHashSet/BTreeSetBitmapDelta— XOR-based delta foru8/u32/u64bitfields, useful for flag sets and masksStringDelta— character- or byte-level diff forString/&str, wrappingSliceDeltawith UTF-8 awarenessMyersSliceDelta— Myers algorithm for huge slice diffing.
- Compact / bitpacked serialization — an opt-in binary format (behind a feature flag) that encodes deltas far more densely than
serde+ any text format can. Candidates include bitpacking index and length fields inSliceDeltaentries and using varint encoding for arithmetic deltas, with the whole thing potentially exposed as adeku-backed implementation. - Reversible delta trait — a
ReversibleDeltatrait (or aninvert()method) so types can cheaply produce their own inverse without needing aStateCachedTimelineto reconstruct two states and calldiff. #[derive(WrappingArithmetic)]— remove the boilerplate of implementing the trait by hand for newtype wrappers and simple structs.- Async / streaming timeline — a
StreamingTimelineadapter that yields commits as aStream, targeting networked applications that push state changes in real time. no_stdsupport — remove the hard dependency onstdso the core traits and delta types can be used in embedded and WASM environments.
License
Licensed under either of MIT or Apache-2.0 at your option.