use core::fmt;
use core::hash::{Hash, Hasher};
use core::marker::PhantomData;
use core::str::FromStr;
use uuid::Uuid;
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum IdError {
#[error("invalid UUID format")]
Uuid,
#[error("invalid numeric id")]
Number,
#[error("numeric id {value} does not fit into BIGINT (i64)")]
NumberTooLarge {
value: u64,
},
#[error("negative numeric id {value} in database does not fit into an unsigned id")]
NumberNegative {
value: i64,
},
}
pub struct Id<Tag>(Uuid, PhantomData<fn() -> Tag>);
impl<Tag> Id<Tag> {
#[must_use]
pub fn new_v4() -> Self {
Self::from_uuid(Uuid::new_v4())
}
#[must_use]
pub fn now_v7() -> Self {
Self::from_uuid(Uuid::now_v7())
}
#[inline]
#[must_use]
pub const fn from_uuid(uuid: Uuid) -> Self {
Self(uuid, PhantomData)
}
pub fn parse(value: &str) -> Result<Self, IdError> {
Uuid::parse_str(value.trim())
.map(Self::from_uuid)
.map_err(|_| IdError::Uuid)
}
#[inline]
#[must_use]
pub const fn as_uuid(&self) -> &Uuid {
&self.0
}
#[inline]
#[must_use]
pub const fn into_uuid(self) -> Uuid {
self.0
}
#[must_use]
pub fn version(&self) -> Option<uuid::Version> {
self.0.get_version()
}
#[must_use]
pub const fn is_nil(&self) -> bool {
self.0.is_nil()
}
}
impl<Tag> Clone for Id<Tag> {
fn clone(&self) -> Self {
*self
}
}
impl<Tag> Copy for Id<Tag> {}
impl<Tag> PartialEq for Id<Tag> {
fn eq(&self, other: &Self) -> bool {
self.0 == other.0
}
}
impl<Tag> Eq for Id<Tag> {}
impl<Tag> PartialOrd for Id<Tag> {
fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
Some(self.cmp(other))
}
}
impl<Tag> Ord for Id<Tag> {
fn cmp(&self, other: &Self) -> core::cmp::Ordering {
self.0.cmp(&other.0)
}
}
impl<Tag> Hash for Id<Tag> {
fn hash<H: Hasher>(&self, state: &mut H) {
self.0.hash(state);
}
}
impl<Tag> fmt::Debug for Id<Tag> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let tag = core::any::type_name::<Tag>()
.rsplit("::")
.next()
.unwrap_or("?");
write!(f, "Id<{tag}>({})", self.0)
}
}
impl<Tag> fmt::Display for Id<Tag> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Display::fmt(self.0.as_hyphenated(), f)
}
}
impl<Tag> FromStr for Id<Tag> {
type Err = IdError;
fn from_str(s: &str) -> Result<Self, IdError> {
Self::parse(s)
}
}
impl<Tag> TryFrom<&str> for Id<Tag> {
type Error = IdError;
fn try_from(value: &str) -> Result<Self, IdError> {
Self::parse(value)
}
}
impl<Tag> TryFrom<String> for Id<Tag> {
type Error = IdError;
fn try_from(value: String) -> Result<Self, IdError> {
Self::parse(&value)
}
}
impl<Tag> From<Uuid> for Id<Tag> {
fn from(uuid: Uuid) -> Self {
Self::from_uuid(uuid)
}
}
impl<Tag> From<Id<Tag>> for Uuid {
fn from(id: Id<Tag>) -> Self {
id.0
}
}
impl<Tag> From<Id<Tag>> for String {
fn from(id: Id<Tag>) -> Self {
id.to_string()
}
}
#[cfg(feature = "serde")]
impl<Tag> serde::Serialize for Id<Tag> {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
self.0.serialize(serializer)
}
}
#[cfg(feature = "serde")]
impl<'de, Tag> serde::Deserialize<'de> for Id<Tag> {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
Uuid::deserialize(deserializer).map(Self::from_uuid)
}
}
#[cfg(any(feature = "sqlx-0_8", feature = "sqlx-0_9"))]
crate::sqlx_support::sqlx_via!(
Id<Tag> [Tag],
Uuid,
|u: Uuid| Ok::<_, core::convert::Infallible>(Id::from_uuid(u)),
|this: &Id<Tag>| &this.0
);
mod sealed {
pub trait Sealed {}
impl Sealed for u64 {}
impl Sealed for i64 {}
}
pub trait NumIdRepr:
sealed::Sealed + Copy + Ord + Hash + fmt::Display + FromStr + Send + Sync + 'static
{
const DEBUG_SUFFIX: &'static str;
fn to_bigint(self) -> Result<i64, IdError>;
fn from_bigint(value: i64) -> Result<Self, IdError>;
fn parse_repr(value: &str) -> Result<Self, IdError>;
#[cfg(feature = "serde")]
fn serialize_repr<S: serde::Serializer>(self, serializer: S) -> Result<S::Ok, S::Error>;
#[cfg(feature = "serde")]
fn deserialize_repr<'de, D: serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self, D::Error>;
}
impl NumIdRepr for u64 {
const DEBUG_SUFFIX: &'static str = "";
fn to_bigint(self) -> Result<i64, IdError> {
i64::try_from(self).map_err(|_| IdError::NumberTooLarge { value: self })
}
fn from_bigint(value: i64) -> Result<Self, IdError> {
Self::try_from(value).map_err(|_| IdError::NumberNegative { value })
}
fn parse_repr(value: &str) -> Result<Self, IdError> {
if value.is_empty() || !value.bytes().all(|b| b.is_ascii_digit()) {
return Err(IdError::Number);
}
value.parse().map_err(|_| IdError::Number)
}
#[cfg(feature = "serde")]
fn serialize_repr<S: serde::Serializer>(self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_u64(self)
}
#[cfg(feature = "serde")]
fn deserialize_repr<'de, D: serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self, D::Error> {
serde::Deserialize::deserialize(deserializer)
}
}
impl NumIdRepr for i64 {
const DEBUG_SUFFIX: &'static str = ", i64";
fn to_bigint(self) -> Result<Self, IdError> {
Ok(self)
}
fn from_bigint(value: Self) -> Result<Self, IdError> {
Ok(value)
}
fn parse_repr(value: &str) -> Result<Self, IdError> {
let digits = value.strip_prefix('-').unwrap_or(value);
if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
return Err(IdError::Number);
}
value.parse().map_err(|_| IdError::Number)
}
#[cfg(feature = "serde")]
fn serialize_repr<S: serde::Serializer>(self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_i64(self)
}
#[cfg(feature = "serde")]
fn deserialize_repr<'de, D: serde::Deserializer<'de>>(
deserializer: D,
) -> Result<Self, D::Error> {
serde::Deserialize::deserialize(deserializer)
}
}
pub struct NumId<Tag, R: NumIdRepr = u64>(R, PhantomData<fn() -> Tag>);
impl<Tag, R: NumIdRepr> NumId<Tag, R> {
#[inline]
#[must_use]
pub const fn new(value: R) -> Self {
Self(value, PhantomData)
}
pub fn parse(value: &str) -> Result<Self, IdError> {
R::parse_repr(value.trim()).map(Self::new)
}
#[inline]
#[must_use]
pub const fn get(&self) -> R {
self.0
}
pub fn to_bigint(&self) -> Result<i64, IdError> {
self.0.to_bigint()
}
#[must_use]
pub fn is_db_safe(&self) -> bool {
self.0.to_bigint().is_ok()
}
}
impl<Tag> NumId<Tag, u64> {
pub const MAX_DB_SAFE: u64 = i64::MAX as u64;
pub const fn try_new_db_safe(value: u64) -> Result<Self, IdError> {
if value > Self::MAX_DB_SAFE {
return Err(IdError::NumberTooLarge { value });
}
Ok(Self::new(value))
}
pub fn parse_db_safe(value: &str) -> Result<Self, IdError> {
Self::try_new_db_safe(Self::parse(value)?.0)
}
}
impl<Tag, R: NumIdRepr> Clone for NumId<Tag, R> {
fn clone(&self) -> Self {
*self
}
}
impl<Tag, R: NumIdRepr> Copy for NumId<Tag, R> {}
impl<Tag, R: NumIdRepr> PartialEq for NumId<Tag, R> {
fn eq(&self, other: &Self) -> bool {
self.0 == other.0
}
}
impl<Tag, R: NumIdRepr> Eq for NumId<Tag, R> {}
impl<Tag, R: NumIdRepr> PartialOrd for NumId<Tag, R> {
fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
Some(self.cmp(other))
}
}
impl<Tag, R: NumIdRepr> Ord for NumId<Tag, R> {
fn cmp(&self, other: &Self) -> core::cmp::Ordering {
self.0.cmp(&other.0)
}
}
impl<Tag, R: NumIdRepr> Hash for NumId<Tag, R> {
fn hash<H: Hasher>(&self, state: &mut H) {
self.0.hash(state);
}
}
impl<Tag, R: NumIdRepr> fmt::Debug for NumId<Tag, R> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let tag = core::any::type_name::<Tag>()
.rsplit("::")
.next()
.unwrap_or("?");
write!(f, "NumId<{tag}{}>({})", R::DEBUG_SUFFIX, self.0)
}
}
impl<Tag, R: NumIdRepr> fmt::Display for NumId<Tag, R> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Display::fmt(&self.0, f)
}
}
impl<Tag, R: NumIdRepr> FromStr for NumId<Tag, R> {
type Err = IdError;
fn from_str(s: &str) -> Result<Self, IdError> {
Self::parse(s)
}
}
impl<Tag, R: NumIdRepr> TryFrom<&str> for NumId<Tag, R> {
type Error = IdError;
fn try_from(value: &str) -> Result<Self, IdError> {
Self::parse(value)
}
}
impl<Tag, R: NumIdRepr> TryFrom<String> for NumId<Tag, R> {
type Error = IdError;
fn try_from(value: String) -> Result<Self, IdError> {
Self::parse(&value)
}
}
impl<Tag, R: NumIdRepr> From<NumId<Tag, R>> for String {
fn from(id: NumId<Tag, R>) -> Self {
id.to_string()
}
}
impl<Tag> From<u64> for NumId<Tag, u64> {
fn from(value: u64) -> Self {
Self::new(value)
}
}
impl<Tag> From<NumId<Tag, u64>> for u64 {
fn from(id: NumId<Tag, u64>) -> Self {
id.0
}
}
impl<Tag> From<i64> for NumId<Tag, i64> {
fn from(value: i64) -> Self {
Self::new(value)
}
}
impl<Tag> From<NumId<Tag, i64>> for i64 {
fn from(id: NumId<Tag, i64>) -> Self {
id.0
}
}
impl<Tag> TryFrom<NumId<Tag, u64>> for NumId<Tag, i64> {
type Error = IdError;
fn try_from(id: NumId<Tag, u64>) -> Result<Self, IdError> {
id.0.to_bigint().map(Self::new)
}
}
impl<Tag> TryFrom<NumId<Tag, i64>> for NumId<Tag, u64> {
type Error = IdError;
fn try_from(id: NumId<Tag, i64>) -> Result<Self, IdError> {
u64::from_bigint(id.0).map(Self::new)
}
}
#[cfg(feature = "serde")]
impl<Tag, R: NumIdRepr> serde::Serialize for NumId<Tag, R> {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
self.0.serialize_repr(serializer)
}
}
#[cfg(feature = "serde")]
impl<'de, Tag, R: NumIdRepr> serde::Deserialize<'de> for NumId<Tag, R> {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
R::deserialize_repr(deserializer).map(Self::new)
}
}
#[cfg(any(feature = "sqlx-0_8", feature = "sqlx-0_9"))]
mod sqlx_impls {
use super::{NumId, NumIdRepr};
macro_rules! num_id_type_decode {
($sqlx:ident) => {
impl<DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Type<DB> for NumId<Tag, R>
where
i64: ::$sqlx::Type<DB>,
{
fn type_info() -> DB::TypeInfo {
<i64 as ::$sqlx::Type<DB>>::type_info()
}
fn compatible(ty: &DB::TypeInfo) -> bool {
<i64 as ::$sqlx::Type<DB>>::compatible(ty)
}
}
impl<'r, DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Decode<'r, DB>
for NumId<Tag, R>
where
i64: ::$sqlx::Decode<'r, DB>,
{
fn decode(value: DB::ValueRef<'r>) -> Result<Self, ::$sqlx::error::BoxDynError> {
let raw = <i64 as ::$sqlx::Decode<'r, DB>>::decode(value)?;
Ok(Self::new(R::from_bigint(raw)?))
}
}
};
}
#[cfg(feature = "sqlx-0_8")]
macro_rules! num_id_encode_0_8 {
($sqlx:ident) => {
impl<'q, DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Encode<'q, DB>
for NumId<Tag, R>
where
i64: ::$sqlx::Encode<'q, DB>,
{
fn encode_by_ref(
&self,
buf: &mut DB::ArgumentBuffer<'q>,
) -> Result<::$sqlx::encode::IsNull, ::$sqlx::error::BoxDynError> {
let value = self.0.to_bigint()?;
<i64 as ::$sqlx::Encode<'q, DB>>::encode_by_ref(&value, buf)
}
}
};
}
#[cfg(feature = "sqlx-0_9")]
macro_rules! num_id_encode_0_9 {
($sqlx:ident) => {
impl<'q, DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Encode<'q, DB>
for NumId<Tag, R>
where
i64: ::$sqlx::Encode<'q, DB>,
{
fn encode_by_ref(
&self,
buf: &mut DB::ArgumentBuffer,
) -> Result<::$sqlx::encode::IsNull, ::$sqlx::error::BoxDynError> {
let value = self.0.to_bigint()?;
<i64 as ::$sqlx::Encode<'q, DB>>::encode_by_ref(&value, buf)
}
}
};
}
#[cfg(any(feature = "sqlx-0_8-postgres", feature = "sqlx-0_9-postgres"))]
macro_rules! num_id_pg_array {
($sqlx:ident) => {
impl<Tag, R: NumIdRepr> ::$sqlx::postgres::PgHasArrayType for NumId<Tag, R> {
fn array_type_info() -> ::$sqlx::postgres::PgTypeInfo {
<i64 as ::$sqlx::postgres::PgHasArrayType>::array_type_info()
}
fn array_compatible(ty: &::$sqlx::postgres::PgTypeInfo) -> bool {
<i64 as ::$sqlx::postgres::PgHasArrayType>::array_compatible(ty)
}
}
};
}
#[cfg(feature = "sqlx-0_8")]
num_id_type_decode!(sqlx_0_8);
#[cfg(feature = "sqlx-0_8")]
num_id_encode_0_8!(sqlx_0_8);
#[cfg(feature = "sqlx-0_8-postgres")]
num_id_pg_array!(sqlx_0_8);
#[cfg(feature = "sqlx-0_9")]
num_id_type_decode!(sqlx_0_9);
#[cfg(feature = "sqlx-0_9")]
num_id_encode_0_9!(sqlx_0_9);
#[cfg(feature = "sqlx-0_9-postgres")]
num_id_pg_array!(sqlx_0_9);
}
#[cfg(test)]
mod tests {
use super::*;
enum Order {}
type OrderId = Id<Order>;
type LegacyOrderId = NumId<Order>;
type SignedOrderId = NumId<Order, i64>;
#[test]
fn ids_are_typed_and_roundtrip() {
let a = OrderId::now_v7();
let b = OrderId::now_v7();
assert!(a < b);
assert_eq!(OrderId::parse(&a.to_string()).unwrap(), a);
assert_eq!(format!("{a:?}"), format!("Id<Order>({})", a.as_uuid()));
assert_eq!(a.version(), Some(uuid::Version::SortRand));
assert!(OrderId::parse("not-a-uuid").is_err());
assert!(OrderId::parse("42").is_err());
let n = LegacyOrderId::parse(" 42 ").unwrap();
assert_eq!(n.get(), 42);
assert_eq!(format!("{n:?}"), "NumId<Order>(42)");
assert!(LegacyOrderId::parse("-1").is_err());
assert!(LegacyOrderId::parse("+1").is_err());
assert!(LegacyOrderId::parse("").is_err());
}
#[test]
fn signed_repr_accepts_negative_legacy_ids() {
let n = SignedOrderId::parse(" -1 ").unwrap();
assert_eq!(n.get(), -1);
assert_eq!(n.to_string(), "-1");
assert_eq!(format!("{n:?}"), "NumId<Order, i64>(-1)");
assert_eq!(SignedOrderId::parse(&n.to_string()).unwrap(), n); assert!(SignedOrderId::parse("+1").is_err());
assert!(SignedOrderId::parse("-").is_err());
assert!(SignedOrderId::parse("").is_err());
assert!(SignedOrderId::new(i64::MIN).is_db_safe());
assert_eq!(SignedOrderId::new(i64::MAX).to_bigint(), Ok(i64::MAX));
}
#[test]
fn db_safe_bounds_move_the_error_to_construction() {
const MAX: u64 = LegacyOrderId::MAX_DB_SAFE;
assert_eq!(MAX, i64::MAX as u64);
let too_big = LegacyOrderId::new(MAX + 1);
assert!(!too_big.is_db_safe());
assert_eq!(
too_big.to_bigint(),
Err(IdError::NumberTooLarge { value: MAX + 1 })
);
assert_eq!(LegacyOrderId::try_new_db_safe(MAX).unwrap().get(), MAX);
assert_eq!(
LegacyOrderId::try_new_db_safe(MAX + 1),
Err(IdError::NumberTooLarge { value: MAX + 1 })
);
assert!(LegacyOrderId::parse_db_safe("9223372036854775808").is_err());
assert!(LegacyOrderId::parse_db_safe("9223372036854775807").is_ok());
}
#[test]
fn repr_conversions_are_checked_both_ways() {
assert_eq!(
SignedOrderId::try_from(LegacyOrderId::new(42))
.unwrap()
.get(),
42
);
assert_eq!(
SignedOrderId::try_from(LegacyOrderId::new(u64::MAX)),
Err(IdError::NumberTooLarge { value: u64::MAX })
);
assert_eq!(
LegacyOrderId::try_from(SignedOrderId::new(42))
.unwrap()
.get(),
42
);
assert_eq!(
LegacyOrderId::try_from(SignedOrderId::new(-1)),
Err(IdError::NumberNegative { value: -1 })
);
}
#[test]
fn numid_conversions_match_the_rest_of_the_crate() {
let expected = LegacyOrderId::parse("42").unwrap();
assert_eq!(LegacyOrderId::try_from("42").unwrap(), expected);
assert_eq!(LegacyOrderId::try_from(" 42 ").unwrap(), expected);
assert_eq!(
LegacyOrderId::try_from(String::from("42")).unwrap(),
expected
);
assert_eq!(String::from(expected), "42");
assert_eq!(String::from(expected), expected.to_string());
let signed = SignedOrderId::try_from("-1").unwrap();
assert_eq!(signed.get(), -1);
assert_eq!(String::from(signed), "-1");
assert_eq!(LegacyOrderId::try_from("-1"), Err(IdError::Number));
assert_eq!(
LegacyOrderId::try_from(String::from("nope")),
Err(IdError::Number)
);
fn ingest<T: TryFrom<String>>(raw: &str) -> Result<T, T::Error> {
T::try_from(raw.to_owned())
}
assert!(ingest::<LegacyOrderId>("42").is_ok());
assert!(ingest::<OrderId>(&OrderId::now_v7().to_string()).is_ok());
assert!(ingest::<SignedOrderId>("-1").is_ok());
}
#[test]
fn id_is_send_sync_regardless_of_tag() {
fn assert_send_sync<T: Send + Sync>() {}
#[allow(dead_code)]
struct NotSync(core::cell::Cell<u8>);
assert_send_sync::<Id<NotSync>>();
assert_send_sync::<NumId<NotSync>>();
assert_send_sync::<NumId<NotSync, i64>>();
}
}