GROQ-JS

GROQ-JS is a JavaScript implementation of GROQ which follows the official specification.

1import {parse, evaluate} from 'groq-js'
2
3let input = '*[_type == "user"]{name}'
4
5// Returns an ESTree-inspired syntax tree
6let tree = parse(input)
7
8let dataset = [
9  {_type: 'user', name: 'Michael'},
10  {_type: 'company', name: 'Bluth Company'},
11]
12
13// Evaluate a tree against a dataset
14let value = await evaluate(tree, {dataset})
15
16// Gather everything into one JavaScript object
17let result = await value.get()
18
19console.log(result)

Table of contents:

• Installation
• Documentation
• Versioning
• License
• Tests

Installation

1# NPM
2npm i groq-js
3
4# Yarn
5yarn add groq-js

Documentation

See API.md for the public API.

Learn 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. This allows us to update the library and its API independent of the GROQ version.

GROQ-JS

GROQ-JS follows SemVer. See the changelog 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.

Releasing a new version of GROQ-JS

We use the np package to roll out new versions to NPM. You can read up more on the package here.

Make sure you update the CHANGELOG before releasing a new version. Use the previous updates as guidance for the desired formatting, and remember we use SemVer!

To interactively release the version run the following:

1npx np --no-release-draft

The --no-release-draft flag prevents a GitHub release draft being created.

The above np command will:

1. Update the version field in package.json
2. Publish the new version to NPM
3. Create a Git tag
4. Commit the Git tag and the updated package.json to version control, then push the changes upstream

It also peforms some pre-release checks, like running tests and ensuring you're releasing from the main branch.

For further context on the package and for instructions on how to bump versions in a non-interactive way visit the README.

License

MIT © Sanity.io

Tests

Tests are written in Jest:

1# Install dependencies
2npm i
3
4# Run tests
5npm test

You can also generate tests from the official GROQ test suite:

1# Fetch and generate test file:
2./test/generate.sh
3
4# Run tests as usual:
5npm test

You can generate tests from a specific version:

1GROQTEST_SUITE_VERSION=v0.1.33 ./test/generate.sh

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

1GROQTEST_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:

1npm test -g "array::join"