\n\nThis is the official [Gel](https://www.geldata.com) client library\nfor JavaScript and TypeScript.\n\nIf you're just getting started with Gel, we recommend going through the\n[Gel Quickstart](https://docs.geldata.com/learn/quickstart/overview/nextjs) first. This walks\nyou through the process of installing Gel, creating a simple schema, and\nwriting some simple queries.\n\n### Requirements\n\n- Node.js 18+\n- For TypeScript users:\n - TypeScript 4.4+ is required\n\n## Basic usage\n\n> The examples below demonstrate only the most fundamental use cases for this\n> library. **[Go to the complete documentation site. >](https://docs.geldata.com/reference/clients/js#gel-js-intro)**\n\n### Create a client\n\nA _client_ is an instance of the `Client` class, which maintains a pool of\nconnections to your database and provides methods for executing queries.\n\n```ts\nimport * as gel from \"gel\";\n\nconst client = gel.createClient();\n```\n\n### Configuring the connection\n\nThe call to `gel.createClient()` doesn't require arguments, as the library\ncan determine how to connect to your database using the following mechanisms.\n\n1. _For local development_: initialize a project with the `gel project init`\n command. As long as the file is within a project directory, `createClient`\n will be able to auto-discover the connection information of the project's\n associated instance. For more information on projects, follow the\n [Using projects](https://docs.geldata.com/learn/projects) guide.\n\n2. _In production_: configure the connection using **environment variables**.\n (This can also be used during local development if you prefer.) The easiest\n way is to set the `GEL_DSN` variable; a DSN (also known as a \"connection\n string\") is a string of the form\n `gel://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE`.\n\nFor advanced cases, see the\n[DSN specification](https://docs.geldata.com/database/reference/dsn) and\n[Reference > Connection Parameters](https://docs.geldata.com/database/reference/connection).\n\n### Run a query\n\n```ts\nimport * as gel from \"gel\";\n\nconst client = gel.createClient();\nawait client.query(\"select 2 + 2\"); // => [4]\n```\n\nNote that the result is an _array_. The `.query()` method always returns an\narray, regardless of the result cardinality of your query. If your query returns\n_zero or one elements_, use the `.querySingle()` method instead. If your query\nis guaranteed to return exactly one element, use the `.queryRequiredSingle()`\nmethod.\n\n```ts\n// empty set, zero elements\nconst q1 = await client.querySingle(\"select {}\");\n// ^? string | null\n\n// one element\nconst q2 = await client.querySingle(\"select 2 + 2\");\n// ^? number | null\n\n// one element\nconst q3 = await client.querySingle<{ title: string }>(\n// ^? { title: string } | null\n `select Movie { title }\n filter .id = '2eb3bc76-a014-45dc-af66-2e6e8cc23e7e';`,\n);\n\n// exactly one element\nconst q4 = await client.queryRequiredSingle(\"select 42;\");\n// ^? number\n```\n\n## Generators\n\nInstall the `@gel/generate` package as a dev dependency to take advantage of Gel's built-in code generators.\n\n```bash\nnpm install @gel/generate --save-dev\n```\n\nThen run a generator with the following command:\n\n```bash\n$ npx @gel/generate [FLAGS]\n```\n\nThe following ``s are currently supported:\n\n- `queries`: Generate typed functions from `*.edgeql` files\n- `interfaces`: Generate interfaces for your schema types\n- `edgeql-js`: Generate the query builder\n\n### `queries`\n\nRun the following command to generate a source file for each `*.edgeql` system in your project.\n\n```bash\n$ npx @gel/generate queries\n```\n\nAssume you have a file called `getUser.edgeql` in your project directory.\n\n```\n// getUser.edgeql\nselect User {\n name,\n email\n}\nfilter .email = $email;\n```\n\nThis generator will generate a `getUser.query.ts` file alongside it that exports a function called `getUser`.\n\n```ts\nimport { createClient } from \"gel\";\nimport { getUser } from \"./getUser.query\";\n\nconst client = createClient();\n\nconst user = await getUser(client, { name: \"Timmy\" });\n// ^? { name: string; email: string }\n```\n\nThe first argument is a `Client`, the second is the set of _parameters_. Both the parameters and the returned value are fully typed.\n\n### `edgeql-js` (query builder)\n\nThe query builder lets you write queries in a code-first way. It automatically infers the return type of your queries.\n\nTo generate the query builder, install the `gel` package, initialize a project (if you haven't already), then run the following command:\n\n```bash\n$ npx @gel/generate edgeql-js\n```\n\nThis will generate an EdgeQL query builder into the `./dbschema/edgeql-js`\ndirectory, as defined relative to your project root.\n\nFor details on generating the query builder, refer to the [complete documentation](https://docs.geldata.com/reference/clients/js/querybuilder#generation). Below is a simple `select` query as an example.\n\n```ts\nimport { createClient } from \"gel\";\nimport e from \"./dbschema/edgeql-js\";\n\nconst client = createClient();\nconst query = e.select(e.Movie, (movie) => ({\n id: true,\n title: true,\n actors: { name: true },\n num_actors: e.count(movie.actors),\n filter_single: e.op(movie.title, \"=\", \"Dune\"),\n}));\n\nconst result = await query.run(client);\nresult.actors[0].name; // => Timothee Chalamet\n```\n\nFor details on using the query builder, refer to the full [query builder docs](https://docs.geldata.com/reference/clients/js/querybuilder).\n\n## Contribute\n\nContributing to this library requires a local installation of Gel. Install\nGel from [here](https://docs.geldata.com/learn/cli) or\n[build it from source](https://docs.geldata.com/resources/guides/contributing/code).\n\n```bash\n$ git clone git@github.com:geldata/gel-js.git\n$ cd gel-js\n$ yarn # install dependencies\n$ yarn run build # build all packages\n$ yarn run test # run tests for all packages\n```\n\n> In order to be able to run all tests you need to have `gel-server` in your\n> path. This can be done by either running tests from within a Python 3.12\n> virtual environment (you will have it if you built Gel locally), or by\n> [installing](https://docs.geldata.com/reference/cli/gel_server/gel_server_install)\n> specific Gel version and then adding its binary path to the `GEL_SERVER_BIN` environment variable.\n> Check [here](https://docs.geldata.com/reference/cli/gel_server/gel_server_info)\n> to find how to get the binary path.\n\n## License\n\n`gel-js` is developed and distributed under the Apache 2.0 license.\n","readmeFilename":"README.md"}
![\"Build](\"https://github.com/geldata/gel-js/actions/workflows/tests.yml/badge.svg?event=push&branch=master\"){kind=icon}
\n \n \n ![\"NPM](\"https://img.shields.io/npm/v/gel\")
\n \n \n ![\"Stars\"](\"https://img.shields.io/github/stars/geldata/gel\")
\n \n \n ![](\"https://img.shields.io/badge/license-Apache%202.0-blue\"){kind=icon}
\n \n