Repository files navigation

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

import{parse,evaluate}from'groq-js'letinput='*[_type == "user"]{name}'// Returns an ESTree-inspired syntax treelettree=parse(input)letdataset=[{_type:'user',name:'Michael'},{_type:'company',name:'Bluth Company'},]// Evaluate a tree against a datasetletvalue=awaitevaluate(tree,{dataset})// Gather everything into one JavaScript objectletresult=awaitvalue.get()console.log(result)

Table of contents:

• Installation
• Documentation
• Learn GROQ
• Versioning
  • GROQ
  • GROQ-JS
• Releasing a new version of GROQ-JS
• License
• Tests

npm i groq-js

yarn add groq-js

pnpm install groq-js

SeeAPI.md for the public API.

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

GROQ-JS followsSemVer.Seethe changelog for recent changes.This is an "experimental" release and anythingmay 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 isnot considered a public API and may change at any time.
• This package always implements the latest version ofGROQ according to the specification.

Run the"CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Version will be automatically bumped based onconventional commits since the last release.

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

Note: commits withchore: will be ignored. If you want updated dependencies to triggera new version, usefix(deps): instead.

MIT ©Sanity.io

Tests are written inJest:

# Install dependenciesnpm i# Run testsnpmtest

You can also generate tests fromthe official GROQ test suite:

# Fetch and generate test file:./test/generate.sh# Run tests as usual:npmtest

You can generate tests from a specific version:

GROQTEST_SUITE_VERSION=v1.0.0 ./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 totap, so you can use arguments, e.g. to run a specific set of tests:

npmtest -g"array::join"