groq-js

What is groq-js?

The groq-js package is a JavaScript implementation of GROQ (Graph-Relational Object Queries), a query language designed for querying JSON documents. It allows you to perform complex queries on JSON data structures, making it particularly useful for applications that need to filter, sort, and transform JSON data.

What are groq-js's main functionalities?

Basic Querying

This feature allows you to perform basic queries on JSON data. In this example, the query fetches all objects of type 'person' from the data.

const groq = require('groq-js');
const data = { "name": "John", "age": 30 };
const query = '*[_type == "person"]';
const result = groq.evaluate(query, data);
console.log(result);

Filtering

This feature allows you to filter JSON data based on specific conditions. In this example, the query fetches all objects where the age is greater than 25.

const groq = require('groq-js');
const data = [
  { "name": "John", "age": 30 },
  { "name": "Jane", "age": 25 }
];
const query = '*[age > 25]';
const result = groq.evaluate(query, data);
console.log(result);

Projection

This feature allows you to project specific fields from JSON data. In this example, the query fetches only the 'name' and 'city' fields from the data.

const groq = require('groq-js');
const data = { "name": "John", "age": 30, "address": { "city": "New York" } };
const query = '{ name, address.city }';
const result = groq.evaluate(query, data);
console.log(result);

Sorting

This feature allows you to sort JSON data based on specific fields. In this example, the query sorts the objects by age in descending order.

const groq = require('groq-js');
const data = [
  { "name": "John", "age": 30 },
  { "name": "Jane", "age": 25 }
];
const query = '* | order(age desc)';
const result = groq.evaluate(query, data);
console.log(result);

Other packages similar to groq-js

json-query

The json-query package allows you to query JSON data using a simple query language. It is similar to groq-js in that it provides filtering, sorting, and projection capabilities, but it uses a different syntax and may not support all the advanced features of GROQ.

jmespath

The jmespath package is a query language for JSON, similar to groq-js. It allows you to search, filter, and transform JSON data. JMESPath is known for its powerful and flexible query capabilities, but it has a different syntax compared to GROQ.

jsonpath

The jsonpath package provides a way to query JSON data using a path-based syntax. It is similar to groq-js in that it allows for complex queries, but it uses a different approach and syntax. JSONPath is widely used and has a strong community support.

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
• Documentation
• Versioning
• License
• Tests

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:

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:

# 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"

Changelog

1.1.2 (2023-01-12)

Bug Fixes

• add sideEffects: false for better tree-shaking (77b3366)
• setup release automation (f676dff)
• support swcMinify in NextJS 13 (9beabc1)