groq-builder

A schema-aware, strongly-typed GROQ query builder.
It enables you to build GROQ queries using auto-completion, type-checking, and runtime validation.

What is GROQ?

GROQ is Sanity's open-source query language.

"It's a powerful and intuitive language that's easy to learn. With GROQ you can describe exactly what information your application needs, join information from several sets of documents, and stitch together a very specific response with only the exact fields you need."

Features

• Schema-aware - uses your sanity.config.ts schema for auto-completion and type-checking.
• Strongly-typed - query results are strongly typed, based on your Sanity schema.
• Runtime validation - validate, parse, and transform query results at run-time, with broad or granular levels.

Brought to you by the team behind GroqD

groq-builder is the successor to GroqD. In addition to runtime validation and strongly-typed results, groq-builder adds schema-awareness and auto-completion.

Example

1import { createGroqBuilder } from 'groq-builder';
2import type { SchemaConfig } from './schema-config';
3//            ☝️ Note:
4// Please see the "Schema Configuration" docs 
5// for an overview of this SchemaConfig type 
6
7const q = createGroqBuilder<SchemaConfig>()
8
9const productsQuery = (
10  q.star
11   .filterByType('products')
12   .order('price desc')
13   .slice(0, 10)
14   .project(q => ({
15     name: true,
16     price: true,
17     slug: q.field("slug.current"),
18     imageUrls: q.field("images[]").deref().field("url")
19   }))
20);

In the above query, ALL fields are strongly-typed, according to the Sanity schema defined in sanity.config.ts!

• All the strings above are strongly-typed, based on field definitions, including 'products', 'price desc', 'slug.current', 'images[]', and 'url'.
• In the projection, the keys name and price have auto-completion, and are strongly-typed, based on the fields of product.
• In the projection, the keys slug and imageUrls are strongly-typed based on their sub-queries.

Example Query:

This example above generates the following GROQ query:

1*[_type == "products"] | order(price desc)[0...10] {
2  name,
3  price,
4  "slug": slug.current,
5  "imageUrls": images[]->url
6}

Example Types:

The example above also generates the following result type:

1import type { InferResultType } from 'groq-builder';
2
3type ProductsQueryResult = InferResultType<typeof productsQuery>;
4//   👆 Evaluates to the following:
5type ProductsQueryResult = Array<{
6  name: string,
7  price: number,
8  slug: string,
9  imageUrls: Array<string>,
10}>;

Runtime Validation

groq-builder enables effortless runtime validation using Zod:

1import { z } from 'zod';
2
3const products = q.star.filterByType('products').project(q => ({
4  name: z.string(),
5  slug: ["slug.current", z.string()],
6  price: q.field("price", z.number().nonnegative()),
7}));

Custom Parsing

Validation methods can include custom validation and/or parsing logic too:

1const products = q.star.filterByType('products').project(q => ({
2  price: z.number(),
3  priceFormatted: q.field("price", price => formatCurrency(price)),
4}));

Sanity Schema Configuration

To support auto-completion and maximum type-safety, you must configure groq-builder by providing type information for your Sanity Schema.

Fortunately, the Sanity CLI supports a typegen command that will generate the Sanity Schema Types for you!

Generating Sanity Schema Types

First, in your Sanity Studio project (where you have your sanity.config.ts), follow the Sanity documentation to run the following commands:

1sanity schema extract --enforce-required-fields
2sanity typegen generate

This generates a sanity.types.ts file, which contains type definitions for all your Sanity documents.

Second, copy the newly generated sanity.types.ts into your application (where you intend to use groq-builder).

Configuring groq-builder with your Sanity Schema:

In your application, you can create a strongly-typed groq-builder using the following snippet:

1// ./q.ts
2import { createGroqBuilder, ExtractDocumentTypes } from 'groq-builder';
3import { AllSanitySchemaTypes, internalGroqTypeReferenceTo } from "./sanity.types.ts";
4
5type SchemaConfig = {
6  documentTypes: ExtractDocumentTypes<AllSanitySchemaTypes>;
7  referenceSymbol: typeof internalGroqTypeReferenceTo;
8};
9export const q = createGroqBuilder<SchemaConfig>();

And that's it! Wherever you write queries, be sure to import this strongly-typed q and you'll get full auto-completion and type-safety!

1import { q } from './q';
2
3const productQuery = q.star.filterByType('product');