Improve docs (#308)

* Update readme

* Fix method name

* Add line breaks

* Improve formatting

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 # .github/release.yml
 
-name: Release
+name: release
 on:
   push:
     branches:

.github/workflows/tests.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: tests
 
 on:
   push:

README.md

@@ -1,58 +1,176 @@
-# The official Node.js client library for EdgeDB
+<div align="center">
+  <h1>The official Node.js client library for EdgeDB</h1>
+
+  <a href="https://github.com/edgedb/edgedb-js/actions" rel="nofollow">
+    <img src="https://github.com/edgedb/edgedb-js/actions/workflows/tests.yml/badge.svg?event=push&branch=master" alt="Build status">
+  </a>
+  <a href="https://www.npmjs.com/package/edgedb" rel="nofollow">
+    <img src="https://img.shields.io/npm/v/edgedb" alt="NPM version">
+  </a>
+  <a href="https://github.com/edgedb/edgedb" rel="nofollow">
+    <img src="https://img.shields.io/github/stars/edgedb/edgedb" alt="Stars">
+  </a>
+  <a href="https://github.com/edgedb/edgedb/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-Apache%202.0-blue" />
+  </a>
+  <br />
+  <br />
+  <a href="https://www.edgedb.com/docs/guides/quickstart">Quickstart</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://www.edgedb.com">Website</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://www.edgedb.com/docs/clients/01_js/index">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://discord.gg/umUueND6ag">Discord</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://twitter.com/edgedatabase">Twitter</a>
+  <br />
+
+</div>
+
+<br />
+<br />
+
+This is the official [EdgeDB](https://github.com/edgedb/edgedb) client library
+for JavaScript and TypeScript.
 
-[![Build Status](https://github.com/edgedb/edgedb-js/workflows/Tests/badge.svg?event=push&branch=master)](https://github.com/edgedb/edgedb-js/actions) [![NPM](https://img.shields.io/npm/v/edgedb)](https://www.npmjs.com/package/edgedb) [![Join GitHub discussions](https://img.shields.io/badge/join-github%20discussions-green)](https://github.com/edgedb/edgedb/discussions)
+If you're just getting started with EdgeDB, we recommend going through the
+[EdgeDB Quickstart](https://www.edgedb.com/docs/quickstart) first. This walks
+you through the process of installing EdgeDB, creating a simple schema, and
+writing some simple queries.
 
-**edgedb** is the official [EdgeDB](https://github.com/edgedb/edgedb) driver
-for JavaScript and TypeScript.
+### Requirements
 
-The library requires Node.js 12+.
+- Node.js 12+
+- _TypeScript only_
+  - TypeScript 4.4+
+  - `yarn add @types/node`
 
-## Installation
+### Installation
 
 ```bash
-npm install edgedb
-# or
-yarn add edgedb
+npm install edgedb      # npm users
+yarn add edgedb         # yarn users
 ```
 
-## Quickstart
+## Basic usage
 
-First, go through the
-[EdgeDB Quickstart](https://www.edgedb.com/docs/quickstart) to install EdgeDB
-and set up your first EdgeDB project.
+> The examples below demonstrate only the most fundamental use cases for this
+> library. **[Go to the complete documentation site. >](https://www.edgedb.com/docs/clients/01_js/index)**
 
-Now in your project directory, install the "edgedb" library:
+### Create a client
 
-```bash
-npm init
+A _client_ is an instance of the `Client` class, which maintains a pool of
+connections to your database and provides methods for executing queries.
+
+_For TypeScript (and Node.js+ESM)_
 
-npm install edgedb
+```ts
+import * as edgedb from "edgedb";
+
+const client = edgedb.createClient();
 ```
 
-And here's a simple script to connect to your EdgeDB instance and
-run a simple query:
+_For Node.js (CommonJS)_
 
 ```js
 const edgedb = require("edgedb");
 
-async function main() {
-  const client = edgedb.createClient();
+const client = edgedb.createClient();
+```
+
+### Configuring the connection
+
+The call to `edgedb.createClient()` doesn't require arguments, as the library
+can determine how to connect to your database using the following mechanisms.
+
+1. _For local development_: initialize a project with the `edgedb project init`
+   command. As long as the file is within a project directory, `createClient`
+   will be able to auto-discover the connection information of the project's
+   associated instance. For more information on projects, follow the
+   [Using projects](https://www.edgedb.com/docs/guides/projects) guide.
+
+2. _In production_: configure the connection using **environment variables**.
+   (This can also be used during local development if you prefer.) The easiest
+   way is to set the `EDGEDB_DSN` variable; a DSN (also known as a "connection
+   string") is a string of the form
+   `edgedb://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE`.
+
+For advanced cases, see the
+[DSN specification](https://www.edgedb.com/docs/reference/dsn) and
+[Reference > Connection Parameters](https://www.edgedb.com/docs/reference/connection).
+
+### Run a query
+
+> The remainder of the documentation assumes you are using ES module (`import`)
+> syntax.
+
+```ts
+import * as edgedb from "edgedb";
+
+const client = edgedb.createClient();
+await client.query("select 2 + 2"); // => [4]
+```
+
+Note that the result is an _array_. The `.query()` method always returns an
+array, regardless of the result cardinality of your query. If your query
+returns _zero or one elements_, use the `.querySingle()` instead.
+
+```ts
+// empty set, zero elements
+await client.querySingle("select <str>{}"); // => null
+
+// one element
+await client.querySingle("select 2 + 2"); // => 4
+
+// one element
+await client.querySingle(
+  `select Movie { title }
+  filter .id = <uuid>'2eb3bc76-a014-45dc-af66-2e6e8cc23e7e';`
+); // => { title: "Dune" }
+```
+
+## Query builder
+
+Instead of writing queries as strings, you can use this package to generate a
+_query builder_. The query builder lets you write queries in a code-first way
+and automatically infers the return type of your queries.
+
+To generate the query builder, install the `edgedb`, initialize a project (if
+you haven't already), then run the following command:
+
+```sh
+$ npx edgeql-js
+```
+
+This will generate an EdgeQL query builder into the `"./dbschema/edgeql-js`
+directory, as defined relative to your project root.
+
+For details on using the query builder, refer to the [complete documentation](https://www.edgedb.com/docs/clients/01_js/generation). Below is a simple
+`select` query as an example.
+
+```ts
+import {createClient} from "edgedb";
+import e from "./dbschema/edgeql-js";
 
-  console.log(
-    await client.querySingle(
-      `SELECT re_replace('World', 'EdgeDB', 'Hello World!')`
-    )
-  );
-}
+const client = createClient();
+const query = e.select(e.Movie, movie => ({
+  id: true,
+  title: true,
+  actors: { name: true },
+  num_actors: e.count(movie.actors)
+  filter: e.op(movie.title, '=', 'Dune')
+}));
 
-main();
+const result = await query.run(client);
+result.actors[0].name; // => Timothee Chalamet
 ```
 
-## Development
+## Contribute
 
-A local installation of EdgeDB is required to run tests. Download
+Contributing to this library requires a local installation of EdgeDB. Install
 EdgeDB from [here](https://www.edgedb.com/download) or
-[build it manually](https://www.edgedb.com/docs/reference/dev).
+[build it from source](https://www.edgedb.com/docs/reference/dev).
 
 ```bash
 $ git clone [email protected]:edgedb/edgedb-js.git

docs/driver.rst

@@ -204,7 +204,8 @@ JSON results
 ------------
 
 There are dedicated methods for running queries and retrieving results as a
-serialized JSON string. This serialization happens inside the database.
+serialized JSON string. This serialization happens inside the database and is
+typically more performant than running ``JSON.stringify`` yourself.
 
 .. code-block:: js
 

docs/generation.rst

@@ -3,7 +3,7 @@
 Generation
 ==========
 
-The query builder is *auto-generated* from your database schema.
+The query builder is *auto-generated* by introspecting the schema of your database.
 
 Minimum requirements
 ^^^^^^^^^^^^^^^^^^^^
@@ -31,10 +31,11 @@ requirements apply to TypeScript users only.
 Initialize a project
 ^^^^^^^^^^^^^^^^^^^^
 
-Set up an :ref:`EdgeDB project <ref_guide_using_projects>` for your
-application. Follow the :ref:`Quickstart <ref_quickstart>` for detailed
-instructions on installing the CLI, initializing a project, writing a basic
-schema, and executing your first migration.
+When developing locally, we recommend initializing an :ref:`EdgeDB project
+<ref_guide_using_projects>` for your application. Follow the :ref:`Quickstart
+<ref_quickstart>` for detailed instructions on installing the CLI,
+initializing a project, writing a basic schema, and executing your first
+migration.
 
 Install the JavaScript client library
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -56,7 +57,8 @@ Generate the query builder with the following command.
   $ npx edgeql-js           # npm users
   $ yarn edgeql-js          # yarn users
 
-You'll see something like this.
+You'll see something similar to this. (The first line will differ depending on
+whether you are using TypeScript or plain JavaScript.)
 
 .. code-block:: bash
 
@@ -69,12 +71,22 @@ You'll see something like this.
   Introspecting database schema...
   Generation successful!
 
-The ``npx edgeql-js`` establishes a connection to your database, introspects
-the current schema, and generates a bunch of files. By default, these files
-are written to the ``./dbschema/edgeql-js`` directory, as defined relative to
-your project root. The project root is identified by scanning up the file
-system for a ``package.json``.
+**Important**. The ``npx edgeql-js`` establishes a connection to your database, introspects the current schema, and generates a bunch of files. It does **not** simply read your local ``.esdl`` files. You must create and apply migrations to your development database before running ``npx edgeql-js``.
 
+.. note::
+
+  It is not possible to generate the query builder without establishing a
+  connection to an active EdgeDB instance. Remember that object types can
+  contain computed fields that correspond to arbitrary EdgeQL queries. It
+  isn't possible to determine the type and cardinality of these queries
+  without implementing a full EdgeQL parser and static analyzer in JavaScript,
+  which is not on our roadmap (to put it lightly). As such, we rely on the
+  existence of an active EdgeDB instance containing the target schema.
+
+By default, ``npx edgeql-js`` generated files into the
+``./dbschema/edgeql-js`` directory, as defined relative to your project root.
+The project root is identified by scanning up the file system for a
+``package.json``.
 
 .. note::
 

qb/playground.ts

@@ -6,6 +6,15 @@ import {setupTests} from "./test/setupTeardown";
 import e, * as types from "./dbschema/edgeql-js/index";
 
 async function run() {
+  const asd = {
+    "3": "asdf",
+    qwer: "sdf",
+  } as const;
+
+  function infer<T>() {}
+
+  console.log(asd[3]);
+
   const {client} = await setupTests();
   const query = e
     .insert(e.Movie, {