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
• Learn GROQ
• Versioning
  • GROQ
  • GROQ-JS
• Releasing a new version of GROQ-JS
• License
• Tests

Installation

npm i groq-js

yarn add groq-js

pnpm install 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

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

Version will be automatically bumped based on conventional 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 with chore: will be ignored. If you want updated dependencies to trigger a new version, use fix(deps): instead.

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.5.0 (2024-03-19)

Features

• access optinal attributes should return null (8e3f7e4)
• add support for slice in type evaluator (7877990)
• add tsdoc to describe the type nodes (65cbc41)
• add type evaluator (637603b)
• evaluateQueryType: add more tests (#180) (5d2528e)
• export type evaluation with version 1 (62c6b7f)
• only export typeEvaluate function (e3e3875)
• replace esbuild with tsx. fixes linenumber (8a60c87)
• typeEvaluator: rename main function to typeEvaluate (9c2f345)

Bug Fixes

• dont access attributes inside arrays (0e267bc)
• dont stringify objects, let debug/util handle it (bb7d646)
• forward type on map unexpected (8131a71)
• handle flatmap over unions correctly (70dc0c3)
• order unions (5a940e0)
• query node type eval tests (522bd9b)
• recursively lookup attributes in object rest (fecc1a1)
• refactor and reuse scope handling from evaluator (7bed827)
• remove un-evaluated Slice-case (349645b)
• typeEvaluate: resolve inline when mapping type (7a3742c)
• update snapshots (0860eaf)
• various type evaluation bugs (3da42d7)