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.
Datatype | Kind | Documentation | |
---|---|---|---|
String | Native |
| |
Number | Native |
| |
Float | Native |
| |
Bool | Native |
| |
Null | Native |
| |
None | Translated to |
| |
Array | Native |
| |
Object | Native |
| |
Datetime | Native |
| |
Binary | Native |
| |
Uuid | Custom | Uuid | |
Duration | Custom | Duration | |
Geometry | Custom | Geometry | |
Decimal | Custom | Decimal | |
Table | Custom | Table | |
RecordId | Custom | RecordId |
Uuid
When you receive a uuid from SurrealDB, it will always be represented as a Uuid
class.
Signaturenew Uuid(uuid: string | ArrayBuffer | Uint8Array | Uuid)
Uuid
const uuid = new Uuid("159408af-2c23-4ac6-944d-75c3ed09e038");
Uuid
const v4 = Uuid.v4(); const v7 = Uuid.v7();
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)
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);
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.
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()
.coordinates
A getter property, representing the coordinates as shown in GeoJSON format for X Geometry
SignatureGeometry.coordinates
GeometryPoint
A point in space, made up of a long and lat coordinate, automatically converted to a float.
Signaturenew GeometryPoint([long: number | Decimal, lat: 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);
const decimal = new Decimal("123.456"); decimal.toString(); // "123.456"
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);
const table = new Table("table"); table.toString(); // "table"
A Table
will be represented as a string in JSON
const table = new Table("table"); table.toJSON(); // "table" JSON.stringify(table); // "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)
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
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"]'
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 StringRecordId
, allowing the server to handle the parsing.
new StringRecordId("person:john");