packages/groqd/CHANGELOG.md

@@ -1,5 +1,21 @@
 # groqd
 
+## 1.2.0
+
+### Minor Changes
+
+- Feature: added `count` method ([#354](https://github.com/FormidableLabs/groqd/pull/354))
+
+  Feature: added `coalesce` method
+
+### Patch Changes
+
+- Fix: always require `[]` when projecting arrays. ([#358](https://github.com/FormidableLabs/groqd/pull/358))
+
+  - Prevents issues with chaining `.deref()` and `.field()`
+  - Makes code clearer
+  - Reduces noise in auto-complete suggestions
+
 ## 1.1.0
 
 ### Minor Changes

packages/groqd/package.json

@@ -1,7 +1,7 @@
 {
   "name": "groqd",
   "description": "GroqD is a GROQ query builder, designed to give the best GROQ developer experience possible, with the flexibility of GROQ, the runtime safety of Zod, and provides schema-aware auto-completion and type-checking.",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "MIT",
   "author": {
     "name": "Formidable",

packages/groqd/src/commands/filter.test.ts

@@ -257,4 +257,23 @@ describe("filterBy", () => {
       `);
     });
   });
+
+  describe("when used in a projection", () => {
+    type VariantImage = NonNullable<SanitySchema.Variant["images"]>[number];
+    const query = q.star.filterByType("variant").project((variant) => ({
+      images: variant.field("images[]").filterBy("asset == null"),
+    }));
+    it("should generate a valid query", () => {
+      expect(query.query).toMatchInlineSnapshot(`
+        "*[_type == "variant"] {
+            "images": images[][asset == null]
+          }"
+      `);
+    });
+    it("should have a valid result type", () => {
+      expectTypeOf<InferResultItem<typeof query>>().toEqualTypeOf<{
+        images: null | Array<VariantImage>;
+      }>();
+    });
+  });
 });

packages/groqd/src/commands/index.ts

@@ -1,3 +1,5 @@
+import "./root/coalesce";
+import "./root/count";
 import "./root/fragment";
 import "./root/parameters";
 import "./root/star";

packages/groqd/src/commands/order.ts

@@ -18,7 +18,6 @@ declare module "../groq-builder" {
 
 GroqBuilder.implement({
   order(this: GroqBuilder, ...fields) {
-    const query = ` | order(${fields.join(", ")})`;
-    return this.pipe(query);
+    return this.pipe(` | order(${fields.join(", ")})`);
   },
 });

packages/groqd/src/commands/root/coalesce-types.ts

@@ -0,0 +1,49 @@
+// eslint-disable-next-line @typescript-eslint/no-namespace
+import { ProjectionPathEntries } from "../../types/projection-paths";
+import { IGroqBuilder } from "../../types/public-types";
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace CoalesceExpressions {
+  /**
+   * Represents the array of args that can be
+   * passed to the `coalesce` method
+   */
+  export type CoalesceArgs<TResult> = ArrayMin2<CoalesceArg<TResult>>;
+
+  type ArrayMin2<T> = [T, T, ...Array<T>];
+
+  type CoalesceArg<TResult> =
+    | keyof ProjectionPathEntries<TResult>
+    | IGroqBuilder;
+
+  /**
+   * Extracts the result type from the `coalesce` method
+   */
+  export type CoalesceResult<
+    TResult,
+    TExpressions extends CoalesceArgs<TResult>
+  > = CoalesceValues<TResult, TExpressions> extends [
+    ...Array<infer TNullableValues>,
+    infer TFinalValue
+  ]
+    ? NonNullable<TNullableValues> | TFinalValue
+    : never;
+
+  type CoalesceValues<
+    TResult,
+    TExpressions extends CoalesceArgs<TResult>,
+    _PathEntries = ProjectionPathEntries<TResult>
+  > = {
+    [Index in keyof TExpressions]: CoalesceExpressionValue<
+      _PathEntries,
+      TExpressions[Index]
+    >;
+  };
+
+  type CoalesceExpressionValue<PathEntries, TExpression> =
+    TExpression extends IGroqBuilder<infer ExpressionResult>
+      ? ExpressionResult
+      : TExpression extends keyof PathEntries
+      ? PathEntries[TExpression]
+      : never; // (unreachable)
+}

packages/groqd/src/commands/root/coalesce.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { q, SanitySchema, zod } from "../../tests/schemas/nextjs-sanity-fe";
+import { InferResultItem, InferResultType } from "../../types/public-types";
+import { executeBuilder } from "../../tests/mocks/executeQuery";
+import { mock } from "../../tests/mocks/nextjs-sanity-fe-mocks";
+
+describe("coalesce", () => {
+  describe("as a root-level query", () => {
+    describe("should have the correct type", () => {
+      it("with literal values", () => {
+        const qAB = q.coalesce(q.value("A"), q.value("B"));
+        expectTypeOf<InferResultType<typeof qAB>>().toEqualTypeOf<"A" | "B">();
+
+        const qABC = q.coalesce(q.value("A"), q.value("B"), q.value("C"));
+        expectTypeOf<InferResultType<typeof qABC>>().toEqualTypeOf<
+          "A" | "B" | "C"
+        >();
+
+        const qA_B = q.coalesce(q.value("A").nullable(), q.value("B"));
+        expectTypeOf<InferResultType<typeof qA_B>>().toEqualTypeOf<"A" | "B">();
+
+        const qA_B_C = q.coalesce(
+          q.value("A").nullable(),
+          q.value("B").nullable(),
+          q.value("C")
+        );
+        expectTypeOf<InferResultType<typeof qA_B_C>>().toEqualTypeOf<
+          "A" | "B" | "C"
+        >();
+
+        const qA_B_C_ = q.coalesce(
+          q.value("A").nullable(),
+          q.value("B").nullable(),
+          q.value("C").nullable()
+        );
+        expectTypeOf<InferResultType<typeof qA_B_C_>>().toEqualTypeOf<
+          "A" | "B" | "C" | null
+        >();
+
+        const qAB_ = q.coalesce(q.value("A"), q.value("B").nullable());
+        expectTypeOf<InferResultType<typeof qAB_>>().toEqualTypeOf<
+          "A" | "B" | null
+        >();
+      });
+    });
+    it("should execute correctly", async () => {
+      const noDataNecessary = { datalake: [] };
+
+      const queryA = q.coalesce(q.value<"A" | null>("A"), q.value("B"));
+      const resultA = await executeBuilder(queryA, noDataNecessary);
+      expect(resultA).toEqual("A");
+
+      const queryB = q.coalesce(q.value<"A" | null>(null), q.value("B"));
+      const resultB = await executeBuilder(queryB, noDataNecessary);
+      expect(resultB).toEqual("B");
+    });
+  });
+
+  describe("in a projection", () => {
+    const qVariants = q.star.filterByType("variant");
+    it("can use a projection string", () => {
+      const qTests = qVariants.project((sub) => ({
+        id_name: sub.coalesce("id", "name"),
+        name_id: sub.coalesce("name", "id"),
+        name_price: sub.coalesce("name", "price"),
+        id_price: sub.coalesce("id", "price"),
+        name_id_price: sub.coalesce("name", "id", "price"),
+      }));
+      expectTypeOf<InferResultItem<typeof qTests>>().toEqualTypeOf<{
+        id_name: string;
+        name_id: string | null;
+        name_price: number | string;
+        id_price: string | number;
+        name_id_price: string | number;
+      }>();
+    });
+    it("can use any nested groq expression", () => {
+      const qTests = qVariants.project((sub) => ({
+        flavour_style: sub.coalesce(
+          sub.field("flavour[]").deref(),
+          sub.field("style[]").deref()
+        ),
+      }));
+      expectTypeOf<InferResultItem<typeof qTests>>().toEqualTypeOf<{
+        flavour_style:
+          | Array<SanitySchema.Flavour>
+          | Array<SanitySchema.Style>
+          | null;
+      }>();
+    });
+
+    const data = mock.generateSeedData({
+      variants: [
+        mock.variant({ id: undefined, _id: "A" }),
+        mock.variant({ id: undefined, _id: "B" }),
+        mock.variant({ id: "C", _id: "FOO" }),
+        mock.variant({ id: undefined, _id: undefined }),
+      ],
+    });
+    it("executes correctly", async () => {
+      const query = qVariants.project((v) => ({
+        coalesceTest: v.coalesce("id", "_id"),
+      }));
+      const results = await executeBuilder(query, data);
+      expect(results).toMatchInlineSnapshot(`
+        [
+          {
+            "coalesceTest": "A",
+          },
+          {
+            "coalesceTest": "B",
+          },
+          {
+            "coalesceTest": "C",
+          },
+          {
+            "coalesceTest": null,
+          },
+        ]
+      `);
+    });
+    it("executes correctly with validation", async () => {
+      const query = qVariants.project((v) => ({
+        coalesceTest: v.coalesce(
+          v.field("id", zod.string().nullable()),
+          v.field("_id", zod.string().nullable()),
+          q.value("DEFAULT", zod.literal("DEFAULT"))
+        ),
+      }));
+      const results = await executeBuilder(query, data);
+      expect(results).toMatchInlineSnapshot(`
+        [
+          {
+            "coalesceTest": "A",
+          },
+          {
+            "coalesceTest": "B",
+          },
+          {
+            "coalesceTest": "C",
+          },
+          {
+            "coalesceTest": "DEFAULT",
+          },
+        ]
+      `);
+
+      const invalidData = mock.generateSeedData({
+        variants: [
+          mock.variant({
+            // @ts-expect-error ---
+            id: 55,
+          }),
+          mock.variant({
+            // @ts-expect-error ---
+            _id: 66,
+          }),
+        ],
+      });
+      await expect(() => executeBuilder(query, invalidData)).rejects
+        .toThrowErrorMatchingInlineSnapshot(`
+        [ValidationErrors: 4 Parsing Errors:
+        result[0].coalesceTest: Expected string, received number
+        result[0].coalesceTest: Expected string, received number
+        result[0].coalesceTest: Invalid literal value, expected "DEFAULT"
+        result[0].coalesceTest: Expected the value to match one of the values above, but got: 55]
+      `);
+    });
+  });
+
+  describe("with validation", () => {
+    const valueA = q.value("A", q.literal("A"));
+    const valueB = q.value("B", q.literal("B"));
+    const valueANull = q.value("A", q.literal("A").nullable());
+
+    describe("when all expressions include validation", () => {
+      const query = q.coalesce(valueANull, valueA, valueB);
+      it("should allow all expressions to include validation", () => {
+        expect(query.parser).toBeDefined();
+      });
+      it("should parse valid inputs without problem", () => {
+        query.parse("A");
+        query.parse("B");
+        query.parse(null);
+      });
+      it("should throw errors when the input is invalid", () => {
+        expect(() => {
+          query.parse("INVALID");
+        }).toThrowErrorMatchingInlineSnapshot(`
+          [ValidationErrors: 4 Parsing Errors:
+          result: Invalid literal value, expected "A"
+          result: Invalid literal value, expected "A"
+          result: Invalid literal value, expected "B"
+          result: Expected the value to match one of the values above, but got: "INVALID"]
+        `);
+      });
+    });
+    describe("when only some expressions include validation", () => {
+      it("should throw an InvalidQueryError", () => {
+        expect(() => {
+          q.coalesce(valueA, q.value("NOT VALIDATED"));
+        }).toThrowErrorMatchingInlineSnapshot(
+          `[Error: [COALESCE_MISSING_VALIDATION] With 'coalesce', you must supply validation for either all, or none, of the expressions. You did not supply validation for ""NOT VALIDATED""]`
+        );
+        expect(() => {
+          q.coalesce(valueA, q.value("NOT VALIDATED"), valueB, q.value("SAME"));
+        }).toThrowErrorMatchingInlineSnapshot(
+          `[Error: [COALESCE_MISSING_VALIDATION] With 'coalesce', you must supply validation for either all, or none, of the expressions. You did not supply validation for ""NOT VALIDATED"" or ""SAME""]`
+        );
+      });
+    });
+  });
+});