facet_format_postcard/
lib.rs

1//! Postcard binary format for facet using the Tier-2 JIT architecture.
2//!
3//! This crate provides Tier-2 JIT deserialization for the postcard binary format.
4//! It implements `JitFormat` and `FormatJitParser` to enable direct byte-level
5//! parsing without going through the event abstraction.
6//!
7//! **Note:** This crate is Tier-2 only. It does not implement a full `FormatParser`
8//! (ParseEvent) stack. For non-JIT postcard support, use `facet-postcard`.
9
10#![cfg_attr(not(feature = "jit"), forbid(unsafe_code))]
11
12extern crate alloc;
13
14mod error;
15mod parser;
16
17#[cfg(feature = "jit")]
18pub mod jit;
19
20pub use error::PostcardError;
21#[cfg(feature = "jit")]
22pub use jit::PostcardJitFormat;
23pub use parser::PostcardParser;
24
25// Re-export DeserializeError for convenience
26pub use facet_format::DeserializeError;
27
28/// Deserialize a value from postcard bytes.
29///
30/// This uses Tier-2 JIT for supported types. Types that aren't Tier-2 compatible
31/// will return an error (this crate is Tier-2 only).
32///
33/// # Supported Types (Tier-2 v1)
34///
35/// - `Vec<bool>`
36///
37/// # Example
38///
39/// ```
40/// use facet_format_postcard::from_slice;
41///
42/// // Postcard encoding: [length=3, true, false, true]
43/// let bytes = &[0x03, 0x01, 0x00, 0x01];
44/// let result: Vec<bool> = from_slice(bytes).unwrap();
45/// assert_eq!(result, vec![true, false, true]);
46/// ```
47#[cfg(feature = "jit")]
48pub fn from_slice<'de, T>(input: &'de [u8]) -> Result<T, DeserializeError<PostcardError>>
49where
50    T: facet_core::Facet<'de>,
51{
52    let mut parser = PostcardParser::new(input);
53
54    // Try Tier-2 format JIT
55    match facet_format::jit::try_deserialize_format::<T, _>(&mut parser) {
56        Some(result) => result,
57        None => Err(DeserializeError::Unsupported(
58            "Type not supported by Tier-2 JIT (facet-format-postcard is Tier-2 only)".into(),
59        )),
60    }
61}
62
63/// Deserialize a value from postcard bytes (non-JIT fallback).
64///
65/// This function is only available when the `jit` feature is disabled.
66/// It will always fail because this crate is Tier-2 JIT only.
67#[cfg(not(feature = "jit"))]
68pub fn from_slice<'de, T>(_input: &'de [u8]) -> Result<T, DeserializeError<PostcardError>>
69where
70    T: facet_core::Facet<'de>,
71{
72    Err(DeserializeError::Unsupported(
73        "facet-format-postcard requires the 'jit' feature".into(),
74    ))
75}
facet_format_postcard/lib.rs

facet_format_postcard/
lib.rs
