facet

facet

facet is an ecosystem of Rust crates built on runtime reflection.

The core crates give types a SHAPE associated constant with their kind, layout, fields, documentation, attributes, and type-specific operations. facet-reflect builds, reads, and mutates values through those shapes while preserving their invariants.

Serialization and integration crates build on that reflection layer: JSON, TOML, YAML, MessagePack, Postcard, ASN.1, XDR, CSV, XML, URL-encoded forms, SQLite, Axum, schema generation, structural diffing, and more.

Some related projects now live in their own repositories:

• Figue for CLI and configuration loading
• Styx for typed configuration documents
• Dibs for Postgres schemas and queries
• Phon for schema-aware binary encoding
• Vox for cross-language RPC
• Weavy for lowered programs and copy-patch execution
• Snark for parser generation
• Vixen for the Vix language and runtime

Website note

The https://facet.rs website has a lot of information about a lot of the ecosystem but it’s unfortunately not super reliable as LLMs have been doing too much of the writing (on account on Amos being burned out). This is being slowly repaired. Bear with us.

Workspace contents

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-macros
• facet-macros, which implements the [Facet] derive attribute as a fast/light proc macro powered by unsynn

For struct manipulation and reflection, we have:

• facet-reflect, allows building values of arbitrary shapes in safe code, respecting invariants. It also allows peeking at existing values.

Internal crates include:

• facet-testhelpers a simple log logger and color-backtrace configured with the lightweight btparse backend

Ecosystem

Various crates live under the https://github.com/facet-rs umbrella, and their repositories are kept somewhat-consistent through facet-dev.

Crates are in various states of progress, buyer beware!

In terms of data formats, we have:

• facet-json: JSON format support
• facet-toml: TOML format support
• facet-yaml: YAML format support
• facet-msgpack: MessagePack deserialization
• facet-asn1: ASN.1 format support
• facet-xdr: XDR format support
• facet-csv: CSV format support
• facet-xml: XML format support

Still adjacent to serialization/deserialization, we have:

• facet-urlencoded: URL-encoded form data deserialization
• figue: CLI arguments, config files, and environment variables (external crate)

As far as utilities go:

• facet-value: Memory-efficient dynamic value type, supporting JSON-like data plus bytes
• facet-pretty: Pretty-print Facet types
• facet-diff: Diffing capabilities for Facet types
• facet-assert: Pretty assertions for Facet types (no PartialEq required)
• facet-serialize: Generic iterative serialization facilities
• facet-deserialize: Generic iterative deserialization facilities

And the less developed:

• facet-inspect: Utilities to inspect the content of a Facet object

Previously separate crates

These crates previously lived in separate repositories and now live in this monorepo:

• facet-xml: XML/DOM ecosystem (includes facet-xml, facet-dom, facet-svg, facet-atom, facet-xml-node, facet-singularize)
• facet-axum: Axum web framework integration

Extended cinematic universe

Some crates are developed completely independently from the facet org:

• facet-v8 provides an experimental Facet/v8 integration
• facet-openapi (experimental) Generates OpenAPI definitions from types that implement Facet
• facet_generate reflects Facet types into Java, Swift and TypeScript
• multi-array-list provides an experimental MultiArrayList type

Sponsors

Thanks to all individual sponsors:

…without whom this work could not exist.

Special thanks

The facet logo was drawn by Misiasart.

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.