obzenflow_idkit/

lib.rs

// SPDX-License-Identifier: MIT OR Apache-2.0
// SPDX-FileCopyrightText: 2025-2026 ObzenFlow Contributors
// https://obzenflow.dev

//! Phantom-typed ULID identifiers.
//!
//! `Id<K>` is a zero-cost wrapper around [`Ulid`] with a phantom kind `K`, preventing
//! accidental mixing of IDs across domains.
//!
//! By default this crate is type-only (no RNG dependencies). Enable the `gen` feature in
//! application crates to generate IDs, and configure the RNG backend per target (for
//! browser wasm, enable `getrandom`'s `js` feature in the app crate).
//!
//! Define marker types (`struct User; type UserId = Id<User>;`) in your domain crates; this
//! crate stays generic.
//!
//! ## Example
//! ```rust
//! use obzenflow_idkit::{Id, Ulid};
//!
//! struct User;
//! struct Order;
//!
//! type UserId = Id<User>;
//! type OrderId = Id<Order>;
//!
//! let _user_id = UserId::from_ulid(Ulid::from_string("01ARZ3NDEKTSV4RRFFQ69G5FAV").unwrap());
//! let _order_id = OrderId::from_ulid(Ulid::from_string("01ARZ3NDEKTSV4RRFFQ69G5FAW").unwrap());
//!
//! // These are different types (won't compile):
//! // let mixed: UserId = _order_id;
//!
//! // With `gen` enabled in an app crate:
//! // let generated = UserId::new();
//! ```

use core::fmt::{self, Debug};
use core::hash::Hash;
use core::marker::PhantomData;
use core::str::FromStr;

pub use ulid::Ulid;

/// A phantom-typed ID wrapper that provides type safety across domains.
///
/// The type parameter `K` is a phantom type that exists only at compile time
/// to prevent mixing IDs from different domains.
#[derive(Clone, Copy)]
pub struct Id<K> {
    inner: Ulid,
    _phantom: PhantomData<K>,
}

// Manual implementations to avoid requiring K to implement these traits

impl<K> Debug for Id<K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Id").field("inner", &self.inner).finish()
    }
}

impl<K> PartialEq for Id<K> {
    fn eq(&self, other: &Self) -> bool {
        self.inner == other.inner
    }
}

impl<K> Eq for Id<K> {}

impl<K> Hash for Id<K> {
    fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
        self.inner.hash(state)
    }
}

impl<K> PartialOrd for Id<K> {
    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl<K> Ord for Id<K> {
    fn cmp(&self, other: &Self) -> core::cmp::Ordering {
        self.inner.cmp(&other.inner)
    }
}

impl<K> Id<K> {
    /// Generate a new ID. Works on both native and WASM platforms.
    ///
    /// Requires the `gen` feature. For browser wasm, enable `getrandom`'s `js` feature in
    /// the application crate.
    #[cfg(feature = "gen")]
    #[inline]
    pub fn new() -> Self {
        Self::from_ulid(new_ulid())
    }

    /// Create from an existing ULID.
    #[inline]
    pub fn from_ulid(ulid: Ulid) -> Self {
        Self {
            inner: ulid,
            _phantom: PhantomData,
        }
    }

    /// Extract the underlying ULID.
    #[inline]
    pub fn as_ulid(&self) -> Ulid {
        self.inner
    }

    /// Extract the underlying ULID, consuming `self`.
    #[inline]
    pub fn ulid(self) -> Ulid {
        self.inner
    }

    /// Get the raw bytes representation.
    #[inline]
    pub fn to_bytes(&self) -> [u8; 16] {
        self.inner.to_bytes()
    }

    /// Create from raw bytes.
    #[inline]
    pub fn from_bytes(bytes: [u8; 16]) -> Self {
        Self {
            inner: Ulid::from_bytes(bytes),
            _phantom: PhantomData,
        }
    }

    /// Get the timestamp in milliseconds.
    #[inline]
    pub fn timestamp_ms(&self) -> u64 {
        self.inner.timestamp_ms()
    }
}

impl<K> Default for Id<K> {
    #[cfg(feature = "gen")]
    #[inline]
    fn default() -> Self {
        Self::new()
    }

    #[cfg(not(feature = "gen"))]
    #[inline]
    fn default() -> Self {
        panic!("Id::default() requires the 'gen' feature to be enabled")
    }
}

impl<K> fmt::Display for Id<K> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(&self.inner, f)
    }
}

impl<K> FromStr for Id<K> {
    type Err = ulid::DecodeError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Ok(Self {
            inner: Ulid::from_str(s)?,
            _phantom: PhantomData,
        })
    }
}

#[cfg(feature = "serde")]
impl<K> serde::Serialize for Id<K> {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        let s = self.to_string();
        serializer.serialize_str(&s)
    }
}

#[cfg(feature = "serde")]
impl<'de, K> serde::Deserialize<'de> for Id<K> {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        use std::borrow::Cow;

        let s: Cow<'de, str> = Cow::deserialize(deserializer)?;
        let ulid = Ulid::from_str(&s).map_err(serde::de::Error::custom)?;
        Ok(Self::from_ulid(ulid))
    }
}

// Optional convenience functions for raw ULID generation (no phantom typing).

/// Generate a raw ULID.
///
/// Requires the `gen` feature.
#[cfg(feature = "gen")]
#[inline]
pub fn new_ulid() -> Ulid {
    fn now() -> std::time::SystemTime {
        #[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
        {
            use web_time::web::SystemTimeExt;
            return web_time::SystemTime::now().to_std();
        }
        #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
        return std::time::SystemTime::now();
    }

    fn random_u128_80() -> u128 {
        let mut bytes = [0u8; 10];
        getrandom::getrandom(&mut bytes).expect("getrandom failed");

        let mut buf = [0u8; 16];
        buf[6..].copy_from_slice(&bytes);
        u128::from_be_bytes(buf)
    }

    let timestamp_ms = now()
        .duration_since(std::time::SystemTime::UNIX_EPOCH)
        .unwrap_or(std::time::Duration::ZERO)
        .as_millis() as u64;

    Ulid::from_parts(timestamp_ms, random_u128_80())
}

/// Generate a ULID as a string.
///
/// Requires the `gen` feature.
#[cfg(feature = "gen")]
#[inline]
pub fn new_ulid_string() -> String {
    new_ulid().to_string()
}

#[cfg(test)]
mod tests {
    use super::*;

    // Test domain types - just empty marker types
    struct User;

    type UserId = Id<User>;

    #[cfg(feature = "gen")]
    struct Order;
    #[cfg(feature = "gen")]
    type OrderId = Id<Order>;

    #[cfg(feature = "gen")]
    #[test]
    fn test_id_generation() {
        let id1 = UserId::new();
        let id2 = UserId::new();
        assert_ne!(id1, id2);
    }

    #[cfg(feature = "gen")]
    #[test]
    fn test_type_safety() {
        let user_id = UserId::new();
        let order_id = OrderId::new();

        // This test verifies that UserId and OrderId are different types
        // The following would not compile:
        // let _: UserId = order_id;

        // But we can extract and compare the inner ULIDs if needed
        assert_ne!(user_id.as_ulid(), order_id.as_ulid());
    }

    #[test]
    fn test_string_roundtrip() {
        let ulid = Ulid::from_string("01ARZ3NDEKTSV4RRFFQ69G5FAV").unwrap();
        let id = UserId::from_ulid(ulid);
        let s = id.to_string();
        let id2 = UserId::from_str(&s).unwrap();
        assert_eq!(id, id2);
    }

    #[test]
    fn test_bytes_roundtrip() {
        let ulid = Ulid::from_string("01ARZ3NDEKTSV4RRFFQ69G5FAV").unwrap();
        let id = UserId::from_ulid(ulid);
        let bytes = id.to_bytes();
        let id2 = UserId::from_bytes(bytes);
        assert_eq!(id, id2);
    }

    #[cfg(feature = "serde")]
    #[test]
    fn test_serde_roundtrip() {
        let ulid = Ulid::from_string("01ARZ3NDEKTSV4RRFFQ69G5FAV").unwrap();
        let id = UserId::from_ulid(ulid);
        let json = serde_json::to_string(&id).unwrap();
        let id2: UserId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, id2);
    }
}