Return this UUID formatted as a string.
@param style Optional output style. Defaults to "canonical".
@eryx/uuid Module
UUID generation, parsing, and formatting.
This module implements the RFC 9562 UUID families v1, v3, v4,
v5, v6, v7, and v8, along with parsing, coercion, comparison,
and formatting helpers.
UUIDs may be consumed as canonical strings, raw 16-byte buffer
values, or metatable-backed UUID objects returned by this module.
Parsed and generated UUID objects expose common metadata such as
variant, version, and bytes, with additional version-specific
fields available on timestamped layouts like v1, v6, and v7.
Version overview:
v1Time-based UUIDs with Gregorian 100ns timestamps, clock sequence, and node ID.v3Namespace-name UUIDs hashed with MD5.v4Random UUIDs generated from a cryptographically secure RNG.v5Namespace-name UUIDs hashed with SHA-1.v6Reordered time-based UUIDs optimized for bytewise sorting.v7Unix-millisecond ordered UUIDs intended for new sortable identifiers.v8Application-defined UUID layouts with normalized version and variant bits.
Textual forms:
- canonical:
123e4567-e89b-12d3-a456-426614174000 - simple:
123e4567e89b12d3a456426614174000 - braced:
{123e4567-e89b-12d3-a456-426614174000} - URN:
urn:uuid:123e4567-e89b-12d3-a456-426614174000
local uuid = require("@eryx/uuid")
local id = uuid.v7()
print(id.kind) -- "v7"
print(uuid.format(id)) -- canonical UUID string
local parsed = uuid.parse("01890f3a-b5f7-7c0d-8f50-8f8c2c7adf4d")
print(parsed.kind, parsed.version) -- "v7", 7
Summary
Functions
UUID:toBuffer() → buffer
API Reference
Functions
<anonymous>
UUID:toString
UUID:toBuffer
UUID:toBuffer() → buffer
Returns
buffer
The formatted UUID string.
UUID:equals
Return a copy of this UUID's raw 16-byte representation.
Returns
A new buffer containing the UUID bytes.
UUID:compare
Check whether this UUID equals another UUID-like value.
Parameters
A UUID object, UUID string, or 16-byte buffer.
Returns
true when both values encode the same bytes.
UUID:isNil
Compare this UUID to another UUID-like value using bytewise ordering.
@param other A UUID object, UUID string, or 16-byte buffer.
Returns
-1, 0, or 1 depending on ordering.
UUID:unixMilliseconds
Check whether this UUID is the all-zero nil UUID.
Returns
true when every byte is zero.
UUID.__tostring
Return the recoverable Unix-millisecond timestamp for timestamped UUIDs.
For v1 and v6, this is derived from the embedded Gregorian 100ns
timestamp. For v7, it is the native Unix-millisecond field. Other
UUID versions return nil.
Returns
Unix milliseconds, or nil when not applicable.
uuid.parse
Parse a UUID string into a UUID object.
Canonical hyphenated strings are always accepted. Hyphenless, braced,
and URN forms may be enabled through options.
Parameters
UUID string to parse.
Optional parse flags controlling accepted textual forms.
Returns
Parsed UUID object with recovered metadata where available.
uuid.tryParse
Parse a UUID string, returning nil instead of raising on invalid input.
Parameters
UUID string to parse.
Optional parse flags controlling accepted textual forms.
Returns
UUID?
Parsed UUID object, or nil when parsing fails.
uuid.from
Coerce a UUID-like value into a UUID object.
Existing UUID objects are returned as-is. Strings are parsed, and 16-byte buffers are decoded directly.
Parameters
UUID object, UUID string, or 16-byte buffer.
Optional parse flags used when value is a string.
Returns
Normalized UUID object.
uuid.validate
Return whether a UUID-like value can be successfully coerced.
Parameters
UUID object, UUID string, or 16-byte buffer.
Optional parse flags used when value is a string.
Returns
true when coercion succeeds.
uuid.format
Format a UUID-like value into a textual representation.
Parameters
UUID object, UUID string, or 16-byte buffer.
Optional output style. Defaults to "canonical".
Returns
Formatted UUID string.
uuid.toBuffer
Return a copy of a UUID-like value as a raw 16-byte buffer.
Parameters
UUID object, UUID string, or 16-byte buffer.
Returns
buffer
New buffer containing the UUID bytes.
uuid.equals
Check whether two UUID-like values are bytewise equal.
Parameters
Returns
true when both values encode the same UUID.
uuid.compare
Compare two UUID-like values using raw byte ordering.
This is useful for sortable UUID families such as v6 and v7, or
when storing UUIDs in ordered indexes.
Parameters
Returns
-1, 0, or 1 depending on ordering.
uuid.v1
Generate a version 1 UUID.
When not explicitly supplied, the node and clock sequence are derived
from cryptographically secure random bytes. The nanoseconds field
represents the sub-millisecond portion of the timestamp and must be a
multiple of 100.
Parameters
Optional generation controls.
Returns
Generated version 1 UUID.
uuid.v3
Generate a version 3 namespace-name UUID using MD5.
Parameters
Namespace and name to hash.
Returns
Generated version 3 UUID.
uuid.v4
Generate a version 4 random UUID.
By default this uses @eryx/crypto/hazmat/random.bytes.
Parameters
Optional RNG override.
Returns
Generated version 4 UUID.
uuid.v5
Generate a version 5 namespace-name UUID using SHA-1.
Parameters
Namespace and name to hash.
Returns
Generated version 5 UUID.
uuid.v6
Generate a version 6 reordered time-based UUID.
This uses the same Gregorian 100ns timestamp source model as v1, but
reorders the bytes to improve sort locality.
Parameters
Optional generation controls.
Returns
Generated version 6 UUID.
uuid.v7
Generate a version 7 Unix-time-ordered UUID.
When sequence is omitted, this module applies monotonic sequencing so
that repeated calls remain bytewise ordered even within the same
millisecond.
Parameters
Optional generation controls.
Returns
Generated version 7 UUID.
uuid.v8
Generate a version 8 UUID from caller-supplied bytes.
The provided payload must be exactly 16 bytes long. The version and
variant bits are normalized to match a valid v8 UUID.
Parameters
Raw payload bytes to wrap as a version 8 UUID.
Returns
Generated version 8 UUID.
Types
UUIDVariant
UUIDVersionName
UUIDFormatStyle
RandomSource
UUIDv1
Implements: UUIDBase
kind: "v1"
Gregorian timestamp in 100ns intervals since 1582-10-15.
Convenience timestamp in Unix milliseconds.
14-bit clock sequence.
node: buffer
48-bit node identifier as 6 bytes.
UUIDv3
Implements: UUIDBase
kind: "v3"
UUIDv4
Implements: UUIDBase
kind: "v4"
UUIDv5
Implements: UUIDBase
kind: "v5"
UUIDv6
Implements: UUIDBase
kind: "v6"
Reordered Gregorian timestamp in 100ns intervals since 1582-10-15.
Convenience timestamp in Unix milliseconds.
14-bit clock sequence.
node: buffer
48-bit node identifier as 6 bytes.
UUIDv7
Implements: UUIDBase
kind: "v7"
Milliseconds since the Unix epoch.
The 12-bit rand_a field.
randB: buffer
The trailing 64-bit payload as 8 bytes, including variant bits.
UUIDv8
Implements: UUIDBase
kind: "v8"
ParseOptions
UUIDv1Options
type UUIDv1Options = {
unixMillis: integer?,
nanoseconds: number?,
clockSequence: number?,
node: buffer | string?,
random: RandomSource?
}
UUIDv3Options
UUIDv5Options
UUIDv6Options
type UUIDv6Options = {
unixMillis: integer?,
nanoseconds: number?,
clockSequence: number?,
node: buffer | string?,
random: RandomSource?
}