feat(client): Allow the client to be used more flexibly (#274)

max-scopp · Max Scopp · web-flow · commit c4bd16c88b70 · 2025-06-01T14:57:42.000+02:00
* feat(client): Allow the client to be used more flexibly

* chore: extend test cases

* docs(client): extend documentation for GridifyQueryBuilder options and methods

---------

Co-authored-by: Max Scopp &lt;mscopp@tesla.com&gt;
diff --git a/client/src/GridifyQueryBuilder.ts b/client/src/GridifyQueryBuilder.ts
@@ -1,15 +1,25 @@
 import { ConditionalOperator, LogicalOperator } from "./GridifyOperator";
+import { GridifyQueryBuilderOptions } from "./GridifyQueryBuilderOptions";
 import { IGridifyQuery } from "./IGridifyQuery";
 
 export class GridifyQueryBuilder {
-   private query: IGridifyQuery = {
+   protected query: IGridifyQuery = {
       page: 1,
       pageSize: 20,
       orderBy: "",
       filter: "",
    };
 
-   private filteringExpressions: IExpression[] = [];
+   protected filteringExpressions: IExpression[] = [];
+
+   constructor(protected readonly options: GridifyQueryBuilderOptions = {}) {
+      if (options.from) {
+         const builder = options.from;
+
+         this.query = { ...builder.query };
+         this.filteringExpressions = builder.filteringExpressions.map((exp) => ({ ...exp }));
+      }
+   }
 
    setPage(page: number): GridifyQueryBuilder {
       this.query.page = page;
@@ -69,16 +79,21 @@ export class GridifyQueryBuilder {
       return this;
    }
 
-   and(): GridifyQueryBuilder {
+   and(optional?: boolean): GridifyQueryBuilder {
       this.filteringExpressions.push({
          value: LogicalOperator.And,
          type: "op",
+         optional
       });
       return this;
    }
 
-   or(): GridifyQueryBuilder {
-      this.filteringExpressions.push({ value: LogicalOperator.Or, type: "op" });
+   or(optional?: boolean): GridifyQueryBuilder {
+      this.filteringExpressions.push({
+         value: LogicalOperator.Or,
+         type: "op",
+         optional
+      });
       return this;
    }
 
@@ -96,6 +111,9 @@ export class GridifyQueryBuilder {
 
          //,
          if (previousType === null && exp.type === "op") {
+            if (exp.optional) {
+               return
+            }
             throw new Error("expression cannot start with a logical operator");
          }
 
@@ -108,13 +126,19 @@ export class GridifyQueryBuilder {
 
          // ,,
          if (previousType === "op" && exp.type === "op") {
+            if (exp.optional) {
+               return
+            }
             throw new Error(
                "consecutive operators are not allowed, consider adding a filter"
             );
          }
 
          // (,
          if (previousType === "startGroup" && exp.type === "op") {
+            if (exp.optional) {
+               return
+            }
             throw new Error(
                "logical operator immediately after startGroup is not allowed"
             );
@@ -126,8 +150,10 @@ export class GridifyQueryBuilder {
          }
 
          // ()
-         if (previousType === "startGroup" && exp.type === "endGroup") {
-            throw new Error("Empty groups are not allowed");
+         if (!this.options.allowEmptyGroups) {
+            if (previousType === "startGroup" && exp.type === "endGroup") {
+               throw new Error("Empty groups are not allowed");
+            }
          }
 
          // )(
@@ -143,11 +169,15 @@ export class GridifyQueryBuilder {
          throw new Error("Group not properly closed");
       }
 
+      // postprocess
+      this.query.filter = this.query.filter?.replace(/[,|]?\(\)/gi, "");
+
       return this.query;
    }
 }
 
 interface IExpression {
    value: string;
    type: "filter" | "op" | "startGroup" | "endGroup";
+   optional?: boolean
 }
diff --git a/client/src/GridifyQueryBuilderOptions.ts b/client/src/GridifyQueryBuilderOptions.ts
@@ -0,0 +1,6 @@
+import { GridifyQueryBuilder } from "./GridifyQueryBuilder";
+
+export interface GridifyQueryBuilderOptions {
+    from?: GridifyQueryBuilder;
+    allowEmptyGroups?: boolean;
+}
diff --git a/client/test/GridifyQueryBuilder.test.ts b/client/test/GridifyQueryBuilder.test.ts
@@ -1,5 +1,5 @@
-import { GridifyQueryBuilder } from "../src/GridifyQueryBuilder";
 import { ConditionalOperator as op } from "../src/GridifyOperator";
+import { GridifyQueryBuilder } from "../src/GridifyQueryBuilder";
 
 describe("GridifyQueryBuilder", () => {
    it("should build a simple query", () => {
@@ -18,6 +18,93 @@ describe("GridifyQueryBuilder", () => {
       });
    });
 
+   it("can be extended by the user", () => {
+      const query = new GridifyQueryBuilder()
+         .setPage(1)
+         .setPageSize(20)
+         .addOrderBy("name")
+         .addCondition("age", op.GreaterThan, 30);
+
+      class CustomQueryImpl extends GridifyQueryBuilder {
+
+         override build() {
+            return {
+               ...super.build(),
+               pageSize: this.query.pageSize + 1,
+               addition: 1
+            }
+         }
+      }
+
+      const customQuery = new CustomQueryImpl({
+         from: query
+      }).build();
+
+      expect(customQuery).toEqual({
+         page: 1,
+         pageSize: 21,
+         orderBy: "name",
+         filter: "age>30",
+         addition: 1
+      });
+   });
+
+   it("should be able to inherit existing instances", () => {
+      const query = new GridifyQueryBuilder()
+         .setPage(1)
+         .setPageSize(20)
+         .addOrderBy("name")
+         .addCondition("age", op.GreaterThan, 30);
+
+      const cloned = new GridifyQueryBuilder({
+         from: query
+      });
+
+      expect(cloned.build()).toEqual(query.build());
+   });
+
+   it("should remove all empty groups", () => {
+      const query = new GridifyQueryBuilder({
+         allowEmptyGroups: true
+      })
+         .setPage(1)
+         .setPageSize(20)
+         .addOrderBy("name")
+         .startGroup().endGroup().or(true)
+         .startGroup().endGroup()
+         .build();
+
+
+      expect(query).toEqual({
+         page: 1,
+         pageSize: 20,
+         orderBy: "name",
+         filter: "",
+      });
+   });
+
+   it("should be able to skip empty groups", () => {
+      const query = new GridifyQueryBuilder({
+         allowEmptyGroups: true
+      })
+         .setPage(1)
+         .setPageSize(20)
+         .addOrderBy("name")
+         .startGroup()
+         .addCondition("age", op.GreaterThan, 30)
+         .endGroup()
+         .and(true)
+         .startGroup().endGroup().build();
+
+
+      expect(query).toEqual({
+         page: 1,
+         pageSize: 20,
+         orderBy: "name",
+         filter: "(age>30)",
+      });
+   });
+
    it("should build a complex query with logical operators and groups", () => {
       const query = new GridifyQueryBuilder()
          .setPage(2)
@@ -85,13 +172,13 @@ describe("GridifyQueryBuilder Validation", () => {
    it("should allow nested balanced parentheses", () => {
       const query = new GridifyQueryBuilder()
          .startGroup()
-            .addCondition("field", op.Equal, "value")
-            .and()
-            .startGroup()
-               .addCondition("field", op.Equal, "value")
-               .or()
-               .addCondition("field", op.Equal, "value")
-            .endGroup()
+         .addCondition("field", op.Equal, "value")
+         .and()
+         .startGroup()
+         .addCondition("field", op.Equal, "value")
+         .or()
+         .addCondition("field", op.Equal, "value")
+         .endGroup()
          .endGroup()
          .build();
 
diff --git a/client/tsconfig.json b/client/tsconfig.json
@@ -1,13 +1,14 @@
 {
    "compilerOptions": {
-     "target": "es5",
-     "module": "ES2015",
-     "declaration": true,
-     "outDir": "./dist",
-     "esModuleInterop": true,
-     "strict": true,
-     "sourceMap": true
+      "target": "ES5",
+      "lib": ["ES2017"],
+      "module": "ES2015",
+      "declaration": true,
+      "outDir": "./dist",
+      "esModuleInterop": true,
+      "strict": true,
+      "sourceMap": true
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules", "test", "**/*.test.ts"]
- }
+}
diff --git a/docs/pages/guide/extensions/gridify-client.md b/docs/pages/guide/extensions/gridify-client.md
@@ -17,6 +17,21 @@ npm i gridify-client
 The `GridifyQueryBuilder` interface represents the methods available for constructing dynamic queries using the Gridify
 Client library.
 
+When creating a new instance of `GridifyQueryBuilder`, you can pass an optional `GridifyQueryBuilderOptions` object to the constructor. This allows you to configure advanced behaviors:
+
+- `from`: Clone an existing builder's state.
+- `allowEmptyGroups`: Allow empty logical groups in the filter expression (default is `false`).
+
+**Example:**
+
+```ts
+import { GridifyQueryBuilder } from "gridify-client";
+
+const builder = new GridifyQueryBuilder({
+  allowEmptyGroups: true
+});
+```
+
 The following table describes the methods available in the GridifyQueryBuilder interface for constructing dynamic queries.
 
 | Method       | Parameter                                          | Description                                                                                                           |
@@ -27,10 +42,12 @@ The following table describes the methods available in the GridifyQueryBuilder i
 | addCondition | field, operator, value, caseSensitive, escapeValue | Add filtering conditions. `caseSensitive` and `escapeValue` are optional parameters.                                  |
 | startGroup   | -                                                  | Start a logical grouping of conditions.                                                                               |
 | endGroup     | -                                                  | End the current logical group.                                                                                        |
-| and          | -                                                  | Add the logical AND operator.                                                                                         |
-| or           | -                                                  | Add the logical OR operator.                                                                                          |
+| and          | optional?: boolean                                 | Add the logical AND operator. If `optional` is `true`, the operator will be ignored if it would be invalid in the current context. |
+| or           | optional?: boolean                                 | Add the logical OR operator. If `optional` is `true`, the operator will be ignored if it would be invalid in the current context.  |
 | build        | -                                                  | Build and retrieve the constructed query.                                                                             |
 
+> **Note:**  
+> The `and` and `or` methods accepts an optional boolean parameter. If set to `true`, the logical operator will be treated as optional and ignored if it would result in an invalid expression (such as being the first operator or consecutive with another operator).
 
 ## Conditional Operators
 
@@ -86,3 +103,4 @@ Output:
   "filter": "(age<50|name^A),isActive=true"
 }
 ```
+
