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 |
| |
Number | Native |
| |
Float | Native |
| |
Bool | Native |
| |
Null | Native |
| |
None | Translated to |
| |
Array | Native |
| |
Object | Native |
| |
Datetime | Native |
| |
Binary | Native |
| |
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.
Signaturenew 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
Simplenew RecordId('table', 123).toString();
// 'table:123'
new RecordId('table', 'abc').toString();
// 'table:abc'
Complex charactersnew 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 Arraysnew 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.
Signaturenew 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.
Signaturenew 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
SignatureGeometry.toJSON()
Exampleconst 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
SignatureGeometry.is(geometry: Geometry)
Exampleconst 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.
SignatureGeometry.clone()
Properties
.coordinates
A getter property, representing the coordinates as shown in GeoJSON format for X Geometry
SignatureGeometry.coordinates
Derivatives
GeometryPoint
A point in space, made up of a lat and lon coordinate, automatically converted to a float.
Signaturenew GeometryPoint([lat: number | Decimal, lon: number | Decimal]);
GeometryLine
A line, made up of two or more points
Signaturenew 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.
Signaturenew GeometryPolygon([GeometryLine, ...GeometryLine[]]);
GeometryMultiPoint
A collection of one or more points
Signaturenew GeometryMultiPoint([GeometryPoint, ...GeometryPoint[]]);
GeometryMultiLine
A collection of one or more lines
Signaturenew GeometryMultiLine([GeometryLine, ...GeometryLine[]]);
GeometryMultiPolygon
A collection of one or more polygons
Signaturenew GeometryMultiPolygon([GeometryPolygon, ...GeometryPolygon[]]);
GeometryCollection
A collection of one or more Geometry
derivatives
Signaturenew 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.
Signaturenew 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.
Signaturenew 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"