Declares a key holding a boolean.

Reports an enum value missing from its declared list anywhere in fields. It encodes, but a handler using these fields cannot decode it. It returns the InvalidField error the handler would report, and Ok(Nil) for any other value. The emit paths log a warning for the same values; check only returns the error, so a test can assert it.

fields.check(method_field(), Delete)
// -> Error(InvalidField("method", [..])) when Delete is not listed

Decodes a native map the way a handler would, reading only the declared keys.

Describes a decoding failure for logs.

Declares no keys. It decodes any map as Nil and rejects a term that is not a map. It is the same codec as success(Nil).

Encodes value into the native map that sinal.emit would send. Use it to pin a package’s wire format in tests or to hand a map to Erlang code. It writes an enum value missing from its list without complaint; the emit paths report it.

Declares a key holding one of values, written as the UTF-8 binary name(value). Decoding accepts that binary, or an atom with the same text, and fails on any other name.

The compiler checks that name covers every constructor, but it cannot check values: a constructor missing from the list compiles. Encoding still writes its name, and every emit path (sinal.emit, forwarder.emit, span.run) logs a warning in the emitting process that names the event and the value. A handler using this enum fails to decode it, reports MalformedMetadata (or MalformedMeasurements) to its failure observer, skips that one invocation and stays attached when failure reporting returns normally. Those handlers skip the unlisted value until the list is fixed.

So keep values next to the type, and give the application a test that names every constructor and round-trips it through the codec. The compiler cannot list a type’s constructors, so the test names them itself; when it names one that values lacks, check returns the error and the decode fails:

pub fn every_method_is_listed_test() {
  let codec = method_field()
  // One entry per constructor of Method.
  list.each([Get, Post], fn(method) {
    let assert Ok(Nil) = fields.check(codec, method)
    let assert Ok(decoded) =
      fields.decode(codec, fields.encode(codec, method))
    assert decoded == method
  })
}

pub type Method {
  Get
  Post
}

fields.enum("method", [Get, Post], fn(method) {
  case method {
    Get -> "get"
    Post -> "post"
  }
})

Panics when values is empty or two values share a name.

Declares one key whose value is written by encode and read by decoder. Use it for a value the other constructors do not cover. Inside a record, sinal runs decoder once against nil where the record is defined, for a placeholder value, so keep it free of effects.

fields.field("attempt", dynamic.int, decode.int)

Declares a key holding a float. Decoding also accepts an integer, which native producers often send for a whole-number measurement, and converts it.

Adds one field to a record codec and binds its decoded value by name for the rest of the use block, which ends in success:

use status <- fields.include(fields.int("status"), get: fn(r) { r.status })

field writes its keys from the value that get reads from the record. It is usually one key, but it can be another record codec, whose keys are written into the same map. The fields of a record may be listed in any order: each value goes to the constructor parameter it is bound to.

Pass the getter with its get: label. Gleam checks arguments in parameter order, and next (the rest of the use block) comes before get, so the record type is known from success by the time the getter is checked and the getter needs no annotation. Without the label the getter fills the then slot and the call fails to compile.

The record’s keys and encoder are fixed once, where the record is defined, by running the use block with placeholder values: the zero value of each field’s decoder (fields.field runs its decoder against nil for it). So keep the block to include calls and a success constructor, and do not choose a field from a value bound before it. Decoding runs the block again with the decoded values.

Panics when field declares a key the rest of the record already has.

Declares a key holding an integer.

The keys fields writes, in declaration order.

Makes a one-key field optional. Encoding None omits the key. Decoding reads a missing key, or the atom nil or undefined that a native producer may write instead, as None; any other value decodes through inner.

Do not wrap an inner whose own encoded values include the atoms nil or undefined: they would decode as None.

Panics when inner declares other than exactly one key.

Declares a key holding a UTF-8 binary.

Ends a record codec with the record built from the values that the include calls before it bound:

pub fn request_fields() -> fields.Fields(Request) {
  use method <- fields.include(fields.string("method"), get: fn(r) {
    r.method
  })
  use status <- fields.include(fields.int("status"), get: fn(r) { r.status })
  fields.success(Request(method:, status:))
}

Alone, success(value) declares no keys and decodes any map as value.