ByteAether.Ulid 1.3.0

ULID

from ByteAether

A high-performance, fully compliant .NET implementation of ULIDs (Universally Unique Lexicographically Sortable Identifiers), adhering to the official ULID specification.

For more detailed documentation, visit our GitHub repository.

Features

• Universally Unique: Ensures global uniqueness across systems.
• Sortable: Lexicographically ordered for time-based sorting.
• Fast and Efficient: Optimized for high performance and low memory usage.
• Specification-Compliant: Fully adheres to the ULID specification.
• Interoperable: Includes conversion methods to and from GUIDs, Crockford's Base32 strings, and byte arrays.
• Ahead-of-Time (AoT) Compilation Compatible: Fully compatible with AoT compilation for improved startup performance and smaller binary sizes.
• Error-Free Generation: Prevents OverflowException by incrementing the timestamp component when the random part overflows, ensuring continuous unique ULID generation.

Installation

Install the latest stable package via NuGet:

dotnet add package ByteAether.Ulid

To install a specific preview version, use the --version option:

dotnet add package ByteAether.Ulid --version <VERSION_NUMBER>

Usage

Here is a basic example of how to use the ULID implementation:

using System;
using ByteAether.Ulid;

// Create a new ULID
var ulid = Ulid.New();

// Convert to byte array and back
byte[] byteArray = ulid.ToByteArray();
var ulidFromByteArray = Ulid.New(byteArray);

// Convert to GUID and back
Guid guid = ulid.ToGuid();
var ulidFromGuid = Ulid.New(guid);

// Convert to string and back
string ulidString = ulid.ToString();
var ulidFromString = Ulid.Parse(ulidString);

Console.WriteLine($"ULID: {ulid}, GUID: {guid}, String: {ulidString}");

API

The Ulid implementation provides the following properties and methods:

Creation

• Ulid.New(GenerationOptions? options = null)
  Generates a new ULID using default generation options. Accepts an optional GenerationOptions parameter to customize the generation behavior.
• Ulid.New(DateTimeOffset dateTimeOffset, GenerationOptions? options = null)
  Generates a new ULID using the specified DateTimeOffset and default generation options. Accepts an optional GenerationOptions parameter to customize the generation behavior.
• Ulid.New(long timestamp, GenerationOptions? options = null)
  Generates a new ULID using the specified Unix timestamp in milliseconds (long) and default generation options. Accepts an optional GenerationOptions parameter to customize the generation behavior.
• Ulid.New(DateTimeOffset dateTimeOffset, ReadOnlySpan<byte> random)
  Generates a new ULID using the specified DateTimeOffset and a pre-existing random byte array.
• Ulid.New(long timestamp, ReadOnlySpan<byte> random)
  Generates a new ULID using the specified Unix timestamp in milliseconds (long) and a pre-existing random byte array.
• Ulid.New(ReadOnlySpan<byte> bytes)
  Creates a ULID from an existing byte array.
• Ulid.New(Guid guid)
  Create from existing Guid.

Checking Validity

• Ulid.IsValid(string ulidString)
  Validates if the given string is a valid ULID.
• Ulid.IsValid(ReadOnlySpan<char> ulidString)
  Validates if the given span of characters is a valid ULID.
• Ulid.IsValid(ReadOnlySpan<byte> ulidBytes)
  Validates if the given byte array represents a valid ULID.

Parsing

• Ulid.Parse(ReadOnlySpan<char> chars, IFormatProvider? provider = null)
  Parses a ULID from a character span in canonical format. The IFormatProvider is ignored.
• Ulid.TryParse(ReadOnlySpan<char> s, IFormatProvider? provider, out Ulid result)
  Tries to parse a ULID from a character span in canonical format. Returns true if successful.
• Ulid.Parse(string s, IFormatProvider? provider = null)
  Parses a ULID from a string in canonical format. The IFormatProvider is ignored.
• Ulid.TryParse(string? s, IFormatProvider? provider, out Ulid result)
  Tries to parse a ULID from a string in canonical format. Returns true if successful.

Properties

• Ulid.Empty
  Represents an empty ULID, equivalent to default(Ulid) and Ulid.New(new byte[16]).
• Ulid.DefaultGenerationOptions
  Default configuration for ULID generation when no options are provided by the Ulid.New(...) call.
• .Time
  Gets the timestamp component of the ULID as a DateTimeOffset.
• .TimeBytes
  Gets the time component of the ULID as a ReadOnlySpan<byte>.
• .Random
  Gets the random component of the ULID as a ReadOnlySpan<byte>.

Conversion Methods

• .AsByteSpan()
  Provides a ReadOnlySpan<byte> representing the contents of the ULID.
• .ToByteArray()
  Converts the ULID to a byte array.
• .ToGuid()
  Converts the ULID to a Guid.
• .ToString(string? format = null, IFormatProvider? formatProvider = null)
  Converts the ULID to a canonical string representation. Format arguments are ignored.

Comparison Operators

• Supports all comparison operators:
  ==, !=, <, <=, >, >=.
• Implements standard comparison and equality methods:
  CompareTo, Equals, GetHashCode.
• Provides implicit operators to and from Guid.

GenerationOptions

The GenerationOptions class provides detailed configuration for ULID generation, with the following key properties:

• Monotonicity
  Controls the behavior of ULID generation when multiple identifiers are created within the same millisecond. It determines whether ULIDs are strictly increasing or allow for random ordering within that millisecond. Available options include: NonMonotonic, MonotonicIncrement (default), MonotonicRandom1Byte, MonotonicRandom2Byte, MonotonicRandom3Byte, MonotonicRandom4Byte.

• InitialRandomSource
  An IRandomProvider for generating the random bytes of a ULID. The default CryptographicallySecureRandomProvider ensures robust, unpredictable ULIDs using a cryptographically secure generator.

• IncrementRandomSource
  An IRandomProvider that provides randomness for monotonic random increments. The default PseudoRandomProvider is a faster, non-cryptographically secure source optimized for this specific purpose.

This library comes with two default IRandomProvider implementations:

• CryptographicallySecureRandomProvider
  Utilizes System.Security.Cryptography.RandomNumberGenerator for high-quality, cryptographically secure random data.
• PseudoRandomProvider
  A faster, non-cryptographically secure option based on System.Random, ideal for performance-critical scenarios where cryptographic security is not required for random increments.

Custom IRandomProvider implementations can also be created.

Integration with Other Libraries

ASP.NET Core

Supports seamless integration as a route or query parameter with built-in TypeConverter.

System.Text.Json

Includes a JsonConverter for easy serialization and deserialization.

Other Libraries

Check out README in GitHub repository for examples to integrate with Entity Framework Core, Dapper, MessagePack, and Newtonsoft.Json.

Prior Art

Much of this implementation is either based on or inspired by existing works. This library is standing on the shoulders of giants.

• NetUlid
• Ulid
• NUlid
• Official ULID specification
• Crockford's Base32

License

This project is licensed under the MIT License. See the LICENSE file for details.