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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
<!-- cargo-sync-rdme title [[ -->
# newtype-uuid
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme badge [[ -->
[](https://crates.io/crates/newtype-uuid)
[](https://docs.rs/newtype-uuid)
[](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
<!-- cargo-sync-rdme ]] -->
<!-- cargo-sync-rdme rustdoc [[ -->
A newtype wrapper around [`Uuid`](https://docs.rs/uuid/1.17.0/uuid/struct.Uuid.html).
## Motivation
Many large systems use UUIDs as unique identifiers for various entities. However, the [`Uuid`](https://docs.rs/uuid/1.17.0/uuid/struct.Uuid.html)
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`](https://docs.rs/uuid/1.17.0/uuid/struct.Uuid.html) that allows you to specify the kind of entity
the UUID identifies.
## Example
````rust
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 using
[`newtype-uuid-macros`] which comes with several convenience features.
````rust
use newtype_uuid_macros::impl_typed_uuid_kinds;
// Invoke this macro with:
impl_typed_uuid_kinds! {
kinds = {
User = {},
Project = {},
// ...
},
}
````
See [`newtype-uuid-macros`] for more information.
For simpler cases, you can also write your own declarative macro. Use this
template to get started:
````rust
macro_rules! impl_kinds {
($($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_kinds! {
UserKind => "user",
ProjectKind => "project",
}
````
## Implementations
In general, [`TypedUuid`](https://docs.rs/newtype-uuid/1.2.4/newtype_uuid/struct.TypedUuid.html) uses the same wire and serialization formats as [`Uuid`](https://docs.rs/uuid/1.17.0/uuid/struct.Uuid.html). This means
that persistent representations of [`TypedUuid`](https://docs.rs/newtype-uuid/1.2.4/newtype_uuid/struct.TypedUuid.html) are the same as [`Uuid`](https://docs.rs/uuid/1.17.0/uuid/struct.Uuid.html); [`TypedUuid`](https://docs.rs/newtype-uuid/1.2.4/newtype_uuid/struct.TypedUuid.html) is
intended to be helpful within Rust code, not across serialization boundaries.
* The `Display` and `FromStr` impls are forwarded to the underlying [`Uuid`](https://docs.rs/uuid/1.17.0/uuid/struct.Uuid.html).
* If the `serde` feature is enabled, `TypedUuid` will serialize and deserialize using the same
format as [`Uuid`](https://docs.rs/uuid/1.17.0/uuid/struct.Uuid.html).
* If the `schemars08` feature is enabled, [`TypedUuid`](https://docs.rs/newtype-uuid/1.2.4/newtype_uuid/struct.TypedUuid.html) will implement `JsonSchema` if the
corresponding [`TypedUuidKind`](https://docs.rs/newtype-uuid/1.2.4/newtype_uuid/trait.TypedUuidKind.html) implements `JsonSchema`.
To abstract over typed and untyped UUIDs, the [`GenericUuid`](https://docs.rs/newtype-uuid/1.2.4/newtype_uuid/trait.GenericUuid.html) trait is provided. This trait also
permits conversions between typed and untyped UUIDs.
## Dependencies
* The only required dependency is the [`uuid`](https://docs.rs/uuid/1.17.0/uuid/index.html) 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 the `new_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.
* `proptest1`: Enables support for generating `proptest::Arbitrary` instances of UUIDs. *Not enabled by default.*
## Minimum supported Rust version (MSRV)
The MSRV of this crate is **Rust 1.79.** In general, this crate will follow the MSRV of the
underlying `uuid` crate or of dependencies, with an aim to be conservative.
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 have `const fn` methods.
* Version **1.2.x**: Rust 1.67, required by some dependency updates.
* Version **1.3.x**: Rust 1.79, required by some dependency updates.
## Alternatives
* [`typed-uuid`](https://crates.io/crates/typed-uuid): generally similar, but with a few design
decisions that are different.
[`newtype-uuid-macros`]: https://docs.rs/newtype-uuid-macros
<!-- cargo-sync-rdme ]] -->
## License
This project is available under the terms of either the [Apache 2.0 license](LICENSE-APACHE) or the [MIT
license](LICENSE-MIT).
|
