Logo by Misiasart

Thanks to all individual and corporate sponsors, without whom this work could not exist:

facet provides reflection for Rust: it gives types a SHAPE associated const with details on the layout, fields, doc comments, attributes, etc.

It can be used for many things, from (de)serialization to pretty-printing, rich debuggers, CLI parsing, reflection in templating engines, code generation, etc.

See https://facet.rs for details.

Known issues and limitations

We have the occasional soundness issue, see the soundness tag. Those are prioritized and fixed as soon as possible.

Format crates like facet-json are still very much incomplete, and will probably always be slower than the serde-* equivalent. Reflection has advantages in terms of flexibility, ergonomics and compile time but has a runtime cost compared to "monomorphize all the things".

(Note: with codegen, one could get the best of both worlds. To be researched more)

Some format crates (like facet-toml) first deserialize to a DOM, and then to partial structs — this is not as efficient as it could be, but it's a good first step.

Rust 1.86.0 has a compile error if you just import Facet but don't use it, see #75. This is fixed in nightly and will no longer be a problem with the next major Rust version.

type_eq is not const, thus preventing many useful things in const fn, see #98. Language changes are needed to address that.

The design of arbitrary attributes is still in flux, see:

• #108 (comment)
• #151 (comment)

There isn't a comparison between facet-reflect and bevy-reflect available right now— this is by design. We're letting facet develop on its own for a while; we'll make a detailed comparison once things have settled.

There are more issues and limitations of course, but this should get you started.

Ecosystem

The core crates, facet-trait, facet-types etc. are no_std-friendly.

The main facet crate re-exports symbols from:

• facet-core, which defines the main components:
  • The Facet trait and implementations for foreign types (mostly libstd)
  • The Shape struct along with various vtables and the whole Def tree
  • Type-erased pointer helpers like PtrUninit, PtrConst, and Opaque
  • Autoderef specialization trick needed for facet-derive
• facet-derive, which implements the Facet derive attribute as a fast/light proc macro powered by unsynn

For struct manipulation and reflection, the following is available:

• facet-reflect, allows building values of arbitrary shapes in safe code, respecting invariants. It also allows peeking at existing values.
• facet-pretty is able to pretty-print Facet types.

facet supports deserialization from multiple data formats through dedicated crates:

• facet-json: JSON deserialization
• facet-yaml: YAML deserialization
• facet-toml: TOML deserialization
• facet-msgpack: MessagePack deserialization
• facet-urlencoded: URL-encoded form data deserialization
• facet-args: CLI arguments (a-la clap)

Internal crates include:

• facet-codegen is internal and generates some of the code of facet-core
• facet-testhelpers a simpler log logger and color-backtrace configured with the lightweight btparse backend

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.