@simtlix/simfinity-js-client 1.0.2 → 1.1.0

package/README.md

@@ -16,16 +16,29 @@ import SimfinityClient from '@simtlix/simfinity-js-client';
 const client = new SimfinityClient('http://localhost:3000/graphql');
 await client.init();
 
+// Optional: attach auth headers (perform login in your app; this client does not include login)
+const tokenStore = { accessToken: null };
+const authedClient = new SimfinityClient('http://localhost:3000/graphql', {
+  prepareHeaders(headers) {
+    if (tokenStore.accessToken) {
+      headers['Authorization'] = `Bearer ${tokenStore.accessToken}`;
+    }
+  },
+});
+await authedClient.init();
+
 const series = await client.find('serie').exec();
 console.log(series);
 ```
 
 ## API Reference
 
-### `new SimfinityClient(endpoint)`
+### `new SimfinityClient(endpoint [, options])`
 
 Creates a new client instance pointing at the given GraphQL endpoint.
 
+- **`options.prepareHeaders(headers)`** (optional): invoked before every GraphQL HTTP request. Mutate the plain `headers` object to add credentials (for example `Authorization`). The client does not implement login — call your auth API separately, then set tokens in a closure or store that `prepareHeaders` reads.
+
 ### `client.init()`
 
 Runs an introspection query against the endpoint and builds internal registries of types, queries, and mutations — including Simfinity-specific field extensions (relation metadata, state machine flags, read-only markers). **Must be called before any other method.**
@@ -70,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.2",
+  "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;
@@ -481,7 +529,14 @@ class AggregateBuilder {
 // ---------------------------------------------------------------------------
 
 export default class SimfinityClient {
-  constructor(endpoint) {
+  /**
+   * @param {string} endpoint GraphQL HTTP endpoint URL
+   * @param {{ prepareHeaders?: (headers: Record<string, string>) => void }} [options]
+   *        Optional `prepareHeaders` runs before each request; mutate `headers` to add auth
+   *        (e.g. `headers['Authorization'] = 'Bearer …'`). Login is not part of this client —
+   *        perform auth in your app and set tokens inside this callback or a closure it sees.
+   */
+  constructor(endpoint, options = {}) {
     this._endpoint = endpoint;
     this._types = new Map();
     this._queries = new Map();
@@ -491,6 +546,8 @@ export default class SimfinityClient {
     this._typeNameToAggregate = new Map();
     this._queryNameToType = new Map();
     this._initialized = false;
+    this._prepareHeaders =
+      typeof options.prepareHeaders === 'function' ? options.prepareHeaders : null;
   }
 
   // -- Initialization ------------------------------------------------------
@@ -664,9 +721,13 @@ export default class SimfinityClient {
     if (variables && Object.keys(variables).length > 0) {
       body.variables = variables;
     }
+    const headers = { 'Content-Type': 'application/json' };
+    if (this._prepareHeaders) {
+      this._prepareHeaders(headers);
+    }
     const response = await _fetch(this._endpoint, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers,
       body: JSON.stringify(body),
     });
     return response.json();
@@ -1326,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] };
+  }
 }