跳转到内容
surrealdb.js

UUID

UUID（Universally Unique Identifier）是用于唯一标识特定实体的128位标识符。Uuid类用于表示UUID，支持UUID v1到v7。需要注意的是，生成UUID需要使用单独的库或运行时中内置的功能（例如node:crypto）。

导入

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()

创建一个新的Uuid对象。

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

参数

source

UUID的字节数组表示，或对于standard预设来说是字符串。

返回值

如果通过new调用，Uuid将返回其实例。

.bytes 实例 属性 >=decode-only

UUID的字节数组。

.bytes: Uint8Array;

.variant 实例 属性 =standard

UUID的变体。它由UUID的第13位的上位比特定义，包含三个主要变体和一个为将来保留的变体。

  1. NCS兼容
    • 0b0xxx
    • 表示UUID与NCS（Network Computing System）兼容。
    • 并不常用。
  2. RFC 4122兼容
    • 0b10xx
    • 基于RFC 4122（UUID标准规范）的UUID。
    • 是最常用的UUID格式，包括v1（基于时间）和v4（随机）等格式。
  3. Microsoft GUID兼容
    • 0b110x
    • Microsoft使用的GUID（Globally Unique Identifier）格式。
  4. 为将来保留
    • 0b111x

此属性除了上述变体外，还表示NIL UUID和MAX UUID。

.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 实例 属性 =standard

如果UUID的变体为"RFC"，则表示UUID版本号；否则为null。

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

.timestamp 实例 属性 =standard

如果UUID的变体为"RFC"且版本为v1、v6或v7，则表示时间戳部分；否则为null。为方便起见，所有时间戳都计算为自UNIX纪元以来的毫秒数。

.timestamp: number | null;

.toString() 实例 方法 >=encodable

将Uuid对象转换为SurrealQL变量中可用的字符串。

.valueOf()和.toJSON()方法返回的结果与该方法相同。

.toString(): string;

参数

无。

返回值

返回一个十六进制的UUID字符串。

示例

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() 实例 方法 >=encodable

将Uuid对象转换为可嵌入SurrealQL的字符串。与.toString()类似，但通过添加u前缀来告知查询解析器该字符串是UUID。

.toSurql(): string;

参数

无。

返回值

返回一个带有u前缀的十六进制UUID字符串。

示例

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() 实例 方法 =standard

复制Uuid对象。

.clone(): this;

参数

无。

返回值

返回一个新的Uuid对象。如果继承了Uuid类，则返回该类的实例。

.compareTo() 实例 方法 =standard

比较Uuid对象的时间戳。

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

参数

other

用于比较的UUID。

返回值

如果任一方没有时间戳部分或时间戳相同，则返回0。如果比较对象的UUID时间戳更靠后，则返回-1；如果更靠前，则返回1。

示例

下面的例子比较了不同UUID版本的timestamp，并按升序排序:

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)
//-> ]

进阶

Uuid对象的通用判断

建议使用isUuid函数来判断值是否为Uuid对象，而无需依赖预设。此函数不使用instanceof，因此在验证值的预设未知时非常有用。

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