@freighter-studio/groq-js
v1.1.0-custom.1
Published
GROQ-JS is a JavaScript implementation of [GROQ](https://www.sanity.io/docs/data-store/how-queries-work) which follows the official specification.
Downloads
7
Readme
GROQ-JS
GROQ-JS is a JavaScript implementation of GROQ which follows the official specification.
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
# NPM
npm i groq-js
# Yarn
yarn 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:
npx np --no-release-draft
The --no-release-draft
flag prevents a GitHub release draft being created.
The above np
command will:
- Update the
version
field inpackage.json
- Publish the new version to NPM
- Create a Git tag
- 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:
# Install dependencies
npm i
# Run tests
npm test
You can also generate tests from the official GROQ test suite:
# Fetch and generate test file:
./test/generate.sh
# Run tests as usual:
npm test
You can generate tests from a specific version:
GROQTEST_SUITE_VERSION=v0.1.33 ./test/generate.sh
or from a file (as generated by the test suite):
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:
npm test -g "array::join"