squirtle - v2.0.0

squirtle

Package Version Hex Docs

A JSON Patch (RFC 6902) implementation for Gleam.

Installation

gleam add squirtle@3

Usage

Applying Patches

import gleam/io
import squirtle.{String, Add, Replace, Remove}

pub fn main() {
  let assert Ok(doc) = squirtle.parse("{\"name\": \"John\", \"age\": 30}")

  let patches = [
    Replace(path: "/name", value: String("Jane")),
    Add(path: "/email", value: String("jane@example.com")),
    Remove(path: "/age"),
  ]

  case squirtle.apply(doc, patches) {
    Ok(result) -> io.println(squirtle.to_string(result))
    // => {"name":"Jane","email":"jane@example.com"}
    Error(err) -> io.println("Patch failed: " <> squirtle.error_to_string(err))
  }
}

Generating Diffs

import gleam/dict
import squirtle.{String, Int, Object}

pub fn main() {
  let old = Object(dict.from_list([#("name", String("John"))]))
  let new = Object(dict.from_list([
    #("name", String("Jane")),
    #("age", Int(30)),
  ]))

  let patches = squirtle.diff(from: old, to: new)
  // => [Replace("/name", String("Jane")), Add("/age", Int(30))]

  let assert Ok(result) = squirtle.apply(old, patches)
  // result == new
}

Decoding from JSON

import gleam/dynamic/decode
import gleam/json
import squirtle

pub fn apply_patch_request(doc_json: String, patches_json: String) {
  let assert Ok(doc) = json.parse(doc_json, squirtle.decoder())
  let assert Ok(patches) = json.parse(patches_json, decode.list(squirtle.patch_decoder()))

  squirtle.apply(doc, patches)
}

Supported Operations

All operations follow RFC 6902:

OperationDescriptionExample
addAdd a value at a path{"op": "add", "path": "/email", "value": "user@example.com"}
removeRemove a value at a path{"op": "remove", "path": "/age"}
replaceReplace a value at a path{"op": "replace", "path": "/name", "value": "Jane"}
copyCopy a value from one path to another{"op": "copy", "from": "/name", "path": "/username"}
moveMove a value from one path to another{"op": "move", "from": "/old", "path": "/new"}
testTest that a value equals expected{"op": "test", "path": "/name", "value": "John"}

JSON Pointer Paths

Paths use JSON Pointer (RFC 6901) syntax:

PathMeaning
""Root document
/fooProperty “foo” in the root object
/foo/barProperty “bar” nested in “foo”
/foo/0First element of array at “foo”
/foo/-Append to array at “foo” (add only)
/foo~0barProperty “bar” ( escaped as ~0)
/foo~1barProperty “/bar” (/ escaped as ~1)

API Reference

Further documentation can be found at https://hexdocs.pm/squirtle.

Development

gleam test  # Run the tests
✨ Search Document