@syncular/typegen 0.61.0 → 0.62.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
@@ -738,6 +738,11 @@ An acknowledgement without a reason fails with
738
738
  `.syql`), and one that matches no finding of its query fails with
739
739
  `typegen.query_acknowledgement_unused`.
740
740
 
741
+ A query that only the server runs as a registered query takes
742
+ `allow plan '<reason>'` (`-- allow plan: <reason>` in `.sql`) instead: it
743
+ acknowledges every finding of that query, because the server's database plans
744
+ it with the server's indexes.
745
+
741
746
  **Emitted SQL.** Wrappers take **positional** params (`query(sql, params[])`),
742
747
  so the emitted SQL rewrites `:name` → `?` (repeats included) and each runner
743
748
  reorders the named params object into the positional array. Comments are
package/dist/query.d.ts CHANGED
@@ -180,10 +180,11 @@ export interface QueryRelation {
180
180
  /** The findings of the query plan check (`docs/SYQL.md` §14.5). */
181
181
  export declare const QUERY_PLAN_FINDINGS: readonly ['scan', 'automatic_index', 'unbounded', 'many_tables'];
182
182
  export type QueryPlanFinding = (typeof QUERY_PLAN_FINDINGS)[number];
183
- /** An author's acknowledgement of one plan finding, with its reason. */
183
+ /** An author's acknowledgement of one plan finding, with its reason.
184
+ * `plan` acknowledges every finding of a query only the server runs. */
184
185
  export interface QueryAcknowledgement {
185
- readonly finding: QueryPlanFinding;
186
- /** Absent for `many_tables`. */
186
+ readonly finding: QueryPlanFinding | 'plan';
187
+ /** Absent for `many_tables` and `plan`. */
187
188
  readonly table?: string;
188
189
  readonly reason: string;
189
190
  }
package/dist/query.js CHANGED
@@ -294,21 +294,23 @@ function parseCommentParams(file, raw) {
294
294
  }
295
295
  return out;
296
296
  }
297
- const ACKNOWLEDGEMENT_RE = new RegExp(`^--\\s*allow\\s+(${QUERY_PLAN_FINDINGS.join('|')})\\b`);
297
+ const ACKNOWLEDGEMENT_RE = new RegExp(`^--\\s*allow\\s+(${QUERY_PLAN_FINDINGS.join('|')}|plan)\\b`);
298
298
  /** Parse the `-- allow <finding> [table]: <reason>` acknowledgements of the
299
299
  * leading comment block (`docs/SYQL.md` §14.5). */
300
300
  function parseCommentAcknowledgements(file, raw) {
301
301
  const out = [];
302
302
  for (const comment of leadingComments(raw)) {
303
303
  const kind = ACKNOWLEDGEMENT_RE.exec(comment)?.[1];
304
- const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind);
304
+ const finding = [...QUERY_PLAN_FINDINGS, 'plan'].find((name) => name === kind);
305
305
  if (finding === undefined)
306
306
  continue;
307
307
  const match = /^--\s*allow\s+\w+(?:\s+([A-Za-z_][A-Za-z0-9_]*))?\s*:\s*(\S.*?)\s*$/.exec(comment);
308
308
  const table = match?.[1];
309
309
  if (match === null ||
310
- (finding === 'many_tables') !== (table === undefined) ||
311
- out.some((other) => other.finding === finding && other.table === table)) {
310
+ (finding === 'many_tables' || finding === 'plan') !==
311
+ (table === undefined) ||
312
+ out.some((other) => (other.finding === finding && other.table === table) ||
313
+ (other.finding === 'plan') !== (finding === 'plan'))) {
312
314
  throw new TypegenError(file, 'invalid query plan acknowledgement; write `-- allow <finding> <table>: <reason>` once per finding', 'typegen.query_acknowledgement_invalid', { file, comment });
313
315
  }
314
316
  out.push({
@@ -1724,8 +1726,9 @@ export function checkQueryPlan(query, ir, db) {
1724
1726
  unbounded: 'the query reads every row of a table, with no WHERE and no LIMIT; bound the query or acknowledge the finding',
1725
1727
  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
1728
  };
1727
- const acknowledged = (acknowledgement, found) => acknowledgement.finding === found.finding &&
1728
- acknowledgement.table === found.table;
1729
+ const acknowledged = (acknowledgement, found) => acknowledgement.finding === 'plan' ||
1730
+ (acknowledgement.finding === found.finding &&
1731
+ acknowledgement.table === found.table);
1729
1732
  for (const found of findings) {
1730
1733
  if (!query.acknowledgements.some((ack) => acknowledged(ack, found))) {
1731
1734
  throw new TypegenError(query.file, messages[found.finding], `typegen.query_${found.finding}`, found.details);
@@ -212,11 +212,13 @@ class Parser {
212
212
  while (this.#peek().text === 'allow') {
213
213
  const start = this.#take();
214
214
  const kind = this.#take();
215
- const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind.text);
215
+ const finding = [...QUERY_PLAN_FINDINGS, 'plan'].find((name) => name === kind.text);
216
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')}`);
217
+ this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', kind, `expected a query plan finding (${QUERY_PLAN_FINDINGS.join(', ')}) or plan, found ${JSON.stringify(kind.text || 'end of file')}`);
218
218
  }
219
- const table = finding === 'many_tables' ? undefined : this.#take();
219
+ const table = finding === 'many_tables' || finding === 'plan'
220
+ ? undefined
221
+ : this.#take();
220
222
  if (table !== undefined && table.kind !== 'identifier') {
221
223
  this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', table, `expected the table the finding names, found ${JSON.stringify(table.text || 'end of file')}`);
222
224
  }
@@ -228,6 +230,9 @@ class Parser {
228
230
  if (out.some((ack) => ack.finding === finding && ack.table === table?.text)) {
229
231
  this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', start, 'the query already acknowledges this finding');
230
232
  }
233
+ if (out.some((ack) => (ack.finding === 'plan') !== (finding === 'plan'))) {
234
+ this.#fail('SYQL2013_INVALID_ACKNOWLEDGEMENT', start, 'allow plan is the only acknowledgement of its query');
235
+ }
231
236
  out.push({
232
237
  finding,
233
238
  ...(table === undefined ? {} : { table: table.text }),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/typegen",
3
- "version": "0.61.0",
3
+ "version": "0.62.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.61.0"
59
+ "@syncular/core": "0.62.0"
60
60
  },
61
61
  "devDependencies": {
62
- "@syncular/server": "0.61.0"
62
+ "@syncular/server": "0.62.0"
63
63
  }
64
64
  }
package/src/query.ts CHANGED
@@ -323,10 +323,11 @@ export const QUERY_PLAN_FINDINGS = [
323
323
  ] as const;
324
324
  export type QueryPlanFinding = (typeof QUERY_PLAN_FINDINGS)[number];
325
325
 
326
- /** An author's acknowledgement of one plan finding, with its reason. */
326
+ /** An author's acknowledgement of one plan finding, with its reason.
327
+ * `plan` acknowledges every finding of a query only the server runs. */
327
328
  export interface QueryAcknowledgement {
328
- readonly finding: QueryPlanFinding;
329
- /** Absent for `many_tables`. */
329
+ readonly finding: QueryPlanFinding | 'plan';
330
+ /** Absent for `many_tables` and `plan`. */
330
331
  readonly table?: string;
331
332
  readonly reason: string;
332
333
  }
@@ -588,7 +589,7 @@ function parseCommentParams(file: string, raw: string): CommentParam[] {
588
589
  }
589
590
 
590
591
  const ACKNOWLEDGEMENT_RE = new RegExp(
591
- `^--\\s*allow\\s+(${QUERY_PLAN_FINDINGS.join('|')})\\b`,
592
+ `^--\\s*allow\\s+(${QUERY_PLAN_FINDINGS.join('|')}|plan)\\b`,
592
593
  );
593
594
 
594
595
  /** Parse the `-- allow <finding> [table]: <reason>` acknowledgements of the
@@ -600,7 +601,9 @@ function parseCommentAcknowledgements(
600
601
  const out: QueryAcknowledgement[] = [];
601
602
  for (const comment of leadingComments(raw)) {
602
603
  const kind = ACKNOWLEDGEMENT_RE.exec(comment)?.[1];
603
- const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind);
604
+ const finding = [...QUERY_PLAN_FINDINGS, 'plan' as const].find(
605
+ (name) => name === kind,
606
+ );
604
607
  if (finding === undefined) continue;
605
608
  const match =
606
609
  /^--\s*allow\s+\w+(?:\s+([A-Za-z_][A-Za-z0-9_]*))?\s*:\s*(\S.*?)\s*$/.exec(
@@ -609,8 +612,13 @@ function parseCommentAcknowledgements(
609
612
  const table = match?.[1];
610
613
  if (
611
614
  match === null ||
612
- (finding === 'many_tables') !== (table === undefined) ||
613
- out.some((other) => other.finding === finding && other.table === table)
615
+ (finding === 'many_tables' || finding === 'plan') !==
616
+ (table === undefined) ||
617
+ out.some(
618
+ (other) =>
619
+ (other.finding === finding && other.table === table) ||
620
+ (other.finding === 'plan') !== (finding === 'plan'),
621
+ )
614
622
  ) {
615
623
  throw new TypegenError(
616
624
  file,
@@ -2518,8 +2526,9 @@ export function checkQueryPlan(
2518
2526
  acknowledgement: QueryAcknowledgement,
2519
2527
  found: (typeof findings)[number],
2520
2528
  ): boolean =>
2521
- acknowledgement.finding === found.finding &&
2522
- acknowledgement.table === found.table;
2529
+ acknowledgement.finding === 'plan' ||
2530
+ (acknowledgement.finding === found.finding &&
2531
+ acknowledgement.table === found.table);
2523
2532
  for (const found of findings) {
2524
2533
  if (!query.acknowledgements.some((ack) => acknowledged(ack, found))) {
2525
2534
  throw new TypegenError(
@@ -487,15 +487,20 @@ class Parser {
487
487
  while (this.#peek().text === 'allow') {
488
488
  const start = this.#take();
489
489
  const kind = this.#take();
490
- const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind.text);
490
+ const finding = [...QUERY_PLAN_FINDINGS, 'plan' as const].find(
491
+ (name) => name === kind.text,
492
+ );
491
493
  if (finding === undefined) {
492
494
  this.#fail(
493
495
  'SYQL2013_INVALID_ACKNOWLEDGEMENT',
494
496
  kind,
495
- `expected a query plan finding (${QUERY_PLAN_FINDINGS.join(', ')}), found ${JSON.stringify(kind.text || 'end of file')}`,
497
+ `expected a query plan finding (${QUERY_PLAN_FINDINGS.join(', ')}) or plan, found ${JSON.stringify(kind.text || 'end of file')}`,
496
498
  );
497
499
  }
498
- const table = finding === 'many_tables' ? undefined : this.#take();
500
+ const table =
501
+ finding === 'many_tables' || finding === 'plan'
502
+ ? undefined
503
+ : this.#take();
499
504
  if (table !== undefined && table.kind !== 'identifier') {
500
505
  this.#fail(
501
506
  'SYQL2013_INVALID_ACKNOWLEDGEMENT',
@@ -521,6 +526,15 @@ class Parser {
521
526
  'the query already acknowledges this finding',
522
527
  );
523
528
  }
529
+ if (
530
+ out.some((ack) => (ack.finding === 'plan') !== (finding === 'plan'))
531
+ ) {
532
+ this.#fail(
533
+ 'SYQL2013_INVALID_ACKNOWLEDGEMENT',
534
+ start,
535
+ 'allow plan is the only acknowledgement of its query',
536
+ );
537
+ }
524
538
  out.push({
525
539
  finding,
526
540
  ...(table === undefined ? {} : { table: table.text }),