@mapped/schema-graph-react-apollo 2.3.5 → 2.3.7

package/dist/index.d.ts

@@ -1942,13 +1942,119 @@ export type ConnectorEntityImportResponse = {
   job?: Maybe<BaseJob>;
 };
 
+/**
+ * Narrows the entities of one namespace. `previewConnectorEntities` (as `list.filter`) is the searchable listing; `listConnectorEntities` rejects a non-blank `searchQuery` with `UNIMPLEMENTED`.
+ *
+ * | Field | `listConnectorEntities` | `previewConnectorEntities` |
+ * |---|---|---|
+ * | `id` | `eq` / `in` | `eq` / `in` |
+ * | `refId`, `mappingKey` | `eq` / `in` | ignored; use `searchQuery` |
+ * | `mergingState` | the first of `eq`, `in`, `ne` that is set | `eq`, `in` and `ne` together, against the state the entity would have after this save |
+ * | `lastChangeDate` | every operator set, so `gte` + `lte` is a closed range; an entity never merged matches no bound | same |
+ * | `lastChangeKind` | the first of `eq`, `in`, `ne` that is set | same |
+ * | `searchQuery` | rejected | the grammar below |
+ *
+ * **searchQuery**
+ *
+ * Up to three parts, separated by whitespace, in any order, all combined with AND. Canonical order:
+ *
+ * ```text
+ * #tags gridv1:TOKEN free text
+ * ```
+ *
+ * **Free text**
+ *
+ * - Split on whitespace; every word must appear, as a case-insensitive substring, somewhere in the entity. Word order does not matter.
+ * - Searched: `refId`, the `exactType` and `baseType` names, every `context` value, and every field value of any type (displayed, default and saved), including an entity reference's readable parts.
+ * - Platform ids (`id`, `mappedId`, `mappingKey`, `legacyMappingKey`, and the ids inside an entity reference) match only a word of 8 or more characters: a pasted id finds its entity, a short word such as `2` never matches every entity through a shared id prefix.
+ * - Never searched: `sourceType`, context keys starting with `__`, field slugs, labels and `options`, boolean values, and platform state such as `mergingState` (use the hashtags).
+ *
+ * **Hashtags**
+ *
+ * Case-insensitive and whitespace-bounded; several are combined with AND. Each keeps the entities carrying that tag in `context.__preview.tags`:
+ *
+ * - `#selected`: selected after this save.
+ * - `#added`: this save adds it to the graph.
+ * - `#updated`: already in the graph, and its values change (by a user, a rule, or the source system since its last merge).
+ * - `#deleted`: a user or a rule unselected it, so this save deletes it from the graph; never a missing entity.
+ * - `#missing`: merged, but the source system no longer reports it, so every save deletes it; never tagged `deleted`.
+ * - `#firstSeen`: first imported after the namespace's last save, selected or not; none until the namespace has been saved or merged once.
+ * - `#unresolved`: added or updated, with an entity reference pointing at nothing in the graph. It runs the graph check: if the check cannot complete, the request fails with `ABORTED` (retry) or `RESOURCE_EXHAUSTED` (too many references) instead of returning an empty page.
+ *
+ * Any other `#word`, and a tag glued to another word (`abc#added`), is free text.
+ *
+ * **Grid token**
+ *
+ * A column filter and sort, at most one per query: `gridv1:` followed by the unpadded base64url encoding of this JSON (MUI X DataGrid's filter and sort models; other keys are ignored, both models are optional):
+ *
+ * ```json
+ * {
+ *   "filterModel": {
+ *     "items": [{ "field": "floor", "operator": ">=", "value": 2 }],
+ *     "logicOperator": "and"
+ *   },
+ *   "sortModel": [{ "field": "name", "sort": "asc" }]
+ * }
+ * ```
+ *
+ * - `logicOperator` is `and` (the default) or `or`, over a flat list of items. `sort` is `asc`, `desc`, or `null` (ignored).
+ * - `field` is a field slug, `@` followed by a context key (non-string values compare as their JSON), or one of the reserved keys `refId`, `mappingKey`, `mappedId`, `legacyMappingKey`. A field slug the namespace does not declare is ignored; a context key starting with `__` is rejected.
+ * - Columns compare as numbers (`FLOOR_LEVEL` fields), by presence only (`ENTITY_REF` fields, whose names are resolved client-side; not sortable), or as text (every other field and key). Operators:
+ *
+ * ```text
+ * operator                                  text  number  entity reference
+ * contains, doesNotContain                  yes   -       -
+ * equals, =, is / doesNotEqual, !=, not     yes   yes     -
+ * startsWith, endsWith                      yes   -       -
+ * isEmpty, isNotEmpty                       yes   yes     yes
+ * isAnyOf (value is an array)               yes   yes     -
+ * >, >=, <, <=                              -     yes     -
+ * ```
+ *
+ * - Values compare against the displayed value (after rules and unsaved edits). Text equality and `isAnyOf` ignore case and accents; `contains`, `startsWith` and `endsWith` ignore case only. Blank text counts as empty. An item with no usable value (missing, blank, `NaN`, an empty array) is ignored.
+ * - Sort keys apply in order: natural order ("Room 2" before "Room 10"), case-insensitive, empty values last in both directions, ties broken by entity `id`.
+ * - Filters and sorts the listing before pagination; never changes the counts.
+ * - Limits, counted before ignored fields are dropped: 50 filter items, 200 `isAnyOf` values summed over the whole query, 10 sort keys, and a 32 KiB encoded payload.
+ * - A second token, an unknown `gridvN` version, a payload that is not base64url JSON of this shape, an unknown operator, an operator the column cannot take, a sort on an entity reference, or a limit exceeded fails with `INVALID_ARGUMENT` and a message starting `Invalid grid query:`.
+ *
+ * **Example**
+ *
+ * For a namespace with fields `floor` (`FLOOR_LEVEL`), `building` (`ENTITY_REF`) and `name` (`NAME`): entities this save adds, on floor 2 or above, whose `department` context is IT or Facilities, with a building set, containing "lobby", sorted by name.
+ *
+ * ```text
+ * #added gridv1:eyJmaWx0ZXJNb2RlbCI6eyJpdGVtcyI6W3siZmllbGQiOiJmbG9vciIsIm9wZXJhdG9yIjoiPj0iLCJ2YWx1ZSI6Mn0seyJmaWVsZCI6IkBkZXBhcnRtZW50Iiwib3BlcmF0b3IiOiJpc0FueU9mIiwidmFsdWUiOlsiSVQiLCJGYWNpbGl0aWVzIl19LHsiZmllbGQiOiJidWlsZGluZyIsIm9wZXJhdG9yIjoiaXNOb3RFbXB0eSJ9XSwibG9naWNPcGVyYXRvciI6ImFuZCJ9LCJzb3J0TW9kZWwiOlt7ImZpZWxkIjoibmFtZSIsInNvcnQiOiJhc2MifV19 lobby
+ * ```
+ *
+ * The token decodes to:
+ *
+ * ```json
+ * {
+ *   "filterModel": {
+ *     "items": [
+ *       { "field": "floor", "operator": ">=", "value": 2 },
+ *       { "field": "@department", "operator": "isAnyOf", "value": ["IT", "Facilities"] },
+ *       { "field": "building", "operator": "isNotEmpty" }
+ *     ],
+ *     "logicOperator": "and"
+ *   },
+ *   "sortModel": [{ "field": "name", "sort": "asc" }]
+ * }
+ * ```
+ */
 export type ConnectorEntityListFilterInput = {
+  /** Entity ids to keep, by eq or in. */
   id?: Maybe<IdFilterExpressionInput>;
+  /** When a merge last changed the entity in the graph; every operator set applies, so gte with lte is a closed range, and an entity never merged matches no bound. */
   lastChangeDate?: Maybe<TimestampFilterExpressionInput>;
+  /** What the last merge did to the entity; only the first operator set among eq, in and ne applies. */
   lastChangeKind?: Maybe<ConnectorEntityChangeKindFilterExpressionInput>;
+  /** Mapping keys to keep, by eq or in; applied by listConnectorEntities only, previewConnectorEntities ignores it. */
   mappingKey?: Maybe<IdFilterExpressionInput>;
+  /** Merging states to keep; listConnectorEntities applies the first operator set among eq, in and ne, previewConnectorEntities applies all of them to the state the entity would have after the save. */
   mergingState?: Maybe<ConnectorEntityMergingStateFilterExpressionInput>;
+  /** Source-system ids to keep, by eq or in; applied by listConnectorEntities only, previewConnectorEntities ignores it. */
   refId?: Maybe<IdFilterExpressionInput>;
+  /** Free text, hashtag filters and an optional grid filter and sort token, honoured by previewConnectorEntities only (listConnectorEntities rejects it); see the type description for the grammar and an example. */
   searchQuery?: Maybe<Scalars['String']>;
 };
 

package/mapped.schema.json

@@ -13964,12 +13964,12 @@
       {
         "kind": "INPUT_OBJECT",
         "name": "ConnectorEntityListFilterInput",
-        "description": null,
+        "description": "Narrows the entities of one namespace. `previewConnectorEntities` (as `list.filter`) is the searchable listing; `listConnectorEntities` rejects a non-blank `searchQuery` with `UNIMPLEMENTED`.\n\n| Field | `listConnectorEntities` | `previewConnectorEntities` |\n|---|---|---|\n| `id` | `eq` / `in` | `eq` / `in` |\n| `refId`, `mappingKey` | `eq` / `in` | ignored; use `searchQuery` |\n| `mergingState` | the first of `eq`, `in`, `ne` that is set | `eq`, `in` and `ne` together, against the state the entity would have after this save |\n| `lastChangeDate` | every operator set, so `gte` + `lte` is a closed range; an entity never merged matches no bound | same |\n| `lastChangeKind` | the first of `eq`, `in`, `ne` that is set | same |\n| `searchQuery` | rejected | the grammar below |\n\n**searchQuery**\n\nUp to three parts, separated by whitespace, in any order, all combined with AND. Canonical order:\n\n```text\n#tags gridv1:TOKEN free text\n```\n\n**Free text**\n\n- Split on whitespace; every word must appear, as a case-insensitive substring, somewhere in the entity. Word order does not matter.\n- Searched: `refId`, the `exactType` and `baseType` names, every `context` value, and every field value of any type (displayed, default and saved), including an entity reference's readable parts.\n- Platform ids (`id`, `mappedId`, `mappingKey`, `legacyMappingKey`, and the ids inside an entity reference) match only a word of 8 or more characters: a pasted id finds its entity, a short word such as `2` never matches every entity through a shared id prefix.\n- Never searched: `sourceType`, context keys starting with `__`, field slugs, labels and `options`, boolean values, and platform state such as `mergingState` (use the hashtags).\n\n**Hashtags**\n\nCase-insensitive and whitespace-bounded; several are combined with AND. Each keeps the entities carrying that tag in `context.__preview.tags`:\n\n- `#selected`: selected after this save.\n- `#added`: this save adds it to the graph.\n- `#updated`: already in the graph, and its values change (by a user, a rule, or the source system since its last merge).\n- `#deleted`: a user or a rule unselected it, so this save deletes it from the graph; never a missing entity.\n- `#missing`: merged, but the source system no longer reports it, so every save deletes it; never tagged `deleted`.\n- `#firstSeen`: first imported after the namespace's last save, selected or not; none until the namespace has been saved or merged once.\n- `#unresolved`: added or updated, with an entity reference pointing at nothing in the graph. It runs the graph check: if the check cannot complete, the request fails with `ABORTED` (retry) or `RESOURCE_EXHAUSTED` (too many references) instead of returning an empty page.\n\nAny other `#word`, and a tag glued to another word (`abc#added`), is free text.\n\n**Grid token**\n\nA column filter and sort, at most one per query: `gridv1:` followed by the unpadded base64url encoding of this JSON (MUI X DataGrid's filter and sort models; other keys are ignored, both models are optional):\n\n```json\n{\n  \"filterModel\": {\n    \"items\": [{ \"field\": \"floor\", \"operator\": \">=\", \"value\": 2 }],\n    \"logicOperator\": \"and\"\n  },\n  \"sortModel\": [{ \"field\": \"name\", \"sort\": \"asc\" }]\n}\n```\n\n- `logicOperator` is `and` (the default) or `or`, over a flat list of items. `sort` is `asc`, `desc`, or `null` (ignored).\n- `field` is a field slug, `@` followed by a context key (non-string values compare as their JSON), or one of the reserved keys `refId`, `mappingKey`, `mappedId`, `legacyMappingKey`. A field slug the namespace does not declare is ignored; a context key starting with `__` is rejected.\n- Columns compare as numbers (`FLOOR_LEVEL` fields), by presence only (`ENTITY_REF` fields, whose names are resolved client-side; not sortable), or as text (every other field and key). Operators:\n\n```text\noperator                                  text  number  entity reference\ncontains, doesNotContain                  yes   -       -\nequals, =, is / doesNotEqual, !=, not     yes   yes     -\nstartsWith, endsWith                      yes   -       -\nisEmpty, isNotEmpty                       yes   yes     yes\nisAnyOf (value is an array)               yes   yes     -\n>, >=, <, <=                              -     yes     -\n```\n\n- Values compare against the displayed value (after rules and unsaved edits). Text equality and `isAnyOf` ignore case and accents; `contains`, `startsWith` and `endsWith` ignore case only. Blank text counts as empty. An item with no usable value (missing, blank, `NaN`, an empty array) is ignored.\n- Sort keys apply in order: natural order (\"Room 2\" before \"Room 10\"), case-insensitive, empty values last in both directions, ties broken by entity `id`.\n- Filters and sorts the listing before pagination; never changes the counts.\n- Limits, counted before ignored fields are dropped: 50 filter items, 200 `isAnyOf` values summed over the whole query, 10 sort keys, and a 32 KiB encoded payload.\n- A second token, an unknown `gridvN` version, a payload that is not base64url JSON of this shape, an unknown operator, an operator the column cannot take, a sort on an entity reference, or a limit exceeded fails with `INVALID_ARGUMENT` and a message starting `Invalid grid query:`.\n\n**Example**\n\nFor a namespace with fields `floor` (`FLOOR_LEVEL`), `building` (`ENTITY_REF`) and `name` (`NAME`): entities this save adds, on floor 2 or above, whose `department` context is IT or Facilities, with a building set, containing \"lobby\", sorted by name.\n\n```text\n#added gridv1:eyJmaWx0ZXJNb2RlbCI6eyJpdGVtcyI6W3siZmllbGQiOiJmbG9vciIsIm9wZXJhdG9yIjoiPj0iLCJ2YWx1ZSI6Mn0seyJmaWVsZCI6IkBkZXBhcnRtZW50Iiwib3BlcmF0b3IiOiJpc0FueU9mIiwidmFsdWUiOlsiSVQiLCJGYWNpbGl0aWVzIl19LHsiZmllbGQiOiJidWlsZGluZyIsIm9wZXJhdG9yIjoiaXNOb3RFbXB0eSJ9XSwibG9naWNPcGVyYXRvciI6ImFuZCJ9LCJzb3J0TW9kZWwiOlt7ImZpZWxkIjoibmFtZSIsInNvcnQiOiJhc2MifV19 lobby\n```\n\nThe token decodes to:\n\n```json\n{\n  \"filterModel\": {\n    \"items\": [\n      { \"field\": \"floor\", \"operator\": \">=\", \"value\": 2 },\n      { \"field\": \"@department\", \"operator\": \"isAnyOf\", \"value\": [\"IT\", \"Facilities\"] },\n      { \"field\": \"building\", \"operator\": \"isNotEmpty\" }\n    ],\n    \"logicOperator\": \"and\"\n  },\n  \"sortModel\": [{ \"field\": \"name\", \"sort\": \"asc\" }]\n}\n```",
         "fields": null,
         "inputFields": [
           {
             "name": "id",
-            "description": null,
+            "description": "Entity ids to keep, by eq or in.",
             "type": {
               "kind": "INPUT_OBJECT",
               "name": "IDFilterExpressionInput",
@@ -13981,7 +13981,7 @@
           },
           {
             "name": "lastChangeDate",
-            "description": null,
+            "description": "When a merge last changed the entity in the graph; every operator set applies, so gte with lte is a closed range, and an entity never merged matches no bound.",
             "type": {
               "kind": "INPUT_OBJECT",
               "name": "TimestampFilterExpressionInput",
@@ -13993,7 +13993,7 @@
           },
           {
             "name": "lastChangeKind",
-            "description": null,
+            "description": "What the last merge did to the entity; only the first operator set among eq, in and ne applies.",
             "type": {
               "kind": "INPUT_OBJECT",
               "name": "ConnectorEntityChangeKindFilterExpressionInput",
@@ -14005,7 +14005,7 @@
           },
           {
             "name": "mappingKey",
-            "description": null,
+            "description": "Mapping keys to keep, by eq or in; applied by listConnectorEntities only, previewConnectorEntities ignores it.",
             "type": {
               "kind": "INPUT_OBJECT",
               "name": "IDFilterExpressionInput",
@@ -14017,7 +14017,7 @@
           },
           {
             "name": "mergingState",
-            "description": null,
+            "description": "Merging states to keep; listConnectorEntities applies the first operator set among eq, in and ne, previewConnectorEntities applies all of them to the state the entity would have after the save.",
             "type": {
               "kind": "INPUT_OBJECT",
               "name": "ConnectorEntityMergingStateFilterExpressionInput",
@@ -14029,7 +14029,7 @@
           },
           {
             "name": "refId",
-            "description": null,
+            "description": "Source-system ids to keep, by eq or in; applied by listConnectorEntities only, previewConnectorEntities ignores it.",
             "type": {
               "kind": "INPUT_OBJECT",
               "name": "IDFilterExpressionInput",
@@ -14041,7 +14041,7 @@
           },
           {
             "name": "searchQuery",
-            "description": null,
+            "description": "Free text, hashtag filters and an optional grid filter and sort token, honoured by previewConnectorEntities only (listConnectorEntities rejects it); see the type description for the grammar and an example.",
             "type": {
               "kind": "SCALAR",
               "name": "String",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapped/schema-graph-react-apollo",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "license": "MIT",
   "description": "Mapped Graph TypeScript typings for react-apollo",
   "repository": {