feat: init cuid2

.gitignore

@@ -0,0 +1,15 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Go workspace file
+go.work

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PatrickChoDev.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,42 @@
+# CUID2
+
+Go implementation of [CUID2](https://github.com/paralleldrive/cuid2) - Collision-resistant ids optimized for horizontal scaling and performance.
+
+## Installation
+```bash
+go get github.com/PatrickChoDev/cuid2
+```
+
+## Usage
+```go
+import "github.com/PatrickChoDev/cuid2"
+
+// Generate a CUID with default settings
+id := cuid2.Generate() // Example: "tz4a98xxat96"
+
+// Initialize with custom options
+generator, err := cuid2.Init(
+    cuid2.WithLength(10),                 // Custom length (2-32)
+    cuid2.WithRandomFunc(rand.Float64),   // Custom random function
+    cuid2.WithFingerprint("myapp"),       // Custom fingerprint
+)
+if err != nil {
+    // Handle error
+}
+id = generator() // Generate using custom settings
+
+// Validate a CUID
+valid := cuid2.IsCuid("tz4a98xxat96") // Returns true/false
+```
+
+## Features
+- Thread-safe ID generation
+- Configurable length (2-32 characters)
+- Customizable random function
+- System fingerprinting for distributed systems
+- Validation function
+- Zero external dependencies (except crypto/sha3)
+
+## License
+MIT License
+

benchmark_test.go

@@ -0,0 +1,28 @@
+package cuid2
+
+import (
+	"log"
+	"testing"
+)
+
+var result string
+
+func benchmarkGenerate(b *testing.B, length int) {
+	var id string
+
+	generate, err := Init(WithLength(length))
+	if err != nil {
+		log.Fatalln("Error: Could not initialise Cuid2 generator")
+	}
+
+	for n := 0; n < b.N; n++ {
+		id = generate()
+	}
+
+	result = id
+}
+
+func BenchmarkGenerate8(b *testing.B)  { benchmarkGenerate(b, 8) }
+func BenchmarkGenerate16(b *testing.B) { benchmarkGenerate(b, 16) }
+func BenchmarkGenerate24(b *testing.B) { benchmarkGenerate(b, 24) }
+func BenchmarkGenerate32(b *testing.B) { benchmarkGenerate(b, 32) }

collision_test.go

@@ -0,0 +1,209 @@
+package cuid2
+
+import (
+	"fmt"
+	"log"
+	"math"
+	"math/big"
+	"strconv"
+	"sync"
+	"testing"
+)
+
+func TestCollisions(t *testing.T) {
+	n := int64(math.Pow(float64(7), float64(8)) * 2)
+	log.Printf("Testing %v unique Cuids...", n)
+
+	numPools := int64(7)
+	pools := createIdPools(numPools, n/numPools)
+
+	ids := []string{}
+	for _, pool := range pools {
+		ids = append(ids, pool.ids...)
+	}
+
+	sampleIds := ids[:10]
+	set := map[string]struct{}{}
+	for _, id := range ids {
+		set[id] = struct{}{}
+	}
+
+	histogram := pools[0].histogram
+
+	log.Println("Sample Cuids:", sampleIds)
+	log.Println("Histogram:", histogram)
+
+	expectedBinSize := math.Ceil(float64(n / numPools / int64(len(histogram))))
+	tolerance := 0.05
+	minBinSize := math.Round(expectedBinSize * (1 - tolerance))
+	maxBinSize := math.Round(expectedBinSize * (1 + tolerance))
+	log.Println("Expected bin size:", expectedBinSize)
+	log.Println("Min bin size:", minBinSize)
+	log.Println("Maximum bin size:", maxBinSize)
+
+	collisionsDetected := int64(len(set)) - n
+	if collisionsDetected > 0 {
+		t.Fatalf("%v collisions detected", int64(len(set))-n)
+	}
+
+	for _, binSize := range histogram {
+		withinDistributionTolerance := binSize > minBinSize && binSize < maxBinSize
+		if !withinDistributionTolerance {
+			t.Errorf("Histogram of generated Cuids is not within the distribution tolerance of %v", tolerance)
+			t.Fatalf("Expected bin size: %v, min: %v, max: %v, actual: %v", expectedBinSize, minBinSize, maxBinSize, binSize)
+		}
+	}
+
+	validateCuids(t, ids)
+}
+
+type IdPool struct {
+	ids       []string
+	numbers   []big.Int
+	histogram []float64
+}
+
+func NewIdPool(max int) func() *IdPool {
+	return func() *IdPool {
+
+		set := map[string]struct{}{}
+
+		for i := 0; i < max; i++ {
+			set[Generate()] = struct{}{}
+			if i%100000 == 0 {
+				progress := float64(i) / float64(max)
+				log.Printf("%d%%", int64(progress*100))
+			}
+			if len(set) < i {
+				log.Printf("Collision at: %v", i)
+				break
+			}
+		}
+
+		log.Println("No collisions detected")
+
+		ids := []string{}
+		numbers := []big.Int{}
+
+		for element := range set {
+			ids = append(ids, element)
+			numbers = append(numbers, *idToBigInt(element[1:]))
+		}
+
+		return &IdPool{
+			ids:       ids,
+			numbers:   numbers,
+			histogram: buildHistogram(numbers, 20),
+		}
+	}
+}
+
+func idToBigInt(id string) *big.Int {
+	bigInt := new(big.Int)
+	for _, char := range id {
+		base36Rune, _ := strconv.ParseInt(string(char), 36, 64)
+		bigInt.Add(big.NewInt(base36Rune), bigInt.Mul(bigInt, big.NewInt(36)))
+	}
+	return bigInt
+}
+
+func buildHistogram(numbers []big.Int, bucketCount int) []float64 {
+	log.Println("Building histogram...")
+
+	buckets := make([]float64, bucketCount)
+	counter := 1
+
+	numPermutations, _ := big.NewFloat(math.Pow(float64(36), float64(DefaultIdLength-1))).Int(nil)
+	bucketLength := new(big.Int).Div(
+		numPermutations,
+		big.NewInt(int64(bucketCount)),
+	)
+
+	for _, number := range numbers {
+
+		if new(big.Int).Mod(big.NewInt(int64(counter)), bucketLength).Int64() == 0 {
+			log.Println(number)
+		}
+
+		bucket := new(big.Int).Div(
+			&number,
+			bucketLength,
+		)
+
+		if new(big.Int).Mod(big.NewInt(int64(counter)), bucketLength).Int64() == 0 {
+			log.Println(bucket)
+		}
+
+		buckets[bucket.Int64()]++
+		counter++
+	}
+
+	return buckets
+}
+
+func worker(id int, jobs <-chan func() *IdPool, results chan<- *IdPool) {
+	for job := range jobs {
+		log.Println("worker", id, "started job")
+		results <- job()
+	}
+}
+
+func createIdPools(numPools int64, maxIdsPerPool int64) []*IdPool {
+
+	jobsList := []func() *IdPool{}
+	for i := 0; i < int(numPools); i++ {
+		jobsList = append(jobsList, NewIdPool(int(maxIdsPerPool)))
+	}
+
+	jobs := make(chan func() *IdPool, numPools)
+	results := make(chan *IdPool, numPools)
+
+	for w := 1; w <= int(numPools); w++ {
+		go worker(w, jobs, results)
+	}
+
+	for _, job := range jobsList {
+		jobs <- job
+	}
+	close(jobs)
+
+	pools := []*IdPool{}
+	for a := 1; a <= int(numPools); a++ {
+		pool := <-results
+		pools = append(pools, pool)
+	}
+
+	return pools
+}
+
+func validateCuids(t *testing.T, ids []string) {
+	log.Printf("Validating all %v Cuids...", len(ids))
+
+	wg := new(sync.WaitGroup)
+	validationErrors := make(chan error)
+
+	for _, id := range ids {
+		wg.Add(1)
+		go func(id string) {
+			defer wg.Done()
+			if !IsCuid(id) {
+				validationErrors <- fmt.Errorf("Cuid (%v) is not valid", id)
+			}
+		}(id)
+	}
+
+	go func() {
+		wg.Wait()
+		close(validationErrors)
+	}()
+
+	numInvalidIds := 0
+	for err := range validationErrors {
+		log.Println(err.Error())
+		numInvalidIds++
+	}
+
+	if numInvalidIds > 0 {
+		t.Fatalf("%v Cuids were invalid", numInvalidIds)
+	}
+}