Aore.SparkId 1.0.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher. .NET Framework 4.6.2 This package targets .NET Framework 4.6.2. The package is compatible with this framework or higher. 
dotnet add package Aore.SparkId --version 1.0.0
                    


                    

                
NuGet\Install-Package Aore.SparkId -Version 1.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Aore.SparkId" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Aore.SparkId" Version="1.0.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Aore.SparkId" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Aore.SparkId --version 1.0.0
                    


                    

                
#r "nuget: Aore.SparkId, 1.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Aore.SparkId@1.0.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Aore.SparkId&version=1.0.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Aore.SparkId&version=1.0.0
                    


                            Install as a Cake Tool

sparkid for C#

Fast, time-sortable, 21-char Base58 unique ID generator for .NET.

Installation

dotnet add package Aore.SparkId

Quick Start

using Aore.SparkId;

// Generate an ID
var id = SparkId.GenerateId();
Console.WriteLine(id.Value);  // "1ocmpHE1bFnygEBAPTzMK"

Features

  • 21-character Base58 IDs — compact, URL-safe, human-readable
  • Time-sortable — IDs sort by creation time
  • Monotonically increasing — strict ordering within a thread
  • Thread-safe — ThreadLocal for synchronous, AsyncLocal for async
  • Zero runtime dependencies — only uses BCL types
  • Multi-target — netstandard2.0, net8.0, net472

API Reference

SparkId (Static Entry Point)

using Aore.SparkId;

// Synchronous (ThreadLocal, thread-safe)
var id = SparkId.GenerateId();
var pastId = SparkId.GenerateIdAt(DateTime.UtcNow.AddDays(-1));

// Asynchronous (AsyncLocal, async-context-safe)
var asyncId = await SparkId.GenerateIdAsync();
var asyncPastId = await SparkId.GenerateIdAtAsync(DateTime.UtcNow.AddDays(-1));

// Extract timestamp
DateTime timestamp = SparkId.ExtractTimestamp(id);
DateTime timestamp2 = SparkId.ExtractTimestamp(id.Value);

SparkIdStr (ID Value Type)

using Aore.SparkId;

var id = new SparkIdStr("1ocmpHE1bFnygEBAPTzMK");

// Properties
string value = id.Value;           // "1ocmpHE1bFnygEBAPTzMK"
DateTime timestamp = id.Timestamp; // Creation time

// Parsing
var parsed = SparkIdStr.Parse("1ocmpHE1bFnygEBAPTzMK");
bool success = SparkIdStr.TryParse("invalid", out var result);

// Comparison (lexicographic)
bool isLess = id1 < id2;
bool isGreater = id1 > id2;
bool isEqual = id1 == id2;

// ToString
string str = id.ToString(); // "1ocmpHE1bFnygEBAPTzMK"

IdGenerator (High-Performance)

using Aore.SparkId;

// Create a reusable generator
var generator = new IdGenerator();

// Generate IDs
var id1 = generator.GenerateId();
var id2 = generator.GenerateId();
// id2 > id1 (monotonic)

// Generate at specific timestamp
var pastId = generator.GenerateIdAt(DateTime.UtcNow.AddHours(-1));

// Reset state
generator.Reset();

Binary Format (16 bytes)

using Aore.SparkId;
using Aore.SparkId.Binary;

var id = SparkId.GenerateId();

// Convert to bytes
byte[] bytes = id.ToBytes();  // 16 bytes
// or
byte[] bytes2 = SparkIdBinary.ToBytes(id.Value);

// Convert from bytes
SparkIdStr restored = SparkIdStr.FromBytes(bytes);
// or
string str = SparkIdBinary.FromBytes(bytes);

// Guid interop
Guid guid = id.ToGuid();
SparkIdStr fromGuid = guid.ToSparkId();
// or
Guid guid2 = SparkIdBinary.ToGuid(id.Value);
string fromGuid2 = SparkIdBinary.FromGuid(guid2);

Thread Safety

Synchronous (ThreadLocal)

// Thread-safe — each thread gets its own generator
var id = SparkId.GenerateId();
  • IDs are strictly monotonically increasing within a single thread
  • Across threads, IDs are unique but unordered

Asynchronous (AsyncLocal)

// Async-context-safe — preserves ordering within async flows
var id = await SparkId.GenerateIdAsync();
  • IDs are strictly monotonically increasing within a single async context
  • Across async contexts, IDs are unique but unordered

Process-Wide Monotonic Ordering

// Use a single generator with a lock for process-wide ordering
private static readonly IdGenerator _generator = new();
private static readonly object _lock = new();

SparkIdStr GenerateOrderedId()
{
    lock (_lock)
    {
        return _generator.GenerateId();
    }
}

Performance

The IdGenerator class is optimized for high-throughput scenarios:

  • Stack-allocated SparkIdStr (no heap allocation)
  • Pre-computed lookup tables for Base58 encoding
  • Batch random number generation (16KB buffer)
  • Minimal string operations on hot path
// Benchmark example
using BenchmarkDotNet.Attributes;
using Aore.SparkId;

[MemoryDiagnoser]
public class SparkIdBenchmark
{
    [Benchmark(Baseline = true)]
    public SparkIdStr GenerateId() => SparkId.GenerateId();

    [Benchmark]
    public Guid GenerateGuid() => Guid.NewGuid();
}

Binary Format Compatibility

The 16-byte binary format is identical across all language implementations:

  • JavaScript: toBytes() / fromBytes()
  • Python: to_bytes() / from_bytes()
  • Rust: to_bytes() / from_bytes()
  • C#: ToBytes() / FromBytes()

Sort order is preserved — byte-wise comparison on the binary form gives the same ordering as string comparison.

Target Frameworks

Framework Status Notes
netstandard2.0 ✅ .NET Core 2.0+, .NET Framework 4.6.1+
net8.0 ✅ .NET 8 LTS, full Span support
net9.0 ✅ .NET 9 LTS, full Span support
net10.0 ✅ .NET 10 LTS, full Span support
net462 ✅ .NET Framework 4.6.2
net472 ✅ .NET Framework 4.7.2
net48 ✅ .NET Framework 4.8

Dependencies

Runtime

  • None (zero dependencies)

Development

  • xunit — testing
  • BenchmarkDotNet — performance benchmarks

License

MIT

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 is compatible.  net48 is compatible.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0 56 9/24/2026

Aore.SparkId Fast, time-sortable, 21-char Base58 unique ID generator