ferroid 2.0.0

High-performance ULID and Snowflake-style IDs. Unique, monotonic, and lexicographically sortable IDs optimized for low-latency services and async workloads.
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
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

use serde::{Deserialize, Deserializer, Serialize, Serializer};

pub mod ulid_as_int {
    use super::{Deserialize, Deserializer, Serialize, Serializer};
    use crate::{id::UlidId, serde::Error};

    /// Serialize a ULID as its native integer representation.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying serializer fails.
    pub fn serialize<ID, S>(id: &ID, s: S) -> Result<S::Ok, S::Error>
    where
        ID: UlidId,
        ID::Ty: Serialize,
        S: Serializer,
    {
        id.to_raw().serialize(s)
    }

    /// Deserialize a ULID from its native integer representation.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The underlying deserializer fails
    /// - The deserialized value is not a valid ULID (e.g., exceeds the valid
    ///   range)
    pub fn deserialize<'de, ID, D>(d: D) -> Result<ID, D::Error>
    where
        ID: UlidId,
        ID::Ty: Deserialize<'de>,
        D: Deserializer<'de>,
    {
        let n = <ID::Ty>::deserialize(d)?;
        let id = ID::from_raw(n);
        if !id.is_valid() {
            return Err(serde::de::Error::custom(Error::DecodeOverflow { id }));
        }
        Ok(id)
    }
}

#[cfg(feature = "base32")]
pub mod ulid_as_base32 {
    use super::{Deserializer, Serializer};
    use crate::{base32::Base32UlidExt, id::BeBytes, serde::Error};

    /// Serialize a ULID as a Crockford base32 encoded string.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying serializer fails.
    pub fn serialize<ID, S>(id: &ID, s: S) -> Result<S::Ok, S::Error>
    where
        ID: Base32UlidExt,
        ID::Ty: BeBytes,
        S: Serializer,
    {
        s.serialize_str(id.encode().as_str())
    }

    /// Deserialize a ULID from a Crockford base32 encoded string.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The underlying deserializer fails
    /// - The string is not valid Crockford base32 (invalid length or ascii)
    /// - The decoded value is not a valid ULID (e.g., exceeds the valid range)
    pub fn deserialize<'de, ID, D>(d: D) -> Result<ID, D::Error>
    where
        ID: Base32UlidExt,
        ID::Ty: BeBytes,
        D: Deserializer<'de>,
    {
        struct Base32Visitor<ID>(core::marker::PhantomData<ID>);

        impl<ID> serde::de::Visitor<'_> for Base32Visitor<ID>
        where
            ID: Base32UlidExt,
            ID::Ty: BeBytes,
        {
            type Value = ID;

            fn expecting(&self, formatter: &mut core::fmt::Formatter) -> core::fmt::Result {
                formatter.write_str("a Crockford base32 encoded string")
            }

            #[inline]
            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
            where
                E: serde::de::Error,
            {
                ID::decode(v).map_err(|e| serde::de::Error::custom(Error::Base32Error(e)))
            }
        }

        d.deserialize_str(Base32Visitor(core::marker::PhantomData))
    }
}

#[cfg(all(test, feature = "ulid"))]
mod tests {
    use core::u64;

    use serde_json::json;

    use super::*;
    use crate::id::ULID;

    #[test]
    fn native_ulid_roundtrip() {
        #[derive(PartialEq, Eq, Debug, Serialize, Deserialize)]
        struct Row {
            #[serde(with = "ulid_as_int")]
            event_id: ULID,
        }
        let row = Row {
            event_id: ULID::from_raw(42),
        };

        let json = serde_json::to_string(&row).expect("serialize");
        assert_eq!(json, json!(r#"{"event_id":42}"#));
        let back: Row = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(back, row);
    }

    #[test]
    #[cfg(feature = "base32")]
    fn base32_ulid_roundtrip() {
        #[derive(PartialEq, Eq, Debug, Serialize, Deserialize)]
        struct Row {
            #[serde(with = "ulid_as_base32")]
            event_id: ULID,
        }
        let row = Row {
            event_id: ULID::from_raw(42),
        };

        let json = serde_json::to_string(&row).expect("serialize");
        assert_eq!(json, json!(r#"{"event_id":"0000000000000000000000001A"}"#));
        let back: Row = serde_json::from_str(&json).expect("deserialize");
        assert_eq!(back, row);
    }
}