Crate structfs_serde_store 

Serde Integration for StructFS

This layer provides typed access to StructFS stores via serde. It adds:

• TypedReader: Read directly into Rust types
• TypedWriter: Write Rust types directly
• JsonCodec: A codec for JSON format
• Value <-> serde conversions

Lossless values

use structfs_serde_store::{Codec, Format, Value, ValueJsonCodec};
let value = Value::Array(vec![Value::from(u64::MAX), Value::Bytes(vec![0, 255])]);
let bytes = ValueJsonCodec.encode(&value, &Format::VALUE_JSON)?;
let decoded = ValueJsonCodec.decode(&bytes, &Format::VALUE_JSON)?;
assert!(value.semantic_eq(&decoded));

Plain JSON rejects bytes and non-finite floats. Use ValueCodec to select a profile and Limits explicitly. to_value and from_value use the structural Serde mapping directly; ambiguous null-valued options require ExplicitOption. All codecs validate complete documents. Raw record forwarding does not imply validation; use transcode for that contract.

Example

use structfs_serde_store::{TypedReader, TypedWriter, JsonCodec};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct User {
    name: String,
    age: u32,
}

fn read_user(store: &mut dyn Reader) -> Result<Option<User>, Error> {
    let codec = JsonCodec;
    store.read_as(&path!("users/123"), &codec)
}

Async Support

Enable the async feature for async trait variants:

[dependencies]
structfs-serde-store = { version = "0.1", features = ["async"] }

Then use AsyncTypedReader and AsyncTypedWriter.

Structs

Bytes

A cheaply cloneable and sliceable chunk of contiguous memory.

CborCodec

StructFS CBOR v1 with default limits.

ExplicitOption

Schema-visible option that can preserve Some(()) and nested optional states.

FlexbuffersCodec

StructFS FlexBuffers v1 with default limits; NUL map keys fail.

Format

A hint about the wire format of raw bytes.

JsonCodec

Strict plain JSON with default limits; bytes and non-finite floats fail.

Limits

Inclusive bounds. Work counts traversed nodes and bytes, plus collection sorting estimates. Allocation counts conservative reservations, not allocator metadata.

MultiCodec

A codec that combines multiple codecs.

Path

A validated path in StructFS.

ValueCodec

A codec with caller-configured finite limits. Canonical validation applies only to tagged JSON and compares the complete supplied document, including whitespace.

ValueJsonCodec

Lossless canonical StructFS Value JSON v1 with default limits.

Enums

Error

Errors at the Core layer.

PathError

Errors related to path parsing and validation.

Profile

Explicitly selected StructFS v1 codec contract.

Record

A record that can be forwarded without parsing or parsed for inspection.

Value

A tree-shaped value that can be read from or written to a Store.

Traits

Codec

Codec for converting between Value and bytes.

Reader

Read records from paths.

Store

Combined read/write at the Core level.

TypedReader

Extension trait for typed reads.

TypedWriter

Extension trait for typed writes.

Writer

Write records to paths.

Functions

from_value

from_value_with_limits

json_to_value

Import an already parsed JSON DOM, preserving its exact supported numbers.

to_value

to_value_with_limits

transcode

Validate and transcode a document, even when both profiles are the same. Raw byte forwarding is deliberately a different operation.

validate_value

Validate an existing value before traversing or cloning it at a trust boundary.

value_to_json

Convert to plain JSON, rejecting bytes and non-finite floats.