Utilities methods

The JavaScript SDK provides some built-in utilities to work with responses.

Utilities overview

.jsonify()

In certain scenario’s, it’s useful to be able to get a JSON representation of returned data, when working with tools like GraphQL for example. For this, the JavaScript SDK publishes a jsonify() utility.

It takes in a value of type unknown, and converts it into a JSON representation in the same manner that SurrealDB would. The utility only affects SurrealQL values, leaving all other sort of classes, including derivatives of Objects, Arrays, Maps and Sets, untouched.

Additionally, it is fully type-safe, transforming only the types for SurrealQL values.

Signature
jsonify<T>(value: T): Jsonify<T>;

Example

jsonify({
    rid: new RecordId("person", "tobie"),
	dec: new Decimal("3.333333"),
	dur: new Duration("1d2h"),
	geo: new GeometryLine([
		new GeometryPoint([1, 2]),
		new GeometryPoint([3, 4]),
	]),

	tb: new Table("table_name"),
	uuid: new Uuid("92b84bde-39c8-4b4b-92f7-626096d6c4d9"),
	date: new Date("2024-05-06T17:44:57.085Z"),
	undef: undefined,
	null: null,
	num: 123,
	float: 123.456,
	true: true,
	false: false,
	string: "I am a string",
});

Output
{
    rid: "person:tobie",
    dec: "3.333333",
    dur: "1d2h",
    geo: {
        type: "GeometryLine",
        coordinates: [
            [1, 2],
            [2, 3],
        ],
    },
    tb: "table_name",
    uuid: "92b84bde-39c8-4b4b-92f7-626096d6c4d9",
    date: "2024-05-06T17:44:57.085Z",
    null: null,
    num: 123,
    float: 123.456,
    true: true,
    false: false,
    string: "I am a string"
}

PreparedQuery

A class containing a query and it’s bindings, which can be passed to the .query() method.

Note

The additional benefit of using this method over the .query() method is that it encodes the query and its variables into CBOR upfront, which can be helpful when writing large queries often.

Signature
new PreparedQuery(query: string, bindings: Record<string, unknown>)

Example

const query = new PreparedQuery(
    /* surql */ `CREATE person CONTENT $content`,
    { content: {} }
);

await surreal.query(query);

Gap

You can set a value to be a Gap instance to later set or override it when sending the query.

const name = new Gap<string>();
const enabled = new Gap(true);
const query = new PreparedQuery(
    /* surql */ `CREATE person SET name = $name, enabled = $enabled`,
    { name, enabled }
);

// All gaps without a default value must be passed
await surreal.query(
    query,
    [name.fill("John Doe")]
);

// You can also override gap default values
await surreal.query(
    query,
    [
        name.fill("John Doe"),
        enabled.fill(false),
    ]
);

Updating Record Links

Handling record links in queries can be tricky, as JavaScript’s default array syntax formats record links like in strings: ["person:tobie", "person:jamie"]. However, SurrealDB expects the input to be in this form: [person:tobie, person:jamie].

To simplify this process, you can use the PreparedQuery method, which allows you to map JavaScript strings to the appropriate SurrealDB record link format:

const people = ["person:tobie", "person:jamie"];

const query = new PreparedQuery(
  /* surql */`UPDATE person:john SET $content`,
  { content: { friends: people.map(p => new StringRecordId(p)) } }
);

This approach makes it easy to handle and update record links dynamically while adhering to SurrealDB’s expected syntax.

Tagged Template

A method allowing you to write a tagged template literal string, automatically escaping any variables passed. You can also use Gap instances like described above. Returns a PreparedQuery.

Note

Template literal strings in JavaScript only work with backticks, and not with single or double quoted strings.

Example

// Optionally, `surrealql` is an alias export of `surql`
import { surql, surrealql } from 'surrealdb';

const content = { name: "Tobie" };
const query = surql`CREATE person CONTENT ${content}`;
await surreal.query(query);

// Or use gaps
const name = new Gap("Tobie");
const query = surql`CREATE person CONTENT ${{ name }}`;
await surreal.query(query);
await surreal.query(
    query,
    // Or override a Gap's default value
    [name.fill("Jaime")]
);

String Prefixes

These methods are also based on tagged template literal strings, but they replicate SurrealQLs string prefixes in JS.

Note

Template literal strings in JavaScript only work with backticks, and not with single or double quoted strings.

Example

// Optionally, `surrealql` is an alias export of `surql`
import { s, d, r, u } from 'surrealdb';

const string = s`I am a string`;
const date = d`2024-05-06T17:44:57.085Z`;
const record = r`person:tobie`;
const uuid = u`92b84bde-39c8-4b4b-92f7-626096d6c4d9`;