Crate typeid_suffix

Crate typeid_suffix 

Source
Expand description

§TypeID Suffix

typeid_suffix is a Rust library that implements the suffix portion of the TypeID Specification. It provides functionality to work with TypeID suffixes, which are base32-encoded representations of UUIDs used in the TypeID system.

This crate offers a robust, efficient, and user-friendly way to generate, encode, decode, and validate TypeID suffixes, supporting various UUID versions.

§Features

  • UUID Version Support: Implements support for UUIDv7 and other UUID versions.
  • Flexible Architecture: Generic implementation allows for handling various UUID versions.
  • Base32 Encoding/Decoding: Efficient encoding and decoding of UUIDs to/from base32 TypeID suffixes.
  • Error Handling: Comprehensive error types for invalid suffixes and UUIDs.
  • Validation: Robust validation for TypeID suffixes and UUIDs.
  • Zero-cost Abstractions: Designed to have minimal runtime overhead.
  • Optional Tracing: Integrates with the tracing crate for logging (optional feature).

§Quick Start

Add this to your Cargo.toml:

[dependencies]
typeid_suffix = "1.3.0"

§Usage Examples

§Creating a TypeID Suffix

By default, calling TypeIdSuffix::default() produces a suffix made from a UUIDv7 using the current timestamp.

use typeid_suffix::prelude::*;

let default_suffix = TypeIdSuffix::default();
println!("Default `TypeID` suffix: {}", default_suffix);

You can also create a TypeID suffix for a specific UUID version:

use typeid_suffix::prelude::*;

// Create a `TypeID` suffix from a `UUIDv7`
let suffix = TypeIdSuffix::new::<V7>();
println!("TypeID suffix: {}", suffix);

§Parsing a TypeID Suffix

use std::str::FromStr;
use typeid_suffix::prelude::*;

let suffix_str = "01h455vb4pex5vsknk084sn02q";
let parsed_suffix = TypeIdSuffix::from_str(suffix_str).expect("Valid suffix");
println!("Parsed suffix: {}", parsed_suffix);

§Converting Between UUID and TypeID Suffix

use typeid_suffix::prelude::*;
use uuid::Uuid;

let uuid = Uuid::new_v4();
let suffix: TypeIdSuffix = uuid.into();
println!("TypeID suffix: {}", suffix);

let recovered_uuid: Uuid = suffix.try_into().expect("Valid UUID");
assert_eq!(uuid, recovered_uuid);

§Error Handling

use typeid_suffix::prelude::*;
use std::str::FromStr;

let result = TypeIdSuffix::from_str("invalid_suffix");
match result {
    Ok(_) => println!("Valid suffix"),
    Err(e) => println!("Invalid suffix: {}", e),
}

§Optional Features

  • instrument: Enables logging with the tracing crate.
  • serde: Enables serialization and deserialization support using the serde crate.

To enable optional features, add them to your Cargo.toml:

[dependencies]
typeid_suffix = { version = "1.2.0", features = ["instrument", "serde"] }

§Serde Support

When the serde feature is enabled, TypeIdSuffix implements serde::Serialize and serde::Deserialize. This allows TypeIdSuffix instances to be easily serialized to and deserialized from various formats like JSON, YAML, CBOR, etc., that are supported by Serde.

TypeIdSuffix is serialized as its string representation and deserialized from a string.

// Enable the serde feature in your Cargo.toml:
// typeid_suffix = { version = "1.2.0", features = ["serde"] }

use typeid_suffix::prelude::*;
// Note: serde_json is used here as an example and would be a separate dependency.
use serde_json;

// Serializing a TypeIdSuffix
let suffix = TypeIdSuffix::default();
let json_string = serde_json::to_string(&suffix).unwrap();
println!("Serialized: {}", json_string); // e.g., "01h455vb4pex5vsknk084sn02q" (with quotes)

// Deserializing a TypeIdSuffix
let deserialized_suffix: TypeIdSuffix = serde_json::from_str(&json_string).unwrap();
assert_eq!(suffix, deserialized_suffix);

// Example of deserialization error
let invalid_json = "\"invalid_suffix_too_long_or_invalid_chars\"";
let result: Result<TypeIdSuffix, _> = serde_json::from_str(invalid_json);
assert!(result.is_err());

§License

This project is licensed under either of

at your option.

§Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Modules§

prelude
The prelude module provides a convenient way to import commonly used items.