facet-value: from_value Deserialization

Happy Path

Simple Struct

Deserialize a Value map into a struct with basic fields.

Value Input

{
  name: "Alice",
  age: 30,
  email: "alice@example.com",
}

Target Type

#[derive(Facet)]
struct Person {
    name: String,
    age: u32,
    email: Option<String>,
}

Success

Person {
  name: "Alice",
  age: 30,
  email: Option<String>::Some("alice@example.com"),
}

Nested Structs

Nested structs are deserialized recursively.

Value Input

{
  person: {
    name: "Bob",
    age: 42,
    email: null,
  },
  address: {
    street: "123 Main St",
    city: "Springfield",
    zip: "12345",
  },
  department: "Engineering",
}

Target Type

#[derive(Facet)]
struct Employee {
    person: Person,
    address: Address,
    department: String,
}

#[derive(Facet)]
struct Address {
    street: String,
    city: String,
    zip: String,
}

#[derive(Facet)]
struct Person {
    name: String,
    age: u32,
    email: Option<String>,
}

Success

Employee {
  person: Person {
    name: "Bob",
    age: 42,
    email: Option<String>::None,
  },
  address: Address {
    street: "123 Main St",
    city: "Springfield",
    zip: "12345",
  },
  department: "Engineering",
}

Unit Enum Variant

A string value deserializes into a unit variant.

Value Input

"Active"

Target Type

#[derive(Facet)]
#[repr(u8)]
enum Status {
    Active,
    Inactive,
    Pending,
}

Success

Status::Active

Tuple Enum Variant

Externally tagged enum: {"Variant": content}.

Value Input

{
  Text: "Hello world!",
}

Target Type

#[derive(Facet)]
#[repr(u8)]
enum Message {
    Text(String),
    Number(i32),
    Data {
        id: u64,
        payload: String,
    },
}

Success

Message::Text("Hello world!")

Struct Enum Variant

Struct variants deserialize with named fields.

Value Input

{
  Data: {
    id: 42,
    payload: "secret data",
  },
}

Target Type

#[derive(Facet)]
#[repr(u8)]
enum Message {
    Text(String),
    Number(i32),
    Data {
        id: u64,
        payload: String,
    },
}

Success

Message::Data {
  id: 42,
  payload: "secret data",
}

Vec Deserialization

Arrays deserialize into Vec<T>.

Value Input

[
  1,
  2,
  3,
  4,
  5,
]

Target Type

Success

Vec<i32> [
  1,
  2,
  3,
  4,
  5,
]

Fixed-Size Array

Arrays with exact length deserialize into [T; N].

Value Input

[
  "a",
  "b",
  "c",
]

Target Type

Success

[String; 3] [
  "a",
  "b",
  "c",
]

HashMap

Objects deserialize into HashMap<String, T>.

Value Input

{
  x: 10,
  y: 20,
  z: 30,
}

Target Type

Success

HashMap<String, i32> [
  "x" => 10,
  "z" => 30,
  "y" => 20,
]

Nested Collections

null values become None in Option<T>.

Value Input

[
  1,
  null,
  3,
  null,
  5,
]

Target Type

Success

Vec<Option<i32>> [
  Option<i32>::Some(1),
  Option<i32>::None,
  Option<i32>::Some(3),
  Option<i32>::None,
  Option<i32>::Some(5),
]

Default Field Values

Fields marked with #[facet(default)] use Default::default() when missing.

Value Input

{
  name: "minimal",
}

Target Type

#[derive(Facet)]
struct Config {
    name: String,
    enabled: bool,
    max_retries: Option<u32>,
}

Success

Config {
  name: "minimal",
  enabled: false,
  max_retries: Option<u32>::None,
}

Errors

Error: Type Mismatch

Trying to deserialize a string as an integer.

Error

× reflection error: Operation failed on shape i32: Failed to parse string value

Error: × input.json ╭──── 1 │ "not a number" · ───────┬────── · ╰── this value ╰────

Error: Number Out of Range

Value 1000 is too large for u8 (max 255).

Error

× number out of range: 1000 out of range for u8

Error: × input.json ╭──── 1 │ 1000 · ──┬─ · ╰── this value: 1000 out of range for u8 ╰────

Error: Wrong Array Length

Array has 4 elements but target type expects exactly 3.

Error

× unsupported: fixed array has 3 elements but got 4

Error: × input.json ╭─[1:1] 1 │ ╭─▶ [ 2 │ │ 1, 3 │ │ 2, 4 │ │ 3, 5 │ │ 4 6 │ ├─▶ ] · ╰──── this value ╰────

Error: Invalid Enum Variant

"Unknown" is not a valid variant of Status.

Error

× reflection error: Operation failed on shape Status: No variant found with the given name Error: × input.json ╭──── 1 │ "Unknown" · ────┬──── · ╰── this value ╰────

Error: × target.rs ╭─[1:1] 1 │ ╭─▶ #[derive(Facet)] 2 │ │ #[repr(u8)] 3 │ │ enum Status { 4 │ │ Active, 5 │ │ Inactive, 6 │ │ Pending, 7 │ ├─▶ } · ╰──── target type ╰────

Error: Expected Object, Got Array

Cannot deserialize an array as a struct.

Error

× type mismatch: expected object, got Array Error: × input.json ╭─[1:1] 1 │ ╭─▶ [ 2 │ │ 1, 3 │ │ 2, 4 │ │ 3 5 │ ├─▶ ] · ╰──── got Array ╰────

Error: × target.rs ╭─[1:1] 1 │ ╭─▶ #[derive(Facet)] 2 │ │ struct Person { 3 │ │ name: String, 4 │ │ age: u32, 5 │ │ email: Option<String>, 6 │ ├─▶ } · ╰──── expected object ╰────