1use core::fmt;
22use core::hash::{Hash, Hasher};
23use core::marker::PhantomData;
24use core::str::FromStr;
25
26use uuid::Uuid;
27
28#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
30#[non_exhaustive]
31pub enum IdError {
32 #[error("invalid UUID format")]
34 Uuid,
35 #[error("invalid numeric id")]
37 Number,
38 #[error("numeric id {value} does not fit into BIGINT (i64)")]
43 NumberTooLarge {
44 value: u64,
46 },
47 #[error("negative numeric id {value} in database does not fit into an unsigned id")]
51 NumberNegative {
52 value: i64,
54 },
55}
56
57pub struct Id<Tag>(Uuid, PhantomData<fn() -> Tag>);
66
67impl<Tag> Id<Tag> {
68 #[must_use]
70 pub fn new_v4() -> Self {
71 Self::from_uuid(Uuid::new_v4())
72 }
73
74 #[must_use]
76 pub fn now_v7() -> Self {
77 Self::from_uuid(Uuid::now_v7())
78 }
79
80 #[inline]
82 #[must_use]
83 pub const fn from_uuid(uuid: Uuid) -> Self {
84 Self(uuid, PhantomData)
85 }
86
87 pub fn parse(value: &str) -> Result<Self, IdError> {
89 Uuid::parse_str(value.trim())
90 .map(Self::from_uuid)
91 .map_err(|_| IdError::Uuid)
92 }
93
94 #[inline]
96 #[must_use]
97 pub const fn as_uuid(&self) -> &Uuid {
98 &self.0
99 }
100
101 #[inline]
103 #[must_use]
104 pub const fn into_uuid(self) -> Uuid {
105 self.0
106 }
107
108 #[must_use]
110 pub fn version(&self) -> Option<uuid::Version> {
111 self.0.get_version()
112 }
113
114 #[must_use]
116 pub const fn is_nil(&self) -> bool {
117 self.0.is_nil()
118 }
119}
120
121impl<Tag> Clone for Id<Tag> {
124 fn clone(&self) -> Self {
125 *self
126 }
127}
128impl<Tag> Copy for Id<Tag> {}
129impl<Tag> PartialEq for Id<Tag> {
130 fn eq(&self, other: &Self) -> bool {
131 self.0 == other.0
132 }
133}
134impl<Tag> Eq for Id<Tag> {}
135impl<Tag> PartialOrd for Id<Tag> {
136 fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
137 Some(self.cmp(other))
138 }
139}
140impl<Tag> Ord for Id<Tag> {
141 fn cmp(&self, other: &Self) -> core::cmp::Ordering {
142 self.0.cmp(&other.0)
143 }
144}
145impl<Tag> Hash for Id<Tag> {
146 fn hash<H: Hasher>(&self, state: &mut H) {
147 self.0.hash(state);
148 }
149}
150
151impl<Tag> fmt::Debug for Id<Tag> {
152 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
153 let tag = core::any::type_name::<Tag>()
154 .rsplit("::")
155 .next()
156 .unwrap_or("?");
157 write!(f, "Id<{tag}>({})", self.0)
158 }
159}
160
161impl<Tag> fmt::Display for Id<Tag> {
162 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
163 fmt::Display::fmt(self.0.as_hyphenated(), f)
164 }
165}
166
167impl<Tag> FromStr for Id<Tag> {
168 type Err = IdError;
169 fn from_str(s: &str) -> Result<Self, IdError> {
170 Self::parse(s)
171 }
172}
173
174impl<Tag> TryFrom<&str> for Id<Tag> {
175 type Error = IdError;
176 fn try_from(value: &str) -> Result<Self, IdError> {
177 Self::parse(value)
178 }
179}
180
181impl<Tag> TryFrom<String> for Id<Tag> {
182 type Error = IdError;
183 fn try_from(value: String) -> Result<Self, IdError> {
184 Self::parse(&value)
185 }
186}
187
188impl<Tag> From<Uuid> for Id<Tag> {
189 fn from(uuid: Uuid) -> Self {
190 Self::from_uuid(uuid)
191 }
192}
193
194impl<Tag> From<Id<Tag>> for Uuid {
195 fn from(id: Id<Tag>) -> Self {
196 id.0
197 }
198}
199
200impl<Tag> From<Id<Tag>> for String {
201 fn from(id: Id<Tag>) -> Self {
202 id.to_string()
203 }
204}
205
206#[cfg(feature = "serde")]
208impl<Tag> serde::Serialize for Id<Tag> {
209 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
210 self.0.serialize(serializer)
211 }
212}
213
214#[cfg(feature = "serde")]
215impl<'de, Tag> serde::Deserialize<'de> for Id<Tag> {
216 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
217 Uuid::deserialize(deserializer).map(Self::from_uuid)
218 }
219}
220
221#[cfg(any(feature = "sqlx-0_8", feature = "sqlx-0_9"))]
222crate::sqlx_support::sqlx_via!(
223 Id<Tag> [Tag],
224 Uuid,
225 |u: Uuid| Ok::<_, core::convert::Infallible>(Id::from_uuid(u)),
226 |this: &Id<Tag>| &this.0
227);
228
229mod sealed {
234 pub trait Sealed {}
235 impl Sealed for u64 {}
236 impl Sealed for i64 {}
237}
238
239pub trait NumIdRepr:
245 sealed::Sealed + Copy + Ord + Hash + fmt::Display + FromStr + Send + Sync + 'static
246{
247 const DEBUG_SUFFIX: &'static str;
249
250 fn to_bigint(self) -> Result<i64, IdError>;
252
253 fn from_bigint(value: i64) -> Result<Self, IdError>;
255
256 fn parse_repr(value: &str) -> Result<Self, IdError>;
258
259 #[cfg(feature = "serde")]
261 fn serialize_repr<S: serde::Serializer>(self, serializer: S) -> Result<S::Ok, S::Error>;
262
263 #[cfg(feature = "serde")]
265 fn deserialize_repr<'de, D: serde::Deserializer<'de>>(
266 deserializer: D,
267 ) -> Result<Self, D::Error>;
268}
269
270impl NumIdRepr for u64 {
271 const DEBUG_SUFFIX: &'static str = "";
272
273 fn to_bigint(self) -> Result<i64, IdError> {
274 i64::try_from(self).map_err(|_| IdError::NumberTooLarge { value: self })
275 }
276
277 fn from_bigint(value: i64) -> Result<Self, IdError> {
278 Self::try_from(value).map_err(|_| IdError::NumberNegative { value })
279 }
280
281 fn parse_repr(value: &str) -> Result<Self, IdError> {
282 if value.is_empty() || !value.bytes().all(|b| b.is_ascii_digit()) {
283 return Err(IdError::Number);
284 }
285 value.parse().map_err(|_| IdError::Number)
286 }
287
288 #[cfg(feature = "serde")]
289 fn serialize_repr<S: serde::Serializer>(self, serializer: S) -> Result<S::Ok, S::Error> {
290 serializer.serialize_u64(self)
291 }
292
293 #[cfg(feature = "serde")]
294 fn deserialize_repr<'de, D: serde::Deserializer<'de>>(
295 deserializer: D,
296 ) -> Result<Self, D::Error> {
297 serde::Deserialize::deserialize(deserializer)
298 }
299}
300
301impl NumIdRepr for i64 {
302 const DEBUG_SUFFIX: &'static str = ", i64";
303
304 fn to_bigint(self) -> Result<Self, IdError> {
305 Ok(self)
306 }
307
308 fn from_bigint(value: Self) -> Result<Self, IdError> {
309 Ok(value)
310 }
311
312 fn parse_repr(value: &str) -> Result<Self, IdError> {
313 let digits = value.strip_prefix('-').unwrap_or(value);
314 if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
315 return Err(IdError::Number);
316 }
317 value.parse().map_err(|_| IdError::Number)
318 }
319
320 #[cfg(feature = "serde")]
321 fn serialize_repr<S: serde::Serializer>(self, serializer: S) -> Result<S::Ok, S::Error> {
322 serializer.serialize_i64(self)
323 }
324
325 #[cfg(feature = "serde")]
326 fn deserialize_repr<'de, D: serde::Deserializer<'de>>(
327 deserializer: D,
328 ) -> Result<Self, D::Error> {
329 serde::Deserialize::deserialize(deserializer)
330 }
331}
332
333pub struct NumId<Tag, R: NumIdRepr = u64>(R, PhantomData<fn() -> Tag>);
350
351impl<Tag, R: NumIdRepr> NumId<Tag, R> {
352 #[inline]
354 #[must_use]
355 pub const fn new(value: R) -> Self {
356 Self(value, PhantomData)
357 }
358
359 pub fn parse(value: &str) -> Result<Self, IdError> {
361 R::parse_repr(value.trim()).map(Self::new)
362 }
363
364 #[inline]
366 #[must_use]
367 pub const fn get(&self) -> R {
368 self.0
369 }
370
371 pub fn to_bigint(&self) -> Result<i64, IdError> {
375 self.0.to_bigint()
376 }
377
378 #[must_use]
380 pub fn is_db_safe(&self) -> bool {
381 self.0.to_bigint().is_ok()
382 }
383}
384
385impl<Tag> NumId<Tag, u64> {
386 pub const MAX_DB_SAFE: u64 = i64::MAX as u64;
388
389 pub const fn try_new_db_safe(value: u64) -> Result<Self, IdError> {
393 if value > Self::MAX_DB_SAFE {
394 return Err(IdError::NumberTooLarge { value });
395 }
396 Ok(Self::new(value))
397 }
398
399 pub fn parse_db_safe(value: &str) -> Result<Self, IdError> {
401 Self::try_new_db_safe(Self::parse(value)?.0)
402 }
403}
404
405impl<Tag, R: NumIdRepr> Clone for NumId<Tag, R> {
406 fn clone(&self) -> Self {
407 *self
408 }
409}
410impl<Tag, R: NumIdRepr> Copy for NumId<Tag, R> {}
411impl<Tag, R: NumIdRepr> PartialEq for NumId<Tag, R> {
412 fn eq(&self, other: &Self) -> bool {
413 self.0 == other.0
414 }
415}
416impl<Tag, R: NumIdRepr> Eq for NumId<Tag, R> {}
417impl<Tag, R: NumIdRepr> PartialOrd for NumId<Tag, R> {
418 fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
419 Some(self.cmp(other))
420 }
421}
422impl<Tag, R: NumIdRepr> Ord for NumId<Tag, R> {
423 fn cmp(&self, other: &Self) -> core::cmp::Ordering {
424 self.0.cmp(&other.0)
425 }
426}
427impl<Tag, R: NumIdRepr> Hash for NumId<Tag, R> {
428 fn hash<H: Hasher>(&self, state: &mut H) {
429 self.0.hash(state);
430 }
431}
432impl<Tag, R: NumIdRepr> fmt::Debug for NumId<Tag, R> {
433 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
434 let tag = core::any::type_name::<Tag>()
435 .rsplit("::")
436 .next()
437 .unwrap_or("?");
438 write!(f, "NumId<{tag}{}>({})", R::DEBUG_SUFFIX, self.0)
439 }
440}
441impl<Tag, R: NumIdRepr> fmt::Display for NumId<Tag, R> {
442 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
443 fmt::Display::fmt(&self.0, f)
444 }
445}
446impl<Tag, R: NumIdRepr> FromStr for NumId<Tag, R> {
447 type Err = IdError;
448 fn from_str(s: &str) -> Result<Self, IdError> {
449 Self::parse(s)
450 }
451}
452
453impl<Tag, R: NumIdRepr> TryFrom<&str> for NumId<Tag, R> {
454 type Error = IdError;
455 fn try_from(value: &str) -> Result<Self, IdError> {
456 Self::parse(value)
457 }
458}
459
460impl<Tag, R: NumIdRepr> TryFrom<String> for NumId<Tag, R> {
464 type Error = IdError;
465 fn try_from(value: String) -> Result<Self, IdError> {
466 Self::parse(&value)
467 }
468}
469
470impl<Tag, R: NumIdRepr> From<NumId<Tag, R>> for String {
471 fn from(id: NumId<Tag, R>) -> Self {
472 id.to_string()
473 }
474}
475
476impl<Tag> From<u64> for NumId<Tag, u64> {
480 fn from(value: u64) -> Self {
481 Self::new(value)
482 }
483}
484impl<Tag> From<NumId<Tag, u64>> for u64 {
485 fn from(id: NumId<Tag, u64>) -> Self {
486 id.0
487 }
488}
489impl<Tag> From<i64> for NumId<Tag, i64> {
490 fn from(value: i64) -> Self {
491 Self::new(value)
492 }
493}
494impl<Tag> From<NumId<Tag, i64>> for i64 {
495 fn from(id: NumId<Tag, i64>) -> Self {
496 id.0
497 }
498}
499
500impl<Tag> TryFrom<NumId<Tag, u64>> for NumId<Tag, i64> {
502 type Error = IdError;
503 fn try_from(id: NumId<Tag, u64>) -> Result<Self, IdError> {
504 id.0.to_bigint().map(Self::new)
505 }
506}
507
508impl<Tag> TryFrom<NumId<Tag, i64>> for NumId<Tag, u64> {
510 type Error = IdError;
511 fn try_from(id: NumId<Tag, i64>) -> Result<Self, IdError> {
512 u64::from_bigint(id.0).map(Self::new)
513 }
514}
515
516#[cfg(feature = "serde")]
517impl<Tag, R: NumIdRepr> serde::Serialize for NumId<Tag, R> {
518 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
519 self.0.serialize_repr(serializer)
520 }
521}
522
523#[cfg(feature = "serde")]
524impl<'de, Tag, R: NumIdRepr> serde::Deserialize<'de> for NumId<Tag, R> {
525 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
526 R::deserialize_repr(deserializer).map(Self::new)
527 }
528}
529
530#[cfg(any(feature = "sqlx-0_8", feature = "sqlx-0_9"))]
540mod sqlx_impls {
541 use super::{NumId, NumIdRepr};
542
543 macro_rules! num_id_type_decode {
545 ($sqlx:ident) => {
546 impl<DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Type<DB> for NumId<Tag, R>
547 where
548 i64: ::$sqlx::Type<DB>,
549 {
550 fn type_info() -> DB::TypeInfo {
551 <i64 as ::$sqlx::Type<DB>>::type_info()
552 }
553 fn compatible(ty: &DB::TypeInfo) -> bool {
554 <i64 as ::$sqlx::Type<DB>>::compatible(ty)
555 }
556 }
557
558 impl<'r, DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Decode<'r, DB>
559 for NumId<Tag, R>
560 where
561 i64: ::$sqlx::Decode<'r, DB>,
562 {
563 fn decode(value: DB::ValueRef<'r>) -> Result<Self, ::$sqlx::error::BoxDynError> {
564 let raw = <i64 as ::$sqlx::Decode<'r, DB>>::decode(value)?;
565 Ok(Self::new(R::from_bigint(raw)?))
566 }
567 }
568 };
569 }
570
571 #[cfg(feature = "sqlx-0_8")]
573 macro_rules! num_id_encode_0_8 {
574 ($sqlx:ident) => {
575 impl<'q, DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Encode<'q, DB>
576 for NumId<Tag, R>
577 where
578 i64: ::$sqlx::Encode<'q, DB>,
579 {
580 fn encode_by_ref(
581 &self,
582 buf: &mut DB::ArgumentBuffer<'q>,
583 ) -> Result<::$sqlx::encode::IsNull, ::$sqlx::error::BoxDynError> {
584 let value = self.0.to_bigint()?;
585 <i64 as ::$sqlx::Encode<'q, DB>>::encode_by_ref(&value, buf)
586 }
587 }
588 };
589 }
590
591 #[cfg(feature = "sqlx-0_9")]
593 macro_rules! num_id_encode_0_9 {
594 ($sqlx:ident) => {
595 impl<'q, DB: ::$sqlx::Database, Tag, R: NumIdRepr> ::$sqlx::Encode<'q, DB>
596 for NumId<Tag, R>
597 where
598 i64: ::$sqlx::Encode<'q, DB>,
599 {
600 fn encode_by_ref(
601 &self,
602 buf: &mut DB::ArgumentBuffer,
603 ) -> Result<::$sqlx::encode::IsNull, ::$sqlx::error::BoxDynError> {
604 let value = self.0.to_bigint()?;
605 <i64 as ::$sqlx::Encode<'q, DB>>::encode_by_ref(&value, buf)
606 }
607 }
608 };
609 }
610
611 #[cfg(any(feature = "sqlx-0_8-postgres", feature = "sqlx-0_9-postgres"))]
613 macro_rules! num_id_pg_array {
614 ($sqlx:ident) => {
615 impl<Tag, R: NumIdRepr> ::$sqlx::postgres::PgHasArrayType for NumId<Tag, R> {
616 fn array_type_info() -> ::$sqlx::postgres::PgTypeInfo {
617 <i64 as ::$sqlx::postgres::PgHasArrayType>::array_type_info()
618 }
619
620 fn array_compatible(ty: &::$sqlx::postgres::PgTypeInfo) -> bool {
621 <i64 as ::$sqlx::postgres::PgHasArrayType>::array_compatible(ty)
622 }
623 }
624 };
625 }
626
627 #[cfg(feature = "sqlx-0_8")]
628 num_id_type_decode!(sqlx_0_8);
629 #[cfg(feature = "sqlx-0_8")]
630 num_id_encode_0_8!(sqlx_0_8);
631 #[cfg(feature = "sqlx-0_8-postgres")]
632 num_id_pg_array!(sqlx_0_8);
633
634 #[cfg(feature = "sqlx-0_9")]
635 num_id_type_decode!(sqlx_0_9);
636 #[cfg(feature = "sqlx-0_9")]
637 num_id_encode_0_9!(sqlx_0_9);
638 #[cfg(feature = "sqlx-0_9-postgres")]
639 num_id_pg_array!(sqlx_0_9);
640}
641
642#[cfg(test)]
643mod tests {
644 use super::*;
645
646 enum Order {}
647 type OrderId = Id<Order>;
648 type LegacyOrderId = NumId<Order>;
649 type SignedOrderId = NumId<Order, i64>;
650
651 #[test]
652 fn ids_are_typed_and_roundtrip() {
653 let a = OrderId::now_v7();
654 let b = OrderId::now_v7();
655 assert!(a < b);
656 assert_eq!(OrderId::parse(&a.to_string()).unwrap(), a);
657 assert_eq!(format!("{a:?}"), format!("Id<Order>({})", a.as_uuid()));
658 assert_eq!(a.version(), Some(uuid::Version::SortRand));
659 assert!(OrderId::parse("not-a-uuid").is_err());
660 assert!(OrderId::parse("42").is_err()); let n = LegacyOrderId::parse(" 42 ").unwrap();
663 assert_eq!(n.get(), 42);
664 assert_eq!(format!("{n:?}"), "NumId<Order>(42)");
665 assert!(LegacyOrderId::parse("-1").is_err());
666 assert!(LegacyOrderId::parse("+1").is_err());
667 assert!(LegacyOrderId::parse("").is_err());
668 }
669
670 #[test]
671 fn signed_repr_accepts_negative_legacy_ids() {
672 let n = SignedOrderId::parse(" -1 ").unwrap();
673 assert_eq!(n.get(), -1);
674 assert_eq!(n.to_string(), "-1");
675 assert_eq!(format!("{n:?}"), "NumId<Order, i64>(-1)");
676 assert_eq!(SignedOrderId::parse(&n.to_string()).unwrap(), n); assert!(SignedOrderId::parse("+1").is_err());
678 assert!(SignedOrderId::parse("-").is_err());
679 assert!(SignedOrderId::parse("").is_err());
680
681 assert!(SignedOrderId::new(i64::MIN).is_db_safe());
683 assert_eq!(SignedOrderId::new(i64::MAX).to_bigint(), Ok(i64::MAX));
684 }
685
686 #[test]
687 fn db_safe_bounds_move_the_error_to_construction() {
688 const MAX: u64 = LegacyOrderId::MAX_DB_SAFE;
689 assert_eq!(MAX, i64::MAX as u64);
690
691 let too_big = LegacyOrderId::new(MAX + 1);
693 assert!(!too_big.is_db_safe());
694 assert_eq!(
695 too_big.to_bigint(),
696 Err(IdError::NumberTooLarge { value: MAX + 1 })
697 );
698
699 assert_eq!(LegacyOrderId::try_new_db_safe(MAX).unwrap().get(), MAX);
701 assert_eq!(
702 LegacyOrderId::try_new_db_safe(MAX + 1),
703 Err(IdError::NumberTooLarge { value: MAX + 1 })
704 );
705 assert!(LegacyOrderId::parse_db_safe("9223372036854775808").is_err());
706 assert!(LegacyOrderId::parse_db_safe("9223372036854775807").is_ok());
707 }
708
709 #[test]
710 fn repr_conversions_are_checked_both_ways() {
711 assert_eq!(
712 SignedOrderId::try_from(LegacyOrderId::new(42))
713 .unwrap()
714 .get(),
715 42
716 );
717 assert_eq!(
718 SignedOrderId::try_from(LegacyOrderId::new(u64::MAX)),
719 Err(IdError::NumberTooLarge { value: u64::MAX })
720 );
721 assert_eq!(
722 LegacyOrderId::try_from(SignedOrderId::new(42))
723 .unwrap()
724 .get(),
725 42
726 );
727 assert_eq!(
728 LegacyOrderId::try_from(SignedOrderId::new(-1)),
729 Err(IdError::NumberNegative { value: -1 })
730 );
731 }
732
733 #[test]
736 fn numid_conversions_match_the_rest_of_the_crate() {
737 let expected = LegacyOrderId::parse("42").unwrap();
738 assert_eq!(LegacyOrderId::try_from("42").unwrap(), expected);
739 assert_eq!(LegacyOrderId::try_from(" 42 ").unwrap(), expected);
740 assert_eq!(
741 LegacyOrderId::try_from(String::from("42")).unwrap(),
742 expected
743 );
744 assert_eq!(String::from(expected), "42");
745 assert_eq!(String::from(expected), expected.to_string());
746
747 let signed = SignedOrderId::try_from("-1").unwrap();
749 assert_eq!(signed.get(), -1);
750 assert_eq!(String::from(signed), "-1");
751
752 assert_eq!(LegacyOrderId::try_from("-1"), Err(IdError::Number));
754 assert_eq!(
755 LegacyOrderId::try_from(String::from("nope")),
756 Err(IdError::Number)
757 );
758
759 fn ingest<T: TryFrom<String>>(raw: &str) -> Result<T, T::Error> {
761 T::try_from(raw.to_owned())
762 }
763 assert!(ingest::<LegacyOrderId>("42").is_ok());
764 assert!(ingest::<OrderId>(&OrderId::now_v7().to_string()).is_ok());
765 assert!(ingest::<SignedOrderId>("-1").is_ok());
766 }
767
768 #[test]
769 fn id_is_send_sync_regardless_of_tag() {
770 fn assert_send_sync<T: Send + Sync>() {}
771 #[allow(dead_code)]
772 struct NotSync(core::cell::Cell<u8>);
773 assert_send_sync::<Id<NotSync>>();
774 assert_send_sync::<NumId<NotSync>>();
775 assert_send_sync::<NumId<NotSync, i64>>();
776 }
777}