@simtlix/simfinity-js-client 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @simtlix/simfinity-js-client
 
-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, and state-machine transitions — no code generation required.
+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.
 
 ## Installation
 
@@ -28,7 +28,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. **Must be called before any other method.**
+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.**
 
 ### Schema Inspection
 
@@ -58,7 +58,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`).
+Filter by a scalar field. Supported operators depend on the server schema (e.g. `EQ`, `NE`, `GT`, `LT`, `GTE`, `LTE`, `BETWEEN`, `LIKE`, `NIN`).
 
 #### `.where(field, terms)`
 
@@ -82,14 +82,42 @@ Include a related collection's fields. Supports dot-notation for nested joins (e
 
 Space-separated list of scalar fields to select on the root type. If omitted, all scalar and enum fields are selected automatically.
 
+#### `.autoSelect()`
+
+Automatically builds a full selection set using schema metadata, including nested object fields with display field resolution. Returns the builder for chaining. The selection metadata is available via `builder._selectionMeta`.
+
+```js
+const results = await client.find('serie')
+  .autoSelect()
+  .page(1, 10)
+  .exec();
+```
+
 #### `.page(page, size [, count])`
 
-Paginate results. `page` is 1-based.
+Paginate results. `page` is 1-based. Set `count` to `true` to include total count in response extensions.
 
 #### `.sort(field, order)`
 
 Sort results. `order` is `'ASC'` or `'DESC'`. Can be called multiple times for multi-field sorting.
 
+#### `.exec()`
+
+Executes the query and returns the result array. If the server returns extensions (e.g. pagination count), they are attached as `result.__extensions`.
+
+#### `.execWithMeta()`
+
+Executes the query and returns a `{ data, extensions }` wrapper for clean access to response metadata:
+
+```js
+const { data: series, extensions } = await client.find('serie')
+  .page(1, 10, true)
+  .execWithMeta();
+
+console.log(series);              // the result array
+console.log(extensions?.count);   // total count from server
+```
+
 ---
 
 ### Aggregate Builder — `client.aggregate(typeName)`
@@ -130,6 +158,44 @@ If `fields` is omitted, all scalar fields are returned.
 
 ---
 
+### Collection Item Queries — `client.findByParent()`
+
+Query collection items filtered by their parent entity:
+
+```js
+const seasons = await client.findByParent('season', 'serie', parentSerieId)
+  .page(1, 10, true)
+  .fields('id number year state')
+  .exec();
+```
+
+Returns a `QueryBuilder` pre-configured with a connection field filter and default sort by `id ASC`. Chain additional `.where()`, `.page()`, `.fields()`, `.sort()` as needed.
+
+---
+
+### FK/Relation Search — `client.search()`
+
+Search-as-you-type for FK reference fields:
+
+```js
+const results = await client.search('Genre', 'com', {
+  displayField: 'name',
+  page: 1,
+  size: 10,
+});
+// [{ id: '1', name: 'Comedy' }, { id: '2', name: 'Romantic Comedy' }]
+```
+
+Automatically selects the appropriate operator (`LIKE` for strings, `EQ` for numeric/boolean) and casts the search term to the field's scalar type.
+
+| Option | Default | Description |
+|---|---|---|
+| `displayField` | auto-resolved (`name` or first scalar) | Field to search by |
+| `page` | `1` | Page number |
+| `size` | `10` | Page size |
+
+---
+
 ### CRUD Mutations
 
 ```js
@@ -140,6 +206,56 @@ const updated = await client.update('star', createdId, { name: 'Jane Doe' }, 'id
 const deleted = await client.delete('star', createdId, 'id name');
 ```
 
+#### Automatic Input Transformation
+
+Pass `{ transform: true }` as the last argument to have the client automatically clean mutation input based on schema metadata — stripping `__typename`, coercing scalar types, extracting FK IDs, handling embedded objects, and skipping read-only/state-machine fields:
+
+```js
+const created = await client.add('serie', rawFormData, 'id name', { transform: true });
+
+const updated = await client.update('serie', id, rawFormData, 'id name', {
+  transform: true,
+  skipFields: ['temporaryField'],
+});
+```
+
+---
+
+### Mutation Input Transformation — `client.transformInput()`
+
+Schema-aware mutation input cleaning, usable standalone:
+
+```js
+const cleaned = client.transformInput('serie', rawInput, {
+  mode: 'create',           // or 'update'
+  skipFields: [],            // fields to exclude
+  transientFields: [],       // transient fields to exclude
+});
+```
+
+Handles: `__typename` removal, numeric/date coercion, embedded object cleaning, FK reference extraction (`{ id }` only), and skipping read-only, state-machine, and collection fields.
+
+---
+
+### Collection Delta Mutations — `client.transformCollectionDelta()`
+
+Build the `{ added, updated, deleted }` structure for collection field mutations:
+
+```js
+const delta = {
+  added: [{ id: 'temp_1', number: '3', year: '2025', __status: 'added' }],
+  updated: [{ id: 'real-id', number: '2', year: '2024', __status: 'modified' }],
+  deleted: [{ id: 'del-id' }],
+};
+
+const cleaned = client.transformCollectionDelta('season', delta, {
+  connectionField: 'serie',
+});
+// { added: [{ number: 3, year: 2025 }], updated: [{ id: 'real-id', number: 2, year: 2024 }], deleted: ['del-id'] }
+```
+
+Strips metadata (`__status`, `__originalData`, `__typename`), removes temporary IDs and connection fields, coerces scalar types, and extracts FK object IDs.
+
 ---
 
 ### State Machine Transitions
@@ -175,9 +291,83 @@ console.log(response.data);
 
 ---
 
+### Selection Set Building — `client.buildSelectionSet()`
+
+Generate a complete GraphQL selection set string with metadata from the schema, useful for building dynamic UIs:
+
+```js
+const { selection, columns, sortFieldByColumn, fieldTypeByColumn } =
+  client.buildSelectionSet('serie');
+```
+
+Returns:
+
+| Property | Type | Description |
+|---|---|---|
+| `selection` | `string` | GraphQL selection set string (includes nested object sub-selections) |
+| `columns` | `string[]` | Display column names (excludes `id`) |
+| `sortFieldByColumn` | `object` | Maps column name to sort field path (e.g. `director` -> `director.name`) |
+| `fieldTypeByColumn` | `object` | Maps column name to scalar type name |
+
+---
+
+### Schema Metadata Access
+
+#### Field Extensions
+
+```js
+const ext = client.getFieldExtensions('serie', 'director');
+// { relation: { displayField: 'name', embedded: true, connectionField: null }, stateMachine: null, readOnly: null }
+```
+
+| Method | Signature | Description |
+|---|---|---|
+| `getFieldExtensions` | `(typeName, fieldName)` | Full extensions object for a field |
+| `getDisplayField` | `(typeName, fieldName)` | Display field with fallback chain (extension -> `name` -> first scalar) |
+| `isEmbeddedField` | `(typeName, fieldName)` | Whether the field is an embedded object |
+| `getConnectionField` | `(typeName, fieldName)` | Back-reference field name for collections |
+| `isStateMachineField` | `(typeName, fieldName)` | Whether the field is state-machine managed |
+| `isReadOnlyField` | `(typeName, fieldName)` | Whether the field is read-only |
+| `getEnumValues` | `(typeName)` | Enum values for an enum type |
+| `getFieldsOfType` | `(typeName)` | All fields with full metadata |
+| `getDescriptionFieldType` | `(typeName, fieldName)` | Scalar type name of a display field |
+
+#### Entity & Query Name Resolution
+
+```js
+client.getTypeNameForQuery('series');           // 'serie'
+client.getPluralQueryName('serie');              // 'series'
+client.getSingularQueryName('serie');            // 'serie'
+client.getListEntityNames();                    // ['episodes', 'seasons', 'series', 'stars', ...]
+client.getListEntityNamesOfType('serie');        // ['series']
+client.getQueryNamesForType('serie');
+// { pluralQueryName: 'series', singularQueryName: 'serie', aggregateQueryName: 'series_aggregate' }
+```
+
+#### Scalar Type Utilities
+
+Simfinity uses validated scalar names like `SeasonNumber_Int` where the suffix after `_` indicates the base type:
+
+```js
+client.getActualScalarType('SeasonNumber_Int');  // 'Int'
+client.isNumericScalar('SeasonNumber_Int');       // true
+client.isBooleanScalar('Boolean');               // true
+client.isDateTimeScalar('StartDate_DateTime');   // true
+```
+
+#### State Machine Metadata
+
+```js
+client.getStateMachineFields('season');          // ['state']
+client.getAvailableTransitions('season');
+// [{ action: 'activate', mutationName: 'activate_season' }, { action: 'finalize', mutationName: 'finalize_season' }]
+```
+
+---
+
 ## Examples
 
-See [`examples/demo.js`](examples/demo.js) for a comprehensive walkthrough covering all features: schema discovery, filtering, joins, pagination, sorting, CRUD, state machine transitions, aggregates, and raw queries.
+See [`examples/demo.js`](examples/demo.js) for a comprehensive walkthrough covering all features: schema discovery, filtering, joins, pagination, sorting, CRUD, state machine transitions, aggregates, raw queries, schema metadata, selection set building, entity resolution, input transformation, collection deltas, parent queries, FK search, and response extensions.
 
 ```bash
 GRAPHQL_ENDPOINT=http://localhost:3000/graphql npm run demo

package/examples/demo.js

@@ -198,6 +198,152 @@ const log = (label, data) => {
     .exec();
   log('17. aggregate("episode") -- count episodes per season', aggFiltered);
 
+  // -----------------------------------------------------------------------
+  // 18. Scalar type utilities (Feature 2)
+  // -----------------------------------------------------------------------
+  log('18. Scalar type utilities', {
+    'getActualScalarType("SeasonNumber_Int")': client.getActualScalarType('SeasonNumber_Int'),
+    'getActualScalarType("StartDate_Date")': client.getActualScalarType('StartDate_Date'),
+    'isNumericScalar("SeasonNumber_Int")': client.isNumericScalar('SeasonNumber_Int'),
+    'isNumericScalar("String")': client.isNumericScalar('String'),
+    'isBooleanScalar("Boolean")': client.isBooleanScalar('Boolean'),
+    'isDateTimeScalar("EpisodeDate_DateTime")': client.isDateTimeScalar('EpisodeDate_DateTime'),
+    'isDateTimeScalar("Int")': client.isDateTimeScalar('Int'),
+  });
+
+  // -----------------------------------------------------------------------
+  // 19. Schema metadata access (Feature 3)
+  // -----------------------------------------------------------------------
+  const serieType = client.getTypes()['serie'] ? 'serie' : 'Serie';
+  const serieFields = client.getFieldsOfType(serieType);
+  log('19. Schema metadata -- getFieldsOfType(' + serieType + ')', serieFields.map(f => ({
+    name: f.name,
+    kind: f.type.kind,
+    typeName: f.type.name,
+    extensions: f.extensions,
+  })));
+
+  const objectFields = serieFields.filter(f => f.type.kind === 'OBJECT');
+  if (objectFields.length > 0) {
+    const objField = objectFields[0];
+    log('19b. Schema metadata -- extensions for ' + serieType + '.' + objField.name, {
+      extensions: client.getFieldExtensions(serieType, objField.name),
+      displayField: client.getDisplayField(serieType, objField.name),
+      isEmbedded: client.isEmbeddedField(serieType, objField.name),
+      connectionField: client.getConnectionField(serieType, objField.name),
+      isStateMachine: client.isStateMachineField(serieType, objField.name),
+      isReadOnly: client.isReadOnlyField(serieType, objField.name),
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // 20. buildSelectionSet / autoSelect (Feature 4)
+  // -----------------------------------------------------------------------
+  const selSet = client.buildSelectionSet(serieType);
+  log('20. buildSelectionSet(' + serieType + ')', selSet);
+
+  const autoSelectResult = await client.find(serieType)
+    .autoSelect()
+    .page(1, 2)
+    .exec();
+  log('20b. find().autoSelect().page(1,2).exec()', autoSelectResult);
+
+  // -----------------------------------------------------------------------
+  // 21. Entity & query name resolution (Feature 5)
+  // -----------------------------------------------------------------------
+  log('21. Entity & query name resolution', {
+    listEntityNames: client.getListEntityNames(),
+    'getQueryNamesForType(serieType)': client.getQueryNamesForType(serieType),
+    'getPluralQueryName(serieType)': client.getPluralQueryName(serieType),
+    'getSingularQueryName(serieType)': client.getSingularQueryName(serieType),
+  });
+
+  const pluralName = client.getPluralQueryName(serieType);
+  if (pluralName) {
+    log('21b. getTypeNameForQuery("' + pluralName + '")',
+      client.getTypeNameForQuery(pluralName));
+  }
+
+  // -----------------------------------------------------------------------
+  // 22. transformInput (Feature 6)
+  // -----------------------------------------------------------------------
+  const rawInput = {
+    name: 'Test Serie',
+    categories: 'Drama',
+    year: '2025',
+    __typename: 'Serie',
+    director: { id: 'dir-123', name: 'Some Director', __typename: 'Director' },
+  };
+  const transformed = client.transformInput(serieType, rawInput, { mode: 'create' });
+  log('22. transformInput -- raw vs transformed', { rawInput, transformed });
+
+  // -----------------------------------------------------------------------
+  // 23. transformCollectionDelta (Feature 7)
+  // -----------------------------------------------------------------------
+  const seasonType = client.getTypes()['season'] ? 'season' : 'Season';
+  const delta = {
+    added: [
+      { id: 'temp_1', number: '3', year: '2025', __typename: 'Season', __status: 'added' },
+    ],
+    updated: [
+      { id: 'real-id-1', number: '2', year: '2024', __status: 'modified' },
+    ],
+    deleted: [
+      { id: 'del-id-1' },
+    ],
+  };
+  const connectionField = client.getConnectionField(serieType, 'seasons');
+  const transformedDelta = client.transformCollectionDelta(seasonType, delta, {
+    connectionField: connectionField || 'serie',
+  });
+  log('23. transformCollectionDelta', { delta, transformedDelta });
+
+  // -----------------------------------------------------------------------
+  // 24. findByParent (Feature 8)
+  // -----------------------------------------------------------------------
+  if (allSeries.length > 0) {
+    const parentId = allSeries[0].id;
+    const childSeasons = await client
+      .findByParent(seasonType, 'serie', parentId)
+      .page(1, 5, true)
+      .fields('id number year')
+      .exec();
+    log('24. findByParent(' + seasonType + ', "serie", "' + parentId + '")', childSeasons);
+  } else {
+    log('24. findByParent -- skipped (no series)', '');
+  }
+
+  // -----------------------------------------------------------------------
+  // 25. search (Feature 9)
+  // -----------------------------------------------------------------------
+  const searchResults = await client.search('star', 'a', {
+    displayField: 'name',
+    page: 1,
+    size: 5,
+  });
+  log('25. search("star", "a", { displayField: "name" })', searchResults);
+
+  // -----------------------------------------------------------------------
+  // 26. State machine metadata (Feature 10)
+  // -----------------------------------------------------------------------
+  log('26. State machine metadata', {
+    'getStateMachineFields(seasonType)': client.getStateMachineFields(seasonType),
+    'getAvailableTransitions(seasonType)': client.getAvailableTransitions(seasonType),
+  });
+
+  // -----------------------------------------------------------------------
+  // 27. execWithMeta -- pagination count (Feature 11)
+  // -----------------------------------------------------------------------
+  const { data: pagedSeries, extensions } = await client
+    .find(serieType)
+    .page(1, 2, true)
+    .execWithMeta();
+  log('27. execWithMeta -- pagination count', {
+    data: pagedSeries,
+    extensions,
+    totalCount: extensions?.count,
+  });
+
   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.0",
+  "version": "1.0.2",
   "description": "Introspection-driven GraphQL client for simfinity-js APIs",
   "type": "module",
   "main": "src/SimfinityClient.js",
@@ -23,7 +23,7 @@
     "type": "git",
     "url": "https://github.com/simtlix/simfinity-js-client"
   },
-  "dependencies": {
-    "node-fetch": "^3.3.2"
+  "engines": {
+    "node": ">=18.0.0"
   }
 }