@simtlix/simfinity-js-client 1.0.6 → 1.1.0

package/README.md

@@ -83,6 +83,106 @@ Filter by a collection field using an array of term objects:
 ])
 ```
 
+#### `.or(groups)` / `.and(groups)`
+
+Add AND/OR logical filter groups for complex boolean conditions. Each method accepts an array of `QLFilterGroup` objects and can be called multiple times (groups accumulate). These combine with existing flat `.where()` filters via AND at the top level.
+
+A `QLFilterGroup` is a plain object with optional `AND`, `OR`, and `conditions` fields:
+
+```js
+{
+  conditions: [{ field: 'category', operator: 'EQ', value: 'Drama' }],
+  AND: [/* nested QLFilterGroup objects */],
+  OR:  [/* nested QLFilterGroup objects */],
+}
+```
+
+**Simple OR** -- return series in either Drama or Comedy:
+
+```js
+const results = await client.find('serie')
+  .or([
+    SimfinityClient.condition('categories', 'EQ', 'Drama'),
+    SimfinityClient.condition('categories', 'EQ', 'Comedy'),
+  ])
+  .fields('id name categories')
+  .exec();
+```
+
+**Flat filters combined with OR** -- flat `.where()` is ANDed with the OR group:
+
+```js
+const results = await client.find('serie')
+  .where('categories', 'NE', 'Horror')
+  .or([
+    SimfinityClient.condition('name', 'LIKE', 'Breaking'),
+    SimfinityClient.condition('name', 'LIKE', 'Game'),
+  ])
+  .fields('id name categories')
+  .exec();
+// Equivalent to: categories != "Horror" AND (name LIKE "Breaking" OR name LIKE "Game")
+```
+
+**Nested AND inside OR**:
+
+```js
+const results = await client.find('serie')
+  .or([
+    { AND: [
+      SimfinityClient.condition('categories', 'EQ', 'Drama'),
+      SimfinityClient.condition('year', 'GTE', 2020),
+    ]},
+    { AND: [
+      SimfinityClient.condition('categories', 'EQ', 'Comedy'),
+      SimfinityClient.condition('year', 'GTE', 2015),
+    ]},
+  ])
+  .exec();
+// Equivalent to: (categories = "Drama" AND year >= 2020) OR (categories = "Comedy" AND year >= 2015)
+```
+
+**AND with nested OR groups**:
+
+```js
+const results = await client.find('serie')
+  .where('year', 'GTE', 2000)
+  .and([
+    { OR: [
+      SimfinityClient.condition('categories', 'EQ', 'Drama'),
+      SimfinityClient.condition('categories', 'EQ', 'Comedy'),
+    ]},
+    { OR: [
+      SimfinityClient.condition('director', 'EQ', 'UK', 'country'),
+      SimfinityClient.condition('director', 'EQ', 'US', 'country'),
+    ]},
+  ])
+  .exec();
+// Equivalent to: year >= 2000 AND (Drama OR Comedy) AND (UK OR US director)
+```
+
+**Relationship path filtering** -- use the `path` parameter for object field conditions:
+
+```js
+.or([
+  SimfinityClient.condition('director', 'LIKE', 'Adams', 'name'),
+  SimfinityClient.condition('director', 'LIKE', 'Nolan', 'name'),
+])
+```
+
+The Aggregate Builder also supports `.or()` and `.and()` with identical behavior. The server enforces a maximum nesting depth of 5 levels.
+
+#### `SimfinityClient.condition(field, operator, value [, path])`
+
+Static convenience factory for creating a filter group with a single condition. Returns a `QLFilterGroup` object:
+
+```js
+SimfinityClient.condition('category', 'EQ', 'Drama')
+// Equivalent to: { conditions: [{ field: 'category', operator: 'EQ', value: 'Drama' }] }
+
+SimfinityClient.condition('author', 'LIKE', 'Adams', 'name')
+// Equivalent to: { conditions: [{ field: 'author', operator: 'LIKE', value: 'Adams', path: 'name' }] }
+```
+
 #### `.joinObject(path, fields)`
 
 Include a related object's fields in the selection.

package/examples/demo.js

@@ -344,6 +344,58 @@ const log = (label, data) => {
     totalCount: extensions?.count,
   });
 
+  // -----------------------------------------------------------------------
+  // 28. find() with OR filter
+  // -----------------------------------------------------------------------
+  const orResults = await client.find(serieType)
+    .or([
+      SimfinityClient.condition('categories', 'EQ', 'Drama'),
+      SimfinityClient.condition('categories', 'EQ', 'Comedy'),
+    ])
+    .fields('id name categories')
+    .exec();
+  log('28. find() -- OR filter (Drama OR Comedy)', orResults);
+
+  // -----------------------------------------------------------------------
+  // 29. find() with flat where + OR combined
+  // -----------------------------------------------------------------------
+  const combinedOrResults = await client.find(serieType)
+    .where('categories', 'NE', 'Horror')
+    .or([
+      SimfinityClient.condition('name', 'LIKE', 'Breaking'),
+      SimfinityClient.condition('name', 'LIKE', 'Game'),
+    ])
+    .fields('id name categories')
+    .exec();
+  log('29. find() -- flat where + OR (not Horror AND (name LIKE Breaking OR Game))', combinedOrResults);
+
+  // -----------------------------------------------------------------------
+  // 30. find() with AND containing nested OR
+  // -----------------------------------------------------------------------
+  const nestedAndOrResults = await client.find(serieType)
+    .and([
+      { OR: [
+        SimfinityClient.condition('categories', 'EQ', 'Drama'),
+        SimfinityClient.condition('categories', 'EQ', 'Comedy'),
+      ]},
+    ])
+    .fields('id name categories')
+    .exec();
+  log('30. find() -- AND with nested OR groups', nestedAndOrResults);
+
+  // -----------------------------------------------------------------------
+  // 31. aggregate() with OR filter
+  // -----------------------------------------------------------------------
+  const aggOrResults = await client.aggregate(seasonType)
+    .groupBy('serie')
+    .fact('COUNT', 'seasonCount', 'id')
+    .or([
+      SimfinityClient.condition('year', 'GTE', 2020),
+      SimfinityClient.condition('year', 'LTE', 2010),
+    ])
+    .exec();
+  log('31. aggregate() -- OR filter (year >= 2020 OR year <= 2010)', aggOrResults);
+
   console.log('\n' + '='.repeat(60));
   console.log('Demo complete.');
   console.log('='.repeat(60));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js-client",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Introspection-driven GraphQL client for simfinity-js APIs",
   "type": "module",
   "main": "src/SimfinityClient.js",

package/src/SimfinityClient.js

@@ -227,6 +227,30 @@ class QueryBuilder {
     return this;
   }
 
+  or(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('or() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.OR) {
+      this._variables.OR.push(...groups);
+    } else {
+      this._variables.OR = [...groups];
+    }
+    return this;
+  }
+
+  and(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('and() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.AND) {
+      this._variables.AND.push(...groups);
+    } else {
+      this._variables.AND = [...groups];
+    }
+    return this;
+  }
+
   // -- Relation Field Selection --------------------------------------------
 
   joinCollection(path, fields, filter) {
@@ -418,6 +442,30 @@ class AggregateBuilder {
     return this;
   }
 
+  or(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('or() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.OR) {
+      this._variables.OR.push(...groups);
+    } else {
+      this._variables.OR = [...groups];
+    }
+    return this;
+  }
+
+  and(groups) {
+    if (!Array.isArray(groups)) {
+      throw new Error('and() expects an array of QLFilterGroup objects');
+    }
+    if (this._variables.AND) {
+      this._variables.AND.push(...groups);
+    } else {
+      this._variables.AND = [...groups];
+    }
+    return this;
+  }
+
   page(page, size, count) {
     const pagination = { page, size };
     if (count !== undefined) pagination.count = count;
@@ -1339,4 +1387,12 @@ export default class SimfinityClient {
       throw new Error('Client not initialized. Call init() first.');
     }
   }
+
+  // -- Static Helpers -------------------------------------------------------
+
+  static condition(field, operator, value, path) {
+    const cond = { field, operator, value };
+    if (path !== undefined) cond.path = path;
+    return { conditions: [cond] };
+  }
 }