Data Types

The JavaScript SDK translates all datatypes native to SurrealQL into either datatypes native to JavaScript, or a custom implementation. This document describes all datatypes, and links to their respective documentation.

Data Types overview

Datatype	Kind	Documentation
String	Native	String on MDN
Number	Native	Number on MDN
Float	Native	Number on MDN
Bool	Native	Boolean on MDN
Null	Native	null on MDN
None	Translated to undefined	undefined on MDN
Array	Native	Array on MDN
Object	Native	Object on MDN
Datetime	Native	Date on MDN
Binary	Native	ArrayBuffer on MDN
RecordId	Custom	RecordId
Uuid	Custom	Uuid
Duration	Custom	Duration
Geometry	Custom	Geometry
Decimal	Custom	Decimal
Table	Custom	Table

RecordId

When you receive a RecordId back from SurrealDB, it will always be represented as a RecordId. The class holds tb and id fields, representing the table name, and a unique identifier for the record on that table. A RecordId can be converted into a string, and will be represented as such when it's converted to JSON.

Signature
new RecordId<Tb extends string>(tb: Tb, id: RecordIdValue)

Working with a RecordId

Constructing
// table is "person"
// unique identifier on the table is "john"
const rid = new RecordId("person", "john");

Extracting data
// Simple
const rid = new RecordId("person", "john");
rid.tb // "person"
rid.id // "john"

// Complex
const rid = new RecordId("recording", { city: "London", data: 123 });
rid.id      // { city: "London", data: 123 }
rid.id.city // "London"
rid.id.data // 123

Convert to String

The JS SDK flawlessly and efficiently handles escaping the TB and ID parts in Record Id's into their string counterparts. Below are some examples

Simple
new RecordId('table', 123).toString();
// 'table:123'
new RecordId('table', 'abc').toString();
// 'table:abc'

Complex characters
new RecordId('table', '123').toString();
// 'table:⟨123⟩'
new RecordId('table', '123withletters').toString();
// 'table:123withletters'
new RecordId('table', 'complex-string').toString();
// 'table:⟨complex-string⟩'
new RecordId('table-name', 123).toString();
// '⟨table-name⟩:123'

Objects and Arrays
new RecordId('table', { city: "London" }).toString();
// 'table:{ city: "London" }'
new RecordId('table', ["London"]).toString();
// 'table:["London"]'

Send back string

If you need to send back a Record Id in string format, you can do so with the StringRecordId class.

We do not implement the parsing of Record Ids in the JS SDK, as that would mean that we need to be able to parse any SurrealQL value, which comes with a cost. Instead you can send it over as a string with StrignRecordId, allowing the server to handle the parsing.

new StringRecordId("person:john");

Uuid

When you receive a uuid from SurrealDB, it will always be represented as a Uuid class.

Signature
new Uuid(uuid: string | ArrayBuffer | Uint8Array | Uuid)

Create a Uuid

const uuid = new Uuid("159408af-2c23-4ac6-944d-75c3ed09e038");

Generating a Uuid

const v4 = Uuid.v4();
const v7 = Uuid.v7();

Convert to String or Binary

Uuid.v4().toString();
Uuid.v4().toUint8Array();
Uuid.v4().toArrayBuffer();

Duration

When you receive a duration from SurrealDB, it will always be represented as a Duration class.

Signature
new Duration(duration: string | number)

Create a Duration

// Parsed from a duration string
const dur = new Duration("1w2d");
// Input milliseconds
const dur = new Duration(1000);
// From a compact format ([ms, ns])
const dur = new Duration([10000, 300]);

// By a unit amount
const dur = Duration.nanoseconds(1000);
const dur = Duration.microseconds(1000);
const dur = Duration.milliseconds(1000);
const dur = Duration.seconds(1000);
const dur = Duration.minutes(1000);
const dur = Duration.hours(1000);
const dur = Duration.days(1000);
const dur = Duration.weeks(1000);

Transform a Duration

const dur = new Duration("7d");

// Format as string, always as small as possible
dur.toString();     // 1w
// Get inner (float) milliseconds
dur._milliseconds;  // 604800000
// Get compact format
dur.toCompact();    // [604800]

// How many of a full unit fit into the duration
dur.nanoseconds;    // 604800000000000
dur.microseconds;   // 604800000000
dur.milliseconds;   // 604800000
dur.seconds;        // 604800
dur.minutes;        // 10080
dur.hours;          // 168
dur.days;           // 7
dur.weeks;          // 1

Geometry

When I Geometry is sent back from SurrealDB, be it a Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon or Collection, it will be represented as a derivative of the Geometry class.

Methods

Below, are all the methods implemented across all geometry derivatives.

.toJSON()

Used to convert a geometry to a GeoJSON representation

Signature
Geometry.toJSON()

Example
const line = new GeometryLine([
    new GeometryPoint([1, 2]),
    new GeometryPoint([3, 4]),
]);

line.toJSON();          // { type: "LineString", coordinates: [ [1, 2], [3, 4] ] }
JSON.stringify(line);   // '{ type: "LineString", coordinates: [ [1, 2], [3, 4] ] }'

.is()

Used to convert a check if geometry X is exactly equal to geometry Y

Signature
Geometry.is(geometry: Geometry)

Example
const point1 = new GeometryPoint([1, 2]);
const point2 = new GeometryPoint([3, 4]);
const line = new GeometryLine([point1, point2]);

point1.is(point1);      // true
point1.is(point2);      // false
point1.is(line);        // false

// Checks the inner values, does not need to be the same instance
const duplicate = new GeometryPoint([1, 2]);
point1.is(duplicate);   // true

.clone()

Used to deeply clone a geometry. Creates a new replica of the original instance, but changing the new instance won't affect the other.

Signature
Geometry.clone()

Properties

.coordinates

A getter property, representing the coordinates as shown in GeoJSON format for X Geometry

Signature
Geometry.coordinates

Derivatives

GeometryPoint

A point in space, made up of a lat and lon coordinate, automatically converted to a float.

Signature
new GeometryPoint([lat: number | Decimal, lon: number | Decimal]);

GeometryLine

A line, made up of two or more points

Signature
new GeometryLine([GeometryPoint, GeometryPoint, ...GeometryPoint[]]);

GeometryPolygon

A polygon, made up of self-closing lines

Note: The lines inside the polygon will automatically be closed if not already, meaning that the last point will be the same as the first.

Signature
new GeometryPolygon([GeometryLine, ...GeometryLine[]]);

GeometryMultiPoint

A collection of one or more points

Signature
new GeometryMultiPoint([GeometryPoint, ...GeometryPoint[]]);

GeometryMultiLine

A collection of one or more lines

Signature
new GeometryMultiLine([GeometryLine, ...GeometryLine[]]);

GeometryMultiPolygon

A collection of one or more polygons

Signature
new GeometryMultiPolygon([GeometryPolygon, ...GeometryPolygon[]]);

GeometryCollection

A collection of one or more Geometry derivatives

Signature
new GeometryCollection([Geometry, ...Geometry[]]);

Decimal

Because Javascript does not support Decimals natively, our SDK represents them in a Decimal class as a string. This means if you want to work with Decimals, you will need to use an external library for this.

Signature
new Decimal(decimal: string | number | Decimal);

Converting to string

const decimal = new Decimal("123.456");
decimal.toString(); // "123.456"

Converting to JSON

A Decimal will be represented as a string in JSON to perserve accuracy

const decimal = new Decimal("123.456");
decimal.toJSON();        // "123.456"
JSON.stringify(decimal); // "123.456"

Table

When you get a table name sent back from SurrealDB, it will be represented as a Table class.

Signature
new Table(table: string);

Converting to string

const table = new Table("table");
table.toString();    // "table"

Converting to JSON

A Table will be represented as a string in JSON

const table = new Table("table");
table.toJSON();        // "table"
JSON.stringify(table); // "table"

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.