globuid 0.1.0

A globally unique ID generator with pluggable algorithms and transport layer
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

// Copyright 2026 GlobUid Contributors
// SPDX-License-Identifier: Apache-2.0

//! NanoID generator.
//!
//! NanoIDs are URL-friendly unique string identifiers with configurable:
//! - Length (default: 21 characters)
//! - Alphabet (default: A-Za-z0-9_-)
//!
//! Example: `V1StGXR8_Z5jdHi6B-myT`

use std::sync::Arc;

use thiserror::Error;

use super::{Id, IdGenerator, IdType};
use std::future::Future;
use std::pin::Pin;

/// Errors that can occur during NanoID generation.
#[derive(Debug, Error)]
pub enum NanoIdError {
    /// Random generation failed.
    #[error("Failed to generate random bytes: {0}")]
    RandomError(String),
}

/// Default alphabet for NanoID.
pub const DEFAULT_ALPHABET: &[u8] =
    b"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_";

/// Configuration for the NanoID generator.
#[derive(Debug, Clone)]
pub struct NanoIdConfig {
    /// Length of the generated ID. Default: 21
    pub length: usize,
    /// Custom alphabet. Default: A-Za-z0-9_-
    pub alphabet: Arc<[u8]>,
}

impl Default for NanoIdConfig {
    fn default() -> Self {
        Self {
            length: 21,
            alphabet: Arc::from(DEFAULT_ALPHABET),
        }
    }
}

impl NanoIdConfig {
    /// Create a new NanoID configuration.
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the ID length.
    pub fn length(mut self, length: usize) -> Self {
        self.length = length;
        self
    }

    /// Set a custom alphabet.
    pub fn alphabet(mut self, alphabet: &[u8]) -> Self {
        self.alphabet = Arc::from(alphabet.to_vec().into_boxed_slice());
        self
    }
}

/// NanoID generator.
#[derive(Debug, Clone)]
pub struct NanoId {
    config: NanoIdConfig,
    mask: u8,
    step: usize,
}

impl NanoId {
    /// Create a new NanoID generator.
    pub fn new(config: NanoIdConfig) -> Self {
        let alphabet_len = config.alphabet.len();

        // Calculate mask for efficient random sampling
        // Find the smallest (2^n - 1) >= alphabet_len - 1
        let mask = {
            let mut m = 1u8;
            while m < alphabet_len as u8 - 1 {
                m = m * 2 + 1;
            }
            m
        };

        // Calculate step (how many bytes we need per generation)
        let step = (config.length * 8)
            .div_ceil(mask.count_ones() as usize)
            .max(1);

        Self { config, mask, step }
    }

    /// Create a NanoID generator with default configuration.
    pub fn with_default() -> Self {
        Self::new(NanoIdConfig::default())
    }

    /// Generate a new NanoID string.
    pub fn generate_string(&self) -> Result<String, NanoIdError> {
        let mut result = String::with_capacity(self.config.length);
        let alphabet = &self.config.alphabet;
        let mut bytes = vec![0u8; self.step * 2]; // Extra buffer

        while result.len() < self.config.length {
            getrandom::fill(&mut bytes).map_err(|e| NanoIdError::RandomError(e.to_string()))?;

            for &byte in &bytes {
                let index = byte & self.mask;
                if (index as usize) < alphabet.len() {
                    result.push(alphabet[index as usize] as char);
                    if result.len() >= self.config.length {
                        break;
                    }
                }
            }
        }

        Ok(result)
    }
}

impl IdGenerator for NanoId {
    type Error = NanoIdError;

    fn generate(&self) -> Pin<Box<dyn Future<Output = Result<Id, Self::Error>> + Send + '_>> {
        Box::pin(async move {
            let s = self.generate_string()?;
            Ok(Id::String(s))
        })
    }

    fn id_type(&self) -> IdType {
        IdType::ShortString
    }
}