Skip to main content

Crate type_history

Crate type_history 

Source
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§

ConstantMembership
Allocation-free membership declaration used by frozen schema assertions.
DecodeContext
Immutable original and adjacent version context for a decoding failure.
DecodeError
Decoding failure with original and adjacent version context.
FieldSchema
Routes a persisted field type to the schemars form of its wire type.
History
Exact-version decoder followed by adjacent typed conversions.
InvalidPayloadVersion
Error returned when a raw payload schema version is zero.
PayloadVersion
Positive schema version of one durable record.
StableName
Validated stable name shared by every version of a type.
Versioned
A serializable value that keeps its stable name, version, and data together.

Enums§

DecodeFailureKind
Stable classification of historical decoding failures.
InvalidStableName
Invalid stable name for a type and its history.
ReadError
A stored stable name mismatch or an exact-version decoding failure.

Traits§

HasHistory
Current record with a generated exact-version history.
JsonSchemaField
The schemars form of one persisted field type.
ResolvedSchema
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.