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 (work-in-progress) 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.

Versioning

GROQ-JS follows SemVer and is currently at version v0.2. 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 version.
• 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.
• The goal is to release a v1.0.0 by the end of 2020.

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:

# Fecth and generate test file:
./test/generate.sh

# Run tests as usual:
npm test

Changelog

v0.2.0 - 2020-10-20

• Require native generators (@rexxars)
• Support concatenation of arrays (@rexxars)
• Correctly fail on invalid asc/desc (@judofyr)
• Projection should not be mapped inside traversals (@judofyr)
• getType: Detect Pair correctly (@judofyr)
• Add support for object merging (@judofyr)
• Improve match semantics (@judofyr)
• Fix ESM build (@rexxars)