RFC: Command naming

[colinhacks]

Currently, we only provide a single bin script: edgeql-js. However there are a few reasons we need to rethink this.

• We're adding another command to run migrations: https://github.com/edgedb/edgedb-js/issues/340
• I proposed a new generation workflow based on *.edgeql files: https://github.com/edgedb/edgedb-js/issues/314
• Some people are opposed to making the script name (edgeql-js) different from the package name that implements the script (edgedb). If someone sees an npx command they may try to install a local version of that package (yarn add edgedb-js) which won't actually work because the implementation of this command lives inside the edgedb module.
• I also just don't like hyphenated commands, they're harder to type and feel more complex.

We will likely implement more commands/functionality moving forward, so we should adopt a more extensible/futureproof convention for naming these commands. I propose splitting each command into a separate NPM package under the @edgedb scope, with a monorepo architecture. The packages would be:

edgedb

The client library implementation (not including query builder generation). This package will also provide a set of tools for building "generators", including an easy way to run a comprehensive strongly-typed introspection query (client.introspect()?), our CodeBuilder utility class, and our ts/js/r/all/dts/t tags.

@edgedb/generate

This package will serve as the basis for an ecosystem of "generators" inspired by graphql-code-generator. The query builder and the *.edgeql generator will be two officially maintained ones, but we can build more later or accept contributions from the community.

We implement the query builder as a "generator" using the tools provided by edgedb, which will be a dependency of this peer package. We can arrange this such that edgedb and @edgedb/generate have matching versions. Users could install/pin a local version of @edgedb/generate if they wish.

This command would be executed like so.

npx @edgedb/generate <generator-name> [options]

The following generators would be implemented initially, and we could built more as the need arises:

qb — generate the query builder types — generate a plain TS representation of the schema (interfaces & enums) edgeql — generate a strongly typed client from any *.edgeql files discovered in the project directory. Detailed here: https://github.com/edgedb/edgedb-js/issues/314

The [options] would include all connection parameters and any generator-specific options (e.g. --target for the query builder).

Future generators:

• Schema definitions for Zod, io-ts, and Yup
• GraphQL schemas or framework code (TypeGraphQL, etc)
• Alternative client APIs, e.g. a Prisma clone to help ease the transition for those users
• Class/struct definitions in various languages
• Community-implemented generators. It would be cool if external contributors could submit PRs for custom generators that, once merged, would be available via the npx @edgedb/generate workflow. We'd have to be clear that these are community maintained and not first-party.

GraphQL's code generation ecosystem is incredibly rich and beloved. Currently there isn't really an equivalent database-centric codegen ecosystem — SQL introspection just doesn't cut it because it's not object-oriented. Prisma is doing something similar with their generators concept. I think it's important that EdgeDB provide the foundation for a similar code generation ecosystem.

Because @edgedb/generate would be a separate package from edgedb, we don't have to worry about bundle bloat, since @edgedb/generate would only ever be a dev dependency. There's no problem bundling all generators into one package.

@edgedb/migrate

This package would install the CLI and execute migrations, per https://github.com/edgedb/edgedb-js/issues/340. It's also sufficiently distinct-looking that there's little risk of confusion with the actual CLI (which was the original concern with using npx edgedb generate).

npx @edgedb/migrate

This proposed command name supercedes the npx edgedb-migrate proposal in https://github.com/edgedb/edgedb-js/issues/340

[1st1]

+1.

[NexZhu]

@colinhacks Hi, what's the status of Zod schema generator? When will it be avaialable? Thanks!

[scotttrinh]

While some details have changed, and some tools like @edgedb/migrate have not materialized yet, I'm going to close this as completed due to the majority of the organizational changes that this was meant to introduce have been introduced. Any further issues/bugs/suggestions can live in their own issue or RFC.