@syncular/typegen 0.59.0 → 0.60.1

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 (47) hide show
  1. package/README.md +53 -18
  2. package/dist/emit-dart.js +7 -18
  3. package/dist/emit-kotlin.d.ts +1 -1
  4. package/dist/emit-kotlin.js +9 -20
  5. package/dist/emit-queries-rust.js +18 -14
  6. package/dist/emit-queries.js +19 -23
  7. package/dist/emit-swift.d.ts +1 -1
  8. package/dist/emit-swift.js +9 -20
  9. package/dist/emit.d.ts +2 -2
  10. package/dist/emit.js +9 -20
  11. package/dist/fmt.js +11 -2
  12. package/dist/generate.js +31 -26
  13. package/dist/init.js +4 -5
  14. package/dist/ir.d.ts +3 -2
  15. package/dist/ir.js +1 -2
  16. package/dist/lsp.js +6 -1
  17. package/dist/manifest.d.ts +1 -2
  18. package/dist/manifest.js +13 -12
  19. package/dist/query.d.ts +40 -0
  20. package/dist/query.js +159 -0
  21. package/dist/syql-ast.d.ts +2 -0
  22. package/dist/syql-ast.js +7 -1
  23. package/dist/syql-browser.js +7 -6
  24. package/dist/syql-diagnostics.d.ts +1 -0
  25. package/dist/syql-diagnostics.js +1 -0
  26. package/dist/syql-lowering.js +1 -0
  27. package/dist/syql-parser.d.ts +4 -1
  28. package/dist/syql-parser.js +42 -5
  29. package/package.json +3 -3
  30. package/src/emit-dart.ts +11 -22
  31. package/src/emit-kotlin.ts +13 -26
  32. package/src/emit-queries-rust.ts +22 -19
  33. package/src/emit-queries.ts +23 -38
  34. package/src/emit-swift.ts +15 -24
  35. package/src/emit.ts +15 -22
  36. package/src/fmt.ts +10 -2
  37. package/src/generate.ts +44 -36
  38. package/src/init.ts +4 -5
  39. package/src/ir.ts +4 -4
  40. package/src/lsp.ts +11 -4
  41. package/src/manifest.ts +22 -18
  42. package/src/query.ts +251 -0
  43. package/src/syql-ast.ts +9 -0
  44. package/src/syql-browser.ts +8 -7
  45. package/src/syql-diagnostics.ts +2 -0
  46. package/src/syql-lowering.ts +1 -0
  47. package/src/syql-parser.ts +73 -8
package/dist/ir.d.ts CHANGED
@@ -84,11 +84,12 @@ export type IrScopeValue = {
84
84
  };
85
85
  export interface IrSubscriptionScope {
86
86
  readonly variable: string;
87
- readonly values: readonly IrScopeValue[];
87
+ readonly value: IrScopeValue;
88
88
  }
89
+ /** A unit template (SPEC §4.1): one value per scope variable. The unit
90
+ * covers every table that declares all of its variables. */
89
91
  export interface IrSubscription {
90
92
  readonly name: string;
91
- readonly table: string;
92
93
  /** Sorted by variable for stable diffs. */
93
94
  readonly scopes: readonly IrSubscriptionScope[];
94
95
  }
package/dist/ir.js CHANGED
@@ -99,10 +99,9 @@ export function serializeIr(ir) {
99
99
  })),
100
100
  subscriptions: ir.subscriptions.map((sub) => ({
101
101
  name: sub.name,
102
- table: sub.table,
103
102
  scopes: sub.scopes.map((scope) => ({
104
103
  variable: scope.variable,
105
- values: scope.values.map(canonicalScopeValue),
104
+ value: canonicalScopeValue(scope.value),
106
105
  })),
107
106
  })),
108
107
  extensions: canonicalizeExtensions(ir.extensions),
package/dist/lsp.js CHANGED
@@ -7,6 +7,7 @@ import { formatSyql } from './fmt.js';
7
7
  import { buildIr, loadMigrations, loadQueries, makeQueryDb } from './generate.js';
8
8
  import { MANIFEST_FILENAME, parseManifest } from './manifest.js';
9
9
  import { lockedMigrationNames, readMigrationLock } from './migration-lock.js';
10
+ import { checkQueryPlan } from './query.js';
10
11
  import { syqlDiagnosticRemedy } from './syql-diagnostics.js';
11
12
  import { SyqlFrontendError } from './syql-lexer.js';
12
13
  import { lowerSyqlQuery } from './syql-lowering.js';
@@ -271,7 +272,11 @@ export class SyqlLanguageServer {
271
272
  throw new TypegenError(file, 'current SYQL module missing');
272
273
  const lowered = project === undefined
273
274
  ? []
274
- : validateSyqlProgram(semantic, project.ir, project.db, project.naming).queries.map((query) => lowerSyqlQuery(query, project.ir, project.db, project.naming));
275
+ : validateSyqlProgram(semantic, project.ir, project.db, project.naming).queries.map((query) => {
276
+ const result = lowerSyqlQuery(query, project.ir, project.db, project.naming);
277
+ checkQueryPlan(result.analysis, project.ir, project.db);
278
+ return result;
279
+ });
275
280
  return { root, file, module, semantic, lowered };
276
281
  }
277
282
  #publishDiagnostics(uri) {
@@ -22,8 +22,7 @@ export interface ManifestTable {
22
22
  }
23
23
  export interface ManifestSubscription {
24
24
  readonly name: string;
25
- readonly table: string;
26
- readonly scopes: Readonly<Record<string, readonly string[]>>;
25
+ readonly scopes: Readonly<Record<string, string>>;
27
26
  }
28
27
  export interface ManifestSchemaVersion {
29
28
  readonly version: number;
package/dist/manifest.js CHANGED
@@ -14,8 +14,8 @@
14
14
  * "dart": "./lib/syncular.generated.dart" },
15
15
  * "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
16
16
  * "tables": [{ "name": "tasks", "scopes": ["project:{project_id}"] }],
17
- * "subscriptions": [{ "name": "projectTasks", "table": "tasks",
18
- * "scopes": { "project_id": ["{projectId}"] } }],
17
+ * "subscriptions": [{ "name": "projectTasks",
18
+ * "scopes": { "project_id": "{projectId}" } }],
19
19
  * "extensions": {}
20
20
  * }
21
21
  * ```
@@ -24,8 +24,10 @@
24
24
  * - `schemaVersions` is the §1.5 version history: strictly increasing
25
25
  * versions, each naming the last migration it includes (`through`); the
26
26
  * final entry must cover the final migration.
27
- * - Subscription scope values are literals or whole-value `{param}`
28
- * placeholders (partial templates are unsupported).
27
+ * - A subscription is a unit template (SPEC §4.1): one literal or
28
+ * whole-value `{param}` placeholder per scope variable (partial templates
29
+ * are unsupported), no table. The unit covers every table declaring all of
30
+ * its variables; a template that covers no table is an error.
29
31
  * - `output.ir` / `output.module` are the always-emitted TS defaults;
30
32
  * `output.queryIr` opts into the deterministic analyzed-query document.
31
33
  * `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native schema
@@ -187,24 +189,23 @@ const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
187
189
  function parseSubscription(value, index) {
188
190
  const context = `subscriptions[${index}]`;
189
191
  const obj = asObject(value, context);
190
- rejectUnknownKeys(obj, ['name', 'table', 'scopes'], context);
191
192
  const name = asString(obj.name, `${context}.name`);
192
193
  if (!IDENTIFIER_RE.test(name)) {
193
194
  fail(`subscription ${JSON.stringify(name)}: name must be a valid identifier`);
194
195
  }
195
- const table = asString(obj.table, `subscription ${name}: table`);
196
196
  const scopesObj = asObject(obj.scopes, `subscription ${name}: scopes`);
197
+ if ('table' in obj || Object.values(scopesObj).some(Array.isArray)) {
198
+ throw new TypegenError(SOURCE, 'a subscription is a unit template { "name", "scopes": { "<variable>": "<value or {param}>" } } with one value per scope variable and no table (SPEC §4.1); several values are several templates', 'typegen.subscription_legacy_shape', { subscription: name });
199
+ }
200
+ rejectUnknownKeys(obj, ['name', 'scopes'], context);
197
201
  const scopes = {};
198
- for (const [variable, values] of Object.entries(scopesObj)) {
199
- if (!Array.isArray(values) || values.length === 0) {
200
- fail(`subscription ${name}: scopes.${variable} must be a non-empty array`);
201
- }
202
- scopes[variable] = values.map((v, i) => asString(v, `subscription ${name}: scopes.${variable}[${i}]`));
202
+ for (const [variable, scope] of Object.entries(scopesObj)) {
203
+ scopes[variable] = asString(scope, `subscription ${name}: scopes.${variable}`);
203
204
  }
204
205
  if (Object.keys(scopes).length === 0) {
205
206
  fail(`subscription ${name}: scopes must not be empty`);
206
207
  }
207
- return { name, table, scopes };
208
+ return { name, scopes };
208
209
  }
209
210
  function parseSchemaVersion(value, index) {
210
211
  const context = `schemaVersions[${index}]`;
package/dist/query.d.ts CHANGED
@@ -44,6 +44,20 @@ export interface QueryCoverageBinding {
44
44
  readonly params: readonly string[];
45
45
  }[];
46
46
  }
47
+ /** The window bases (SPEC §4.8) a query's coverage needs, for generated
48
+ * descriptors. A base names no table, so tables proven by the same base share
49
+ * one entry; a fixed scope bound to several params yields one base per value
50
+ * combination, since a base holds one value per fixed variable. Ordered by
51
+ * code point of the JSON so emitted metadata is byte-identical across
52
+ * locales. */
53
+ export declare function windowBases(coverage: readonly QueryCoverageBinding[]): {
54
+ readonly variable: string;
55
+ readonly units: readonly string[];
56
+ readonly fixedScopes: readonly {
57
+ variable: string;
58
+ param: string;
59
+ }[];
60
+ }[];
47
61
  export interface QueryReactiveMetadata {
48
62
  readonly dependencies: readonly {
49
63
  readonly table: string;
@@ -163,6 +177,16 @@ export interface QueryRelation {
163
177
  readonly end: number;
164
178
  readonly alias?: string;
165
179
  }
180
+ /** The findings of the query plan check (`docs/SYQL.md` §14.5). */
181
+ export declare const QUERY_PLAN_FINDINGS: readonly ['scan', 'automatic_index', 'unbounded', 'many_tables'];
182
+ export type QueryPlanFinding = (typeof QUERY_PLAN_FINDINGS)[number];
183
+ /** An author's acknowledgement of one plan finding, with its reason. */
184
+ export interface QueryAcknowledgement {
185
+ readonly finding: QueryPlanFinding;
186
+ /** Absent for `many_tables`. */
187
+ readonly table?: string;
188
+ readonly reason: string;
189
+ }
166
190
  export interface AnalyzedQuery {
167
191
  /** camelCase function name (path-derived, or a `-- name:` override). */
168
192
  readonly name: string;
@@ -188,6 +212,8 @@ export interface AnalyzedQuery {
188
212
  /** Revision-1 frontend/public-input and physical execution contract. When
189
213
  * present, emitters use this instead of treating `params` as the API. */
190
214
  readonly syql?: QuerySyqlMetadata;
215
+ /** Plan findings the author acknowledged on the statement. */
216
+ readonly acknowledgements: readonly QueryAcknowledgement[];
191
217
  }
192
218
  /** The public SYQL input an emitter binds by name. */
193
219
  export declare function syqlInput(query: AnalyzedQuery, name: string): QuerySyqlPublicInput;
@@ -332,6 +358,14 @@ export interface QueryDb {
332
358
  declaredTypes: readonly (string | null)[];
333
359
  paramsCount: number;
334
360
  };
361
+ /** The `EXPLAIN QUERY PLAN` rows of `sql`. With `index`, a `CREATE INDEX`
362
+ * statement, SQLite plans as if that index existed; the database keeps no
363
+ * trace of it afterwards. */
364
+ plan(sql: string, index?: string): readonly {
365
+ id: number;
366
+ parent: number;
367
+ detail: string;
368
+ }[];
335
369
  }
336
370
  /** Synthesize the schema DDL from the IR (the reverse of the migration
337
371
  * parser): a `CREATE TABLE` per IR table with each column's declared SQLite
@@ -377,3 +411,9 @@ export declare function analyzeQueryFile(relPath: string, content: string, ir: I
377
411
  * (or a `-- name:` override) and analyze. Rejects a `;`-separated file loudly
378
412
  * — use {@link analyzeQueryFile} for the multi-statement contract. */
379
413
  export declare function analyzeQuery(file: string, raw: string, ir: IrDocument, db: QueryDb, naming?: QueryNamingOptions): AnalyzedQuery;
414
+ /**
415
+ * The query plan check (`docs/SYQL.md` §14.5): plan every physical statement
416
+ * against the schema database and fail on the first finding the query does
417
+ * not acknowledge, then on the first acknowledgement that matches no finding.
418
+ */
419
+ export declare function checkQueryPlan(query: AnalyzedQuery, ir: IrDocument, db: QueryDb): void;
package/dist/query.js CHANGED
@@ -90,7 +90,39 @@ const DECLTYPE_MAP = {
90
90
  const SYNC_VERSION_COLUMN = '_sync_version';
91
91
  /** Stable private identity shared by every declared local FTS5 projection. */
92
92
  const FTS_SOURCE_ID_COLUMN = '_syncular_source_id';
93
+ /** The window bases (SPEC §4.8) a query's coverage needs, for generated
94
+ * descriptors. A base names no table, so tables proven by the same base share
95
+ * one entry; a fixed scope bound to several params yields one base per value
96
+ * combination, since a base holds one value per fixed variable. Ordered by
97
+ * code point of the JSON so emitted metadata is byte-identical across
98
+ * locales. */
99
+ export function windowBases(coverage) {
100
+ const bases = coverage.flatMap((entry) => {
101
+ let combinations = [[]];
102
+ for (const scope of entry.fixedScopes) {
103
+ combinations = combinations.flatMap((combination) => scope.params.map((param) => [
104
+ ...combination,
105
+ { variable: scope.variable, param },
106
+ ]));
107
+ }
108
+ return combinations.map((fixedScopes) => ({
109
+ variable: entry.variable,
110
+ units: entry.units,
111
+ fixedScopes,
112
+ }));
113
+ });
114
+ return [...new Map(bases.map((base) => [JSON.stringify(base), base]))]
115
+ .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
116
+ .map(([, base]) => base);
117
+ }
93
118
  const DEFAULT_NAMING = { naming: 'camel', targets: ['ts'] };
119
+ /** The findings of the query plan check (`docs/SYQL.md` §14.5). */
120
+ export const QUERY_PLAN_FINDINGS = [
121
+ 'scan',
122
+ 'automatic_index',
123
+ 'unbounded',
124
+ 'many_tables',
125
+ ];
94
126
  /** The public SYQL input an emitter binds by name. */
95
127
  export function syqlInput(query, name) {
96
128
  const input = query.syql?.inputs.find((candidate) => candidate.name === name);
@@ -262,6 +294,31 @@ function parseCommentParams(file, raw) {
262
294
  }
263
295
  return out;
264
296
  }
297
+ const ACKNOWLEDGEMENT_RE = new RegExp(`^--\\s*allow\\s+(${QUERY_PLAN_FINDINGS.join('|')})\\b`);
298
+ /** Parse the `-- allow <finding> [table]: <reason>` acknowledgements of the
299
+ * leading comment block (`docs/SYQL.md` §14.5). */
300
+ function parseCommentAcknowledgements(file, raw) {
301
+ const out = [];
302
+ for (const comment of leadingComments(raw)) {
303
+ const kind = ACKNOWLEDGEMENT_RE.exec(comment)?.[1];
304
+ const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind);
305
+ if (finding === undefined)
306
+ continue;
307
+ const match = /^--\s*allow\s+\w+(?:\s+([A-Za-z_][A-Za-z0-9_]*))?\s*:\s*(\S.*?)\s*$/.exec(comment);
308
+ const table = match?.[1];
309
+ if (match === null ||
310
+ (finding === 'many_tables') !== (table === undefined) ||
311
+ out.some((other) => other.finding === finding && other.table === table)) {
312
+ throw new TypegenError(file, 'invalid query plan acknowledgement; write `-- allow <finding> <table>: <reason>` once per finding', 'typegen.query_acknowledgement_invalid', { file, comment });
313
+ }
314
+ out.push({
315
+ finding,
316
+ ...(table === undefined ? {} : { table }),
317
+ reason: match[2],
318
+ });
319
+ }
320
+ return out;
321
+ }
265
322
  /** Blank comments and string/blob literals with spaces (newlines kept), so
266
323
  * offset-preserving text scans never read inside them. */
267
324
  export function stripCommentsAndStrings(sql) {
@@ -1287,6 +1344,7 @@ export function lowerFtsSourceIds(sql, ir) {
1287
1344
  export function analyzeStatement(name, location, statementText, ir, db, naming = DEFAULT_NAMING) {
1288
1345
  const file = location;
1289
1346
  const commentParams = parseCommentParams(file, statementText);
1347
+ const acknowledgements = parseCommentAcknowledgements(file, statementText);
1290
1348
  const sourceSql = statementText.trim();
1291
1349
  if (sourceSql.length === 0) {
1292
1350
  throw new TypegenError(file, 'query file is empty');
@@ -1541,6 +1599,7 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
1541
1599
  columns,
1542
1600
  tables,
1543
1601
  reactive,
1602
+ acknowledgements,
1544
1603
  };
1545
1604
  }
1546
1605
  /**
@@ -1583,3 +1642,103 @@ export function analyzeQuery(file, raw, ir, db, naming = DEFAULT_NAMING) {
1583
1642
  const results = analyzeQueryFile(file, raw, ir, db, naming);
1584
1643
  return results[0];
1585
1644
  }
1645
+ /**
1646
+ * The query plan check (`docs/SYQL.md` §14.5): plan every physical statement
1647
+ * against the schema database and fail on the first finding the query does
1648
+ * not acknowledge, then on the first acknowledgement that matches no finding.
1649
+ */
1650
+ export function checkQueryPlan(query, ir, db) {
1651
+ const findings = [];
1652
+ const tables = new Map(ir.tables.map((table) => [table.name, table]));
1653
+ const statements = query.syql?.plan.statements ?? [query];
1654
+ statements.forEach(({ positionalSql: sql, relations }, statement) => {
1655
+ const rows = db.plan(sql);
1656
+ const plan = rows.map((row) => row.detail);
1657
+ const scans = (details) => details.filter((detail) => detail.startsWith('SCAN ') && !detail.includes(' VIRTUAL TABLE')).length;
1658
+ // A plan names a relation by its alias, or by its table when unaliased.
1659
+ const tableOf = (name) => relations.find((relation) => (relation.alias ?? relation.table) === name)
1660
+ ?.table ?? name;
1661
+ const context = { query: query.name, file: query.file, statement, sql };
1662
+ for (const detail of plan) {
1663
+ const automatic = /^SEARCH (\S+) USING AUTOMATIC (?:PARTIAL )?(?:COVERING )?INDEX \((.*)\)/.exec(detail);
1664
+ if (automatic === null)
1665
+ continue;
1666
+ const table = tableOf(automatic[1]);
1667
+ findings.push({
1668
+ finding: 'automatic_index',
1669
+ table,
1670
+ details: {
1671
+ ...context,
1672
+ table,
1673
+ columns: [...automatic[2].matchAll(/(\w+)[=<>]/g)].map((key) => key[1]),
1674
+ plan,
1675
+ },
1676
+ });
1677
+ }
1678
+ const scanCount = scans(plan);
1679
+ if (scanCount > 0) {
1680
+ for (const table of [
1681
+ ...new Set(relations.map((relation) => relation.table)),
1682
+ ]) {
1683
+ const columns = (tables.get(table)?.columns ?? [])
1684
+ .map((column) => column.name)
1685
+ .filter((column) => scans(db
1686
+ .plan(sql, `CREATE INDEX "__syncular_plan_probe" ON "${table}" ("${column}")`)
1687
+ .map((row) => row.detail)) < scanCount);
1688
+ if (columns.length > 0) {
1689
+ findings.push({
1690
+ finding: 'scan',
1691
+ table,
1692
+ details: { ...context, table, columns, plan },
1693
+ });
1694
+ }
1695
+ }
1696
+ }
1697
+ const { tokens, depths } = sqlStructure(sql);
1698
+ const bounded = tokens.some((token, index) => depths[index] === 0 &&
1699
+ ['where', 'limit'].includes(lowerWord(token) ?? ''));
1700
+ const topScan = rows.find((row) => row.parent === 0 &&
1701
+ scans([row.detail]) === 1 &&
1702
+ tables.has(tableOf(row.detail.split(' ')[1])));
1703
+ if (!bounded && topScan !== undefined) {
1704
+ const table = tableOf(topScan.detail.split(' ')[1]);
1705
+ findings.push({
1706
+ finding: 'unbounded',
1707
+ table,
1708
+ details: { ...context, table, plan },
1709
+ });
1710
+ }
1711
+ });
1712
+ const dependencies = [
1713
+ ...new Set(query.reactive.dependencies.map(({ table }) => table)),
1714
+ ].sort();
1715
+ if (dependencies.length > 4) {
1716
+ findings.push({
1717
+ finding: 'many_tables',
1718
+ details: { query: query.name, file: query.file, tables: dependencies },
1719
+ });
1720
+ }
1721
+ const messages = {
1722
+ scan: 'the query plan scans a table that an index on one of the listed columns would let SQLite search; declare the index or acknowledge the finding',
1723
+ automatic_index: 'the query plan builds an automatic index on every run; declare an index on the listed columns or acknowledge the finding',
1724
+ unbounded: 'the query reads every row of a table, with no WHERE and no LIMIT; bound the query or acknowledge the finding',
1725
+ many_tables: 'the query reads more than four tables, and a change to any of them re-runs it; split the query or acknowledge the finding',
1726
+ };
1727
+ const acknowledged = (acknowledgement, found) => acknowledgement.finding === found.finding &&
1728
+ acknowledgement.table === found.table;
1729
+ for (const found of findings) {
1730
+ if (!query.acknowledgements.some((ack) => acknowledged(ack, found))) {
1731
+ throw new TypegenError(query.file, messages[found.finding], `typegen.query_${found.finding}`, found.details);
1732
+ }
1733
+ }
1734
+ for (const ack of query.acknowledgements) {
1735
+ if (!findings.some((found) => acknowledged(ack, found))) {
1736
+ throw new TypegenError(query.file, 'the query plan acknowledgement matches no finding of its query; remove it', 'typegen.query_acknowledgement_unused', {
1737
+ query: query.name,
1738
+ file: query.file,
1739
+ finding: ack.finding,
1740
+ table: ack.table ?? null,
1741
+ });
1742
+ }
1743
+ }
1744
+ }
@@ -1,4 +1,5 @@
1
1
  /** Stable, span-free semantic AST used by revision-1 conformance fixtures. */
2
+ import type { QueryAcknowledgement } from './query.js';
2
3
  import { type SyqlToken } from './syql-lexer.js';
3
4
  import type { SyqlSyntaxFile, SyqlTemplate, SyqlValueType } from './syql-parser.js';
4
5
  export interface SyqlSemanticToken {
@@ -77,6 +78,7 @@ export type SyqlSemanticDeclaration = {
77
78
  readonly defaultSize: number;
78
79
  readonly maxSize: number;
79
80
  };
81
+ readonly acknowledgements?: readonly QueryAcknowledgement[];
80
82
  };
81
83
  export interface SyqlSemanticFile {
82
84
  readonly kind: 'syql-file';
package/dist/syql-ast.js CHANGED
@@ -1,4 +1,3 @@
1
- /** Stable, span-free semantic AST used by revision-1 conformance fixtures. */
2
1
  import { isSyqlTrivia } from './syql-lexer.js';
3
2
  function semanticType(type) {
4
3
  return type === undefined
@@ -125,6 +124,13 @@ function semanticDeclaration(declaration) {
125
124
  maxSize: declaration.limit.maxSize,
126
125
  },
127
126
  }),
127
+ ...(declaration.acknowledgements.length === 0
128
+ ? {}
129
+ : {
130
+ acknowledgements: declaration.acknowledgements.map((ack) => ({
131
+ ...ack,
132
+ })),
133
+ }),
128
134
  };
129
135
  }
130
136
  /** Return the stable syntax/semantic AST pinned by `spec/syql` fixtures. */
@@ -7,7 +7,7 @@
7
7
  * keep using the normal project generator.
8
8
  */
9
9
  import { formatSyql } from './fmt.js';
10
- import { synthesizeDdl, } from './query.js';
10
+ import { checkQueryPlan, synthesizeDdl, } from './query.js';
11
11
  import { SyqlFrontendError } from './syql-lexer.js';
12
12
  import { lowerSyqlQuery } from './syql-lowering.js';
13
13
  import { parseSyqlSyntaxFile } from './syql-parser.js';
@@ -34,11 +34,12 @@ export function compileSyqlSource(source, ir, db, options = {}) {
34
34
  const file = options.file ?? SYQL_BROWSER_DEFAULT_FILE;
35
35
  const semantic = analyzeSyqlSemantics(singleFileGraph(file, source));
36
36
  const validated = validateSyqlProgram(semantic, ir, db, options.naming);
37
- return {
38
- queries: validated.queries.map((query) => lowerSyqlQuery(query, ir, db, options.naming, {
39
- ...(options.backend === undefined ? {} : { backend: options.backend }),
40
- })),
41
- };
37
+ const queries = validated.queries.map((query) => lowerSyqlQuery(query, ir, db, options.naming, {
38
+ ...(options.backend === undefined ? {} : { backend: options.backend }),
39
+ }));
40
+ for (const query of queries)
41
+ checkQueryPlan(query.analysis, ir, db);
42
+ return { queries };
42
43
  }
43
44
  /** Format one virtual source file with the canonical SYQL formatter. */
44
45
  export function formatSyqlSource(source, file = SYQL_BROWSER_DEFAULT_FILE) {
@@ -25,6 +25,7 @@ export declare const SYQL_DIAGNOSTIC_REMEDIES: {
25
25
  readonly SYQL2010_INVALID_PAGE_RANGE: 'Choose default and maximum page sizes that satisfy the declared range.';
26
26
  readonly SYQL2011_INVALID_PARAMETER: 'Rewrite the parameter using a supported value, optional, range, group, sort, or limit form.';
27
27
  readonly SYQL2012_INVALID_QUERY_BODY: 'Rewrite the query body using the clause order and forms defined by the SYQL grammar.';
28
+ readonly SYQL2013_INVALID_ACKNOWLEDGEMENT: "Write the acknowledgement as allow <finding> <table> '<reason>' directly above a query, once per finding.";
28
29
  readonly SYQL3001_EXPECTED_EMBEDDED_TOKEN: 'Insert the required token in the embedded SQL construct.';
29
30
  readonly SYQL3002_INVALID_BIND: 'Bind a declared input with the :name form in a supported SQL position.';
30
31
  readonly SYQL3003_INVALID_PREDICATE_CALL: 'Call the predicate with declared bind arguments and matching parentheses.';
@@ -16,6 +16,7 @@ export const SYQL_DIAGNOSTIC_REMEDIES = {
16
16
  SYQL2010_INVALID_PAGE_RANGE: 'Choose default and maximum page sizes that satisfy the declared range.',
17
17
  SYQL2011_INVALID_PARAMETER: 'Rewrite the parameter using a supported value, optional, range, group, sort, or limit form.',
18
18
  SYQL2012_INVALID_QUERY_BODY: 'Rewrite the query body using the clause order and forms defined by the SYQL grammar.',
19
+ SYQL2013_INVALID_ACKNOWLEDGEMENT: "Write the acknowledgement as allow <finding> <table> '<reason>' directly above a query, once per finding.",
19
20
  SYQL3001_EXPECTED_EMBEDDED_TOKEN: 'Insert the required token in the embedded SQL construct.',
20
21
  SYQL3002_INVALID_BIND: 'Bind a declared input with the :name form in a supported SQL position.',
21
22
  SYQL3003_INVALID_PREDICATE_CALL: 'Call the predicate with declared bind arguments and matching parentheses.',
@@ -433,6 +433,7 @@ export function lowerSyqlQuery(validated, ir, db, naming = DEFAULT_NAMING, optio
433
433
  file: logical.module.file,
434
434
  reactive: validated.reactive,
435
435
  syql: metadata,
436
+ acknowledgements: logical.declaration.acknowledgements,
436
437
  };
437
438
  return {
438
439
  validated,
@@ -1,5 +1,6 @@
1
1
  /** Revision-1 SYQL container parser (`docs/SYQL.md` §3). */
2
2
  import { type SyqlSourceSpan, type SyqlToken } from './syql-lexer.js';
3
+ import { type QueryAcknowledgement } from './query.js';
3
4
  import { type SyqlEmbeddedTemplate } from './syql-template-parser.js';
4
5
  export type SyqlBaseType = 'string' | 'integer' | 'float' | 'boolean' | 'json' | 'bytes' | 'blob_ref' | 'crdt';
5
6
  export interface SyqlValueType {
@@ -113,6 +114,8 @@ export interface SyqlQueryDeclaration {
113
114
  readonly statement: SyqlTemplate;
114
115
  readonly sort?: SyqlSortSection;
115
116
  readonly limit?: SyqlLimitDeclaration;
117
+ /** Query plan findings acknowledged before the declaration (§14.5). */
118
+ readonly acknowledgements: readonly QueryAcknowledgement[];
116
119
  readonly span: SyqlSourceSpan;
117
120
  readonly nameSpan: SyqlSourceSpan;
118
121
  }
@@ -128,6 +131,6 @@ export interface SyqlSyntaxFile {
128
131
  readonly queries: readonly SyqlQueryDeclaration[];
129
132
  readonly span: SyqlSourceSpan;
130
133
  }
131
- export type SyqlParseErrorCode = 'SYQL2001_EXPECTED_TOKEN' | 'SYQL2002_INVALID_NAME' | 'SYQL2003_RESERVED_NAME' | 'SYQL2004_DUPLICATE_NAME' | 'SYQL2005_INVALID_IMPORT' | 'SYQL2006_EMPTY_TEMPLATE' | 'SYQL2007_FORBIDDEN_SEMICOLON' | 'SYQL2008_INVALID_MEMBER' | 'SYQL2009_INVALID_INTEGER' | 'SYQL2010_INVALID_PAGE_RANGE' | 'SYQL2011_INVALID_PARAMETER' | 'SYQL2012_INVALID_QUERY_BODY';
134
+ export type SyqlParseErrorCode = 'SYQL2001_EXPECTED_TOKEN' | 'SYQL2002_INVALID_NAME' | 'SYQL2003_RESERVED_NAME' | 'SYQL2004_DUPLICATE_NAME' | 'SYQL2005_INVALID_IMPORT' | 'SYQL2006_EMPTY_TEMPLATE' | 'SYQL2007_FORBIDDEN_SEMICOLON' | 'SYQL2008_INVALID_MEMBER' | 'SYQL2009_INVALID_INTEGER' | 'SYQL2010_INVALID_PAGE_RANGE' | 'SYQL2011_INVALID_PARAMETER' | 'SYQL2012_INVALID_QUERY_BODY' | 'SYQL2013_INVALID_ACKNOWLEDGEMENT';
132
135
  /** Parse one `.syql` file using the destructive revision-1 grammar. */
133
136
  export declare function parseSyqlSyntaxFile(file: string, source: string): SyqlSyntaxFile;
@@ -1,5 +1,6 @@
1
1
  /** Revision-1 SYQL container parser (`docs/SYQL.md` §3). */
2
2
  import { isSyqlTrivia, lexSyqlSource, SyqlFrontendError, } from './syql-lexer.js';
3
+ import { QUERY_PLAN_FINDINGS } from './query.js';
3
4
  import { parseSyqlEmbeddedTemplate, } from './syql-template-parser.js';
4
5
  const CAMEL_IDENT_RE = /^[a-z][A-Za-z0-9]*$/;
5
6
  const INTEGER_LITERAL_RE = /^(?:0|[1-9][0-9]*)$/;
@@ -82,20 +83,26 @@ class Parser {
82
83
  continue;
83
84
  }
84
85
  sawDeclaration = true;
85
- if (keyword.text === 'predicate') {
86
+ const acknowledgements = this.#parseAcknowledgements();
87
+ const next = this.#peek();
88
+ if (acknowledgements.length === 0 && next.text === 'predicate') {
86
89
  const declaration = this.#parsePredicate();
87
90
  this.#claimName(fileNames, declaration.name, declaration.nameSpan, 'declaration');
88
91
  declarations.push(declaration);
89
92
  predicates.push(declaration);
90
93
  }
91
- else if (keyword.text === 'query' || keyword.text === 'sync') {
92
- const declaration = this.#parseQuery(keyword.text === 'sync');
94
+ else if (next.text === 'query' || next.text === 'sync') {
95
+ const declaration = this.#parseQuery(next.text === 'sync', acknowledgements);
93
96
  this.#claimName(fileNames, declaration.name, declaration.nameSpan, 'declaration');
94
97
  declarations.push(declaration);
95
98
  queries.push(declaration);
96
99
  }
97
100
  else {
98
- this.#fail('SYQL2008_INVALID_MEMBER', keyword, `expected import, predicate, query, or sync query; found ${JSON.stringify(keyword.text)}`);
101
+ this.#fail(acknowledgements.length > 0
102
+ ? 'SYQL2013_INVALID_ACKNOWLEDGEMENT'
103
+ : 'SYQL2008_INVALID_MEMBER', next, acknowledgements.length > 0
104
+ ? `a query plan acknowledgement precedes a query declaration; found ${JSON.stringify(next.text || 'end of file')}`
105
+ : `expected import, predicate, query, or sync query; found ${JSON.stringify(next.text)}`);
99
106
  }
100
107
  }
101
108
  const first = this.#tokens[0];
@@ -200,7 +207,36 @@ class Parser {
200
207
  nameSpan: name.span,
201
208
  };
202
209
  }
203
- #parseQuery(sync) {
210
+ #parseAcknowledgements() {
211
+ const out = [];
212
+ while (this.#peek().text === 'allow') {
213
+ const start = this.#take();
214
+ const kind = this.#take();
215
+ const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind.text);
216
+ if (finding === undefined) {
217
+ this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', kind, `expected a query plan finding (${QUERY_PLAN_FINDINGS.join(', ')}), found ${JSON.stringify(kind.text || 'end of file')}`);
218
+ }
219
+ const table = finding === 'many_tables' ? undefined : this.#take();
220
+ if (table !== undefined && table.kind !== 'identifier') {
221
+ this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', table, `expected the table the finding names, found ${JSON.stringify(table.text || 'end of file')}`);
222
+ }
223
+ const reason = this.#take();
224
+ const text = reason.text.slice(1, -1).split("''").join("'");
225
+ if (reason.kind !== 'string' || text.trim() === '') {
226
+ this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', reason, 'a query plan acknowledgement ends with a non-blank reason string');
227
+ }
228
+ if (out.some((ack) => ack.finding === finding && ack.table === table?.text)) {
229
+ this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', start, 'the query already acknowledges this finding');
230
+ }
231
+ out.push({
232
+ finding,
233
+ ...(table === undefined ? {} : { table: table.text }),
234
+ reason: text,
235
+ });
236
+ }
237
+ return out;
238
+ }
239
+ #parseQuery(sync, acknowledgements) {
204
240
  const start = sync ? this.#expectText('sync') : this.#peek();
205
241
  this.#expectText('query');
206
242
  const name = this.#parseCamelName('query name');
@@ -257,6 +293,7 @@ class Parser {
257
293
  statement: body.statement,
258
294
  ...(body.sort === undefined ? {} : { sort: body.sort }),
259
295
  ...(body.limit === undefined ? {} : { limit: body.limit }),
296
+ acknowledgements,
260
297
  span: spanBetween(start, body.close),
261
298
  nameSpan: name.span,
262
299
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/typegen",
3
- "version": "0.59.0",
3
+ "version": "0.60.1",
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.59.0"
59
+ "@syncular/core": "0.60.1"
60
60
  },
61
61
  "devDependencies": {
62
- "@syncular/server": "0.59.0"
62
+ "@syncular/server": "0.60.1"
63
63
  }
64
64
  }
package/src/emit-dart.ts CHANGED
@@ -98,40 +98,29 @@ function emitClass(table: IrTable): string[] {
98
98
  }
99
99
 
100
100
  function emitSubscription(sub: IrSubscription): string[] {
101
- const params: string[] = [];
102
- for (const scope of sub.scopes) {
103
- for (const value of scope.values) {
104
- if (value.kind === 'parameter' && !params.includes(value.name)) {
105
- params.push(value.name);
106
- }
107
- }
108
- }
101
+ const params = [
102
+ ...new Set(
103
+ sub.scopes.flatMap(({ value }) =>
104
+ value.kind === 'parameter' ? [value.name] : [],
105
+ ),
106
+ ),
107
+ ];
109
108
  const lines: string[] = [];
110
109
  lines.push(
111
- `/// Requested-scope template for the ${stringLiteral(sub.name, 'dart')} subscription.`,
110
+ `/// Unit template for the ${stringLiteral(sub.name, 'dart')} subscription (SPEC §4.1).`,
112
111
  );
113
112
  lines.push(`class Syncular${pascalCase(sub.name)}Subscription {`);
114
113
  lines.push(
115
114
  ` static const String name = ${stringLiteral(sub.name, 'dart')};`,
116
115
  );
117
- lines.push(
118
- ` static const String table = ${stringLiteral(sub.table, 'dart')};`,
119
- );
120
116
  const args = params
121
117
  .map((p) => `required String ${snakeToCamel(p)}`)
122
118
  .join(', ');
123
119
  const argsClause = args.length > 0 ? `{${args}}` : '';
124
- lines.push(` static Map<String, List<String>> scopes(${argsClause}) => {`);
125
- for (const scope of sub.scopes) {
126
- const values = scope.values
127
- .map((value) =>
128
- value.kind === 'literal'
129
- ? stringLiteral(value.value, 'dart')
130
- : snakeToCamel(value.name),
131
- )
132
- .join(', ');
120
+ lines.push(` static Map<String, String> scopes(${argsClause}) => {`);
121
+ for (const { variable, value } of sub.scopes) {
133
122
  lines.push(
134
- ` ${stringLiteral(scope.variable, 'dart')}: [${values}],`,
123
+ ` ${stringLiteral(variable, 'dart')}: ${value.kind === 'literal' ? stringLiteral(value.value, 'dart') : snakeToCamel(value.name)},`,
135
124
  );
136
125
  }
137
126
  lines.push(' };');