# groq-js

> [![npm stat](https://img.shields.io/npm/dm/groq-js.svg?style=flat-square)](https://npm-stat.com/charts.html?package=groq-js) [![npm version](https://img.shields.io/npm/v/groq-js.svg?style=flat-square)](https://www.npmjs.com/package/groq-js) [![gzip size][

Latest version **2.0.0** (published 2026-07-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install groq-js
pnpm add groq-js
yarn add groq-js
bun add groq-js
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-07-22 |
| First published | 2019-07-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=22.12 |
| Dependencies | 1 |
| Unpacked size | 593.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 344 |
| Author | Sanity.io |
| Maintainers | kmelve, judofyr, sanity-svc.npm, sanity-io |
| Keywords | sanity, json, query, groq |

## Links

- npm: https://www.npmjs.com/package/groq-js
- Repository: https://github.com/sanity-io/groq-js
- Homepage: https://github.com/sanity-io/groq-js#readme
- Issues: https://github.com/sanity-io/groq-js/issues
- npm.io page: https://npm.io/package/groq-js

## Dependencies (1)

- [obug](https://npm.io/package/obug.md) ^2.1.3

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.0.0 (latest) — 2026-07-22
- 1.27.0-type-node-hasher.0 (type-node-hasher) — 2026-02-14
- 1.10.1-canary.0 (canary) — 2024-07-08
- 1.2.0-introspect.5 (introspect) — 2023-02-15
- 1.1.7 (beta) — 2023-02-14
- 1.30.3 — 2026-06-26
- 1.30.2 — 2026-05-26
- 1.30.1 — 2026-04-24
- 1.30.0 — 2026-04-16
- 1.29.0 — 2026-03-06
- 1.28.0 — 2026-03-04
- 1.27.1 — 2026-02-18
- 1.27.0 — 2026-02-12
- 1.26.0 — 2026-01-27
- 1.25.0 — 2026-01-06
- … 84 more at https://npm.io/package/groq-js/versions

## README

# GROQ-JS<!-- omit in toc -->

[![npm stat](https://img.shields.io/npm/dm/groq-js.svg?style=flat-square)](https://npm-stat.com/charts.html?package=groq-js)
[![npm version](https://img.shields.io/npm/v/groq-js.svg?style=flat-square)](https://www.npmjs.com/package/groq-js)
[![gzip size][gzip-badge]][bundlephobia]
[![size][size-badge]][bundlephobia]

GROQ-JS is a JavaScript implementation of [GROQ](https://www.sanity.io/docs/how-queries-work) which follows the official specification.

```javascript
import {parse, evaluate} from 'groq-js'

let input = '*[_type == "user"]{name}'

// Returns an ESTree-inspired syntax tree
let tree = parse(input)

let dataset = [
  {_type: 'user', name: 'Michael'},
  {_type: 'company', name: 'Bluth Company'},
]

// Evaluate a tree against a dataset
let value = await evaluate(tree, {dataset})

// Gather everything into one JavaScript object
let result = await value.get()

console.log(result)
```

Table of contents:

- [Installation](#installation)
- [Documentation](#documentation)
- [Learn GROQ](#learn-groq)
- [Versioning](#versioning)
  - [GROQ](#groq)
  - [GROQ-JS](#groq-js-1)
- [Releasing a new version of GROQ-JS](#releasing-a-new-version-of-groq-js)
- [License](#license)
- [Tests](#tests)

## Installation

```bash
npm i groq-js
```

```bash
yarn add groq-js
```

```bash
pnpm install groq-js
```

## Documentation

See [API.md](API.md) for the public API.

## Learn GROQ

[![Free egghead GROQ introduction course by John Lindquist](https://user-images.githubusercontent.com/6188161/142889665-fc04ac47-d0fa-492b-897b-4203c97e94ec.png)](https://egghead.io/courses/introduction-to-groq-query-language-6e9c6fc0?utm_source=github&utm_medium=cta&utm_term=GROQ)

## Versioning

### GROQ

The GROQ spec version is independent of the groq-js library version. When you import groq-js you need to be explicit on which GROQ version you want to use. The GROQ version is tied to the [groq-spec](https://github.com/sanity-io/groq). This allows us to update the library and its API independent of the GROQ version.

### GROQ-JS

GROQ-JS follows [SemVer](https://semver.org).
See [the changelog](CHANGELOG.md) for recent changes.
This is an "experimental" release and anything _may_ change at any time, but we're trying to keep changes as minimal as possible:

- The public API of the parser/evaluator will most likely stay the same in future versions.
- The syntax tree is _not_ considered a public API and may change at any time.
- This package always implements the latest version of [GROQ according to the specification](https://github.com/sanity-io/groq).

## Releasing a new version of GROQ-JS

Run the ["CI & Release" workflow](https://github.com/sanity-io/groq-js/actions/workflows/test.yml). Make sure to select the main branch and check "Release new version".

Version will be automatically bumped based on [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) since the last release.

Semantic release will only release on configured branches, so it is safe to run release on any branch.

Note: commits with `chore:` will be ignored. If you want updated dependencies to trigger
a new version, use `fix(deps):` instead.

## Adding a new GROQ function

To add a new function (e.g. `string::trim`):

1. **Register metadata** in `src/functionRegistry.ts` - add an entry to the appropriate namespace with its arity and mode. This is what the parser uses to validate function calls.
2. **Add the implementation** in `src/evaluator/functions/<namespace>.ts` - implement `executeSync` and `executeAsync`.
3. **Add tests** - test both parsing and evaluation. Run `npm test` to verify.
4. For **pipe functions** (used with `|`), add to `pipeFunctionRegistry` in the registry and implement in `src/evaluator/functions/pipeFunctions.ts`.

## License

MIT © [Sanity.io](https://www.sanity.io/)

## Tests

Tests are written in [Jest](https://jestjs.io/):

```bash
# Install dependencies
npm i

# Run tests
npm test
```

You can also generate tests from [the official GROQ test suite](https://github.com/sanity-io/groq-test-suite):

```bash
# Fetch and generate test file:
./test/generate.sh

# Run tests as usual:
npm test
```

You can generate tests from a specific version:

```shell
GROQTEST_SUITE_VERSION=v1.0.0 ./test/generate.sh
```

or from a file (as generated by the test suite):

```shell
GROQTEST_SUITE=suite.ndjson ./test/generate.sh
```

The test arguments are passed to `tap`, so you can use arguments, e.g. to run a specific set of tests:

```shell
npm test -g "array::join"
```

[gzip-badge]: https://img.shields.io/bundlephobia/minzip/groq-js?label=gzip%20size&style=flat-square
[size-badge]: https://img.shields.io/bundlephobia/min/groq-js?label=size&style=flat-square
[bundlephobia]: https://bundlephobia.com/package/groq-js

---
_Source: https://npm.io/package/groq-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._