@coasys/ad4m 0.13.0-test-4 → 0.13.0-test-6

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 (72) hide show
  1. package/lib/index.cjs +1507 -1372
  2. package/lib/index.js +1505 -1370
  3. package/lib/src/Ad4mClient.d.ts +1 -1
  4. package/lib/src/Ad4mClient.js +12 -1
  5. package/lib/src/agent/AgentClient.d.ts +16 -0
  6. package/lib/src/agent/AgentClient.js +74 -4
  7. package/lib/src/cache/PersistentCache.d.ts +40 -0
  8. package/lib/src/cache/PersistentCache.js +139 -0
  9. package/lib/src/expression/ExpressionClient.d.ts +8 -0
  10. package/lib/src/expression/ExpressionClient.js +113 -5
  11. package/lib/src/index.d.ts +1 -0
  12. package/lib/src/index.js +1 -0
  13. package/lib/src/model/Ad4mModel.d.ts +20 -7
  14. package/lib/src/model/Ad4mModel.js +102 -108
  15. package/lib/src/model/Ad4mModel.test.js +688 -1434
  16. package/lib/src/model/ModelQueryBuilder.d.ts +6 -6
  17. package/lib/src/model/ModelQueryBuilder.js +29 -20
  18. package/lib/src/model/Subject.js +6 -6
  19. package/lib/src/model/hydration.d.ts +2 -39
  20. package/lib/src/model/hydration.js +2 -260
  21. package/lib/src/model/query-surreal.d.ts +44 -0
  22. package/lib/src/model/query-surreal.js +249 -0
  23. package/lib/src/model/query-utils.d.ts +1 -0
  24. package/lib/src/model/query-utils.js +46 -1
  25. package/lib/src/model/relation-filtering.test.js +15 -15
  26. package/lib/src/model/surreal-utils.d.ts +42 -0
  27. package/lib/src/model/surreal-utils.js +128 -0
  28. package/lib/src/model/types.d.ts +4 -6
  29. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
  30. package/lib/src/perspectives/PerspectiveClient.js +15 -13
  31. package/lib/src/perspectives/PerspectiveProxy.d.ts +14 -0
  32. package/lib/src/perspectives/PerspectiveProxy.js +16 -3
  33. package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -0
  34. package/lib/src/perspectives/PerspectiveResolver.js +11 -0
  35. package/lib/src/runtime/RuntimeResolver.d.ts +1 -28
  36. package/lib/src/runtime/RuntimeResolver.js +4 -197
  37. package/lib/src/schema.gql +1 -27
  38. package/lib/src/shacl/SHACLShape.test.js +0 -82
  39. package/package.json +11 -8
  40. package/src/Ad4mClient.test.ts +14 -4
  41. package/src/Ad4mClient.ts +12 -1
  42. package/src/agent/AgentClient.ts +84 -2
  43. package/src/cache/PersistentCache.ts +145 -0
  44. package/src/cache/cache.test.ts +713 -0
  45. package/src/expression/ExpressionClient.ts +137 -3
  46. package/src/index.ts +1 -0
  47. package/src/model/Ad4mModel.test.ts +59 -358
  48. package/src/model/Ad4mModel.ts +112 -108
  49. package/src/model/ModelQueryBuilder.ts +29 -17
  50. package/src/model/hydration.ts +2 -279
  51. package/src/model/query-utils.ts +47 -2
  52. package/src/model/types.ts +5 -6
  53. package/src/perspectives/PerspectiveClient.ts +26 -17
  54. package/src/perspectives/PerspectiveProxy.ts +24 -3
  55. package/lib/src/model/hydration-batch.d.ts +0 -34
  56. package/lib/src/model/hydration-batch.js +0 -147
  57. package/lib/src/model/hydration-batching.test.d.ts +0 -7
  58. package/lib/src/model/hydration-batching.test.js +0 -456
  59. package/lib/src/model/model-manifest.d.ts +0 -41
  60. package/lib/src/model/model-manifest.js +0 -11
  61. package/lib/src/model/query-cache.test.d.ts +0 -1
  62. package/lib/src/model/query-cache.test.js +0 -43
  63. package/lib/src/model/query-sparql-batch.d.ts +0 -17
  64. package/lib/src/model/query-sparql-batch.js +0 -260
  65. package/lib/src/model/query-sparql.test.d.ts +0 -1
  66. package/lib/src/model/query-sparql.test.js +0 -312
  67. package/lib/src/model/subscription-delta.test.d.ts +0 -24
  68. package/lib/src/model/subscription-delta.test.js +0 -180
  69. package/lib/src/model/subscription-pool.d.ts +0 -39
  70. package/lib/src/model/subscription-pool.js +0 -165
  71. package/lib/src/perspectives/PerspectiveClient.test.d.ts +0 -1
  72. package/lib/src/perspectives/PerspectiveClient.test.js +0 -224
@@ -3,12 +3,11 @@ import { Link } from "../links/Links";
3
3
  import { LinkQuery } from "../perspectives/LinkQuery";
4
4
  import { makeRandomId } from "./util";
5
5
  import { getPropertiesMetadata, getRelationsMetadata, buildConformanceFilter, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
6
- import { compileWhereClause } from "./query-utils";
7
6
  import { resolveParentPredicate } from "./query-common";
8
7
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
9
8
  import { buildSPARQLQuery } from "./query-sparql";
10
9
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
11
- import { normalizeValue, evaluateCustomGettersForInstance, } from "./hydration";
10
+ import { normalizeValue, } from "./hydration";
12
11
  // ---------------------------------------------------------------------------
13
12
  // Helpers for Rust-side include resolution
14
13
  // ---------------------------------------------------------------------------
@@ -647,6 +646,7 @@ export class Ad4mModel {
647
646
  const query = {
648
647
  where: { id: this._baseExpression },
649
648
  limit: 1,
649
+ deepQuery: true, // Single-instance get() always evaluates property getters
650
650
  };
651
651
  if (opts?.properties)
652
652
  query.properties = opts.properties;
@@ -755,11 +755,16 @@ export class Ad4mModel {
755
755
  queryInput.limit = query.limit;
756
756
  if (query.count !== undefined)
757
757
  queryInput.count = query.count;
758
+ queryInput.deepQuery = query.deepQuery ?? true;
758
759
  if (query.include) {
759
760
  const allRelMeta = getRelationsMetadata(this);
760
761
  enrichShapeForIncludes(metadata, query.include, allRelMeta);
761
762
  }
762
- // Pre-compute conformance getters (with where-clause support)
763
+ // Pre-compute conformance getters for Rust-side evaluation.
764
+ // Where clauses are NOT compiled into getter SPARQL because stored
765
+ // property values are signed expression envelopes (literal:json:...),
766
+ // not simple literal:string:X values. Instead, where clauses are
767
+ // attached as metadata for Rust-side post-evaluation filtering.
763
768
  {
764
769
  const allRelMeta = getRelationsMetadata(this);
765
770
  for (const [relName, relMeta] of Object.entries(metadata.relations)) {
@@ -772,46 +777,31 @@ export class Ad4mModel {
772
777
  try {
773
778
  const TargetClass = meta.target();
774
779
  const filter = buildConformanceFilter(meta.predicate, TargetClass);
775
- // Only compile where clauses to SPARQL when the target properties
776
- // are stored as plain IRIs (not signed expressions). Properties
777
- // without resolveLanguage or with resolveLanguage='literal' store
778
- // values as signed JSON envelopes, so SPARQL exact-match fails.
779
- let whereConditions = [];
780
+ if (filter) {
781
+ rel.getter = filter.getter;
782
+ }
783
+ // Attach where-clause metadata for Rust-side post-getter filtering
780
784
  if (rel.where) {
781
785
  try {
782
786
  const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
783
- let allSparqlFilterable = true;
784
787
  if (targetMetadata) {
788
+ const predicates = {};
785
789
  for (const propName of Object.keys(rel.where)) {
786
790
  if (['id', 'author', 'timestamp'].includes(propName))
787
791
  continue;
788
792
  const propMeta = targetMetadata.properties[propName];
789
- if (propMeta && (!propMeta.resolveLanguage || propMeta.resolveLanguage === 'literal')) {
790
- allSparqlFilterable = false;
791
- break;
793
+ if (propMeta?.predicate) {
794
+ predicates[propName] = propMeta.predicate;
792
795
  }
793
796
  }
794
- }
795
- else {
796
- allSparqlFilterable = false;
797
- }
798
- if (allSparqlFilterable) {
799
- whereConditions = compileWhereClause(rel.where, targetMetadata);
797
+ if (Object.keys(predicates).length > 0) {
798
+ rel.whereFilter = rel.where;
799
+ rel.wherePredicates = predicates;
800
+ }
800
801
  }
801
802
  }
802
803
  catch (_) { }
803
804
  }
804
- if (filter) {
805
- let getter = filter.getter;
806
- if (whereConditions.length > 0) {
807
- getter = getter.replace(/ \}$/, ` ${whereConditions.join(' ')} }`);
808
- }
809
- rel.getter = getter;
810
- }
811
- else if (whereConditions.length > 0) {
812
- const escapedPred = meta.predicate.replace(/[<>"{}|\\^`\u0000-\u0020]/g, '');
813
- rel.getter = `SELECT ?target WHERE { <Base> <${escapedPred}> ?target . ${whereConditions.join(' ')} }`;
814
- }
815
805
  }
816
806
  catch (_) { }
817
807
  }
@@ -914,6 +904,7 @@ export class Ad4mModel {
914
904
  queryInput.limit = query.limit;
915
905
  if (query.count !== undefined)
916
906
  queryInput.count = query.count;
907
+ queryInput.deepQuery = query.deepQuery ?? true;
917
908
  // Enrich relation metadata with target class shapes for Rust-side
918
909
  // include resolution. This eliminates per-relation GraphQL round-trips
919
910
  // by letting the Rust endpoint resolve includes in-process.
@@ -943,48 +934,33 @@ export class Ad4mModel {
943
934
  try {
944
935
  const TargetClass = meta.target();
945
936
  const filter = buildConformanceFilter(meta.predicate, TargetClass);
946
- // Only compile where clauses to SPARQL when the target properties
947
- // are stored as plain IRIs (not signed expressions). Properties
948
- // without resolveLanguage or with resolveLanguage='literal' store
949
- // values as signed JSON envelopes, so SPARQL exact-match fails.
950
- let whereConditions = [];
937
+ if (filter) {
938
+ rel.getter = filter.getter;
939
+ }
940
+ // Attach where-clause metadata for Rust-side post-getter filtering.
941
+ // Property values are signed expression envelopes (literal:json:...)
942
+ // and cannot be matched by SPARQL FILTER on the raw IRI.
951
943
  if (rel.where) {
952
944
  try {
953
945
  const targetMetadata = TargetClass.getModelMetadata?.() ?? null;
954
- let allSparqlFilterable = true;
955
946
  if (targetMetadata) {
947
+ const predicates = {};
956
948
  for (const propName of Object.keys(rel.where)) {
957
949
  if (['id', 'author', 'timestamp'].includes(propName))
958
950
  continue;
959
951
  const propMeta = targetMetadata.properties[propName];
960
- if (propMeta && (!propMeta.resolveLanguage || propMeta.resolveLanguage === 'literal')) {
961
- allSparqlFilterable = false;
962
- break;
952
+ if (propMeta?.predicate) {
953
+ predicates[propName] = propMeta.predicate;
963
954
  }
964
955
  }
965
- }
966
- else {
967
- allSparqlFilterable = false;
968
- }
969
- if (allSparqlFilterable) {
970
- whereConditions = compileWhereClause(rel.where, targetMetadata);
956
+ if (Object.keys(predicates).length > 0) {
957
+ rel.whereFilter = rel.where;
958
+ rel.wherePredicates = predicates;
959
+ }
971
960
  }
972
961
  }
973
962
  catch (_) { /* target metadata unavailable */ }
974
963
  }
975
- if (filter) {
976
- let getter = filter.getter;
977
- if (whereConditions.length > 0) {
978
- // Append where conditions before the closing }
979
- getter = getter.replace(/ \}$/, ` ${whereConditions.join(' ')} }`);
980
- }
981
- rel.getter = getter;
982
- }
983
- else if (whereConditions.length > 0) {
984
- // No conformance filter but where clause exists — build getter from where alone
985
- const escapedPred = meta.predicate.replace(/[<>"{}|\\^`\u0000-\u0020]/g, '');
986
- rel.getter = `SELECT ?target WHERE { <Base> <${escapedPred}> ?target . ${whereConditions.join(' ')} }`;
987
- }
988
964
  }
989
965
  catch (e) {
990
966
  // Target class may not be available; skip silently
@@ -1032,40 +1008,6 @@ export class Ad4mModel {
1032
1008
  }
1033
1009
  }));
1034
1010
  }
1035
- // Relation conformance getters are evaluated Rust-side via evaluate_getters()
1036
- // in model_query.rs. However, for relations with non-SPARQL-filterable where
1037
- // clauses (e.g. properties stored as signed expressions), we still need
1038
- // TS-side evaluation as a fallback. Running evaluateCustomGettersForInstance
1039
- // with skipPropertyGetters ensures conformance + JS post-filtering for
1040
- // where clauses that couldn't be compiled to SPARQL.
1041
- const includedRelNames = queryInput.include ? new Set(Object.keys(queryInput.include)) : new Set();
1042
- for (const inst of instances) {
1043
- // Save included relation values that came from Rust hydration
1044
- const savedIncluded = {};
1045
- for (const relName of includedRelNames) {
1046
- if (inst[relName] !== undefined) {
1047
- savedIncluded[relName] = inst[relName];
1048
- }
1049
- }
1050
- await evaluateCustomGettersForInstance(inst, perspective, metadata, {
1051
- skipPropertyGetters: true,
1052
- });
1053
- // Restore hydrated include objects that were overwritten by conformance getters
1054
- for (const [relName, value] of Object.entries(savedIncluded)) {
1055
- inst[relName] = value;
1056
- }
1057
- // Fix cardinality for non-included HasOne/BelongsToOne relations:
1058
- // The conformance getter always produces arrays; unwrap to scalar.
1059
- for (const [relName, relMeta] of Object.entries(metadata.relations)) {
1060
- if (includedRelNames.has(relName))
1061
- continue;
1062
- const kind = relMeta.kind;
1063
- if ((kind === 'hasOne' || kind === 'belongsToOne') && Array.isArray(inst[relName])) {
1064
- const arr = inst[relName];
1065
- inst[relName] = arr.length > 0 ? arr[0] : null;
1066
- }
1067
- }
1068
- }
1069
1011
  // Take snapshots for dirty tracking
1070
1012
  const snapshotRelations = queryInput.include;
1071
1013
  for (const inst of instances) {
@@ -1493,10 +1435,10 @@ export class Ad4mModel {
1493
1435
  /**
1494
1436
  * Evaluate SPARQL getters for a batch of instances on demand.
1495
1437
  *
1496
- * Use after a shallow collection query (the default) to resolve
1497
- * getter-backed properties for visible items only. This avoids the
1498
- * O(N × getters) cost of evaluating every getter on every instance in
1499
- * a large collection query.
1438
+ * Since deepQuery defaults to true, property getters are evaluated
1439
+ * automatically during collection queries. Use this method when
1440
+ * deepQuery was explicitly set to false and you want to lazily
1441
+ * resolve getter-backed properties for a subset of instances.
1500
1442
  *
1501
1443
  * @param instances - Array of model instances to evaluate getters on
1502
1444
  * @param perspective - The perspective to query against
@@ -1505,8 +1447,8 @@ export class Ad4mModel {
1505
1447
  *
1506
1448
  * @example
1507
1449
  * ```typescript
1508
- * const messages = await Message.findAll(perspective, { parent: channel, limit: 30 });
1509
- * // messages[i].replyingTo is undefined (getter skipped by default)
1450
+ * const messages = await Message.query(perspective).deepQuery(false).limit(30).get();
1451
+ * // messages[i].replyingTo is undefined (getter skipped)
1510
1452
  *
1511
1453
  * // Evaluate getters for the visible subset
1512
1454
  * await Message.evaluateGetters(messages.slice(0, 10), perspective, ['replyingTo']);
@@ -1517,10 +1459,28 @@ export class Ad4mModel {
1517
1459
  if (instances.length === 0)
1518
1460
  return;
1519
1461
  const metadata = this.getModelMetadata();
1520
- const opts = propertyNames && propertyNames.length > 0
1521
- ? { requestedProperties: propertyNames }
1522
- : undefined;
1523
- // Determine which property names will actually be evaluated
1462
+ // Pre-compute conformance getters so the shape sent to Rust includes them
1463
+ const allRelMeta = getRelationsMetadata(this);
1464
+ for (const [relName, relMeta] of Object.entries(metadata.relations)) {
1465
+ const rel = relMeta;
1466
+ if (rel.getter || rel.direction === 'reverse' || rel.filter === false)
1467
+ continue;
1468
+ const meta = allRelMeta[relName];
1469
+ if (!meta?.target)
1470
+ continue;
1471
+ try {
1472
+ const TargetClass = meta.target();
1473
+ const filter = buildConformanceFilter(meta.predicate, TargetClass);
1474
+ if (filter)
1475
+ rel.getter = filter.getter;
1476
+ }
1477
+ catch (_) { /* target class may not be available */ }
1478
+ }
1479
+ const shapeJson = JSON.stringify(metadata);
1480
+ const instanceIds = instances.map(inst => inst.id || inst._baseExpression);
1481
+ // Single RPC call evaluates all getters in-process on the executor
1482
+ const result = await perspective.evaluateGetters(metadata.className, instanceIds, shapeJson, propertyNames);
1483
+ // Determine which property names were evaluated for snapshot sync
1524
1484
  const evaluatedPropertyNames = [];
1525
1485
  for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1526
1486
  if (propMeta.getter) {
@@ -1529,13 +1489,24 @@ export class Ad4mModel {
1529
1489
  }
1530
1490
  }
1531
1491
  }
1492
+ // Also include relation getters
1493
+ for (const [relName, relMeta] of Object.entries(metadata.relations)) {
1494
+ if (relMeta.getter) {
1495
+ if (!propertyNames || propertyNames.length === 0 || propertyNames.includes(relName)) {
1496
+ evaluatedPropertyNames.push(relName);
1497
+ }
1498
+ }
1499
+ }
1500
+ // Apply results to instances and sync snapshots
1532
1501
  for (const instance of instances) {
1533
- await evaluateCustomGettersForInstance(instance, perspective, metadata, opts);
1534
- // Sync snapshot so isDirty() doesn't flag getter-only changes.
1535
- // evaluateGetters() mutates instances in place, but their snapshots
1536
- // were already taken during hydration. Without this sync, the computed
1537
- // getter values would make isDirty() return true and save() would try
1538
- // to write read-only computed properties.
1502
+ const id = instance.id || instance._baseExpression;
1503
+ const props = result[id];
1504
+ if (props) {
1505
+ for (const [key, value] of Object.entries(props)) {
1506
+ instance[key] = value;
1507
+ }
1508
+ }
1509
+ // Sync snapshot so isDirty() doesn't flag getter-only changes
1539
1510
  const modelInstance = instance;
1540
1511
  if (modelInstance._snapshot) {
1541
1512
  for (const propName of evaluatedPropertyNames) {
@@ -1936,7 +1907,20 @@ export class Ad4mModel {
1936
1907
  * @param name - Class name to assign (e.g. "Channel")
1937
1908
  * @returns Generated Ad4mModel subclass, ready for querying
1938
1909
  */
1939
- static fromSHACL(shape, name) {
1910
+ /**
1911
+ * Synthesise an `Ad4mModel` subclass from a SHACL shape.
1912
+ *
1913
+ * @param shape - The SHACL shape to synthesise from.
1914
+ * @param name - The model name (e.g. "Channel").
1915
+ * @param classResolver - Optional thunk factory. When provided, any collection
1916
+ * property that carries a `sh:class` URI will have its `target` wired up lazily:
1917
+ * `target: () => classResolver(localName)`. Because `target` is only called at
1918
+ * query time (inside `enrichShapeForIncludes` / `jsonToModelInstance`), the
1919
+ * resolver just needs to return the correct class by the time a query runs —
1920
+ * making it safe to pass a closure over a registry object that is still being
1921
+ * populated (e.g. the `result` record inside `getModelClasses`).
1922
+ */
1923
+ static fromSHACL(shape, name, classResolver) {
1940
1924
  const DynamicModelClass = class extends this {
1941
1925
  };
1942
1926
  DynamicModelClass.className = name;
@@ -1975,9 +1959,19 @@ export class Ad4mModel {
1975
1959
  continue;
1976
1960
  const isCollection = prop.maxCount === undefined || prop.maxCount > 1;
1977
1961
  if (isCollection) {
1962
+ // Derive a lazy `target` thunk when a sh:class URI is present and a
1963
+ // classResolver was supplied. The thunk is evaluated at query time so
1964
+ // it is safe even if the target class hasn't been registered yet.
1965
+ let targetThunk;
1966
+ if (prop.class && classResolver) {
1967
+ const sep = Math.max(prop.class.lastIndexOf('#'), prop.class.lastIndexOf('/'));
1968
+ const localName = sep >= 0 ? prop.class.slice(sep + 1) : prop.class;
1969
+ targetThunk = () => classResolver(localName);
1970
+ }
1978
1971
  setRelationRegistryEntry(DynamicModelClass, prop.name, {
1979
1972
  predicate: prop.path,
1980
1973
  kind: 'hasMany',
1974
+ ...(targetThunk !== undefined && { target: targetThunk }),
1981
1975
  ...(prop.local !== undefined && { local: prop.local }),
1982
1976
  ...(prop.getter !== undefined && { getter: prop.getter }),
1983
1977
  });