@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.cjs CHANGED
@@ -5497,9 +5497,13 @@ function buildWhereCondition(predicate, condition, opts) {
5497
5497
  if (ops.not !== undefined) {
5498
5498
  if (Array.isArray(ops.not)) {
5499
5499
  const formattedValues = ops.not.map((v) => formatValue(v)).join(', ');
5500
+ // FILTER NOT EXISTS here is scoped to a specific predicate, not a global scan,
5501
+ // so O(N²) behavior is bounded by the number of values for this property.
5500
5502
  parts.push(`FILTER NOT EXISTS { ?target <${escapedPredicate}> ?_nval . FILTER(?_nval IN (${formattedValues})) }`);
5501
5503
  }
5502
5504
  else {
5505
+ // FILTER NOT EXISTS here is scoped to a specific predicate, not a global scan,
5506
+ // so O(N²) behavior is bounded by the number of values for this property.
5503
5507
  parts.push(`FILTER NOT EXISTS { ?target <${escapedPredicate}> ${formatValue(ops.not)} }`);
5504
5508
  }
5505
5509
  }
@@ -7252,6 +7256,21 @@ class PerspectiveProxy {
7252
7256
  __classPrivateFieldGet$9(this, _PerspectiveProxy_client, "f").addPerspectiveLinkUpdatedListener(__classPrivateFieldGet$9(this, _PerspectiveProxy_handle, "f").uuid, __classPrivateFieldGet$9(this, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, "f"));
7253
7257
  __classPrivateFieldGet$9(this, _PerspectiveProxy_client, "f").addPerspectiveSyncStateChangeListener(__classPrivateFieldGet$9(this, _PerspectiveProxy_handle, "f").uuid, __classPrivateFieldGet$9(this, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks, "f"));
7254
7258
  }
7259
+ /** Update the proxy's internal handle and public fields in-place.
7260
+ * Keeps the same object reference so all holders see the update. */
7261
+ updateHandle(handle) {
7262
+ if (handle.uuid !== __classPrivateFieldGet$9(this, _PerspectiveProxy_handle, "f").uuid) {
7263
+ 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}". ` +
7264
+ `This would silently diverge from listeners registered under the original UUID.`);
7265
+ }
7266
+ __classPrivateFieldSet$9(this, _PerspectiveProxy_handle, handle, "f");
7267
+ this.uuid = handle.uuid;
7268
+ this.name = handle.name;
7269
+ this.owners = handle.owners;
7270
+ this.sharedUrl = handle.sharedUrl;
7271
+ this.neighbourhood = handle.neighbourhood;
7272
+ this.state = handle.state;
7273
+ }
7255
7274
  /**
7256
7275
  * Escapes special regex characters in a string to prevent ReDoS attacks
7257
7276
  * and regex injection when building dynamic regular expressions.
@@ -8946,7 +8965,7 @@ var __classPrivateFieldGet$8 = (undefined && undefined.__classPrivateFieldGet) |
8946
8965
  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");
8947
8966
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
8948
8967
  };
8949
- var _PerspectiveClient_apolloClient, _PerspectiveClient_perspectiveAddedCallbacks, _PerspectiveClient_perspectiveUpdatedCallbacks, _PerspectiveClient_perspectiveRemovedCallbacks, _PerspectiveClient_perspectiveSyncStateChangeCallbacks, _PerspectiveClient_expressionClient, _PerspectiveClient_neighbourhoodClient, _PerspectiveClient_aiClient;
8968
+ var _PerspectiveClient_apolloClient, _PerspectiveClient_perspectiveAddedCallbacks, _PerspectiveClient_perspectiveUpdatedCallbacks, _PerspectiveClient_perspectiveRemovedCallbacks, _PerspectiveClient_perspectiveSyncStateChangeCallbacks, _PerspectiveClient_expressionClient, _PerspectiveClient_neighbourhoodClient, _PerspectiveClient_aiClient, _PerspectiveClient_proxyCache;
8950
8969
  const LINK_EXPRESSION_FIELDS = `
8951
8970
  author
8952
8971
  timestamp
@@ -8986,6 +9005,7 @@ class PerspectiveClient {
8986
9005
  _PerspectiveClient_expressionClient.set(this, void 0);
8987
9006
  _PerspectiveClient_neighbourhoodClient.set(this, void 0);
8988
9007
  _PerspectiveClient_aiClient.set(this, void 0);
9008
+ _PerspectiveClient_proxyCache.set(this, new Map());
8989
9009
  __classPrivateFieldSet$8(this, _PerspectiveClient_apolloClient, client, "f");
8990
9010
  __classPrivateFieldSet$8(this, _PerspectiveClient_perspectiveAddedCallbacks, [], "f");
8991
9011
  __classPrivateFieldSet$8(this, _PerspectiveClient_perspectiveUpdatedCallbacks, [], "f");
@@ -8997,6 +9017,17 @@ class PerspectiveClient {
8997
9017
  this.subscribePerspectiveRemoved();
8998
9018
  }
8999
9019
  }
9020
+ /** Get or create a proxy for a UUID. If the proxy exists in cache, update its handle and return it. */
9021
+ getOrCreateProxy(handle) {
9022
+ const existing = __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").get(handle.uuid);
9023
+ if (existing) {
9024
+ existing.updateHandle(handle);
9025
+ return existing;
9026
+ }
9027
+ const proxy = new PerspectiveProxy(handle, this);
9028
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").set(handle.uuid, proxy);
9029
+ return proxy;
9030
+ }
9000
9031
  setExpressionClient(client) {
9001
9032
  __classPrivateFieldSet$8(this, _PerspectiveClient_expressionClient, client, "f");
9002
9033
  }
@@ -9017,9 +9048,12 @@ class PerspectiveClient {
9017
9048
  }
9018
9049
  }`
9019
9050
  }));
9020
- return perspectives.map(handle => new PerspectiveProxy(handle, this));
9051
+ return perspectives.map(handle => this.getOrCreateProxy(handle));
9021
9052
  }
9022
9053
  async byUUID(uuid) {
9054
+ const cached = __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").get(uuid);
9055
+ if (cached)
9056
+ return cached;
9023
9057
  const { perspective } = unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").query({
9024
9058
  query: gql `query perspective($uuid: String!) {
9025
9059
  perspective(uuid: $uuid) {
@@ -9030,7 +9064,7 @@ class PerspectiveClient {
9030
9064
  }));
9031
9065
  if (!perspective)
9032
9066
  return null;
9033
- return new PerspectiveProxy(perspective, this);
9067
+ return this.getOrCreateProxy(perspective);
9034
9068
  }
9035
9069
  async snapshotByUUID(uuid) {
9036
9070
  const { perspectiveSnapshot } = unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").query({
@@ -9168,7 +9202,7 @@ class PerspectiveClient {
9168
9202
  }`,
9169
9203
  variables: { name }
9170
9204
  }));
9171
- return new PerspectiveProxy(perspectiveAdd, this);
9205
+ return this.getOrCreateProxy(perspectiveAdd);
9172
9206
  }
9173
9207
  async update(uuid, name) {
9174
9208
  const { perspectiveUpdate } = unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").mutate({
@@ -9179,9 +9213,12 @@ class PerspectiveClient {
9179
9213
  }`,
9180
9214
  variables: { uuid, name }
9181
9215
  }));
9182
- return new PerspectiveProxy(perspectiveUpdate, this);
9216
+ // Evict stale proxy — getOrCreateProxy will create a fresh one with updated handle
9217
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(uuid);
9218
+ return this.getOrCreateProxy(perspectiveUpdate);
9183
9219
  }
9184
9220
  async remove(uuid) {
9221
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(uuid);
9185
9222
  return unwrapApolloResult(await __classPrivateFieldGet$8(this, _PerspectiveClient_apolloClient, "f").mutate({
9186
9223
  mutation: gql `mutation perspectiveRemove($uuid: String!) {
9187
9224
  perspectiveRemove(uuid: $uuid)
@@ -9334,9 +9371,12 @@ class PerspectiveClient {
9334
9371
  `
9335
9372
  }).subscribe({
9336
9373
  next: result => {
9374
+ const handle = result.data.perspectiveAdded;
9337
9375
  __classPrivateFieldGet$8(this, _PerspectiveClient_perspectiveAddedCallbacks, "f").forEach(cb => {
9338
- cb(result.data.perspectiveAdded);
9376
+ cb(handle);
9339
9377
  });
9378
+ // Populate cache so subsequent byUUID() calls get a hit
9379
+ this.getOrCreateProxy(handle);
9340
9380
  },
9341
9381
  error: (e) => console.error(e)
9342
9382
  });
@@ -9352,9 +9392,13 @@ class PerspectiveClient {
9352
9392
  `
9353
9393
  }).subscribe({
9354
9394
  next: result => {
9395
+ const handle = result.data.perspectiveUpdated;
9355
9396
  __classPrivateFieldGet$8(this, _PerspectiveClient_perspectiveUpdatedCallbacks, "f").forEach(cb => {
9356
- cb(result.data.perspectiveUpdated);
9397
+ cb(handle);
9357
9398
  });
9399
+ // Evict stale proxy and create fresh one with updated handle
9400
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(handle.uuid);
9401
+ this.getOrCreateProxy(handle);
9358
9402
  },
9359
9403
  error: (e) => console.error(e)
9360
9404
  });
@@ -9389,9 +9433,12 @@ class PerspectiveClient {
9389
9433
  `
9390
9434
  }).subscribe({
9391
9435
  next: result => {
9436
+ const uuid = result.data.perspectiveRemoved;
9392
9437
  __classPrivateFieldGet$8(this, _PerspectiveClient_perspectiveRemovedCallbacks, "f").forEach(cb => {
9393
- cb(result.data.perspectiveRemoved);
9438
+ cb(uuid);
9394
9439
  });
9440
+ // Evict from cache
9441
+ __classPrivateFieldGet$8(this, _PerspectiveClient_proxyCache, "f").delete(uuid);
9395
9442
  },
9396
9443
  error: (e) => console.error(e)
9397
9444
  });
@@ -9489,7 +9536,7 @@ class PerspectiveClient {
9489
9536
  return perspectiveCommitBatch;
9490
9537
  }
9491
9538
  }
9492
- _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();
9539
+ _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();
9493
9540
 
9494
9541
  var __classPrivateFieldSet$7 = (undefined && undefined.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
9495
9542
  if (kind === "m") throw new TypeError("Private method is not writable");
@@ -18896,6 +18943,31 @@ var __decorate$6 = (undefined && undefined.__decorate) || function (decorators,
18896
18943
  var __metadata$6 = (undefined && undefined.__metadata) || function (k, v) {
18897
18944
  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
18898
18945
  };
18946
+ /**
18947
+ * # AD4M Language — client-side types
18948
+ *
18949
+ * This file only contains the client-visible types that the AD4M GraphQL
18950
+ * API exposes on top of a running Language — interaction metadata, online
18951
+ * agent records, and the telepresence-signal callback shape.
18952
+ *
18953
+ * **If you're authoring an AD4M Language**, you don't consume types from
18954
+ * here — use [`@coasys/ad4m-ldk`](https://www.npmjs.com/package/@coasys/ad4m-ldk)
18955
+ * (or the [Rust ALDK](https://crates.io/crates/ad4m-ldk)), which provide
18956
+ * the capability traits, typed runtime-import wrappers, and authoring
18957
+ * macros/helpers.
18958
+ *
18959
+ * The normative interface definition lives in
18960
+ * [`docs-src/ad4m-lang.wit`](https://github.com/coasys/ad4m/blob/dev/docs-src/ad4m-lang.wit).
18961
+ * The prose spec is
18962
+ * [`docs-src/language-interface-spec.md`](https://github.com/coasys/ad4m/blob/dev/docs-src/language-interface-spec.md).
18963
+ */
18964
+ // ----- Interaction metadata --------------------------------------------------
18965
+ //
18966
+ // Languages optionally publish a list of user-invocable actions per
18967
+ // Expression ("interactions"). The runtime surfaces these to UIs via
18968
+ // GraphQL, which is why `InteractionParameter` / `InteractionMeta` /
18969
+ // `InteractionCall` need the type-graphql decorators — they cross the
18970
+ // GraphQL boundary as first-class objects.
18899
18971
  exports.InteractionParameter = class InteractionParameter {
18900
18972
  };
18901
18973
  __decorate$6([
@@ -18947,6 +19019,7 @@ exports.InteractionCall = __decorate$6([
18947
19019
  InputType(),
18948
19020
  __metadata$6("design:paramtypes", [String, Object])
18949
19021
  ], exports.InteractionCall);
19022
+ // ----- Telepresence ----------------------------------------------------------
18950
19023
  exports.OnlineAgent = class OnlineAgent {
18951
19024
  };
18952
19025
  __decorate$6([
@@ -18961,9 +19034,6 @@ exports.OnlineAgent = __decorate$6([
18961
19034
  ObjectType()
18962
19035
  ], exports.OnlineAgent);
18963
19036
 
18964
- class Dna {
18965
- }
18966
-
18967
19037
  var __decorate$5 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
18968
19038
  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
18969
19039
  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -19990,6 +20060,59 @@ function buildModelFromJSONSchema(BaseClass, schema, options) {
19990
20060
  *
19991
20061
  * @module
19992
20062
  */
20063
+ /**
20064
+ * Check whether a `where` clause contains filters that cannot be pushed down
20065
+ * to SPARQL and must be evaluated in JS after hydration.
20066
+ *
20067
+ * JS-only filters include:
20068
+ * - Literal-stored properties (equality, comparison, contains, etc.)
20069
+ * - Reverse relations (belongsToOne / belongsToMany)
20070
+ * - author / timestamp filters (skipped by buildSPARQLWhereFilters)
20071
+ *
20072
+ * When JS-only filters exist, SPARQL-level LIMIT/OFFSET must NOT be applied
20073
+ * because the database would cap the candidate set before JS filters run,
20074
+ * potentially discarding matches beyond the LIMIT.
20075
+ */
20076
+ function hasJsOnlyWhereFilters(metadata, allRelationsMetadata, where) {
20077
+ if (!where)
20078
+ return false;
20079
+ for (const [propertyName, condition] of Object.entries(where)) {
20080
+ if (propertyName === "base" || propertyName === "id")
20081
+ continue;
20082
+ // author/timestamp: return true so that count() falls back to the full hydration
20083
+ // path (which uses buildSPARQLQuery — which DOES bind ?author/?timestamp via the
20084
+ // named graph block). buildSPARQLCountQuery intentionally omits the named graph,
20085
+ // so emitting an ?author FILTER there would produce unbound-variable SPARQL.
20086
+ // buildSPARQLWhereFilters still pushes these into FILTER when called from
20087
+ // buildSPARQLQuery / buildSPARQLGroupedCountQuery, which both include the named graph.
20088
+ if (propertyName === "author" || propertyName === "timestamp")
20089
+ return true;
20090
+ const propMeta = metadata.properties[propertyName];
20091
+ if (!propMeta)
20092
+ continue;
20093
+ // Reverse relations are JS-only
20094
+ const relMeta = allRelationsMetadata[propertyName];
20095
+ if (relMeta && (relMeta.kind === 'belongsToOne' || relMeta.kind === 'belongsToMany')) {
20096
+ return true;
20097
+ }
20098
+ // Literal-stored properties: equality/IN/NOT can be pushed to SPARQL via
20099
+ // <ad4m://fn/parse_literal>(), but comparison operators (gt/lt/gte/lte/between/contains)
20100
+ // must remain JS-only because parse_literal returns strings.
20101
+ if (isLiteralStoredProperty(propMeta)) {
20102
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
20103
+ const ops = condition;
20104
+ const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
20105
+ ops.lt !== undefined || ops.lte !== undefined ||
20106
+ ops.between !== undefined || ops.contains !== undefined;
20107
+ if (hasCompOps)
20108
+ return true;
20109
+ // NOT with simple value can be pushed to SPARQL — not JS-only
20110
+ }
20111
+ // Simple equality and IN filters can be pushed to SPARQL — not JS-only
20112
+ }
20113
+ }
20114
+ return false;
20115
+ }
19993
20116
  /**
19994
20117
  * Determine if a property stores values as literal: IRIs (needs parse_literal for comparisons).
19995
20118
  * Properties with resolveLanguage === "literal" AND properties without resolveLanguage
@@ -20033,6 +20156,30 @@ function formatSPARQLValue(value) {
20033
20156
  function iri(value) {
20034
20157
  return `<${value}>`;
20035
20158
  }
20159
+ /**
20160
+ * Map a user-facing property name to the SPARQL variable alias used in the query.
20161
+ *
20162
+ * Properties appear in the query as:
20163
+ * - Required properties: `?cfTarget_${name}`
20164
+ * - Where-clause joins: `?wTarget_${name}`
20165
+ * - Initial-value fallback: `?cfInitTarget_${name}`
20166
+ *
20167
+ * For ORDER BY, we prefer the conformance variable (always present for required props),
20168
+ * then the where-target variable.
20169
+ */
20170
+ function mapPropertyToSPARQLVar(propertyName, metadata) {
20171
+ const propMeta = metadata.properties[propertyName];
20172
+ if (propMeta) {
20173
+ if (propMeta.required && !propMeta.getter && !(propMeta.flag && propMeta.initial)) {
20174
+ return `?cfTarget_${propertyName}`;
20175
+ }
20176
+ if (propMeta.initial && !propMeta.flag) {
20177
+ return `?cfInitTarget_${propertyName}`;
20178
+ }
20179
+ }
20180
+ // Fallback: where-clause variable or raw name
20181
+ return `?wTarget_${propertyName}`;
20182
+ }
20036
20183
  /**
20037
20184
  * Build a SPARQL query that returns all links belonging to instances of
20038
20185
  * the given model class, optionally filtered by `where` conditions.
@@ -20116,6 +20263,35 @@ function buildSPARQLQuery(metadata, allRelationsMetadata, query, modelClass) {
20116
20263
  const filterClause = filterExpressions.length > 0
20117
20264
  ? `FILTER(\n ${filterExpressions.join(" &&\n ")}\n )`
20118
20265
  : "";
20266
+ // Determine if SPARQL-level pagination is safe.
20267
+ // When JS-only where filters exist, we must NOT limit at the SPARQL level
20268
+ // because the database would cap candidates before JS filters run.
20269
+ // Without an explicit ORDER BY, SPARQL OFFSET/LIMIT produces non-deterministic
20270
+ // ordering across different query plans and index traversals. Fall back to
20271
+ // JS-level slicing in that case to preserve the grouping order from the full
20272
+ // result set.
20273
+ const canPaginateInSPARQL = !hasJsOnlyWhereFilters(metadata, allRelationsMetadata, query.where)
20274
+ && (query.limit !== undefined || query.offset !== undefined)
20275
+ && query.order !== undefined && Object.keys(query.order).length > 0;
20276
+ // Build a pagination subquery that constrains ?source to only the page
20277
+ // of interest. This avoids fetching all links for all matching instances.
20278
+ const paginationSubquery = canPaginateInSPARQL
20279
+ ? buildPaginationSubquery(joinPatterns, filterExpressions, metadata, query)
20280
+ : '';
20281
+ if (paginationSubquery) {
20282
+ // Use the pagination subquery to constrain ?source, then fetch all links
20283
+ // for those sources only.
20284
+ return `
20285
+ SELECT ?source ?predicate ?target ?author ?timestamp WHERE {
20286
+ ${paginationSubquery}${joinClause}
20287
+ GRAPH ?linkGraph { ?source ?predicate ?target . }
20288
+ FILTER(isIRI(?source) && isIRI(?predicate))
20289
+ ?linkGraph <ad4m://ontology/author> ?author .
20290
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
20291
+ ${filterClause}
20292
+ }
20293
+ `.trim();
20294
+ }
20119
20295
  return `
20120
20296
  SELECT ?source ?predicate ?target ?author ?timestamp WHERE {${joinClause}
20121
20297
  GRAPH ?linkGraph { ?source ?predicate ?target . }
@@ -20129,10 +20305,146 @@ function buildSPARQLQuery(metadata, allRelationsMetadata, query, modelClass) {
20129
20305
  }
20130
20306
  /**
20131
20307
  * Build ORDER BY / LIMIT / OFFSET clauses for the SPARQL query.
20308
+ *
20309
+ * NOTE: The outer SELECT returns multiple rows per instance (one per link),
20310
+ * so LIMIT/OFFSET at the outer level would cut off links mid-instance.
20311
+ * This function is kept for backward compatibility and always returns "".
20312
+ * SPARQL-level pagination is handled via a subquery in buildSPARQLQuery
20313
+ * using buildPaginationSubquery().
20132
20314
  */
20133
- function buildSPARQLOrderLimitOffset(_metadata, _query) {
20315
+ function buildSPARQLOrderLimitOffset(_metadata, query) {
20134
20316
  return "";
20135
20317
  }
20318
+ /**
20319
+ * Build an inner subquery that selects DISTINCT ?source URIs with
20320
+ * ORDER BY, LIMIT, and OFFSET applied at the instance level.
20321
+ *
20322
+ * Because the outer SELECT returns multiple rows per instance (one per link),
20323
+ * we cannot apply LIMIT/OFFSET there. Instead this subquery constrains
20324
+ * ?source to only the instances on the requested page.
20325
+ *
20326
+ * @internal — used by buildSPARQLQuery when SPARQL-level pagination is safe.
20327
+ */
20328
+ function buildPaginationSubquery(joinPatterns, filterExpressions, metadata, query) {
20329
+ const innerJoin = joinPatterns.join('\n');
20330
+ const innerFilter = filterExpressions.length > 0
20331
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
20332
+ : '';
20333
+ // Build ORDER BY clause from query.order.
20334
+ // When ORDER BY references non-grouped variables we must use SAMPLE()
20335
+ // aggregates so the query is valid SPARQL 1.1.
20336
+ let orderByClause = '';
20337
+ const orderJoinPatterns = [];
20338
+ const sampleProjections = []; // e.g. (SAMPLE(?cfTarget_title) AS ?pg_sort_0)
20339
+ const needsGroupBy = query.order && Object.keys(query.order).length > 0;
20340
+ if (query.order) {
20341
+ let sortIdx = 0;
20342
+ const orderTerms = Object.entries(query.order).map(([prop, dir]) => {
20343
+ const sparqlVar = mapPropertyToSPARQLVar(prop, metadata);
20344
+ // Check if this order property's variable is already bound by existing
20345
+ // join patterns. If not, add an OPTIONAL join so ORDER BY is deterministic.
20346
+ const varAlreadyBound = innerJoin.includes(sparqlVar);
20347
+ if (!varAlreadyBound) {
20348
+ const propMeta = metadata.properties[prop];
20349
+ if (propMeta && propMeta.predicate && !propMeta.getter) {
20350
+ orderJoinPatterns.push(`\n OPTIONAL { ?source <${propMeta.predicate}> ${sparqlVar} . }`);
20351
+ }
20352
+ }
20353
+ // Use SAMPLE() aggregate so ORDER BY is valid with GROUP BY ?source.
20354
+ const sortAlias = `?pg_sort_${sortIdx++}`;
20355
+ sampleProjections.push(`(SAMPLE(${sparqlVar}) AS ${sortAlias})`);
20356
+ return dir === 'DESC' ? `DESC(${sortAlias})` : `ASC(${sortAlias})`;
20357
+ });
20358
+ if (orderTerms.length > 0) {
20359
+ orderByClause = `ORDER BY ${orderTerms.join(' ')}`;
20360
+ }
20361
+ }
20362
+ const limitClause = query.limit !== undefined ? `LIMIT ${query.limit}` : '';
20363
+ const offsetClause = query.offset !== undefined && query.offset > 0 ? `OFFSET ${query.offset}` : '';
20364
+ // When there's no ORDER BY, DISTINCT alone handles deduplication — no GROUP BY needed.
20365
+ // When there IS ORDER BY, use GROUP BY ?source with SAMPLE() aggregates for the sort keys.
20366
+ const sampleSelect = sampleProjections.length > 0 ? ' ' + sampleProjections.join(' ') : '';
20367
+ const groupByClause = needsGroupBy ? 'GROUP BY ?source' : '';
20368
+ return `
20369
+ { SELECT DISTINCT ?source${sampleSelect} WHERE {${innerJoin}${orderJoinPatterns.join('')}
20370
+ FILTER(isIRI(?source))
20371
+ ${innerFilter}
20372
+ } ${groupByClause} ${orderByClause} ${limitClause} ${offsetClause} }\n`;
20373
+ }
20374
+ /**
20375
+ * Build a SPARQL COUNT query that returns the total number of matching
20376
+ * instances WITHOUT hydrating them. Uses the same WHERE clause as
20377
+ * buildSPARQLQuery but wraps it in SELECT (COUNT(DISTINCT ?source) AS ?count).
20378
+ *
20379
+ * LIMIT/OFFSET from the query are stripped internally — this always counts
20380
+ * the full result set.
20381
+ */
20382
+ function buildSPARQLCountQuery(metadata, allRelationsMetadata, query, modelClass) {
20383
+ // Build the same join/filter patterns as buildSPARQLQuery
20384
+ const joinPatterns = [];
20385
+ const filterExpressions = [];
20386
+ if (query.parent) {
20387
+ const parentPredicate = resolveParentPredicate(query.parent, modelClass);
20388
+ joinPatterns.push(`\n ${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
20389
+ }
20390
+ let hasConformance = false;
20391
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20392
+ if (propMeta.required) {
20393
+ if (propMeta.getter)
20394
+ continue;
20395
+ hasConformance = true;
20396
+ if (propMeta.flag && propMeta.initial) {
20397
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20398
+ }
20399
+ else {
20400
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
20401
+ }
20402
+ }
20403
+ }
20404
+ if (!hasConformance) {
20405
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20406
+ if (propMeta.initial) {
20407
+ hasConformance = true;
20408
+ if (propMeta.flag) {
20409
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20410
+ }
20411
+ else {
20412
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
20413
+ }
20414
+ break;
20415
+ }
20416
+ }
20417
+ }
20418
+ if (!hasConformance && joinPatterns.length === 0) {
20419
+ const knownPredicates = [];
20420
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20421
+ if (propMeta.predicate)
20422
+ knownPredicates.push(iri(propMeta.predicate));
20423
+ }
20424
+ if (metadata.relations) {
20425
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
20426
+ if (relMeta.predicate)
20427
+ knownPredicates.push(iri(relMeta.predicate));
20428
+ }
20429
+ }
20430
+ if (knownPredicates.length > 0) {
20431
+ joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(", ")})) } }`);
20432
+ }
20433
+ }
20434
+ const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, query.where);
20435
+ joinPatterns.push(...userJoins);
20436
+ filterExpressions.push(...userFilters);
20437
+ const joinClause = joinPatterns.join('\n');
20438
+ const filterClause = filterExpressions.length > 0
20439
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
20440
+ : '';
20441
+ return `
20442
+ SELECT (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
20443
+ FILTER(isIRI(?source))
20444
+ ${filterClause}
20445
+ }
20446
+ `.trim();
20447
+ }
20136
20448
  /**
20137
20449
  * Build a SPARQL query to fetch all links for a single instance.
20138
20450
  */
@@ -20203,7 +20515,53 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
20203
20515
  }
20204
20516
  continue;
20205
20517
  }
20206
- if (propertyName === "author" || propertyName === "timestamp") {
20518
+ if (propertyName === "author") {
20519
+ // ?author is bound by the named graph block in buildSPARQLQuery /
20520
+ // buildSPARQLGroupedCountQuery — push equality/IN filters into SPARQL.
20521
+ if (Array.isArray(condition)) {
20522
+ const formatted = condition.map(v => formatSPARQLValue(String(v))).join(', ');
20523
+ filters.push(`STR(?author) IN (${formatted})`);
20524
+ }
20525
+ else if (typeof condition === 'object' && condition !== null) {
20526
+ const ops = condition;
20527
+ if (ops.not !== undefined) {
20528
+ if (Array.isArray(ops.not)) {
20529
+ const formatted = ops.not.map((v) => formatSPARQLValue(String(v))).join(', ');
20530
+ filters.push(`!(STR(?author) IN (${formatted}))`);
20531
+ }
20532
+ else {
20533
+ filters.push(`STR(?author) != ${formatSPARQLValue(String(ops.not))}`);
20534
+ }
20535
+ }
20536
+ // Other operators (gt/lt/etc.) fall through to JS post-filter
20537
+ }
20538
+ else {
20539
+ filters.push(`STR(?author) = ${formatSPARQLValue(String(condition))}`);
20540
+ }
20541
+ continue;
20542
+ }
20543
+ if (propertyName === "timestamp") {
20544
+ // ?timestamp is bound by the named graph block — push numeric comparisons.
20545
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
20546
+ const ops = condition;
20547
+ if (ops.gt !== undefined)
20548
+ filters.push(`?timestamp > ${Number(ops.gt)}`);
20549
+ if (ops.gte !== undefined)
20550
+ filters.push(`?timestamp >= ${Number(ops.gte)}`);
20551
+ if (ops.lt !== undefined)
20552
+ filters.push(`?timestamp < ${Number(ops.lt)}`);
20553
+ if (ops.lte !== undefined)
20554
+ filters.push(`?timestamp <= ${Number(ops.lte)}`);
20555
+ if (ops.between !== undefined && Array.isArray(ops.between)) {
20556
+ filters.push(`?timestamp >= ${Number(ops.between[0])} && ?timestamp <= ${Number(ops.between[1])}`);
20557
+ }
20558
+ if (ops.not !== undefined) {
20559
+ filters.push(`?timestamp != ${Number(ops.not)}`);
20560
+ }
20561
+ }
20562
+ else if (typeof condition === 'number' || (typeof condition === 'string' && !isNaN(Number(condition)))) {
20563
+ filters.push(`?timestamp = ${Number(condition)}`);
20564
+ }
20207
20565
  continue;
20208
20566
  }
20209
20567
  const propMeta = metadata.properties[propertyName];
@@ -20218,33 +20576,49 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
20218
20576
  }
20219
20577
  // Determine if this property stores values as literal: IRIs
20220
20578
  const useParseLiteral = isLiteralStoredProperty(propMeta);
20221
- // For literal-stored properties, skip SPARQL-level FILTER expressions entirely.
20222
- // The parse_literal custom function is unreliable across oxigraph versions and
20223
- // environments. All property-level where filtering is done in JS post-filter
20224
- // (instancesFromQueryResult) after hydration resolves values to JS primitives.
20225
- // We only add a JOIN pattern to ensure the property exists (conformance check).
20579
+ // For literal-stored properties, push equality/IN/NOT filters to SPARQL using
20580
+ // <ad4m://fn/parse_literal>() which extracts the raw value from literal: IRIs.
20581
+ // The correct SPARQL syntax is <ad4m://fn/parse_literal>(?var) — NOT fn::parse_literal
20582
+ // (which was SurrealDB syntax that Oxigraph rejects at parse time).
20583
+ // Comparison operators (gt/lt/gte/lte/between/contains) remain JS-only because
20584
+ // parse_literal returns strings and numeric/date comparisons would be unreliable.
20585
+ // JS post-filter in instancesFromQueryResult remains as a safety net for all cases.
20226
20586
  if (useParseLiteral) {
20227
- // Just ensure the property exists — no value filtering in SPARQL
20228
20587
  if (typeof condition === "object" && condition !== null && !Array.isArray(condition)) {
20229
20588
  const ops = condition;
20230
20589
  const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
20231
20590
  ops.lt !== undefined || ops.lte !== undefined ||
20232
- ops.between !== undefined || ops.contains !== undefined ||
20233
- ops.not !== undefined;
20591
+ ops.between !== undefined || ops.contains !== undefined;
20234
20592
  if (hasCompOps) {
20593
+ // Comparison operators: join only, filter in JS
20235
20594
  joins.push(`
20236
20595
  ?source ${iri(propMeta.predicate)} ?wTarget_cmp_${propertyName} .`);
20237
20596
  }
20238
- // NOT filters: no SPARQL-level filtering — handled in JS
20597
+ if (ops.not !== undefined) {
20598
+ // NOT filter: push down to SPARQL
20599
+ joins.push(`
20600
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
20601
+ if (Array.isArray(ops.not)) {
20602
+ const formatted = ops.not.map((v) => formatSPARQLValue(v)).join(", ");
20603
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) NOT IN (${formatted})`);
20604
+ }
20605
+ else {
20606
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) != ${formatSPARQLValue(ops.not)}`);
20607
+ }
20608
+ }
20609
+ }
20610
+ else if (Array.isArray(condition)) {
20611
+ // IN filter: push down to SPARQL
20612
+ joins.push(`
20613
+ ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
20614
+ const formatted = condition.map((v) => formatSPARQLValue(v)).join(", ");
20615
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) IN (${formatted})`);
20239
20616
  }
20240
20617
  else {
20241
- // Simple equality or IN — add join for conformance.
20242
- // NOTE: push-down FILTER with fn::parse_literal was attempted but removed because
20243
- // Oxigraph's query parser rejects the fn:: custom function syntax at parse time
20244
- // (custom functions are only available at execution time). All literal property
20245
- // filtering is done in JS post-filter after hydration resolves values.
20618
+ // Simple equality: push down to SPARQL
20246
20619
  joins.push(`
20247
20620
  ?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
20621
+ filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) = ${formatSPARQLValue(condition)}`);
20248
20622
  }
20249
20623
  }
20250
20624
  else if (Array.isArray(condition)) {
@@ -20289,6 +20663,133 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
20289
20663
  }
20290
20664
  return { joins, filters };
20291
20665
  }
20666
+ /**
20667
+ * Parse a SPARQL COUNT result row into a number.
20668
+ * Handles `row.count?.value` (RDF binding), `row.count` (direct number/string),
20669
+ * NaN results, and empty/malformed results.
20670
+ *
20671
+ * @returns The parsed count, or `null` if the result cannot be interpreted.
20672
+ */
20673
+ function parseSparqlCount(result) {
20674
+ if (!Array.isArray(result) || result.length === 0)
20675
+ return null;
20676
+ const row = result[0];
20677
+ const val = row.count?.value ?? row.count;
20678
+ if (val === undefined || val === null)
20679
+ return null;
20680
+ const parsed = typeof val === 'number' ? val : parseInt(String(val), 10);
20681
+ return isNaN(parsed) ? null : parsed;
20682
+ }
20683
+ /**
20684
+ * Build a SPARQL query that counts child instances grouped by parent IRI.
20685
+ *
20686
+ * Used by the projection Path A (`count: true`) in `hydrateRelations` to get
20687
+ * per-parent counts in a single round-trip with zero instance hydration.
20688
+ *
20689
+ * Includes the full named graph block so that `?author` and `?timestamp` are
20690
+ * bound and available for SPARQL FILTER expressions (unlike the intentionally
20691
+ * minimal `buildSPARQLCountQuery` which omits them for speed).
20692
+ *
20693
+ * @param metadata - Model metadata for the **child** (target) class
20694
+ * @param allRelationsMetadata - Relations metadata for the child class
20695
+ * @param relationPredicate - The predicate linking `?parent` → `?source` (child)
20696
+ * @param parentIds - IRI strings of all parent instances to count for
20697
+ * @param where - Optional filter applied to child instances
20698
+ */
20699
+ function buildSPARQLGroupedCountQuery(metadata, allRelationsMetadata, relationPredicate, parentIds, where) {
20700
+ const joinPatterns = [];
20701
+ const filterExpressions = [];
20702
+ // Parent → child join and IN filter
20703
+ joinPatterns.push(`\n ?parent ${iri(relationPredicate)} ?source .`);
20704
+ const parentIris = parentIds.map(id => iri(id)).join(', ');
20705
+ filterExpressions.push(`?parent IN (${parentIris})`);
20706
+ // Conformance patterns (mirrors buildSPARQLCountQuery logic)
20707
+ let hasConformance = false;
20708
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20709
+ if (propMeta.required) {
20710
+ if (propMeta.getter)
20711
+ continue;
20712
+ hasConformance = true;
20713
+ if (propMeta.flag && propMeta.initial) {
20714
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20715
+ }
20716
+ else {
20717
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
20718
+ }
20719
+ }
20720
+ }
20721
+ if (!hasConformance) {
20722
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20723
+ if (propMeta.initial) {
20724
+ hasConformance = true;
20725
+ if (propMeta.flag) {
20726
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
20727
+ }
20728
+ else {
20729
+ joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
20730
+ }
20731
+ break;
20732
+ }
20733
+ }
20734
+ }
20735
+ if (!hasConformance && joinPatterns.length <= 1) {
20736
+ // Only the parent join so far — add open-world structural matching
20737
+ const knownPredicates = [];
20738
+ for (const [, propMeta] of Object.entries(metadata.properties)) {
20739
+ if (propMeta.predicate)
20740
+ knownPredicates.push(iri(propMeta.predicate));
20741
+ }
20742
+ if (metadata.relations) {
20743
+ for (const [, relMeta] of Object.entries(metadata.relations)) {
20744
+ if (relMeta.predicate)
20745
+ knownPredicates.push(iri(relMeta.predicate));
20746
+ }
20747
+ }
20748
+ if (knownPredicates.length > 0) {
20749
+ joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(', ')})) } }`);
20750
+ }
20751
+ }
20752
+ // User where-clause filters (including author/timestamp after the SPARQL push)
20753
+ const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, where);
20754
+ joinPatterns.push(...userJoins);
20755
+ filterExpressions.push(...userFilters);
20756
+ const joinClause = joinPatterns.join('\n');
20757
+ const filterClause = filterExpressions.length > 0
20758
+ ? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
20759
+ : '';
20760
+ return `
20761
+ SELECT ?parent (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
20762
+ GRAPH ?linkGraph { ?source ?predicate ?target . }
20763
+ FILTER(isIRI(?source) && isIRI(?predicate))
20764
+ ?linkGraph <ad4m://ontology/author> ?author .
20765
+ ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
20766
+ ${filterClause}
20767
+ }
20768
+ GROUP BY ?parent
20769
+ `.trim();
20770
+ }
20771
+ /**
20772
+ * Parse the result of `buildSPARQLGroupedCountQuery` into a map from parent IRI
20773
+ * to count. Missing parents (zero matches) are absent from the map — callers
20774
+ * should use `map.get(id) ?? 0`.
20775
+ *
20776
+ * @returns Map from parentId string → count number
20777
+ */
20778
+ function parseSparqlGroupedCount(result) {
20779
+ const out = new Map();
20780
+ if (!Array.isArray(result))
20781
+ return out;
20782
+ for (const row of result) {
20783
+ const parentVal = row.parent?.value ?? row.parent;
20784
+ const countVal = row.count?.value ?? row.count;
20785
+ if (!parentVal || countVal === undefined || countVal === null)
20786
+ continue;
20787
+ const parsed = typeof countVal === 'number' ? countVal : parseInt(String(countVal), 10);
20788
+ if (!isNaN(parsed))
20789
+ out.set(String(parentVal), parsed);
20790
+ }
20791
+ return out;
20792
+ }
20292
20793
 
20293
20794
  /**
20294
20795
  * Subscription Pool — deduplicates identical SPARQL subscriptions.
@@ -20347,14 +20848,60 @@ async function pooledSubscribe(perspective, sparqlQuery, hydrate, onResult) {
20347
20848
  refCount: 1,
20348
20849
  };
20349
20850
  pool.set(key, newEntry);
20350
- // Set up shared result handler
20851
+ // Set up shared result handler with delta optimization
20351
20852
  subscription.onResult(async (rawResult) => {
20853
+ const prevRaw = newEntry.latestRaw;
20352
20854
  newEntry.latestRaw = rawResult;
20353
20855
  newEntry.hydrating = true;
20354
20856
  try {
20355
- // Hydrate ONCE using the first subscriber's hydrate function
20356
20857
  const firstSub = newEntry.callbacks.values().next().value;
20357
20858
  if (firstSub) {
20859
+ // Delta optimization: if the new result is strictly an addition
20860
+ // (all previous rows still present + new rows), only hydrate the
20861
+ // new rows and append them to the cached hydrated result.
20862
+ const prevArr = Array.isArray(prevRaw) ? prevRaw : [];
20863
+ const newArr = Array.isArray(rawResult) ? rawResult : [];
20864
+ const prevHydrated = newEntry.latestHydrated;
20865
+ if (prevHydrated &&
20866
+ Array.isArray(prevHydrated) &&
20867
+ newArr.length > prevArr.length &&
20868
+ newArr.length - prevArr.length <= 5 // small delta — worth optimizing
20869
+ ) {
20870
+ // Build a set of source URIs from previous results for quick lookup
20871
+ const prevSources = new Set(prevArr.map((r) => `${r.source}|${r.predicate}|${r.target}`));
20872
+ const addedRows = newArr.filter((r) => !prevSources.has(`${r.source}|${r.predicate}|${r.target}`));
20873
+ // Check that no rows were removed (pure addition)
20874
+ const newSources = new Set(newArr.map((r) => `${r.source}|${r.predicate}|${r.target}`));
20875
+ const removedRows = prevArr.filter((r) => !newSources.has(`${r.source}|${r.predicate}|${r.target}`));
20876
+ if (removedRows.length === 0 && addedRows.length > 0) {
20877
+ // Verify ALL added rows have sources not in previous results.
20878
+ // If any added row's source matches an existing source, it means
20879
+ // an existing instance got new links — we need full rehydration.
20880
+ const prevSourceIds = new Set(prevArr.map((r) => r.source));
20881
+ const allNewSources = addedRows.every((r) => !prevSourceIds.has(r.source));
20882
+ if (allNewSources) {
20883
+ // Pure addition of new instances — hydrate only the new rows
20884
+ try {
20885
+ const deltaHydrated = await firstSub.hydrate(addedRows);
20886
+ if (Array.isArray(deltaHydrated)) {
20887
+ const merged = [...prevHydrated, ...deltaHydrated];
20888
+ newEntry.latestHydrated = merged;
20889
+ for (const cb of newEntry.callbacks) {
20890
+ try {
20891
+ cb.onResult(merged);
20892
+ }
20893
+ catch (e) { /* subscriber error */ }
20894
+ }
20895
+ return; // Delta path succeeded
20896
+ }
20897
+ }
20898
+ catch {
20899
+ // Delta hydration failed — fall through to full hydration
20900
+ }
20901
+ }
20902
+ }
20903
+ }
20904
+ // Full hydration fallback
20358
20905
  const hydrated = await firstSub.hydrate(rawResult);
20359
20906
  newEntry.latestHydrated = hydrated;
20360
20907
  // Distribute to all callbacks
@@ -20613,6 +21160,28 @@ class ModelQueryBuilder {
20613
21160
  this.queryParams.properties = properties;
20614
21161
  return this;
20615
21162
  }
21163
+ /**
21164
+ * Opts in to evaluating SPARQL property getters during collection hydration.
21165
+ *
21166
+ * By default, collection queries skip getter evaluation for performance.
21167
+ * Call `.deepQuery()` when you need getter-backed properties in the result set.
21168
+ *
21169
+ * @returns The query builder for chaining
21170
+ *
21171
+ * @example
21172
+ * ```typescript
21173
+ * const messages = await Message.query(perspective)
21174
+ * .parent(channel)
21175
+ * .deepQuery()
21176
+ * .limit(30)
21177
+ * .get();
21178
+ * // messages[i].replyingTo is populated
21179
+ * ```
21180
+ */
21181
+ deepQuery() {
21182
+ this.queryParams.deepQuery = true;
21183
+ return this;
21184
+ }
20616
21185
  /**
20617
21186
  * Specifies which relations to eager-load (hydrate into model instances).
20618
21187
  *
@@ -20697,9 +21266,9 @@ class ModelQueryBuilder {
20697
21266
  * Groups raw SPARQL results and hydrates them into model instances.
20698
21267
  * Centralises the repeated groupSPARQLResults → instancesFromQueryResult pipeline.
20699
21268
  */
20700
- async processSparqlResult(rawResult, queryOverride) {
21269
+ async processSparqlResult(rawResult, queryOverride, computeTotalCount = false) {
20701
21270
  const grouped = groupSPARQLResults(Array.isArray(rawResult) ? rawResult : []);
20702
- return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped);
21271
+ return await this.ctor.instancesFromQueryResult(this.perspective, queryOverride || this.queryParams, grouped, computeTotalCount);
20703
21272
  }
20704
21273
  /**
20705
21274
  * Returns the first matching instance, or `null` if none match.
@@ -20762,9 +21331,9 @@ class ModelQueryBuilder {
20762
21331
  const buildFingerprint = (results) => {
20763
21332
  if (results.length === 0)
20764
21333
  return '0:';
20765
- const ids = results.map((r) => r.id || '').sort().join(',');
20766
- const ts = results.map((r) => r.updatedAt || r.timestamp || '').join(',');
20767
- return `${results.length}:${ids}:${ts}`;
21334
+ // Must include relation data (e.g. tags) — not just id/timestamp.
21335
+ // Otherwise @HasMany changes on existing instances are suppressed as duplicates.
21336
+ return JSON.stringify(results, (_, v) => typeof v === 'function' ? undefined : v);
20768
21337
  };
20769
21338
  const hydrate = async (rawResult) => {
20770
21339
  const { results } = await this.processSparqlResult(rawResult);
@@ -20826,10 +21395,19 @@ class ModelQueryBuilder {
20826
21395
  */
20827
21396
  async count() {
20828
21397
  if (this.engineFlag === 'sparql') {
20829
- const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
20830
- const rawResult = await this.perspective.querySparql(sparqlQuery);
20831
- const { totalCount } = await this.processSparqlResult(rawResult);
20832
- return totalCount;
21398
+ // When query has JS-only where filters, fall back to full hydration
21399
+ const metadata = this.ctor.getModelMetadata();
21400
+ const allRelMeta = getRelationsMetadata(this.ctor);
21401
+ if (hasJsOnlyWhereFilters(metadata, allRelMeta, this.queryParams.where)) {
21402
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
21403
+ const rawResult = await this.perspective.querySparql(sparqlQuery);
21404
+ const { totalCount } = await this.processSparqlResult(rawResult, undefined, true);
21405
+ return totalCount;
21406
+ }
21407
+ // Use efficient COUNT query — no hydration
21408
+ const countSparql = await this.ctor.countQueryToSPARQL(this.perspective, this.queryParams);
21409
+ const countResult = await this.perspective.querySparql(countSparql);
21410
+ return parseSparqlCount(countResult) ?? 0;
20833
21411
  }
20834
21412
  else {
20835
21413
  const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
@@ -20889,11 +21467,11 @@ class ModelQueryBuilder {
20889
21467
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
20890
21468
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
20891
21469
  const processResults = async (result) => {
20892
- const { totalCount } = await this.processSparqlResult(result);
21470
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
20893
21471
  callback(totalCount);
20894
21472
  };
20895
21473
  this.currentSubscription.onResult(processResults);
20896
- const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
21474
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
20897
21475
  // Initial count returned via Promise — callback for updates only
20898
21476
  return totalCount;
20899
21477
  }
@@ -20918,11 +21496,11 @@ class ModelQueryBuilder {
20918
21496
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, this.queryParams);
20919
21497
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
20920
21498
  const processResults = async (result) => {
20921
- const { totalCount } = await this.processSparqlResult(result);
21499
+ const { totalCount } = await this.processSparqlResult(result, undefined, true);
20922
21500
  callback(totalCount);
20923
21501
  };
20924
21502
  this.currentSubscription.onResult(processResults);
20925
- const { totalCount } = await this.processSparqlResult(this.currentSubscription.result);
21503
+ const { totalCount } = await this.processSparqlResult(this.currentSubscription.result, undefined, true);
20926
21504
  // Initial count returned via Promise — callback for updates only
20927
21505
  return totalCount;
20928
21506
  }
@@ -20946,7 +21524,7 @@ class ModelQueryBuilder {
20946
21524
  if (this.engineFlag === 'sparql') {
20947
21525
  const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
20948
21526
  const result = await this.perspective.querySparql(sparqlQuery);
20949
- const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
21527
+ const { results, totalCount } = await this.processSparqlResult(result, paginationQuery, true);
20950
21528
  return { results, totalCount, pageSize, pageNumber };
20951
21529
  }
20952
21530
  else {
@@ -21008,14 +21586,26 @@ class ModelQueryBuilder {
21008
21586
  this.dispose();
21009
21587
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
21010
21588
  if (this.engineFlag === 'sparql') {
21011
- const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, paginationQuery);
21589
+ // Subscribe to the FULL result set (no LIMIT/OFFSET) so the subscription
21590
+ // detects changes anywhere in the dataset (e.g. new items beyond current page).
21591
+ // Pagination is applied in JS when processing each update.
21592
+ const subscriptionParams = { ...(this.queryParams || {}) };
21593
+ delete subscriptionParams.limit;
21594
+ delete subscriptionParams.offset;
21595
+ const sparqlQuery = await this.ctor.queryToSPARQL(this.perspective, subscriptionParams);
21012
21596
  this.currentSubscription = await this.perspective.subscribeQuery(sparqlQuery);
21597
+ // Query for processSparqlResult has NO limit/offset — gets all results, totalCount via count:true
21598
+ const fullQuery = { ...(this.queryParams || {}), count: true };
21013
21599
  const processResults = async (result) => {
21014
- const { results, totalCount } = await this.processSparqlResult(result, paginationQuery);
21600
+ const { results: allResults, totalCount } = await this.processSparqlResult(result, fullQuery, true);
21601
+ const start = pageSize * (pageNumber - 1);
21602
+ const results = allResults.slice(start, start + pageSize);
21015
21603
  callback({ results, totalCount, pageSize, pageNumber });
21016
21604
  };
21017
21605
  this.currentSubscription.onResult(processResults);
21018
- const { results, totalCount } = await this.processSparqlResult(this.currentSubscription.result, paginationQuery);
21606
+ const { results: allResults, totalCount } = await this.processSparqlResult(this.currentSubscription.result, fullQuery, true);
21607
+ const start = pageSize * (pageNumber - 1);
21608
+ const results = allResults.slice(start, start + pageSize);
21019
21609
  const initialPage = { results, totalCount, pageSize, pageNumber };
21020
21610
  // Initial page returned via Promise — callback for subsequent updates only
21021
21611
  return initialPage;
@@ -21439,41 +22029,44 @@ async function evaluateCustomGettersForInstance(instance, perspective, metadata,
21439
22029
  // evaluate getters for fields that are requested (or included).
21440
22030
  const projectionActive = options?.requestedProperties && options.requestedProperties.length > 0;
21441
22031
  const projectionSet = projectionActive ? new Set(options.requestedProperties) : null;
21442
- // Evaluate property getters
21443
- for (const [propName, propMeta] of Object.entries(metadata.properties)) {
21444
- if (projectionSet && !projectionSet.has(propName))
21445
- continue;
21446
- if (propMeta.getter) {
21447
- try {
21448
- const rawGetter = propMeta.getter;
21449
- const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
21450
- // If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
21451
- const trimmed = getterWithBase.trim().toUpperCase();
21452
- if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
21453
- const result = await perspective.querySparql(getterWithBase);
21454
- if (trimmed.startsWith('ASK')) {
21455
- instance[propName] = result === true || result === 'true';
21456
- }
21457
- else if (result && result.length > 0) {
21458
- // Get first binding's first value
21459
- const firstRow = result[0];
21460
- const firstKey = Object.keys(firstRow)[0];
21461
- const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
21462
- if (val !== undefined && val !== null && val !== 'None' && val !== '') {
21463
- instance[propName] = val;
22032
+ // Evaluate property getters (skip when caller only wants relation type-filtering)
22033
+ if (!options?.skipPropertyGetters) {
22034
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
22035
+ if (projectionSet && !projectionSet.has(propName))
22036
+ continue;
22037
+ if (propMeta.getter) {
22038
+ try {
22039
+ const rawGetter = propMeta.getter;
22040
+ const getterWithBase = rawGetter.replace(/\?source\b/g, `<${instance.id}>`).replace(/<Base>/g, `<${instance.id}>`).replace(/Base/g, `<${instance.id}>`);
22041
+ // If the getter is already SPARQL (starts with SELECT/ASK/CONSTRUCT), execute directly
22042
+ const trimmed = getterWithBase.trim().toUpperCase();
22043
+ if (trimmed.startsWith('SELECT') || trimmed.startsWith('ASK') || trimmed.startsWith('CONSTRUCT')) {
22044
+ const result = await perspective.querySparql(getterWithBase);
22045
+ if (trimmed.startsWith('ASK')) {
22046
+ instance[propName] = result === true || result === 'true';
21464
22047
  }
22048
+ else if (result && result.length > 0) {
22049
+ // Get first binding's first value
22050
+ const firstRow = result[0];
22051
+ const firstKey = Object.keys(firstRow)[0];
22052
+ const val = firstRow[firstKey]?.value ?? firstRow[firstKey];
22053
+ if (val !== undefined && val !== null && val !== 'None' && val !== '') {
22054
+ instance[propName] = val;
22055
+ }
22056
+ }
22057
+ }
22058
+ else {
22059
+ // Legacy SurrealDB-style getter — safety guard for getters that don't match
22060
+ // SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
22061
+ console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
21465
22062
  }
21466
22063
  }
21467
- else {
21468
- // Legacy SurrealDB-style getter — no longer supported
21469
- console.warn(`Unsupported legacy getter syntax for property ${propName} — use native SPARQL (SELECT/ASK): ${rawGetter.slice(0, 100)}`);
22064
+ catch (error) {
22065
+ console.warn(`Failed to evaluate getter for ${propName}:`, error);
21470
22066
  }
21471
22067
  }
21472
- catch (error) {
21473
- console.warn(`Failed to evaluate getter for ${propName}:`, error);
21474
- }
21475
22068
  }
21476
- }
22069
+ } // end skipPropertyGetters guard
21477
22070
  // Evaluate relation getters (explicit or auto-generated from target)
21478
22071
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
21479
22072
  // Skip relations excluded by property projection (unless in include map)
@@ -21553,7 +22146,8 @@ async function evaluateCustomGettersForInstance(instance, perspective, metadata,
21553
22146
  }
21554
22147
  }
21555
22148
  else {
21556
- // Legacy SurrealDB-style getter — no longer supported
22149
+ // Legacy SurrealDB-style getter — safety guard for relation getters that don't
22150
+ // match SPARQL patterns (SELECT/ASK). Logs a warning but does not crash.
21557
22151
  console.warn(`Unsupported legacy getter syntax for relation ${relName} — use native SPARQL (SELECT/ASK): ${getter.slice(0, 100)}`);
21558
22152
  }
21559
22153
  }
@@ -21609,7 +22203,166 @@ async function hydrateRelations(modelClass, instances, perspective, includeMap)
21609
22203
  if (!includeMap || Object.keys(includeMap).length === 0)
21610
22204
  return;
21611
22205
  const relMeta = getRelationsMetadata(modelClass);
22206
+ // ── Projections ($-prefixed keys) ────────────────────────────────────────
22207
+ // Collect all projection entries up-front so we can batch the count queries
22208
+ // together per-projection before processing. Each projection key starts
22209
+ // with '$' and has a descriptor with a `from` field.
22210
+ const projectionEntries = [];
22211
+ for (const [key, val] of Object.entries(includeMap)) {
22212
+ if (key.startsWith('$') && val !== null && typeof val === 'object' && 'from' in val) {
22213
+ projectionEntries.push([key, val]);
22214
+ }
22215
+ }
22216
+ for (const [projKey, proj] of projectionEntries) {
22217
+ const sourceMeta = relMeta[proj.from];
22218
+ if (!sourceMeta) {
22219
+ console.warn(`include projection "${projKey}": relation "${proj.from}" not found in metadata, skipping`);
22220
+ for (const inst of instances)
22221
+ inst[projKey] = proj.count ? 0 : [];
22222
+ continue;
22223
+ }
22224
+ const TargetClass = sourceMeta.target();
22225
+ const allParentIds = instances.map(inst => inst.id).filter(Boolean);
22226
+ if (proj.count) {
22227
+ // ── Path A: grouped SPARQL COUNT ─────────────────────────────────────
22228
+ // One round-trip, zero instance hydration. Returns one row per parent.
22229
+ const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
22230
+ const targetRelMeta = TargetClass.getAllRelationsMetadata?.() ?? {};
22231
+ let countMap = new Map();
22232
+ if (targetMetadata && allParentIds.length > 0) {
22233
+ try {
22234
+ const sparql = buildSPARQLGroupedCountQuery(targetMetadata, targetRelMeta, sourceMeta.predicate, allParentIds, proj.where);
22235
+ const raw = await perspective.querySparql(sparql);
22236
+ const rows = Array.isArray(raw) ? raw
22237
+ : raw?.results?.bindings ?? raw?.bindings ?? [];
22238
+ countMap = parseSparqlGroupedCount(rows);
22239
+ }
22240
+ catch (e) {
22241
+ console.warn(`include projection "${projKey}" count query failed, falling back to 0:`, e);
22242
+ }
22243
+ }
22244
+ for (const inst of instances) {
22245
+ inst[projKey] = countMap.get(inst.id) ?? 0;
22246
+ }
22247
+ }
22248
+ else {
22249
+ // ── Path B: findAll + Map distribution ───────────────────────────────
22250
+ // For reverse relations we don't have the child IDs on the instance,
22251
+ // so fall back to a parent-scoped findAll per instance (uncommon path).
22252
+ const isReverse = sourceMeta.kind === 'belongsToOne' || sourceMeta.kind === 'belongsToMany';
22253
+ if (isReverse) {
22254
+ // Reverse: the link goes child→parent, reuse the batched SPARQL pattern
22255
+ // from the existing belongsTo path to collect source IDs per parent.
22256
+ if (allParentIds.length > 0) {
22257
+ const sparqlQuery = `SELECT ?source ?target WHERE {
22258
+ GRAPH ?g { ?source <${sourceMeta.predicate}> ?target }
22259
+ FILTER(?target IN (${allParentIds.map(id => `<${id}>`).join(', ')}))
22260
+ }`;
22261
+ const sourcesByTarget = new Map();
22262
+ try {
22263
+ const raw = await perspective.querySparql(sparqlQuery);
22264
+ const bindings = Array.isArray(raw) ? raw : raw?.results?.bindings ?? raw?.bindings ?? [];
22265
+ for (const row of bindings) {
22266
+ const source = row.source?.value ?? row.source;
22267
+ const target = row.target?.value ?? row.target;
22268
+ if (!source || !target)
22269
+ continue;
22270
+ if (!sourcesByTarget.has(target))
22271
+ sourcesByTarget.set(target, []);
22272
+ sourcesByTarget.get(target).push(source);
22273
+ }
22274
+ }
22275
+ catch (e) {
22276
+ console.warn(`include projection "${projKey}" reverse SPARQL failed:`, e);
22277
+ }
22278
+ const allSourceIds = new Set();
22279
+ for (const ids of sourcesByTarget.values())
22280
+ for (const id of ids)
22281
+ allSourceIds.add(id);
22282
+ const hydratedMap = new Map();
22283
+ if (allSourceIds.size > 0) {
22284
+ const results = await TargetClass.findAll(perspective, {
22285
+ where: { id: Array.from(allSourceIds), ...(proj.where ?? {}) },
22286
+ });
22287
+ for (const r of results)
22288
+ hydratedMap.set(r.id, r);
22289
+ }
22290
+ for (const inst of instances) {
22291
+ const sourceIds = sourcesByTarget.get(inst.id) ?? [];
22292
+ let resolved = sourceIds.map(id => hydratedMap.get(id)).filter((v) => v != null);
22293
+ if (proj.limit != null) {
22294
+ if (proj.limit === 1) {
22295
+ inst[projKey] = resolved[0] ?? null;
22296
+ }
22297
+ else {
22298
+ inst[projKey] = resolved.slice(0, proj.limit);
22299
+ }
22300
+ }
22301
+ else {
22302
+ inst[projKey] = resolved;
22303
+ }
22304
+ }
22305
+ }
22306
+ else {
22307
+ for (const inst of instances)
22308
+ inst[projKey] = proj.limit === 1 ? null : [];
22309
+ }
22310
+ }
22311
+ else {
22312
+ // Forward: instance[from] holds raw child URIs — collect across all parents
22313
+ const uriSet = new Set();
22314
+ const rawCache = new Map();
22315
+ for (const inst of instances) {
22316
+ const raw = inst[proj.from];
22317
+ const uris = [];
22318
+ if (Array.isArray(raw)) {
22319
+ for (const v of raw) {
22320
+ const id = typeof v === 'string' ? v : v?.id;
22321
+ if (id) {
22322
+ uriSet.add(id);
22323
+ uris.push(id);
22324
+ }
22325
+ }
22326
+ }
22327
+ else if (typeof raw === 'string') {
22328
+ uriSet.add(raw);
22329
+ uris.push(raw);
22330
+ }
22331
+ else if (raw?.id) {
22332
+ uriSet.add(raw.id);
22333
+ uris.push(raw.id);
22334
+ }
22335
+ rawCache.set(inst, uris);
22336
+ }
22337
+ const hydratedMap = new Map();
22338
+ if (uriSet.size > 0) {
22339
+ const results = await TargetClass.findAll(perspective, {
22340
+ where: { id: Array.from(uriSet), ...(proj.where ?? {}) },
22341
+ });
22342
+ for (const r of results)
22343
+ hydratedMap.set(r.id, r);
22344
+ }
22345
+ for (const inst of instances) {
22346
+ const uris = rawCache.get(inst) ?? [];
22347
+ const resolved = uris.map(id => hydratedMap.get(id)).filter((v) => v != null);
22348
+ if (proj.limit === 1) {
22349
+ inst[projKey] = resolved[0] ?? null;
22350
+ }
22351
+ else if (proj.limit != null) {
22352
+ inst[projKey] = resolved.slice(0, proj.limit);
22353
+ }
22354
+ else {
22355
+ inst[projKey] = resolved;
22356
+ }
22357
+ }
22358
+ }
22359
+ }
22360
+ }
22361
+ // ── Standard relations (non-projected) ───────────────────────────────────
21612
22362
  for (const [relName, includeValue] of Object.entries(includeMap)) {
22363
+ // Skip projection keys — already handled above
22364
+ if (relName.startsWith('$') && typeof includeValue === 'object' && includeValue !== null && 'from' in includeValue)
22365
+ continue;
21613
22366
  const meta = relMeta[relName];
21614
22367
  if (!meta) {
21615
22368
  console.warn(`include: relation "${relName}" not found in metadata, skipping`);
@@ -21624,57 +22377,102 @@ async function hydrateRelations(modelClass, instances, perspective, includeMap)
21624
22377
  // ── Reverse relations (belongsToOne / belongsToMany) ──────────────────
21625
22378
  // The link goes target→instance, so we query backwards:
21626
22379
  // predicate = meta.predicate, target = inst.id → source is the related id
22380
+ //
22381
+ // PERF: Batch all reverse lookups into a single SPARQL query instead of
22382
+ // N sequential perspective.get() calls (N+1 → 1 optimisation).
21627
22383
  if (meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany') {
21628
- // Per-instance reverse lookup (can't batch easily across instances)
22384
+ const allIds = instances.map(inst => inst.id).filter(Boolean);
22385
+ // Batch query: find all (source, target) pairs for this predicate
22386
+ // where target is one of our instance IDs
22387
+ const sourcesByTarget = new Map();
22388
+ if (allIds.length > 0) {
22389
+ const sparqlQuery = `SELECT ?source ?target WHERE {
22390
+ GRAPH ?g { ?source <${meta.predicate}> ?target }
22391
+ FILTER(?target IN (${allIds.map(id => `<${id}>`).join(', ')}))
22392
+ }`;
22393
+ try {
22394
+ const sparqlResult = await perspective.querySparql(sparqlQuery);
22395
+ // Parse SPARQL results — querySparql returns a flat array of row objects
22396
+ // e.g. [{ source: "uri1", target: "uri2" }, ...]
22397
+ const bindings = Array.isArray(sparqlResult) ? sparqlResult
22398
+ : sparqlResult?.results?.bindings ?? sparqlResult?.bindings ?? [];
22399
+ for (const row of bindings) {
22400
+ const source = row.source?.value ?? row.source;
22401
+ const target = row.target?.value ?? row.target;
22402
+ if (!source || !target)
22403
+ continue;
22404
+ if (!sourcesByTarget.has(target))
22405
+ sourcesByTarget.set(target, []);
22406
+ sourcesByTarget.get(target).push(source);
22407
+ }
22408
+ }
22409
+ catch (e) {
22410
+ // Fallback: sequential queries if SPARQL fails
22411
+ console.warn('Batched reverse relation SPARQL failed, falling back to sequential:', e);
22412
+ for (const inst of instances) {
22413
+ const reverseLinks = await perspective.get(new exports.LinkQuery({ predicate: meta.predicate, target: inst.id }));
22414
+ const sourceIds = reverseLinks
22415
+ .filter(l => l.data.target === inst.id)
22416
+ .map(l => l.data.source);
22417
+ if (sourceIds.length > 0) {
22418
+ sourcesByTarget.set(inst.id, sourceIds);
22419
+ }
22420
+ }
22421
+ }
22422
+ }
22423
+ // Collect ALL source IDs across all instances for batch hydration
22424
+ const allSourceIds = new Set();
22425
+ for (const ids of sourcesByTarget.values()) {
22426
+ for (const id of ids)
22427
+ allSourceIds.add(id);
22428
+ }
22429
+ // Batch-hydrate all related instances at once (1 findAll instead of N)
22430
+ const hydratedMap = new Map();
22431
+ if (allSourceIds.size > 0) {
22432
+ const fetchQuery = {
22433
+ where: {
22434
+ id: Array.from(allSourceIds),
22435
+ ...(subQuery?.where ?? {}),
22436
+ },
22437
+ ...(subQuery?.order && { order: subQuery.order }),
22438
+ ...(subQuery?.properties && { properties: subQuery.properties }),
22439
+ };
22440
+ try {
22441
+ const allResults = await TargetClass.findAll(perspective, fetchQuery);
22442
+ for (const r of allResults)
22443
+ hydratedMap.set(r.id, r);
22444
+ }
22445
+ catch {
22446
+ // Fallback: hydrate individually
22447
+ await Promise.all(Array.from(allSourceIds).map(async (sid) => {
22448
+ try {
22449
+ const related = new TargetClass(perspective, sid);
22450
+ await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
22451
+ hydratedMap.set(sid, related);
22452
+ }
22453
+ catch { /* skip */ }
22454
+ }));
22455
+ }
22456
+ }
22457
+ // Assign hydrated instances to each parent
21629
22458
  for (const inst of instances) {
21630
- const reverseLinks = await perspective.get(new exports.LinkQuery({ predicate: meta.predicate, target: inst.id }));
21631
- // Defensive filter: perspective.get may return extra results; ensure
21632
- // we only use links that genuinely point to this instance.
21633
- const sourceIds = reverseLinks
21634
- .filter(l => l.data.target === inst.id)
21635
- .map(l => l.data.source);
22459
+ const instId = inst.id;
22460
+ const sourceIds = sourcesByTarget.get(instId) ?? [];
21636
22461
  if (meta.kind === 'belongsToOne') {
21637
22462
  if (sourceIds.length === 0) {
21638
22463
  inst[relName] = null;
21639
22464
  continue;
21640
22465
  }
21641
22466
  const sourceId = sourceIds[sourceIds.length - 1]; // latest-wins
21642
- try {
21643
- const related = new TargetClass(perspective, sourceId);
21644
- await related.get();
21645
- inst[relName] = related;
21646
- }
21647
- catch {
21648
- inst[relName] = null;
21649
- }
22467
+ inst[relName] = hydratedMap.get(sourceId) ?? null;
21650
22468
  }
21651
22469
  else {
21652
22470
  // belongsToMany — return array of hydrated instances
21653
- let hydrated = [];
21654
- // If there's a where/order sub-query, delegate to findAll for filtering
21655
- if (subQuery && (subQuery.where || subQuery.order || subQuery.properties)) {
21656
- const whereWithIds = {
21657
- id: sourceIds,
21658
- ...(subQuery.where ?? {}),
21659
- };
21660
- hydrated = await TargetClass.findAll(perspective, {
21661
- where: whereWithIds,
21662
- ...(subQuery.order && { order: subQuery.order }),
21663
- ...(subQuery.properties && { properties: subQuery.properties }),
21664
- });
21665
- }
21666
- else {
21667
- await Promise.all(sourceIds.map(async (sid) => {
21668
- try {
21669
- const related = new TargetClass(perspective, sid);
21670
- await related.get(subQuery?.properties ? { properties: subQuery.properties } : undefined);
21671
- hydrated.push(related);
21672
- }
21673
- catch { /* skip */ }
21674
- }));
21675
- }
21676
- // Apply order (client-side, if not already handled by findAll above)
21677
- if (subQuery?.order && !(subQuery.where || subQuery.properties)) {
22471
+ let hydrated = sourceIds
22472
+ .map(sid => hydratedMap.get(sid))
22473
+ .filter((v) => v != null);
22474
+ // Apply order (client-side)
22475
+ if (subQuery?.order) {
21678
22476
  const orderEntries = Object.entries(subQuery.order);
21679
22477
  hydrated = hydrated.sort((a, b) => {
21680
22478
  for (const [field, dir] of orderEntries) {
@@ -22495,7 +23293,7 @@ class Ad4mModel {
22495
23293
  *
22496
23294
  * @internal
22497
23295
  */
22498
- static async instancesFromQueryResult(perspective, query, result) {
23296
+ static async instancesFromQueryResult(perspective, query, result, computeTotalCount = false) {
22499
23297
  if (!result || result.length === 0)
22500
23298
  return { results: [], totalCount: 0 };
22501
23299
  const metadata = this.getModelMetadata();
@@ -22560,18 +23358,38 @@ class Ad4mModel {
22560
23358
  }
22561
23359
  }));
22562
23360
  }
22563
- // Evaluate custom getters for all instances (single pass)
22564
- const getterOpts = requestedProperties.length > 0 || query.include
22565
- ? { requestedProperties, include: query.include }
22566
- : undefined;
22567
- for (const instance of instances) {
22568
- await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
23361
+ // Evaluate custom getters for all instances.
23362
+ // Relation getters (type-conformance filtering) always run — they ensure
23363
+ // correctness of @HasMany/@HasOne targets. Property getters only run when
23364
+ // deepQuery is true or when where conditions reference getter-backed properties.
23365
+ const whereGetterProperties = query.where
23366
+ ? Object.keys(query.where).filter((propName) => metadata.properties[propName]?.getter)
23367
+ : [];
23368
+ const shouldEvaluatePropertyGetters = query.deepQuery === true || whereGetterProperties.length > 0;
23369
+ {
23370
+ const skipPropertyGetters = !shouldEvaluatePropertyGetters;
23371
+ const getterRequestedProperties = shouldEvaluatePropertyGetters
23372
+ ? (requestedProperties.length > 0
23373
+ ? Array.from(new Set([...requestedProperties, ...whereGetterProperties]))
23374
+ : query.deepQuery === true
23375
+ ? [] // deepQuery: evaluate all getters
23376
+ : whereGetterProperties) // only evaluate where-referenced getters
23377
+ : [];
23378
+ const getterOpts = {
23379
+ ...(getterRequestedProperties.length > 0 && { requestedProperties: getterRequestedProperties }),
23380
+ ...(query.include && { include: query.include }),
23381
+ skipPropertyGetters,
23382
+ };
23383
+ for (const instance of instances) {
23384
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
23385
+ }
22569
23386
  }
22570
23387
  // Filter by where conditions that couldn't be filtered in SPARQL
22571
23388
  // This includes:
22572
23389
  // - author/timestamp (computed from grouped links)
22573
23390
  // - Properties with comparison operators (gt, gte, lt, lte, between, contains)
22574
- // because fn::parse_literal() comparisons in SPARQL subqueries don't work reliably
23391
+ // because <ad4m://fn/parse_literal>() returns strings, making numeric/date
23392
+ // comparisons unreliable. Equality, IN, and NOT are pushed to SPARQL.
22575
23393
  // - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
22576
23394
  // which require reverse-link resolution before filtering
22577
23395
  let filteredInstances = instances;
@@ -22597,9 +23415,9 @@ class Ad4mModel {
22597
23415
  }
22598
23416
  continue;
22599
23417
  }
22600
- // Filter ALL property conditions in JS (equality, NOT, IN, comparison operators).
22601
- // SPARQL-level filtering with parse_literal is unreliable across environments,
22602
- // so we do all property filtering here after hydration resolves values.
23418
+ // Filter ALL property conditions in JS (safety net).
23419
+ // Equality/IN/NOT are also filtered in SPARQL via <ad4m://fn/parse_literal>()
23420
+ // but JS re-validates after hydration resolves values.
22603
23421
  if (!matchesCondition(instance[propertyName], condition)) {
22604
23422
  return false;
22605
23423
  }
@@ -22611,7 +23429,7 @@ class Ad4mModel {
22611
23429
  // If limit/offset is used but no explicit order, default to ordering by timestamp (ASC)
22612
23430
  // This ensures consistent pagination behavior
22613
23431
  const effectiveOrder = query.order ||
22614
- (query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' } : null);
23432
+ (query.limit !== undefined || query.offset !== undefined ? { createdAt: 'ASC' } : null);
22615
23433
  if (effectiveOrder) {
22616
23434
  const orderEntries = Object.entries(effectiveOrder);
22617
23435
  filteredInstances.sort((a, b) => {
@@ -22644,11 +23462,37 @@ class Ad4mModel {
22644
23462
  return 0;
22645
23463
  });
22646
23464
  }
22647
- // Calculate totalCount BEFORE applying limit/offset
22648
- const totalCount = filteredInstances.length;
22649
- // Apply offset and limit in JavaScript
23465
+ // Determine if SPARQL already applied LIMIT/OFFSET (i.e., the pagination
23466
+ // subquery was used). When it was, skip JS-level slicing — instances are
23467
+ // already the correct page.
23468
+ const allRelsMeta2 = getRelationsMetadata(this);
23469
+ const sparqlPaginated = !hasJsOnlyWhereFilters(metadata, allRelsMeta2, query.where)
23470
+ && (query.limit !== undefined || query.offset !== undefined)
23471
+ && query.order !== undefined && Object.keys(query.order).length > 0;
23472
+ // Calculate totalCount BEFORE applying limit/offset.
23473
+ // When SPARQL already paginated, filteredInstances.length is the page size,
23474
+ // not the total — use a separate COUNT query for the real total.
23475
+ // Only run the COUNT query when the caller actually needs it (computeTotalCount=true).
23476
+ let totalCount;
23477
+ if (sparqlPaginated && computeTotalCount) {
23478
+ try {
23479
+ const countSparql = buildSPARQLCountQuery(metadata, allRelsMeta2, query, this);
23480
+ const countResult = await perspective.querySparql(countSparql);
23481
+ totalCount = parseSparqlCount(countResult) ?? filteredInstances.length;
23482
+ }
23483
+ catch {
23484
+ // Fallback: if count query fails, use what we have
23485
+ totalCount = filteredInstances.length;
23486
+ }
23487
+ }
23488
+ else {
23489
+ totalCount = filteredInstances.length;
23490
+ }
23491
+ // Apply offset and limit in JavaScript only when SPARQL didn't already paginate.
23492
+ // Subscription queries use unpaginated SPARQL, so JS must apply pagination.
23493
+ // Direct queries use SPARQL-level pagination, so JS slicing would double-apply.
22650
23494
  let paginatedInstances = filteredInstances;
22651
- if (query.offset !== undefined || query.limit !== undefined) {
23495
+ if (!sparqlPaginated && (query.offset !== undefined || query.limit !== undefined)) {
22652
23496
  const start = query.offset || 0;
22653
23497
  const end = query.limit ? start + query.limit : undefined;
22654
23498
  paginatedInstances = filteredInstances.slice(start, end);
@@ -22800,7 +23644,7 @@ class Ad4mModel {
22800
23644
  const sparqlQuery = await this.queryToSPARQL(perspective, query);
22801
23645
  const rawResult = await perspective.querySparql(sparqlQuery);
22802
23646
  const grouped = groupSPARQLResults(rawResult);
22803
- return await this.instancesFromQueryResult(perspective, query, grouped);
23647
+ return await this.instancesFromQueryResult(perspective, query, grouped, true);
22804
23648
  }
22805
23649
  else {
22806
23650
  const prologQuery = await this.queryToProlog(perspective, query);
@@ -22838,7 +23682,7 @@ class Ad4mModel {
22838
23682
  const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
22839
23683
  const rawResult = await perspective.querySparql(sparqlQuery);
22840
23684
  const grouped = groupSPARQLResults(rawResult);
22841
- const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped);
23685
+ const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped, true);
22842
23686
  return { results, totalCount, pageSize, pageNumber };
22843
23687
  }
22844
23688
  else {
@@ -22876,12 +23720,9 @@ class Ad4mModel {
22876
23720
  * @private
22877
23721
  */
22878
23722
  static async countQueryToSPARQL(perspective, query) {
22879
- // Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
22880
- // We'll count the number of rows returned (one row per source)
22881
- const countQuery = { ...query };
22882
- delete countQuery.limit;
22883
- delete countQuery.offset;
22884
- return await this.queryToSPARQL(perspective, countQuery);
23723
+ const metadata = this.getModelMetadata();
23724
+ const allRelMeta = getRelationsMetadata(this);
23725
+ return buildSPARQLCountQuery(metadata, allRelMeta, query, this);
22885
23726
  }
22886
23727
  /**
22887
23728
  * Gets a count of all matching instances.
@@ -22907,11 +23748,22 @@ class Ad4mModel {
22907
23748
  ? (engine ? 'sparql' : 'prolog')
22908
23749
  : engine;
22909
23750
  if (resolvedEngine === 'sparql') {
22910
- const sparqlQuery = await this.queryToSPARQL(perspective, query);
22911
- const rawResult = await perspective.querySparql(sparqlQuery);
22912
- const grouped = groupSPARQLResults(rawResult);
22913
- const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped);
22914
- return totalCount;
23751
+ // When query has JS-only where filters (gt, between, author, timestamp, etc.),
23752
+ // we must fall back to full hydration + JS filtering to get accurate count.
23753
+ const metadata = this.getModelMetadata();
23754
+ const allRelMeta = getRelationsMetadata(this);
23755
+ if (hasJsOnlyWhereFilters(metadata, allRelMeta, query.where)) {
23756
+ // Fall back to full query + JS filter path for accurate count
23757
+ const sparqlQuery = await this.queryToSPARQL(perspective, query);
23758
+ const rawResult = await perspective.querySparql(sparqlQuery);
23759
+ const grouped = groupSPARQLResults(rawResult);
23760
+ const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped, true);
23761
+ return totalCount;
23762
+ }
23763
+ // No JS-only filters — use efficient COUNT query
23764
+ const countSparql = await this.countQueryToSPARQL(perspective, query);
23765
+ const countResult = await perspective.querySparql(countSparql);
23766
+ return parseSparqlCount(countResult) ?? 0;
22915
23767
  }
22916
23768
  else {
22917
23769
  const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
@@ -23199,6 +24051,61 @@ class Ad4mModel {
23199
24051
  }
23200
24052
  }
23201
24053
  }
24054
+ /**
24055
+ * Evaluate SPARQL getters for a batch of instances on demand.
24056
+ *
24057
+ * Use after a shallow collection query (the default) to resolve
24058
+ * getter-backed properties for visible items only. This avoids the
24059
+ * O(N × getters) cost of evaluating every getter on every instance in
24060
+ * a large collection query.
24061
+ *
24062
+ * @param instances - Array of model instances to evaluate getters on
24063
+ * @param perspective - The perspective to query against
24064
+ * @param propertyNames - Optional list of getter-backed property names to evaluate.
24065
+ * If omitted, all getters are evaluated.
24066
+ *
24067
+ * @example
24068
+ * ```typescript
24069
+ * const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
24070
+ * // messages[i].replyingTo is undefined (getter skipped by default)
24071
+ *
24072
+ * // Evaluate getters for the visible subset
24073
+ * await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
24074
+ * // messages[0..9].replyingTo is now populated
24075
+ * ```
24076
+ */
24077
+ static async evaluateGetters(instances, perspective, propertyNames) {
24078
+ if (instances.length === 0)
24079
+ return;
24080
+ const metadata = this.getModelMetadata();
24081
+ const opts = propertyNames && propertyNames.length > 0
24082
+ ? { requestedProperties: propertyNames }
24083
+ : undefined;
24084
+ // Determine which property names will actually be evaluated
24085
+ const evaluatedPropertyNames = [];
24086
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
24087
+ if (propMeta.getter) {
24088
+ if (!propertyNames || propertyNames.length === 0 || propertyNames.includes(propName)) {
24089
+ evaluatedPropertyNames.push(propName);
24090
+ }
24091
+ }
24092
+ }
24093
+ for (const instance of instances) {
24094
+ await evaluateCustomGettersForInstance(instance, perspective, metadata, opts);
24095
+ // Sync snapshot so isDirty() doesn't flag getter-only changes.
24096
+ // evaluateGetters() mutates instances in place, but their snapshots
24097
+ // were already taken during hydration. Without this sync, the computed
24098
+ // getter values would make isDirty() return true and save() would try
24099
+ // to write read-only computed properties.
24100
+ const modelInstance = instance;
24101
+ if (modelInstance._snapshot) {
24102
+ for (const propName of evaluatedPropertyNames) {
24103
+ const val = instance[propName];
24104
+ modelInstance._snapshot[propName] = normalizeValue(Array.isArray(val) ? [...val] : val);
24105
+ }
24106
+ }
24107
+ }
24108
+ }
23202
24109
  /**
23203
24110
  * Gets the model instance with all properties and relations populated.
23204
24111
  *
@@ -25440,7 +26347,6 @@ exports.Ad4mModel = Ad4mModel;
25440
26347
  exports.AgentClient = AgentClient;
25441
26348
  exports.BelongsToMany = BelongsToMany;
25442
26349
  exports.BelongsToOne = BelongsToOne;
25443
- exports.Dna = Dna;
25444
26350
  exports.ExpressionGeneric = ExpressionGeneric;
25445
26351
  exports.ExpressionGenericInput = ExpressionGenericInput;
25446
26352
  exports.Flag = Flag;
@@ -25473,11 +26379,15 @@ exports.buildLimitQuery = buildLimitQuery;
25473
26379
  exports.buildModelFromJSONSchema = buildModelFromJSONSchema;
25474
26380
  exports.buildOffsetQuery = buildOffsetQuery;
25475
26381
  exports.buildOrderQuery = buildOrderQuery;
26382
+ exports.buildPaginationSubquery = buildPaginationSubquery;
25476
26383
  exports.buildParentQuery = buildParentQuery;
25477
26384
  exports.buildPropertiesQuery = buildPropertiesQuery;
25478
26385
  exports.buildSDNA = buildSDNA;
25479
26386
  exports.buildSHACL = buildSHACL;
26387
+ exports.buildSPARQLCountQuery = buildSPARQLCountQuery;
25480
26388
  exports.buildSPARQLGetDataQuery = buildSPARQLGetDataQuery;
26389
+ exports.buildSPARQLGroupedCountQuery = buildSPARQLGroupedCountQuery;
26390
+ exports.buildSPARQLOrderLimitOffset = buildSPARQLOrderLimitOffset;
25481
26391
  exports.buildSPARQLQuery = buildSPARQLQuery;
25482
26392
  exports.buildWhereCondition = buildWhereCondition;
25483
26393
  exports.buildWhereQuery = buildWhereQuery;
@@ -25501,6 +26411,7 @@ exports.getPropertiesMetadata = getPropertiesMetadata;
25501
26411
  exports.getPropertyOption = getPropertyOption;
25502
26412
  exports.getRelationsMetadata = getRelationsMetadata;
25503
26413
  exports.groupSPARQLResults = groupSPARQLResults;
26414
+ exports.hasJsOnlyWhereFilters = hasJsOnlyWhereFilters;
25504
26415
  exports.hydrateFromLinks = hydrateFromLinks;
25505
26416
  exports.hydratePropertyValue = hydratePropertyValue;
25506
26417
  exports.hydrateRelations = hydrateRelations;
@@ -25517,6 +26428,8 @@ exports.normalizeNamespaceString = normalizeNamespaceString;
25517
26428
  exports.normalizeSchemaType = normalizeSchemaType;
25518
26429
  exports.normalizeValue = normalizeValue;
25519
26430
  exports.parseExprUrl = parseExprUrl;
26431
+ exports.parseSparqlCount = parseSparqlCount;
26432
+ exports.parseSparqlGroupedCount = parseSparqlGroupedCount;
25520
26433
  exports.pooledSubscribe = pooledSubscribe;
25521
26434
  exports.queryCacheSize = queryCacheSize;
25522
26435
  exports.resolveParentPredicate = resolveParentPredicate;