Datetime
The Datetime class represents dates and times. It corresponds to the SurrealQL datetime type.
Importing
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()
Creates a new Datetime object.
new Datetime(source: [number, number] | string); // decode-only, encodablenew Datetime( source?: | [number, number] | number | bigint | Date | Datetime | undefined,); // standardnew 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,); // standardArguments
source
A pair of seconds and nanoseconds, or a string. If the preset is standard, it also supports inputs such as Date objects and bigint.
year, monthIndex, …
These arguments are the same as those for the Date class. However, it also supports nanoseconds input. A number cannot be provided after an argument where undefined is provided. This is roughly the same specification as the Date class.
Return Value
When called via new, Datetime returns its instance. If the preset is standard, it is also a Date instance.
.seconds instance property >=decode-only
The seconds part of the nanosecond-precision time. Read-only for presets below standard. The value is an integer between -253-1 and 253-1, or NaN.
.seconds: number;.nanoseconds instance property >=decode-only
The nanoseconds part of the nanosecond-precision time. Read-only for presets below standard. The value is an integer between 0 and 999999999, or NaN.
.nanoseconds: number;.valueOf() instance method >=encodable
Gets the millisecond-precision time.
.valueOf(): number;Arguments
None.
Return Value
Returns the millisecond-precision time.
Example
import { Datetime } from "@tai-kun/surrealdb/encodable-datatypes";
const date = new Datetime("2024-06-01T12:34:56.780123456Z");console.log(date.valueOf());//-> 1717245296780.toString() instance method >=encodable
Gets the string representation of the millisecond-precision time. Same as the .toString() method of the Date object.
.toString(): string;Arguments
None.
Return Value
Returns the string representation of the millisecond-precision time.
Example
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 (Japan Standard Time).toISOString() instance method >=encodable
Gets the nanosecond-precision time string in ISO format. Similar to the .toISOString() method of the Date object, but with nanosecond precision (up to the ninth decimal place).
.toISOString(): string;Arguments
None.
Return Value
Returns the nanosecond-precision time string in ISO format.
Example
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() instance method >=encodable
Converts to a runtime-built-in Date object. Note that this results in millisecond precision.
.toDate(): Date;Arguments
None.
Return Value
Returns a runtime-built-in Date object.
.toSurql() instance method >=encodable
Converts the Datetime object into a string embeddable in SurrealQL. Similar to .toISOString(), but adds a d prefix to inform the query parser that the string is a datetime.
.toSurql(): string;Arguments
None.
Return Value
Returns the ISO-formatted datetime with a d prefix.
Example
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() instance method =standard
Gets the pair of seconds and nanoseconds.
.getCompact(): [seconds: number, nanoseconds: number];Arguments
None.
Return Value
Returns a pair of seconds and nanoseconds.
.setCompact() instance method =standard
Sets the date and time with a pair of seconds and nanoseconds.
.setCompact(compact: [seconds: number, nanoseconds: number]): number;Arguments
compact
A pair of seconds and nanoseconds.
Return Value
Returns the millisecond-precision time.
Example
import { Datetime } from "@tai-kun/surrealdb/standard-datatypes";
const date = new Datetime(0);const time = date.setCompact([1717245296, 780123456]);console.log(time);//-> 1717245296780.getMicroseconds() instance method =standard
Gets the microseconds of the date using the local time.
.getUTCMicroseconds() behaves the same as this method.
.getMicroseconds(): number;Arguments
None.
Return Value
Returns the microseconds.
Example
import { Datetime } from "@tai-kun/surrealdb/standard-datatypes";
const date = new Datetime([1717245296, 780123456]);console.log(date.toISOString());//-> 2024-06-01T12:34:56.780123456Z// ^^^// |// +---+// vconsole.log(date.getMicroseconds());//-> 780.setMicroseconds() instance method =standard
Sets the microseconds.
.setUTCMicroseconds() behaves the same as this method.
.setMicroseconds(us: number): number;Arguments
us
The microseconds to set. The value is converted to an integer. Note that if the value is not between 0 and 999, the entire time will be affected.
Return Value
Returns the millisecond-precision time.
Example
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(1000);console.log(date.toISOString());//-> 2024-06-01T12:34:57.000123456Zconsole.log(time);//-> 1717245300123.getNanoseconds() instance method =standard
Gets the nanoseconds of the date using the local time.
.getUTCNanoseconds() behaves the same as this method.
.getNanoseconds(): number;Arguments
None.
Return Value
Returns the nanoseconds.
Example
import { Datetime } from "@tai-kun/surrealdb/standard-datatypes";
const date = new Datetime([1717245296, 780123456]);console.log(date.toISOString());//-> 2024-06-01T12:34:56.780123456Z// ^^^// |// +-------+// vconsole.log(date.getNanoseconds());//-> 456.setNanoseconds() instance method =standard
Sets the nanoseconds.
.setUTCNanoseconds() behaves the same as this method.
.setNanoseconds(ns: number): number;Arguments
ns
The nanoseconds to set. The value is converted to an integer. Note that if the value is not between 0 and 999,999,999, the entire time will be affected.
Return Value
Returns the millisecond-precision time.
Example
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(1000000000);console.log(date.toISOString());//-> 2024-06-01T12:34:57.000123456Zconsole.log(time);//-> 1717245300123.clone() instance method =standard
Clones the Datetime object.
.clone(): this;Arguments
None.
Return Value
Returns a new Datetime object. If inheriting the Datetime class, an instance of that class is returned.
Advanced Usage
Generic Datetime Object Check
To check if a value is a Datetime object regardless of the preset, it is recommended to use the isDatetime function. This function does not use instanceof, so it is useful when the preset of the value to be checked is unknown.
import { isDatetime } from "@tai-kun/surrealdb";Dates Before the UNIX Epoch
The SurrealDB datetime type can store nanosecond precision. Therefore, care must be taken when handling it in JavaScript. When passing a SurrealDB serialized datetime, for example "1969-12-31T23:59:59.999999999Z", to JavaScript’s Date.parse, WebKit will return 0 milliseconds, while others (Node.js, Deno, Bun, Chromium, Firefox) will return -1 milliseconds.
WebKit:
const date = new Date("1969-12-31T23:59:59.999999999Z");console.log(date.getTime());//-> 0Node.js, Deno, Bun, Chromium, Firefox:
const date = new Date("1969-12-31T23:59:59.999999999Z");console.log(date.getTime());//-> -1