@syncular/typegen 0.24.0 → 0.25.0

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.
package/README.md CHANGED
@@ -668,14 +668,18 @@ sync query compareLists(left, right) {
668
668
  }
669
669
  ```
670
670
 
671
- Coverage must resolve every read schema table, with one instance per table, and
672
- bind every declared scope. A required scope bind can propagate across a
673
- qualified scope-column equality in an unconditional outer `WHERE` clause or a
674
- simple mandatory `ON` clause. The generated descriptor contains aggregate
675
- coverage for every table, and readiness requires all of it. Self-joins and
676
- `ON` clauses containing `OR`, `NOT`, or nested SQL cannot claim coverage. Only
671
+ Coverage must resolve every read schema table and bind every declared scope on
672
+ every table instance. A required scope bind can propagate across a qualified
673
+ scope-column equality in an unconditional outer `WHERE` clause or a simple
674
+ mandatory `ON` clause. The generated descriptor contains aggregate coverage for
675
+ every table, and readiness requires all of it. A self-join claims coverage when
676
+ every instance of the table carries the same proof (the same scopes, operators,
677
+ and parameters); the descriptor then holds one coverage entry and one
678
+ dependency for that table. An unproven instance or differing proofs fail with
679
+ `SYQL6005_INVALID_SYNC_QUERY`. `ON` clauses containing `OR`, `NOT`, or nested
680
+ SQL cannot claim coverage. Only
677
681
  required, non-null, exactly typed binds are allowed. Result identity is inferred
678
- from schema keys and the projection. Without constructive proof an ordinary
682
+ from schema keys and the projection; a self-join has no inferred identity. Without constructive proof an ordinary
679
683
  query falls back to table-wide dependency, no coverage, and/or unkeyed
680
684
  reconciliation; a `sync query` fails generation rather than claiming partial
681
685
  completeness.
@@ -478,7 +478,7 @@ function emitDescriptorAndRunners(query, hash) {
478
478
  else {
479
479
  lines.push(' pub fn snapshot(', ' client: &mut SyncClient,', ' params: &Params,', ' ) -> Result<TypedQuerySnapshot<Row>, QueryError> {');
480
480
  }
481
- lines.push(' let selected = select(params)?;', ' let required_coverage = coverage(params);', ' let snapshot = client', ' .query_snapshot(selected.sql, &selected.params, &required_coverage)', ' .map_err(|message| QueryError::Client { query: ID, message })?;', ' let rows = snapshot.rows.into_iter().map(decode).collect::<Result<_, _>>()?;', ' Ok(TypedQuerySnapshot {', ' revision: snapshot.revision,', ' rows,', ' coverage: snapshot.coverage,', ' })', ' }');
481
+ lines.push(' let selected = select(params)?;', ' let required_coverage = coverage(params);', ' let snapshot = client', ' .query_snapshot(', ' selected.sql,', ' &selected.params,', ' &required_coverage,', ' Some(QueryOwner { id: ID, tables: TABLES }),', ' )', ' .map_err(|message| QueryError::Client { query: ID, message })?;', ' let rows = snapshot.rows.into_iter().map(decode).collect::<Result<_, _>>()?;', ' Ok(TypedQuerySnapshot {', ' revision: snapshot.revision,', ' rows,', ' coverage: snapshot.coverage,', ' })', ' }');
482
482
  return lines;
483
483
  }
484
484
  function emitQuery(query, hash) {
@@ -498,7 +498,7 @@ function emitSupport(clientCrate) {
498
498
  'use std::error::Error;',
499
499
  'use std::fmt;',
500
500
  `use ${clientCrate}::{`,
501
- ' CoverageSnapshot, QueryRow, QueryValue, SyncClient, WindowBase, WindowCoverage,',
501
+ ' CoverageSnapshot, QueryOwner, QueryRow, QueryValue, SyncClient, WindowBase, WindowCoverage,',
502
502
  '};',
503
503
  '',
504
504
  '#[derive(Debug, Clone, PartialEq, Eq, Default)]',
@@ -1131,31 +1131,30 @@ class Validator {
1131
1131
  return { ...candidate, scopes };
1132
1132
  });
1133
1133
  const ftsOwners = new Map(this.#ir.tables.flatMap((table) => table.ftsIndexes.map((index) => [index.name, table.name])));
1134
+ // Several instances of one table (a self-join) share one dependency and
1135
+ // one coverage entry only when their proofs are identical. Scopes follow
1136
+ // the table's declaration order, so only the parameter sets need sorting.
1137
+ const proofKey = (candidate) => JSON.stringify(candidate.scopes.map((scope) => [
1138
+ scope.binding.variable,
1139
+ scope.operator,
1140
+ [...scope.binding.params].sort(),
1141
+ ]));
1134
1142
  const dependencies = [
1135
1143
  ...new Set(refs.map((ref) => ftsOwners.get(ref.table) ?? ref.table)),
1136
1144
  ]
1137
1145
  .sort()
1138
1146
  .map((table) => {
1139
1147
  const instances = resolvedCandidates.filter((item) => item.ref.table === table);
1140
- if (instances.length !== 1 ||
1141
- instances.some((item) => item.scopes.length === 0)) {
1148
+ const first = instances[0];
1149
+ if (first === undefined ||
1150
+ first.scopes.length === 0 ||
1151
+ instances.some((item) => proofKey(item) !== proofKey(first))) {
1142
1152
  return { table, scopes: [] };
1143
1153
  }
1144
- const scopes = instances
1145
- .flatMap((item) => item.scopes.map((scope) => scope.binding))
1146
- .reduce((out, scope) => {
1147
- const existing = out.find((item) => item.variable === scope.variable);
1148
- if (existing === undefined)
1149
- out.push(scope);
1150
- else {
1151
- out[out.indexOf(existing)] = {
1152
- ...existing,
1153
- params: [...new Set([...existing.params, ...scope.params])],
1154
- };
1155
- }
1156
- return out;
1157
- }, []);
1158
- return { table, scopes };
1154
+ return {
1155
+ table,
1156
+ scopes: first.scopes.map((scope) => scope.binding),
1157
+ };
1159
1158
  });
1160
1159
  if (!logical.declaration.sync)
1161
1160
  return { dependencies, coverage: [] };
@@ -1163,13 +1162,17 @@ class Validator {
1163
1162
  const eligible = syncedCandidates.filter((candidate) => {
1164
1163
  const table = this.#ir.tables.find((item) => item.name === candidate.ref.table);
1165
1164
  return (table !== undefined &&
1166
- syncedCandidates.filter((item) => item.ref.table === candidate.ref.table).length === 1 &&
1167
1165
  table.scopes.length > 0 &&
1168
1166
  candidate.scopes.length === table.scopes.length);
1169
1167
  });
1170
1168
  const syncBy = logical.declaration.syncBy;
1171
1169
  if (eligible.length === 0 || eligible.length !== syncedCandidates.length) {
1172
- this.#fail('SYQL6005_INVALID_SYNC_QUERY', logical.declaration.syncBy?.span ?? logical.declaration.nameSpan, 'sync query coverage cannot be proven for every read table from required equality/IN predicates over every declared scope; split the query or add an exact compatible scope proof');
1170
+ this.#fail('SYQL6005_INVALID_SYNC_QUERY', logical.declaration.syncBy?.span ?? logical.declaration.nameSpan, 'sync query coverage cannot be proven for every read table instance from required equality/IN predicates over every declared scope; split the query or add an exact compatible scope proof');
1171
+ }
1172
+ const divergent = eligible.find((candidate) => eligible.some((other) => other.ref.table === candidate.ref.table &&
1173
+ proofKey(other) !== proofKey(candidate)));
1174
+ if (divergent !== undefined) {
1175
+ this.#fail('SYQL6005_INVALID_SYNC_QUERY', logical.declaration.syncBy?.span ?? logical.declaration.nameSpan, `sync query reads ${divergent.ref.table} through several instances whose scope proofs differ; every instance must bind the same scopes with the same operator and parameters, or the query must be split`);
1173
1176
  }
1174
1177
  const byCandidate = syncBy === undefined
1175
1178
  ? undefined
@@ -1195,13 +1198,16 @@ class Validator {
1195
1198
  }
1196
1199
  const sameParams = (left, right) => left.length === right.length &&
1197
1200
  left.every((value) => right.includes(value));
1198
- const coverage = eligible.map((candidate) => {
1201
+ const coverage = eligible
1202
+ .filter((candidate) => eligible.find((item) => item.ref.table === candidate.ref.table) ===
1203
+ candidate)
1204
+ .map((candidate) => {
1199
1205
  const table = this.#ir.tables.find((item) => item.name === candidate.ref.table);
1200
1206
  if (table === undefined)
1201
1207
  throw new Error('eligible table disappeared');
1202
1208
  const byVariable = new Map(candidate.scopes.map((scope) => [scope.binding.variable, scope]));
1203
1209
  let unit;
1204
- if (candidate === byCandidate) {
1210
+ if (candidate.ref.table === byCandidate?.ref.table) {
1205
1211
  unit = anchorUnit;
1206
1212
  }
1207
1213
  else if (table.scopes.length === 1) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/typegen",
3
- "version": "0.24.0",
3
+ "version": "0.25.0",
4
4
  "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -56,9 +56,9 @@
56
56
  "!dist/**/*.test.d.ts"
57
57
  ],
58
58
  "dependencies": {
59
- "@syncular/core": "0.24.0"
59
+ "@syncular/core": "0.25.0"
60
60
  },
61
61
  "devDependencies": {
62
- "@syncular/server": "0.24.0"
62
+ "@syncular/server": "0.25.0"
63
63
  }
64
64
  }
@@ -684,7 +684,12 @@ function emitDescriptorAndRunners(
684
684
  ' let selected = select(params)?;',
685
685
  ' let required_coverage = coverage(params);',
686
686
  ' let snapshot = client',
687
- ' .query_snapshot(selected.sql, &selected.params, &required_coverage)',
687
+ ' .query_snapshot(',
688
+ ' selected.sql,',
689
+ ' &selected.params,',
690
+ ' &required_coverage,',
691
+ ' Some(QueryOwner { id: ID, tables: TABLES }),',
692
+ ' )',
688
693
  ' .map_err(|message| QueryError::Client { query: ID, message })?;',
689
694
  ' let rows = snapshot.rows.into_iter().map(decode).collect::<Result<_, _>>()?;',
690
695
  ' Ok(TypedQuerySnapshot {',
@@ -715,7 +720,7 @@ function emitSupport(clientCrate: string): string {
715
720
  'use std::error::Error;',
716
721
  'use std::fmt;',
717
722
  `use ${clientCrate}::{`,
718
- ' CoverageSnapshot, QueryRow, QueryValue, SyncClient, WindowBase, WindowCoverage,',
723
+ ' CoverageSnapshot, QueryOwner, QueryRow, QueryValue, SyncClient, WindowBase, WindowCoverage,',
719
724
  '};',
720
725
  '',
721
726
  '#[derive(Debug, Clone, PartialEq, Eq, Default)]',
@@ -1625,6 +1625,17 @@ class Validator {
1625
1625
  table.ftsIndexes.map((index) => [index.name, table.name] as const),
1626
1626
  ),
1627
1627
  );
1628
+ // Several instances of one table (a self-join) share one dependency and
1629
+ // one coverage entry only when their proofs are identical. Scopes follow
1630
+ // the table's declaration order, so only the parameter sets need sorting.
1631
+ const proofKey = (candidate: Candidate): string =>
1632
+ JSON.stringify(
1633
+ candidate.scopes.map((scope) => [
1634
+ scope.binding.variable,
1635
+ scope.operator,
1636
+ [...scope.binding.params].sort(),
1637
+ ]),
1638
+ );
1628
1639
  const dependencies = [
1629
1640
  ...new Set(refs.map((ref) => ftsOwners.get(ref.table) ?? ref.table)),
1630
1641
  ]
@@ -1633,28 +1644,18 @@ class Validator {
1633
1644
  const instances = resolvedCandidates.filter(
1634
1645
  (item) => item.ref.table === table,
1635
1646
  );
1647
+ const first = instances[0];
1636
1648
  if (
1637
- instances.length !== 1 ||
1638
- instances.some((item) => item.scopes.length === 0)
1649
+ first === undefined ||
1650
+ first.scopes.length === 0 ||
1651
+ instances.some((item) => proofKey(item) !== proofKey(first))
1639
1652
  ) {
1640
1653
  return { table, scopes: [] };
1641
1654
  }
1642
- const scopes = instances
1643
- .flatMap((item) => item.scopes.map((scope) => scope.binding))
1644
- .reduce<QueryScopeBinding[]>((out, scope) => {
1645
- const existing = out.find(
1646
- (item) => item.variable === scope.variable,
1647
- );
1648
- if (existing === undefined) out.push(scope);
1649
- else {
1650
- out[out.indexOf(existing)] = {
1651
- ...existing,
1652
- params: [...new Set([...existing.params, ...scope.params])],
1653
- };
1654
- }
1655
- return out;
1656
- }, []);
1657
- return { table, scopes };
1655
+ return {
1656
+ table,
1657
+ scopes: first.scopes.map((scope) => scope.binding),
1658
+ };
1658
1659
  });
1659
1660
 
1660
1661
  if (!logical.declaration.sync) return { dependencies, coverage: [] };
@@ -1667,9 +1668,6 @@ class Validator {
1667
1668
  );
1668
1669
  return (
1669
1670
  table !== undefined &&
1670
- syncedCandidates.filter(
1671
- (item) => item.ref.table === candidate.ref.table,
1672
- ).length === 1 &&
1673
1671
  table.scopes.length > 0 &&
1674
1672
  candidate.scopes.length === table.scopes.length
1675
1673
  );
@@ -1679,7 +1677,21 @@ class Validator {
1679
1677
  this.#fail(
1680
1678
  'SYQL6005_INVALID_SYNC_QUERY',
1681
1679
  logical.declaration.syncBy?.span ?? logical.declaration.nameSpan,
1682
- 'sync query coverage cannot be proven for every read table from required equality/IN predicates over every declared scope; split the query or add an exact compatible scope proof',
1680
+ 'sync query coverage cannot be proven for every read table instance from required equality/IN predicates over every declared scope; split the query or add an exact compatible scope proof',
1681
+ );
1682
+ }
1683
+ const divergent = eligible.find((candidate) =>
1684
+ eligible.some(
1685
+ (other) =>
1686
+ other.ref.table === candidate.ref.table &&
1687
+ proofKey(other) !== proofKey(candidate),
1688
+ ),
1689
+ );
1690
+ if (divergent !== undefined) {
1691
+ this.#fail(
1692
+ 'SYQL6005_INVALID_SYNC_QUERY',
1693
+ logical.declaration.syncBy?.span ?? logical.declaration.nameSpan,
1694
+ `sync query reads ${divergent.ref.table} through several instances whose scope proofs differ; every instance must bind the same scopes with the same operator and parameters, or the query must be split`,
1683
1695
  );
1684
1696
  }
1685
1697
  const byCandidate =
@@ -1737,61 +1749,67 @@ class Validator {
1737
1749
  ): boolean =>
1738
1750
  left.length === right.length &&
1739
1751
  left.every((value) => right.includes(value));
1740
- const coverage = eligible.map((candidate): QueryCoverageBinding => {
1741
- const table = this.#ir.tables.find(
1742
- (item) => item.name === candidate.ref.table,
1743
- );
1744
- if (table === undefined) throw new Error('eligible table disappeared');
1745
- const byVariable = new Map(
1746
- candidate.scopes.map((scope) => [scope.binding.variable, scope]),
1747
- );
1748
- let unit: InferredScope | undefined;
1749
- if (candidate === byCandidate) {
1750
- unit = anchorUnit;
1751
- } else if (table.scopes.length === 1) {
1752
- unit = candidate.scopes[0];
1753
- } else if (anchorUnit !== undefined) {
1754
- const matching = candidate.scopes.filter((scope) =>
1755
- sameParams(scope.binding.params, anchorUnit.binding.params),
1752
+ const coverage = eligible
1753
+ .filter(
1754
+ (candidate) =>
1755
+ eligible.find((item) => item.ref.table === candidate.ref.table) ===
1756
+ candidate,
1757
+ )
1758
+ .map((candidate): QueryCoverageBinding => {
1759
+ const table = this.#ir.tables.find(
1760
+ (item) => item.name === candidate.ref.table,
1756
1761
  );
1757
- if (matching.length === 1) unit = matching[0];
1758
- }
1759
- if (unit === undefined) {
1760
- this.#fail(
1761
- 'SYQL6005_INVALID_SYNC_QUERY',
1762
- syncBy?.span ?? logical.declaration.nameSpan,
1763
- `joined multi-scope table ${table.name} has no unambiguous unit dimension compatible with the selected anchor; split the query`,
1762
+ if (table === undefined) throw new Error('eligible table disappeared');
1763
+ const byVariable = new Map(
1764
+ candidate.scopes.map((scope) => [scope.binding.variable, scope]),
1764
1765
  );
1765
- }
1766
- const fixedScopes = table.scopes
1767
- .filter((scope) => scope.variable !== unit.binding.variable)
1768
- .map((scope) => {
1769
- const fixed = byVariable.get(scope.variable) as
1770
- | InferredScope
1771
- | undefined;
1772
- if (
1773
- fixed === undefined ||
1774
- fixed.operator !== 'equal' ||
1775
- fixed.binding.params.length !== 1
1776
- ) {
1777
- this.#fail(
1778
- 'SYQL6005_INVALID_SYNC_QUERY',
1779
- syncBy?.span ?? logical.declaration.nameSpan,
1780
- `fixed sync scope ${table.name}.${scope.column} must use one required equality bind`,
1781
- );
1782
- }
1783
- return {
1784
- variable: fixed.binding.variable,
1785
- params: fixed.binding.params,
1786
- };
1787
- });
1788
- return {
1789
- table: table.name,
1790
- variable: unit.binding.variable,
1791
- units: unit.binding.params,
1792
- fixedScopes,
1793
- };
1794
- });
1766
+ let unit: InferredScope | undefined;
1767
+ if (candidate.ref.table === byCandidate?.ref.table) {
1768
+ unit = anchorUnit;
1769
+ } else if (table.scopes.length === 1) {
1770
+ unit = candidate.scopes[0];
1771
+ } else if (anchorUnit !== undefined) {
1772
+ const matching = candidate.scopes.filter((scope) =>
1773
+ sameParams(scope.binding.params, anchorUnit.binding.params),
1774
+ );
1775
+ if (matching.length === 1) unit = matching[0];
1776
+ }
1777
+ if (unit === undefined) {
1778
+ this.#fail(
1779
+ 'SYQL6005_INVALID_SYNC_QUERY',
1780
+ syncBy?.span ?? logical.declaration.nameSpan,
1781
+ `joined multi-scope table ${table.name} has no unambiguous unit dimension compatible with the selected anchor; split the query`,
1782
+ );
1783
+ }
1784
+ const fixedScopes = table.scopes
1785
+ .filter((scope) => scope.variable !== unit.binding.variable)
1786
+ .map((scope) => {
1787
+ const fixed = byVariable.get(scope.variable) as
1788
+ | InferredScope
1789
+ | undefined;
1790
+ if (
1791
+ fixed === undefined ||
1792
+ fixed.operator !== 'equal' ||
1793
+ fixed.binding.params.length !== 1
1794
+ ) {
1795
+ this.#fail(
1796
+ 'SYQL6005_INVALID_SYNC_QUERY',
1797
+ syncBy?.span ?? logical.declaration.nameSpan,
1798
+ `fixed sync scope ${table.name}.${scope.column} must use one required equality bind`,
1799
+ );
1800
+ }
1801
+ return {
1802
+ variable: fixed.binding.variable,
1803
+ params: fixed.binding.params,
1804
+ };
1805
+ });
1806
+ return {
1807
+ table: table.name,
1808
+ variable: unit.binding.variable,
1809
+ units: unit.binding.params,
1810
+ fixedScopes,
1811
+ };
1812
+ });
1795
1813
  // Code-point order keeps emitted metadata byte-identical across locales.
1796
1814
  coverage.sort((left, right) =>
1797
1815
  left.table < right.table ? -1 : left.table > right.table ? 1 : 0,