跳转到内容
surrealdb.js

日期时间

Datetime 是用于表示日期和时间的类。它对应于 SurrealQL 的 datetime 类型。

导入

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

.constructor()

创建一个新的 Datetime 对象。

new Datetime(source: [number, number] | string); // decode-only, encodable
new Datetime(
  source?:
    | [number, number]
    | number
    | bigint
    | Date
    | Datetime
    | undefined,
); // standard
new Datetime(
  year: number,
  monthIndex: number,
  date?: number | undefined,
  hours?: number | undefined,
  minutes?: number | undefined,
  seconds?: number | undefined,
  milliseconds?: number | undefined,
  microseconds?: number | undefined,
  nanoseconds?: number | undefined,
); // standard

参数

source

秒数和纳秒数对，或字符串。如果预设为 standard，则还支持 Date 对象和 bigint 输入。

year, monthIndex, …

与 Date 类的参数相同。但它也支持 nanoseconds 输入。不能在提供 undefined 的参数之后提供 number。这与 Date 类的规范大致相同。

返回值

如果通过 new 调用，Datetime 将返回其实例。如果预设为 standard，它也是 Date 的实例。

.seconds 实例 属性 >=decode-only

纳秒精度时间的秒数部分。在 standard 以下的预设中，它是只读的。值是 -253-1 到 253-1 之间的整数或 NaN。

.seconds: number;

.nanoseconds 实例 属性 >=decode-only

纳秒精度时间的纳秒数部分。在 standard 以下的预设中，它是只读的。值是 0 到 999999999 之间的整数或 NaN。

.nanoseconds: number;

.valueOf() 实例 方法 >=encodable

获取毫秒精度的時間。

.valueOf(): number;

参数

无。

返回值

返回毫秒精度的時間。

例子

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


const date = new Datetime("2024-06-01T12:34:56.780123456Z");
console.log(date.valueOf());
//-> 1717245296780

.toString() 实例 方法 >=encodable

获取毫秒精度时间的字符串表示。与 Date 对象的 .toString() 相同。

.toString(): string;

参数

无。

返回值

返回毫秒精度时间的字符串表示。

例子

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


const date = new Datetime("2024-06-01T12:34:56.780123456Z");
console.log(date.toString());
//-> Sat Jun 01 2024 21:34:56 GMT+0900 (日本標準時)

.toISOString() 实例 方法 >=encodable

以 ISO 格式获取纳秒精度时间的字符串。与 Date 对象的 .toISOString() 类似，但由于它是纳秒精度，因此小数点后会显示到第九位。

.toISOString(): string;

参数

无。

返回值

以 ISO 格式返回纳秒精度时间的字符串。

例子

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


const date = new Datetime([1717245296, 780123456]);
console.log(date.toISOString());
//-> 2024-06-01T12:34:56.780123456Z

.toDate() 实例 方法 >=encodable

转换为运行时内置的 Date 对象。请注意，这将是毫秒精度。

.toDate(): Date;

参数

无。

返回值

返回运行时内置的 Date 对象。

.toSurql() 实例 方法 >=encodable

将 Datetime 对象转换为可以嵌入 SurrealQL 的字符串。它类似于 .toISOString()，但通过添加 d 前缀来告诉查询解析器该字符串是 UUID。

.toSurql(): string;

参数

无。

返回值

返回带有 d 前缀的 ISO 格式的日期时间。

例子

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


const date = new Datetime([1717245296, 780123456]);
console.log(date.toSurql());
//-> d'2024-06-01T12:34:56.780123456Z'

.getCompact() 实例 方法 =standard

获取秒数和纳秒数对。

.getCompact(): [seconds: number, nanoseconds: number];

参数

无。

返回值

返回秒数和纳秒数对。

.setCompact() 实例 方法 =standard

使用秒数和纳秒数对设置日期时间。

.setCompact(compact: [seconds: number, nanoseconds: number]): number;

参数

compact

秒数和纳秒数对。

返回值

返回毫秒精度的時間。

例子

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


const date = new Datetime(0);
const time = dt.setCompact([1717245296, 780123456]);
console.log(time);
//-> 1717245296780

.getMicroseconds() 实例 方法 =standard

使用本地时间获取日期的微秒数。

.getUTCMicroseconds() 与此方法的行为相同。

.getMicroseconds(): number;

参数

无。

返回值

返回微秒数。

例子

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


const date = new Datetime([1717245296, 780123456]);
console.log(date.toISOString());
//-> 2024-06-01T12:34:56.780123456Z
//                          ^^^
//                           |
//                       +---+
//                       v
console.log(date.getMicroseconds());
//-> 123

.setMicroseconds() 实例 方法 =standard

设置微秒数。

.setUTCMicroseconds() 与此方法的行为相同。

.setMicroseconds(us: number): number;

参数

us

要设置的微秒数。该值将被转换为整数。请注意，如果该值不在 0 到 999 之间，则整个时间都会受到影响。

返回值

返回毫秒精度的時間。

例子

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


const date = new Datetime([1717245296, 780123456]);
console.log(date.toISOString());
//-> 2024-06-01T12:34:56.780123456Z


const time = date.setMicroseconds(1_000);
console.log(date.toISOString());
//-> 2024-06-01T12:34:56.781000456Z
console.log(time);
//-> 1717245296781

.getNanoseconds() 实例 方法 =standard

使用本地时间获取日期的纳秒数。

.getUTCNanoseconds() 与此方法的行为相同。

.getNanoseconds(): number;

参数

无。

返回值

返回纳秒数。

例子

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


const date = new Datetime([1717245296, 780123456]);
console.log(date.toISOString());
//-> 2024-06-01T12:34:56.780123456Z
//                             ^^^
//                              |
//                      +-------+
//                      v
console.log(date.getNanoseconds());
//-> 456

.setNanoseconds() 实例 方法 =standard

设置纳秒数。

.setUTCNanoseconds() 与此方法的行为相同。

.setNanoseconds(us: number): number;

参数

us

要设置的纳秒数。该值将被转换为整数。请注意，如果该值不在 0 到 999 之间，则整个时间都会受到影响。

返回值

返回毫秒精度的時間。

例子

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


const date = new Datetime([1717245296, 780123456]);
console.log(date.toISOString());
//-> 2024-06-01T12:34:56.780123456Z


const time = date.setNanoseconds(-1);
console.log(date.toISOString());
//-> 2024-06-01T12:34:56.780122999Z
console.log(time);
//-> 1717245296780

.clone() 实例 方法 =standard

复制 Datetime 对象。

.clone(): this;

参数

无。

返回值

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

进阶

Datetime 对象的通用判断

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

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

早于 UNIX 纪元的时间

SurrealDB 的 datetime 类型可以精确到纳秒。因此，在 JavaScript 中处理它时需要小心。将 SurrealDB 序列化后的 datetime（例如 "1969-12-31T23:59:59.999999999Z"）传递给 JavaScript 的 Date.parse，在 WebKit 中将得到 0 毫秒，但在其他环境（Node.js、Deno、Bun、Chromium、Firefox）中将得到 -1 毫秒。

WebKit：

const date = new Date("1969-12-31T23:59:59.999999999Z");
console.log(date.getTime());
//-> 0

Node.js、Deno、Bun、Chromium、Firefox：

const date = new Date("1969-12-31T23:59:59.999999999Z");
console.log(date.getTime());
//-> -1