nuid (nuid v1.0.0)

View Source

Unique identifier generation.

This module produces two families of identifiers as t/0 binaries:

  • UUIDs. Versions 1, 3, 4, and 5 per RFC 4122, and versions 6, 7, and 8 per RFC 9562, plus the nil and max UUIDs. Rendered as the canonical 36-character hyphenated form, e.g. <<"018b3d7a-9f9a-7577-adb2-08761e3d87f7">>.
  • nuids. nuid1/0 and nuid2/0, two Nomasystems identifiers that are lexicographically sortable by creation time and carry 128 bits of cryptographically strong randomness. They are encoded with a URL-safe, sortable base64 variant (see nuid_base64).

Time-based and random identifiers (uuid1/0, uuid4/0, uuid6/0, uuid7/0, nuid1/0, nuid2/0) are non-deterministic. The name-based identifiers (uuid3/2, uuid5/2) are deterministic: the same namespace/0 and name always produce the same UUID.

The *_info/1 functions recover the creation time (and, where encoded, the originating node) from an identifier.

Examples

1> nuid:uuid4().
<<"37a9e737-f680-44a9-b83d-a517ec758b75">>
2> nuid:uuid5(dns, <<"nomasystems.com">>).
<<"cefe05b2-95ca-5b0a-ad06-9b3f2b38e532">>
3> nuid:uuid7().
<<"018b3d7a-9f9a-7577-adb2-08761e3d87f7">>
4> nuid:nuid2().
<<"OHtpP-----Fkn3F6JaT5Kxnm_NAiDzFgGMzc">>

Summary

Types

date()
datetime()
day()
hour()
mins()
month()
namespace()

Namespace for name-based UUIDs. The atoms select the predefined RFC 4122 namespace UUIDs; a binary is used verbatim as a custom namespace.

secs()
t()

A generated identifier as a printable binary.

time()
uuid_info()

Decoded creation time, embedded counter, and originating node of a time-based UUID. Defined by the uuidInfo record in nuid.hrl.

Functions

max_uuid()

Return the RFC 9562 max UUID (all one bits).

nil_uuid()

Return the RFC 4122 nil UUID (all zero bits).

nuid1()

Generate a nuid1 identifier.

nuid1_info/1

Recover the creation time from a nuid1 identifier.

nuid2()

Generate a nuid2 identifier.

nuid2_info(Id)

Recover the originating node and creation time from a nuid2 identifier.

uuid1()

Generate a time-based RFC 4122 version 1 UUID.

uuid1_info(Bin)

Recover creation time, counter, and node from a version 1 UUID.

uuid3/2

Generate a name-based RFC 4122 version 3 UUID (MD5).

uuid4()

Generate a random RFC 4122 version 4 UUID (122 random bits).

uuid5/2

Generate a name-based RFC 4122 version 5 UUID (SHA-1).

uuid6()

Generate a time-ordered RFC 9562 version 6 UUID.

uuid6_info(Bin)

Recover creation time, counter, and node from a version 6 UUID.

uuid7()

Generate a time-ordered RFC 9562 version 7 UUID.

uuid7_info(Bin)

Recover the creation time from a version 7 UUID.

uuid8/1

Generate a vendor-specific RFC 9562 version 8 UUID from a 128-bit binary.

uuid8(CustomA, CustomB, CustomC)

Generate a vendor-specific RFC 9562 version 8 UUID from its three custom fields (48, 12, and 62 bits).

Types

date()

-type date() :: {non_neg_integer(), month(), day()}.

datetime()

-type datetime() :: {date(), time()}.

day()

-type day() :: 1..31.

hour()

-type hour() :: 0..23.

mins()

-type mins() :: 0..59.

month()

-type month() :: 1..12.

namespace()

-type namespace() :: dns | url | oid | x500 | nil | binary().

Namespace for name-based UUIDs. The atoms select the predefined RFC 4122 namespace UUIDs; a binary is used verbatim as a custom namespace.

secs()

-type secs() :: 0..59.

t()

-type t() :: binary().

A generated identifier as a printable binary.

time()

-type time() :: {hour(), mins(), secs()}.

uuid_info()

-type uuid_info() :: #uuidInfo{date :: datetime(), id :: integer(), node :: node()}.

Decoded creation time, embedded counter, and originating node of a time-based UUID. Defined by the uuidInfo record in nuid.hrl.

Functions

max_uuid()

-spec max_uuid() -> t().

Return the RFC 9562 max UUID (all one bits).

nil_uuid()

-spec nil_uuid() -> t().

Return the RFC 4122 nil UUID (all zero bits).

nuid1()

-spec nuid1() -> t().

Generate a nuid1 identifier.

A hex microsecond timestamp, a separator, and 16 cryptographically strong random bytes in sortable base64. Lexicographically sortable and greater than any previously generated version 6 UUID.

nuid1_info/1

-spec nuid1_info(t()) -> datetime().

Recover the creation time from a nuid1 identifier.

nuid2()

-spec nuid2() -> t().

Generate a nuid2 identifier.

A POSIX-second timestamp, a sortable counter, 3 bytes of node origin, and 16 cryptographically strong random bytes, all in sortable base64. Lexicographically sortable, URL-safe, and no longer than a UUID.

nuid2_info(Id)

-spec nuid2_info(t()) -> {node() | undefined, datetime()}.

Recover the originating node and creation time from a nuid2 identifier.

The node is resolved against the currently connected nodes; it is undefined if the originating node is not reachable.

uuid1()

-spec uuid1() -> t().

Generate a time-based RFC 4122 version 1 UUID.

uuid1_info(Bin)

-spec uuid1_info(t()) -> uuid_info().

Recover creation time, counter, and node from a version 1 UUID.

uuid3/2

-spec uuid3(namespace(), binary()) -> t().

Generate a name-based RFC 4122 version 3 UUID (MD5).

Deterministic: the same namespace/0 and name always yield the same UUID.

uuid4()

-spec uuid4() -> t().

Generate a random RFC 4122 version 4 UUID (122 random bits).

uuid5/2

-spec uuid5(namespace(), binary()) -> t().

Generate a name-based RFC 4122 version 5 UUID (SHA-1).

Deterministic: the same namespace/0 and name always yield the same UUID.

uuid6()

-spec uuid6() -> t().

Generate a time-ordered RFC 9562 version 6 UUID.

The most significant bits hold the timestamp, so version 6 UUIDs sort lexicographically by creation time.

uuid6_info(Bin)

-spec uuid6_info(t()) -> uuid_info().

Recover creation time, counter, and node from a version 6 UUID.

uuid7()

-spec uuid7() -> t().

Generate a time-ordered RFC 9562 version 7 UUID.

A 48-bit Unix millisecond timestamp followed by 74 random bits. Sorts lexicographically by creation time.

uuid7_info(Bin)

-spec uuid7_info(t()) -> datetime().

Recover the creation time from a version 7 UUID.

uuid8/1

-spec uuid8(binary()) -> t().

Generate a vendor-specific RFC 9562 version 8 UUID from a 128-bit binary.

The version and variant bits in the input are overwritten; all other bits are preserved.

uuid8(CustomA, CustomB, CustomC)

-spec uuid8(non_neg_integer(), non_neg_integer(), non_neg_integer()) -> t().

Generate a vendor-specific RFC 9562 version 8 UUID from its three custom fields (48, 12, and 62 bits).