@coasys/ad4m 0.13.1-staging.13 → 0.13.1-staging.15

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 (75) hide show
  1. package/lib/index.cjs +571 -480
  2. package/lib/index.js +571 -476
  3. package/lib/src/agent/AgentClient.d.ts +9 -8
  4. package/lib/src/agent/AgentClient.js +46 -67
  5. package/lib/src/cache/KeyedCache.d.ts +51 -0
  6. package/lib/src/cache/KeyedCache.js +142 -0
  7. package/lib/src/expression/ExpressionClient.d.ts +14 -3
  8. package/lib/src/expression/ExpressionClient.js +49 -111
  9. package/lib/src/generated/api/ExpressionLookupError.d.ts +7 -0
  10. package/lib/src/generated/api/ExpressionLookupError.js +2 -0
  11. package/lib/src/generated/api/ExpressionManyEntry.d.ts +6 -0
  12. package/lib/src/generated/api/ExpressionManyEntry.js +1 -0
  13. package/lib/src/generated/api/FlowFiredEntry.d.ts +11 -0
  14. package/lib/src/generated/api/FlowFiredEntry.js +2 -0
  15. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +3 -3
  16. package/lib/src/generated/api/RpcMethods.d.ts +4 -2
  17. package/lib/src/model/Ad4mModel.d.ts +26 -2
  18. package/lib/src/model/Ad4mModel.js +127 -83
  19. package/lib/src/model/ModelQueryBuilder.d.ts +3 -0
  20. package/lib/src/model/ModelQueryBuilder.js +42 -14
  21. package/lib/src/model/index.d.ts +0 -1
  22. package/lib/src/model/index.js +0 -1
  23. package/lib/src/model/query-common.d.ts +8 -0
  24. package/lib/src/model/query-common.js +12 -0
  25. package/lib/src/model/shacl-gen.js +2 -0
  26. package/lib/src/model/types.d.ts +12 -3
  27. package/lib/src/neighbourhood/SfuManager.d.ts +8 -1
  28. package/lib/src/neighbourhood/SfuManager.js +9 -2
  29. package/lib/src/perspectives/FlowModels.js +1 -1
  30. package/lib/src/perspectives/LiveQuery.d.ts +1 -1
  31. package/lib/src/perspectives/PerspectiveClient.d.ts +17 -6
  32. package/lib/src/perspectives/PerspectiveClient.js +83 -44
  33. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -10
  34. package/lib/src/perspectives/PerspectiveProxy.js +31 -69
  35. package/lib/src/shacl/SHACLShape.d.ts +4 -0
  36. package/lib/src/shacl/SHACLShape.js +10 -0
  37. package/package.json +2 -2
  38. package/src/Ad4mClient.test.ts +17 -6
  39. package/src/agent/AgentClient.ts +46 -74
  40. package/src/cache/KeyedCache.test.ts +162 -0
  41. package/src/cache/KeyedCache.ts +179 -0
  42. package/src/cache/cache.test.ts +294 -71
  43. package/src/expression/ExpressionClient.ts +46 -131
  44. package/src/generated/api/ExpressionLookupError.ts +6 -0
  45. package/src/generated/api/ExpressionManyEntry.ts +8 -0
  46. package/src/generated/api/FlowFiredEntry.ts +11 -0
  47. package/src/generated/api/PerspectiveFlowFiredParams.ts +3 -3
  48. package/src/generated/api/RpcMethods.ts +4 -2
  49. package/src/model/Ad4mModel.test.ts +237 -43
  50. package/src/model/Ad4mModel.ts +134 -99
  51. package/src/model/ModelQueryBuilder.ts +41 -15
  52. package/src/model/count-result-type.test.ts +72 -0
  53. package/src/model/index.ts +0 -1
  54. package/src/model/query-common.ts +13 -0
  55. package/src/model/relation-filtering.test.ts +3 -5
  56. package/src/model/shacl-gen.ts +1 -0
  57. package/src/model/shacl-roundtrip.test.ts +28 -0
  58. package/src/model/types.ts +9 -3
  59. package/src/model/write-round-trips.test.ts +30 -6
  60. package/src/neighbourhood/SfuManager.test.ts +57 -5
  61. package/src/neighbourhood/SfuManager.ts +10 -2
  62. package/src/perspectives/FlowModels.ts +1 -1
  63. package/src/perspectives/LiveQuery.ts +1 -1
  64. package/src/perspectives/PerspectiveClient.test.ts +287 -0
  65. package/src/perspectives/PerspectiveClient.ts +101 -66
  66. package/src/perspectives/PerspectiveProxy.test.ts +6 -14
  67. package/src/perspectives/PerspectiveProxy.ts +33 -67
  68. package/src/perspectives/TextContent.test.ts +0 -16
  69. package/src/perspectives/shacl-rpc.test.ts +1 -1
  70. package/src/shacl/SHACLShape.test.ts +21 -0
  71. package/src/shacl/SHACLShape.ts +16 -0
  72. package/lib/src/model/query-cache.d.ts +0 -30
  73. package/lib/src/model/query-cache.js +0 -66
  74. package/src/model/query-cache.test.ts +0 -54
  75. package/src/model/query-cache.ts +0 -79
@@ -7,7 +7,7 @@ import { makeRandomId } from "./util";
7
7
  import { getPropertiesMetadata, getRelationsMetadata, setPropertyRegistryEntry, setRelationRegistryEntry, Model } from "./decorators";
8
8
  import type { PropertyOptions, PropertyMetadataEntry, RelationMetadataEntry } from "./decorators";
9
9
  import { formatQueryValue, compileWhereClause } from "./query-utils";
10
- import { requireSingleParent, resolveParentPredicate } from "./query-common";
10
+ import { requireSingleParent, requireTotalCount, resolveParentPredicate } from "./query-common";
11
11
  import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
12
12
  import type { SHACLShape } from "../shacl/SHACLShape";
13
13
  import type { JSONSchemaProperty, JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
@@ -19,7 +19,7 @@ import {
19
19
  } from "./hydration";
20
20
  import type {
21
21
  Scope, TraverseScope, IncludeMap, Query,
22
- GetOptions, AllInstancesResult, ResultsWithTotalCount,
22
+ GetOptions, AllInstancesResult, Page, ResultsWithTotalCount,
23
23
  PaginationResult, PropertyMetadata, RelationMetadata, ModelMetadata,
24
24
  IncludeProjection,
25
25
  TypedQuery, IncludeExtras, IncludeOf, LinksMap,
@@ -73,7 +73,8 @@ const SUBJECT_CLASS_KEY = '__subjectClass';
73
73
  * The walk stops descending *through* a polymorphic relation, because there is
74
74
  * nothing to descend into: its targets are of several classes by definition, so
75
75
  * no single class's metadata could say what a deeper include means. The
76
- * executor resolves those nested includes against each concrete class instead.
76
+ * executor applies each concrete class's declared default from its shape
77
+ * (`ad4m://polymorphic`) to those nested includes instead.
77
78
  */
78
79
  function applyPolymorphicIncludeDefaults(includes: IncludeMap, ctor: Function): void {
79
80
  const relMeta = getRelationsMetadata(ctor);
@@ -373,6 +374,14 @@ function jsonToModelInstance<T extends Ad4mModel>(
373
374
  return instance;
374
375
  }
375
376
 
377
+ /** One field write: the commands and parameters of one `executeAction`. */
378
+ interface FieldWrite {
379
+ commands: any[];
380
+ parameters: { name: string; value: any }[];
381
+ }
382
+
383
+ /** The most writes `sendWrites` joins into one `executeAction` call. */
384
+ const MAX_WRITES_PER_CALL = 200;
376
385
 
377
386
  /**
378
387
  * Put `childId` under `parent`. A containment scope `{ id }` writes through the
@@ -1367,7 +1376,7 @@ export class Ad4mModel {
1367
1376
  classes: (typeof Ad4mModel)[],
1368
1377
  query: Query = {},
1369
1378
  options?: CallOptions,
1370
- ): Promise<ResultsWithTotalCount<Ad4mModel>> {
1379
+ ): Promise<Page<Ad4mModel>> {
1371
1380
  const { classNames, queryJson } = Ad4mModel.prepareUnionQueryParams(classes, query);
1372
1381
  const result = await perspective.modelQuery(classNames, queryJson, options);
1373
1382
  const results = Ad4mModel.parseUnionResult(classes, perspective, result, query.include, query.properties);
@@ -1446,7 +1455,7 @@ export class Ad4mModel {
1446
1455
  query: Query = {},
1447
1456
  classNameOverride?: string | null,
1448
1457
  options?: CallOptions,
1449
- ): Promise<ResultsWithTotalCount<T>> {
1458
+ ): Promise<Page<T>> {
1450
1459
  // Delegate query input building to the shared prepareModelQueryParams
1451
1460
  // helper. The executor resolves the shape from SHACL server-side.
1452
1461
  const { className, queryJson } = this.prepareModelQueryParams(
@@ -1561,8 +1570,8 @@ export class Ad4mModel {
1561
1570
  query?: Q,
1562
1571
  options?: CallOptions,
1563
1572
  ): Promise<ResultsWithTotalCount<T & IncludeExtras<T, IncludeOf<Q>>>> {
1564
- const out = await this.executeModelQuery(perspective, (query ?? {}) as Query, undefined, options);
1565
- return out as ResultsWithTotalCount<T & IncludeExtras<T, IncludeOf<Q>>>;
1573
+ const answer = await this.executeModelQuery(perspective, { ...((query ?? {}) as Query), count: true }, undefined, options);
1574
+ return { results: answer.results as (T & IncludeExtras<T, IncludeOf<Q>>)[], totalCount: requireTotalCount(answer) };
1566
1575
  }
1567
1576
 
1568
1577
  /**
@@ -1591,8 +1600,8 @@ export class Ad4mModel {
1591
1600
  options?: CallOptions,
1592
1601
  ): Promise<PaginationResult<T & IncludeExtras<T, IncludeOf<Q>>>> {
1593
1602
  const paginationQuery = { ...((query ?? {}) as Query), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
1594
- const { results, totalCount } = await this.executeModelQuery(perspective, paginationQuery, undefined, options);
1595
- return { results: results as (T & IncludeExtras<T, IncludeOf<Q>>)[], totalCount, pageSize, pageNumber };
1603
+ const answer = await this.executeModelQuery(perspective, paginationQuery, undefined, options);
1604
+ return { results: answer.results as (T & IncludeExtras<T, IncludeOf<Q>>)[], totalCount: requireTotalCount(answer), pageSize, pageNumber };
1596
1605
  }
1597
1606
 
1598
1607
  /**
@@ -1627,15 +1636,15 @@ export class Ad4mModel {
1627
1636
  query?: TypedQuery<T>,
1628
1637
  options?: CallOptions,
1629
1638
  ): Promise<number> {
1630
- const { totalCount } = await this.executeModelQuery(perspective, { ...((query ?? {}) as Query), limit: 0 }, undefined, options);
1631
- return totalCount;
1639
+ return requireTotalCount(await this.executeModelQuery(perspective, { ...((query ?? {}) as Query), limit: 0, count: true }, undefined, options));
1632
1640
  }
1633
1641
 
1634
- private async setProperty(key: string, value: any, batchId?: string) {
1642
+ /** The `executeAction` write that sets property `key` to `value`; none for an empty value. */
1643
+ private async planProperty(key: string, value: any): Promise<FieldWrite[]> {
1635
1644
  const metadata = this.getPropertyMetadata(key);
1636
1645
  if (!metadata) {
1637
1646
  console.warn(`Property "${key}" has no metadata, skipping`);
1638
- return;
1647
+ return [];
1639
1648
  }
1640
1649
 
1641
1650
  // Generate actions from metadata (replaces Prolog query)
@@ -1643,7 +1652,7 @@ export class Ad4mModel {
1643
1652
 
1644
1653
  // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
1645
1654
  if (value === undefined || value === null || value === "") {
1646
- return;
1655
+ return [];
1647
1656
  }
1648
1657
 
1649
1658
  const mode = effectiveLiteralStorage(metadata);
@@ -1658,7 +1667,76 @@ export class Ad4mModel {
1658
1667
  value = valueToLiteralIri(value);
1659
1668
  }
1660
1669
 
1661
- await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
1670
+ return [{ commands: actions, parameters: [{ name: "value", value }] }];
1671
+ }
1672
+
1673
+ /**
1674
+ * The `executeAction` writes of a relation change: one for a set (its
1675
+ * `collectionSetter` takes every value), one per value for an add or remove.
1676
+ */
1677
+ private planRelation(key: string, kind: 'setter' | 'adder' | 'remover', value: any): FieldWrite[] {
1678
+ const metadata = this.getRelationOptions(key);
1679
+ if (!metadata) {
1680
+ console.warn(`Relation "${key}" has no metadata, skipping`);
1681
+ return [];
1682
+ }
1683
+
1684
+ // Generate actions from metadata (replaces Prolog query)
1685
+ const actions = this.generateRelationAction(key, kind);
1686
+
1687
+ if (value == null) return [];
1688
+ const values = Array.isArray(value) ? value : [value];
1689
+ const param = (v: any) => ({ name: "value", value: this.resolveRelationId(v) });
1690
+ if (kind === 'setter') return [{ commands: actions, parameters: values.map(param) }];
1691
+ return values.map(v => ({ commands: actions, parameters: [param(v)] }));
1692
+ }
1693
+
1694
+ /**
1695
+ * Sends writes in as few `executeAction` calls as keep their links: the
1696
+ * executor runs a call's commands in order, so consecutive writes share one
1697
+ * call, each with its own parameter names. A `collectionSetter` takes every
1698
+ * parameter of its call as a member, so it goes in a call of its own. A
1699
+ * command's `local` flag is per command, so Local and Shared links mix. The
1700
+ * executor tries every parameter name at each position of each command, so
1701
+ * a call holds at most `MAX_WRITES_PER_CALL` writes.
1702
+ */
1703
+ private async sendWrites(writes: FieldWrite[], batchId?: string): Promise<void> {
1704
+ let group: FieldWrite[] = [];
1705
+ const flush = async () => {
1706
+ if (group.length === 1) {
1707
+ await this._perspective.executeAction(group[0].commands, this._baseExpression, group[0].parameters, batchId);
1708
+ } else if (group.length > 1) {
1709
+ const commands: any[] = [];
1710
+ const parameters: { name: string; value: any }[] = [];
1711
+ group.forEach((write, i) => {
1712
+ // The executor substitutes a parameter name wherever it occurs in a
1713
+ // command's source, predicate or target; rename `value` the same way.
1714
+ const name = `ad4m-model-write-${i}-value`;
1715
+ const rename = (s: any) => (typeof s === "string" && write.parameters.length ? s.split("value").join(name) : s);
1716
+ for (const c of write.commands) {
1717
+ commands.push({ ...c, source: rename(c.source), predicate: rename(c.predicate), target: rename(c.target) });
1718
+ }
1719
+ for (const p of write.parameters) parameters.push({ name, value: p.value });
1720
+ });
1721
+ await this._perspective.executeAction(commands, this._baseExpression, parameters, batchId);
1722
+ }
1723
+ group = [];
1724
+ };
1725
+ for (const write of writes) {
1726
+ if (write.commands.some((c: any) => c.action === "collectionSetter")) {
1727
+ await flush();
1728
+ group = [write];
1729
+ await flush();
1730
+ } else {
1731
+ group.push(write);
1732
+ if (group.length >= MAX_WRITES_PER_CALL) await flush();
1733
+ }
1734
+ }
1735
+ await flush();
1736
+ }
1737
+
1738
+ private async setProperty(key: string, value: any, batchId?: string) {
1739
+ await this.sendWrites(await this.planProperty(key, value), batchId);
1662
1740
  }
1663
1741
 
1664
1742
  /** Resolve a relation argument to a plain string ID. Accepts either a raw
@@ -1685,90 +1763,34 @@ export class Ad4mModel {
1685
1763
  }
1686
1764
 
1687
1765
  private async setRelationValues(key: string, value: any, batchId?: string) {
1688
- const metadata = this.getRelationOptions(key);
1689
- if (!metadata) {
1690
- console.warn(`Relation "${key}" has no metadata, skipping`);
1691
- return;
1692
- }
1693
- this._relationsWritten.add(metadata.predicate);
1694
- const abstractName = this.abstractName();
1695
- if (abstractName) {
1696
- if (value != null) await this.relationThroughAbstract(abstractName, key, 'setter', value, batchId);
1697
- return;
1698
- }
1699
-
1700
- // Generate actions from metadata (replaces Prolog query)
1701
- const actions = this.generateRelationAction(key, 'setter');
1702
-
1703
- if (value != null) {
1704
- if (Array.isArray(value)) {
1705
- await this._perspective.executeAction(
1706
- actions,
1707
- this._baseExpression,
1708
- value.map((v) => ({ name: "value", value: this.resolveRelationId(v) })),
1709
- batchId
1710
- );
1711
- } else {
1712
- await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
1713
- }
1714
- }
1766
+ await this.writeRelation(key, 'setter', value, batchId);
1715
1767
  }
1716
1768
 
1717
1769
  private async addRelationValue(key: string, value: any, batchId?: string) {
1718
- const metadata = this.getRelationOptions(key);
1719
- if (!metadata) {
1720
- console.warn(`Relation "${key}" has no metadata, skipping`);
1721
- return;
1722
- }
1723
- this._relationsWritten.add(metadata.predicate);
1724
- const abstractName = this.abstractName();
1725
- if (abstractName) {
1726
- if (value != null) await this.relationThroughAbstract(abstractName, key, 'adder', value, batchId);
1727
- return;
1728
- }
1729
-
1730
- // Generate actions from metadata (replaces Prolog query)
1731
- const actions = this.generateRelationAction(key, 'adder');
1732
-
1733
- if (value != null) {
1734
- if (Array.isArray(value)) {
1735
- await Promise.all(
1736
- value.map((v) =>
1737
- this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(v) }], batchId)
1738
- )
1739
- );
1740
- } else {
1741
- await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
1742
- }
1743
- }
1770
+ await this.writeRelation(key, 'adder', value, batchId);
1744
1771
  }
1745
1772
 
1746
1773
  private async removeRelationValue(key: string, value: any, batchId?: string) {
1747
- const metadata = this.getRelationOptions(key);
1748
- if (!metadata) {
1749
- console.warn(`Relation "${key}" has no metadata, skipping`);
1750
- return;
1751
- }
1774
+ await this.writeRelation(key, 'remover', value, batchId);
1775
+ }
1776
+
1777
+ /** A relation setter, adder or remover call: on a row read through an
1778
+ * abstract class it dispatches through the executor (see
1779
+ * {@link relationThroughAbstract}); otherwise its writes go out in as few
1780
+ * `executeAction` calls as {@link sendWrites} allows. */
1781
+ private async writeRelation(key: string, kind: 'setter' | 'adder' | 'remover', value: any, batchId?: string) {
1782
+ const predicate = this.getRelationOptions(key)?.predicate;
1783
+ if (predicate && kind !== 'remover') this._relationsWritten.add(predicate);
1752
1784
  const abstractName = this.abstractName();
1753
- if (abstractName) {
1754
- if (value != null) await this.relationThroughAbstract(abstractName, key, 'remover', value, batchId);
1785
+ if (!abstractName) {
1786
+ await this.sendWrites(this.planRelation(key, kind, value), batchId);
1755
1787
  return;
1756
1788
  }
1757
-
1758
- // Generate actions from metadata (replaces Prolog query)
1759
- const actions = this.generateRelationAction(key, 'remover');
1760
-
1761
- if (value != null) {
1762
- if (Array.isArray(value)) {
1763
- await Promise.all(
1764
- value.map((v) =>
1765
- this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(v) }], batchId)
1766
- )
1767
- );
1768
- } else {
1769
- await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value: this.resolveRelationId(value) }], batchId);
1770
- }
1789
+ if (!this.getRelationOptions(key)) {
1790
+ console.warn(`Relation "${key}" has no metadata, skipping`);
1791
+ return;
1771
1792
  }
1793
+ if (value != null) await this.relationThroughAbstract(abstractName, key, kind, value, batchId);
1772
1794
  }
1773
1795
 
1774
1796
  /**
@@ -1871,14 +1893,15 @@ export class Ad4mModel {
1871
1893
  );
1872
1894
 
1873
1895
  // Relations via innerUpdate; createSubject wrote the scalar properties.
1874
- await this.innerUpdate(false, batchId)
1896
+ const writes = await this.updateWrites(false);
1875
1897
 
1876
1898
  for (const key of deferredExpressionProps) {
1877
1899
  const value = (this as any)[key];
1878
1900
  if (value !== undefined && value !== null) {
1879
- await this.setProperty(key, value, batchId);
1901
+ writes.push(...await this.planProperty(key, value));
1880
1902
  }
1881
1903
  }
1904
+ await this.sendWrites(writes, batchId);
1882
1905
 
1883
1906
  // If we got a batchId passed in, we let the caller decide when to commit.
1884
1907
  // We can't call getData() since the instance won't exist in the perspective
@@ -1949,6 +1972,12 @@ export class Ad4mModel {
1949
1972
  }
1950
1973
 
1951
1974
  private async innerUpdate(setProperties: boolean = true, batchId?: string) {
1975
+ await this.sendWrites(await this.updateWrites(setProperties), batchId);
1976
+ }
1977
+
1978
+ /** The writes of the changed fields, in field order (see {@link sendWrites}). */
1979
+ private async updateWrites(setProperties: boolean = true): Promise<FieldWrite[]> {
1980
+ const writes: FieldWrite[] = [];
1952
1981
  const ctor = this.constructor as typeof Ad4mModel;
1953
1982
 
1954
1983
  // Determine which fields actually changed (skip unchanged when snapshot exists)
@@ -1989,26 +2018,30 @@ export class Ad4mModel {
1989
2018
 
1990
2019
  if (value !== undefined && value !== null) {
1991
2020
  if (value?.action) {
2021
+ const envelopePredicate = this.getRelationOptions(key)?.predicate;
2022
+ if (envelopePredicate && value.action !== "remover") this._relationsWritten.add(envelopePredicate);
1992
2023
  switch (value.action) {
1993
2024
  case "setter":
1994
- await this.setRelationValues(key, value.value, batchId);
2025
+ writes.push(...this.planRelation(key, 'setter', value.value));
1995
2026
  break;
1996
2027
  case "adder":
1997
- await this.addRelationValue(key, value.value, batchId);
2028
+ writes.push(...this.planRelation(key, 'adder', value.value));
1998
2029
  break;
1999
2030
  case "remover":
2000
- await this.removeRelationValue(key, value.value, batchId);
2031
+ writes.push(...this.planRelation(key, 'remover', value.value));
2001
2032
  break;
2002
2033
  default:
2003
- await this.setRelationValues(key, value.value, batchId);
2034
+ writes.push(...this.planRelation(key, 'setter', value.value));
2004
2035
  break;
2005
2036
  }
2006
2037
  } else if (Array.isArray(value)) {
2007
2038
  // Handle all arrays as relations, including empty ones (which clears the relation).
2008
2039
  // A record being created under an id minted here has no links to
2009
2040
  // clear, so an empty relation there costs a round trip and writes nothing.
2010
- if (value.length === 0 && !this._snapshot && this._idMinted && !this._relationsWritten.has(this.getRelationOptions(key)?.predicate ?? key)) continue;
2011
- await this.setRelationValues(key, value, batchId);
2041
+ const predicate = this.getRelationOptions(key)?.predicate ?? key;
2042
+ if (value.length === 0 && !this._snapshot && this._idMinted && !this._relationsWritten.has(predicate)) continue;
2043
+ this._relationsWritten.add(predicate);
2044
+ writes.push(...this.planRelation(key, 'setter', value));
2012
2045
  } else if (value !== undefined && value !== null && value !== "") {
2013
2046
  // A scalar handed to a relation field is a single-member relation.
2014
2047
  //
@@ -2036,7 +2069,8 @@ export class Ad4mModel {
2036
2069
  // both paths at once.
2037
2070
  const relationMeta = this.getRelationOptions(key);
2038
2071
  if (relationMeta) {
2039
- await this.setRelationValues(key, [value], batchId);
2072
+ this._relationsWritten.add(relationMeta.predicate);
2073
+ writes.push(...this.planRelation(key, 'setter', [value]));
2040
2074
  continue;
2041
2075
  }
2042
2076
 
@@ -2047,11 +2081,12 @@ export class Ad4mModel {
2047
2081
  continue;
2048
2082
  }
2049
2083
 
2050
- await this.setProperty(key, value, batchId);
2084
+ writes.push(...await this.planProperty(key, value));
2051
2085
  }
2052
2086
  }
2053
2087
  }
2054
2088
  }
2089
+ return writes;
2055
2090
  }
2056
2091
 
2057
2092
  /**
@@ -8,9 +8,10 @@
8
8
  import type { Ad4mModel } from "./Ad4mModel";
9
9
  import type { LinkStatus, PerspectiveProxy } from "../perspectives/PerspectiveProxy";
10
10
  import { LiveQuery } from "../perspectives/LiveQuery";
11
+ import { requireTotalCount } from "./query-common";
11
12
  import type {
12
13
  Where, Order, IncludeMap, Query,
13
- ResultsWithTotalCount, PaginationResult,
14
+ Page, PaginationResult,
14
15
  TypedQueryWhere, TypedOrder, TypedIncludeMap, PropertyKeysOf,
15
16
  } from "./types";
16
17
 
@@ -66,7 +67,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
66
67
  }
67
68
 
68
69
  /** Run `params` once and build model instances from the rows. */
69
- private execute(params: Query): Promise<ResultsWithTotalCount<T>> {
70
+ private execute(params: Query): Promise<Page<T>> {
70
71
  if (this.unionClasses) {
71
72
  return (this.ctor as any).executeUnionQuery(this.perspective, this.unionClasses, params);
72
73
  }
@@ -110,12 +111,18 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
110
111
  try {
111
112
  return { live, initial: await live.start() };
112
113
  } catch (e) {
113
- live.dispose();
114
- if (this.currentSubscription === live) this.currentSubscription = undefined;
114
+ this.endFailed(live);
115
115
  throw e;
116
116
  }
117
117
  }
118
118
 
119
+ /** End `live` after its call failed. A later call may already own
120
+ * `currentSubscription`, so only clear it if it is still `live`. */
121
+ private endFailed(live: LiveQuery): void {
122
+ live.dispose();
123
+ if (this.currentSubscription === live) this.currentSubscription = undefined;
124
+ }
125
+
119
126
  /**
120
127
  * Adds where conditions to the query.
121
128
  *
@@ -525,8 +532,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
525
532
  * ```
526
533
  */
527
534
  async count(): Promise<number> {
528
- const { totalCount } = await this.execute({ ...this.queryParams, limit: 0 });
529
- return totalCount;
535
+ return requireTotalCount(await this.execute({ ...this.queryParams, limit: 0, count: true }));
530
536
  }
531
537
 
532
538
  /**
@@ -567,8 +573,21 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
567
573
  */
568
574
  async countSubscribe(callback: (count: number) => void): Promise<number> {
569
575
  this.dispose();
570
- const { initial } = await this.live({ ...this.queryParams, limit: 0 }, (raw) => callback(raw.totalCount ?? 0));
571
- return initial.totalCount ?? 0;
576
+ // As paginateSubscribe: a push without the asked-for count is logged and
577
+ // skipped, since a throw here would reach the client's update dispatch.
578
+ const { live, initial } = await this.live({ ...this.queryParams, limit: 0, count: true }, (raw) => {
579
+ try {
580
+ callback(requireTotalCount(raw));
581
+ } catch (e) {
582
+ console.error('Count subscription error:', e);
583
+ }
584
+ });
585
+ try {
586
+ return requireTotalCount(initial);
587
+ } catch (e) {
588
+ this.endFailed(live);
589
+ throw e;
590
+ }
572
591
  }
573
592
 
574
593
  /**
@@ -596,8 +615,8 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
596
615
  */
597
616
  async paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>> {
598
617
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
599
- const { results, totalCount } = await this.execute(paginationQuery);
600
- return { results, totalCount, pageSize, pageNumber };
618
+ const answer = await this.execute(paginationQuery);
619
+ return { results: answer.results, totalCount: requireTotalCount(answer), pageSize, pageNumber };
601
620
  }
602
621
 
603
622
  /**
@@ -667,10 +686,11 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
667
686
  const results = this.parse(raw);
668
687
  const fp = fingerprint([results, raw?.totalCount]);
669
688
  this.takeSnapshots(results);
670
- return { page: { results, totalCount: raw?.totalCount, pageSize, pageNumber }, fp };
689
+ // `count: true` is set above, so the executor sends a total.
690
+ return { page: { results, totalCount: requireTotalCount(raw), pageSize, pageNumber }, fp };
671
691
  };
672
692
 
673
- const { initial } = await this.live(paginatedQuery, (raw) => {
693
+ const { live, initial } = await this.live(paginatedQuery, (raw) => {
674
694
  try {
675
695
  const { page, fp } = toPage(raw);
676
696
  if (fp === lastFingerprint) return;
@@ -680,9 +700,15 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
680
700
  console.error('Paginate subscription error:', e);
681
701
  }
682
702
  });
683
- const { page, fp } = toPage(initial);
684
- lastFingerprint = fp;
685
- return page;
703
+ let first: { page: PaginationResult<T>; fp: string };
704
+ try {
705
+ first = toPage(initial);
706
+ } catch (e) {
707
+ this.endFailed(live);
708
+ throw e;
709
+ }
710
+ lastFingerprint = first.fp;
711
+ return first.page;
686
712
  }
687
713
 
688
714
  /**
@@ -0,0 +1,72 @@
1
+ /**
2
+ * Type test: the results of the calls that always ask for the count
3
+ * (`findAllAndCount()`, `paginate()`, `paginateSubscribe()`) have a required
4
+ * `totalCount`, so a consumer under `strictNullChecks` does not see
5
+ * "possibly undefined". ts-jest type-checks this file; the optional modifier
6
+ * is visible to `IsRequired` with or without `strictNullChecks`.
7
+ *
8
+ * At run time those calls, and `count()`, throw when the executor's answer has
9
+ * no `totalCount` instead of reporting zero matches.
10
+ */
11
+ import { Ad4mModel } from './Ad4mModel';
12
+ import { ModelQueryBuilder } from './ModelQueryBuilder';
13
+ import { Model, Property } from './decorators';
14
+ import { PerspectiveProxy } from '../perspectives/PerspectiveProxy';
15
+ import type { PaginationResult, ResultsWithTotalCount } from './types';
16
+
17
+ type IsRequired<T, K extends keyof T> = {} extends Pick<T, K> ? false : true;
18
+
19
+ class Note extends Ad4mModel {}
20
+
21
+ type FindAllAndCount = Awaited<ReturnType<typeof Note.findAllAndCount<Note>>>;
22
+ type StaticPaginate = Awaited<ReturnType<typeof Note.paginate<Note>>>;
23
+ type BuilderPaginate = Awaited<ReturnType<ModelQueryBuilder<Note>['paginate']>>;
24
+ type BuilderPaginateSubscribe = Awaited<ReturnType<ModelQueryBuilder<Note>['paginateSubscribe']>>;
25
+ type PaginateCallbackPage = Parameters<Parameters<ModelQueryBuilder<Note>['paginateSubscribe']>[2]>[0];
26
+
27
+ describe('count results type', () => {
28
+ it('totalCount is required where the call always asks for the count', () => {
29
+ const required: [
30
+ IsRequired<ResultsWithTotalCount<Note>, 'totalCount'>,
31
+ IsRequired<PaginationResult<Note>, 'totalCount'>,
32
+ IsRequired<FindAllAndCount, 'totalCount'>,
33
+ IsRequired<StaticPaginate, 'totalCount'>,
34
+ IsRequired<BuilderPaginate, 'totalCount'>,
35
+ IsRequired<BuilderPaginateSubscribe, 'totalCount'>,
36
+ IsRequired<PaginateCallbackPage, 'totalCount'>,
37
+ ] = [true, true, true, true, true, true, true];
38
+ expect(required.every(Boolean)).toBe(true);
39
+ });
40
+ });
41
+
42
+ describe('an answer without the count that was asked for', () => {
43
+ @Model({ name: 'CountedNote' })
44
+ class CountedNote extends Ad4mModel {
45
+ @Property({ through: 'cn://title' })
46
+ title: string = '';
47
+ }
48
+
49
+ // A perspective whose executor answers every model query without `totalCount`.
50
+ const perspective = new PerspectiveProxy(
51
+ { uuid: 'cn-uuid', name: 'cn', owners: [], sharedUrl: null, neighbourhood: null, state: 'Synced' } as any,
52
+ new Proxy({} as any, {
53
+ get: (_target, method: string) => {
54
+ if (method === 'then') return undefined;
55
+ return async () => {
56
+ if (method === 'modelQuery') return { instances: [] };
57
+ throw new Error(`unexpected RPC ${method}`);
58
+ };
59
+ },
60
+ }),
61
+ );
62
+
63
+ it.each([
64
+ ['Model.count', () => CountedNote.count(perspective)],
65
+ ['Model.findAllAndCount', () => CountedNote.findAllAndCount(perspective)],
66
+ ['Model.paginate', () => CountedNote.paginate(perspective, 10, 1)],
67
+ ['query().count', () => CountedNote.query(perspective).count()],
68
+ ['query().paginate', () => CountedNote.query(perspective).paginate(10, 1)],
69
+ ])('%s throws naming totalCount', async (_name, call) => {
70
+ await expect(call()).rejects.toThrow(/totalCount/);
71
+ });
72
+ });
@@ -17,4 +17,3 @@ export * from "./hydration";
17
17
  export * from "./ModelQueryBuilder";
18
18
  export * from "./sdna";
19
19
  export * from "./shacl-gen";
20
- export * from "./query-cache";
@@ -6,6 +6,19 @@ import type { Scope, TraverseScope } from "./types";
6
6
  import { isContainedScope, isContainmentTraversal, isTraverseScope } from "./types";
7
7
  import { getRelationsMetadata } from "./decorators";
8
8
 
9
+ /**
10
+ * The `totalCount` of a model query sent with `count: true`. The executor
11
+ * answers such a query with a count, so an answer without one is an error,
12
+ * not zero matches.
13
+ */
14
+ export function requireTotalCount(answer: { totalCount?: number } | null | undefined): number {
15
+ const totalCount = answer?.totalCount;
16
+ if (typeof totalCount !== "number") {
17
+ throw new Error("model query asked for a count (count: true) but the answer has no totalCount");
18
+ }
19
+ return totalCount;
20
+ }
21
+
9
22
  /**
10
23
  * Resolves the predicate for a parent query.
11
24
  *
@@ -1031,18 +1031,16 @@ class SavesReadOnly extends Ad4mModel {
1031
1031
  describe("readOnly relations when saving", () => {
1032
1032
  it("are skipped by save() and create(), even without a getter", async () => {
1033
1033
  const proto = SavesReadOnly.prototype as any;
1034
- const set = jest.spyOn(proto, "setRelationValues").mockResolvedValue(undefined);
1035
- const add = jest.spyOn(proto, "addRelationValue").mockResolvedValue(undefined);
1034
+ const plan = jest.spyOn(proto, "planRelation").mockReturnValue([]);
1036
1035
  try {
1037
1036
  const instance = new SavesReadOnly({ uuid: "p" } as any, "test://instance");
1038
1037
  await (instance as any).innerUpdate(true);
1039
1038
 
1040
- const touched = [...set.mock.calls, ...add.mock.calls].map((call) => call[0]);
1039
+ const touched = plan.mock.calls.map((call) => call[0]);
1041
1040
  expect(touched).toContain("writableLinks");
1042
1041
  expect(touched).not.toContain("readOnlyLinks");
1043
1042
  } finally {
1044
- set.mockRestore();
1045
- add.mockRestore();
1043
+ plan.mockRestore();
1046
1044
  }
1047
1045
  });
1048
1046
 
@@ -329,6 +329,7 @@ export function buildSHACL(
329
329
  // Encode relation kind so the executor can derive direction and
330
330
  // scalar-vs-collection rendering without consulting the JS class.
331
331
  relShape.relationKind = relMeta.kind;
332
+ if (relMeta.polymorphic) relShape.polymorphic = true;
332
333
 
333
334
  // Scalar relations cap at 1.
334
335
  if (relMeta.kind === 'hasOne' || relMeta.kind === 'belongsToOne') {