Adds an optional field to a list of key-value pairs that will be used to create a JSON object. This is particularly useful when defining JSON encoder to pair up to the optional_field decoder.

Example

fn tree_decoder() {
  blueprint.union_type_decoder([
    #(
      "node",
      blueprint.decode3(
        Node,
        blueprint.field("value", blueprint.int()),
        // This is an optional field for an optional value
        blueprint.optional_field("left", blueprint.self_decoder(tree_decoder)),
        // And this is a required field with an optional value
        blueprint.field(
          "right",
          blueprint.optional(blueprint.self_decoder(tree_decoder)),
        ),
      ),
    ),
  ])
  |> blueprint.reuse_decoder
}

fn encode_tree(tree: Tree) -> json.Json {
  blueprint.union_type_encoder(tree, fn(node) {
    case node {
      Node(value, left, right) -> #(
        "node",
        [
          #("value", json.int(value)),
          // This is a required field with an optional value
          #("right", json.nullable(right, encode_tree)),
        ]
          // And this is an optional field for an optional value
          |> blueprint.encode_optional_field("left", left, encode_tree)
          |> json.object(),
      )
    }
  })
}

Function to define a decoder for enum types (unions where constructors have no arguments). The function takes a list of tuples containing the string representation and the corresponding enum value.

Make sure to add tests for every possible enum value because it is not possible to check for exhaustiveness.

Example

type Color {
  Red
  Green
  Blue
}

let color_decoder = enum_type_decoder([
  #("red", Red),
  #("green", Green),
  #("blue", Blue),
])

Function to encode an enum type (unions where constructors have no arguments) into a JSON object. The function takes a value and an encoder function that returns the string representation of the enum value.

Make sure to update the decoder function accordingly.

Example

type Color {
  Red
  Green
  Blue
}

let color_encoder = enum_type_encoder(fn(color) {
  case color {
    Red -> "red"
    Green -> "green"
    Blue -> "blue"
  }
})

Creates a decoder that can handle null values by wrapping the result in an Option type. When the value is null, it returns None. Otherwise, it uses the provided decoder to decode the value and wraps the result in Some. If you need the decoder to handle a possible missing field (i.e., the field is absent from the JSON), use the optional_field function instead.

Example

type User {
  User(name: String, age: Option(Int))
}

let decoder = decode2(
  User,
  field("name", string()),
  field("age", optional(int()))  // Will handle "age": null
)

// These JSON strings will decode successfully:
// {"name": "Alice", "age": 25}  -> User("Alice", Some(25))
// {"name": "Bob", "age": null}  -> User("Bob", None)

Decode a field that can be missing or have a null value into an Option type. This function is useful when you want to handle both cases where a field is absent from the JSON or when it’s explicitly set to null.

If you only need to handle fields that are present but might be null, use the optional function instead.

Example

type User {
  User(name: String, age: Option(Int))
}

let decoder = decode2(
  User,
  field("name", string()),
  optional_field("age", int())  // Will handle both missing "age" field and "age": null
)

// All these JSON strings will decode successfully:
// {"name": "Alice", "age": 25}     -> User("Alice", Some(25))
// {"name": "Bob", "age": null}     -> User("Bob", None)
// {"name": "Charlie"}              -> User("Charlie", None)

Creates a reusable version of a decoder that can be used multiple times in a schema without duplicating the schema definition.

The function:

1. Creates a unique reference name based on the schema’s hash
2. Moves the original schema into the $defs section
3. Returns a new decoder that references the schema via $ref

Example

type Person {
  Person(name: String, friends: List(Pet))
}

type Pet {
  Pet(name: String)
}


let pet_decoder = reuse_decoder(
  decode2(
    Pet,
    field("name", string()),
  )
)

let person_decoder = reuse_decoder(
  decode2(
    Person,
    field("name", string()),
    field("friends", list(pet_decoder))
  )
)

Creates a decoder for recursive data types by allowing self-referential definitions. This is useful when you have types that contain themselves, like trees or linked lists.

The function takes a lazy decoder (a function that returns a decoder) to break the recursive dependency cycle. The returned decoder uses a JSON Schema reference “#” to point to the root schema definition.

❗ IMPORTANT Add the reuse_decoder when there are nested recursive types so the schema references (#) get rewritten correctly and self-references from the different types don’t get mixed up. As a recommendation, always add it when decoding recursive types.

Example

// A binary tree type that can contain itself
pub type Tree {
  Node(value: Int, left: Option(Tree), right: Option(Tree))
  Leaf(value: Int)
}

// Create a recursive decoder for the Tree type
pub fn tree_decoder() -> Decoder(Tree) {
  // Use union_type_decoder for handling different variants
  union_type_decoder([
    #("leaf", decode1(Leaf, field("value", int()))),
    #("node", decode3(
      Node,
      field("value", int()),
      // Use self_decoder to handle recursive fields
      field("left", optional(self_decoder(tree_decoder))),
      field("right", optional(self_decoder(tree_decoder))),
    )),
  ])
  |> reuse_decoder
}

Function to defined a decoder for a union types. The function takes a list of decoders for each possible type of the union.

Make sure to add tests for every possible type of the union because it is not possible to check for exhaustiveness in the case.

Example

type Shape {
  Circle(Float)
  Rectangle(Float, Float)
}

let shape_decoder = union_type_decoder([
  #("circle", decode1(Circle, field("radius", float()))),
  #("rectangle", decode2(Rectangle,
    field("width", float()),
    field("height", float())
  ))
])

Function to encode a union type into a JSON object. The function takes a value and an encoder function that returns a tuple of the type name and the JSON value.

Make sure to update the decoder function accordingly.

Example

type Shape {
  Circle(Float)
  Rectangle(Float, Float)
}

let shape_encoder = union_type_encoder(fn(shape) {
  case shape {
    Circle(radius) -> #("circle", json.object([#("radius", json.float(radius))]))
    Rectangle(width, height) -> #(
      "rectangle",
      json.object([
        #("width", json.float(width)),
        #("height", json.float(height))
      ])
    )
  }
})