Add String Representation

Author: lemon-mint

README.md

@@ -109,6 +109,36 @@ console.log(uid);
 
 Randflake ID is designed for high-performance scenarios, with minimal overhead in ID generation.
 
+## String Representation
+
+Randflake ID is encoded as a base32hex string.
+
+```python
+base32hexchars = "0123456789abcdefghijklmnopqrstuv"
+
+original = 4594531474933654033
+encoded = "3vgoe12ccb8gh"
+
+def decode(s):
+    return int(s, 32)
+
+def encode(n):
+    if n < 0:
+        n += 1 << 64
+    
+    if n == 0:
+        return "0"
+    
+    result = ""
+    while n > 0:
+        result = base32hexchars[n&0x1f] + result
+        n = n // 32
+    return result
+
+assert original == decode(encode(original))
+assert encode(original) == "3vgoe12ccb8gh"
+```
+
 ## Contributing
 
 Contributions are welcome! Please follow these steps:

randflake.go

@@ -35,6 +35,7 @@ var (
 	ErrInvalidNode          = errors.New("randflake: invalid node id, node id must be between 0 and 131071")
 	ErrResourceExhausted    = errors.New("randflake: resource exhausted (generator can't handle current throughput, try using multiple randflake instances)")
 	ErrConsistencyViolation = errors.New("randflake: timestamp consistency violation, the current time is less than the last time")
+	ErrInvalidID            = errors.New("randflake: invalid id")
 )
 
 type Generator struct {
@@ -176,6 +177,15 @@ func (g *Generator) Generate() (int64, error) {
 	return int64(binary.LittleEndian.Uint64(b[:])), nil
 }
 
+// GenerateString generates a unique, encrypted ID and returns it as a string.
+func (g *Generator) GenerateString() (string, error) {
+	id, err := g.Generate()
+	if err != nil {
+		return "", err
+	}
+	return base32hexencode(uint64(id)), nil
+}
+
 // Inspect returns the timestamp, node ID, and sequence number of the given ID.
 func (g *Generator) Inspect(id int64) (timestamp int64, nodeID int64, sequence int64, err error) {
 	var b [8]byte
@@ -190,3 +200,63 @@ func (g *Generator) Inspect(id int64) (timestamp int64, nodeID int64, sequence i
 	sequence = id & RANDFLAKE_MAX_SEQUENCE
 	return
 }
+
+// InspectString returns the timestamp, node ID, and sequence number of the given ID.
+func (g *Generator) InspectString(id string) (timestamp int64, nodeID int64, sequence int64, err error) {
+	num, err := base32hexdecode(id)
+	if err != nil {
+		return 0, 0, 0, err
+	}
+	return g.Inspect(int64(num))
+}
+
+const b32hexchars = "0123456789abcdefghijklmnopqrstuv"
+
+func base32hexencode(num uint64) string {
+	if num == 0 {
+		return "0"
+	}
+
+	var encoded [13]byte
+	idx := 12
+	for num > 0 {
+		encoded[idx] = b32hexchars[num&0x1f]
+		num >>= 5
+		idx--
+	}
+
+	return string(encoded[idx+1:])
+}
+
+func base32hexdecode(s string) (uint64, error) {
+	var num uint64
+	for _, c := range s {
+		if c == '=' {
+			break
+		}
+
+		num <<= 5
+		if c >= '0' && c <= '9' {
+			num += uint64(c - '0')
+		} else if c >= 'a' && c <= 'v' {
+			num += uint64(c - 'a' + 10)
+		} else if c >= 'A' && c <= 'V' {
+			num += uint64(c - 'A' + 10)
+		} else {
+			return 0, ErrInvalidID
+		}
+	}
+	return num, nil
+}
+
+func EncodeString(id int64) string {
+	return base32hexencode(uint64(id))
+}
+
+func DecodeString(s string) (int64, error) {
+	id, err := base32hexdecode(s)
+	if err != nil {
+		return 0, err
+	}
+	return int64(id), nil
+}

randflake_test.go

@@ -3,6 +3,9 @@ package randflake
 import (
 	"crypto/rand"
 	"encoding/binary"
+	"encoding/hex"
+	"math"
+	"strconv"
 	"sync/atomic"
 	"testing"
 	"time"
@@ -279,3 +282,145 @@ func TestGenerator_Inspect(t *testing.T) {
 		t.Errorf("Expected counter %d, got %d", counter, counter2)
 	}
 }
+
+func TestBase32HexEncode(t *testing.T) {
+	tests := []uint64{
+		0,
+		1,
+		10,
+		100,
+		1000,
+		10000,
+		100000,
+		1000000,
+		10000000,
+		100000000,
+		1000000000,
+		10000000000,
+		100000000000,
+		1000000000000,
+		10000000000000,
+		100000000000000,
+		1000000000000000,
+		10000000000000000,
+		100000000000000000,
+		1000000000000000000,
+		math.MaxUint64,
+		math.MaxInt64,
+	}
+
+	for i := range tests {
+		enc1 := strconv.FormatUint(tests[i], 32)
+		enc2 := base32hexencode(tests[i])
+		if enc1 != enc2 {
+			t.Errorf("Expected %s, got %s", enc1, enc2)
+			t.Fail()
+			return
+		}
+	}
+}
+
+func TestBase32HexDecode(t *testing.T) {
+	tests := []uint64{
+		0,
+		1,
+		10,
+		100,
+		1000,
+		10000,
+		100000,
+		1000000,
+		10000000,
+		100000000,
+		1000000000,
+		10000000000,
+		100000000000,
+		1000000000000,
+		10000000000000,
+		100000000000000,
+		1000000000000000,
+		10000000000000000,
+		100000000000000000,
+		1000000000000000000,
+		math.MaxUint64,
+		math.MaxInt64,
+	}
+
+	for i := range tests {
+		dec1, err := strconv.ParseUint(base32hexencode(tests[i]), 32, 64)
+		if err != nil {
+			t.Errorf("Error decoding %d: %v", tests[i], err)
+			t.Fail()
+			return
+		}
+		dec2, err := base32hexdecode(base32hexencode(tests[i]))
+		if err != nil {
+			t.Errorf("Error decoding %d: %v", tests[i], err)
+			t.Fail()
+			return
+		}
+		if dec1 != dec2 {
+			t.Errorf("Expected %d, got %d", dec1, dec2)
+			t.Fail()
+			return
+		}
+	}
+}
+
+func TestInspectString(t *testing.T) {
+	keyString := "dffd6021bb2bd5b0af676290809ec3a5"
+	encoded := "3vgoe12ccb8gh"
+
+	key, err := hex.DecodeString(keyString)
+	if err != nil {
+		t.Fatalf("Failed to decode key: %v", err)
+	}
+
+	id, err := DecodeString(encoded)
+	if err != nil {
+		t.Fatalf("Failed to decode ID: %v", err)
+	}
+
+	if id != 4594531474933654033 {
+		t.Errorf("Expected ID 4594531474933654033, got %d", id)
+	}
+
+	g, err := NewGenerator(1, time.Now().Unix(), time.Now().Unix()+3600, key)
+	if err != nil {
+		t.Fatalf("Failed to create generator: %v", err)
+	}
+
+	timestamp0, nodeID0, counter0, err := g.Inspect(int64(id))
+	if err != nil {
+		t.Fatalf("Failed to inspect ID: %v", err)
+	}
+
+	if timestamp0 != 1733706297 {
+		t.Errorf("Expected timestamp 1733706297, got %d", timestamp0)
+	}
+
+	if nodeID0 != 42 {
+		t.Errorf("Expected node ID 42, got %d", nodeID0)
+	}
+
+	if counter0 != 1 {
+		t.Errorf("Expected counter 1, got %d", counter0)
+	}
+
+	timestamp1, nodeID1, counter1, err := g.InspectString(encoded)
+	if err != nil {
+		t.Fatalf("Failed to inspect ID: %v", err)
+	}
+
+	if timestamp1 != 1733706297 {
+		t.Errorf("Expected timestamp 1733706297, got %d", timestamp1)
+	}
+
+	if nodeID1 != 42 {
+		t.Errorf("Expected node ID 42, got %d", nodeID1)
+	}
+
+	if counter1 != 1 {
+		t.Errorf("Expected counter 1, got %d", counter1)
+	}
+}

src/randflake/randflake.py

@@ -62,6 +62,32 @@ def __init__(self):
         )
 
 
+class ErrInvalidID(RandflakeError):
+    def __init__(self):
+        super().__init__("randflake: invalid id")
+
+
+_base32hexchars = "0123456789abcdefghijklmnopqrstuv"
+
+
+def _encodeB32hex(n):
+    if n < 0:
+        n += 1 << 64
+
+    if n == 0:
+        return "0"
+
+    result = ""
+    while n > 0:
+        result = base32hexchars[n & 0x1F] + result
+        n = n // 32
+    return result
+
+
+def _decodeB32hex(s):
+    return int(s, 32)
+
+
 class Generator:
     def __init__(self, node_id: int, lease_start: int, lease_end: int, secret: bytes):
         if lease_end < lease_start:
@@ -134,6 +160,10 @@ def generate(self) -> int:
         self.sbox.encrypt(dst, src)
         return struct.unpack("<q", dst)[0]
 
+    def generate_string(self) -> str:
+        _id = self.generate()
+        return _encodeB32hex(_id)
+
     def inspect(self, id_val: int) -> Tuple[int, int, int]:
         src = struct.pack("<q", id_val)
         dst = bytearray(8)  # Use bytearray for dst
@@ -150,3 +180,7 @@ def inspect(self, id_val: int) -> Tuple[int, int, int]:
         sequence = id_raw & RANDFLAKE_MAX_SEQUENCE
 
         return timestamp, node_id, sequence
+
+    def inspect_string(self, id_str: str) -> Tuple[int, int, int]:
+        id_val = _decodeB32hex(id_str)
+        return self.inspect(id_val)

src/randflake/test_randflake.py

@@ -202,8 +202,14 @@ def test_inspect(self):
         secret_bytes = bytes.fromhex(secret)
         g = Generator(1, time.time(), time.time() + 3600, secret_bytes)
 
-        id = 4594531474933654033
-        timestamp, node_id, counter = g.inspect(id)
+        _id = 4594531474933654033
+        timestamp, node_id, counter = g.inspect(_id)
+        self.assertEqual(timestamp, 1733706297)
+        self.assertEqual(node_id, 42)
+        self.assertEqual(counter, 1)
+
+        _id_str = "3vgoe12ccb8gh"
+        timestamp, node_id, counter = g.inspect_string(_id_str)
         self.assertEqual(timestamp, 1733706297)
         self.assertEqual(node_id, 42)
         self.assertEqual(counter, 1)