squirtle

Types

JsonArray

A JSON array represented as a list of JsonValues

pub type JsonArray =
  List(JsonValue)

JsonDict

</>

A JSON object represented as a dictionary mapping strings to JsonValues

pub type JsonDict =
  dict.Dict(String, JsonValue)

JsonValue

</>

Represents any JSON value

This type can represent all valid JSON values including objects, arrays, strings, numbers, booleans, and null.

pub type JsonValue {
  Null
  String(String)
  Int(Int)
  Bool(Bool)
  Float(Float)
  Array(List(JsonValue))
  Object(dict.Dict(String, JsonValue))
}

Constructors

```
Null
```
```
String(String)
```
```
Int(Int)
```
```
Bool(Bool)
```
```
Float(Float)
```
```
Array(List(JsonValue))
```
```
Object(dict.Dict(String, JsonValue))
```

Patch

</>

A JSON Patch operation Represents one of the six operations defined in RFC 6902:

pub type Patch {
  Add(path: String, value: JsonValue)
  Remove(path: String)
  Replace(path: String, value: JsonValue)
  Copy(from: String, path: String)
  Move(from: String, path: String)
  Test(path: String, value: JsonValue)
}

Constructors

```
Add(path: String, value: JsonValue)
```
Add a value at a path
```
Remove(path: String)
```
Remove a value at a path
```
Replace(path: String, value: JsonValue)
```
Replace a value at a path
```
Copy(from: String, path: String)
```
Copy a value from one path to another
```
Move(from: String, path: String)
```
Move a value from one path to another
```
Test(path: String, value: JsonValue)
```
Test that a value at a path equals an expected value

Values

array

</>

pub fn array() -> decode.Decoder(JsonValue)

Decoder that parses a JSON array into a JsonValue

bool

</>

pub fn bool() -> decode.Decoder(JsonValue)

Decoder that parses a JSON boolean into a JsonValue

dict

</>

pub fn dict() -> decode.Decoder(dict.Dict(String, JsonValue))

Decoder that parses a JSON dictionary into a JsonDict

diff

</>

pub fn diff(from: JsonValue, to: JsonValue) -> List(Patch)

Generate a list of patch operations that transform one JSON value into another

This function compares two JsonValues and produces the minimal set of patches that, when applied to the first value, will produce the second value.

Example

import gleam/dict
import squirtle

let doc1 = squirtle.Object(dict.from_list([
  #("name", squirtle.String("John")),
  #("age", squirtle.Int(30))
]))

let doc2 = squirtle.Object(dict.from_list([
  #("name", squirtle.String("Jane")),
  #("age", squirtle.Int(30)),
  #("email", squirtle.String("jane@example.com"))
]))

let patches = squirtle.diff(doc1, doc2)
// => [
//   Replace(path: "/name", value: String("Jane")),
//   Add(path: "/email", value: String("jane@example.com"))
// ]

squirtle.patch(doc1, patches)
// => Ok(doc2)

float

</>

pub fn float() -> decode.Decoder(JsonValue)

Decoder that parses a JSON float into a JsonValue

int

</>

pub fn int() -> decode.Decoder(JsonValue)

Decoder that parses a JSON integer into a JsonValue

json_value_decode

</>

pub fn json_value_decode(
  value: JsonValue,
  decoder: decode.Decoder(a),
) -> Result(a, List(decode.DecodeError))

Decode a JsonValue using a custom decoder

This allows you to decode a JsonValue into a specific Gleam type.

Example

import gleam/dynamic/decode
import squirtle

let value = squirtle.Object(...)
squirtle.json_value_decode(value, decode.field("name", decode.string))
// => Ok("John")

json_value_decoder

</>

pub fn json_value_decoder() -> decode.Decoder(JsonValue)

Returns a decoder for parsing JSON into a JsonValue

This decoder can parse any valid JSON value.

Example

import gleam/json
import squirtle

json.parse("{\"name\": \"John\"}", squirtle.json_value_decoder())
// => Ok(Object(...))

json_value_parse

</>

pub fn json_value_parse(
  raw: String,
) -> Result(JsonValue, json.DecodeError)

Parse a JSON string into a JsonValue

Example

import squirtle

squirtle.parse("{\"name\": \"John\", \"age\": 30}")
// => Ok(Object(...))

json_value_to_dynamic

</>

pub fn json_value_to_dynamic(value: JsonValue) -> dynamic.Dynamic

Convert a JsonValue to a Dynamic value

This is useful when you need to use the value with Gleam’s dynamic decoding functions.

Example

import squirtle

let value = squirtle.String("hello")
squirtle.json_value_to_dynamic(value)

json_value_to_gleam_json

</>

pub fn json_value_to_gleam_json(value: JsonValue) -> json.Json

Convert a JsonValue to gleam/json’s Json type

This is useful when you need to work with the standard library’s JSON functions.

Example

import squirtle

let value = squirtle.String("hello")
squirtle.json_value_to_gleam_json(value)

json_value_to_string

</>

pub fn json_value_to_string(value: JsonValue) -> String

Convert a JsonValue to a JSON string

Example

import squirtle

let value = squirtle.Object(...)
squirtle.json_value_to_string(value)
// => "{\"name\":\"John\"}"

list

</>

pub fn list() -> decode.Decoder(List(JsonValue))

Decoder that parses a JSON array into a JsonValue list

null

</>

pub fn null() -> decode.Decoder(JsonValue)

Decoder that parses a JSON null into a JsonValue

object

</>

pub fn object() -> decode.Decoder(JsonValue)

Decoder that parses a JSON object into a JsonValue

parse_patches

</>

pub fn parse_patches(
  patches: String,
) -> Result(List(Patch), json.DecodeError)

Parse a JSON array of patch operations from a string

Example

import squirtle

let patches_json = "[
  {\"op\": \"add\", \"path\": \"/name\", \"value\": \"John\"},
  {\"op\": \"remove\", \"path\": \"/age\"}
]"

squirtle.parse_patches(patches_json)
// => Ok([Add("/name", String("John")), Remove("/age")])

patch

</>

pub fn patch(
  data: JsonValue,
  patches: List(Patch),
) -> Result(JsonValue, String)

Apply a list of patch operations to a JSON document

Applies all patches in order, returning the modified document or an error if any patch fails. All patches must succeed for the operation to succeed.

Example

import squirtle

let assert Ok(doc) = squirtle.parse("{\"name\": \"John\"}")
let patches = [
  squirtle.Replace(path: "/name", value: squirtle.String("Jane")),
  squirtle.Add(path: "/age", value: squirtle.Int(30)),
]

squirtle.patch(doc, patches)
// => Ok(Object(...))

patch_decoder

</>

pub fn patch_decoder() -> decode.Decoder(Patch)

Returns a decoder for parsing JSON into a Patch operation

This decoder parses a single patch operation from JSON according to RFC 6902.

Example

import gleam/json
import squirtle

json.parse("{\"op\": \"add\", \"path\": \"/name\", \"value\": \"John\"}",
           squirtle.patch_decoder())
// => Ok(Add("/name", String("John")))

patch_string

</>

pub fn patch_string(
  data: String,
  patches: String,
) -> Result(String, String)

Parse and apply JSON patches to a JSON document, both provided as strings

This is a convenience function that combines parsing, patching, and stringifying. Returns the patched document as a JSON string.

Example

import squirtle

let doc = "{\"name\":\"John\",\"age\":30}"
let patches = "[{\"op\":\"replace\",\"path\":\"/name\",\"value\":\"Jane\"}]"

squirtle.patch_string(doc, patches)
// => Ok("{\"name\":\"Jane\",\"age\":30}")

patch_to_json_value

</>

pub fn patch_to_json_value(patch: Patch) -> JsonValue

Convert a Patch operation to a JsonValue

This function converts a single patch operation into a JsonValue representation that follows RFC 6902 format, making it easy to serialize patches for transmission.

Example

import squirtle

let patch = squirtle.Add(path: "/name", value: squirtle.String("John"))
squirtle.patch_to_json_value(patch)
// => Object(...) representing {"op":"add","path":"/name","value":"John"}

patch_to_string

</>

pub fn patch_to_string(patch: Patch) -> String

Convert a Patch operation to a JSON string

This function converts a single patch operation to its JSON string representation according to RFC 6902 format.

Example

import squirtle

let patch = squirtle.Add(path: "/name", value: squirtle.String("John"))
squirtle.patch_to_string(patch)
// => "{\"op\":\"add\",\"path\":\"/name\",\"value\":\"John\"}"

patches_to_string

</>

pub fn patches_to_string(patches: List(Patch)) -> String

Convert a list of Patch operations to a JSON array string

This function converts a list of patch operations to their JSON array string representation according to RFC 6902 format, making it easy to send patches over the wire.

Example

import squirtle

let patches = [
  squirtle.Replace(path: "/name", value: squirtle.String("Jane")),
  squirtle.Add(path: "/age", value: squirtle.Int(30)),
]
squirtle.patches_to_string(patches)
// => "[{\"op\":\"replace\",\"path\":\"/name\",\"value\":\"Jane\"},{\"op\":\"add\",\"path\":\"/age\",\"value\":30}]"

string

</>

pub fn string() -> decode.Decoder(JsonValue)

Decoder that parses a JSON string into a JsonValue