Quantum.Snowflake 1.0.0

Quantum.Snowflake

Quantum.Snowflake is a lightweight and customizable Snowflake ID generator for .NET, producing unique, time-based, sortable identifiers suitable for distributed systems.

Inspired by Twitter's original Snowflake algorithm, it splits the ID into:

• Timestamp
• Instance ID
• Sequence number

✅ Features

• 64-bit Snowflake-style IDs (timestamp + machine + sequence)
• Plug-and-play instance ID and timestamp providers
• Built-in sequence throttling with wrap-around control
• Binary format padding for consistent bit-width representation
• Easily extendable/customizable via interfaces
• Zero external dependencies

📦 Structure

Each Snowflake ID is a binary string composed of:

💡 Example

// Generate a new ID
var snowflake = SnowflakeIdGenerator.New();

// Get full binary string
Console.WriteLine(snowflake.Get());      // 64-bit binary string

// Convert to long
Console.WriteLine(snowflake.ToLong());   // Unique, sortable long
‍‍```

## 🧩 Integration
You can plug in your own timestamp source or machine ID strategy:

```csharp
var customTimestamp = new TimeStampIdGenerator(
    startingPoint: new DateTime(2020, 1, 1),
    dateTimeProvider: new MyCustomDateTimeProvider()
);

var machineId = new MyMachineIdGenerator(); // Must implement IMachineIdGenerator
var sequencer = new Sequencer(12);         // Custom bit-width

SnowflakeIdGenerator.Set(customTimestamp, machineId, sequencer);

🔄 Use Cases

Quantum.Snowflake is ideal for:

• Distributed systems needing globally unique identifiers
• Order-preserving IDs for events, messages, or logs
• Sharded databases with local instance ID logic
• ID generation without relying on database identity columns
• High-throughput message queues and event sourcing
• Distributed caching or temporary object identifiers

🧠 Design Notes

• IMachineIdGenerator allows plug-in strategies for per-instance IDs.
• Sequencer wraps around at 4095, matching classic Snowflake behavior.
• TimeStampIdGenerator allows custom epochs and datetime providers.
• All components use bitwise padding to maintain consistent ID lengths.

🧪 Installation

dotnet add package Quantum.Snowflake

🔗 Related Packages

• Quantum.Tempo: Calendar-agnostic date/time engine
• Quantum.Sequence: Generic cyclic sequencer used in this package