@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.
- package/README.md +53 -18
- package/dist/emit-dart.js +7 -18
- package/dist/emit-kotlin.d.ts +1 -1
- package/dist/emit-kotlin.js +9 -20
- package/dist/emit-queries-rust.js +18 -14
- package/dist/emit-queries.js +19 -23
- package/dist/emit-swift.d.ts +1 -1
- package/dist/emit-swift.js +9 -20
- package/dist/emit.d.ts +2 -2
- package/dist/emit.js +9 -20
- package/dist/fmt.js +11 -2
- package/dist/generate.js +31 -26
- package/dist/init.js +4 -5
- package/dist/ir.d.ts +3 -2
- package/dist/ir.js +1 -2
- package/dist/lsp.js +6 -1
- package/dist/manifest.d.ts +1 -2
- package/dist/manifest.js +13 -12
- package/dist/query.d.ts +40 -0
- package/dist/query.js +159 -0
- package/dist/syql-ast.d.ts +2 -0
- package/dist/syql-ast.js +7 -1
- package/dist/syql-browser.js +7 -6
- package/dist/syql-diagnostics.d.ts +1 -0
- package/dist/syql-diagnostics.js +1 -0
- package/dist/syql-lowering.js +1 -0
- package/dist/syql-parser.d.ts +4 -1
- package/dist/syql-parser.js +42 -5
- package/package.json +3 -3
- package/src/emit-dart.ts +11 -22
- package/src/emit-kotlin.ts +13 -26
- package/src/emit-queries-rust.ts +22 -19
- package/src/emit-queries.ts +23 -38
- package/src/emit-swift.ts +15 -24
- package/src/emit.ts +15 -22
- package/src/fmt.ts +10 -2
- package/src/generate.ts +44 -36
- package/src/init.ts +4 -5
- package/src/ir.ts +4 -4
- package/src/lsp.ts +11 -4
- package/src/manifest.ts +22 -18
- package/src/query.ts +251 -0
- package/src/syql-ast.ts +9 -0
- package/src/syql-browser.ts +8 -7
- package/src/syql-diagnostics.ts +2 -0
- package/src/syql-lowering.ts +1 -0
- 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
|
|
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
|
-
|
|
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) =>
|
|
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) {
|
package/dist/manifest.d.ts
CHANGED
|
@@ -22,8 +22,7 @@ export interface ManifestTable {
|
|
|
22
22
|
}
|
|
23
23
|
export interface ManifestSubscription {
|
|
24
24
|
readonly name: string;
|
|
25
|
-
readonly
|
|
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",
|
|
18
|
-
* "scopes": { "project_id":
|
|
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
|
-
* -
|
|
28
|
-
*
|
|
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,
|
|
199
|
-
|
|
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,
|
|
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
|
+
}
|
package/dist/syql-ast.d.ts
CHANGED
|
@@ -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. */
|
package/dist/syql-browser.js
CHANGED
|
@@ -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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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.';
|
package/dist/syql-diagnostics.js
CHANGED
|
@@ -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.',
|
package/dist/syql-lowering.js
CHANGED
|
@@ -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,
|
package/dist/syql-parser.d.ts
CHANGED
|
@@ -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;
|
package/dist/syql-parser.js
CHANGED
|
@@ -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
|
-
|
|
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 (
|
|
92
|
-
const declaration = this.#parseQuery(
|
|
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(
|
|
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
|
-
#
|
|
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.
|
|
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
|
+
"@syncular/core": "0.60.1"
|
|
60
60
|
},
|
|
61
61
|
"devDependencies": {
|
|
62
|
-
"@syncular/server": "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
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
`///
|
|
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,
|
|
125
|
-
for (const
|
|
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(
|
|
123
|
+
` ${stringLiteral(variable, 'dart')}: ${value.kind === 'literal' ? stringLiteral(value.value, 'dart') : snakeToCamel(value.name)},`,
|
|
135
124
|
);
|
|
136
125
|
}
|
|
137
126
|
lines.push(' };');
|