Expand description
Versioned Rust records with explicit field conversions and frozen schema checks.
A shop starts by storing receipts with an amount in US cents. Later, it adds a
currency field. New code needs that field, but old receipts still contain only
the amount. Type History keeps the old record shape and runs your conversion
to supply "USD" when those receipts are read.
#[versioned] generates a Rust struct for each supported version of a record.
A new ReceiptCreated history starts with ReceiptCreatedV1. Later versions
add ReceiptCreatedV2, ReceiptCreatedV3, and so on. The original name aliases
the latest struct: at V2, the macro generates pub type ReceiptCreated = ReceiptCreatedV2;.
Use the alias’s into_versioned method to create a Versioned containing
the data and its generated metadata.
Serialize that record with JSON or named-field MessagePack, and store the
bytes where your application chooses. After deserialization, the alias’s
from_versioned method applies the declared conversions and returns the
latest type. Application code reads and writes through that alias.
After setting up a library package, start the receipt history with a stable name:
use type_history::versioned;
#[versioned(stable_name = "shop.receipt.created")]
pub struct ReceiptCreated {
pub amount_cents: u64,
}The stable name is frozen with the schemas. Builds reject changes to that value, even when the Rust type or its module is renamed. Frozen schemas protect the stored shape; your conversion functions and tests must preserve what the values mean.
Conversions run from older versions to the current version. A consumer built with only V1 rejects a V2 receipt. Services sharing a types crate must therefore coordinate which versions they publish and accept; see the distributed-system walkthrough.
Install the matching 0.3.3 crates from crates.io. The package setup guide shows the matching runtime, build hook, and CLI configuration. The guide configures schema checks and initializes the ledger before any history declaration. The current setup requires Rust 1.97 or later. Type History supports Linux and macOS. Windows is not supported. The book links to field rules, lifecycle commands, and error handling.
For existing storage that keeps JSON payloads and metadata separately, the
low-level decode API reads the payload using that metadata. Validate it
when reading it from storage:
use type_history::{PayloadVersion, StableName};
let stable_name = StableName::try_from("billing.invoice.issued".to_owned())?;
let version = PayloadVersion::try_from(1_u32)?;
assert_eq!(stable_name.as_str(), "billing.invoice.issued");
assert_eq!(version.get(), 1);
assert!(PayloadVersion::try_from(0_u32).is_err());A receipt may contain another record or an enum. The Schema derive
describes how those supporting types are serialized so changes can be checked
against frozen schemas. It supports named records, nonempty tuple structs,
and externally tagged enums, including inside supported containers.
Keep earlier enum definitions when a containing field
changes type; #[versioned] remains restricted to concrete named-field structs.
ResolvedSchema, JsonSchemaField, and FieldSchema provide the
underlying schema description and export traits.
String-keyed hash/tree maps share a storage contract. Sets carry an explicit
SetMembership contract and differ from vectors. Custom membership IDs are
trusted declarations of equality; schema derivation does not verify custom
Eq, Hash, or Ord. A membership change requires a versioned field update.
Bare tuples support arities 1 through 16. Owned Box values preserve the inner
contract; feature rc adds Rc and Arc by value.
Histories containing tuples above arity 12 must set derive_debug = false
and derive_partial_eq = false.
Optional features typed-floats, uuid, rust-decimal, chrono, and time
add finite numeric types and checked adapters. Defaults are empty. Adapters
own their serialization, so native dependencies’ Serde features do not change
stored profiles. See the field integration guide.
Modules§
- adapters
- Checked field adapters with stable storage contracts.
Structs§
- Constant
Membership - Allocation-free membership declaration used by frozen schema assertions.
- Decode
Context - Immutable original and adjacent version context for a decoding failure.
- Decode
Error - Decoding failure with original and adjacent version context.
- Field
Schema - Routes a persisted field type to the
schemarsform of its wire type. - History
- Exact-version decoder followed by adjacent typed conversions.
- Invalid
Payload Version - Error returned when a raw payload schema version is zero.
- Payload
Version - Positive schema version of one durable record.
- Stable
Name - Validated stable name shared by every version of a type.
- Versioned
- A serializable value that keeps its stable name, version, and data together.
Enums§
- Decode
Failure Kind - Stable classification of historical decoding failures.
- Invalid
Stable Name - Invalid stable name for a type and its history.
- Read
Error - A stored stable name mismatch or an exact-version decoding failure.
Traits§
- HasHistory
- Current record with a generated exact-version history.
- Json
Schema Field - The
schemarsform of one persisted field type. - Resolved
Schema - Structural schema resolved through Rust trait selection.
- SetMembership
- Declares the equality rule used when this type is a set element.
Functions§
- decode
- Read a JSON payload whose stable name and version are stored separately.
Attribute Macros§
- versioned
- Generate numbered structs and an alias for the current version.
Derive Macros§
- Schema
- Describe how a supporting record, nonempty tuple struct, or enum is serialized.