edgedb-js automatically converts EdgeDB types to the corresponding JavaScript types and vice versa.

The table below shows the correspondence between EdgeDB and JavaScript types.

EdgeDB Type

JavaScript Type

Set

Array

array<anytype>

Array

anytuple

Array or Array-like object

anyenum

string

Object

object

bool

boolean

bytes

Buffer

str

string

local_date

LocalDate()

local_time

LocalTime()

local_datetime

LocalDateTime()

datetime

Date

duration

Duration()

float32, float64 int16, int32, int64

number

bigint

BigInt

decimal

n/a

json

string

uuid

edgedb.UUID

Inexact single-precision float values may have a different representation when decoded into a JavaScript number. This is inherent to the implementation of limited-precision floating point types. If you need the decimal representation to match, cast the expression to float64 in your query.

Due to precision limitations the decimal type cannot be decoded to a JavaScript number. Use an explicit cast to float64 if the precision degradation is acceptable or a cast to str for an exact decimal representation.

class
Set
Set extends Array

Under the hood, the result of the .query method is an instance of edgedb.Set. This class represents a set of values returned by a query. If the query contained an explicit ORDER BY clause, the values will be ordered, otherwise no specific ordering is guaranteed.

This type also allows to differentiate between a set of values and an explicit array.

Copy
const result = await conn.query(`SELECT {0, 1, 2};`);
result instanceof edgedb.Set; // true
result[0]; // 0
result[1]; // 1
result[2]; // 2

EdgeDB array maps onto the JavaScript Array.

Copy
// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const conn = await edgedb.connect({
    dsn: "edgedb://edgedb@localhost/"
  });

  try {
    let data = await conn.querySingle("SELECT [1, 2, 3]");

    // The result is an Array.
    assert(data instanceof Array);
    assert(typeof data[0] === "number");
    assert(data.length === 3);
    assert(data[2] === 3);
  } finally {
    conn.close();
  }
}

main();

Object represents an object instance returned from a query. The value of an object property or a link can be accessed through a corresponding object key:

Copy
// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const conn = await edgedb.connect({
    dsn: "edgedb://edgedb@localhost/"
  });

  try {
    let data = await conn.querySingle(`
      SELECT schema::Property {
          name,
          annotations: {name, @value}
      }
      FILTER .name = 'listen_port'
          AND .source.name = 'cfg::Config'
      LIMIT 1
    `);

    // The property 'name' is accessible.
    assert(typeof data.name === "string");
    // The link 'annotaions' is accessible and is a Set.
    assert(typeof data.annotations === "object");
    assert(data.annotations instanceof edgedb.Set);
    // The Set of 'annotations' is array-like.
    assert(data.annotations.length > 0);
    assert(data.annotations[0].name === "cfg::system");
    assert(data.annotations[0]["@value"] === "true");
  } finally {
    conn.close();
  }
}

main();

A regular EdgeDB tuple becomes an Array in JavaScript.

Copy
// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const conn = await edgedb.connect({
    dsn: "edgedb://edgedb@localhost/"
  });

  try {
    let data = await conn.querySingle(`
      SELECT (1, 'a', [3])
    `);

    // The resulting tuple is an Array.
    assert(data instanceof Array);
    assert(data.length === 3);
    assert(typeof data[0] === "number");
    assert(typeof data[1] === "string");
    assert(data[2] instanceof Array);
  } finally {
    conn.close();
  }
}

main();

A named EdgeDB tuple becomes an Array-like object in JavaScript, where the elements are accessible either by their names or indexes.

Copy
// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const conn = await edgedb.connect({
    dsn: "edgedb://edgedb@localhost/"
  });

  try {
    let data = await conn.querySingle(`
      SELECT (a := 1, b := 'a', c := [3])
    `);

    // The resulting tuple is an Array.
    assert(data instanceof Array);
    assert(data.length === 3);
    assert(typeof data[0] === "number");
    assert(typeof data[1] === "string");
    assert(data[2] instanceof Array);
    // Elements can be accessed by their names.
    assert(typeof data.a === "number");
    assert(typeof data["b"] === "string");
    assert(data.c instanceof Array);
  } finally {
    conn.close();
  }
}

main();
class
LocalDate
LocalDate(year: number, month: number, day: number)

A JavaScript representation of an EdgeDB local_date value. Implements a subset of the TC39 Temporal Proposal PlainDate type.

Assumes the calendar is always ISO 8601.

attribute
LocalDate.year
LocalDate.year: number

The year value of the local date.

attribute
LocalDate.month
LocalDate.month: number

The numerical month value of the local date.

Unlike the JS Date object, months in LocalDate start at 1. ie. Jan = 1, Feb = 2, etc.

attribute
LocalDate.day
LocalDate.day: number

The day of the month value of the local date (starting with 1).

attribute
LocalDate.dayOfWeek
LocalDate.dayOfWeek: number

The weekday number of the local date. Returns a value between 1 and 7 inclusive, where 1 = Monday and 7 = Sunday.

attribute
LocalDate.dayOfYear
LocalDate.dayOfYear: number

The ordinal day of the year of the local date. Returns a value between 1 and 365 (or 366 in a leap year).

attribute
LocalDate.weekOfYear
LocalDate.weekOfYear: number

The ISO week number of the local date. Returns a value between 1 and 53, where ISO week 1 is defined as the week containing the first Thursday of the year.

attribute
LocalDate.daysInWeek
LocalDate.daysInWeek: number

The number of days in the week of the local date. Always returns 7.

attribute
LocalDate.daysInMonth
LocalDate.daysInMonth: number

The number of days in the month of the local date. Returns a value between 28 and 31 inclusive.

attribute
LocalDate.daysInYear
LocalDate.daysInYear: number

The number of days in the year of the local date. Returns either 365 or 366 if the year is a leap year.

attribute
LocalDate.monthsInYear
LocalDate.monthsInYear: number

The number of months in the year of the local date. Always returns 12.

attribute
LocalDate.inLeapYear
LocalDate.inLeapYear: boolean

Return whether the year of the local date is a leap year.

method
LocalDate.toString()
LocalDate.toString(): string

Get the string representation of the LocalDate in the YYYY-MM-DD format.

method
LocalDate.toJSON()
LocalDate.toJSON(): number

Same as toString().

method
LocalDate.valueOf()
LocalDate.valueOf(): never

Always throws an Error. LocalDate objects are not comparable.

class
LocalTime
LocalTime(hour: number = 0, minute: number = 0, second: number = 0, millisecond: number = 0, microsecond: number = 0, nanosecond: number = 0)

A JavaScript representation of an EdgeDB local_time value. Implements a subset of the TC39 Temporal Proposal PlainTime type.

The EdgeDB local_time type only has microsecond precision, any nanoseconds specified in the LocalTime will be ignored when encoding to an EdgeDB local_time.

attribute
LocalTime.hour
LocalTime.hour: number

The hours component of the local time in 0-23 range.

attribute
LocalTime.minute
LocalTime.minute: number

The minutes component of the local time in 0-59 range.

attribute
LocalTime.second
LocalTime.second: number

The seconds component of the local time in 0-59 range.

attribute
LocalTime.millisecond
LocalTime.millisecond: number

The millisecond component of the local time in 0-999 range.

attribute
LocalTime.microsecond
LocalTime.microsecond: number

The microsecond component of the local time in 0-999 range.

attribute
LocalTime.nanosecond
LocalTime.nanosecond: number

The nanosecond component of the local time in 0-999 range.

method
LocalTime.toString()
LocalTime.toString(): string

Get the string representation of the local_time in the HH:MM:SS 24-hour format.

method
LocalTime.toJSON()
LocalTime.toJSON(): number

Same as toString().

method
LocalTime.valueOf()
LocalTime.valueOf(): never

Always throws an Error. LocalTime objects are not comparable.

class
LocalDateTime
LocalDateTime(year: number, month: number, day: number, hour: number = 0, minute: number = 0, second: number = 0, millisecond: number = 0, microsecond: number = 0, nanosecond: number = 0) extends LocalDate, LocalTime

A JavaScript representation of an EdgeDB local_datetime value. Implements a subset of the TC39 Temporal Proposal PlainDateTime type.

Inherits all properties from the LocalDate() and LocalTime() types.

method
LocalDateTime.toString()
LocalDateTime.toString(): string

Get the string representation of the local_datetime in the YYYY-MM-DDTHH:MM:SS 24-hour format.

method
LocalDateTime.toJSON()
LocalDateTime.toJSON(): number

Same as toString().

method
LocalDateTime.valueOf()
LocalDateTime.valueOf(): never

Always throws an Error. LocalDateTime objects are not comparable.

class
Duration
Duration(years: number = 0, months: number = 0, weeks: number = 0, days: number = 0, hours: number = 0, minutes: number = 0, seconds: number = 0, milliseconds: number = 0, microseconds: number = 0, nanoseconds: number = 0)

A JavaScript representation of an EdgeDB duration value. Implements a subset of the TC39 Temporal Proposal Duration type.

No arguments may be infinite and all must have the same sign. Any non-integer arguments will be rounded towards zero.

The Temporal Duration type can contain both absolute duration components, such as hours, minutes, seconds, etc. and relative duration components, such as years, months, weeks, and days, where their absolute duration changes depending on the exact date they are relative to (eg. different months have a different number of days).

The EdgeDB duration type only supports absolute durations, so any Duration with non-zero years, months, weeks, or days will throw an error when trying to encode them.

The EdgeDB duration type only has microsecond precision, any nanoseconds specified in the Duration will be ignored when encoding to an EdgeDB duration.

Temporal Duration objects can be unbalanced, (ie. have a greater value in any property than it would naturally have, eg. have a seconds property greater than 59), but EdgeDB duration objects are always balanced.

Therefore in a round-trip of a Duration object to EdgeDB and back, the returned object, while being an equivalent duration, may not have exactly the same property values as the sent object.

attribute
Duration.years
Duration.years: number

The number of years in the duration.

attribute
Duration.months
Duration.months: number

The number of months in the duration.

attribute
Duration.weeks
Duration.weeks: number

The number of weeks in the duration.

attribute
Duration.days
Duration.days: number

The number of days in the duration.

attribute
Duration.hours
Duration.hours: number

The number of hours in the duration.

attribute
Duration.minutes
Duration.minutes: number

The number of minutes in the duration.

attribute
Duration.seconds
Duration.seconds: number

The number of seconds in the duration.

attribute
Duration.milliseconds
Duration.milliseconds: number

The number of milliseconds in the duration.

attribute
Duration.microseconds
Duration.microseconds: number

The number of microseconds in the duration.

attribute
Duration.nanoseconds
Duration.nanoseconds: number

The number of nanoseconds in the duration.

attribute
Duration.sign
Duration.sign: number

Returns -1, 0, or 1 depending on whether the duration is negative, zero or positive.

attribute
Duration.blank
Duration.blank: boolean

Returns true if the duration is zero.

method
Duration.toString()
Duration.toString(): string

Get the string representation of the duration in ISO 8601 duration format.

method
Duration.toJSON()
Duration.toJSON(): number

Same as toString().

method
Duration.valueOf()
Duration.valueOf(): never

Always throws an Error. Duration objects are not comparable.

Light
Dark
System