acton-ern 3.1.0

A Rust library for handling Entity Resource Names (ERNs), providing type-safe, hierarchical, and k-sortable resource identifiers for distributed systems and more.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

//! # Acton Entity Resource Name (ERN) Library
//!
//! `acton-ern` is a Rust library for working with Entity Resource Names (ERNs), which are structured identifiers
//! used to uniquely identify and manage hierarchical resources across different services and partitions in distributed systems.
//! While ERNs follow the Uniform Resource Name (URN) format defined in [RFC 8141](https://tools.ietf.org/html/rfc8141),
//! they extend beyond standard URNs by offering additional features like k-sortability and type-safe construction.
//!
//! ## Key Features
//!
//! - **Structured Resource Naming**: Create standardized, hierarchical resource identifiers that are both human-readable and machine-parseable
//! - **K-Sortable Identifiers**: When using `UnixTime` or `Timestamp` ID types, ERNs can be efficiently sorted and queried by creation time
//! - **Content-Addressable IDs**: When using `SHA1Name` ID type, generate deterministic IDs based on content
//! - **Type-Safe Construction**: The builder pattern ensures ERNs are constructed correctly at compile time
//! - **Flexible ID Types**: Choose the right ID type for your use case (time-based ordering or content-based addressing)
//! - **Hierarchical Relationships**: Model parent-child relationships between resources naturally
//! - **Serialization Support**: Serialize and deserialize ERNs to/from JSON and YAML (with the `serde` feature)
//!
//! ## Crate Structure
//!
//! - `builder`: Type-safe builder pattern for constructing ERNs
//! - `parser`: Tools for parsing ERN strings into structured components
//! - `model`: Component models (Domain, Category, Account, Root, Part)
//! - `traits`: Common traits used across the crate
//!
//! ## Basic Usage
//!
//! ```rust,ignore
//! use acton_ern::prelude::*;
//!
//! // Create a time-ordered, sortable ERN
//! let ern = ErnBuilder::new()
//!     .with::<Domain>("my-app")?
//!     .with::<Category>("users")?
//!     .with::<Account>("tenant123")?
//!     .with::<EntityRoot>("profile")?
//!     .with::<Part>("settings")?
//!     .build()?;
//!
//! // Parse an ERN from a string
//! let ern_str = "ern:my-app:users:tenant123:profile_01h9xz7n2e5p6q8r3t1u2v3w4x/settings";
//! let parsed_ern = ErnParser::new(ern_str.to_string()).parse()?;
//! ```
//!
//! ## Serialization/Deserialization
//!
//! With the `serde` feature enabled, ERNs can be serialized to and deserialized from formats like JSON and YAML:
//!
//! ```rust,ignore
//! // Enable the serde feature in Cargo.toml:
//! // acton-ern = { version = "3.1.0", features = ["serde"] }
//!
//! use acton_ern::prelude::*;
//! use serde_json;
//!
//! // Create an ERN
//! let ern = ErnBuilder::new()
//!     .with::<Domain>("my-app")?
//!     .with::<Category>("users")?
//!     .with::<Account>("tenant123")?
//!     .with::<EntityRoot>("profile")?
//!     .build()?;
//!
//! // Serialize to JSON
//! let json = serde_json::to_string(&ern)?;
//!
//! // Deserialize from JSON
//! let deserialized: Ern = serde_json::from_str(&json)?;
//! ```
//!

#![allow(missing_docs)]

extern crate core;

// Re-exporting the public API under the root of the crate for direct access
pub use builder::*;
pub use model::*;
pub use parser::*;
pub use traits::*;

mod builder;
mod errors;
mod model;
mod parser;
mod traits;

pub mod prelude {
    //! The prelude module for `acton-ern`.
    //!
    //! This module re-exports essential traits and structures for easy use in your application.
    //! Import this module with `use acton_ern::prelude::*;` to get access to all the commonly used
    //! types and traits without having to import them individually.

    pub use super::builder::ErnBuilder;
    pub use super::errors::ErnError;
    pub use super::model::{
        Account, Category, DEFAULT_MAX_PARTS, Domain, EntityRoot, Ern, Part, Parts, SHA1Name,
    };
    pub use super::parser::ErnParser;
    pub use super::traits::*;
}