filter: support multiple expressions (#387)

Author: scottrippey

.changeset/selfish-bees-smoke.md

@@ -0,0 +1,6 @@
+---
+"groqd": patch
+"website": patch
+---
+
+`filterBy`: support multiple expressions.  Expressions will be combined using the `||` "OR" operator.

packages/groqd/src/commands/as.ts

@@ -28,7 +28,7 @@ declare module "../groq-builder" {
      * Use this carefully, since it's essentially "lying" to TypeScript, and there's no runtime validation.
      *
      * @example
-     * q.star.filter("slug.current == $productSlug").as<Product>()...
+     * q.star.filterBy("slug.current == $productSlug").as<Product>()...
      *
      */
     as<TResultNew>(): GroqBuilderOfType<TResultNew, TQueryConfig, ReturnType>;
@@ -39,7 +39,7 @@ declare module "../groq-builder" {
      * Use this carefully, since it's essentially "lying" to TypeScript, and there's no runtime validation.
      *
      * @example
-     * q.star.filter("slug.current == $productSlug").asType<"product">()...
+     * q.star.filterBy("slug.current == $productSlug").asType<"product">()...
      */
     asType<
       _type extends ExtractDocumentTypes<TQueryConfig["schemaTypes"]>

packages/groqd/src/commands/filter.ts

@@ -280,4 +280,57 @@ describe("filterBy", () => {
       }>();
     });
   });
+
+  describe("should support multiple filters", () => {
+    const qMultiple = q.star
+      .filterByType("variant")
+      .filterBy("msrp < 50", "price <= 50")
+      .project({ name: true, msrp: true, price: true });
+    it("should have the correct type", () => {
+      expectTypeOf<InferResultItem<typeof qMultiple>>().toEqualTypeOf<{
+        name: string;
+        msrp: number;
+        price: number;
+      }>();
+    });
+    it("should generate the correct query", () => {
+      expect(qMultiple.query).toMatchInlineSnapshot(`
+        "*[_type == "variant"][msrp < 50 || price <= 50] {
+            name,
+            msrp,
+            price
+          }"
+      `);
+    });
+    it("should execute correctly", async () => {
+      const data = mock.generateSeedData({
+        variants: [
+          mock.variant({ name: "Yes 1", price: 99, msrp: 5 }),
+          mock.variant({ name: "Yes 2", price: 5, msrp: 99 }),
+          mock.variant({ name: "No", price: 99, msrp: 99 }),
+          mock.variant({ name: "Yes 3", price: 5, msrp: 5 }),
+        ],
+      });
+      const result = await executeBuilder(qMultiple, data);
+      expect(result).toMatchInlineSnapshot(`
+        [
+          {
+            "msrp": 5,
+            "name": "Yes 1",
+            "price": 99,
+          },
+          {
+            "msrp": 99,
+            "name": "Yes 2",
+            "price": 5,
+          },
+          {
+            "msrp": 5,
+            "name": "Yes 3",
+            "price": 5,
+          },
+        ]
+      `);
+    });
+  });
 });

…ckages/groqd/src/commands/filter.test.ts …ages/groqd/src/commands/filterBy.test.tspackages/groqd/src/commands/filter.test.ts renamed to packages/groqd/src/commands/filterBy.test.ts packages/groqd/src/commands/filter.test.ts renamed to packages/groqd/src/commands/filterBy.test.ts

@@ -0,0 +1,89 @@
+import { GroqBuilder } from "../groq-builder";
+import { Expressions } from "../types/groq-expressions";
+import { ConfigCreateNestedScope } from "../types/query-config";
+import { ResultItem } from "../types/result-types";
+
+declare module "../groq-builder" {
+  export interface GroqBuilder<TResult, TQueryConfig> {
+    /**
+     * This is an alias for the `filterRaw` method; please use that instead.
+     *
+     * Filters based on any raw filter expression.
+     * This method is NOT type-checked, but does provide suggestions.
+     *
+     * @deprecated Please use `filterRaw` instead!
+     *
+     * @example
+     * q.star.filterRaw("count(items[]) > 5")
+     *
+     * @param filterExpression - Any valid GROQ expression that can be used for filtering
+     */
+    filter(
+      ...filterExpression: NonEmptyArray<
+        Expressions.AnyConditional<ResultItem.Infer<TResult>, TQueryConfig>
+      >
+    ): GroqBuilder<TResult, TQueryConfig>;
+
+    /**
+     * Filters based on any raw filter expression(s).
+     * This method is NOT type-checked, but does provide suggestions.
+     *
+     * Multiple expressions will be combined with "OR" logic.
+     *
+     * @example
+     * q.star.filterRaw("count(items[]) > 5")
+     *
+     * @param filterExpression - Any valid GROQ expression that can be used for filtering
+     */
+    filterRaw(
+      ...filterExpression: NonEmptyArray<
+        Expressions.AnyConditional<
+          ResultItem.Infer<TResult>,
+          ConfigCreateNestedScope<TQueryConfig, ResultItem.Infer<TResult>>
+        >
+      >
+    ): GroqBuilder<TResult, TQueryConfig>;
+
+    /**
+     * Filters the results based on a simple,
+     * strongly-typed equality expression.
+     *
+     * Multiple calls will result in "AND" logic.
+     * Multiple arguments will be combined with "OR" logic.
+     *
+     * This method is strongly-typed, but only supports common expressions.
+     * If you'd like to filter based off more complex logic, use `filterRaw` instead.
+     *
+     * @example
+     * q.star.filterByType("product")
+     *  .filterBy("image.url != null")
+     *  .filterBy('category == "food"')
+     *  .filterBy("price < 50", "msrp < 50")
+     *  .filterBy("references(^._id)")
+     */
+    filterBy(
+      ...filterExpression: NonEmptyArray<
+        Expressions.Conditional<
+          ResultItem.Infer<TResult>,
+          ConfigCreateNestedScope<TQueryConfig, ResultItem.Infer<TResult>>
+        >
+      >
+    ): GroqBuilder<TResult, TQueryConfig>;
+  }
+}
+
+type NonEmptyArray<T> = [T, ...T[]];
+
+GroqBuilder.implement({
+  filter(this: GroqBuilder, ...filterExpressions) {
+    return this.filterRaw(...filterExpressions);
+  },
+  filterRaw(this: GroqBuilder, ...filterExpressions) {
+    const needsWrap = this.query.endsWith("->");
+    const self = needsWrap ? this.extend({ query: `(${this.query})` }) : this;
+    return self.chain(`[${filterExpressions.join(" || ")}]`, "passthrough");
+  },
+  filterBy(this: GroqBuilder, ...filterExpressions) {
+    return this.filterRaw(...filterExpressions);
+  },
+});

packages/groqd/src/commands/filterBy.ts

@@ -13,7 +13,7 @@ import "./subquery/selectByType";
 import "./as";
 import "./asCombined";
 import "./deref";
-import "./filter";
+import "./filterBy";
 import "./filterByType";
 import "./grab-deprecated";
 import "./notNull";

packages/groqd/src/commands/index.ts

@@ -15,7 +15,7 @@ declare module "../groq-builder" {
      *
      * @example
      * q.star
-     *  .filter("slug.current == $slug")
+     *  .filterBy("slug.current == $slug")
      *  .slice(0) // <- this return type is nullable, even though we expect there will be a match
      *  .project({ name: z.string() })
      *  .notNull() // <- this ensures that the results are not null

packages/groqd/src/commands/notNull.ts

@@ -20,7 +20,7 @@ describe("parameters", () => {
   const qWithParameters = q
     .parameters<{ slug: string }>()
     .star.filterByType("variant")
-    .filter("slug.current == $slug")
+    .filterBy("slug.current == $slug")
     .project({ slug: "slug.current" });
 
   it("chains should retain the parameters type", () => {

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

@@ -21,7 +21,7 @@ interface StarDefinition<TResult, TQueryConfig extends QueryConfig> {
    * This is how most queries start.
    *
    * @example
-   * q.star.filter(...).project(...)
+   * q.star.filterByType(...).project(...)
    *
    */
   star: GroqBuilder<

packages/groqd/src/commands/root/star.ts

@@ -11,7 +11,7 @@ Selects all documents, via GROQ's `*` selector.
 This is how most queries start.
 
 ```ts
-q.star.filter(...).project(...)
+q.star.filterByType(...).project(...)
 ```
 
 ## `.filterByType(type)`
@@ -36,10 +36,10 @@ q.star
  .filterBy('category == "shoe"')
 ```
 
-> For more complex expressions, use `.filter(expression)`:
+> For more complex expressions, use `.filterRaw(expression)`:
 
 
-## `.filter(expression)`
+## `.filterRaw(expression)`
 
 Filters the query based on **any** GROQ expression.
 
@@ -48,7 +48,7 @@ Filters the query based on **any** GROQ expression.
 ```ts
 q.star
  .filterByType("product")
- .filter("price >= 50");
+ .filterRaw("price >= 50");
 // Result GROQ: *[_type == "product"][price >= 50]
 // Result Type: Product[]
 ```
@@ -65,25 +65,6 @@ q.star
 // Result Type: Product[]
 ```
 
-<!--    
-    ## `.score(expression)`
-    ## `.score(expression)`
-    
-    Used to pipe a list of results through the `score` GROQ function.
-    
-    ```ts
-    // Fetch first 9 Pokemon's names, bubble Char* (Charmander, etc) to the top.
-    q.star
-      .filter("_type == 'pokemon'")
-      .slice(0, 8)
-      .score(`name match "char*"`)
-      .order("_score desc")
-      .grabOne("name", z.string());
-    ```
--->
-
-
-
 ## `.slice(index)`
 
 Returns a single item from the results, based on the index.