Skip to content
surrealdb.js

Uuid

A Universally Unique Identifier (UUID) is a 128-bit identifier used to uniquely identify a particular entity. The Uuid class represents this identifier, supporting UUID versions 1 through 7. Note that you need a separate library or a built-in runtime function (such as node:crypto) to generate UUIDs.

Importing

import { Uuid } from "@tai-kun/surrealdb/decodeonly-datatypes";
import { Uuid } from "@tai-kun/surrealdb/encodable-datatypes";
import { Uuid } from "@tai-kun/surrealdb/standard-datatypes";

.constructor()

Creates a new Uuid object.

new Uuid(source: Uint8Array); // decode-only, encodable
new Uuid(source: Uint8Array | string); // standard

Arguments

source

A byte array representation of the UUID, or a string for the standard preset.

Return Value

When called with new, Uuid returns its instance.

.bytes instance property >=decode-only

The byte array of the UUID.

.bytes: Uint8Array;

.variant instance property =standard

The variant of the UUID. This is defined by the upper bits of the 13th bit of the UUID and consists of three main variants and one reserved variant for future use.

  1. NCS Compatible
    • 0b0xxx
    • Indicates that the UUID is compatible with the Network Computing System (NCS).
    • Not commonly used.
  2. RFC 4122 Compatible
    • 0b10xx
    • A UUID based on RFC 4122 (the standard specification for UUIDs).
    • The commonly used UUID format. Includes formats such as v1 (time-based) and v4 (random).
  3. Microsoft GUID Compatible
    • 0b110x
    • The format of GUID (Globally Unique Identifier) used by Microsoft.
  4. Reserved for Future Use
    • 0b111x

This property also represents NIL UUID and MAX UUID in addition to the variants above.

.variant:
  | "NIL" // 00000000-0000-0000-0000-000000000000
  | "MAX" // ffffffff-ffff-ffff-ffff-ffffffffffff
  | "NCS" // 0xxx (0b0000 ~ 0b0111)
  | "RFC" // 10xx (0b1000 ~ 0b1011)
  | "MS" // 110x (0b1100 ~ 0b1101)
  | "RESERVED"; // 111x (0b1110 ~ 0b1111)

.version instance property =standard

The UUID version number if the UUID variant is "RFC"; otherwise, null.

.version: 1 | 2 | 3 | 4 | 5 | 6 | 7 | null;

.timestamp instance property =standard

The timestamp part of the UUID if the UUID variant is "RFC" and the version is v1, v6, or v7; otherwise, null. For convenience, all timestamps are calculated as milliseconds since the UNIX epoch.

.timestamp: number | null;

.toString() instance method >=encodable

Converts the Uuid object to a string usable in SurrealQL variables.

.valueOf() and .toJSON() return the same result as this method.

.toString(): string;

Arguments

None.

Return Value

Returns a hexadecimal UUID string.

Example

import { Uuid } from "@tai-kun/surrealdb/encodable-datatypes";


const bytes = new Uint8Array([
  0x26, 0xc8, 0x01, 0x63,
  0x3b, 0x83,
  0x48, 0x1b,
  0x93, 0xda,
  0xc4, 0x73, 0x94, 0x7c, 0xcc, 0xbc,
]);
const uuid = new Uuid(bytes);
console.log(uuid.toString());
//-> 26c80163-3b83-481b-93da-c473947cccbc

.toSurql() instance method >=encodable

Converts the Uuid object to a string that can be embedded in SurrealQL. Similar to .toString(), but adds a u prefix to tell the query parser that the string is a UUID.

.toSurql(): string;

Arguments

None.

Return Value

Returns a hexadecimal UUID string with a u prefix.

Example

import { Uuid } from "@tai-kun/surrealdb/encodable-datatypes";


const bytes = new Uint8Array([
  0x26, 0xc8, 0x01, 0x63,
  0x3b, 0x83,
  0x48, 0x1b,
  0x93, 0xda,
  0xc4, 0x73, 0x94, 0x7c, 0xcc, 0xbc,
]);
const uuid = new Uuid(bytes);
console.log(uuid.toSurql());
//-> u'26c80163-3b83-481b-93da-c473947cccbc'

.clone() instance method =standard

Clones the Uuid object.

.clone(): this;

Arguments

None.

Return Value

Returns a new Uuid object. If the Uuid class is inherited, an instance of that class is returned.

.compareTo() instance method =standard

Compares the timestamps of Uuid objects.

.compareTo(other: Uuid): -1 | 0 | 1;

Arguments

other

The UUID to compare against.

Return Value

Returns 0 if either UUID lacks a timestamp or if the timestamps are the same. Returns -1 if the comparison UUID has a later timestamp and 1 if it has an earlier timestamp.

Example

The following example compares the timestamps of different UUID versions and sorts them in ascending order:

import { Uuid } from "@tai-kun/surrealdb/standard-datatypes";


const uuidv1 = new Uuid("0e004000-2073-11ef-8451-eb2a011f8691");
const uuidv6 = new Uuid("1ef1fa9e-3968-6000-a77e-683eb1a35ebe");


console.log(new Date(uuidv1.timestamp).toISOString());
//-> 2024-06-02T00:00:00.000Z
console.log(new Date(uuidv6.timestamp).toISOString());
//-> 2024-06-01T00:00:00.000Z


const uuidList = [
  uuidv1,
  uuidv6,
];


uuidList.sort((a, b) => a.compareTo(b));


console.log(uuidList);
//-> [
//->   1ef1fa9e-3968-6000-a77e-683eb1a35ebe, (uuidv6)
//->   0e004000-2073-11ef-8451-eb2a011f8691, (uuidv1)
//-> ]

Further Development

Generic Determination of Uuid Objects

To determine if a value is a Uuid object without relying on presets, it is recommended to use the isUuid function. This function does not use instanceof, making it useful when the preset of the value being verified is unknown.

import { isUuid } from "@tai-kun/surrealdb";