Class GenerateValue

Namespace: Cratis.Concepts

Assembly: Cratis.Fundamentals.dll

Generates values using cryptographically secure randomness.

public static class GenerateValue

Inheritance: object

GenerateValue

Inherited Members: object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

Bytes(int, ValueEncoding)

Creates cryptographically secure random bytes encoded as an unpadded string.

public static string Bytes(int count, ValueEncoding encoding = ValueEncoding.Base64Url)

Parameters

count int: The number of random bytes, from 1 to 512.
encoding ValueEncoding: The text encoding; defaults to URL-safe base64 without padding.

Returns

string: The encoded random bytes: URL-safe base64, lowercase hex, or uppercase RFC 4648 base32.

Exceptions

InvalidByteCount: The count is outside 1 to 512.
UnknownValueEncoding: The encoding is undefined.

HasValidChecksum(string, Checksum)

Checks exact trailing check digits against all preceding ASCII digits, ignoring printable nondigits.

public static bool HasValidChecksum(string value, Checksum checksum)

Parameters

value string: The complete payload and trailing check digits.
checksum Checksum: The checksum algorithm; None is not valid for validation.

Returns

bool: Whether the printable-ASCII value has exactly the expected check digits.

Exceptions

ArgumentNullException: The value is null.
UnknownChecksum: The checksum is None or undefined.

Integer(long, long)

Creates an unbiased integer in an inclusive Int64 range using cryptographically secure randomness.

public static long Integer(long minimum, long maximum)

Parameters

minimum long: The inclusive lower bound.
maximum long: The inclusive upper bound.

Returns

long: A uniformly distributed integer between the bounds, including both endpoints.

Exceptions

InvalidIntegerRange: The minimum exceeds the maximum.

NanoId(int, string?)

Creates a uniformly random string from a printable ASCII alphabet.

public static string NanoId(int size = 21, string? alphabet = null)

Parameters

size int: The number of characters, from 1 to 256; defaults to 21.
alphabet string: Two to 256 distinct printable ASCII characters, or null for A-Z, a-z, 0-9, underscore and hyphen.

Returns

string: A string of the requested size drawn uniformly using cryptographically secure randomness.

Exceptions

InvalidNanoIdSize: The size is outside 1 to 256.
InvalidNanoIdAlphabet: The alphabet is not distinct printable ASCII or its length is outside 2 to 256.

Pattern(string, Checksum)

Creates a uniformly selected distinct string from a finite printable-ASCII pattern.

public static string Pattern(string pattern, Checksum checksum = Checksum.None)

Parameters

pattern string: The pattern containing at least one random token.
checksum Checksum: Optional check digits appended over all payload digits.

Returns

string: A uniformly sampled admissible value, including any check digits.

Exceptions

InvalidValuePattern: The pattern is invalid or exceeds a construction budget.
PatternRequiresGenerationContext: The pattern contains date segments.
EmptyPatternSupport: No payload has an emittable check digit.
UnknownChecksum: The checksum is undefined.

Pattern(string, GenerationContext, Checksum)

Creates a uniformly selected distinct string with date segments fixed to the operation's UTC date.

public static string Pattern(string pattern, GenerationContext context, Checksum checksum = Checksum.None)

Parameters

pattern string: The pattern containing at least one random token.
context GenerationContext: The operation's captured time and tenant; the tenant does not affect this strategy.
checksum Checksum: Optional check digits appended over all payload digits.

Returns

string: A uniformly sampled admissible value, including any check digits.

Exceptions

MissingGenerationTime: The context has no captured time, even for a pattern without dates.
InvalidValuePattern: The pattern is invalid or exceeds a construction budget.
EmptyPatternSupport: No payload has an emittable check digit for the captured date.
UnknownChecksum: The checksum is undefined.

TypeId(string)

Creates a TypeID with a validated prefix and a UUID v7 suffix using the current time.

public static string TypeId(string prefix)

Parameters

prefix string: Zero to 63 lowercase letters or underscores, starting and ending with a letter unless empty.

Returns

string: The prefix and underscore followed by 26 lowercase Crockford base32 characters, or only the suffix for an empty prefix.

Exceptions

InvalidTypeIdPrefix: The prefix does not match the TypeID prefix rules.

TypeId(string, GenerationContext)

Creates a TypeID with a validated prefix and a UUID v7 suffix using the operation's time.

public static string TypeId(string prefix, GenerationContext context)

Parameters

prefix string: Zero to 63 lowercase letters or underscores, starting and ending with a letter unless empty.
context GenerationContext: The operation's captured time and tenant.

Returns

string: The prefix and underscore followed by 26 lowercase Crockford base32 characters, or only the suffix for an empty prefix.

Exceptions

InvalidTypeIdPrefix: The prefix does not match the TypeID prefix rules.
MissingGenerationTime: The context has no captured time.
GenerationTimeBeforeUnixEpoch: The captured time precedes the Unix epoch.

Ulid()

Creates a ULID containing the current Unix-epoch milliseconds and 80 random bits.

public static string Ulid()

Returns

string: 26 uppercase Crockford base32 characters, with a first character from 0 to 7.

Remarks

Values expose creation time and are not monotonic within a millisecond.

Ulid(GenerationContext)

Creates a ULID containing the operation's Unix-epoch milliseconds and 80 random bits.

public static string Ulid(GenerationContext context)

Parameters

context GenerationContext: The operation's captured time and tenant.

Returns

string: 26 uppercase Crockford base32 characters, with a first character from 0 to 7.

Exceptions

MissingGenerationTime: The context has no captured time.
GenerationTimeBeforeUnixEpoch: The captured time precedes the Unix epoch.

Uuid()

Creates an RFC 9562 version 4 UUID using cryptographically secure randomness.

public static Guid Uuid()

Returns

Guid: A random version 4 UUID with the RFC variant.

UuidV7()

Creates an RFC 9562 version 7 UUID containing the current Unix-epoch milliseconds.

public static Guid UuidV7()

Returns

Guid: A time-ordered version 7 UUID with the RFC variant and cryptographically secure random bits.

Remarks

Values expose their creation time and are not monotonic within a millisecond. Clock adjustments can also affect their chronological order.

UuidV7(GenerationContext)

Creates an RFC 9562 version 7 UUID containing the operation's Unix-epoch milliseconds.

public static Guid UuidV7(GenerationContext context)

Parameters

context GenerationContext: The operation's captured time and tenant.

Returns

Guid: A time-ordered UUID with 74 cryptographically secure random bits.

Exceptions

MissingGenerationTime: The context has no captured time.
GenerationTimeBeforeUnixEpoch: The captured time precedes the Unix epoch.