Crate typex 

typex is a lightweight Rust library for inspecting, traversing, comparing and mutating values at runtime without knowing their concrete types. It supports no_std environments with alloc.

Available types

• Reflection traits: Meta and MetaMut
• Owned objects: Object, ObjectMut and SendObject
• Object trait: ObjectOps
• Borrowed views: ObjectRef and ObjectRefMut
• Typed map access: TypedMapAccess and TypedMapAccessMut
• Paths: PathSegment, OwnedPath and TypedPath
• Mutations: PatchOperation, MutationBatch and MutationRollback
• Type metadata: TypeInfo, ValueKind and AccessKind
• Structural shapes: Reflect and ReflectMut
• Shape access: StructAccess, TupleAccess, EnumAccess, SequenceAccess, KeyedSequenceAccess and MapAccess, with VariantFields for the fields of an enum variant
• Mutable shape access: StructAccessMut, TupleAccessMut, EnumAccessMut, SequenceAccessMut, KeyedSequenceAccessMut, MapAccessMut and OptionAccessMut, with VariantFieldsMut
• Type-keyed maps: TypeMap

Derive macros

The Meta and MetaMut derive macros are provided by typex_derive. Enable the derive feature to use them as Meta and MetaMut.

Structural equality

Meta::eq_dyn compares values with matching runtime type metadata. Its default implementation dispatches on the shape from Meta::reflect:

• Reflect::Struct compares field names, then fields by name.
• Reflect::Tuple compares lengths, then fields by index.
• Reflect::Enum compares active variant names, then their fields by name or index.
• Reflect::Map compares lengths, then looks up each visited key by string. It supports String and &'static str keys.
• Reflect::Sequence and Reflect::KeyedSequence compare lengths, then items by index.
• Reflect::Option compares presence and inner values.
• Reflect::Scalar returns false; scalar implementations provide their own value comparisons.

Built-in scalars, tuples, Result and the derives compare values directly, avoiding dispatch through the access traits. BTreeMap and HashMap compare native keys and reflective values. Custom opaque values provide equality through #[typex(partial_eq)] or a hand-written implementation. Float equality follows PartialEq, so NaN != NaN.

Feature flags

• std (default): Enables HashMap support and implementations of std::error::Error for the crate’s error types
• derive: Re-exports the Meta and MetaMut derive macros

Minimum supported Rust version (MSRV)

Rust v1.85+ is required.

Example

use typex::{Meta, Object, ObjectOps};

#[derive(Clone, Debug, Meta)]
struct Scope {
  name: &'static str,
}

#[derive(Debug, Meta)]
struct User {
  id: u16,
  scopes: Vec<Scope>,
}

let object = Object::new(User {
  id: 42,
  scopes: vec![Scope { name: "read" }],
});

assert!(object.is::<User>());
assert_eq!(object.type_name(), core::any::type_name::<User>());
assert_eq!(object.field_names(), &["id", "scopes"]);

assert_eq!(object.field("id").unwrap().to_ref::<u16>(), Some(&42));

let scope_name = |object: &Object| {
  object
    .field("scopes")?
    .item(0)?
    .field("name")?
    .to_ref::<&'static str>()
    .copied()
};
assert_eq!(scope_name(&object), Some("read"));

// Use typed paths to traverse fields without an explicit downcast
assert_eq!(object.field_path(User::FIELD_ID.path()), Some(&42));
assert_eq!(
  object.field_path(User::FIELD_SCOPES.item(0).then(Scope::FIELD_NAME)),
  Some(&"read")
);

Structs

AnyRef

Borrowed, type-erased reference to a value that exposes runtime type information and downcasts to the concrete type.

MutationBatch

Ordered list of patch operations that can be applied to a mutable reflective value.

MutationRollback

Holds inverse operations used by undo to revert a committed MutationBatch.

Object

Owned reflective value stored as a boxed Meta trait object.

ObjectMut

Owned mutable reflective value stored as a boxed MetaMut trait object.

ObjectRef

Borrowed reflective view of a Meta value.

ObjectRefMut

Borrowed mutable reflective view of a MetaMut value.

OwnedPath

Owned path used by staged operations and rollback records.

OwnedPathIter

Iterator over the segments of an OwnedPath.

RollbackError

Failure returned by MutationRollback::undo.

SendObject

Owned value with reflective access whose concrete value is Send and Sync.

TypeInfo

Shallow metadata about a type, containing its qualified Rust name and type ID. Equality and hashing are based only on the type ID.

TypeMap

Maps type identities to values of type T. Useful for registries and dispatch tables.

TypedField

A single typed field segment that can be composed into a TypedPath.

TypedPath

Typed path from a Root value to a nested Value.

Enums

AccessKind

Describes how a reflected value can be accessed.

ApplyError

Failure returned when applying a reflective patch. Paths in failure variants borrow names from the patch operation.

CommitError

Failure returned by a staged commit.

CommitOperationError

An operation failure reported by MutationBatch::commit.

MoveItemError

Failure returned when a sequential value cannot move an item.

OwnedPatchOperation

One owned operation waiting for a staged commit.

PatchOperation

Operation in a patch, applied with ObjectRefMut::apply or staged in a MutationBatch.

PatchOperationKind

Operation kinds used to identify unsupported patch requests.

PathSegment

Borrowed path segment for nested reflective traversal.

Reflect

Read-only structural shape of a Meta value.

ReflectMut

Mutable structural shape of a MetaMut value.

ReflectiveError

Failure returned by reflective path traversal or mutable operations.

ValueKind

Classifies the structural shape exposed by a Meta implementation.

VariantFields

Fields of the active variant of an enum.

VariantFieldsMut

Mutable fields of the active variant of an enum.

Traits

EnumAccess

Variant access for Reflect::Enum.

EnumAccessMut

Mutable variant access for ReflectMut::Enum.

FieldPathQuery

Path accepted by field_path. Its kind determines the return type.

FieldPathQueryMut

Path accepted by field_path_mut and ObjectRefMut::set_field_path: the mutable counterpart of FieldPathQuery.

KeyedSequenceAccess

Indexed and keyed item access for Reflect::KeyedSequence, such as a list of records with unique IDs.

KeyedSequenceAccessMut

Mutable indexed and keyed item access for ReflectMut::KeyedSequence.

MapAccess

Keyed entry access for Reflect::Map.

MapAccessMut

Mutable keyed entry access for ReflectMut::Map.

Meta

Read-only reflection for runtime type information, structural navigation and downcasting to a concrete type.

MetaMut

Mutable reflection extension of Meta.

ObjectOps

Conversion and downcasting helpers for owned reflective objects.

OptionAccessMut

Mutable access for ReflectMut::Option.

SendMeta

Thread-safe counterpart of Meta for boxed values moved across threads.

SequenceAccess

Indexed item access for Reflect::Sequence, such as a Vec or VecDeque.

SequenceAccessMut

Mutable indexed item access for ReflectMut::Sequence.

StructAccess

Field access for Reflect::Struct and for the active variant of a Reflect::Enum with named fields.

StructAccessMut

Mutable named field access for ReflectMut::Struct and for enum variants with named fields.

TupleAccess

Positional field access for Reflect::Tuple and for tuple enum variants.

TupleAccessMut

Mutable positional field access for ReflectMut::Tuple and for tuple enum variants.

TypedMap

Associates a map with the type of its values.

TypedMapAccess

Typed key lookup for map-like values.

TypedMapAccessMut

Typed mutable key lookup for map-like values.

TypedSequence

Associates a sequential value with the type of each indexed item.

Type Aliases

MapEntryVisitor

Callback for enumerating map entries through reflection.

Derive Macros

Meta

Derives structural typex::Meta for a struct or enum.

MetaMut

Derives mutable typex::MetaMut for a struct or enum.