groq-builder: implement "conditionals" feature (target fixed)

.changeset/fast-pianos-occur.md

@@ -0,0 +1,7 @@
+---
+"groq-builder": minor
+---
+
+Improved the way we handle validation.
+Enable "tree shaking" to remove validation, if unused.
+Improve type-checking of validation methods, for better error detection.

packages/groq-builder/docs/CONDITIONALS.md

@@ -0,0 +1,132 @@
+# Conditionals
+
+In Groq, there are 2 ways to use conditional logic: inline in a projection, or using the `select` function.
+
+## Conditions in a projection
+
+In `groq-builder`, the `project` method allows inline conditional statements with the help of `q.conditional$(...)` or `q.conditionalByType(...)` using the following syntax:
+
+```ts
+const contentQuery = q.star
+  .filterByType("movie", "actor")
+  .project({
+    slug: "slug.current",
+    ...q.conditional$({
+      "_type == 'movie'": { title: "title", subtitle: "description" },
+      "_type == 'actor'": { title: "name", subtitle: "biography" },
+    }),
+  });
+```
+
+This outputs the following groq query:
+```groq
+*[_type == "movie" || _type == "actor"] {
+  "slug": slug.current,
+  _type == 'movie' => {
+    title,
+    "subtitle": description
+  },
+  _type == 'actor' => {
+    "title": name,
+    "subtitle": biography
+  }
+}
+```
+
+And the result type is inferred as:
+```ts
+type ContentResults = InferResultType<typeof contentQuery>;
+// Same as:
+type ContentResults = Array<
+  | { slug: string }
+  | { slug: string, title: string, subtitle: string }
+>;
+```
+
+Notice that the conditions are wrapped in `q.conditional$()` and then spread into the projection.  This is necessary for type-safety and runtime validation.
+
+The `$` in the method `q.conditional$` indicates that this method is not completely type-safe; the condition statements (eg. `_type == 'movie'`) are not strongly-typed (this may be improved in a future version).
+
+However, the most common use-case is to base conditional logic off the document's `_type`.  For this, we have the `q.conditionalByType` helper:
+
+### Strongly-typed conditions via `q.conditionalByType(...)`
+
+The most common use-case for conditional logic is to check the `_type` field. 
+The `q.conditionalByType(...)` method makes this easier, by ensuring all conditional logic is strongly-typed, and it enables auto-complete.  For example:
+
+```ts
+const contentQuery = q.star
+  .filterByType("movie", "actor")
+  .project(q => ({
+    slug: "slug.current",
+    ...q.conditionalByType({
+      movie: { title: "title", subtitle: "description" },
+      actor: { title: "name", subtitle: "biography" },
+    })
+  }));
+```
+
+The resulting query is identical to the above example with `q.conditional$`.
+
+The result type here is inferred as:
+
+```ts
+type ContentResult = InferResultType<typeof contentQuery>;
+// Same as:
+type ContentResult = Array<
+  { slug: string, title: string, subtitle: string }
+>
+```
+
+Notice that this type is stronger than the example with `q.conditional$`, because we've detected that the conditions are "exhaustive". 
+
+## The `select` method
+
+Adds support for the `select$` method:
+```ts
+const qMovies = q.star.filterByType("movie").project({
+  name: true,
+  popularity: q.select$({
+    "popularity > 20": q.value("high"),
+    "popularity > 10": q.value("medium"),
+  }, q.value("low")),
+});
+```
+
+The `$` sign is to indicate that there's some "loosely typed" code in here -- the conditions are unchecked.
+
+This will output the following query:
+```groq
+*[_type == "movie"] {
+  name,
+  "popularity": select(
+    popularity > 20 => "high",
+    popularity > 10 => "medium",
+    "low"
+  )
+}
+```
+
+And will have the following result type:
+```ts
+type MoviesResult = InferResultType<typeof qMovies>;
+// Same as:
+type MoviesResult = Array<{
+  name: string
+  popularity: "high" | "medium" | "low"
+}>
+```
+
+
+## The `selectByType` method
+
+Adds a `selectByType` helper, which facilitates type-based logic.  This is completely strongly-typed:
+```ts
+const qContent = q.star.filterByType("movie", "actor").project(q => ({
+  name: q.selectByType({
+    movie: q => q.field("title"),
+    actor: q => q.field("name"),
+  })
+}));
+```
+

packages/groq-builder/docs/MIGRATION.md

@@ -26,8 +26,9 @@ const productsQuery = q("*")
 #### After, with `groq-builder`
 
 ```ts
-import { createGroqBuilderWithValidation } from "groq-builder";
-const q = createGroqBuilderWithValidation<any>(); // Using 'any' makes the query schema-unaware 
+import { createGroqBuilder, validation } from "groq-builder";
+// Using 'any' makes the query schema-unaware: 
+const q = createGroqBuilder<any>().include(validation); 
 
 const productsQuery = q.star
   .filterByType("product")
@@ -52,15 +53,17 @@ Keep reading for a deeper explanation of these changes.
 
 ```ts
 // src/queries/q.ts
-import { createGroqBuilder } from 'groq-builder';
+import { createGroqBuilder, validation } from 'groq-builder';
 type SchemaConfig = any;
-export const q = createGroqBuilder<SchemaConfig>();
+export const q = createGroqBuilder<SchemaConfig>().include(validation);
 ```
 
 By creating the root `q` this way, we're able to bind it to our `SchemaConfig`.  
 By using `any` for now, our `q` will be schema-unaware (same as `groqd`).  
 Later, we'll show you how to change this to a strongly-typed schema.
 
+We also call `.include(validation)` to extend the root `q` with our validation methods, like `q.string()`.
+This is for convenience and compatibility.
 
 ## Step 2: Replacing the `q("...")` method
 

packages/groq-builder/src/commands/conditional$.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "vitest";
+import {
+  createGroqBuilder,
+  GroqBuilder,
+  InferResultItem,
+  InferResultType,
+} from "../index";
+import { SchemaConfig } from "../tests/schemas/nextjs-sanity-fe";
+import { ExtractConditionalProjectionTypes } from "./conditional-types";
+import { expectType } from "../tests/expectType";
+import { Empty, Simplify } from "../types/utils";
+
+const q = createGroqBuilder<SchemaConfig>({ indent: "  " });
+const qBase = q.star.filterByType("variant");
+
+describe("conditional$", () => {
+  describe("by itself", () => {
+    const conditionalResult = q.star.filterByType("variant").conditional$({
+      "price == msrp": {
+        onSale: q.value(false),
+      },
+      "price < msrp": {
+        onSale: q.value(true),
+        price: true,
+        msrp: true,
+      },
+    });
+
+    it("we should be able to extract the intersection of projection types", () => {
+      expectType<
+        Simplify<ExtractConditionalProjectionTypes<typeof conditionalResult>>
+      >().toStrictEqual<
+        | Empty
+        | { onSale: false }
+        | { onSale: true; price: number; msrp: number }
+      >();
+    });
+    it("should return a spreadable object", () => {
+      expect(conditionalResult).toMatchObject({
+        "[Conditional] [$]": expect.any(GroqBuilder),
+      });
+    });
+  });
+
+  const qAll = qBase.project((qA) => ({
+    name: true,
+    ...qA.conditional$({
+      "price == msrp": {
+        onSale: q.value(false),
+      },
+      "price < msrp": {
+        onSale: q.value(true),
+        price: true,
+        msrp: true,
+      },
+    }),
+  }));
+
+  it("should be able to extract the return type", () => {
+    expectType<InferResultType<typeof qAll>>().toStrictEqual<
+      Array<
+        | { name: string }
+        | { name: string; onSale: false }
+        | { name: string; onSale: true; price: number; msrp: number }
+      >
+    >();
+  });
+
+  it("the query should look correct", () => {
+    expect(qAll.query).toMatchInlineSnapshot(
+      `
+      "*[_type == \\"variant\\"] {
+          name,
+          price == msrp => {
+              \\"onSale\\": false
+            },
+          price < msrp => {
+              \\"onSale\\": true,
+              price,
+              msrp
+            }
+        }"
+    `
+    );
+  });
+
+  describe("multiple conditionals", () => {
+    describe("without using unique keys", () => {
+      const qIncorrect = q.star.filterByType("variant").project((qV) => ({
+        name: true,
+        ...qV.conditional$({
+          "price == msrp": {
+            onSale: q.value(false),
+          },
+          "price < msrp": {
+            onSale: q.value(true),
+            price: true,
+            msrp: true,
+          },
+        }),
+        // Here we're trying to spread another conditional,
+        // however, it will override the first one
+        // since we didn't specify a unique key:
+        ...qV.conditional$({
+          "second == condition": { price: true },
+        }),
+      }));
+
+      it("the type will be missing the first conditionals", () => {
+        expectType<InferResultType<typeof qIncorrect>>().toStrictEqual<
+          Array<{ name: string } | { name: string; price: number }>
+        >();
+      });
+      it("the query will also be missing the first conditionals", () => {
+        expect(qIncorrect.query).toMatchInlineSnapshot(`
+          "*[_type == \\"variant\\"] {
+              name,
+              second == condition => {
+                  price
+                }
+            }"
+        `);
+      });
+    });
+
+    describe("with different keys", () => {
+      const qMultipleConditions = q.star
+        .filterByType("variant")
+        .project((qV) => ({
+          name: true,
+          ...qV.conditional$({
+            "price == msrp": {
+              onSale: q.value(false),
+            },
+            "price < msrp": {
+              onSale: q.value(true),
+              price: true,
+              msrp: true,
+            },
+          }),
+          ...qV.conditional$(
+            {
+              "another == condition1": { foo: q.value("FOO") },
+              "another == condition2": { bar: q.value("BAR") },
+            },
+            { key: "unique-key" }
+          ),
+        }));
+
+      it("the types should be inferred correctly", () => {
+        type ActualItem = InferResultItem<typeof qMultipleConditions>;
+        type ExpectedItem =
+          | { name: string }
+          | { name: string; onSale: false }
+          | { name: string; onSale: true; price: number; msrp: number }
+          | { name: string; foo: "FOO" }
+          | { name: string; onSale: false; foo: "FOO" }
+          | {
+              name: string;
+              onSale: true;
+              price: number;
+              msrp: number;
+              foo: "FOO";
+            }
+          | { name: string; bar: "BAR" }
+          | { name: string; onSale: false; bar: "BAR" }
+          | {
+              name: string;
+              onSale: true;
+              price: number;
+              msrp: number;
+              bar: "BAR";
+            };
+
+        type Remainder = Exclude<ActualItem, ExpectedItem>;
+        expectType<Remainder>().toStrictEqual<never>();
+        expectType<ActualItem>().toStrictEqual<ExpectedItem>();
+      });
+
+      it("the query should be compiled correctly", () => {
+        expect(qMultipleConditions.query).toMatchInlineSnapshot(`
+          "*[_type == \\"variant\\"] {
+              name,
+              price == msrp => {
+                  \\"onSale\\": false
+                },
+              price < msrp => {
+                  \\"onSale\\": true,
+                  price,
+                  msrp
+                },
+              another == condition1 => {
+                  \\"foo\\": \\"FOO\\"
+                },
+              another == condition2 => {
+                  \\"bar\\": \\"BAR\\"
+                }
+            }"
+        `);
+      });
+    });
+  });
+});