{"id":25660646,"url":"https://github.com/geldata/gel-js","last_synced_at":"2025-02-24T02:02:10.703Z","repository":{"id":37550103,"uuid":"42406144","full_name":"geldata/gel-js","owner":"geldata","description":"The official TypeScript/JS client library and query builder for EdgeDB","archived":false,"fork":false,"pushed_at":"2025-02-22T22:13:24.000Z","size":12752,"stargazers_count":523,"open_issues_count":182,"forks_count":67,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-02-22T22:16:23.367Z","etag":null,"topics":["database-driver","edgedb","edgeql","high-performance","typescript"],"latest_commit_sha":null,"homepage":"https://edgedb.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geldata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-13T17:46:38.000Z","updated_at":"2025-02-22T22:13:27.000Z","dependencies_parsed_at":"2023-10-13T04:53:02.321Z","dependency_job_id":"f3f3ba65-51e7-4da7-bf6f-5ca69d897c9d","html_url":"https://github.com/geldata/gel-js","commit_stats":{"total_commits":892,"total_committers":42,"mean_commits":"21.238095238095237","dds":0.7432735426008968,"last_synced_commit":"5de9abdec4106fd212b716bdee619e1124c52635"},"previous_names":["geldata/gel-js","edgedb/edgedb-js"],"tags_count":124,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geldata%2Fgel-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geldata%2Fgel-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geldata%2Fgel-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geldata%2Fgel-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geldata","download_url":"https://codeload.github.com/geldata/gel-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240386536,"owners_count":19793193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database-driver","edgedb","edgeql","high-performance","typescript"],"created_at":"2025-02-24T02:01:30.493Z","updated_at":"2025-02-24T02:02:10.686Z","avatar_url":"https://github.com/geldata.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eThe official Node.js client library for Gel\u003c/h1\u003e\n\n  \u003ca href=\"https://github.com/geldata/gel-js/actions\" rel=\"nofollow\"\u003e\n    \u003cimg src=\"https://github.com/geldata/gel-js/actions/workflows/tests.yml/badge.svg?event=push\u0026branch=master\" alt=\"Build status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/gel\" rel=\"nofollow\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/gel\" alt=\"NPM version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/geldata/gel\" rel=\"nofollow\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/geldata/gel\" alt=\"Stars\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/geldata/gel/blob/master/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue\" /\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://docs.geldata.com/get-started/quickstart\"\u003eQuickstart\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://www.geldata.com\"\u003eWebsite\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://docs.geldata.com/libraries/js\"\u003eDocs\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://discord.gg/umUueND6ag\"\u003eDiscord\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://twitter.com/geldata\"\u003eTwitter\u003c/a\u003e\n  \u003cbr /\u003e\n\n\u003c/div\u003e\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/get-started/quickstart) 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\u003e The examples below demonstrate only the most fundamental use cases for this\n\u003e library. **[Go to the complete documentation site. \u003e](https://docs.geldata.com/libraries/js)**\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/get-started/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 \u003e 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\"); // =\u003e [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\u003cstring\u003e(\"select \u003cstr\u003e{}\");\n//    ^? string | null\n\n// one element\nconst q2 = await client.querySingle\u003cnumber\u003e(\"select 2 + 2\");\n//    ^? number | null\n\n// one element\nconst q3 = await client.querySingle\u003c{ title: string }\u003e(\n//    ^? { title: string } | null\n  `select Movie { title }\n  filter .id = \u003cuuid\u003e'2eb3bc76-a014-45dc-af66-2e6e8cc23e7e';`,\n);\n\n// exactly one element\nconst q4 = await client.queryRequiredSingle\u003cnumber\u003e(\"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 \u003cgenerator\u003e [FLAGS]\n```\n\nThe following `\u003cgenerator\u003e`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 = \u003cstr\u003e$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://www.geldata.com/docs/clients/js/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) =\u003e ({\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; // =\u003e Timothee Chalamet\n```\n\nFor details on using the query builder, refer to the full [query builder docs](https://www.geldata.com/docs/clients/js/querybuilder).\n\n## Contribute\n\nContributing to this library requires a local installation of Gel. Install\nGel from [here](https://www.geldata.com/download) or\n[build it from source](https://docs.geldata.com/guides/contributing/code).\n\n```bash\n$ git clone git@github.com:gel/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\u003e In order to be able to run all tests you need to have `gel-server` in your\n\u003e path. This can be done by either running tests from within a Python 3.12\n\u003e virtual environment (you will have it if you built Gel locally), or by\n\u003e [installing](https://docs.geldata.com/cli/gel_server/gel_server_install#ref-cli-gel-server-install)\n\u003e specific Gel version and then adding its binary path to the `GEL_SERVER_BIN` environment variable.\n\u003e Check [here](https://docs.geldata.com/cli/gel_server/gel_server_info#ref-cli-gel-server-info)\n\u003e 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","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeldata%2Fgel-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeldata%2Fgel-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeldata%2Fgel-js/lists"}