@simtlix/simfinity-js-client 1.0.6 → 3.19.0

package/README.md

@@ -2,10 +2,12 @@
 
 Introspection-driven GraphQL client for [simfinity-js](https://github.com/simtlix/simfinity.js) APIs. It discovers your schema at runtime via introspection and exposes a chainable query builder, CRUD helpers, aggregate queries, state-machine transitions, schema metadata access, mutation input transformation, and more — no code generation required.
 
+> Since 3.19.0, the client is maintained in the Simfinity monorepo and follows its aligned release version. Existing valid 1.1 JavaScript calls remain supported.
+
 ## Installation
 
 ```bash
-npm install @simtlix/simfinity-js-client
+npm install @simtlix/simfinity-js-client@3.19.0
 ```
 
 ## Quick Start
@@ -41,7 +43,7 @@ Creates a new client instance pointing at the given GraphQL endpoint.
 
 ### `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.**
+By default, runs an extended 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.**
 
 ### Schema Inspection
 
@@ -71,7 +73,7 @@ const results = await client.find('serie')
 
 #### `.where(field, operator, value [, value2])`
 
-Filter by a scalar field. Supported operators depend on the server schema (e.g. `EQ`, `NE`, `GT`, `LT`, `GTE`, `LTE`, `BETWEEN`, `LIKE`, `NIN`).
+Filter by a scalar field. Supported operators depend on the server schema (e.g. `EQ`, `NE`, `GT`, `LT`, `GTE`, `LTE`, `BTW`, `LIKE`, `NIN`).
 
 #### `.where(field, terms)`
 
@@ -83,6 +85,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.
@@ -389,3 +491,19 @@ GRAPHQL_ENDPOINT=http://localhost:3000/graphql npm run demo
 ## License
 
 [Apache-2.0](LICENSE)
+
+## Source provenance
+
+Imported from simtlix/simfinity-js-client commit `32d9c5bf7264cd3ecddcd3441bffea3b21566cb0` (1.1.0), under its Apache-2.0 license.
+
+## Monorepo additions
+
+See the [JavaScript client guide](https://simtlix.github.io/simfinity.js/guide/client) for the complete current API and both-engine setup. The client remains dependency-free and browser compatible.
+
+- Constructor options add mutually exclusive `descriptor` and `descriptorEndpoint`, injected `fetch`, `introspection: 'extended' | 'standard'`, and asynchronous `prepareHeaders`. Descriptor mode never introspects; use it when the server disables introspection. `getDescriptor()` returns the loaded descriptor or null.
+- `query(name, args?, fields?)` executes exact query roots, including scalar and abstract outputs. `findView(name, params?)` returns a normal list builder, while `getViews(typeName?)` lists descriptor-classified views. Canonical lists are not replaced by views.
+- List and aggregate builders accept `.where(field, filterObject)` and `.filter(group)` for `valuePath`, `ANY`/`ALL`/`NONE` and `$parent`. Operators come from the schema, including text, emptiness, `CONTAINS_ALL` and `IIN`; the server still gates engine support. `collectionArgs(path, args)` applies variables to selected nested collections, separately from legacy parent filtering. Aliased paths use response names.
+- Transformed updates/actions preserve required managed versions. `delete(type, id, fields?, { version })` supplies the protected delete precondition. `transformInput` adds `preserveEmpty`, `includeCollections` and concrete `inputType` opt-ins. Collection delta transformation keeps `{ id, version }` for protected deletions and IDs for unprotected deletions.
+- `transaction(operations, fields?, { name }?)` sends one generated transaction mutation, preserving reference tokens and explicit versions. Descriptor mode discovers its root; introspection mode requires the exact configured name. Errors preserve all `graphQLErrors` extensions, including transaction positions. Writes are never retried by this client.
+
+Version 3.19.0 starts the client's aligned monorepo release policy, preserving the package name and existing valid 1.1 JavaScript calls. Releases use this repository's Release Simfinity workflow with npm Trusted Publishing and verified archives in both registries.

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@simtlix/simfinity-js-client",
-  "version": "1.0.6",
+  "version": "3.19.0",
   "description": "Introspection-driven GraphQL client for simfinity-js APIs",
   "type": "module",
-  "main": "src/SimfinityClient.js",
+  "main": "./src/SimfinityClient.js",
   "exports": {
-    ".": "./src/SimfinityClient.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/SimfinityClient.js"
+    }
   },
   "scripts": {
     "demo": "node examples/demo.js"
@@ -21,9 +24,17 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/simtlix/simfinity-js-client"
+    "url": "https://github.com/simtlix/simfinity.js",
+    "directory": "packages/client"
   },
   "engines": {
-    "node": ">=18.0.0"
-  }
+    "node": ">=18.18.0"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "types": "./types/index.d.ts"
 }