Merge pull request #151 from Tynab/develop

Develop

Author: Tynab

README.md

@@ -27,6 +27,7 @@
   - [YANTask](#yantask)
   - [YANProcess](#yanprocess)
   - [YANExpression](#yanexpression)
+  - [YANLib.Snowflake](#yanlibsnowflake)
 - [Performance Benchmarks](#-performance-benchmarks)
 - [Code Examples](#-code-examples)
 - [Project Architecture](#-project-architecture)
@@ -361,6 +362,56 @@ var person = new Person { Name = "John", Age = 30 };
 string name = (string)func(person); // Returns "John"
 ```
 
+### YANLib.Snowflake
+
+A robust implementation of the Snowflake ID algorithm for generating distributed, time-ordered unique identifiers in C# applications.
+
+#### Key Features
+
+- 64-bit unique ID generation
+- Alphabetic and alphanumeric string representations
+- Time-ordered IDs for easy sorting
+- Distributed system support with worker and datacenter IDs
+- Component extraction from existing IDs
+- Predefined bit allocation strategies for different use cases
+- Customizable bit allocation for specialized scaling needs
+
+```csharp
+// Create an ID generator with worker ID 1 and datacenter ID 1
+var generator = new IdGenerator(1, 1);
+
+// Generate a numeric ID
+long id = generator.NextId();
+// Example: 6982190104624234496
+
+// Generate an alphabetic ID (base-26, A-Z)
+string alphabeticId = generator.NextIdAlphabetic();
+// Example: "BPNHEBKDMGLCQ"
+
+// Generate an alphanumeric ID (base-36, 0-9, A-Z)
+string alphanumericId = generator.NextIdAlphanumeric();
+// Example: "1Z9DHPKW0S"
+
+// Create a generator with a predefined bit allocation strategy
+// MoreDistributed: 10 bits for worker ID (0-1023), 10 bits for datacenter ID (0-1023), 3 bits for sequence (0-7)
+var distributedGenerator = new IdGenerator(100, 200, BitAllocationStrategy.MoreDistributed);
+
+// HighVolume: 2 bits for worker ID (0-3), 2 bits for datacenter ID (0-3), 19 bits for sequence (0-524,287)
+var highVolumeGenerator = new IdGenerator(1, 1, BitAllocationStrategy.HighVolume);
+
+// Extract components from an ID
+var components = IdGenerator.ExtractIdComponents(id);
+DateTime timestamp = components.Timestamp;
+long workerId = components.WorkerId;
+long datacenterId = components.DatacenterId;
+
+// Extract components using the same strategy used to generate the ID
+var strategicComponents = IdGenerator.ExtractIdComponents(
+    distributedGenerator.NextId(),
+    BitAllocationStrategy.MoreDistributed
+);
+```
+
 
 ## 📊 Performance Benchmarks
 
@@ -468,6 +519,61 @@ public Customer PrepareCustomerData(Customer customer)
 }
 ```
 
+### Unique ID Generation with Snowflake
+
+```csharp
+public class IdService
+{
+    private readonly IdGenerator _userIdGenerator;
+    private readonly IdGenerator _orderIdGenerator;
+    private readonly IdGenerator _highVolumeGenerator;
+    
+    public IdService()
+    {
+        // Create separate generators for different entity types
+        _userIdGenerator = new IdGenerator(1, 1);
+        _orderIdGenerator = new IdGenerator(2, 1);
+        
+        // Create a high-volume generator with custom bit allocation
+        // 2 bits for worker ID, 2 bits for datacenter ID, 19 bits for sequence
+        _highVolumeGenerator = new IdGenerator(
+            workerId: 1,
+            datacenterId: 1,
+            sequence: 0,
+            workerIdBits: 2,
+            datacenterIdBits: 2,
+            sequenceBits: 19
+        );
+    }
+    
+    public string GenerateUserId()
+    {
+        // Generate a compact alphanumeric ID for users
+        return _userIdGenerator.NextIdAlphanumeric();
+    }
+    
+    public long GenerateOrderId()
+    {
+        // Generate a numeric ID for orders
+        return _orderIdGenerator.NextId();
+    }
+    
+    public long GenerateHighVolumeId()
+    {
+        // Generate an ID optimized for high volume (up to 524,287 IDs per millisecond)
+        return _highVolumeGenerator.NextId();
+    }
+    
+    public DateTime GetIdCreationTime(long id)
+    {
+        // Extract the timestamp from an ID
+        var components = IdGenerator.ExtractIdComponents(id);
+
+        return components.Timestamp;
+    }
+}
+```
+
 ### Random Test Data Generation
 
 ```csharp
@@ -532,6 +638,7 @@ YANLib is based on .NET 8.0 (LTS) and consists of the following main components:
 - Task
 - Process
 - Expression
+- Snowflake
 
 ### Project Structure
 
@@ -581,9 +688,13 @@ YANLib/
 │       ├── YANProcess.Collection.cs
 │       └── ...
 └── Advanced/
-    └── Expression/
-        ├── YANExpression.cs
-        ├── YANExpression.Implement.cs
+    ├── Expression/
+    │   ├── YANExpression.cs
+    │   ├── YANExpression.Implement.cs
+    │   └── ...
+    └── Snowflake/
+        ├── IdGenerator.Constant.cs
+        ├── IdGenerator.Constructor.cs
         └── ...
 ```
 
@@ -602,6 +713,7 @@ Each component in YANLib is implemented with careful attention to performance, m
 - **YANTask**: Uses HashSet<Task`<T>`> for efficient task tracking and implements async/await patterns
 - **YANProcess**: Uses Process.GetProcessesByName() with proper resource cleanup
 - **YANExpression**: Uses expression trees with thread-safe caching in ConcurrentDictionary
+- **YANLib.Snowflake**: Implements the Snowflake algorithm with bit manipulation for efficient ID generation and customizable bit allocation
 
 
 ### Important Notes

lib/YANLib/Snowflake/BitAllocationStrategy.cs

@@ -0,0 +1,38 @@
+namespace YANLib.Snowflake;
+
+/// <summary>
+/// Defines the bit allocation strategies for the Snowflake ID generator.
+/// </summary>
+/// <remarks>
+/// Each strategy allocates the 23 available bits differently between worker ID, datacenter ID, and sequence components,
+/// optimizing for different use cases.
+/// </remarks>
+public enum BitAllocationStrategy
+{
+    /// <summary>
+    /// Default allocation: 5 bits for worker ID, 5 bits for datacenter ID, 13 bits for sequence.
+    /// Supports up to 32 workers per datacenter, 32 datacenters, and 8,192 IDs per millisecond per worker.
+    /// </summary>
+    Default,
+
+    /// <summary>
+    /// More distributed allocation: 10 bits for worker ID, 10 bits for datacenter ID, 3 bits for sequence.
+    /// Supports up to 1,024 workers per datacenter, 1,024 datacenters, and 8 IDs per millisecond per worker.
+    /// Optimized for highly distributed systems with many nodes.
+    /// </summary>
+    MoreDistributed,
+
+    /// <summary>
+    /// High volume allocation: 2 bits for worker ID, 2 bits for datacenter ID, 19 bits for sequence.
+    /// Supports up to 4 workers per datacenter, 4 datacenters, and 524,288 IDs per millisecond per worker.
+    /// Optimized for high-throughput scenarios with few nodes.
+    /// </summary>
+    HighVolume,
+
+    /// <summary>
+    /// Balanced allocation: 8 bits for worker ID, 8 bits for datacenter ID, 7 bits for sequence.
+    /// Supports up to 256 workers per datacenter, 256 datacenters, and 128 IDs per millisecond per worker.
+    /// Provides a balance between distribution and sequence capacity.
+    /// </summary>
+    Balanced
+}

lib/YANLib/Snowflake/IdGenerator.Constant.cs

@@ -0,0 +1,47 @@
+namespace YANLib.Snowflake;
+
+/// <summary>
+/// Provides a distributed unique ID generator implementation based on the Snowflake algorithm.
+/// </summary>
+/// <remarks>
+/// This partial class contains the constant values used in the Snowflake ID generation algorithm,
+/// including bit allocations, maximum values, and shift operations for the different components of the ID.
+/// </remarks>
+public partial class IdGenerator
+{
+    /// <summary>
+    /// The epoch timestamp in milliseconds (January 1, 2023 00:00:00 UTC).
+    /// </summary>
+    /// <remarks>
+    /// This constant represents the starting point for timestamp calculations in the Snowflake algorithm.
+    /// </remarks>
+    public const long TIMESTAMP_EPOCH = 1_672_531_200_000;
+
+    private const int TOTAL_BITS = 23;
+
+    // Default bit allocation (5-5-13)
+    private const int DEFAULT_WORKER_ID_BITS = 5;
+    private const int DEFAULT_DATACENTER_ID_BITS = 5;
+    private const int DEFAULT_SEQUENCE_BITS = 13;
+
+    // More Distributed bit allocation (10-10-3)
+    private const int MORE_DISTRIBUTED_WORKER_ID_BITS = 10;
+    private const int MORE_DISTRIBUTED_DATACENTER_ID_BITS = 10;
+    private const int MORE_DISTRIBUTED_SEQUENCE_BITS = 3;
+
+    // High Volume bit allocation (2-2-19)
+    private const int HIGH_VOLUME_WORKER_ID_BITS = 2;
+    private const int HIGH_VOLUME_DATACENTER_ID_BITS = 2;
+    private const int HIGH_VOLUME_SEQUENCE_BITS = 19;
+
+    // Balanced bit allocation (8-8-7)
+    private const int BALANCED_WORKER_ID_BITS = 8;
+    private const int BALANCED_DATACENTER_ID_BITS = 8;
+    private const int BALANCED_SEQUENCE_BITS = 7;
+
+    private const string BASE_ALPHABETIC_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    private static readonly int BASE_ALPHABETIC_CHARS_LENGTH = BASE_ALPHABETIC_CHARS.Length;
+
+    private const string BASE_ALPHANUMERIC_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    private static readonly int BASE_ALPHANUMERIC_CHARS_LENGTH = BASE_ALPHANUMERIC_CHARS.Length;
+}