groqd

GroqD is a GROQ query builder, designed to give the best GROQ developer experience possible.

It gives you the flexibility of GROQ, the runtime safety of Zod, and provides schema-aware auto-completion and type-checking.

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

Documentation

Read the official documentation at https://commerce.nearform.com/open-source/groqd/docs/

Usage Example

GroqD uses a strongly-typed chaining syntax to build queries:

import { createGroqBuilder, z } from 'groqd';
// 👇 Import Sanity types, generated by your Sanity project. See "Configuration" docs for more details.
import type * as SanityTypes from "./sanity.types.ts";

// 👇 Create a strongly-typed query builder:
const q = createGroqBuilder<{
  schemaTypes: SanityTypes.AllSanitySchemaTypes
  referenceSymbol: typeof SanityTypes.internalGroqTypeReferenceTo;
}>();

// ✨ Write strongly-typed queries, with auto-complete and runtime safety!
const productsQuery = (
  q.star
   .filterByType("products")
   .order("price desc")
   .slice(0, 10)
   .project(sub => ({
     name: z.string(),
     price: z.number(),
     slug: sub.field("slug.current", z.string()),
     imageUrls: sub.field("images[]").field("asset").deref().field("url", z.string())
   }))
);

Everything in the above query is strongly-typed, according to the Sanity schema defined in your sanity.config.ts. This means you get auto-complete for all strings, including "price desc" and "slug.current"!

The example above generates a GROQ query like this:

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

and executing the query will return strongly-typed results:

const results = await runQuery(productsQuery);
/*
 * results: Array<{ 
 *   name: string,
 *   price: number,
 *   slug: string,
 *   imageUrls: Array<string>,
 * }>
 */

Why GroqD over raw GROQ?

Sanity's CLI can generate types from your raw GROQ queries. This works well for simple use-cases.
However, GroqD aims to maximize the developer experience, improve generated types, and ensure scalability. Namely, it adds:

• Auto-completion - write queries quickly and confidently
• Runtime validation - ensure data integrity, catch errors early
• Transformation - map values at runtime, like parsing dates
• Fragments - create reusable query fragments, and compose queries from other fragments