Expand description
§Palim: reversible JSON changes for Rust
Palim tracks list moves and edits by stable IDs and saves reversible JSON changes for undo/redo or replay. It also generates RFC 6902 JSON Patch for other clients, reads and writes jsondiffpatch deltas, and compares configurations.
§Installation
Requires Rust 1.85 or newer:
cargo add palim serde_jsonIn Cargo.toml, use palim = "0.3" and serde_json = "1.0".
Numbers use serde_json’s ordinary behavior by default. For arbitrary-precision
integers/decimals and precise float wire round trips, opt in:
palim = { version = "0.3", features = ["exact-numbers"] }This enables serde_json’s arbitrary_precision and float_roundtrip features
for the shared dependency, affecting Value equality and float parsing elsewhere
in your project. Enable it to retain Palim 0.2’s numeric capabilities. Without it,
ordinary parsing can round or reject numbers before Palim sees them.
§Match a list by ID, then undo the change
use palim::{DiffPatcher, patch, unpatch};
use serde_json::json;
let engine = DiffPatcher::by_key("id");
let before = json!([{ "id": 1, "score": 10 }, { "id": 2, "score": 20 }]);
let after = json!([{ "id": 2, "score": 21 }, { "id": 1, "score": 10 }]);
let delta = engine.diff(&before, &after)?.ok_or("expected a change")?;
assert_eq!(patch(&before, &delta)?, after);
assert_eq!(unpatch(&after, &delta)?, before);diff returns None when nothing changes. Serialize a complete Delta with
serde_json to save it for later replay. Apply it to the correct baseline;
Palim does not resolve concurrent edits. Missing IDs fall back to the complete
item value, and repeated IDs are paired deterministically.
§Choose an API
| I want to… | Use | What it produces |
|---|---|---|
| Save history or implement undo/redo | diff or DiffPatcher::by_key("id").diff, then patch / unpatch | Native Delta, including old values |
| Send a standard patch to a frontend or third party | diff_json_patch or Delta::to_json_patch, then apply_json_patch | RFC 6902 Patch operations |
| Undo a standard patch | invert_json_patch, with the original baseline | An inverse RFC 6902 Patch |
| See which paths changed | compare | CompareReport; a report, not a patch |
| Use JSON Merge Patch | diff_merge_patch / merge_patch | RFC 7396 JSON; object-member null means deletion |
| Read a JS jsondiffpatch change | Deserialize a forward delta as Delta, then patch / unpatch | Native interoperable delta |
Delta and Patch are different formats. Native deltas retain values for
undo; standard patches interoperate with RFC 6902 clients and need the baseline
for inversion. For a full API inventory and details on filters, fuzzy text,
limits and atomic application, read the
API guide or
function documentation.
§When to choose Palim
| Your need | A useful starting point |
|---|---|
| Undo/redo, replay, or jsondiffpatch-compatible deltas | Palim’s reversible Delta |
| Large arrays with stable IDs, reorders and edits inside moved items | Palim’s identity matching and move output |
| Standard patches with move/copy optimization, guards or inversion | Palim’s RFC APIs |
| Ordinary positional RFC patches without those capabilities | json-patch offers a simpler API |
| Small configurations in an existing JavaScript application | Compare the JS libraries in your own workload |
Performance depends on the workload and output format. Dated measurements show Palim’s advantages on large reorders and reversible deltas, with slower cases on random shuffles and wide additions. These historical runs do not measure the ordinary-number default introduced in 0.3. See the benchmarks and measurement boundaries and library comparison.
§Runnable examples
| Example | Demonstrates |
|---|---|
| id_list_history | ID-based list moves, edits, saved deltas, undo and redo |
| rfc_patch_transport | Serialize RFC 6902 operations, apply them and generate an inverse |
| config_report | Compare configuration paths and print a report |
| jsondiffpatch_interop | Import a forward JS delta and use Rust to apply and undo it |
cargo run --example id_list_history --locked
cargo run --example rfc_patch_transport --locked
cargo run --example config_report --locked
cargo run --example jsondiffpatch_interop --locked§More information
- API guide: matching, patch formats, numeric semantics and error contracts.
- Benchmarks and verification: dated results, interoperability boundaries and commands for contributors.
- Design, changelog and releases.
MIT for this implementation. Dependencies retain their respective licenses. Upstream-derived test fixtures are Apache-2.0; see tests/fixtures/NOTICE.md.
Structs§
- Array
Move - An identity-matched item whose source and target indices differ.
- Compare
Options - Options for a comparison report, separate from reversible delta generation.
- Compare
Report - JSON comparison output. It is not an applicable or reversible patch.
- Delta
- A complete reversible delta, serialized using jsondiffpatch’s JSON protocol.
- Diff
Options - Instance-local matching options.
- Diff
Patcher - A reusable, shareable diff instance without global configuration.
- Difference
- A changed, added or removed value. None denotes absence, not JSON null.
- Error
- A patch or diff failure, with a JSON Pointer identifying the affected value.
- Forward
Delta - A delta with omitted old values. Its wire representation has no reversible marker; deserialize it as this type, never as Delta. It intentionally has no reverse method.
- Json
Patch Apply Options - Resource limits for standard patch application.
- Json
Patch Options - Options for producing RFC 6902 patches.
- Patch
- Representation of JSON Patch (list of patch operations)
- Text
Patch Options - Bounds for opt-in approximate text application. Distances use UTF-16 units.
Enums§
- Patch
Operation - JSON Patch single patch operation
Functions§
- apply_
json_ patch - Apply all six RFC 6902 operations without changing the source.
- apply_
json_ patch_ in_ place - Update the caller’s document only after every operation succeeds.
- apply_
json_ patch_ owned - Consume the baseline, avoiding the initial whole-document clone.
- apply_
json_ patch_ with_ options - Apply with copy and nesting limits; failures return no partial document.
- apply_
text_ patch - Apply a DMP text patch with bounded approximate matching.
- compare
- Compare JSON with mathematical number equality by default (1 equals 1.0). Inputs remain unchanged. Exhausted budgets return an error, never partial output.
- compose_
merge_ patches - Compose two RFC 7396 merge patches for every possible source document.
- diff
- Compare using default options. Unkeyed objects in arrays are matched by position.
- diff_
json_ patch - Compare documents and return a standard JSON Patch.
- diff_
merge_ patch - Generate an RFC 7396 merge patch transforming left into right.
- invert_
json_ patch - Produce an inverse from the original operations and their complete baseline. Tests make no changes and therefore produce no inverse operation. A move may need remove/add/replace operations to restore a destination it overwrote.
- invert_
json_ patch_ guarded - Generate an inverse with tests for the values and containers it will touch. Guards are computed from the successfully patched baseline. They do not authenticate unrelated document fields, and container tests can be large.
- merge_
patch - Apply an RFC 7396 JSON Merge Patch without changing the source.
- merge_
patch_ in_ place - Apply an RFC 7396 merge patch atomically to a mutable source.
- patch
- Apply a complete delta with strict old-value, type, index and text context checks.
- patch_
fuzzy - Apply native deltas with approximate text matching; non-text changes stay strict.
- patch_
in_ place - Atomically update a baseline after successful native application.
- patch_
owned - Consume a baseline instead of borrowing it.
- reverse
- Generate the inverse solely from the original delta; no re-diff is performed.
- test_
json_ patch - Check a sequence of RFC 6902 test operations without cloning the document. Other operations are rejected in sequence. Source and expected values retain the standard 128-container depth limit and mathematical number equality.
- unpatch
- Restore a source document by applying the inverse delta to right.
Type Aliases§
- Array
Item Matcher - Pair array elements using caller-defined identity or similarity.
- Compare
Node Filter - Return false to exclude a node, including root, array items and absent values.
- Custom
Equal - Return Some to decide equality of a node, or None to use normal comparison.
- Node
Filter - Select any JSON node, including roots, missing values and array positions.
- Object
Hash - Return an identity for an object/array item. Called once per item in each changed array.
- Property
Filter - Return false to exclude an object property from comparison.
- Unordered
Arrays - Select array paths whose order is immaterial. Repeated values retain their counts.