Reflect types annotated with #[derive(Facet)] into Swift, Kotlin, TypeScript, and C#. Optionally generates serialization and deserialization code for Bincode and JSON encodings.
The API documentation is on docs.rs, together with a guide that covers the crate in more depth:
- Why
facet_generate, and how it compares: the problem it solves, and how it differs from UniFFI, typeshare, serde-generate, ts-rs and specta. - Supported types: every Rust type the reflector accepts, what it becomes in each language, and what is rejected.
- Serialization: what the bincode and JSON plugins generate, and how their output lines up with Rust's
bincodeandserde_json. - Swift, Kotlin, C# and TypeScript: the installer, the package it writes, runtimes, namespaces, external packages and toolchains.
- Writing a plugin: extending the generated code through
EmitterPlugin. - Contributing: how the crate's own tests are organised.
cargo add facet facet_generate facet-generate-attrsThe #[facet(fg::…)] attributes expand to paths in facet_generate_attrs, so a crate that uses them must depend on facet-generate-attrs directly.
use facet::Facet;
use facet_generate::reflection::RegistryBuilder;
#[derive(Facet)]
struct Point {
x: f64,
y: f64,
}
#[derive(Facet)]
#[repr(C)]
enum Shape {
Circle { centre: Point, radius: f64 },
Rectangle { position: Point, width: f64, height: f64 },
}
// Point is discovered automatically as a field type of Shape
let registry = RegistryBuilder::new()
.add_type::<Shape>()?
.build()?;To generate code from the registry, use a language-specific Installer, then call generate() — the installer splits by namespace, installs runtimes, generates each module, and writes the package manifest. Add a plugin such as BincodePlugin or JsonPlugin to include serialization code and install whatever runtime it needs; omit .plugin(...) for plain type definitions only. BincodePlugin adds serialize/deserialize methods in every language. JsonPlugin writes and reads the JSON that Rust's serde_json does for the same types, so JSON written on either side reads on the other. It uses each platform's own JSON support where there is one: kotlinx.serialization in Kotlin, System.Text.Json in C# (with a generated converter per type), and Codable in Swift. In TypeScript it generates toJson/fromJson and installs a small runtime, serde/json.ts. C#, Swift and TypeScript types also get jsonSerialize/jsonDeserialize helpers (JsonSerialize/JsonDeserialize in C#). serde ignores unknown keys; to do the same in Kotlin, configure your Json with ignoreUnknownKeys = true. TypeScript reads and writes 64- and 128-bit integers beyond 2^53 exactly through JSON.rawJSON and the JSON.parse reviver's context.source, which need Node 21+, Deno 1.37+, Chrome 114+, Safari 18.4+ or Firefox 135+; on an older engine, only such an integer throws.
use facet_generate::generation::bincode::BincodePlugin;
// Swift
swift::Installer::new("MyPackage", &out_dir)
.plugin(BincodePlugin)
.generate(®istry)?;
// Kotlin
kotlin::Installer::new("com.example", &out_dir)
.plugin(BincodePlugin)
.generate(®istry)?;
// TypeScript
typescript::Installer::new("example", &out_dir)
.plugin(BincodePlugin)
.generate(®istry)?;
// C#
csharp::Installer::new("Example", &out_dir)
.plugin(BincodePlugin)
.generate(®istry)?;With BincodePlugin, structs and enums gain serialize/deserialize members. In TypeScript, where an enum is emitted as a discriminated union rather than a class, the plugin instead emits standalone serializeX/deserializeX functions alongside per-variant constructor functions and an exhaustive matchX helper. The examples below show the full generated module for both Point (struct) and Shape (enum) in each language.
Note
The code blocks below are generated from the real output of the code
generators and kept in sync by the readme integration test
(crates/facet_generate/tests/readme.rs). Do not edit them by hand — run
UPDATE_EXPECT=1 cargo test -p facet_generate --test readme to refresh them.
Swift
public struct Point: Hashable, Equatable {
public var x: Double
public var y: Double
public init(x: Double, y: Double) {
self.x = x
self.y = y
}
public func serialize<S: Serializer>(serializer: S) throws {
try serializer.increase_container_depth()
try serializer.serialize_f64(value: self.x)
try serializer.serialize_f64(value: self.y)
try serializer.decrease_container_depth()
}
public func bincodeSerialize() throws -> [UInt8] {
let serializer = BincodeSerializer.init();
try self.serialize(serializer: serializer)
return serializer.get_bytes()
}
public static func deserialize<D: Deserializer>(deserializer: D) throws -> Point {
try deserializer.increase_container_depth()
let x = try deserializer.deserialize_f64()
let y = try deserializer.deserialize_f64()
try deserializer.decrease_container_depth()
return Point(x: x, y: y)
}
public static func bincodeDeserialize(input: [UInt8]) throws -> Point {
let deserializer = BincodeDeserializer.init(input: input);
let obj = try deserialize(deserializer: deserializer)
if deserializer.get_buffer_offset() < input.count {
throw DeserializationError.invalidInput(issue: "Some input bytes were not read")
}
return obj
}
}
indirect public enum Shape: Hashable, Equatable {
case circle(centre: Point, radius: Double)
case rectangle(position: Point, width: Double, height: Double)
public func serialize<S: Serializer>(serializer: S) throws {
try serializer.increase_container_depth()
switch self {
case .circle(let centre, let radius):
try serializer.serialize_variant_index(value: 0)
try centre.serialize(serializer: serializer)
try serializer.serialize_f64(value: radius)
case .rectangle(let position, let width, let height):
try serializer.serialize_variant_index(value: 1)
try position.serialize(serializer: serializer)
try serializer.serialize_f64(value: width)
try serializer.serialize_f64(value: height)
}
try serializer.decrease_container_depth()
}
public func bincodeSerialize() throws -> [UInt8] {
let serializer = BincodeSerializer.init();
try self.serialize(serializer: serializer)
return serializer.get_bytes()
}
public static func deserialize<D: Deserializer>(deserializer: D) throws -> Shape {
let index = try deserializer.deserialize_variant_index()
try deserializer.increase_container_depth()
switch index {
case 0:
let centre = try Point.deserialize(deserializer: deserializer)
let radius = try deserializer.deserialize_f64()
try deserializer.decrease_container_depth()
return .circle(centre: centre, radius: radius)
case 1:
let position = try Point.deserialize(deserializer: deserializer)
let width = try deserializer.deserialize_f64()
let height = try deserializer.deserialize_f64()
try deserializer.decrease_container_depth()
return .rectangle(position: position, width: width, height: height)
default: throw DeserializationError.invalidInput(issue: "Unknown variant index for Shape: \(index)")
}
}
public static func bincodeDeserialize(input: [UInt8]) throws -> Shape {
let deserializer = BincodeDeserializer.init(input: input);
let obj = try deserialize(deserializer: deserializer)
if deserializer.get_buffer_offset() < input.count {
throw DeserializationError.invalidInput(issue: "Some input bytes were not read")
}
return obj
}
}Kotlin
data class Point(
val x: Double,
val y: Double,
) {
fun serialize(serializer: Serializer) {
serializer.increase_container_depth()
serializer.serialize_f64(x)
serializer.serialize_f64(y)
serializer.decrease_container_depth()
}
fun bincodeSerialize(): ByteArray {
val serializer = BincodeSerializer()
serialize(serializer)
return serializer.get_bytes()
}
companion object {
fun deserialize(deserializer: Deserializer): Point {
deserializer.increase_container_depth()
val x = deserializer.deserialize_f64()
val y = deserializer.deserialize_f64()
deserializer.decrease_container_depth()
return Point(x, y)
}
@Throws(DeserializationError::class)
fun bincodeDeserialize(input: ByteArray?): Point {
if (input == null) {
throw DeserializationError("Cannot deserialize null array")
}
val deserializer = BincodeDeserializer(input)
val value = deserialize(deserializer)
if (deserializer.get_buffer_offset() < input.size) {
throw DeserializationError("Some input bytes were not read")
}
return value
}
}
}
sealed interface Shape {
fun serialize(serializer: Serializer)
fun bincodeSerialize(): ByteArray {
val serializer = BincodeSerializer()
serialize(serializer)
return serializer.get_bytes()
}
data class Circle(
val centre: com.example.Point,
val radius: Double,
) : Shape {
override fun serialize(serializer: Serializer) {
serializer.increase_container_depth()
serializer.serialize_variant_index(0)
centre.serialize(serializer)
serializer.serialize_f64(radius)
serializer.decrease_container_depth()
}
companion object {
fun deserialize(deserializer: Deserializer): Circle {
deserializer.increase_container_depth()
val centre = com.example.Point.deserialize(deserializer)
val radius = deserializer.deserialize_f64()
deserializer.decrease_container_depth()
return Circle(centre, radius)
}
}
}
data class Rectangle(
val position: com.example.Point,
val width: Double,
val height: Double,
) : Shape {
override fun serialize(serializer: Serializer) {
serializer.increase_container_depth()
serializer.serialize_variant_index(1)
position.serialize(serializer)
serializer.serialize_f64(width)
serializer.serialize_f64(height)
serializer.decrease_container_depth()
}
companion object {
fun deserialize(deserializer: Deserializer): Rectangle {
deserializer.increase_container_depth()
val position = com.example.Point.deserialize(deserializer)
val width = deserializer.deserialize_f64()
val height = deserializer.deserialize_f64()
deserializer.decrease_container_depth()
return Rectangle(position, width, height)
}
}
}
companion object {
@Throws(DeserializationError::class)
fun deserialize(deserializer: Deserializer): Shape {
val index = deserializer.deserialize_variant_index()
return when (index) {
0 -> Circle.deserialize(deserializer)
1 -> Rectangle.deserialize(deserializer)
else -> throw DeserializationError("Unknown variant index for Shape: $index")
}
}
@Throws(DeserializationError::class)
fun bincodeDeserialize(input: ByteArray?): Shape {
if (input == null) {
throw DeserializationError("Cannot deserialize null array")
}
val deserializer = BincodeDeserializer(input)
val value = deserialize(deserializer)
if (deserializer.get_buffer_offset() < input.size) {
throw DeserializationError("Some input bytes were not read")
}
return value
}
}
}TypeScript
type float64 = number;
export class Point {
constructor (public x: float64, public y: float64) {
}
public serialize(serializer: Serializer): void {
serializer.serializeF64(this.x);
serializer.serializeF64(this.y);
}
static deserialize(deserializer: Deserializer): Point {
const x = deserializer.deserializeF64();
const y = deserializer.deserializeF64();
return new Point(x,y);
}
}
export type Shape =
| { kind: "Circle"; centre: Point; radius: float64 }
| { kind: "Rectangle"; position: Point; width: float64; height: float64 };
export const shapeCircle = (centre: Point, radius: float64): Shape => ({ kind: "Circle", centre, radius });
export const shapeRectangle = (position: Point, width: float64, height: float64): Shape => ({ kind: "Rectangle", position, width, height });
export function matchShape<R>(value: Shape, cases: {
Circle: (v: Extract<Shape, { kind: "Circle" }>) => R;
Rectangle: (v: Extract<Shape, { kind: "Rectangle" }>) => R;
}): R {
return cases[value.kind as Shape["kind"]](value as never);
}
export function serializeShape(value: Shape, serializer: Serializer): void {
switch (value.kind) {
case "Circle": {
serializer.serializeVariantIndex(0);
value.centre.serialize(serializer);
serializer.serializeF64(value.radius);
break;
}
case "Rectangle": {
serializer.serializeVariantIndex(1);
value.position.serialize(serializer);
serializer.serializeF64(value.width);
serializer.serializeF64(value.height);
break;
}
default: throw new Error("Unknown variant: " + (value as any).kind);
}
}
export function deserializeShape(deserializer: Deserializer): Shape {
const index = deserializer.deserializeVariantIndex();
switch (index) {
case 0: {
const centre = Point.deserialize(deserializer);
const radius = deserializer.deserializeF64();
return { kind: "Circle", centre, radius };
}
case 1: {
const position = Point.deserialize(deserializer);
const width = deserializer.deserializeF64();
const height = deserializer.deserializeF64();
return { kind: "Rectangle", position, width, height };
}
default: throw new Error("Unknown variant index for Shape: " + index);
}
}C#
namespace Example;
public partial class Point : ObservableObject, IFacetSerializable, IFacetDeserializable<Point> {
[ObservableProperty]
private double _x;
[ObservableProperty]
private double _y;
public void Serialize(ISerializer serializer)
{
serializer.IncreaseContainerDepth();
serializer.SerializeF64(X);
serializer.SerializeF64(Y);
serializer.DecreaseContainerDepth();
}
public static Point Deserialize(IDeserializer deserializer)
{
deserializer.IncreaseContainerDepth();
var x = deserializer.DeserializeF64();
var y = deserializer.DeserializeF64();
deserializer.DecreaseContainerDepth();
return new Point {
X = x,
Y = y,
};
}
public byte[] BincodeSerialize()
{
var serializer = new BincodeSerializer();
Serialize(serializer);
return serializer.GetBytes();
}
public static Point BincodeDeserialize(byte[] input)
{
if (input is null)
{
throw new DeserializationError("Cannot deserialize null array");
}
var deserializer = new BincodeDeserializer(input);
var value = Deserialize(deserializer);
if (deserializer.GetBufferOffset() < input.Length)
{
throw new DeserializationError("Some input bytes were not read");
}
return value;
}
}
public abstract record Shape : IFacetSerializable, IFacetDeserializable<Shape> {
public sealed partial record Circle(Point Centre, double Radius) : Shape;
public sealed partial record Rectangle(Point Position, double Width, double Height) : Shape;
public abstract void Serialize(ISerializer serializer);
private static Shape DeserializeCircle(IDeserializer deserializer)
{
var centre = Point.Deserialize(deserializer);
var radius = deserializer.DeserializeF64();
return new Circle(centre, radius);
}
public sealed partial record Circle
{
public override void Serialize(ISerializer serializer)
{
serializer.IncreaseContainerDepth();
serializer.SerializeVariantIndex(0);
Centre.Serialize(serializer);
serializer.SerializeF64(Radius);
serializer.DecreaseContainerDepth();
}
}
private static Shape DeserializeRectangle(IDeserializer deserializer)
{
var position = Point.Deserialize(deserializer);
var width = deserializer.DeserializeF64();
var height = deserializer.DeserializeF64();
return new Rectangle(position, width, height);
}
public sealed partial record Rectangle
{
public override void Serialize(ISerializer serializer)
{
serializer.IncreaseContainerDepth();
serializer.SerializeVariantIndex(1);
Position.Serialize(serializer);
serializer.SerializeF64(Width);
serializer.SerializeF64(Height);
serializer.DecreaseContainerDepth();
}
}
public static Shape Deserialize(IDeserializer deserializer)
{
var index = deserializer.DeserializeVariantIndex();
return index switch
{
0 => DeserializeCircle(deserializer),
1 => DeserializeRectangle(deserializer),
_ => throw new DeserializationError("Unknown variant index for Shape: " + index),
}
;
}
public byte[] BincodeSerialize()
{
var serializer = new BincodeSerializer();
Serialize(serializer);
return serializer.GetBytes();
}
public static Shape BincodeDeserialize(byte[] input)
{
if (input is null)
{
throw new DeserializationError("Cannot deserialize null array");
}
var deserializer = new BincodeDeserializer(input);
var value = Deserialize(deserializer);
if (deserializer.GetBufferOffset() < input.Length)
{
throw new DeserializationError("Some input bytes were not read");
}
return value;
}
}Types that are explicitly annotated as belonging to a specific namespace are emitted as separate modules. These can be within the same package, or in a separate package if specified in the config during type generation (using ExternalPackage).
- In Swift, namespaces become a separate target in the current package
- In Kotlin, they are emitted as a child namespace of the package's namespace
- In TypeScript they are emitted alongside as a separate
.tsfile - In C#, each namespace becomes a file-scoped
namespacewritten to a directory matching the dotted module path (e.g.Company.Models.Shared)
Notes:
- Once a namespace is set (via
#[facet(fg::namespace = "my_ns")]) either at field-level (call-site) or type-level (called site), it will propagate to child types. The latest namespace is in effect until changed or cancelled. Type-level annotations take priority over field-level annotations. - A namespace context can be unset (via
#[facet(fg::namespace)]). This is still an explicit annotation, so it cancels any implicit annotations being carried forwards from higher in the graph. It places the type (and any child types) in the ROOT namespace. - Namespaces are propagated through field level references, including via pointers and collections.
- Any ambiguity (i.e. a type is reached via more than one path, each with a different implicit namespace) will cause the typegen to emit an error, detailing the type involved and the namespaces that clash. The fix is then to either explicitly set (or unset) the type's namespace, or to align the inherited namespaces.
- Every generated name must belong to exactly one Rust type. If two different Rust types would generate the same name in the same namespace (
a::Deleteandb::Deleteboth in the root, say, or two types renamed to the same string), the builder returns an error naming both types by their Rust path, whether they were added directly or reached through a field. Rename one with#[facet(rename = "...")], or give it its own namespace with#[facet(fg::namespace = "...")]. The same Rust type reached many times, including recursively, is fine. - Each installer checks the namespaces before it writes anything, and fails with an error naming both sides when generated code couldn't compile: a namespace that collides with a type, with the root package or with another namespace (after case conversion); a namespace that would shadow a builtin or runtime name the generated code uses, such as
Mapin TypeScript orStringin Swift; a package name that is also an external package's namespace; and, in Swift, a cycle between targets, such as a root type holding a namespaced type that refers back to the root. Rename the type with#[facet(rename = "...")], or move it to a different namespace. For a Swift cycle, move the shared types into a namespace of their own.
#[derive(Facet)]
#[facet(fg::namespace = "server_sent_events")]
pub struct SseRequest {
pub url: String,
}
#[derive(Facet)]
#[facet(fg::namespace = "server_sent_events")]
#[repr(C)]
pub enum SseResponse {
Chunk(Vec<u8>),
Done,
}Renaming uses Facet's builtin rename and rename_all attributes, documented in Facet's field attributes and container attributes reference.
Rename a struct or enum in the generated output (the Rust name stays the same):
#[derive(Facet)]
#[facet(rename = "Effect")]
struct EffectFfi {
name: String,
active: bool,
}This also works on enums:
#[derive(Facet)]
#[facet(rename = "Effect")]
#[repr(C)]
enum EffectFfi {
One,
Two,
}When a renamed type is referenced from another struct, the generated code uses the new name automatically. The new name has to be free: renaming a type to the name of another type in the same namespace is rejected with an error that names both Rust types, since one of them would otherwise be lost from the generated output.
Rename individual struct fields with #[facet(rename = "...")]:
#[derive(Facet)]
struct Request {
#[facet(rename = "id")]
request_id: u32,
}This works for all field types — primitives, Option<T>, Vec<T>, and
user-defined types.
Rename individual enum variants:
#[derive(Facet)]
#[repr(C)]
enum Effect {
#[facet(rename = "Id")]
RequestId,
}Fields inside struct variants can also be renamed:
#[derive(Facet)]
#[repr(C)]
enum Message {
Info {
#[facet(rename = "msg")]
message: String,
},
}Apply a naming convention to all fields in a struct or all variants in an enum:
#[derive(Facet)]
#[facet(rename_all = "camelCase")]
struct Config {
request_id: u32,
user_name: String,
is_active: bool,
}This also works on enums:
#[derive(Facet)]
#[facet(rename_all = "camelCase")]
#[repr(C)]
enum Effect {
RequestId, // → requestId
SomeOtherVariant, // → someOtherVariant
}A per-field or per-variant rename always takes priority over rename_all:
#[derive(Facet)]
#[facet(rename_all = "camelCase")]
struct Request {
#[facet(rename = "id")] // "id", not "requestId"
request_id: u32,
}Container-level rename and field/variant-level rename (or rename_all) can
be combined freely.
Names reach the target language exactly as written (after rename / rename_all), so a
field called default or a variant called Default becomes an identifier that is a reserved
word in most targets. Each generator escapes such identifiers with the language's own
mechanism, so the member keeps its name and its wire name:
| Language | Escaping | default: String becomes |
|---|---|---|
| Swift | backticks | public var `default`: String |
| Kotlin | backticks (hard keywords only) | val default: String — default is not one; in is |
| TypeScript | property keeps its name; bindings get a _ suffix |
public default: str; set from default_ |
| C# | @ prefix on locals; properties are PascalCase anyway |
@default |
Backticks and @ are pure quoting, so a Kotlin @SerialName, a JSON key or a positional
bincode field is unaffected. In TypeScript a reserved word is legal as a property name but
not as a parameter or local, so a class with any reserved field declares its fields
explicitly and assigns them in the constructor from renamed parameters; classes without one
keep the compact parameter-property form. Kotlin soft keywords such as value, field,
import and data are ordinary identifiers and are left alone.
Plugins that derive identifiers from field or variant names should use the same helpers the
emitters use — swift::field_name, swift::case_name, kotlin::field_name,
kotlin::variant_class_name, kotlin::enum_constant_name, typescript::param_name and
csharp::escape_identifier, with swift::escape_identifier, kotlin::escape_identifier and
typescript::is_reserved_word as the lower-level escapes — so their output agrees with the
generated type.
A type can also take the name of a builtin the generated code relies on. crux_kv, for
example, has an operation struct called Set, which in Kotlin becomes a package-level
data class Set that hides kotlin.collections.Set for the whole package. Rather than
rejecting the name, the generators notice that the module declares it and write the builtin
fully qualified, only where it is shadowed:
data class Set(
val key: String,
val value: Bytes,
)
data class Store(
val tags: kotlin.collections.Set<String>,
val entries: Map<String, String>,
)The same happens for Swift.Set<String>, global::System.Collections.Generic.HashSet<string>
and globalThis.Map<str,str>. When nothing is shadowed the output is unchanged.
A few names cannot be escaped or qualified: a type named after something the module
imports explicitly (Serializer, Deserializer, Bytes, UUID, the TypeScript aliases
such as str and Seq), or a field that would become a member the language or the
generated code already provides (toString, copy or hashCode on a Kotlin data class,
GetHashCode or a property named like its class in C#, serializer and deserializer
everywhere). Generation stops before writing anything and says what to rename:
Kotlin: field `to_string` of `Foo` would become `toString`, which Kotlin generates for every data class; rename it with #[facet(rename = "...")]
An import that is only written beside a field of one format — Bytes, UUID,
BigInteger — only collides where such a field is: in the module, for a top-level type,
or in the enclosing enum, for a Kotlin variant, which becomes a nested class that outranks
the import inside that enum alone. So crux_kv's Value::Bytes(Vec<u8>) is
accepted, while an enum with both a Bytes variant and a #[facet(bytes)] field is not.
Serializer and the other names every generated type mentions are always rejected.
You can annotate fields or variants with #[facet(skip)] to prevent them from being emitted in the generated code. #[facet(opaque)] also leaves a field out, without reflecting its type, which is useful for a type the generator doesn't support.
#[derive(Facet)]
#[repr(C)]
pub enum Event {
Get,
#[facet(skip)]
Set(#[facet(opaque)] HttpResult<HttpResponse<Count>, HttpError>),
}You can skip through (even successive layers) of newtyping by annotating the struct with #[facet(transparent)].
#[derive(Facet)]
#[facet(transparent)]
struct Inner(i32);
#[derive(Facet)]
struct MyStruct {
inner: Inner,
}With #[facet(transparent)], Inner is unwrapped and MyStruct.inner is generated as a plain Int32 (Swift) / Int (Kotlin) / int32 (a TypeScript alias for number) / int (C#) in the target language.
In order to generate byte array types (e.g. [UInt8] in Swift, Bytes in Kotlin, bytes (an alias for Uint8Array) in TypeScript, byte[] in C#) for Vec<u8>, &'a [u8], [u8; N] and Bytes fields, or an Option of any of them, use the #[facet(fg::bytes)] attribute:
#[derive(Facet)]
pub struct HttpResponse {
pub status: u16,
pub headers: Vec<HttpHeader>,
#[facet(fg::bytes)]
pub body: Vec<u8>,
}