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

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 (64) hide show
  1. package/lib/index.cjs +548 -477
  2. package/lib/index.js +548 -473
  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 +125 -82
  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/types.d.ts +12 -3
  26. package/lib/src/perspectives/FlowModels.js +1 -1
  27. package/lib/src/perspectives/LiveQuery.d.ts +1 -1
  28. package/lib/src/perspectives/PerspectiveClient.d.ts +17 -6
  29. package/lib/src/perspectives/PerspectiveClient.js +83 -44
  30. package/lib/src/perspectives/PerspectiveProxy.d.ts +19 -10
  31. package/lib/src/perspectives/PerspectiveProxy.js +31 -69
  32. package/package.json +2 -2
  33. package/src/Ad4mClient.test.ts +17 -6
  34. package/src/agent/AgentClient.ts +46 -74
  35. package/src/cache/KeyedCache.test.ts +162 -0
  36. package/src/cache/KeyedCache.ts +179 -0
  37. package/src/cache/cache.test.ts +294 -71
  38. package/src/expression/ExpressionClient.ts +46 -131
  39. package/src/generated/api/ExpressionLookupError.ts +6 -0
  40. package/src/generated/api/ExpressionManyEntry.ts +8 -0
  41. package/src/generated/api/FlowFiredEntry.ts +11 -0
  42. package/src/generated/api/PerspectiveFlowFiredParams.ts +3 -3
  43. package/src/generated/api/RpcMethods.ts +4 -2
  44. package/src/model/Ad4mModel.test.ts +237 -43
  45. package/src/model/Ad4mModel.ts +132 -98
  46. package/src/model/ModelQueryBuilder.ts +41 -15
  47. package/src/model/count-result-type.test.ts +72 -0
  48. package/src/model/index.ts +0 -1
  49. package/src/model/query-common.ts +13 -0
  50. package/src/model/relation-filtering.test.ts +3 -5
  51. package/src/model/types.ts +9 -3
  52. package/src/model/write-round-trips.test.ts +30 -6
  53. package/src/perspectives/FlowModels.ts +1 -1
  54. package/src/perspectives/LiveQuery.ts +1 -1
  55. package/src/perspectives/PerspectiveClient.test.ts +287 -0
  56. package/src/perspectives/PerspectiveClient.ts +101 -66
  57. package/src/perspectives/PerspectiveProxy.test.ts +6 -14
  58. package/src/perspectives/PerspectiveProxy.ts +33 -67
  59. package/src/perspectives/TextContent.test.ts +0 -16
  60. package/src/perspectives/shacl-rpc.test.ts +1 -1
  61. package/lib/src/model/query-cache.d.ts +0 -30
  62. package/lib/src/model/query-cache.js +0 -66
  63. package/src/model/query-cache.test.ts +0 -54
  64. 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,
@@ -373,6 +373,14 @@ function jsonToModelInstance<T extends Ad4mModel>(
373
373
  return instance;
374
374
  }
375
375
 
376
+ /** One field write: the commands and parameters of one `executeAction`. */
377
+ interface FieldWrite {
378
+ commands: any[];
379
+ parameters: { name: string; value: any }[];
380
+ }
381
+
382
+ /** The most writes `sendWrites` joins into one `executeAction` call. */
383
+ const MAX_WRITES_PER_CALL = 200;
376
384
 
377
385
  /**
378
386
  * Put `childId` under `parent`. A containment scope `{ id }` writes through the
@@ -1367,7 +1375,7 @@ export class Ad4mModel {
1367
1375
  classes: (typeof Ad4mModel)[],
1368
1376
  query: Query = {},
1369
1377
  options?: CallOptions,
1370
- ): Promise<ResultsWithTotalCount<Ad4mModel>> {
1378
+ ): Promise<Page<Ad4mModel>> {
1371
1379
  const { classNames, queryJson } = Ad4mModel.prepareUnionQueryParams(classes, query);
1372
1380
  const result = await perspective.modelQuery(classNames, queryJson, options);
1373
1381
  const results = Ad4mModel.parseUnionResult(classes, perspective, result, query.include, query.properties);
@@ -1446,7 +1454,7 @@ export class Ad4mModel {
1446
1454
  query: Query = {},
1447
1455
  classNameOverride?: string | null,
1448
1456
  options?: CallOptions,
1449
- ): Promise<ResultsWithTotalCount<T>> {
1457
+ ): Promise<Page<T>> {
1450
1458
  // Delegate query input building to the shared prepareModelQueryParams
1451
1459
  // helper. The executor resolves the shape from SHACL server-side.
1452
1460
  const { className, queryJson } = this.prepareModelQueryParams(
@@ -1561,8 +1569,8 @@ export class Ad4mModel {
1561
1569
  query?: Q,
1562
1570
  options?: CallOptions,
1563
1571
  ): 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>>>;
1572
+ const answer = await this.executeModelQuery(perspective, { ...((query ?? {}) as Query), count: true }, undefined, options);
1573
+ return { results: answer.results as (T & IncludeExtras<T, IncludeOf<Q>>)[], totalCount: requireTotalCount(answer) };
1566
1574
  }
1567
1575
 
1568
1576
  /**
@@ -1591,8 +1599,8 @@ export class Ad4mModel {
1591
1599
  options?: CallOptions,
1592
1600
  ): Promise<PaginationResult<T & IncludeExtras<T, IncludeOf<Q>>>> {
1593
1601
  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 };
1602
+ const answer = await this.executeModelQuery(perspective, paginationQuery, undefined, options);
1603
+ return { results: answer.results as (T & IncludeExtras<T, IncludeOf<Q>>)[], totalCount: requireTotalCount(answer), pageSize, pageNumber };
1596
1604
  }
1597
1605
 
1598
1606
  /**
@@ -1627,15 +1635,15 @@ export class Ad4mModel {
1627
1635
  query?: TypedQuery<T>,
1628
1636
  options?: CallOptions,
1629
1637
  ): Promise<number> {
1630
- const { totalCount } = await this.executeModelQuery(perspective, { ...((query ?? {}) as Query), limit: 0 }, undefined, options);
1631
- return totalCount;
1638
+ return requireTotalCount(await this.executeModelQuery(perspective, { ...((query ?? {}) as Query), limit: 0, count: true }, undefined, options));
1632
1639
  }
1633
1640
 
1634
- private async setProperty(key: string, value: any, batchId?: string) {
1641
+ /** The `executeAction` write that sets property `key` to `value`; none for an empty value. */
1642
+ private async planProperty(key: string, value: any): Promise<FieldWrite[]> {
1635
1643
  const metadata = this.getPropertyMetadata(key);
1636
1644
  if (!metadata) {
1637
1645
  console.warn(`Property "${key}" has no metadata, skipping`);
1638
- return;
1646
+ return [];
1639
1647
  }
1640
1648
 
1641
1649
  // Generate actions from metadata (replaces Prolog query)
@@ -1643,7 +1651,7 @@ export class Ad4mModel {
1643
1651
 
1644
1652
  // Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
1645
1653
  if (value === undefined || value === null || value === "") {
1646
- return;
1654
+ return [];
1647
1655
  }
1648
1656
 
1649
1657
  const mode = effectiveLiteralStorage(metadata);
@@ -1658,7 +1666,76 @@ export class Ad4mModel {
1658
1666
  value = valueToLiteralIri(value);
1659
1667
  }
1660
1668
 
1661
- await this._perspective.executeAction(actions, this._baseExpression, [{ name: "value", value }], batchId);
1669
+ return [{ commands: actions, parameters: [{ name: "value", value }] }];
1670
+ }
1671
+
1672
+ /**
1673
+ * The `executeAction` writes of a relation change: one for a set (its
1674
+ * `collectionSetter` takes every value), one per value for an add or remove.
1675
+ */
1676
+ private planRelation(key: string, kind: 'setter' | 'adder' | 'remover', value: any): FieldWrite[] {
1677
+ const metadata = this.getRelationOptions(key);
1678
+ if (!metadata) {
1679
+ console.warn(`Relation "${key}" has no metadata, skipping`);
1680
+ return [];
1681
+ }
1682
+
1683
+ // Generate actions from metadata (replaces Prolog query)
1684
+ const actions = this.generateRelationAction(key, kind);
1685
+
1686
+ if (value == null) return [];
1687
+ const values = Array.isArray(value) ? value : [value];
1688
+ const param = (v: any) => ({ name: "value", value: this.resolveRelationId(v) });
1689
+ if (kind === 'setter') return [{ commands: actions, parameters: values.map(param) }];
1690
+ return values.map(v => ({ commands: actions, parameters: [param(v)] }));
1691
+ }
1692
+
1693
+ /**
1694
+ * Sends writes in as few `executeAction` calls as keep their links: the
1695
+ * executor runs a call's commands in order, so consecutive writes share one
1696
+ * call, each with its own parameter names. A `collectionSetter` takes every
1697
+ * parameter of its call as a member, so it goes in a call of its own. A
1698
+ * command's `local` flag is per command, so Local and Shared links mix. The
1699
+ * executor tries every parameter name at each position of each command, so
1700
+ * a call holds at most `MAX_WRITES_PER_CALL` writes.
1701
+ */
1702
+ private async sendWrites(writes: FieldWrite[], batchId?: string): Promise<void> {
1703
+ let group: FieldWrite[] = [];
1704
+ const flush = async () => {
1705
+ if (group.length === 1) {
1706
+ await this._perspective.executeAction(group[0].commands, this._baseExpression, group[0].parameters, batchId);
1707
+ } else if (group.length > 1) {
1708
+ const commands: any[] = [];
1709
+ const parameters: { name: string; value: any }[] = [];
1710
+ group.forEach((write, i) => {
1711
+ // The executor substitutes a parameter name wherever it occurs in a
1712
+ // command's source, predicate or target; rename `value` the same way.
1713
+ const name = `ad4m-model-write-${i}-value`;
1714
+ const rename = (s: any) => (typeof s === "string" && write.parameters.length ? s.split("value").join(name) : s);
1715
+ for (const c of write.commands) {
1716
+ commands.push({ ...c, source: rename(c.source), predicate: rename(c.predicate), target: rename(c.target) });
1717
+ }
1718
+ for (const p of write.parameters) parameters.push({ name, value: p.value });
1719
+ });
1720
+ await this._perspective.executeAction(commands, this._baseExpression, parameters, batchId);
1721
+ }
1722
+ group = [];
1723
+ };
1724
+ for (const write of writes) {
1725
+ if (write.commands.some((c: any) => c.action === "collectionSetter")) {
1726
+ await flush();
1727
+ group = [write];
1728
+ await flush();
1729
+ } else {
1730
+ group.push(write);
1731
+ if (group.length >= MAX_WRITES_PER_CALL) await flush();
1732
+ }
1733
+ }
1734
+ await flush();
1735
+ }
1736
+
1737
+ private async setProperty(key: string, value: any, batchId?: string) {
1738
+ await this.sendWrites(await this.planProperty(key, value), batchId);
1662
1739
  }
1663
1740
 
1664
1741
  /** Resolve a relation argument to a plain string ID. Accepts either a raw
@@ -1685,90 +1762,34 @@ export class Ad4mModel {
1685
1762
  }
1686
1763
 
1687
1764
  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
- }
1765
+ await this.writeRelation(key, 'setter', value, batchId);
1715
1766
  }
1716
1767
 
1717
1768
  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
- }
1769
+ await this.writeRelation(key, 'adder', value, batchId);
1744
1770
  }
1745
1771
 
1746
1772
  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
- }
1773
+ await this.writeRelation(key, 'remover', value, batchId);
1774
+ }
1775
+
1776
+ /** A relation setter, adder or remover call: on a row read through an
1777
+ * abstract class it dispatches through the executor (see
1778
+ * {@link relationThroughAbstract}); otherwise its writes go out in as few
1779
+ * `executeAction` calls as {@link sendWrites} allows. */
1780
+ private async writeRelation(key: string, kind: 'setter' | 'adder' | 'remover', value: any, batchId?: string) {
1781
+ const predicate = this.getRelationOptions(key)?.predicate;
1782
+ if (predicate && kind !== 'remover') this._relationsWritten.add(predicate);
1752
1783
  const abstractName = this.abstractName();
1753
- if (abstractName) {
1754
- if (value != null) await this.relationThroughAbstract(abstractName, key, 'remover', value, batchId);
1784
+ if (!abstractName) {
1785
+ await this.sendWrites(this.planRelation(key, kind, value), batchId);
1755
1786
  return;
1756
1787
  }
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
- }
1788
+ if (!this.getRelationOptions(key)) {
1789
+ console.warn(`Relation "${key}" has no metadata, skipping`);
1790
+ return;
1771
1791
  }
1792
+ if (value != null) await this.relationThroughAbstract(abstractName, key, kind, value, batchId);
1772
1793
  }
1773
1794
 
1774
1795
  /**
@@ -1871,14 +1892,15 @@ export class Ad4mModel {
1871
1892
  );
1872
1893
 
1873
1894
  // Relations via innerUpdate; createSubject wrote the scalar properties.
1874
- await this.innerUpdate(false, batchId)
1895
+ const writes = await this.updateWrites(false);
1875
1896
 
1876
1897
  for (const key of deferredExpressionProps) {
1877
1898
  const value = (this as any)[key];
1878
1899
  if (value !== undefined && value !== null) {
1879
- await this.setProperty(key, value, batchId);
1900
+ writes.push(...await this.planProperty(key, value));
1880
1901
  }
1881
1902
  }
1903
+ await this.sendWrites(writes, batchId);
1882
1904
 
1883
1905
  // If we got a batchId passed in, we let the caller decide when to commit.
1884
1906
  // We can't call getData() since the instance won't exist in the perspective
@@ -1949,6 +1971,12 @@ export class Ad4mModel {
1949
1971
  }
1950
1972
 
1951
1973
  private async innerUpdate(setProperties: boolean = true, batchId?: string) {
1974
+ await this.sendWrites(await this.updateWrites(setProperties), batchId);
1975
+ }
1976
+
1977
+ /** The writes of the changed fields, in field order (see {@link sendWrites}). */
1978
+ private async updateWrites(setProperties: boolean = true): Promise<FieldWrite[]> {
1979
+ const writes: FieldWrite[] = [];
1952
1980
  const ctor = this.constructor as typeof Ad4mModel;
1953
1981
 
1954
1982
  // Determine which fields actually changed (skip unchanged when snapshot exists)
@@ -1989,26 +2017,30 @@ export class Ad4mModel {
1989
2017
 
1990
2018
  if (value !== undefined && value !== null) {
1991
2019
  if (value?.action) {
2020
+ const envelopePredicate = this.getRelationOptions(key)?.predicate;
2021
+ if (envelopePredicate && value.action !== "remover") this._relationsWritten.add(envelopePredicate);
1992
2022
  switch (value.action) {
1993
2023
  case "setter":
1994
- await this.setRelationValues(key, value.value, batchId);
2024
+ writes.push(...this.planRelation(key, 'setter', value.value));
1995
2025
  break;
1996
2026
  case "adder":
1997
- await this.addRelationValue(key, value.value, batchId);
2027
+ writes.push(...this.planRelation(key, 'adder', value.value));
1998
2028
  break;
1999
2029
  case "remover":
2000
- await this.removeRelationValue(key, value.value, batchId);
2030
+ writes.push(...this.planRelation(key, 'remover', value.value));
2001
2031
  break;
2002
2032
  default:
2003
- await this.setRelationValues(key, value.value, batchId);
2033
+ writes.push(...this.planRelation(key, 'setter', value.value));
2004
2034
  break;
2005
2035
  }
2006
2036
  } else if (Array.isArray(value)) {
2007
2037
  // Handle all arrays as relations, including empty ones (which clears the relation).
2008
2038
  // A record being created under an id minted here has no links to
2009
2039
  // 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);
2040
+ const predicate = this.getRelationOptions(key)?.predicate ?? key;
2041
+ if (value.length === 0 && !this._snapshot && this._idMinted && !this._relationsWritten.has(predicate)) continue;
2042
+ this._relationsWritten.add(predicate);
2043
+ writes.push(...this.planRelation(key, 'setter', value));
2012
2044
  } else if (value !== undefined && value !== null && value !== "") {
2013
2045
  // A scalar handed to a relation field is a single-member relation.
2014
2046
  //
@@ -2036,7 +2068,8 @@ export class Ad4mModel {
2036
2068
  // both paths at once.
2037
2069
  const relationMeta = this.getRelationOptions(key);
2038
2070
  if (relationMeta) {
2039
- await this.setRelationValues(key, [value], batchId);
2071
+ this._relationsWritten.add(relationMeta.predicate);
2072
+ writes.push(...this.planRelation(key, 'setter', [value]));
2040
2073
  continue;
2041
2074
  }
2042
2075
 
@@ -2047,11 +2080,12 @@ export class Ad4mModel {
2047
2080
  continue;
2048
2081
  }
2049
2082
 
2050
- await this.setProperty(key, value, batchId);
2083
+ writes.push(...await this.planProperty(key, value));
2051
2084
  }
2052
2085
  }
2053
2086
  }
2054
2087
  }
2088
+ return writes;
2055
2089
  }
2056
2090
 
2057
2091
  /**
@@ -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
 
@@ -307,7 +307,8 @@ export function isTraverseScope(scope: Scope): scope is TraverseScope {
307
307
  * // One level deep
308
308
  * { comments: true }
309
309
  *
310
- * // Sub-query: only the 5 most-recent comments
310
+ * // Sub-query: only the 5 most-recent comments of each parent
311
+ * // (`limit` and `offset` page every parent's relation on its own)
311
312
  * { comments: { order: { createdAt: 'DESC' }, limit: 5 } }
312
313
  *
313
314
  * // Nested eager-load
@@ -400,6 +401,7 @@ export type Query = {
400
401
  order?: Order;
401
402
  offset?: number;
402
403
  limit?: number;
404
+ /** Ask for `totalCount`. Without it the result has none and the executor runs no COUNT query. */
403
405
  count?: boolean;
404
406
  /**
405
407
  * When true, SPARQL property getters (@Property with `getter`) ARE evaluated
@@ -772,8 +774,12 @@ export type GetOptions = Pick<Query, 'include' | 'properties'>;
772
774
  // ---------------------------------------------------------------------------
773
775
 
774
776
  export type AllInstancesResult = { AllInstances: Ad4mModel[]; TotalCount?: number };
775
- export type ResultsWithTotalCount<T> = { results: T[]; totalCount?: number };
776
- export type PaginationResult<T> = { results: T[]; totalCount?: number; pageSize: number; pageNumber: number };
777
+ /** A model query's rows; `totalCount` is set when the query asked for it (`count: true`). */
778
+ export type Page<T> = { results: T[]; totalCount?: number };
779
+ /** The result of `findAllAndCount()`, which always asks for the count. */
780
+ export type ResultsWithTotalCount<T> = { results: T[]; totalCount: number };
781
+ /** The result of `paginate()` and `paginateSubscribe()`, which always ask for the count. */
782
+ export type PaginationResult<T> = { results: T[]; totalCount: number; pageSize: number; pageNumber: number };
777
783
 
778
784
  // ---------------------------------------------------------------------------
779
785
  // Internal value transport