@coasys/ad4m 0.13.0-test-2 → 0.13.0-test-3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/lib/index.cjs +1060 -147
  2. package/lib/index.js +1054 -147
  3. package/lib/src/index.d.ts +0 -1
  4. package/lib/src/index.js +0 -1
  5. package/lib/src/language/Language.d.ts +26 -214
  6. package/lib/src/language/Language.js +28 -2
  7. package/lib/src/model/Ad4mModel.d.ts +25 -1
  8. package/lib/src/model/Ad4mModel.js +139 -30
  9. package/lib/src/model/Ad4mModel.test.js +214 -32
  10. package/lib/src/model/ModelQueryBuilder.d.ts +19 -0
  11. package/lib/src/model/ModelQueryBuilder.js +62 -18
  12. package/lib/src/model/hydration-batching.test.d.ts +7 -0
  13. package/lib/src/model/hydration-batching.test.js +456 -0
  14. package/lib/src/model/hydration.d.ts +1 -0
  15. package/lib/src/model/hydration.js +279 -70
  16. package/lib/src/model/query-sparql.d.ts +78 -1
  17. package/lib/src/model/query-sparql.js +447 -16
  18. package/lib/src/model/query-sparql.test.d.ts +1 -0
  19. package/lib/src/model/query-sparql.test.js +495 -0
  20. package/lib/src/model/query-utils.js +4 -0
  21. package/lib/src/model/subscription-delta.test.d.ts +24 -0
  22. package/lib/src/model/subscription-delta.test.js +180 -0
  23. package/lib/src/model/subscription-pool.js +48 -2
  24. package/lib/src/model/types.d.ts +49 -1
  25. package/lib/src/perspectives/PerspectiveClient.d.ts +2 -0
  26. package/lib/src/perspectives/PerspectiveClient.js +37 -9
  27. package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
  28. package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
  29. package/lib/src/perspectives/PerspectiveProxy.d.ts +3 -0
  30. package/lib/src/perspectives/PerspectiveProxy.js +15 -0
  31. package/package.json +1 -1
  32. package/src/Ad4mClient.test.ts +56 -1
  33. package/src/index.ts +0 -1
  34. package/src/language/Language.ts +54 -275
  35. package/src/model/Ad4mModel.test.ts +222 -35
  36. package/src/model/Ad4mModel.ts +144 -30
  37. package/src/model/ModelQueryBuilder.ts +66 -18
  38. package/src/model/hydration-batching.test.ts +563 -0
  39. package/src/model/hydration.ts +249 -47
  40. package/src/model/query-sparql.test.ts +568 -0
  41. package/src/model/query-sparql.ts +473 -16
  42. package/src/model/query-utils.ts +4 -0
  43. package/src/model/subscription-delta.test.ts +207 -0
  44. package/src/model/subscription-pool.ts +50 -2
  45. package/src/model/types.ts +50 -1
  46. package/src/perspectives/PerspectiveClient.test.ts +204 -0
  47. package/src/perspectives/PerspectiveClient.ts +36 -7
  48. package/src/perspectives/PerspectiveProxy.ts +18 -0
  49. package/lib/src/model/query-surreal.d.ts +0 -44
  50. package/lib/src/model/query-surreal.js +0 -249
  51. package/lib/src/model/surreal-utils.d.ts +0 -42
  52. package/lib/src/model/surreal-utils.js +0 -128
  53. package/src/language/LanguageContext.ts +0 -37
  54. package/tsconfig-browser.json +0 -82
package/lib/index.js CHANGED
@@ -5493,9 +5493,13 @@ function buildWhereCondition(predicate, condition, opts) {
5493
5493
  if (ops.not !== undefined) {
5494
5494
  if (Array.isArray(ops.not)) {
5495
5495
  const formattedValues = ops.not.map((v) => formatValue(v)).join(', ');
5496
+ // FILTER NOT EXISTS here is scoped to a specific predicate, not a global scan,
5497
+ // so O(N²) behavior is bounded by the number of values for this property.
5496
5498
  parts.push(`FILTER NOT EXISTS { ?target <${escapedPredicate}> ?_nval . FILTER(?_nval IN (${formattedValues})) }`);
5497
5499
  }
5498
5500
  else {
5501
+ // FILTER NOT EXISTS here is scoped to a specific predicate, not a global scan,
5502
+ // so O(N²) behavior is bounded by the number of values for this property.
5499
5503
  parts.push(`FILTER NOT EXISTS { ?target <${escapedPredicate}> ${formatValue(ops.not)} }`);
5500
5504
  }
5501
5505
  }
@@ -7248,6 +7252,21 @@ class PerspectiveProxy {
7248
7252
  __classPrivateFieldGet$9(this, _PerspectiveProxy_client, "f").addPerspectiveLinkUpdatedListener(__classPrivateFieldGet$9(this, _PerspectiveProxy_handle, "f").uuid, __classPrivateFieldGet$9(this, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, "f"));
7249
7253
  __classPrivateFieldGet$9(this, _PerspectiveProxy_client, "f").addPerspectiveSyncStateChangeListener(__classPrivateFieldGet$9(this, _PerspectiveProxy_handle, "f").uuid, __classPrivateFieldGet$9(this, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks, "f"));
7250
7254
  }
7255
+ /** Update the proxy's internal handle and public fields in-place.
7256
+ * Keeps the same object reference so all holders see the update. */
7257
+ updateHandle(handle) {
7258
+ if (handle.uuid !== __classPrivateFieldGet$9(this, _PerspectiveProxy_handle, "f").uuid) {
7259
+ throw new Error(`PerspectiveProxy.updateHandle: UUID mismatch — proxy is bound to "${__classPrivateFieldGet$9(this, _PerspectiveProxy_handle, "f").uuid}" but received handle with UUID "${handle.uuid}". ` +
7260
+ `This would silently diverge from listeners registered under the original UUID.`);
7261
+ }
7262
+ __classPrivateFieldSet$9(this, _PerspectiveProxy_handle, handle, "f");
7263
+ this.uuid = handle.uuid;
7264
+ this.name = handle.name;
7265
+ this.owners = handle.owners;
7266
+ this.sharedUrl = handle.sharedUrl;
7267
+ this.neighbourhood = handle.neighbourhood;
7268
+ this.state = handle.state;
7269
+ }
7251
7270
  /**
7252
7271
  * Escapes special regex characters in a string to prevent ReDoS attacks
7253
7272
  * and regex injection when building dynamic regular expressions.
@@ -8942,7 +8961,7 @@ var __classPrivateFieldGet$8 = (undefined && undefined.__classPrivateFieldGet) |
8942
8961
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
8943
8962
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
8944
8963
  };
8945
- var _PerspectiveClient_apolloClient, _PerspectiveClient_perspectiveAddedCallbacks, _PerspectiveClient_perspectiveUpdatedCallbacks, _PerspectiveClient_perspectiveRemovedCallbacks, _PerspectiveClient_perspectiveSyncStateChangeCallbacks, _PerspectiveClient_expressionClient, _PerspectiveClient_neighbourhoodClient, _PerspectiveClient_aiClient;
8964
+ var _PerspectiveClient_apolloClient, _PerspectiveClient_perspectiveAddedCallbacks, _PerspectiveClient_perspectiveUpdatedCallbacks, _PerspectiveClient_perspectiveRemovedCallbacks, _PerspectiveClient_perspectiveSyncStateChangeCallbacks, _PerspectiveClient_expressionClient, _PerspectiveClient_neighbourhoodClient, _PerspectiveClient_aiClient, _PerspectiveClient_proxyCache;
8946
8965
  const LINK_EXPRESSION_FIELDS = `
8947
8966
  author
8948
8967
  timestamp
@@ -8982,6 +9001,7 @@ class PerspectiveClient {
8982
9001
  _PerspectiveClient_expressionClient.set(this, void 0);
8983
9002
  _PerspectiveClient_neighbourhoodClient.set(this, void 0);
8984
9003
  _PerspectiveClient_aiClient.set(this, void 0);
9004
+ _PerspectiveClient_proxyCache.set(this, new Map());
8985
9005
  __classPrivateFieldSet$8(this, _PerspectiveClient_apolloClient, client, "f");
8986
9006
  __classPrivateFieldSet$8(this, _PerspectiveClient_perspectiveAddedCallbacks, [], "f");
8987
9007
  __classPrivateFieldSet$8(this, _PerspectiveClient_perspectiveUpdatedCallbacks, [], "f");
@@ -8993,6 +9013,17 @@ class PerspectiveClient {
8993
9013
  this.subscribePerspectiveRemoved();
8994
9014
  }
8995
9015
  }
9016
+ /** Get or create a proxy for a UUID. If the proxy exists in cache, update its handle and return it. */
9017
+ getOrCreateProxy(handle) {
9018
+ const existing = __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").get(handle.uuid);
9019
+ if (existing) {
9020
+ existing.updateHandle(handle);
9021
+ return existing;
9022
+ }
9023
+ const proxy = new PerspectiveProxy(handle, this);
9024
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").set(handle.uuid, proxy);
9025
+ return proxy;
9026
+ }
8996
9027
  setExpressionClient(client) {
8997
9028
  __classPrivateFieldSet$8(this, _PerspectiveClient_expressionClient, client, "f");
8998
9029
  }
@@ -9013,9 +9044,12 @@ class PerspectiveClient {
9013
9044
  }
9014
9045
  }`
9015
9046
  }));
9016
- return perspectives.map(handle => new PerspectiveProxy(handle, this));
9047
+ return perspectives.map(handle => this.getOrCreateProxy(handle));
9017
9048
  }
9018
9049
  async byUUID(uuid) {
9050
+ const cached = __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").get(uuid);
9051
+ if (cached)
9052
+ return cached;
9019
9053
  const { perspective } = unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").query({
9020
9054
  query: gql `query perspective($uuid: String!) {
9021
9055
  perspective(uuid: $uuid) {
@@ -9026,7 +9060,7 @@ class PerspectiveClient {
9026
9060
  }));
9027
9061
  if (!perspective)
9028
9062
  return null;
9029
- return new PerspectiveProxy(perspective, this);
9063
+ return this.getOrCreateProxy(perspective);
9030
9064
  }
9031
9065
  async snapshotByUUID(uuid) {
9032
9066
  const { perspectiveSnapshot } = unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").query({
@@ -9164,7 +9198,7 @@ class PerspectiveClient {
9164
9198
  }`,
9165
9199
  variables: { name }
9166
9200
  }));
9167
- return new PerspectiveProxy(perspectiveAdd, this);
9201
+ return this.getOrCreateProxy(perspectiveAdd);
9168
9202
  }
9169
9203
  async update(uuid, name) {
9170
9204
  const { perspectiveUpdate } = unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").mutate({
@@ -9175,9 +9209,12 @@ class PerspectiveClient {
9175
9209
  }`,
9176
9210
  variables: { uuid, name }
9177
9211
  }));
9178
- return new PerspectiveProxy(perspectiveUpdate, this);
9212
+ // Evict stale proxy — getOrCreateProxy will create a fresh one with updated handle
9213
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(uuid);
9214
+ return this.getOrCreateProxy(perspectiveUpdate);
9179
9215
  }
9180
9216
  async remove(uuid) {
9217
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(uuid);
9181
9218
  return unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").mutate({
9182
9219
  mutation: gql `mutation perspectiveRemove($uuid: String!) {
9183
9220
  perspectiveRemove(uuid: $uuid)
@@ -9330,9 +9367,12 @@ class PerspectiveClient {
9330
9367
  `
9331
9368
  }).subscribe({
9332
9369
  next: result => {
9370
+ const handle = result.data.perspectiveAdded;
9333
9371
  __classPrivateFieldGet$8(this, _PerspectiveClient_perspectiveAddedCallbacks, "f").forEach(cb => {
9334
- cb(result.data.perspectiveAdded);
9372
+ cb(handle);
9335
9373
  });
9374
+ // Populate cache so subsequent byUUID() calls get a hit
9375
+ this.getOrCreateProxy(handle);
9336
9376
  },
9337
9377
  error: (e) => console.error(e)
9338
9378
  });
@@ -9348,9 +9388,13 @@ class PerspectiveClient {
9348
9388
  `
9349
9389
  }).subscribe({
9350
9390
  next: result => {
9391
+ const handle = result.data.perspectiveUpdated;
9351
9392
  __classPrivateFieldGet$8(this, _PerspectiveClient_perspectiveUpdatedCallbacks, "f").forEach(cb => {
9352
- cb(result.data.perspectiveUpdated);
9393
+ cb(handle);
9353
9394
  });
9395
+ // Evict stale proxy and create fresh one with updated handle
9396
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(handle.uuid);
9397
+ this.getOrCreateProxy(handle);
9354
9398
  },
9355
9399
  error: (e) => console.error(e)
9356
9400
  });
@@ -9385,9 +9429,12 @@ class PerspectiveClient {
9385
9429
  `
9386
9430
  }).subscribe({
9387
9431
  next: result => {
9432
+ const uuid = result.data.perspectiveRemoved;
9388
9433
  __classPrivateFieldGet$8(this, _PerspectiveClient_perspectiveRemovedCallbacks, "f").forEach(cb => {
9389
- cb(result.data.perspectiveRemoved);
9434
+ cb(uuid);
9390
9435
  });
9436
+ // Evict from cache
9437
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(uuid);
9391
9438
  },
9392
9439
  error: (e) => console.error(e)
9393
9440
  });
@@ -9485,7 +9532,7 @@ class PerspectiveClient {
9485
9532
  return perspectiveCommitBatch;
9486
9533
  }
9487
9534
  }
9488
- _PerspectiveClient_apolloClient = new WeakMap(), _PerspectiveClient_perspectiveAddedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveUpdatedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveRemovedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveSyncStateChangeCallbacks = new WeakMap(), _PerspectiveClient_expressionClient = new WeakMap(), _PerspectiveClient_neighbourhoodClient = new WeakMap(), _PerspectiveClient_aiClient = new WeakMap();
9535
+ _PerspectiveClient_apolloClient = new WeakMap(), _PerspectiveClient_perspectiveAddedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveUpdatedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveRemovedCallbacks = new WeakMap(), _PerspectiveClient_perspectiveSyncStateChangeCallbacks = new WeakMap(), _PerspectiveClient_expressionClient = new WeakMap(), _PerspectiveClient_neighbourhoodClient = new WeakMap(), _PerspectiveClient_aiClient = new WeakMap(), _PerspectiveClient_proxyCache = new WeakMap();
9489
9536
 
9490
9537
  var __classPrivateFieldSet$7 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
9491
9538
  if (kind === "m") throw new TypeError("Private method is not writable");
@@ -18892,6 +18939,31 @@ var __decorate$6 = (undefined && undefined.__decorate) || function (decorators,
18892
18939
  var __metadata$6 = (undefined && undefined.__metadata) || function (k, v) {
18893
18940
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
18894
18941
  };
18942
+ /**
18943
+ * # AD4M Language — client-side types
18944
+ *
18945
+ * This file only contains the client-visible types that the AD4M GraphQL
18946
+ * API exposes on top of a running Language — interaction metadata, online
18947
+ * agent records, and the telepresence-signal callback shape.
18948
+ *
18949
+ * **If you're authoring an AD4M Language**, you don't consume types from
18950
+ * here — use [`@coasys/ad4m-ldk`](https://www.npmjs.com/package/@coasys/ad4m-ldk)
18951
+ * (or the [Rust ALDK](https://crates.io/crates/ad4m-ldk)), which provide
18952
+ * the capability traits, typed runtime-import wrappers, and authoring
18953
+ * macros/helpers.
18954
+ *
18955
+ * The normative interface definition lives in
18956
+ * [`docs-src/ad4m-lang.wit`](https://github.com/coasys/ad4m/blob/dev/docs-src/ad4m-lang.wit).
18957
+ * The prose spec is
18958
+ * [`docs-src/language-interface-spec.md`](https://github.com/coasys/ad4m/blob/dev/docs-src/language-interface-spec.md).
18959
+ */
18960
+ // ----- Interaction metadata --------------------------------------------------
18961
+ //
18962
+ // Languages optionally publish a list of user-invocable actions per
18963
+ // Expression ("interactions"). The runtime surfaces these to UIs via
18964
+ // GraphQL, which is why `InteractionParameter` / `InteractionMeta` /
18965
+ // `InteractionCall` need the type-graphql decorators — they cross the
18966
+ // GraphQL boundary as first-class objects.
18895
18967
  let InteractionParameter = class InteractionParameter {
18896
18968
  };
18897
18969
  __decorate$6([
@@ -18943,6 +19015,7 @@ InteractionCall = __decorate$6([
18943
19015
  InputType(),
18944
19016
  __metadata$6("design:paramtypes", [String, Object])
18945
19017
  ], InteractionCall);
19018
+ // ----- Telepresence ----------------------------------------------------------
18946
19019
  let OnlineAgent = class OnlineAgent {
18947
19020
  };
18948
19021
  __decorate$6([
@@ -18957,9 +19030,6 @@ OnlineAgent = __decorate$6([
18957
19030
  ObjectType()
18958
19031
  ], OnlineAgent);
18959
19032
 
18960
- class Dna {
18961
- }
18962
-
18963
19033
  var __decorate$5 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
18964
19034
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
18965
19035
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -19986,6 +20056,59 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
19986
20056
  *
19987
20057
  * @module
19988
20058
  */
20059
+ /**
20060
+ * Check whether a `where` clause contains filters that cannot be pushed down
20061
+ * to SPARQL and must be evaluated in JS after hydration.
20062
+ *
20063
+ * JS-only filters include:
20064
+ * - Literal-stored properties (equality, comparison, contains, etc.)
20065
+ * - Reverse relations (belongsToOne / belongsToMany)
20066
+ * - author / timestamp filters (skipped by buildSPARQLWhereFilters)
20067
+ *
20068
+ * When JS-only filters exist, SPARQL-level LIMIT/OFFSET must NOT be applied
20069
+ * because the database would cap the candidate set before JS filters run,
20070
+ * potentially discarding matches beyond the LIMIT.
20071
+ */
20072
+ function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
20073
+ if (!where)
20074
+ return false;
20075
+ for (const [propertyName, condition] of Object.entries(where)) {
20076
+ if (propertyName === "base" || propertyName === "id")
20077
+ continue;
20078
+ // author/timestamp: return true so that count() falls back to the full hydration
20079
+ // path (which uses buildSPARQLQuery — which DOES bind ?author/?timestamp via the
20080
+ // named graph block). buildSPARQLCountQuery intentionally omits the named graph,
20081
+ // so emitting an ?author FILTER there would produce unbound-variable SPARQL.
20082
+ // buildSPARQLWhereFilters still pushes these into FILTER when called from
20083
+ // buildSPARQLQuery / buildSPARQLGroupedCountQuery, which both include the named graph.
20084
+ if (propertyName === "author" || propertyName === "timestamp")
20085
+ return true;
20086
+ const propMeta = metadata.properties[propertyName];
20087
+ if (!propMeta)
20088
+ continue;
20089
+ // Reverse relations are JS-only
20090
+ const relMeta = allRelationsMetadata[propertyName];
20091
+ if (relMeta && (relMeta.kind === 'belongsToOne' || relMeta.kind === 'belongsToMany')) {
20092
+ return true;
20093
+ }
20094
+ // Literal-stored properties: equality/IN/NOT can be pushed to SPARQL via
20095
+ // <ad4m://fn/parse_literal>(), but comparison operators (gt/lt/gte/lte/between/contains)
20096
+ // must remain JS-only because parse_literal returns strings.
20097
+ if (isLiteralStoredProperty(propMeta)) {
20098
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
20099
+ const ops = condition;
20100
+ const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
20101
+ ops.lt !== undefined || ops.lte !== undefined ||
20102
+ ops.between !== undefined || ops.contains !== undefined;
20103
+ if (hasCompOps)
20104
+ return true;
20105
+ // NOT with simple value can be pushed to SPARQL — not JS-only
20106
+ }
20107
+ // Simple equality and IN filters can be pushed to SPARQL — not JS-only
20108
+ }
20109
+ }
20110
+ return false;
20111
+ }
19989
20112
  /**
19990
20113
  * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
19991
20114
  * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
@@ -20029,6 +20152,30 @@ function formatSPARQLValue(value) {
20029
20152
  function iri(value) {
20030
20153
  return `<${value}>`;
20031
20154
  }
20155
+ /**
20156
+ * Map a user-facing property name to the SPARQL variable alias used in the query.
20157
+ *
20158
+ * Properties appear in the query as:
20159
+ * - Required properties: `?cfTarget_${name}`
20160
+ * - Where-clause joins: `?wTarget_${name}`
20161
+ * - Initial-value fallback: `?cfInitTarget_${name}`
20162
+ *
20163
+ * For ORDER BY, we prefer the conformance variable (always present for required props),
20164
+ * then the where-target variable.
20165
+ */
20166
+ function mapPropertyToSPARQLVar(propertyName, metadata) {
20167
+ const propMeta = metadata.properties[propertyName];
20168
+ if (propMeta) {
20169
+ if (propMeta.required && !propMeta.getter && !(propMeta.flag && propMeta.initial)) {
20170
+ return `?cfTarget_${propertyName}`;
20171
+ }
20172
+ if (propMeta.initial && !propMeta.flag) {
20173
+ return `?cfInitTarget_${propertyName}`;
20174
+ }
20175
+ }
20176
+ // Fallback: where-clause variable or raw name
20177
+ return `?wTarget_${propertyName}`;
20178
+ }
20032
20179
  /**
20033
20180
  * Build a SPARQL query that returns all links belonging to instances of
20034
20181
  * the given model class, optionally filtered by `where` conditions.
@@ -20112,6 +20259,35 @@ function buildSPARQLQuery(metadata, allRelationsMetadata, query, modelClass) {
20112
20259
  const filterClause = filterExpressions.length > 0
20113
20260
  ? `FILTER(\n ${filterExpressions.join(" &&\n ")}\n )`
20114
20261
  : "";
20262
+ // Determine if SPARQL-level pagination is safe.
20263
+ // When JS-only where filters exist, we must NOT limit at the SPARQL level
20264
+ // because the database would cap candidates before JS filters run.
20265
+ // Without an explicit ORDER BY, SPARQL OFFSET/LIMIT produces non-deterministic
20266
+ // ordering across different query plans and index traversals. Fall back to
20267
+ // JS-level slicing in that case to preserve the grouping order from the full
20268
+ // result set.
20269
+ const canPaginateInSPARQL = !hasJsOnlyWhereFilters(metadata, allRelationsMetadata, query.where)
20270
+ && (query.limit !== undefined || query.offset !== undefined)
20271
+ && query.order !== undefined && Object.keys(query.order).length > 0;
20272
+ // Build a pagination subquery that constrains ?source to only the page
20273
+ // of interest. This avoids fetching all links for all matching instances.
20274
+ const paginationSubquery = canPaginateInSPARQL
20275
+ ? buildPaginationSubquery(joinPatterns, filterExpressions, metadata, query)
20276
+ : '';
20277
+ if (paginationSubquery) {
20278
+ // Use the pagination subquery to constrain ?source, then fetch all links
20279
+ // for those sources only.
20280
+ return `
20281
+ SELECT ?source ?predicate ?target ?author ?timestamp WHERE {
20282
+ ${paginationSubquery}${joinClause}
20283
+ GRAPH ?linkGraph { ?source ?predicate ?target . }
20284
+ FILTER(isIRI(?source) && isIRI(?predicate))
20285
+ ?linkGraph <ad4m://ontology/author> ?author .
20286
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
20287
+ ${filterClause}
20288
+ }
20289
+ `.trim();
20290
+ }
20115
20291
  return `
20116
20292
  SELECT ?source ?predicate ?target ?author ?timestamp WHERE {${joinClause}
20117
20293
  GRAPH ?linkGraph { ?source ?predicate ?target . }
@@ -20125,10 +20301,146 @@ function buildSPARQLQuery(metadata, allRelationsMetadata, query, modelClass) {
20125
20301
  }
20126
20302
  /**
20127
20303
  * Build ORDER BY / LIMIT / OFFSET clauses for the SPARQL query.
20304
+ *
20305
+ * NOTE: The outer SELECT returns multiple rows per instance (one per link),
20306
+ * so LIMIT/OFFSET at the outer level would cut off links mid-instance.
20307
+ * This function is kept for backward compatibility and always returns "".
20308
+ * SPARQL-level pagination is handled via a subquery in buildSPARQLQuery
20309
+ * using buildPaginationSubquery().
20128
20310
  */
20129
- function buildSPARQLOrderLimitOffset(_metadata, _query) {
20311
+ function buildSPARQLOrderLimitOffset(_metadata, query) {
20130
20312
  return "";
20131
20313
  }
20314
+ /**
20315
+ * Build an inner subquery that selects DISTINCT ?source URIs with
20316
+ * ORDER BY, LIMIT, and OFFSET applied at the instance level.
20317
+ *
20318
+ * Because the outer SELECT returns multiple rows per instance (one per link),
20319
+ * we cannot apply LIMIT/OFFSET there. Instead this subquery constrains
20320
+ * ?source to only the instances on the requested page.
20321
+ *
20322
+ * @internal — used by buildSPARQLQuery when SPARQL-level pagination is safe.
20323
+ */
20324
+ function buildPaginationSubquery(joinPatterns, filterExpressions, metadata, query) {
20325
+ const innerJoin = joinPatterns.join('\n');
20326
+ const innerFilter = filterExpressions.length > 0
20327
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
20328
+ : '';
20329
+ // Build ORDER BY clause from query.order.
20330
+ // When ORDER BY references non-grouped variables we must use SAMPLE()
20331
+ // aggregates so the query is valid SPARQL 1.1.
20332
+ let orderByClause = '';
20333
+ const orderJoinPatterns = [];
20334
+ const sampleProjections = []; // e.g. (SAMPLE(?cfTarget_title) AS ?pg_sort_0)
20335
+ const needsGroupBy = query.order && Object.keys(query.order).length > 0;
20336
+ if (query.order) {
20337
+ let sortIdx = 0;
20338
+ const orderTerms = Object.entries(query.order).map(([prop, dir]) => {
20339
+ const sparqlVar = mapPropertyToSPARQLVar(prop, metadata);
20340
+ // Check if this order property's variable is already bound by existing
20341
+ // join patterns. If not, add an OPTIONAL join so ORDER BY is deterministic.
20342
+ const varAlreadyBound = innerJoin.includes(sparqlVar);
20343
+ if (!varAlreadyBound) {
20344
+ const propMeta = metadata.properties[prop];
20345
+ if (propMeta && propMeta.predicate && !propMeta.getter) {
20346
+ orderJoinPatterns.push(`\n OPTIONAL { ?source <${propMeta.predicate}> ${sparqlVar} . }`);
20347
+ }
20348
+ }
20349
+ // Use SAMPLE() aggregate so ORDER BY is valid with GROUP BY ?source.
20350
+ const sortAlias = `?pg_sort_${sortIdx++}`;
20351
+ sampleProjections.push(`(SAMPLE(${sparqlVar}) AS ${sortAlias})`);
20352
+ return dir === 'DESC' ? `DESC(${sortAlias})` : `ASC(${sortAlias})`;
20353
+ });
20354
+ if (orderTerms.length > 0) {
20355
+ orderByClause = `ORDER BY ${orderTerms.join(' ')}`;
20356
+ }
20357
+ }
20358
+ const limitClause = query.limit !== undefined ? `LIMIT ${query.limit}` : '';
20359
+ const offsetClause = query.offset !== undefined && query.offset > 0 ? `OFFSET ${query.offset}` : '';
20360
+ // When there's no ORDER BY, DISTINCT alone handles deduplication — no GROUP BY needed.
20361
+ // When there IS ORDER BY, use GROUP BY ?source with SAMPLE() aggregates for the sort keys.
20362
+ const sampleSelect = sampleProjections.length > 0 ? ' ' + sampleProjections.join(' ') : '';
20363
+ const groupByClause = needsGroupBy ? 'GROUP BY ?source' : '';
20364
+ return `
20365
+ { SELECT DISTINCT ?source${sampleSelect} WHERE {${innerJoin}${orderJoinPatterns.join('')}
20366
+ FILTER(isIRI(?source))
20367
+ ${innerFilter}
20368
+ } ${groupByClause} ${orderByClause} ${limitClause} ${offsetClause} }\n`;
20369
+ }
20370
+ /**
20371
+ * Build a SPARQL COUNT query that returns the total number of matching
20372
+ * instances WITHOUT hydrating them. Uses the same WHERE clause as
20373
+ * buildSPARQLQuery but wraps it in SELECT (COUNT(DISTINCT ?source) AS ?count).
20374
+ *
20375
+ * LIMIT/OFFSET from the query are stripped internally — this always counts
20376
+ * the full result set.
20377
+ */
20378
+ function buildSPARQLCountQuery(metadata, allRelationsMetadata, query, modelClass) {
20379
+ // Build the same join/filter patterns as buildSPARQLQuery
20380
+ const joinPatterns = [];
20381
+ const filterExpressions = [];
20382
+ if (query.parent) {
20383
+ const parentPredicate = resolveParentPredicate(query.parent, modelClass);
20384
+ joinPatterns.push(`\n ${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
20385
+ }
20386
+ let hasConformance = false;
20387
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20388
+ if (propMeta.required) {
20389
+ if (propMeta.getter)
20390
+ continue;
20391
+ hasConformance = true;
20392
+ if (propMeta.flag && propMeta.initial) {
20393
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20394
+ }
20395
+ else {
20396
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
20397
+ }
20398
+ }
20399
+ }
20400
+ if (!hasConformance) {
20401
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20402
+ if (propMeta.initial) {
20403
+ hasConformance = true;
20404
+ if (propMeta.flag) {
20405
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20406
+ }
20407
+ else {
20408
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
20409
+ }
20410
+ break;
20411
+ }
20412
+ }
20413
+ }
20414
+ if (!hasConformance && joinPatterns.length === 0) {
20415
+ const knownPredicates = [];
20416
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20417
+ if (propMeta.predicate)
20418
+ knownPredicates.push(iri(propMeta.predicate));
20419
+ }
20420
+ if (metadata.relations) {
20421
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
20422
+ if (relMeta.predicate)
20423
+ knownPredicates.push(iri(relMeta.predicate));
20424
+ }
20425
+ }
20426
+ if (knownPredicates.length > 0) {
20427
+ joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(", ")})) } }`);
20428
+ }
20429
+ }
20430
+ const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, query.where);
20431
+ joinPatterns.push(...userJoins);
20432
+ filterExpressions.push(...userFilters);
20433
+ const joinClause = joinPatterns.join('\n');
20434
+ const filterClause = filterExpressions.length > 0
20435
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
20436
+ : '';
20437
+ return `
20438
+ SELECT (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
20439
+ FILTER(isIRI(?source))
20440
+ ${filterClause}
20441
+ }
20442
+ `.trim();
20443
+ }
20132
20444
  /**
20133
20445
  * Build a SPARQL query to fetch all links for a single instance.
20134
20446
  */
@@ -20199,7 +20511,53 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
20199
20511
  }
20200
20512
  continue;
20201
20513
  }
20202
- if (propertyName === "author" || propertyName === "timestamp") {
20514
+ if (propertyName === "author") {
20515
+ // ?author is bound by the named graph block in buildSPARQLQuery /
20516
+ // buildSPARQLGroupedCountQuery — push equality/IN filters into SPARQL.
20517
+ if (Array.isArray(condition)) {
20518
+ const formatted = condition.map(v => formatSPARQLValue(String(v))).join(', ');
20519
+ filters.push(`STR(?author) IN (${formatted})`);
20520
+ }
20521
+ else if (typeof condition === 'object' && condition !== null) {
20522
+ const ops = condition;
20523
+ if (ops.not !== undefined) {
20524
+ if (Array.isArray(ops.not)) {
20525
+ const formatted = ops.not.map((v) => formatSPARQLValue(String(v))).join(', ');
20526
+ filters.push(`!(STR(?author) IN (${formatted}))`);
20527
+ }
20528
+ else {
20529
+ filters.push(`STR(?author) != ${formatSPARQLValue(String(ops.not))}`);
20530
+ }
20531
+ }
20532
+ // Other operators (gt/lt/etc.) fall through to JS post-filter
20533
+ }
20534
+ else {
20535
+ filters.push(`STR(?author) = ${formatSPARQLValue(String(condition))}`);
20536
+ }
20537
+ continue;
20538
+ }
20539
+ if (propertyName === "timestamp") {
20540
+ // ?timestamp is bound by the named graph block — push numeric comparisons.
20541
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
20542
+ const ops = condition;
20543
+ if (ops.gt !== undefined)
20544
+ filters.push(`?timestamp > ${Number(ops.gt)}`);
20545
+ if (ops.gte !== undefined)
20546
+ filters.push(`?timestamp >= ${Number(ops.gte)}`);
20547
+ if (ops.lt !== undefined)
20548
+ filters.push(`?timestamp < ${Number(ops.lt)}`);
20549
+ if (ops.lte !== undefined)
20550
+ filters.push(`?timestamp <= ${Number(ops.lte)}`);
20551
+ if (ops.between !== undefined && Array.isArray(ops.between)) {
20552
+ filters.push(`?timestamp >= ${Number(ops.between[0])} && ?timestamp <= ${Number(ops.between[1])}`);
20553
+ }
20554
+ if (ops.not !== undefined) {
20555
+ filters.push(`?timestamp != ${Number(ops.not)}`);
20556
+ }
20557
+ }
20558
+ else if (typeof condition === 'number' || (typeof condition === 'string' && !isNaN(Number(condition)))) {
20559
+ filters.push(`?timestamp = ${Number(condition)}`);
20560
+ }
20203
20561
  continue;
20204
20562
  }
20205
20563
  const propMeta = metadata.properties[propertyName];
@@ -20214,33 +20572,49 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
20214
20572
  }
20215
20573
  // Determine if this property stores values as literal: IRIs
20216
20574
  const useParseLiteral = isLiteralStoredProperty(propMeta);
20217
- // For literal-stored properties, skip SPARQL-level FILTER expressions entirely.
20218
- // The parse_literal custom function is unreliable across oxigraph versions and
20219
- // environments. All property-level where filtering is done in JS post-filter
20220
- // (instancesFromQueryResult) after hydration resolves values to JS primitives.
20221
- // We only add a JOIN pattern to ensure the property exists (conformance check).
20575
+ // For literal-stored properties, push equality/IN/NOT filters to SPARQL using
20576
+ // <ad4m://fn/parse_literal>() which extracts the raw value from literal: IRIs.
20577
+ // The correct SPARQL syntax is <ad4m://fn/parse_literal>(?var) — NOT fn::parse_literal
20578
+ // (which was SurrealDB syntax that Oxigraph rejects at parse time).
20579
+ // Comparison operators (gt/lt/gte/lte/between/contains) remain JS-only because
20580
+ // parse_literal returns strings and numeric/date comparisons would be unreliable.
20581
+ // JS post-filter in instancesFromQueryResult remains as a safety net for all cases.
20222
20582
  if (useParseLiteral) {
20223
- // Just ensure the property exists — no value filtering in SPARQL
20224
20583
  if (typeof condition === "object" && condition !== null && !Array.isArray(condition)) {
20225
20584
  const ops = condition;
20226
20585
  const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
20227
20586
  ops.lt !== undefined || ops.lte !== undefined ||
20228
- ops.between !== undefined || ops.contains !== undefined ||
20229
- ops.not !== undefined;
20587
+ ops.between !== undefined || ops.contains !== undefined;
20230
20588
  if (hasCompOps) {
20589
+ // Comparison operators: join only, filter in JS
20231
20590
  joins.push(`
20232
20591
  ?source ${iri(propMeta.predicate)} ?wTarget_cmp_${propertyName} .`);
20233
20592
  }
20234
- // NOT filters: no SPARQL-level filtering — handled in JS
20593
+ if (ops.not !== undefined) {
20594
+ // NOT filter: push down to SPARQL
20595
+ joins.push(`
20596
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
20597
+ if (Array.isArray(ops.not)) {
20598
+ const formatted = ops.not.map((v) => formatSPARQLValue(v)).join(", ");
20599
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) NOT IN (${formatted})`);
20600
+ }
20601
+ else {
20602
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) != ${formatSPARQLValue(ops.not)}`);
20603
+ }
20604
+ }
20605
+ }
20606
+ else if (Array.isArray(condition)) {
20607
+ // IN filter: push down to SPARQL
20608
+ joins.push(`
20609
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
20610
+ const formatted = condition.map((v) => formatSPARQLValue(v)).join(", ");
20611
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) IN (${formatted})`);
20235
20612
  }
20236
20613
  else {
20237
- // Simple equality or IN — add join for conformance.
20238
- // NOTE: push-down FILTER with fn::parse_literal was attempted but removed because
20239
- // Oxigraph's query parser rejects the fn:: custom function syntax at parse time
20240
- // (custom functions are only available at execution time). All literal property
20241
- // filtering is done in JS post-filter after hydration resolves values.
20614
+ // Simple equality: push down to SPARQL
20242
20615
  joins.push(`
20243
20616
  ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
20617
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) = ${formatSPARQLValue(condition)}`);
20244
20618
  }
20245
20619
  }
20246
20620
  else if (Array.isArray(condition)) {
@@ -20285,6 +20659,133 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
20285
20659
  }
20286
20660
  return { joins, filters };
20287
20661
  }
20662
+ /**
20663
+ * Parse a SPARQL COUNT result row into a number.
20664
+ * Handles `row.count?.value` (RDF binding), `row.count` (direct number/string),
20665
+ * NaN results, and empty/malformed results.
20666
+ *
20667
+ * @returns The parsed count, or `null` if the result cannot be interpreted.
20668
+ */
20669
+ function parseSparqlCount(result) {
20670
+ if (!Array.isArray(result) || result.length === 0)
20671
+ return null;
20672
+ const row = result[0];
20673
+ const val = row.count?.value ?? row.count;
20674
+ if (val === undefined || val === null)
20675
+ return null;
20676
+ const parsed = typeof val === 'number' ? val : parseInt(String(val), 10);
20677
+ return isNaN(parsed) ? null : parsed;
20678
+ }
20679
+ /**
20680
+ * Build a SPARQL query that counts child instances grouped by parent IRI.
20681
+ *
20682
+ * Used by the projection Path A (`count: true`) in `hydrateRelations` to get
20683
+ * per-parent counts in a single round-trip with zero instance hydration.
20684
+ *
20685
+ * Includes the full named graph block so that `?author` and `?timestamp` are
20686
+ * bound and available for SPARQL FILTER expressions (unlike the intentionally
20687
+ * minimal `buildSPARQLCountQuery` which omits them for speed).
20688
+ *
20689
+ * @param metadata - Model metadata for the **child** (target) class
20690
+ * @param allRelationsMetadata - Relations metadata for the child class
20691
+ * @param relationPredicate - The predicate linking `?parent` → `?source` (child)
20692
+ * @param parentIds - IRI strings of all parent instances to count for
20693
+ * @param where - Optional filter applied to child instances
20694
+ */
20695
+ function buildSPARQLGroupedCountQuery(metadata, allRelationsMetadata, relationPredicate, parentIds, where) {
20696
+ const joinPatterns = [];
20697
+ const filterExpressions = [];
20698
+ // Parent → child join and IN filter
20699
+ joinPatterns.push(`\n ?parent ${iri(relationPredicate)} ?source .`);
20700
+ const parentIris = parentIds.map(id => iri(id)).join(', ');
20701
+ filterExpressions.push(`?parent IN (${parentIris})`);
20702
+ // Conformance patterns (mirrors buildSPARQLCountQuery logic)
20703
+ let hasConformance = false;
20704
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20705
+ if (propMeta.required) {
20706
+ if (propMeta.getter)
20707
+ continue;
20708
+ hasConformance = true;
20709
+ if (propMeta.flag && propMeta.initial) {
20710
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20711
+ }
20712
+ else {
20713
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
20714
+ }
20715
+ }
20716
+ }
20717
+ if (!hasConformance) {
20718
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20719
+ if (propMeta.initial) {
20720
+ hasConformance = true;
20721
+ if (propMeta.flag) {
20722
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20723
+ }
20724
+ else {
20725
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
20726
+ }
20727
+ break;
20728
+ }
20729
+ }
20730
+ }
20731
+ if (!hasConformance && joinPatterns.length <= 1) {
20732
+ // Only the parent join so far — add open-world structural matching
20733
+ const knownPredicates = [];
20734
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20735
+ if (propMeta.predicate)
20736
+ knownPredicates.push(iri(propMeta.predicate));
20737
+ }
20738
+ if (metadata.relations) {
20739
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
20740
+ if (relMeta.predicate)
20741
+ knownPredicates.push(iri(relMeta.predicate));
20742
+ }
20743
+ }
20744
+ if (knownPredicates.length > 0) {
20745
+ joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(', ')})) } }`);
20746
+ }
20747
+ }
20748
+ // User where-clause filters (including author/timestamp after the SPARQL push)
20749
+ const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, where);
20750
+ joinPatterns.push(...userJoins);
20751
+ filterExpressions.push(...userFilters);
20752
+ const joinClause = joinPatterns.join('\n');
20753
+ const filterClause = filterExpressions.length > 0
20754
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
20755
+ : '';
20756
+ return `
20757
+ SELECT ?parent (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
20758
+ GRAPH ?linkGraph { ?source ?predicate ?target . }
20759
+ FILTER(isIRI(?source) && isIRI(?predicate))
20760
+ ?linkGraph <ad4m://ontology/author> ?author .
20761
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
20762
+ ${filterClause}
20763
+ }
20764
+ GROUP BY ?parent
20765
+ `.trim();
20766
+ }
20767
+ /**
20768
+ * Parse the result of `buildSPARQLGroupedCountQuery` into a map from parent IRI
20769
+ * to count. Missing parents (zero matches) are absent from the map — callers
20770
+ * should use `map.get(id) ?? 0`.
20771
+ *
20772
+ * @returns Map from parentId string → count number
20773
+ */
20774
+ function parseSparqlGroupedCount(result) {
20775
+ const out = new Map();
20776
+ if (!Array.isArray(result))
20777
+ return out;
20778
+ for (const row of result) {
20779
+ const parentVal = row.parent?.value ?? row.parent;
20780
+ const countVal = row.count?.value ?? row.count;
20781
+ if (!parentVal || countVal === undefined || countVal === null)
20782
+ continue;
20783
+ const parsed = typeof countVal === 'number' ? countVal : parseInt(String(countVal), 10);
20784
+ if (!isNaN(parsed))
20785
+ out.set(String(parentVal), parsed);
20786
+ }
20787
+ return out;
20788
+ }
20288
20789
 
20289
20790
  /**
20290
20791
  * Subscription Pool — deduplicates identical SPARQL subscriptions.
@@ -20343,14 +20844,60 @@ async function pooledSubscribe(perspective, sparqlQuery, hydrate, onResult) {
20343
20844
  refCount: 1,
20344
20845
  };
20345
20846
  pool.set(key, newEntry);
20346
- // Set up shared result handler
20847
+ // Set up shared result handler with delta optimization
20347
20848
  subscription.onResult(async (rawResult) => {
20849
+ const prevRaw = newEntry.latestRaw;
20348
20850
  newEntry.latestRaw = rawResult;
20349
20851
  newEntry.hydrating = true;
20350
20852
  try {
20351
- // Hydrate ONCE using the first subscriber's hydrate function
20352
20853
  const firstSub = newEntry.callbacks.values().next().value;
20353
20854
  if (firstSub) {
20855
+ // Delta optimization: if the new result is strictly an addition
20856
+ // (all previous rows still present + new rows), only hydrate the
20857
+ // new rows and append them to the cached hydrated result.
20858
+ const prevArr = Array.isArray(prevRaw) ? prevRaw : [];
20859
+ const newArr = Array.isArray(rawResult) ? rawResult : [];
20860
+ const prevHydrated = newEntry.latestHydrated;
20861
+ if (prevHydrated &&
20862
+ Array.isArray(prevHydrated) &&
20863
+ newArr.length > prevArr.length &&
20864
+ newArr.length - prevArr.length <= 5 // small delta — worth optimizing
20865
+ ) {
20866
+ // Build a set of source URIs from previous results for quick lookup
20867
+ const prevSources = new Set(prevArr.map((r) => `${r.source}|${r.predicate}|${r.target}`));
20868
+ const addedRows = newArr.filter((r) => !prevSources.has(`${r.source}|${r.predicate}|${r.target}`));
20869
+ // Check that no rows were removed (pure addition)
20870
+ const newSources = new Set(newArr.map((r) => `${r.source}|${r.predicate}|${r.target}`));
20871
+ const removedRows = prevArr.filter((r) => !newSources.has(`${r.source}|${r.predicate}|${r.target}`));
20872
+ if (removedRows.length === 0 && addedRows.length > 0) {
20873
+ // Verify ALL added rows have sources not in previous results.
20874
+ // If any added row's source matches an existing source, it means
20875
+ // an existing instance got new links — we need full rehydration.
20876
+ const prevSourceIds = new Set(prevArr.map((r) => r.source));
20877
+ const allNewSources = addedRows.every((r) => !prevSourceIds.has(r.source));
20878
+ if (allNewSources) {
20879
+ // Pure addition of new instances — hydrate only the new rows
20880
+ try {
20881
+ const deltaHydrated = await firstSub.hydrate(addedRows);
20882
+ if (Array.isArray(deltaHydrated)) {
20883
+ const merged = [...prevHydrated, ...deltaHydrated];
20884
+ newEntry.latestHydrated = merged;
20885
+ for (const cb of newEntry.callbacks) {
20886
+ try {
20887
+ cb.onResult(merged);
20888
+ }
20889
+ catch (e) { /* subscriber error */ }
20890
+ }
20891
+ return; // Delta path succeeded
20892
+ }
20893
+ }
20894
+ catch {
20895
+ // Delta hydration failed — fall through to full hydration
20896
+ }
20897
+ }
20898
+ }
20899
+ }
20900
+ // Full hydration fallback
20354
20901
  const hydrated = await firstSub.hydrate(rawResult);
20355
20902
  newEntry.latestHydrated = hydrated;
20356
20903
  // Distribute to all callbacks
@@ -20609,6 +21156,28 @@ class ModelQueryBuilder {
20609
21156
  this.queryParams.properties = properties;
20610
21157
  return this;
20611
21158
  }
21159
+ /**
21160
+ * Opts in to evaluating SPARQL property getters during collection hydration.
21161
+ *
21162
+ * By default, collection queries skip getter evaluation for performance.
21163
+ * Call `.deepQuery()` when you need getter-backed properties in the result set.
21164
+ *
21165
+ * @returns The query builder for chaining
21166
+ *
21167
+ * @example
21168
+ * ```typescript
21169
+ * const messages = await Message.query(perspective)
21170
+ * .parent(channel)
21171
+ * .deepQuery()
21172
+ * .limit(30)
21173
+ * .get();
21174
+ * // messages[i].replyingTo is populated
21175
+ * ```
21176
+ */
21177
+ deepQuery() {
21178
+ this.queryParams.deepQuery = true;
21179
+ return this;
21180
+ }
20612
21181
  /**
20613
21182
  * Specifies which relations to eager-load (hydrate into model instances).
20614
21183
  *
@@ -20693,9 +21262,9 @@ class ModelQueryBuilder {
20693
21262
  * Groups raw SPARQL results and hydrates them into model instances.
20694
21263
  * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
20695
21264
  */
20696
- async processSparqlResult(rawResult, queryOverride) {
21265
+ async processSparqlResult(rawResult, queryOverride, computeTotalCount = false) {
20697
21266
  const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
20698
- return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped);
21267
+ return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped, computeTotalCount);
20699
21268
  }
20700
21269
  /**
20701
21270
  * Returns the first matching instance, or `null` if none match.
@@ -20758,9 +21327,9 @@ class ModelQueryBuilder {
20758
21327
  const buildFingerprint = (results) => {
20759
21328
  if (results.length === 0)
20760
21329
  return '0:';
20761
- const ids = results.map((r) => r.id || '').sort().join(',');
20762
- const ts = results.map((r) => r.updatedAt || r.timestamp || '').join(',');
20763
- return `${results.length}:${ids}:${ts}`;
21330
+ // Must include relation data (e.g. tags) — not just id/timestamp.
21331
+ // Otherwise @HasMany changes on existing instances are suppressed as duplicates.
21332
+ return JSON.stringify(results, (_, v) => typeof v === 'function' ? undefined : v);
20764
21333
  };
20765
21334
  const hydrate = async (rawResult) => {
20766
21335
  const { results } = await this.processSparqlResult(rawResult);
@@ -20822,10 +21391,19 @@ class ModelQueryBuilder {
20822
21391
  */
20823
21392
  async count() {
20824
21393
  if (this.engineFlag === 'sparql') {
20825
- const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
20826
- const rawResult = await this.perspective.querySparql(sparqlQuery);
20827
- const { totalCount } = await this.processSparqlResult(rawResult);
20828
- return totalCount;
21394
+ // When query has JS-only where filters, fall back to full hydration
21395
+ const metadata = this.ctor.getModelMetadata();
21396
+ const allRelMeta = getRelationsMetadata(this.ctor);
21397
+ if (hasJsOnlyWhereFilters(metadata, allRelMeta, this.queryParams.where)) {
21398
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
21399
+ const rawResult = await this.perspective.querySparql(sparqlQuery);
21400
+ const { totalCount } = await this.processSparqlResult(rawResult, undefined, true);
21401
+ return totalCount;
21402
+ }
21403
+ // Use efficient COUNT query — no hydration
21404
+ const countSparql = await this.ctor.countQueryToSPARQL(this.perspective, this.queryParams);
21405
+ const countResult = await this.perspective.querySparql(countSparql);
21406
+ return parseSparqlCount(countResult) ?? 0;
20829
21407
  }
20830
21408
  else {
20831
21409
  const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -20885,11 +21463,11 @@ class ModelQueryBuilder {
20885
21463
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
20886
21464
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
20887
21465
  const processResults = async (result) => {
20888
- const { totalCount } = await this.processSparqlResult(result);
21466
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
20889
21467
  callback(totalCount);
20890
21468
  };
20891
21469
  this.currentSubscription.onResult(processResults);
20892
- const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
21470
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
20893
21471
  // Initial count returned via Promise — callback for updates only
20894
21472
  return totalCount;
20895
21473
  }
@@ -20914,11 +21492,11 @@ class ModelQueryBuilder {
20914
21492
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
20915
21493
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
20916
21494
  const processResults = async (result) => {
20917
- const { totalCount } = await this.processSparqlResult(result);
21495
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
20918
21496
  callback(totalCount);
20919
21497
  };
20920
21498
  this.currentSubscription.onResult(processResults);
20921
- const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
21499
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
20922
21500
  // Initial count returned via Promise — callback for updates only
20923
21501
  return totalCount;
20924
21502
  }
@@ -20942,7 +21520,7 @@ class ModelQueryBuilder {
20942
21520
  if (this.engineFlag === 'sparql') {
20943
21521
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
20944
21522
  const result = await this.perspective.querySparql(sparqlQuery);
20945
- const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
21523
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery, true);
20946
21524
  return { results, totalCount, pageSize, pageNumber };
20947
21525
  }
20948
21526
  else {
@@ -21004,14 +21582,26 @@ class ModelQueryBuilder {
21004
21582
  this.dispose();
21005
21583
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
21006
21584
  if (this.engineFlag === 'sparql') {
21007
- const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
21585
+ // Subscribe to the FULL result set (no LIMIT/OFFSET) so the subscription
21586
+ // detects changes anywhere in the dataset (e.g. new items beyond current page).
21587
+ // Pagination is applied in JS when processing each update.
21588
+ const subscriptionParams = { ...(this.queryParams || {}) };
21589
+ delete subscriptionParams.limit;
21590
+ delete subscriptionParams.offset;
21591
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, subscriptionParams);
21008
21592
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
21593
+ // Query for processSparqlResult has NO limit/offset — gets all results, totalCount via count:true
21594
+ const fullQuery = { ...(this.queryParams || {}), count: true };
21009
21595
  const processResults = async (result) => {
21010
- const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
21596
+ const { results: allResults, totalCount } = await this.processSparqlResult(result, fullQuery, true);
21597
+ const start = pageSize * (pageNumber - 1);
21598
+ const results = allResults.slice(start, start + pageSize);
21011
21599
  callback({ results, totalCount, pageSize, pageNumber });
21012
21600
  };
21013
21601
  this.currentSubscription.onResult(processResults);
21014
- const { results, totalCount } = await this.processSparqlResult(this.currentSubscription.result, paginationQuery);
21602
+ const { results: allResults, totalCount } = await this.processSparqlResult(this.currentSubscription.result, fullQuery, true);
21603
+ const start = pageSize * (pageNumber - 1);
21604
+ const results = allResults.slice(start, start + pageSize);
21015
21605
  const initialPage = { results, totalCount, pageSize, pageNumber };
21016
21606
  // Initial page returned via Promise — callback for subsequent updates only
21017
21607
  return initialPage;
@@ -21435,41 +22025,44 @@ async function evaluateCustomGettersForInstance(instance, perspective, metadata,
21435
22025
  // evaluate getters for fields that are requested (or included).
21436
22026
  const projectionActive = options?.requestedProperties && options.requestedProperties.length > 0;
21437
22027
  const projectionSet = projectionActive ? new Set(options.requestedProperties) : null;
21438
- // Evaluate property getters
21439
- for (const [propName, propMeta] of Object.entries(metadata.properties)) {
21440
- if (projectionSet && !projectionSet.has(propName))
21441
- continue;
21442
- if (propMeta.getter) {
21443
- try {
21444
- const rawGetter = propMeta.getter;
21445
- const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
21446
- // If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
21447
- const trimmed = getterWithBase.trim().toUpperCase();
21448
- if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
21449
- const result = await perspective.querySparql(getterWithBase);
21450
- if (trimmed.startsWith('ASK')) {
21451
- instance[propName] = result === true || result === 'true';
21452
- }
21453
- else if (result && result.length > 0) {
21454
- // Get first binding's first value
21455
- const firstRow = result[0];
21456
- const firstKey = Object.keys(firstRow)[0];
21457
- const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
21458
- if (val !== undefined && val !== null && val !== 'None' && val !== '') {
21459
- instance[propName] = val;
22028
+ // Evaluate property getters (skip when caller only wants relation type-filtering)
22029
+ if (!options?.skipPropertyGetters) {
22030
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
22031
+ if (projectionSet && !projectionSet.has(propName))
22032
+ continue;
22033
+ if (propMeta.getter) {
22034
+ try {
22035
+ const rawGetter = propMeta.getter;
22036
+ const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
22037
+ // If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
22038
+ const trimmed = getterWithBase.trim().toUpperCase();
22039
+ if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
22040
+ const result = await perspective.querySparql(getterWithBase);
22041
+ if (trimmed.startsWith('ASK')) {
22042
+ instance[propName] = result === true || result === 'true';
21460
22043
  }
22044
+ else if (result && result.length > 0) {
22045
+ // Get first binding's first value
22046
+ const firstRow = result[0];
22047
+ const firstKey = Object.keys(firstRow)[0];
22048
+ const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
22049
+ if (val !== undefined && val !== null && val !== 'None' && val !== '') {
22050
+ instance[propName] = val;
22051
+ }
22052
+ }
22053
+ }
22054
+ else {
22055
+ // Legacy SurrealDB-style getter — safety guard for getters that don't match
22056
+ // SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
22057
+ console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
21461
22058
  }
21462
22059
  }
21463
- else {
21464
- // Legacy SurrealDB-style getter — no longer supported
21465
- console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
22060
+ catch (error) {
22061
+ console.warn(`Failed to evaluate getter for ${propName}:`, error);
21466
22062
  }
21467
22063
  }
21468
- catch (error) {
21469
- console.warn(`Failed to evaluate getter for ${propName}:`, error);
21470
- }
21471
22064
  }
21472
- }
22065
+ } // end skipPropertyGetters guard
21473
22066
  // Evaluate relation getters (explicit or auto-generated from target)
21474
22067
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
21475
22068
  // Skip relations excluded by property projection (unless in include map)
@@ -21549,7 +22142,8 @@ async function evaluateCustomGettersForInstance(instance, perspective, metadata,
21549
22142
  }
21550
22143
  }
21551
22144
  else {
21552
- // Legacy SurrealDB-style getter — no longer supported
22145
+ // Legacy SurrealDB-style getter — safety guard for relation getters that don't
22146
+ // match SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
21553
22147
  console.warn(`Unsupported legacy getter syntax for relation ${relName} — use native SPARQL (SELECT/ASK): ${getter.slice(0, 100)}`);
21554
22148
  }
21555
22149
  }
@@ -21605,7 +22199,166 @@ async function hydrateRelations(modelClass, instances, perspective, includeMap)
21605
22199
  if (!includeMap || Object.keys(includeMap).length === 0)
21606
22200
  return;
21607
22201
  const relMeta = getRelationsMetadata(modelClass);
22202
+ // ── Projections ($-prefixed keys) ────────────────────────────────────────
22203
+ // Collect all projection entries up-front so we can batch the count queries
22204
+ // together per-projection before processing. Each projection key starts
22205
+ // with '$' and has a descriptor with a `from` field.
22206
+ const projectionEntries = [];
22207
+ for (const [key, val] of Object.entries(includeMap)) {
22208
+ if (key.startsWith('$') && val !== null && typeof val === 'object' && 'from' in val) {
22209
+ projectionEntries.push([key, val]);
22210
+ }
22211
+ }
22212
+ for (const [projKey, proj] of projectionEntries) {
22213
+ const sourceMeta = relMeta[proj.from];
22214
+ if (!sourceMeta) {
22215
+ console.warn(`include projection "${projKey}": relation "${proj.from}" not found in metadata, skipping`);
22216
+ for (const inst of instances)
22217
+ inst[projKey] = proj.count ? 0 : [];
22218
+ continue;
22219
+ }
22220
+ const TargetClass = sourceMeta.target();
22221
+ const allParentIds = instances.map(inst => inst.id).filter(Boolean);
22222
+ if (proj.count) {
22223
+ // ── Path A: grouped SPARQL COUNT ─────────────────────────────────────
22224
+ // One round-trip, zero instance hydration. Returns one row per parent.
22225
+ const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
22226
+ const targetRelMeta = TargetClass.getAllRelationsMetadata?.() ?? {};
22227
+ let countMap = new Map();
22228
+ if (targetMetadata && allParentIds.length > 0) {
22229
+ try {
22230
+ const sparql = buildSPARQLGroupedCountQuery(targetMetadata, targetRelMeta, sourceMeta.predicate, allParentIds, proj.where);
22231
+ const raw = await perspective.querySparql(sparql);
22232
+ const rows = Array.isArray(raw) ? raw
22233
+ : raw?.results?.bindings ?? raw?.bindings ?? [];
22234
+ countMap = parseSparqlGroupedCount(rows);
22235
+ }
22236
+ catch (e) {
22237
+ console.warn(`include projection "${projKey}" count query failed, falling back to 0:`, e);
22238
+ }
22239
+ }
22240
+ for (const inst of instances) {
22241
+ inst[projKey] = countMap.get(inst.id) ?? 0;
22242
+ }
22243
+ }
22244
+ else {
22245
+ // ── Path B: findAll + Map distribution ───────────────────────────────
22246
+ // For reverse relations we don't have the child IDs on the instance,
22247
+ // so fall back to a parent-scoped findAll per instance (uncommon path).
22248
+ const isReverse = sourceMeta.kind === 'belongsToOne' || sourceMeta.kind === 'belongsToMany';
22249
+ if (isReverse) {
22250
+ // Reverse: the link goes child→parent, reuse the batched SPARQL pattern
22251
+ // from the existing belongsTo path to collect source IDs per parent.
22252
+ if (allParentIds.length > 0) {
22253
+ const sparqlQuery = `SELECT ?source ?target WHERE {
22254
+ GRAPH ?g { ?source <${sourceMeta.predicate}> ?target }
22255
+ FILTER(?target IN (${allParentIds.map(id => `<${id}>`).join(', ')}))
22256
+ }`;
22257
+ const sourcesByTarget = new Map();
22258
+ try {
22259
+ const raw = await perspective.querySparql(sparqlQuery);
22260
+ const bindings = Array.isArray(raw) ? raw : raw?.results?.bindings ?? raw?.bindings ?? [];
22261
+ for (const row of bindings) {
22262
+ const source = row.source?.value ?? row.source;
22263
+ const target = row.target?.value ?? row.target;
22264
+ if (!source || !target)
22265
+ continue;
22266
+ if (!sourcesByTarget.has(target))
22267
+ sourcesByTarget.set(target, []);
22268
+ sourcesByTarget.get(target).push(source);
22269
+ }
22270
+ }
22271
+ catch (e) {
22272
+ console.warn(`include projection "${projKey}" reverse SPARQL failed:`, e);
22273
+ }
22274
+ const allSourceIds = new Set();
22275
+ for (const ids of sourcesByTarget.values())
22276
+ for (const id of ids)
22277
+ allSourceIds.add(id);
22278
+ const hydratedMap = new Map();
22279
+ if (allSourceIds.size > 0) {
22280
+ const results = await TargetClass.findAll(perspective, {
22281
+ where: { id: Array.from(allSourceIds), ...(proj.where ?? {}) },
22282
+ });
22283
+ for (const r of results)
22284
+ hydratedMap.set(r.id, r);
22285
+ }
22286
+ for (const inst of instances) {
22287
+ const sourceIds = sourcesByTarget.get(inst.id) ?? [];
22288
+ let resolved = sourceIds.map(id => hydratedMap.get(id)).filter((v) => v != null);
22289
+ if (proj.limit != null) {
22290
+ if (proj.limit === 1) {
22291
+ inst[projKey] = resolved[0] ?? null;
22292
+ }
22293
+ else {
22294
+ inst[projKey] = resolved.slice(0, proj.limit);
22295
+ }
22296
+ }
22297
+ else {
22298
+ inst[projKey] = resolved;
22299
+ }
22300
+ }
22301
+ }
22302
+ else {
22303
+ for (const inst of instances)
22304
+ inst[projKey] = proj.limit === 1 ? null : [];
22305
+ }
22306
+ }
22307
+ else {
22308
+ // Forward: instance[from] holds raw child URIs — collect across all parents
22309
+ const uriSet = new Set();
22310
+ const rawCache = new Map();
22311
+ for (const inst of instances) {
22312
+ const raw = inst[proj.from];
22313
+ const uris = [];
22314
+ if (Array.isArray(raw)) {
22315
+ for (const v of raw) {
22316
+ const id = typeof v === 'string' ? v : v?.id;
22317
+ if (id) {
22318
+ uriSet.add(id);
22319
+ uris.push(id);
22320
+ }
22321
+ }
22322
+ }
22323
+ else if (typeof raw === 'string') {
22324
+ uriSet.add(raw);
22325
+ uris.push(raw);
22326
+ }
22327
+ else if (raw?.id) {
22328
+ uriSet.add(raw.id);
22329
+ uris.push(raw.id);
22330
+ }
22331
+ rawCache.set(inst, uris);
22332
+ }
22333
+ const hydratedMap = new Map();
22334
+ if (uriSet.size > 0) {
22335
+ const results = await TargetClass.findAll(perspective, {
22336
+ where: { id: Array.from(uriSet), ...(proj.where ?? {}) },
22337
+ });
22338
+ for (const r of results)
22339
+ hydratedMap.set(r.id, r);
22340
+ }
22341
+ for (const inst of instances) {
22342
+ const uris = rawCache.get(inst) ?? [];
22343
+ const resolved = uris.map(id => hydratedMap.get(id)).filter((v) => v != null);
22344
+ if (proj.limit === 1) {
22345
+ inst[projKey] = resolved[0] ?? null;
22346
+ }
22347
+ else if (proj.limit != null) {
22348
+ inst[projKey] = resolved.slice(0, proj.limit);
22349
+ }
22350
+ else {
22351
+ inst[projKey] = resolved;
22352
+ }
22353
+ }
22354
+ }
22355
+ }
22356
+ }
22357
+ // ── Standard relations (non-projected) ───────────────────────────────────
21608
22358
  for (const [relName, includeValue] of Object.entries(includeMap)) {
22359
+ // Skip projection keys — already handled above
22360
+ if (relName.startsWith('$') && typeof includeValue === 'object' && includeValue !== null && 'from' in includeValue)
22361
+ continue;
21609
22362
  const meta = relMeta[relName];
21610
22363
  if (!meta) {
21611
22364
  console.warn(`include: relation "${relName}" not found in metadata, skipping`);
@@ -21620,57 +22373,102 @@ async function hydrateRelations(modelClass, instances, perspective, includeMap)
21620
22373
  // ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
21621
22374
  // The link goes target→instance, so we query backwards:
21622
22375
  // predicate = meta.predicate, target = inst.id → source is the related id
22376
+ //
22377
+ // PERF: Batch all reverse lookups into a single SPARQL query instead of
22378
+ // N sequential perspective.get() calls (N+1 → 1 optimisation).
21623
22379
  if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
21624
- // Per-instance reverse lookup (can't batch easily across instances)
22380
+ const allIds = instances.map(inst => inst.id).filter(Boolean);
22381
+ // Batch query: find all (source, target) pairs for this predicate
22382
+ // where target is one of our instance IDs
22383
+ const sourcesByTarget = new Map();
22384
+ if (allIds.length > 0) {
22385
+ const sparqlQuery = `SELECT ?source ?target WHERE {
22386
+ GRAPH ?g { ?source <${meta.predicate}> ?target }
22387
+ FILTER(?target IN (${allIds.map(id => `<${id}>`).join(', ')}))
22388
+ }`;
22389
+ try {
22390
+ const sparqlResult = await perspective.querySparql(sparqlQuery);
22391
+ // Parse SPARQL results — querySparql returns a flat array of row objects
22392
+ // e.g. [{ source: "uri1", target: "uri2" }, ...]
22393
+ const bindings = Array.isArray(sparqlResult) ? sparqlResult
22394
+ : sparqlResult?.results?.bindings ?? sparqlResult?.bindings ?? [];
22395
+ for (const row of bindings) {
22396
+ const source = row.source?.value ?? row.source;
22397
+ const target = row.target?.value ?? row.target;
22398
+ if (!source || !target)
22399
+ continue;
22400
+ if (!sourcesByTarget.has(target))
22401
+ sourcesByTarget.set(target, []);
22402
+ sourcesByTarget.get(target).push(source);
22403
+ }
22404
+ }
22405
+ catch (e) {
22406
+ // Fallback: sequential queries if SPARQL fails
22407
+ console.warn('Batched reverse relation SPARQL failed, falling back to sequential:', e);
22408
+ for (const inst of instances) {
22409
+ const reverseLinks = await perspective.get(new LinkQuery({ predicate: meta.predicate, target: inst.id }));
22410
+ const sourceIds = reverseLinks
22411
+ .filter(l => l.data.target === inst.id)
22412
+ .map(l => l.data.source);
22413
+ if (sourceIds.length > 0) {
22414
+ sourcesByTarget.set(inst.id, sourceIds);
22415
+ }
22416
+ }
22417
+ }
22418
+ }
22419
+ // Collect ALL source IDs across all instances for batch hydration
22420
+ const allSourceIds = new Set();
22421
+ for (const ids of sourcesByTarget.values()) {
22422
+ for (const id of ids)
22423
+ allSourceIds.add(id);
22424
+ }
22425
+ // Batch-hydrate all related instances at once (1 findAll instead of N)
22426
+ const hydratedMap = new Map();
22427
+ if (allSourceIds.size > 0) {
22428
+ const fetchQuery = {
22429
+ where: {
22430
+ id: Array.from(allSourceIds),
22431
+ ...(subQuery?.where ?? {}),
22432
+ },
22433
+ ...(subQuery?.order && { order: subQuery.order }),
22434
+ ...(subQuery?.properties && { properties: subQuery.properties }),
22435
+ };
22436
+ try {
22437
+ const allResults = await TargetClass.findAll(perspective, fetchQuery);
22438
+ for (const r of allResults)
22439
+ hydratedMap.set(r.id, r);
22440
+ }
22441
+ catch {
22442
+ // Fallback: hydrate individually
22443
+ await Promise.all(Array.from(allSourceIds).map(async (sid) => {
22444
+ try {
22445
+ const related = new TargetClass(perspective, sid);
22446
+ await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
22447
+ hydratedMap.set(sid, related);
22448
+ }
22449
+ catch { /* skip */ }
22450
+ }));
22451
+ }
22452
+ }
22453
+ // Assign hydrated instances to each parent
21625
22454
  for (const inst of instances) {
21626
- const reverseLinks = await perspective.get(new LinkQuery({ predicate: meta.predicate, target: inst.id }));
21627
- // Defensive filter: perspective.get may return extra results; ensure
21628
- // we only use links that genuinely point to this instance.
21629
- const sourceIds = reverseLinks
21630
- .filter(l => l.data.target === inst.id)
21631
- .map(l => l.data.source);
22455
+ const instId = inst.id;
22456
+ const sourceIds = sourcesByTarget.get(instId) ?? [];
21632
22457
  if (meta.kind === 'belongsToOne') {
21633
22458
  if (sourceIds.length === 0) {
21634
22459
  inst[relName] = null;
21635
22460
  continue;
21636
22461
  }
21637
22462
  const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
21638
- try {
21639
- const related = new TargetClass(perspective, sourceId);
21640
- await related.get();
21641
- inst[relName] = related;
21642
- }
21643
- catch {
21644
- inst[relName] = null;
21645
- }
22463
+ inst[relName] = hydratedMap.get(sourceId) ?? null;
21646
22464
  }
21647
22465
  else {
21648
22466
  // belongsToMany — return array of hydrated instances
21649
- let hydrated = [];
21650
- // If there's a where/order sub-query, delegate to findAll for filtering
21651
- if (subQuery && (subQuery.where || subQuery.order || subQuery.properties)) {
21652
- const whereWithIds = {
21653
- id: sourceIds,
21654
- ...(subQuery.where ?? {}),
21655
- };
21656
- hydrated = await TargetClass.findAll(perspective, {
21657
- where: whereWithIds,
21658
- ...(subQuery.order && { order: subQuery.order }),
21659
- ...(subQuery.properties && { properties: subQuery.properties }),
21660
- });
21661
- }
21662
- else {
21663
- await Promise.all(sourceIds.map(async (sid) => {
21664
- try {
21665
- const related = new TargetClass(perspective, sid);
21666
- await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
21667
- hydrated.push(related);
21668
- }
21669
- catch { /* skip */ }
21670
- }));
21671
- }
21672
- // Apply order (client-side, if not already handled by findAll above)
21673
- if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
22467
+ let hydrated = sourceIds
22468
+ .map(sid => hydratedMap.get(sid))
22469
+ .filter((v) => v != null);
22470
+ // Apply order (client-side)
22471
+ if (subQuery?.order) {
21674
22472
  const orderEntries = Object.entries(subQuery.order);
21675
22473
  hydrated = hydrated.sort((a, b) => {
21676
22474
  for (const [field, dir] of orderEntries) {
@@ -22491,7 +23289,7 @@ class Ad4mModel {
22491
23289
  *
22492
23290
  * @internal
22493
23291
  */
22494
- static async instancesFromQueryResult(perspective, query, result) {
23292
+ static async instancesFromQueryResult(perspective, query, result, computeTotalCount = false) {
22495
23293
  if (!result || result.length === 0)
22496
23294
  return { results: [], totalCount: 0 };
22497
23295
  const metadata = this.getModelMetadata();
@@ -22556,18 +23354,38 @@ class Ad4mModel {
22556
23354
  }
22557
23355
  }));
22558
23356
  }
22559
- // Evaluate custom getters for all instances (single pass)
22560
- const getterOpts = requestedProperties.length > 0 || query.include
22561
- ? { requestedProperties, include: query.include }
22562
- : undefined;
22563
- for (const instance of instances) {
22564
- await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
23357
+ // Evaluate custom getters for all instances.
23358
+ // Relation getters (type-conformance filtering) always run — they ensure
23359
+ // correctness of @HasMany/@HasOne targets. Property getters only run when
23360
+ // deepQuery is true or when where conditions reference getter-backed properties.
23361
+ const whereGetterProperties = query.where
23362
+ ? Object.keys(query.where).filter((propName) => metadata.properties[propName]?.getter)
23363
+ : [];
23364
+ const shouldEvaluatePropertyGetters = query.deepQuery === true || whereGetterProperties.length > 0;
23365
+ {
23366
+ const skipPropertyGetters = !shouldEvaluatePropertyGetters;
23367
+ const getterRequestedProperties = shouldEvaluatePropertyGetters
23368
+ ? (requestedProperties.length > 0
23369
+ ? Array.from(new Set([...requestedProperties, ...whereGetterProperties]))
23370
+ : query.deepQuery === true
23371
+ ? [] // deepQuery: evaluate all getters
23372
+ : whereGetterProperties) // only evaluate where-referenced getters
23373
+ : [];
23374
+ const getterOpts = {
23375
+ ...(getterRequestedProperties.length > 0 && { requestedProperties: getterRequestedProperties }),
23376
+ ...(query.include && { include: query.include }),
23377
+ skipPropertyGetters,
23378
+ };
23379
+ for (const instance of instances) {
23380
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
23381
+ }
22565
23382
  }
22566
23383
  // Filter by where conditions that couldn't be filtered in SPARQL
22567
23384
  // This includes:
22568
23385
  // - author/timestamp (computed from grouped links)
22569
23386
  // - Properties with comparison operators (gt, gte, lt, lte, between, contains)
22570
- // because fn::parse_literal() comparisons in SPARQL subqueries don't work reliably
23387
+ // because <ad4m://fn/parse_literal>() returns strings, making numeric/date
23388
+ // comparisons unreliable. Equality, IN, and NOT are pushed to SPARQL.
22571
23389
  // - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
22572
23390
  // which require reverse-link resolution before filtering
22573
23391
  let filteredInstances = instances;
@@ -22593,9 +23411,9 @@ class Ad4mModel {
22593
23411
  }
22594
23412
  continue;
22595
23413
  }
22596
- // Filter ALL property conditions in JS (equality, NOT, IN, comparison operators).
22597
- // SPARQL-level filtering with parse_literal is unreliable across environments,
22598
- // so we do all property filtering here after hydration resolves values.
23414
+ // Filter ALL property conditions in JS (safety net).
23415
+ // Equality/IN/NOT are also filtered in SPARQL via <ad4m://fn/parse_literal>()
23416
+ // but JS re-validates after hydration resolves values.
22599
23417
  if (!matchesCondition(instance[propertyName], condition)) {
22600
23418
  return false;
22601
23419
  }
@@ -22607,7 +23425,7 @@ class Ad4mModel {
22607
23425
  // If limit/offset is used but no explicit order, default to ordering by timestamp (ASC)
22608
23426
  // This ensures consistent pagination behavior
22609
23427
  const effectiveOrder = query.order ||
22610
- (query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' } : null);
23428
+ (query.limit !== undefined || query.offset !== undefined ? { createdAt: 'ASC' } : null);
22611
23429
  if (effectiveOrder) {
22612
23430
  const orderEntries = Object.entries(effectiveOrder);
22613
23431
  filteredInstances.sort((a, b) => {
@@ -22640,11 +23458,37 @@ class Ad4mModel {
22640
23458
  return 0;
22641
23459
  });
22642
23460
  }
22643
- // Calculate totalCount BEFORE applying limit/offset
22644
- const totalCount = filteredInstances.length;
22645
- // Apply offset and limit in JavaScript
23461
+ // Determine if SPARQL already applied LIMIT/OFFSET (i.e., the pagination
23462
+ // subquery was used). When it was, skip JS-level slicing — instances are
23463
+ // already the correct page.
23464
+ const allRelsMeta2 = getRelationsMetadata(this);
23465
+ const sparqlPaginated = !hasJsOnlyWhereFilters(metadata, allRelsMeta2, query.where)
23466
+ && (query.limit !== undefined || query.offset !== undefined)
23467
+ && query.order !== undefined && Object.keys(query.order).length > 0;
23468
+ // Calculate totalCount BEFORE applying limit/offset.
23469
+ // When SPARQL already paginated, filteredInstances.length is the page size,
23470
+ // not the total — use a separate COUNT query for the real total.
23471
+ // Only run the COUNT query when the caller actually needs it (computeTotalCount=true).
23472
+ let totalCount;
23473
+ if (sparqlPaginated && computeTotalCount) {
23474
+ try {
23475
+ const countSparql = buildSPARQLCountQuery(metadata, allRelsMeta2, query, this);
23476
+ const countResult = await perspective.querySparql(countSparql);
23477
+ totalCount = parseSparqlCount(countResult) ?? filteredInstances.length;
23478
+ }
23479
+ catch {
23480
+ // Fallback: if count query fails, use what we have
23481
+ totalCount = filteredInstances.length;
23482
+ }
23483
+ }
23484
+ else {
23485
+ totalCount = filteredInstances.length;
23486
+ }
23487
+ // Apply offset and limit in JavaScript only when SPARQL didn't already paginate.
23488
+ // Subscription queries use unpaginated SPARQL, so JS must apply pagination.
23489
+ // Direct queries use SPARQL-level pagination, so JS slicing would double-apply.
22646
23490
  let paginatedInstances = filteredInstances;
22647
- if (query.offset !== undefined || query.limit !== undefined) {
23491
+ if (!sparqlPaginated && (query.offset !== undefined || query.limit !== undefined)) {
22648
23492
  const start = query.offset || 0;
22649
23493
  const end = query.limit ? start + query.limit : undefined;
22650
23494
  paginatedInstances = filteredInstances.slice(start, end);
@@ -22796,7 +23640,7 @@ class Ad4mModel {
22796
23640
  const sparqlQuery = await this.queryToSPARQL(perspective, query);
22797
23641
  const rawResult = await perspective.querySparql(sparqlQuery);
22798
23642
  const grouped = groupSPARQLResults(rawResult);
22799
- return await this.instancesFromQueryResult(perspective, query, grouped);
23643
+ return await this.instancesFromQueryResult(perspective, query, grouped, true);
22800
23644
  }
22801
23645
  else {
22802
23646
  const prologQuery = await this.queryToProlog(perspective, query);
@@ -22834,7 +23678,7 @@ class Ad4mModel {
22834
23678
  const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
22835
23679
  const rawResult = await perspective.querySparql(sparqlQuery);
22836
23680
  const grouped = groupSPARQLResults(rawResult);
22837
- const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped);
23681
+ const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped, true);
22838
23682
  return { results, totalCount, pageSize, pageNumber };
22839
23683
  }
22840
23684
  else {
@@ -22872,12 +23716,9 @@ class Ad4mModel {
22872
23716
  * @private
22873
23717
  */
22874
23718
  static async countQueryToSPARQL(perspective, query) {
22875
- // Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
22876
- // We'll count the number of rows returned (one row per source)
22877
- const countQuery = { ...query };
22878
- delete countQuery.limit;
22879
- delete countQuery.offset;
22880
- return await this.queryToSPARQL(perspective, countQuery);
23719
+ const metadata = this.getModelMetadata();
23720
+ const allRelMeta = getRelationsMetadata(this);
23721
+ return buildSPARQLCountQuery(metadata, allRelMeta, query, this);
22881
23722
  }
22882
23723
  /**
22883
23724
  * Gets a count of all matching instances.
@@ -22903,11 +23744,22 @@ class Ad4mModel {
22903
23744
  ? (engine ? 'sparql' : 'prolog')
22904
23745
  : engine;
22905
23746
  if (resolvedEngine === 'sparql') {
22906
- const sparqlQuery = await this.queryToSPARQL(perspective, query);
22907
- const rawResult = await perspective.querySparql(sparqlQuery);
22908
- const grouped = groupSPARQLResults(rawResult);
22909
- const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped);
22910
- return totalCount;
23747
+ // When query has JS-only where filters (gt, between, author, timestamp, etc.),
23748
+ // we must fall back to full hydration + JS filtering to get accurate count.
23749
+ const metadata = this.getModelMetadata();
23750
+ const allRelMeta = getRelationsMetadata(this);
23751
+ if (hasJsOnlyWhereFilters(metadata, allRelMeta, query.where)) {
23752
+ // Fall back to full query + JS filter path for accurate count
23753
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
23754
+ const rawResult = await perspective.querySparql(sparqlQuery);
23755
+ const grouped = groupSPARQLResults(rawResult);
23756
+ const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped, true);
23757
+ return totalCount;
23758
+ }
23759
+ // No JS-only filters — use efficient COUNT query
23760
+ const countSparql = await this.countQueryToSPARQL(perspective, query);
23761
+ const countResult = await perspective.querySparql(countSparql);
23762
+ return parseSparqlCount(countResult) ?? 0;
22911
23763
  }
22912
23764
  else {
22913
23765
  const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
@@ -23195,6 +24047,61 @@ class Ad4mModel {
23195
24047
  }
23196
24048
  }
23197
24049
  }
24050
+ /**
24051
+ * Evaluate SPARQL getters for a batch of instances on demand.
24052
+ *
24053
+ * Use after a shallow collection query (the default) to resolve
24054
+ * getter-backed properties for visible items only. This avoids the
24055
+ * O(N × getters) cost of evaluating every getter on every instance in
24056
+ * a large collection query.
24057
+ *
24058
+ * @param instances - Array of model instances to evaluate getters on
24059
+ * @param perspective - The perspective to query against
24060
+ * @param propertyNames - Optional list of getter-backed property names to evaluate.
24061
+ * If omitted, all getters are evaluated.
24062
+ *
24063
+ * @example
24064
+ * ```typescript
24065
+ * const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
24066
+ * // messages[i].replyingTo is undefined (getter skipped by default)
24067
+ *
24068
+ * // Evaluate getters for the visible subset
24069
+ * await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
24070
+ * // messages[0..9].replyingTo is now populated
24071
+ * ```
24072
+ */
24073
+ static async evaluateGetters(instances, perspective, propertyNames) {
24074
+ if (instances.length === 0)
24075
+ return;
24076
+ const metadata = this.getModelMetadata();
24077
+ const opts = propertyNames && propertyNames.length > 0
24078
+ ? { requestedProperties: propertyNames }
24079
+ : undefined;
24080
+ // Determine which property names will actually be evaluated
24081
+ const evaluatedPropertyNames = [];
24082
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
24083
+ if (propMeta.getter) {
24084
+ if (!propertyNames || propertyNames.length === 0 || propertyNames.includes(propName)) {
24085
+ evaluatedPropertyNames.push(propName);
24086
+ }
24087
+ }
24088
+ }
24089
+ for (const instance of instances) {
24090
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, opts);
24091
+ // Sync snapshot so isDirty() doesn't flag getter-only changes.
24092
+ // evaluateGetters() mutates instances in place, but their snapshots
24093
+ // were already taken during hydration. Without this sync, the computed
24094
+ // getter values would make isDirty() return true and save() would try
24095
+ // to write read-only computed properties.
24096
+ const modelInstance = instance;
24097
+ if (modelInstance._snapshot) {
24098
+ for (const propName of evaluatedPropertyNames) {
24099
+ const val = instance[propName];
24100
+ modelInstance._snapshot[propName] = normalizeValue(Array.isArray(val) ? [...val] : val);
24101
+ }
24102
+ }
24103
+ }
24104
+ }
23198
24105
  /**
23199
24106
  * Gets the model instance with all properties and relations populated.
23200
24107
  *
@@ -25430,4 +26337,4 @@ RuntimeResolver = __decorate([
25430
26337
  Resolver()
25431
26338
  ], RuntimeResolver);
25432
26339
 
25433
- export { AIClient, AIModelLoadingStatus, AIPromptExamples, AIPromptExamplesInput, AITask, AITaskInput, Ad4mClient, Ad4mModel, Agent, AgentClient, AgentExpression, AgentSignature, AgentStatus, Apps, AuthInfo, AuthInfoInput, BelongsToMany, BelongsToOne, Capability, CapabilityInput, ComputeLogEntry, Dna, EntanglementProof, EntanglementProofInput, ExceptionInfo, ExceptionType, Expression, ExpressionGeneric, ExpressionGenericInput, ExpressionProof, ExpressionProofInput, ExpressionRef, ExpressionRendered, Flag, HasMany, HasOne, HostingUserInfo, Icon, ImportResult, ImportStats, InteractionCall, InteractionMeta, InteractionParameter, LanguageExpression, LanguageHandle, LanguageLanguageInput, LanguageMeta, LanguageMetaInput, LanguageMetaInternal, LanguageRef, Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkExpressionUpdated, LinkInput, LinkMutations, LinkQuery, Literal, Model, ModelQueryBuilder, Neighbourhood, NeighbourhoodExpression, NeighbourhoodProxy, Notification, NotificationInput, OnlineAgent, Optional, PaymentRequestResult, Perspective, PerspectiveDiff, PerspectiveDiffExpression, PerspectiveExpression, PerspectiveHandle, PerspectiveInput, PerspectiveProxy, PerspectiveState, PerspectiveUnsignedInput, Property, QuerySubscriptionProxy, ReadOnly, Resource, ResourceInput, RuntimeInfo, SHACLFlow, SHACLShape, SMART_LITERAL_CONTENT_PREDICATE, SentMessage, SmartLiteral, Subject, TriggeredNotification, UserCreationResult, UserStatistics, VerificationRequestResult, WakerSubscriptionManager, assignValuesToInstance, buildAuthorAndTimestampQuery, buildConformanceFilter, buildConformanceGetter, buildCountQuery, buildLimitQuery, buildModelFromJSONSchema, buildOffsetQuery, buildOrderQuery, buildParentQuery, buildPropertiesQuery, buildSDNA, buildSHACL, buildSPARQLGetDataQuery, buildSPARQLQuery, buildWhereCondition, buildWhereQuery, capSentence, clearQueryCache, clearSubscriptionPool, compileWhereClause, determineNamespace, determinePredicate, escapeQueryString, evaluateCustomGettersForInstance, exprRef2String, formatList, formatQueryValue, formatSPARQLValue, generatePrologFacts, getCachedResult, getDefaultValueForType, getMemoizedSHACL, getPropertiesMetadata, getPropertyOption, getRelationsMetadata, groupSPARQLResults, hydrateFromLinks, hydratePropertyValue, hydrateRelations, invalidatePerspectiveCache, isArrayType, isExpression, isLink, isNumericType, isObjectType, isSchemaType, linkEqual, matchesCondition, normalizeNamespaceString, normalizeSchemaType, normalizeValue, parseExprUrl, pooledSubscribe, queryCacheSize, resolveParentPredicate, setCachedResult, setPropertyRegistryEntry, setRelationRegistryEntry, subscriptionPoolSize, typeDefsString };
26340
+ export { AIClient, AIModelLoadingStatus, AIPromptExamples, AIPromptExamplesInput, AITask, AITaskInput, Ad4mClient, Ad4mModel, Agent, AgentClient, AgentExpression, AgentSignature, AgentStatus, Apps, AuthInfo, AuthInfoInput, BelongsToMany, BelongsToOne, Capability, CapabilityInput, ComputeLogEntry, EntanglementProof, EntanglementProofInput, ExceptionInfo, ExceptionType, Expression, ExpressionGeneric, ExpressionGenericInput, ExpressionProof, ExpressionProofInput, ExpressionRef, ExpressionRendered, Flag, HasMany, HasOne, HostingUserInfo, Icon, ImportResult, ImportStats, InteractionCall, InteractionMeta, InteractionParameter, LanguageExpression, LanguageHandle, LanguageLanguageInput, LanguageMeta, LanguageMetaInput, LanguageMetaInternal, LanguageRef, Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkExpressionUpdated, LinkInput, LinkMutations, LinkQuery, Literal, Model, ModelQueryBuilder, Neighbourhood, NeighbourhoodExpression, NeighbourhoodProxy, Notification, NotificationInput, OnlineAgent, Optional, PaymentRequestResult, Perspective, PerspectiveDiff, PerspectiveDiffExpression, PerspectiveExpression, PerspectiveHandle, PerspectiveInput, PerspectiveProxy, PerspectiveState, PerspectiveUnsignedInput, Property, QuerySubscriptionProxy, ReadOnly, Resource, ResourceInput, RuntimeInfo, SHACLFlow, SHACLShape, SMART_LITERAL_CONTENT_PREDICATE, SentMessage, SmartLiteral, Subject, TriggeredNotification, UserCreationResult, UserStatistics, VerificationRequestResult, WakerSubscriptionManager, assignValuesToInstance, buildAuthorAndTimestampQuery, buildConformanceFilter, buildConformanceGetter, buildCountQuery, buildLimitQuery, buildModelFromJSONSchema, buildOffsetQuery, buildOrderQuery, buildPaginationSubquery, buildParentQuery, buildPropertiesQuery, buildSDNA, buildSHACL, buildSPARQLCountQuery, buildSPARQLGetDataQuery, buildSPARQLGroupedCountQuery, buildSPARQLOrderLimitOffset, buildSPARQLQuery, buildWhereCondition, buildWhereQuery, capSentence, clearQueryCache, clearSubscriptionPool, compileWhereClause, determineNamespace, determinePredicate, escapeQueryString, evaluateCustomGettersForInstance, exprRef2String, formatList, formatQueryValue, formatSPARQLValue, generatePrologFacts, getCachedResult, getDefaultValueForType, getMemoizedSHACL, getPropertiesMetadata, getPropertyOption, getRelationsMetadata, groupSPARQLResults, hasJsOnlyWhereFilters, hydrateFromLinks, hydratePropertyValue, hydrateRelations, invalidatePerspectiveCache, isArrayType, isExpression, isLink, isNumericType, isObjectType, isSchemaType, linkEqual, matchesCondition, normalizeNamespaceString, normalizeSchemaType, normalizeValue, parseExprUrl, parseSparqlCount, parseSparqlGroupedCount, pooledSubscribe, queryCacheSize, resolveParentPredicate, setCachedResult, setPropertyRegistryEntry, setRelationRegistryEntry, subscriptionPoolSize, typeDefsString };