///|
/// Report a wire-format error at the supplied JSON path.
pub fn[T] invalid(
path : @json.JsonPath,
message : String,
) -> T raise @json.JsonDecodeError {
raise @json.JsonDecodeError((path, message))
}
///|
/// Report the key at the first absent path segment.
pub fn[T] missing_field(
path : @json.JsonPath,
key : String,
) -> T raise @json.JsonDecodeError {
invalid(path, "missing field: \{key}")
}
///|
/// Codecs operate on dynamic JSON values because this package implements the serialization boundary itself.
pub fn object(
value : Json,
path : @json.JsonPath,
) -> Map[String, Json] raise @json.JsonDecodeError {
match value {
Object(fields) => fields
_ => invalid(path, "expected an object")
}
}
///|
/// Resolve a field and its aliases, rejecting ambiguous input.
pub fn field(
fields : Map[String, Json],
key : String,
aliases : Array[String],
path : @json.JsonPath,
) -> Json? raise @json.JsonDecodeError {
let mut found = fields.get(key)
for alternate in aliases {
if fields.get(alternate) is Some(value) {
if found is Some(_) {
invalid(path.add_key(key), "duplicate field or alias: \{key}")
}
found = Some(value)
}
}
found
}
///|
/// Read fixed object keys and return the value, its location, and the first missing key or leaf key.
pub fn read_path(
fields : Map[String, Json],
keys : Array[String],
path : @json.JsonPath,
) -> (Json?, @json.JsonPath, String) raise @json.JsonDecodeError {
let mut value = None
let mut cursor = path
let mut object_fields = fields
let mut last_key = ""
for i, key in keys {
last_key = key
cursor = cursor.add_key(key)
value = object_fields.get(key)
if i < keys.length() - 1 {
match value {
None => return (None, cursor, key)
Some(child) => object_fields = object(child, cursor)
}
}
}
(value, cursor, last_key)
}
///|
/// Write a leaf into the generated object's already-validated, non-overlapping paths.
pub fn write_path(
fields : Map[String, Json],
keys : Array[String],
value : Json,
) -> Unit {
let mut object_fields = fields
for i, key in keys {
if i == keys.length() - 1 {
object_fields[key] = value
} else {
match object_fields.get(key) {
Some(Object(child)) => object_fields = child
None => {
let child = Map([])
object_fields[key] = Json::object(child)
object_fields = child
}
Some(_) => abort("generated JSON field paths overlap")
}
}
}
}
///|
/// Reject unexpected keys without changing the caller's object.
pub fn deny_unknown(
fields : Map[String, Json],
allowed : Array[String],
path : @json.JsonPath,
) -> Unit raise @json.JsonDecodeError {
for key, _ in fields {
if !allowed.contains(key) {
invalid(path.add_key(key), "unknown field: \{key}")
}
}
}
///|
/// Check unknown keys at each object implied by fixed paths. Leaf decoders validate their own values.
pub fn deny_unknown_paths(
fields : Map[String, Json],
paths : Array[Array[String]],
path : @json.JsonPath,
) -> Unit raise @json.JsonDecodeError {
deny_unknown_at(fields, paths, path, 0)
}
///|
fn deny_unknown_at(
fields : Map[String, Json],
paths : Array[Array[String]],
path : @json.JsonPath,
depth : Int32,
) -> Unit raise @json.JsonDecodeError {
for key, value in fields {
let matching = paths.filter(keys => keys[depth] == key)
let field_path = path.add_key(key)
if matching.is_empty() {
invalid(field_path, "unknown field: \{key}")
}
if value is Object(child) && matching[0].length() > depth + 1 {
deny_unknown_at(child, matching, field_path, depth + 1)
}
}
}
///|
/// Decode the externally tagged representation. None distinguishes a unit tag from an explicit null payload.
pub fn external(
value : Json,
path : @json.JsonPath,
) -> (String, Json?) raise @json.JsonDecodeError {
match value {
String(tag) => (tag, None)
Object(fields) if fields.length() == 1 => {
for tag, payload in fields {
return (tag, Some(payload))
}
invalid(path, "expected one enum variant")
}
_ => invalid(path, "expected a variant string or a single-key object")
}
}
///|
/// Read an internal or adjacent string discriminator.
pub fn discriminator(
fields : Map[String, Json],
tag : String,
path : @json.JsonPath,
) -> String raise @json.JsonDecodeError {
match fields.get(tag) {
Some(String(value)) => value
None => invalid(path.add_key(tag), "missing discriminator: \{tag}")
Some(_) => invalid(path.add_key(tag), "expected a string discriminator")
}
}
///|
/// Try candidates in declaration order. If none match, report each candidate's location and reason.
pub fn[T] untagged(
value : Json,
path : @json.JsonPath,
candidates : Array[
(String, (Json, @json.JsonPath) -> T raise @json.JsonDecodeError),
],
) -> T raise @json.JsonDecodeError {
let details : Array[String] = []
for candidate in candidates {
let (name, decode) = candidate
try {
return decode(value, path)
} catch {
@json.JsonDecodeError((at, reason)) => {
let pointer = at.to_string()
let location = if pointer.is_empty() { "" } else { pointer }
details.push("\{name} at \{location}: \{reason}")
}
}
}
invalid(path, "no untagged variant matched:\n " + details.join("\n "))
}
///|
/// Validate a tuple payload before indexing it.
pub fn tuple(
value : Json,
length : Int32,
path : @json.JsonPath,
) -> Array[Json] raise @json.JsonDecodeError {
match value {
Array(values) if values.length() == length => values
_ => invalid(path, "expected a tuple of length \{length}")
}
}
///|
/// Require a variant's content, preserving the difference between absent and null.
pub fn payload(
value : Json?,
path : @json.JsonPath,
) -> Json raise @json.JsonDecodeError {
match value {
Some(value) => value
None => invalid(path, "missing enum content")
}
}
///|
/// Require the string form of an external unit variant or an absent adjacent content field.
pub fn unit(
value : Json?,
path : @json.JsonPath,
) -> Unit raise @json.JsonDecodeError {
if value is Some(_) {
invalid(path, "unit variant must not have content")
}
}