edgedb - npm Package Compare versions

Comparing version 0.19.15 to 0.19.16

dist/index.shared.d.ts

@@ -36,1 +36,2 @@ /*!
 export declare const _plugJSBI: typeof plugJSBI;
+export declare const _edgedbJsVersion = "0.19.16";

dist/index.shared.js

@@ -42,3 +42,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._plugJSBI = exports._introspect = exports._ReadBuffer = exports._CodecsRegistry = exports.Set = exports.ConfigMemory = exports.RelativeDuration = exports.Duration = exports.LocalTime = exports.LocalDate = exports.LocalDateTime = void 0;
+exports._edgedbJsVersion = exports._plugJSBI = exports._introspect = exports._ReadBuffer = exports._CodecsRegistry = exports.Set = exports.ConfigMemory = exports.RelativeDuration = exports.Duration = exports.LocalTime = exports.LocalDate = exports.LocalDateTime = void 0;
 var datetime_1 = require("./datatypes/datetime");
@@ -63,1 +63,2 @@ Object.defineProperty(exports, "LocalDateTime", { enumerable: true, get: function () { return datetime_1.LocalDateTime; } });
 exports._plugJSBI = bigint_1.plugJSBI;
+exports._edgedbJsVersion = "0.19.16";

dist/reflection/generate.js

@@ -99,6 +99,15 @@ "use strict";
         index.addExportStarFrom(null, "./types", true, ["ts", "dts"]);
-        index.addImport({ $: true }, "edgedb");
+        index.addImport({ $: true, _edgedbJsVersion: true }, "edgedb");
         index.addExportFrom({ createClient: true }, "edgedb");
         index.addStarImport("$syntax", "./syntax/syntax", true);
         index.addStarImport("$op", "./operators", true);
+        index.writeln([
+            (0, builders_1.r) `\nif (_edgedbJsVersion !== "${index_node_1._edgedbJsVersion}") {
+  throw new Error(
+    \`The query builder was generated by a different version of edgedb-js (v${index_node_1._edgedbJsVersion})\` +
+      \` than the one currently installed (v\${_edgedbJsVersion}).\\n\` +
+      \`Run 'npx edgeql-js' to re-generate a compatible version.\\n\`
+  );
+}`,
+        ]);
         const spreadModules = [
@@ -105,0 +114,0 @@ {

dist/reflection/generators/generateSetImpl.js

@@ -39,2 +39,3 @@ "use strict";
     ]);
+    code.addImport({ getSharedParent: true }, "./set", true, ["ts", "js"]);
     code.nl();
@@ -146,46 +147,20 @@ code.writeln([
         (0, builders_1.r) ` = _exprs.map(expr => castMaps.literalToTypeSet(expr));
-  if (exprs.every((expr) => expr.__element__.__kind__ === TypeKind.object)) {
-    // merge object types;
-    return $expressionify({
-      __kind__: ExpressionKind.Set,
-      __element__: exprs
-        .map((expr) => expr.__element__`,
+
+  return $expressionify({
+    __kind__: ExpressionKind.Set,
+    __element__: exprs
+      .map(expr => expr.__element__`,
         (0, builders_1.ts) ` as any`,
-        (0, builders_1.r) `)
-        .reduce($mergeObjectTypes),
-      __cardinality__: cardinalityUtil.mergeCardinalitiesVariadic(
-        exprs.map((expr) => expr.__cardinality__)`,
+        `)
+      .reduce(getSharedParent),
+    __cardinality__: cardinalityUtil.mergeCardinalitiesVariadic(
+      exprs.map(expr => expr.__cardinality__)`,
         (0, builders_1.ts) ` as any`,
-        (0, builders_1.r) `
-      ),
-      __exprs__: exprs,
-    })`,
+        `
+    ),
+    __exprs__: exprs,
+  })`,
         (0, builders_1.ts) ` as any`,
-        (0, builders_1.r) `;
-  }
-  if (exprs.every((expr) => expr.__element__.__kind__ !== TypeKind.object)) {
-    return $expressionify({
-      __kind__: ExpressionKind.Set,
-      __element__: exprs
-        .map((expr) => expr.__element__`,
-        (0, builders_1.ts) ` as any`,
-        (0, builders_1.r) `)
-        .reduce(castMaps.getSharedParentScalar),
-      __cardinality__: cardinalityUtil.mergeCardinalitiesVariadic(
-        exprs.map((expr) => expr.__cardinality__)`,
-        (0, builders_1.ts) ` as any`,
-        (0, builders_1.r) `
-      ),
-      __exprs__: exprs,
-    })`,
-        (0, builders_1.ts) ` as any`,
-        (0, builders_1.r) `;
-  }
-  throw new Error(
-    \`Invalid arguments to set constructor: \${(_exprs`,
-        (0, builders_1.ts) ` as TypeSet[]`,
-        (0, builders_1.r) `)
-      .map((expr) => expr.__element__.__name__)
-      .join(", ")}\`
-  );
+        `;
+
 }`,
@@ -192,0 +167,0 @@ ]);

dist/reflection/hydrate.d.ts

 import * as introspect from "./queries/getTypes";
-import { BaseType, ObjectType, ObjectTypePointers } from "./typesystem";
+import { BaseType, ObjectType, ObjectTypePointers, TupleType } from "./typesystem";
 import { typeutil } from "./util/util";
@@ -10,1 +10,2 @@ export declare function makeType<T extends BaseType>(spec: introspect.Types, id: string, literal: any, anytype?: BaseType): T;
 export declare function $mergeObjectTypes<A extends ObjectType, B extends ObjectType>(a: A, b: B): mergeObjectTypes<A, B>;
+export declare function $mergeTupleTypes<A extends TupleType, B extends TupleType>(a: A, b: B): TupleType;

dist/reflection/hydrate.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.$mergeObjectTypes = exports.makeType = void 0;
+exports.$mergeTupleTypes = exports.$mergeObjectTypes = exports.makeType = void 0;
 const enums_1 = require("./enums");
@@ -198,1 +198,8 @@ const util_1 = require("./util/util");
 exports.$mergeObjectTypes = $mergeObjectTypes;
+function $mergeTupleTypes(a, b) {
+    if (a.__items__.length !== b.__items__.length) {
+        throw new Error("Incompatible tuple types; lengths differ.");
+    }
+    return {};
+}
+exports.$mergeTupleTypes = $mergeTupleTypes;

dist/reflection/typesystem.d.ts

@@ -91,2 +91,3 @@ import type { Executor } from "../ifaces";
 export declare type PropertyTypes = ScalarType | EnumType | ArrayType | TupleType | NamedTupleType;
+export declare type SomeType = ScalarType | EnumType | ArrayType | TupleType | ObjectType | NamedTupleType;
 export interface PropertyDesc<Type extends BaseType = BaseType, Card extends Cardinality = Cardinality, Exclusive extends boolean = boolean, Computed extends boolean = boolean, Readonly extends boolean = boolean, HasDefault extends boolean = boolean> {
@@ -93,0 +94,0 @@ __kind__: "property";

dist/syntax/set.d.ts

@@ -1,3 +0,4 @@
-import type { ArrayType, BaseTypeTuple, BaseType, NamedTupleType, ObjectTypeSet, TypeSet, TupleType, Expression, ExpressionKind, mergeObjectTypes, ObjectType, Cardinality, getPrimitiveBaseType } from "../reflection";
-import { getSharedParentScalar } from "../castMaps";
+import type { ArrayType, BaseTypeTuple, BaseType, NamedTupleType, ObjectTypeSet, TypeSet, TupleType, Expression, ExpressionKind, mergeObjectTypes, ObjectType, Cardinality, getPrimitiveBaseType, SomeType } from "../reflection";
+import * as castMaps from "../castMaps";
+export declare function getSharedParent(a: SomeType, b: SomeType): SomeType;
 export { set } from "./setImpl";
@@ -13,5 +14,5 @@ export declare type $expr_Set<Set extends LooseTypeSet = LooseTypeSet> = Expression<{
 };
-export declare type getSharedParentPrimitive<A, B> = A extends undefined ? B extends undefined ? undefined : B : B extends undefined ? A : A extends ArrayType<infer AEl> ? B extends ArrayType<infer BEl> ? ArrayType<getSharedParentScalar<AEl, BEl>> : never : A extends NamedTupleType<infer AShape> ? B extends NamedTupleType<infer BShape> ? NamedTupleType<{
-    [k in keyof AShape & keyof BShape]: getSharedParentScalar<AShape[k], BShape[k]>;
-}> : never : A extends TupleType<infer AItems> ? B extends TupleType<infer BItems> ? mergeTypeTuples<AItems, BItems> extends BaseTypeTuple ? TupleType<mergeTypeTuples<AItems, BItems>> : never : never : getSharedParentScalar<A, B>;
+export declare type getSharedParentPrimitive<A, B> = A extends undefined ? B extends undefined ? undefined : B : B extends undefined ? A : A extends ArrayType<infer AEl> ? B extends ArrayType<infer BEl> ? ArrayType<castMaps.getSharedParentScalar<AEl, BEl>> : never : A extends NamedTupleType<infer AShape> ? B extends NamedTupleType<infer BShape> ? NamedTupleType<{
+    [k in keyof AShape & keyof BShape]: castMaps.getSharedParentScalar<AShape[k], BShape[k]>;
+}> : never : A extends TupleType<infer AItems> ? B extends TupleType<infer BItems> ? mergeTypeTuples<AItems, BItems> extends BaseTypeTuple ? TupleType<mergeTypeTuples<AItems, BItems>> : never : never : castMaps.getSharedParentScalar<A, B>;
 declare type _getSharedParentPrimitiveVariadic<Types extends [any, ...any[]]> = Types extends [infer U] ? U : Types extends [infer A, infer B, ...infer Rest] ? _getSharedParentPrimitiveVariadic<[
@@ -18,0 +19,0 @@ getSharedParentPrimitive<A, B>,

dist/syntax/set.js

 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.set = void 0;
+exports.set = exports.getSharedParent = void 0;
+const reflection_1 = require("../reflection");
+const castMaps = __importStar(require("../castMaps"));
+function getSharedParent(a, b) {
+    if (a.__kind__ !== b.__kind__) {
+        throw new Error(`Incompatible array types: ${a.__name__} and ${b.__name__}`);
+    }
+    if (a.__kind__ === reflection_1.TypeKind.scalar && b.__kind__ === reflection_1.TypeKind.scalar) {
+        return castMaps.getSharedParentScalar(a, b);
+    }
+    else if (a.__kind__ === reflection_1.TypeKind.object &&
+        b.__kind__ === reflection_1.TypeKind.object) {
+        return (0, reflection_1.$mergeObjectTypes)(a, b);
+    }
+    else if (a.__kind__ === reflection_1.TypeKind.tuple && b.__kind__ === reflection_1.TypeKind.tuple) {
+        if (a.__items__.length !== b.__items__.length) {
+            throw new Error(`Incompatible tuple types: ${a.__name__} and ${b.__name__}`);
+        }
+        try {
+            const items = a.__items__.map((_, i) => {
+                if (!a.__items__[i] || !b.__items__[i]) {
+                    throw new Error();
+                }
+                return getSharedParent(a.__items__[i], b.__items__[i]);
+            });
+            return {
+                __kind__: reflection_1.TypeKind.tuple,
+                __name__: `tuple<${items.map(item => item.__name__).join(", ")}>`,
+                __items__: items,
+            };
+        }
+        catch (err) {
+            throw new Error(`Incompatible tuple types: ${a.__name__} and ${b.__name__}`);
+        }
+    }
+    else if (a.__kind__ === reflection_1.TypeKind.namedtuple &&
+        b.__kind__ === reflection_1.TypeKind.namedtuple) {
+        const aKeys = Object.keys(a);
+        const bKeys = new Set(Object.keys(b));
+        const sameKeys = aKeys.length === bKeys.size && aKeys.every(k => bKeys.has(k));
+        if (!sameKeys) {
+            throw new Error(`Incompatible tuple types: ${a.__name__} and ${b.__name__}`);
+        }
+        try {
+            const items = {};
+            for (const [i] of Object.entries(a.__shape__)) {
+                if (!a.__shape__[i] || !b.__shape__[i]) {
+                    throw new Error();
+                }
+                items[i] = getSharedParent(a.__shape__[i], b.__shape__[i]);
+            }
+            return {
+                __kind__: reflection_1.TypeKind.namedtuple,
+                __name__: `tuple<${Object.entries(items)
+                    .map(([key, val]) => `${key}: ${val.__name__}`)
+                    .join(", ")}>`,
+                __shape__: items,
+            };
+        }
+        catch (err) {
+            throw new Error(`Incompatible tuple types: ${a.__name__} and ${b.__name__}`);
+        }
+    }
+    else if (a.__kind__ === reflection_1.TypeKind.array && b.__kind__ === reflection_1.TypeKind.array) {
+        try {
+            const mergedEl = getSharedParent(a.__element__, b.__element__);
+            return {
+                __kind__: reflection_1.TypeKind.array,
+                __name__: a.__name__,
+                __element__: mergedEl,
+            };
+        }
+        catch (err) {
+            throw new Error(`Incompatible array types: ${a.__name__} and ${b.__name__}`);
+        }
+    }
+    else if (a.__kind__ === reflection_1.TypeKind.enum && b.__kind__ === reflection_1.TypeKind.enum) {
+        if (a.__name__ === b.__name__)
+            return a;
+        throw new Error(`Incompatible array types: ${a.__name__} and ${b.__name__}`);
+    }
+    else {
+        throw new Error(`Incompatible array types: ${a.__name__} and ${b.__name__}`);
+    }
+}
+exports.getSharedParent = getSharedParent;
 var setImpl_1 = require("./setImpl");
 Object.defineProperty(exports, "set", { enumerable: true, get: function () { return setImpl_1.set; } });

dist/syntax/set.ts

@@ -15,8 +15,112 @@ import type {
   getPrimitiveBaseType,
+  SomeType,
 } from "../reflection";
+import {TypeKind, $mergeObjectTypes} from "../reflection";
 
 // "@generated/" path gets replaced during generation step
 // @ts-ignore
-import {getSharedParentScalar} from "../castMaps";
+import * as castMaps from "../castMaps";
 
+export function getSharedParent(a: SomeType, b: SomeType): SomeType {
+  if (a.__kind__ !== b.__kind__) {
+    throw new Error(
+      `Incompatible array types: ${a.__name__} and ${b.__name__}`
+    );
+  }
+  if (a.__kind__ === TypeKind.scalar && b.__kind__ === TypeKind.scalar) {
+    return castMaps.getSharedParentScalar(a, b);
+  } else if (
+    a.__kind__ === TypeKind.object &&
+    b.__kind__ === TypeKind.object
+  ) {
+    return $mergeObjectTypes(a, b);
+  } else if (a.__kind__ === TypeKind.tuple && b.__kind__ === TypeKind.tuple) {
+    if (a.__items__.length !== b.__items__.length) {
+      throw new Error(
+        `Incompatible tuple types: ${a.__name__} and ${b.__name__}`
+      );
+    }
+    try {
+      const items = a.__items__.map((_, i) => {
+        if (!a.__items__[i] || !b.__items__[i]) {
+          throw new Error();
+        }
+        return getSharedParent(
+          a.__items__[i] as SomeType,
+          b.__items__[i] as SomeType
+        );
+      });
+
+      return {
+        __kind__: TypeKind.tuple,
+        __name__: `tuple<${items.map(item => item.__name__).join(", ")}>`,
+        __items__: items as BaseTypeTuple,
+      };
+    } catch (err) {
+      throw new Error(
+        `Incompatible tuple types: ${a.__name__} and ${b.__name__}`
+      );
+    }
+  } else if (
+    a.__kind__ === TypeKind.namedtuple &&
+    b.__kind__ === TypeKind.namedtuple
+  ) {
+    const aKeys = Object.keys(a);
+    const bKeys = new Set(Object.keys(b));
+    const sameKeys =
+      aKeys.length === bKeys.size && aKeys.every(k => bKeys.has(k));
+    if (!sameKeys) {
+      throw new Error(
+        `Incompatible tuple types: ${a.__name__} and ${b.__name__}`
+      );
+    }
+    try {
+      const items: {[k: string]: BaseType} = {};
+      for (const [i] of Object.entries(a.__shape__)) {
+        if (!a.__shape__[i] || !b.__shape__[i]) {
+          throw new Error();
+        }
+        items[i] = getSharedParent(
+          a.__shape__[i] as SomeType,
+          b.__shape__[i] as SomeType
+        );
+      }
+
+      return {
+        __kind__: TypeKind.namedtuple,
+        __name__: `tuple<${Object.entries(items)
+          .map(([key, val]: [string, any]) => `${key}: ${val.__name__}`)
+          .join(", ")}>`,
+        __shape__: items,
+      };
+    } catch (err) {
+      throw new Error(
+        `Incompatible tuple types: ${a.__name__} and ${b.__name__}`
+      );
+    }
+  } else if (a.__kind__ === TypeKind.array && b.__kind__ === TypeKind.array) {
+    try {
+      const mergedEl: any = getSharedParent(a.__element__, b.__element__);
+      return {
+        __kind__: TypeKind.array,
+        __name__: a.__name__,
+        __element__: mergedEl,
+      } as ArrayType;
+    } catch (err) {
+      throw new Error(
+        `Incompatible array types: ${a.__name__} and ${b.__name__}`
+      );
+    }
+  } else if (a.__kind__ === TypeKind.enum && b.__kind__ === TypeKind.enum) {
+    if (a.__name__ === b.__name__) return a;
+    throw new Error(
+      `Incompatible array types: ${a.__name__} and ${b.__name__}`
+    );
+  } else {
+    throw new Error(
+      `Incompatible array types: ${a.__name__} and ${b.__name__}`
+    );
+  }
+}
+
 // @ts-ignore
@@ -47,3 +151,3 @@ export {set} from "./setImpl";
   ? B extends ArrayType<infer BEl>
-    ? ArrayType<getSharedParentScalar<AEl, BEl>>
+    ? ArrayType<castMaps.getSharedParentScalar<AEl, BEl>>
     : never
@@ -53,3 +157,3 @@ : A extends NamedTupleType<infer AShape>
     ? NamedTupleType<{
-        [k in keyof AShape & keyof BShape]: getSharedParentScalar<
+        [k in keyof AShape & keyof BShape]: castMaps.getSharedParentScalar<
           AShape[k],
@@ -66,3 +170,3 @@ BShape[k]
     : never
-  : getSharedParentScalar<A, B>;
+  : castMaps.getSharedParentScalar<A, B>;
 
@@ -69,0 +173,0 @@ type _getSharedParentPrimitiveVariadic<Types extends [any, ...any[]]> =

package.json

 {
   "name": "edgedb",
-  "version": "0.19.15",
+  "version": "0.19.16",
   "description": "The official Node.js client library for EdgeDB",
@@ -5,0 +5,0 @@ "homepage": "https://edgedb.com/docs",

README.md

@@ -1,34 +0,75 @@
-# The official Node.js client library for EdgeDB
+<div align="center">
+  <h1>The official Node.js client library for EdgeDB</h1>
 
-[![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)
+  <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 />
 
-**edgedb** is the official [EdgeDB](https://github.com/edgedb/edgedb) driver
+</div>
+
+<br />
+<br />
+
+This is the official [EdgeDB](https://github.com/edgedb/edgedb) client library
 for JavaScript and TypeScript.
 
-The library requires Node.js 12+.
+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.
 
-## Installation
+### Requirements
 
+- Node.js 12+
+- _TypeScript only_
+  - TypeScript 4.4+
+  - `yarn add @types/node`
+
+### 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.
 
-npm install edgedb
+_For TypeScript (and Node.js+ESM)_
+
+```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)_
 
@@ -38,20 +79,97 @@ ```js
 
-async function main() {
-  const client = edgedb.createClient();
+const client = edgedb.createClient();
+```
 
-  console.log(
-    await client.querySingle(
-      `SELECT re_replace('World', 'EdgeDB', 'Hello World!')`
-    )
-  );
-}
+### Configuring the connection
 
-main();
+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]
 ```
 
-## Development
+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.
 
-A local installation of EdgeDB is required to run tests. Download
+```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";
+
+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')
+}));
+
+const result = await query.run(client);
+result.actors[0].name; // => Timothee Chalamet
+```
+
+## Contribute
+
+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).
 
@@ -58,0 +176,0 @@ ```bash

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

186

increased by173.53%

Number of low supply chain risk alerts

17

decreased by-41.38%

Worsened metrics

Total package byte prevSize

996764

decreased by-12%

Number of package files

249

decreased by-7.09%

Lines of code

25518

decreased by-10.8%

No dependency changes