Future

The Future class represents SurrealDB’s Futures feature.

Import

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

.constructor()

Creates a new Future object.

new Future(source: string);

Arguments

source

The value or expression within the future block.

Return Value

When called via new, Future returns its instance.

.block instance property >=decode-only

The value or expression within the future block.

.block: number;

.toString() instance method >=encodable

Converts the Future object into a string representation.

.toString(): string;

Arguments

None.

Return Value

Returns the value or expression within the future block.

Example

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

const future = new Future(`time::now()`);
console.log(future.toString());
//-> time::now()

.toSurql() instance method >=encodable

Converts the Future object into a string embeddable in SurrealQL. Similar to .toString(), but the block is enclosed in curly braces ({}) and cast with <future>.

.toSurql(): string;

Arguments

None.

Return Value

Returns a future embeddable in SurrealQL.

Example

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

const future = new Future(`time::now()`);
console.log(future.toSurql());
//-> <future>{time::now()}

.surql() static method =standard

This method assists in writing SurrealQL. It allows writing SurrealQL using template literals. Values embedded within the template literal are automatically converted to SurrealQL. If you have the official SurrealDB extension installed in VSCode, syntax highlighting for template literals will be enabled.

.surql(texts: TemplateStringsArray, ...values: unknown[]): string;

Arguments

texts

An array of strings that constitute the template literal.

values

Values to be embedded between each element of texts.

Return Value

A SurrealQL string.

Example

import { Future, Thing } from "@tai-kun/surrealdb/standard-datatypes";

const foo = "foo";
const rid = new Thing("person", "tai-kun");
const future = new Future(Future.surql`
  LET $a = ${foo} + ${Future.raw("'-'")};
  LET $b = type::string(${rid});
  string::concat($a, $b)
`);
console.log(future.toSurql());
//-> <future>{
//->   LET $a = 'foo' + '-';
//->   LET $b = type::string(r'person:⟨tai-kun⟩');
//->   string::concat($a, $b)
//-> }

Without using .surql(), the above example would be:

import { Future, Thing } from "@tai-kun/surrealdb/standard-datatypes";
import { toSurql } from "@tai-kun/surrealdb/utils";

const foo = "foo";
const rid = new Thing("person", "tai-kun");
const future = new Future(/*surql*/ `
  LET $a = ${toSurql(foo)} + ${"'-'"};
  LET $b = type::string(${rid.toSurql()});
  string::concat($a, $b)
`);
console.log(future.toSurql());
//-> <future>{
//->   LET $a = 'foo' + '-';
//->   LET $b = type::string(r'person:⟨tai-kun⟩');
//->   string::concat($a, $b)
//-> }

• Strings and objects need to be converted to SurrealQL using the toSurql helper function or the .toSurql() method.
• Strings can be embedded into SurrealQL without using Future.raw.

Advanced

Generic Future Object Determination

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

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