Generators​

Requirements​

To get started with generators, first initialize an EdgeDB project in the root of your application. Generators will look for an edgedb.toml file to determine the root of your application.

The query builder works for both JavaScript and TypeScript users, and supports both Node.js and Deno. It’s possible to use the query builder with or without TypeScript. Some requirements apply to TypeScript users only.

Node.js - Node.js v14+. Run node --version to see your current version.

Deno

• Deno v0.20+.

TypeScript

• TypeScript v4.4+.

• For Node.js users: npm install @types/node -D.

• Strict mode: "strict": true

• Downlevel iteration (query builder only): "downlevelIteration": true

// tsconfig.json
{
  // ...
  "compilerOptions": {
    // ...
    "strict": true,
    "downlevelIteration": true,
  }
}

Installation​

Install the edgedb package.

$ 

npm install edgedb       # npm users

$ 

yarn add edgedb          # yarn users

Then install @edgedb/generate as a dev dependency.

$ 

npm install @edgedb/generate --save-dev      # npm users

$ 

yarn add @edgedb/generate --dev              # yarn users

Running a generator​

Run a generator with the following command.

Node.js

$ 

npx @edgedb/generate <generator> [options]

Deno

$ 

deno run --allow-all --unstable https://deno.land/x/edgedb/generate.ts <generator> [options]

The value of <generator> should be one of the following.

• queries: This generator scans your project for *.edgeql files and generates a file containing a strongly-typed function alongside each. Alternatively you can use --file mode to generate a single file containing all the “query functions”.

• edgeql-js: This generator introspects your database schema and generates a query builder.

• interfaces: This generator introspects your database schema and generates TypeScript interfaces for each object type.

Connection​

Generating the query builder requires a connection to an active EdgeDB database. It does not simply read your local .esdl schema files. Generators rely on the database to introspect the schema and analyze queries. Doing so without a database connection would require implementing a full EdgeQL parser and static analyzer in JavaScript—which we don’t intend to do anytime soon.

If you’re using edgedb project init, this is automatically handled for you. Otherwise, you’ll need to explicitly pass connection information via environment variables or CLI flags, just like any other CLI command. See Client Libraries > Connection for guidance.

Targets​

All generators look at your environment and guess what kind of files to generate (.ts vs .js + .d.ts) and what module system to use (CommonJS vs ES modules). You can override this with the --target flag.

Help​

To see helptext for the @edgedb/generate command, run the following.

$ 

npx @edgedb/generate --help

Or read the full documentation for each generator:

• Query files

• Query builder