8 releases (4 stable)
1.1.3 | Nov 7, 2024 |
---|---|
1.1.2 | Oct 8, 2024 |
1.1.0 | Apr 12, 2024 |
1.0.1 | Feb 16, 2024 |
0.1.0 | Jan 31, 2024 |
#88 in Data structures
156,783 downloads per month
Used in 14 crates
(2 directly)
28KB
354 lines
newtype-uuid
A newtype wrapper around Uuid
.
Motivation
Many large systems use UUIDs as unique identifiers for various entities. However, the Uuid
type does not carry information about the kind of entity it identifies, which can lead to mixing
up different types of UUIDs at runtime.
This crate provides a wrapper type around Uuid
that allows you to specify the kind of entity
the UUID identifies.
Example
use newtype_uuid::{GenericUuid, TypedUuid, TypedUuidKind, TypedUuidTag};
// First, define a type that represents the kind of UUID this is.
enum MyKind {}
impl TypedUuidKind for MyKind {
fn tag() -> TypedUuidTag {
// Tags are required to be ASCII identifiers, with underscores
// and dashes also supported. The validity of a tag can be checked
// at compile time by assigning it to a const, like so:
const TAG: TypedUuidTag = TypedUuidTag::new("my_kind");
TAG
}
}
// Now, a UUID can be created with this kind.
let uuid: TypedUuid<MyKind> = "dffc3068-1cd6-47d5-b2f3-636b41b07084".parse().unwrap();
// The Display (and therefore ToString) impls still show the same value.
assert_eq!(uuid.to_string(), "dffc3068-1cd6-47d5-b2f3-636b41b07084");
// The Debug impl will show the tag as well.
assert_eq!(format!("{:?}", uuid), "dffc3068-1cd6-47d5-b2f3-636b41b07084 (my_kind)");
If you have a large number of UUID kinds, consider defining a macro for your purposes. An example macro:
macro_rules! impl_typed_uuid_kind {
($($kind:ident => $tag:literal),* $(,)?) => {
$(
pub enum $kind {}
impl TypedUuidKind for $kind {
#[inline]
fn tag() -> TypedUuidTag {
const TAG: TypedUuidTag = TypedUuidTag::new($tag);
TAG
}
}
)*
};
}
// Invoke this macro with:
impl_typed_uuid_kind! {
Kind1 => "kind1",
Kind2 => "kind2",
}
Implementations
In general, TypedUuid
uses the same wire and serialization formats as Uuid
. This means
that persistent representations of TypedUuid
are the same as Uuid
; TypedUuid
is
intended to be helpful within Rust code, not across serialization boundaries.
- The
Display
andFromStr
impls are forwarded to the underlyingUuid
. - If the
serde
feature is enabled,TypedUuid
will serialize and deserialize using the same format asUuid
. - If the
schemars08
feature is enabled,TypedUuid
will implementJsonSchema
if the correspondingTypedUuidKind
implementsJsonSchema
.
To abstract over typed and untyped UUIDs, the GenericUuid
trait is provided. This trait also
permits conversions between typed and untyped UUIDs.
Dependencies
- The only required dependency is the
uuid
crate. Optional features may add further dependencies.
Features
default
: Enables default features in the newtype-uuid crate.std
: Enables the use of the standard library. Enabled by default.serde
: Enables serialization and deserialization support via Serde. Not enabled by default.v4
: Enables thenew_v4
method for generating UUIDs. Not enabled by default.schemars08
: Enables support for generating JSON schemas via schemars 0.8. Not enabled by default. Note that the format of the generated schema is not currently part of the stable API, though we hope to stabilize it in the future.
Minimum supported Rust version (MSRV)
The MSRV of this crate is Rust 1.60. In general, this crate will follow the MSRV of the
underlying uuid
crate.
Within the 1.x series, MSRV updates will be accompanied by a minor version bump. The MSRVs for each minor version are:
- Version 1.0.x: Rust 1.60.
- Version 1.1.x: Rust 1.61. This permits
TypedUuid<T>
to haveconst fn
methods.
Alternatives
typed-uuid
: generally similar, but with a few design decisions that are different.
License
This project is available under the terms of either the Apache 2.0 license or the MIT license.
Dependencies
~205–520KB
~10K SLoC