Utilities
The JavaScript SDK provides some built-in utilities to work with responses.
Utilities overview
| Utility | Description | |
|---|---|---|
Convert a response into a type-preserving JSON representation, in the same manner as SurrealDB would. | ||
A class containing a query and it's variables, which can be passed to the | ||
A method allowing you to write a tagged template string, automatically escaping any variables passed. | ||
.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.
Signaturejsonify<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.
Signaturenew 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),
]
);
Tagged Template
A method allowing you to write a tagged template string, automatically escaping any variables passed. You can also use Gap instances like described above. Returns a PreparedQuery.
Example
// Optionally, `surrealql` is an alias export of `surql`
import { surql, surrealql } from 'surrealdb.js';
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")]
);