v1.0.0

This is the v1.0 release for the edgedb-js client library. It is accompanied by the introduction of a new package @edgedb/generate which contains a set of code generation tools, including the EdgeQL query builder.

Try the beta

$ npm install edgedb@beta
$ npm install -D @edgedb/generate@beta

$ yarn add edgedb@beta
$ yarn add -D @edgedb/generate@beta

Breaking changes

New generation command

To generate the query builder, you should separately install @edgedb/generate.

$ npm install -D @edgedb/generate@beta
$ yarn add -D @edgedb/generate@beta

Then generate the query builder with the following command.

$ npx @edgedb/generate edgeql-js
# Deno users
$ deno run --allow-all --unstable https://deno.land/x/edgedb/generate.ts edgeql-js

The command still accepts the same set of flags.

Cardinality inference and filter_single

When selecting a single object, use the new filter_single key. This indicates to the query builder that a given query returns a single object.

  const query = e.select(e.Movie, (m)=>({
    title: true,
-   filter: e.op(m.id, '=', e.uuid('0e874596-b9b2-4ca1-a72e-4088fbee3b34'))
+   filter_single: e.op(m.id, '=', e.uuid('0e874596-b9b2-4ca1-a72e-4088fbee3b34'))
  }));

Previously, the query builder tried to infer whether or not a query was selecting a single item by inspecting the expressed passed to filter. Ultimately this was too verbose, caused performance issues, and didn't work in all cases (e.g. composite constraints like constraint exclusive on ((.title, .release_year))).

// OLD SYNTAX
const query = e.select(e.Movie, (m)=>({
  title: true,
  filter: e.op(m.id, '=', e.uuid('0e874596-b9b2-4ca1-a72e-4088fbee3b34'))
}));

await query.run(client);
// { title: string } | null 

Simplified filter_single syntax

The filter_single key also supports a simplified syntax that eliminates the need for e.op:

  const query = e.select(e.Movie, (m)=>({
    title: true,
-   filter: e.op(m.id, '=', e.uuid('0e874596-b9b2-4ca1-a72e-4088fbee3b34'))
+   filter_single: {id, '0e874596-b9b2-4ca1-a72e-4088fbee3b34'}
  }));
  
  await query.run(client);
  // {title: string} | null

This works for composite constraints as well.

const query = e.select(e.Movie, (m)=>({
  title: true,
  filter_single: {title: "The Avengers", release_year: 2012}
}));

This simplified "object filter" syntax only works on filter_single, not plain filter!

Interfaces are now their own generator

Previously the query builder would generate a set of interfaces representing your schema. This has now been split into its own generator. Run this generator with the following command.

$ npx @edgedb/generate interfaces

This will generate dbschema/interfaces.ts by default.

- import e, {Movie} from "./dbschema/edgeql-js"
+ import e from "./dbschema/edgeql-js"
+ import {Movie} from "./dbschema/interfaces"

Full documentation

Buffer -> UInt8Array

The client library no longer decodes bytes to the Node.js-specific Buffer class. Instead, we use the runtime-agnostic Uint8Array. This is part of a larger effort to make the client library run in non-Node.js evironments like Deno and Cloudflare workers.

New features

*.edgeql code generation

As an alternative to the query builder, it's now possible to write EdgeQL in *.edgeql files. Then run the queries code generator to produce typesafe functions corresponding to each file.

Given the following query in getMovie.edgeql...

select Movie { title } filter .title = <str>$title;

...running this command...

$ npx @edgedb/generate queries

...will generate this file as getMovie.edgeql.ts (roughly):

import type {Client} from "edgedb";

export async function getMovie(
  client: Client, 
  params: {title: string}
): Promise<{title: string} | null> {
  return client.querySingle(`select Movie { title } filter .title = <str>$title;`, params)
}

Pass the --file flag to generate a single file containing "query functions" for all detected *.edgeql files. By default this file will be written to dbschema/queries.ts.

$ npx @edgedb/generate queries --file

Full documentation

createHttpClient

A "vanilla" EdgeDB client created with createClient opens a raw TLS connection to EdgeDB over which it communicates using EdgeDB's binary protocol. However, if you need to execute EdgeQL directly from the browser or from an edge environment like Cloudflare Workers, this usually isn't possible.

It's now possible to create an EdgeDB Client that communicates entirely over HTTP for use in these constrained environments. The API for executing queries is identical.

import {createHttpClient} from "edgedb"

const client = createHttpClient();

await client.querySingle(`select 3.14`);

Since HTTP is stateless, these clients do not support transactions.