@syncular/typegen 0.58.0 → 0.60.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.
Files changed (78) hide show
  1. package/README.md +96 -43
  2. package/dist/cli.js +8 -3
  3. package/dist/emit-dart.d.ts +4 -3
  4. package/dist/emit-dart.js +40 -100
  5. package/dist/emit-kotlin.d.ts +4 -4
  6. package/dist/emit-kotlin.js +41 -99
  7. package/dist/emit-queries-dart.d.ts +1 -1
  8. package/dist/emit-queries-dart.js +17 -26
  9. package/dist/emit-queries-kotlin.d.ts +1 -1
  10. package/dist/emit-queries-kotlin.js +15 -24
  11. package/dist/emit-queries-rust.d.ts +1 -1
  12. package/dist/emit-queries-rust.js +18 -19
  13. package/dist/emit-queries-swift.d.ts +1 -1
  14. package/dist/emit-queries-swift.js +22 -26
  15. package/dist/emit-queries.d.ts +1 -1
  16. package/dist/emit-queries.js +18 -27
  17. package/dist/emit-swift.d.ts +4 -4
  18. package/dist/emit-swift.js +43 -102
  19. package/dist/emit.d.ts +3 -3
  20. package/dist/emit.js +37 -113
  21. package/dist/errors.d.ts +6 -2
  22. package/dist/errors.js +10 -2
  23. package/dist/fmt.js +11 -2
  24. package/dist/generate.d.ts +4 -3
  25. package/dist/generate.js +61 -73
  26. package/dist/init.js +5 -6
  27. package/dist/ir.d.ts +14 -2
  28. package/dist/ir.js +67 -49
  29. package/dist/lower.d.ts +0 -7
  30. package/dist/lower.js +0 -62
  31. package/dist/lsp.js +6 -1
  32. package/dist/manifest.d.ts +1 -2
  33. package/dist/manifest.js +13 -12
  34. package/dist/migration-lock.d.ts +32 -23
  35. package/dist/migration-lock.js +115 -92
  36. package/dist/naming.d.ts +25 -0
  37. package/dist/naming.js +92 -0
  38. package/dist/query.d.ts +94 -14
  39. package/dist/query.js +642 -461
  40. package/dist/sql.js +18 -3
  41. package/dist/syql-ast.d.ts +2 -0
  42. package/dist/syql-ast.js +7 -1
  43. package/dist/syql-browser.js +7 -6
  44. package/dist/syql-diagnostics.d.ts +1 -0
  45. package/dist/syql-diagnostics.js +1 -0
  46. package/dist/syql-lowering.js +11 -1
  47. package/dist/syql-parser.d.ts +4 -1
  48. package/dist/syql-parser.js +42 -5
  49. package/dist/syql-validator.js +13 -220
  50. package/package.json +3 -3
  51. package/src/cli.ts +9 -3
  52. package/src/emit-dart.ts +44 -116
  53. package/src/emit-kotlin.ts +41 -118
  54. package/src/emit-queries-dart.ts +23 -32
  55. package/src/emit-queries-kotlin.ts +20 -30
  56. package/src/emit-queries-rust.ts +29 -31
  57. package/src/emit-queries-swift.ts +26 -32
  58. package/src/emit-queries.ts +26 -47
  59. package/src/emit-swift.ts +49 -120
  60. package/src/emit.ts +45 -135
  61. package/src/errors.ts +13 -2
  62. package/src/fmt.ts +10 -2
  63. package/src/generate.ts +113 -107
  64. package/src/init.ts +8 -6
  65. package/src/ir.ts +91 -54
  66. package/src/lower.ts +0 -53
  67. package/src/lsp.ts +11 -4
  68. package/src/manifest.ts +22 -18
  69. package/src/migration-lock.ts +192 -137
  70. package/src/naming.ts +154 -0
  71. package/src/query.ts +864 -502
  72. package/src/sql.ts +30 -3
  73. package/src/syql-ast.ts +9 -0
  74. package/src/syql-browser.ts +8 -7
  75. package/src/syql-diagnostics.ts +2 -0
  76. package/src/syql-lowering.ts +16 -1
  77. package/src/syql-parser.ts +73 -8
  78. package/src/syql-validator.ts +21 -279
package/dist/emit.js CHANGED
@@ -1,4 +1,19 @@
1
- import { snakeToCamel } from './naming.js';
1
+ /**
2
+ * TS emitter: neutral IR → one standalone generated module exporting
3
+ *
4
+ * - `schema` — a ServerSchema-compatible object (structurally typed; the
5
+ * generated file imports nothing),
6
+ * - a `<Table>Row` interface per table,
7
+ * - `<Table>Insert` / `<Table>Update` mutation-input shapes honoring
8
+ * nullability,
9
+ * - a `<name>Subscription` helper constant per manifest unit template with
10
+ * a typed builder of its unit scope map (SPEC §4.1).
11
+ *
12
+ * The header carries the IR hash so `--check` verifies freshness
13
+ * byte-exactly.
14
+ */
15
+ import { appColumnType, serializeSchema, } from './ir.js';
16
+ import { pascalCase, snakeToCamel, stringLiteral, } from './naming.js';
2
17
  const TS_TYPE = {
3
18
  string: 'string',
4
19
  integer: 'number',
@@ -13,92 +28,9 @@ const TS_TYPE = {
13
28
  // is an app-level helper in @syncular/crdt-yjs, not generated code.
14
29
  crdt: 'Uint8Array',
15
30
  };
16
- /**
17
- * §5.11: the app-side TS type of a column. An encrypted column's wire type is
18
- * `bytes`, but the app sees its declared type (the local mirror is plaintext).
19
- */
20
- function appTsType(column) {
21
- const type = column.encrypted === true && column.declaredType !== undefined
22
- ? column.declaredType
23
- : column.type;
24
- return TS_TYPE[type];
25
- }
26
- function pascalCase(name) {
27
- return name
28
- .split(/[_-]+/)
29
- .filter((part) => part.length > 0)
30
- .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
31
- .join('');
32
- }
33
- function quote(value) {
34
- return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
35
- }
36
31
  const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
37
32
  function propertyKey(name) {
38
- return IDENTIFIER_RE.test(name) ? name : quote(name);
39
- }
40
- function emitSchema(ir) {
41
- const lines = [];
42
- lines.push('/** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */');
43
- lines.push('export const schema = {');
44
- lines.push(` version: ${ir.schemaVersion},`);
45
- lines.push(' tables: [');
46
- for (const table of ir.tables) {
47
- lines.push(' {');
48
- lines.push(` name: ${quote(table.name)},`);
49
- lines.push(' columns: [');
50
- for (const column of table.columns) {
51
- // §5.10.1: emit crdtType on crdt columns so a generated server schema
52
- // can select the merger; omitted (and thus unchanged) for others.
53
- const crdtType = column.crdtType !== undefined
54
- ? `, crdtType: ${quote(column.crdtType)}`
55
- : '';
56
- // §5.11: emit encrypted/declaredType on encrypted columns so the client
57
- // codec encrypts/decrypts them; omitted for others.
58
- const encrypted = column.encrypted === true
59
- ? `, encrypted: true, declaredType: ${quote(column.declaredType ?? column.type)}`
60
- : '';
61
- lines.push(` { name: ${quote(column.name)}, type: ${quote(column.type)}, nullable: ${column.nullable}${crdtType}${encrypted} },`);
62
- }
63
- lines.push(' ],');
64
- lines.push(` primaryKey: ${quote(table.primaryKey)},`);
65
- lines.push(' scopes: [');
66
- for (const scope of table.scopes) {
67
- lines.push(` { pattern: ${quote(scope.pattern)}, column: ${quote(scope.column)} },`);
68
- }
69
- lines.push(' ],');
70
- // §6.11 declared references — emitted only when the table declares any,
71
- // so reference-free tables keep their exact pre-reference generated bytes.
72
- if (table.references.length > 0) {
73
- lines.push(' references: [');
74
- for (const reference of table.references) {
75
- lines.push(` { column: ${quote(reference.column)}, parentTable: ${quote(reference.parentTable)}, onDelete: ${quote(reference.onDelete)} },`);
76
- }
77
- lines.push(' ],');
78
- }
79
- // Local secondary indexes — emitted only when the table declares any, so
80
- // index-free tables keep their exact pre-index generated bytes.
81
- if (table.indexes.length > 0) {
82
- lines.push(' indexes: [');
83
- for (const index of table.indexes) {
84
- const cols = index.columns.map((c) => quote(c)).join(', ');
85
- lines.push(` { name: ${quote(index.name)}, columns: [${cols}], unique: ${index.unique} },`);
86
- }
87
- lines.push(' ],');
88
- }
89
- if (table.ftsIndexes.length > 0) {
90
- lines.push(' ftsIndexes: [');
91
- for (const index of table.ftsIndexes) {
92
- const cols = index.columns.map((column) => quote(column)).join(', ');
93
- lines.push(` { name: ${quote(index.name)}, columns: [${cols}], tokenize: ${quote(index.tokenize)} },`);
94
- }
95
- lines.push(' ],');
96
- }
97
- lines.push(' },');
98
- }
99
- lines.push(' ],');
100
- lines.push('} as const;');
101
- return lines.join('\n');
33
+ return IDENTIFIER_RE.test(name) ? name : stringLiteral(name, 'ts');
102
34
  }
103
35
  function emitRowInterfaces(table, naming) {
104
36
  const type = pascalCase(table.name);
@@ -110,7 +42,7 @@ function emitRowInterfaces(table, naming) {
110
42
  lines.push(`/** One ${table.name} row (§2.4 column order). */`);
111
43
  lines.push(`export interface ${type}Row {`);
112
44
  for (const column of table.columns) {
113
- const ts = appTsType(column);
45
+ const ts = TS_TYPE[appColumnType(column)];
114
46
  lines.push(` ${key(column.name)}: ${ts}${column.nullable ? ' | null' : ''};`);
115
47
  }
116
48
  lines.push('}');
@@ -118,7 +50,7 @@ function emitRowInterfaces(table, naming) {
118
50
  lines.push(`/** Insert shape: nullable columns may be omitted. */`);
119
51
  lines.push(`export interface ${type}Insert {`);
120
52
  for (const column of table.columns) {
121
- const ts = appTsType(column);
53
+ const ts = TS_TYPE[appColumnType(column)];
122
54
  lines.push(column.nullable
123
55
  ? ` ${key(column.name)}?: ${ts} | null;`
124
56
  : ` ${key(column.name)}: ${ts};`);
@@ -128,7 +60,7 @@ function emitRowInterfaces(table, naming) {
128
60
  lines.push(`/** Update shape: primary key required, all other columns optional. */`);
129
61
  lines.push(`export interface ${type}Update {`);
130
62
  for (const column of table.columns) {
131
- const ts = appTsType(column);
63
+ const ts = TS_TYPE[appColumnType(column)];
132
64
  if (column.name === table.primaryKey) {
133
65
  lines.push(` ${key(column.name)}: ${ts};`);
134
66
  }
@@ -147,23 +79,18 @@ function emitTableDescriptor(table, naming) {
147
79
  const field = naming === 'camel' ? snakeToCamel(table.primaryKey) : table.primaryKey;
148
80
  const constant = `${naming === 'camel' ? snakeToCamel(table.name) : table.name}Table`;
149
81
  return [
150
- `/** Typed mutation/resource descriptor for ${quote(table.name)}. */`,
151
- `export const ${constant}: SyncTable<${type}Row, ${type}Insert, ${type}Update, ${appTsType(primary)}> = {`,
152
- ` name: ${quote(table.name)},`,
153
- ` primaryKey: ${quote(field)},`,
154
- ` physicalPrimaryKey: ${quote(table.primaryKey)},`,
82
+ `/** Typed mutation/resource descriptor for ${stringLiteral(table.name, 'ts')}. */`,
83
+ `export const ${constant}: SyncTable<${type}Row, ${type}Insert, ${type}Update, ${TS_TYPE[appColumnType(primary)]}> = {`,
84
+ ` name: ${stringLiteral(table.name, 'ts')},`,
85
+ ` primaryKey: ${stringLiteral(field, 'ts')},`,
86
+ ` physicalPrimaryKey: ${stringLiteral(table.primaryKey, 'ts')},`,
155
87
  '};',
156
88
  ].join('\n');
157
89
  }
158
90
  function emitSubscription(sub) {
159
- const params = [];
160
- for (const scope of sub.scopes) {
161
- for (const value of scope.values) {
162
- if (value.kind === 'parameter' && !params.includes(value.name)) {
163
- params.push(value.name);
164
- }
165
- }
166
- }
91
+ const params = [
92
+ ...new Set(sub.scopes.flatMap(({ value }) => value.kind === 'parameter' ? [value.name] : [])),
93
+ ];
167
94
  const lines = [];
168
95
  const paramsType = `${pascalCase(sub.name)}Params`;
169
96
  if (params.length > 0) {
@@ -174,19 +101,13 @@ function emitSubscription(sub) {
174
101
  lines.push('}');
175
102
  lines.push('');
176
103
  }
177
- lines.push(`/** Requested-scope template for the ${quote(sub.name)} subscription. */`);
104
+ lines.push(`/** Unit template for the ${stringLiteral(sub.name, 'ts')} subscription (SPEC §4.1). */`);
178
105
  lines.push(`export const ${sub.name}Subscription = {`);
179
- lines.push(` name: ${quote(sub.name)},`);
180
- lines.push(` table: ${quote(sub.table)},`);
106
+ lines.push(` name: ${stringLiteral(sub.name, 'ts')},`);
181
107
  const args = params.length > 0 ? `params: ${paramsType}` : '';
182
- lines.push(` scopes: (${args}): Record<string, string[]> => ({`);
183
- for (const scope of sub.scopes) {
184
- const values = scope.values
185
- .map((value) => value.kind === 'literal'
186
- ? quote(value.value)
187
- : `params.${propertyKey(value.name)}`)
188
- .join(', ');
189
- lines.push(` ${propertyKey(scope.variable)}: [${values}],`);
108
+ lines.push(` scopes: (${args}): Record<string, string> => ({`);
109
+ for (const { variable, value } of sub.scopes) {
110
+ lines.push(` ${propertyKey(variable)}: ${value.kind === 'literal' ? stringLiteral(value.value, 'ts') : `params.${propertyKey(value.name)}`},`);
190
111
  }
191
112
  lines.push(' }),');
192
113
  lines.push('} as const;');
@@ -214,7 +135,10 @@ export function emitModule(ir, hash, naming = 'camel') {
214
135
  ' readonly __id?: Id;',
215
136
  '}',
216
137
  ].join('\n'));
217
- parts.push(emitSchema(ir));
138
+ parts.push([
139
+ '/** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */',
140
+ `export const schema = ${serializeSchema(ir)} as const;`,
141
+ ].join('\n'));
218
142
  for (const table of ir.tables) {
219
143
  parts.push(emitRowInterfaces(table, naming));
220
144
  parts.push(emitTableDescriptor(table, naming));
package/dist/errors.d.ts CHANGED
@@ -1,6 +1,10 @@
1
- /** Fail-loud codegen error: every message names the offending construct. */
1
+ /** Fail-loud codegen error: every message names the offending construct. A
2
+ * coded error carries a static message, its stable `code`, and the dynamic
3
+ * values (table, column, …) in `details`. */
2
4
  export declare class TypegenError extends Error {
3
5
  /** Input the error came from (a migration file, the manifest, …). */
4
6
  readonly source: string;
5
- constructor(source: string, message: string);
7
+ readonly code?: string;
8
+ readonly details?: Readonly<Record<string, unknown>>;
9
+ constructor(source: string, message: string, code?: string, details?: Readonly<Record<string, unknown>>);
6
10
  }
package/dist/errors.js CHANGED
@@ -1,10 +1,18 @@
1
- /** Fail-loud codegen error: every message names the offending construct. */
1
+ /** Fail-loud codegen error: every message names the offending construct. A
2
+ * coded error carries a static message, its stable `code`, and the dynamic
3
+ * values (table, column, …) in `details`. */
2
4
  export class TypegenError extends Error {
3
5
  /** Input the error came from (a migration file, the manifest, …). */
4
6
  source;
5
- constructor(source, message) {
7
+ code;
8
+ details;
9
+ constructor(source, message, code, details) {
6
10
  super(`${source}: ${message}`);
7
11
  this.name = 'TypegenError';
8
12
  this.source = source;
13
+ if (code !== undefined)
14
+ this.code = code;
15
+ if (details !== undefined)
16
+ this.details = details;
9
17
  }
10
18
  }
package/dist/fmt.js CHANGED
@@ -217,6 +217,7 @@ function formatTokens(parsed) {
217
217
  let importList = false;
218
218
  let justClosedImportList = false;
219
219
  let seenTopLevel = false;
220
+ let acknowledging = false;
220
221
  let pendingBetween = 0;
221
222
  let inlineParameterRecord = false;
222
223
  let justClosedInlineParameterRecord = false;
@@ -231,11 +232,19 @@ function formatTokens(parsed) {
231
232
  (lower === 'import' ||
232
233
  lower === 'predicate' ||
233
234
  lower === 'query' ||
234
- lower === 'sync') &&
235
+ lower === 'sync' ||
236
+ (lower === 'allow' &&
237
+ (previous === undefined ||
238
+ previous.kind === 'string' ||
239
+ previous.text === '}'))) &&
235
240
  !(lower === 'query' && previous?.text === 'sync');
236
241
  if (topLevelDeclaration) {
237
- if (seenTopLevel)
242
+ // Acknowledgements sit on their own lines directly above their query.
243
+ if (acknowledging)
244
+ writer.newline();
245
+ else if (seenTopLevel)
238
246
  writer.blankline();
247
+ acknowledging = lower === 'allow';
239
248
  seenTopLevel = true;
240
249
  previous = undefined;
241
250
  awaitsDeclarationParameters = lower === 'predicate' || lower === 'query';
@@ -73,9 +73,10 @@ export interface GenerateResult {
73
73
  */
74
74
  export declare function baselineMigrationHistory(manifestDir: string): GeneratedOutput;
75
75
  /**
76
- * Validate and explicitly compact a version-1 migration lock to version 2.
77
- * The caller owns the in-place write so the CLI can make the format transition
78
- * visible and reviewable.
76
+ * Validate a format-1 or format-2 migration lock and convert it to the
77
+ * current format, recording each locked migration's schema version from the
78
+ * manifest. The caller owns the in-place write so the CLI can make the format
79
+ * transition visible and reviewable.
79
80
  */
80
81
  export declare function upgradeMigrationHistory(manifestDir: string): GeneratedOutput;
81
82
  /** Fast CI check for migration history without emitting/query analysis. */
package/dist/generate.js CHANGED
@@ -17,9 +17,9 @@ import { emitSwiftModule } from './emit-swift.js';
17
17
  import { TypegenError } from './errors.js';
18
18
  import { canonicalizeExtensions, IR_VERSION, irHash, serializeIr, } from './ir.js';
19
19
  import { MANIFEST_FILENAME, parseManifest, } from './manifest.js';
20
- import { buildMigrationLock, LEGACY_MIGRATION_LOCK_FORMAT_VERSION, lockedMigrationNames, MIGRATION_LOCK_FILENAME, readMigrationLock, serializeMigrationLock, updateMigrationLock, } from './migration-lock.js';
21
- import { buildNamingMap } from './naming.js';
22
- import { analyzeQueryFile, synthesizeDdl, } from './query.js';
20
+ import { buildMigrationLock, buildSchemaVersions, lockedMigrationNames, MIGRATION_LOCK_FILENAME, MIGRATION_LOCK_FORMAT_VERSION, readMigrationLock, serializeMigrationLock, updateMigrationLock, upgradeMigrationLock, } from './migration-lock.js';
21
+ import { validateSchemaIdentifiers } from './naming.js';
22
+ import { analyzeQueryFile, checkQueryPlan, synthesizeDdl, } from './query.js';
23
23
  import { serializeQueryIr } from './query-ir.js';
24
24
  import { applyMigrationSql, validateFinalSchemaIdentifiers, } from './sql.js';
25
25
  import { lowerSyqlQuery } from './syql-lowering.js';
@@ -38,9 +38,13 @@ function resolveScope(table, spec) {
38
38
  }
39
39
  const variable = match[2];
40
40
  const column = typeof spec === 'string' ? variable : spec.column;
41
- if (!table.columns.some((c) => c.name === column)) {
41
+ const scopeColumn = table.columns.find((c) => c.name === column);
42
+ if (scopeColumn === undefined) {
42
43
  throw new TypegenError(MANIFEST_FILENAME, `table ${table.name}: scope pattern ${JSON.stringify(pattern)} names unknown column ${JSON.stringify(column)}`);
43
44
  }
45
+ if (scopeColumn.type !== 'string' && scopeColumn.type !== 'integer') {
46
+ throw new TypegenError(MANIFEST_FILENAME, 'a scope column must have type string or integer (§3.1)', 'typegen.scope_column_type', { table: table.name, column, type: scopeColumn.type });
47
+ }
44
48
  return { pattern, variable, column };
45
49
  }
46
50
  function buildTable(manifestTable, parsed) {
@@ -96,6 +100,12 @@ function applyEncryption(parsed, scopes, encryptedColumns) {
96
100
  if (column.type === 'crdt') {
97
101
  throw new TypegenError(MANIFEST_FILENAME, `table ${parsed.name}: crdt column ${JSON.stringify(name)} cannot be encrypted — the server merges crdt bytes plaintext (§5.10.3, §5.11)`);
98
102
  }
103
+ // The server indexes ciphertext under a random nonce: a UNIQUE index
104
+ // never fires there while clients enforce it on plaintext.
105
+ const index = parsed.indexes.find((i) => i.columns.includes(name));
106
+ if (index !== undefined) {
107
+ throw new TypegenError(MANIFEST_FILENAME, 'an encrypted column cannot be an index column (§5.11)', 'typegen.encrypted_index_column', { table: parsed.name, index: index.name, column: name });
108
+ }
99
109
  }
100
110
  return parsed.columns.map((column) => {
101
111
  if (!encrypted.has(column.name))
@@ -141,6 +151,11 @@ function validateReferences(tables, parsedTables) {
141
151
  if (child.type !== parentKey.type) {
142
152
  throw new TypegenError(MANIFEST_FILENAME, `table ${table.name}: reference column ${JSON.stringify(reference.column)} has type ${JSON.stringify(child.type)} but ${parent.name}.${parent.primaryKey} has type ${JSON.stringify(parentKey.type)} — the types must match (§6.11)`);
143
153
  }
154
+ // The server reaches children through this index (§6.11); a migration
155
+ // that drops it leaves a schema the server refuses to compile.
156
+ if (!table.indexes.some((index) => index.columns.length === 1 && index.columns[0] === reference.column)) {
157
+ throw new TypegenError(MANIFEST_FILENAME, 'a declared reference needs a single-column index over its column (§6.11)', 'typegen.reference_index_missing', { table: table.name, column: reference.column });
158
+ }
144
159
  if (patternsOf(table) !== patternsOf(parent)) {
145
160
  throw new TypegenError(MANIFEST_FILENAME, `table ${table.name}: reference column ${JSON.stringify(reference.column)} targets ${parent.name}, whose scope patterns (${parent.scopes.map((scope) => scope.pattern).join(', ')}) differ from ${table.name}'s (${table.scopes.map((scope) => scope.pattern).join(', ')}) — a cascade MUST NOT cross an authorization boundary (§6.11)`);
146
161
  }
@@ -148,50 +163,22 @@ function validateReferences(tables, parsedTables) {
148
163
  }
149
164
  }
150
165
  function buildSubscription(sub, tables) {
151
- const table = tables.find((t) => t.name === sub.table);
152
- if (table === undefined) {
153
- throw new TypegenError(MANIFEST_FILENAME, `subscription ${sub.name}: unknown table ${JSON.stringify(sub.table)}`);
166
+ const variables = Object.keys(sub.scopes).sort();
167
+ if (!tables.some((table) => variables.every((variable) => table.scopes.some((scope) => scope.variable === variable)))) {
168
+ throw new TypegenError(MANIFEST_FILENAME, 'a unit template covers no table: no table declares all of its scope variables (SPEC §4.1)', 'typegen.subscription_uncovered', { subscription: sub.name, variables });
154
169
  }
155
- const declared = new Set(table.scopes.map((s) => s.variable));
156
- const scopes = Object.entries(sub.scopes)
157
- .map(([variable, values]) => {
158
- if (!declared.has(variable)) {
159
- throw new TypegenError(MANIFEST_FILENAME, `subscription ${sub.name}: ${JSON.stringify(variable)} is not a scope variable of table ${sub.table} (declared: ${[...declared].join(', ')})`);
170
+ const scopes = variables.map((variable) => {
171
+ const value = sub.scopes[variable];
172
+ const param = PARAM_RE.exec(value);
173
+ if (param?.[1] !== undefined) {
174
+ return { variable, value: { kind: 'parameter', name: param[1] } };
160
175
  }
161
- const irValues = values.map((value) => {
162
- const param = PARAM_RE.exec(value);
163
- if (param?.[1] !== undefined) {
164
- return { kind: 'parameter', name: param[1] };
165
- }
166
- if (value.includes('{') || value.includes('}')) {
167
- throw new TypegenError(MANIFEST_FILENAME, `subscription ${sub.name}: scope value ${JSON.stringify(value)} mixes literals and placeholders — a value is either a literal or exactly '{param}'`);
168
- }
169
- if (value === '*') {
170
- throw new TypegenError(MANIFEST_FILENAME, `subscription ${sub.name}: '*' is rejected in requested scopes (§3.2)`);
171
- }
172
- return { kind: 'literal', value };
173
- });
174
- return { variable, values: irValues };
175
- })
176
- .sort((a, b) => (a.variable < b.variable ? -1 : 1));
177
- return { name: sub.name, table: sub.table, scopes };
178
- }
179
- function buildSchemaVersions(manifest, migrations) {
180
- const names = migrations.map((m) => m.name);
181
- let cursor = 0;
182
- const out = manifest.schemaVersions.map((entry) => {
183
- const index = names.indexOf(entry.through, cursor);
184
- if (index === -1) {
185
- throw new TypegenError(MANIFEST_FILENAME, `schemaVersions: version ${entry.version} names migration ${JSON.stringify(entry.through)}, which does not exist after ${JSON.stringify(names[cursor - 1] ?? '(start)')} (migrations: ${names.join(', ')})`);
176
+ if (value.includes('{') || value.includes('}') || value === '*') {
177
+ throw new TypegenError(MANIFEST_FILENAME, "a unit template value is a literal other than '*' (§3.2) or exactly '{param}'", 'typegen.subscription_invalid_value', { subscription: sub.name, variable, value });
186
178
  }
187
- const covered = names.slice(cursor, index + 1);
188
- cursor = index + 1;
189
- return { version: entry.version, migrations: covered };
179
+ return { variable, value: { kind: 'literal', value } };
190
180
  });
191
- if (cursor !== names.length) {
192
- throw new TypegenError(MANIFEST_FILENAME, `schemaVersions: migrations ${names.slice(cursor).join(', ')} are not covered by any schema version — the last entry's "through" must be the last migration`);
193
- }
194
- return out;
181
+ return { name: sub.name, scopes };
195
182
  }
196
183
  /** Pure IR construction — the testable heart of the generator. Migrations
197
184
  * named in `lockedNames` replay as immutable deployed history: rules that
@@ -206,7 +193,7 @@ export function buildIr(manifest, migrations, lockedNames) {
206
193
  applyMigrationSql(parsedTables, migration.sql, `${migration.name}/up.sql`, droppedTables, { lockedHistory: lockedNames?.has(migration.name) === true });
207
194
  }
208
195
  validateFinalSchemaIdentifiers(parsedTables);
209
- const schemaVersions = buildSchemaVersions(manifest, migrations);
196
+ const schemaVersions = buildSchemaVersions(manifest.schemaVersions, migrations);
210
197
  const tables = manifest.tables.map((manifestTable) => {
211
198
  const parsed = parsedTables.get(manifestTable.name);
212
199
  if (parsed === undefined) {
@@ -307,8 +294,7 @@ export function makeQueryDb(ir) {
307
294
  try {
308
295
  const columnNames = stmt.columnNames;
309
296
  // Execute once against the empty DB to populate decltype; result is [].
310
- const paramsCount = stmt
311
- .paramsCount;
297
+ const paramsCount = stmt.paramsCount;
312
298
  // An unbound FTS5 MATCH parameter is treated as the empty query and
313
299
  // fails parsing. A numeric probe is valid for MATCH and LIMIT alike,
314
300
  // while the empty database still guarantees no result rows.
@@ -323,6 +309,20 @@ export function makeQueryDb(ir) {
323
309
  stmt.finalize();
324
310
  }
325
311
  },
312
+ plan(sql, index) {
313
+ if (index !== undefined)
314
+ sqlite.run(`SAVEPOINT plan_probe; ${index}`);
315
+ try {
316
+ return sqlite
317
+ .query(`EXPLAIN QUERY PLAN ${sql}`)
318
+ .all();
319
+ }
320
+ finally {
321
+ if (index !== undefined) {
322
+ sqlite.run('ROLLBACK TO plan_probe; RELEASE plan_probe');
323
+ }
324
+ }
325
+ },
326
326
  };
327
327
  return { db, close: () => sqlite.close() };
328
328
  }
@@ -365,6 +365,8 @@ export function analyzeQueries(ir, queries, naming, queriesRoot = resolve('/__sy
365
365
  }
366
366
  seen.set(q.name, q.file);
367
367
  }
368
+ for (const query of analyzed)
369
+ checkQueryPlan(query, ir, db);
368
370
  return analyzed;
369
371
  }
370
372
  finally {
@@ -397,44 +399,32 @@ export function baselineMigrationHistory(manifestDir) {
397
399
  buildIr(manifest, migrations);
398
400
  return {
399
401
  path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
400
- content: serializeMigrationLock(buildMigrationLock(migrations)),
402
+ content: serializeMigrationLock(buildMigrationLock(migrations, manifest.schemaVersions)),
401
403
  };
402
404
  }
403
405
  /**
404
- * Validate and explicitly compact a version-1 migration lock to version 2.
405
- * The caller owns the in-place write so the CLI can make the format transition
406
- * visible and reviewable.
406
+ * Validate a format-1 or format-2 migration lock and convert it to the
407
+ * current format, recording each locked migration's schema version from the
408
+ * manifest. The caller owns the in-place write so the CLI can make the format
409
+ * transition visible and reviewable.
407
410
  */
408
411
  export function upgradeMigrationHistory(manifestDir) {
409
412
  const { manifest, migrations } = loadProjectInputs(manifestDir);
410
413
  const locked = readMigrationLock(manifestDir);
411
- if (locked.formatVersion !== LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
412
- throw new TypegenError(MIGRATION_LOCK_FILENAME, 'already uses the current compact migration-lock format');
413
- }
414
- // Validate the immutable prefix before replacing its representation.
415
- updateMigrationLock(locked, migrations);
416
- // upgrade-lock converts the committed representation of history that is
417
- // already locked. Extending the lock over appended migrations is its own
418
- // reviewable act, so unlocked migrations stop the conversion here.
419
- if (migrations.length > locked.migrations.length) {
420
- const appended = migrations
421
- .slice(locked.migrations.length)
422
- .map((migration) => migration.name)
423
- .join(', ');
424
- throw new TypegenError(MIGRATION_LOCK_FILENAME, `migrations ${appended} are appended beyond the locked history — run generate to extend the lock over them, commit the extended lock, then rerun \`migrations upgrade-lock\``);
414
+ if (locked.formatVersion === MIGRATION_LOCK_FORMAT_VERSION) {
415
+ throw new TypegenError(MIGRATION_LOCK_FILENAME, 'already uses the current migration-lock format');
425
416
  }
426
- const lockedNames = lockedMigrationNames(locked);
427
- buildIr(manifest, migrations, lockedNames);
417
+ buildIr(manifest, migrations, lockedMigrationNames(locked));
428
418
  return {
429
419
  path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
430
- content: serializeMigrationLock(buildMigrationLock(migrations, undefined, lockedNames)),
420
+ content: serializeMigrationLock(upgradeMigrationLock(locked, migrations, manifest.schemaVersions)),
431
421
  };
432
422
  }
433
423
  /** Fast CI check for migration history without emitting/query analysis. */
434
424
  export function checkMigrationHistory(manifestDir) {
435
425
  const { manifest, migrations } = loadProjectInputs(manifestDir);
436
426
  const locked = readMigrationLock(manifestDir);
437
- const current = updateMigrationLock(locked, migrations);
427
+ const current = updateMigrationLock(locked, migrations, manifest.schemaVersions);
438
428
  buildIr(manifest, migrations, lockedMigrationNames(locked));
439
429
  const output = {
440
430
  path: resolve(manifestDir, MIGRATION_LOCK_FILENAME),
@@ -451,7 +441,7 @@ export function checkMigrationHistory(manifestDir) {
451
441
  export function generate(manifestDir) {
452
442
  const { manifest, migrations } = loadProjectInputs(manifestDir);
453
443
  const locked = readMigrationLock(manifestDir);
454
- const migrationLock = updateMigrationLock(locked, migrations);
444
+ const migrationLock = updateMigrationLock(locked, migrations, manifest.schemaVersions);
455
445
  const ir = buildIr(manifest, migrations, lockedMigrationNames(locked));
456
446
  // §5/§12 naming: the emitter targets this run generates (keyword hazards
457
447
  // are only real on targets that exist), and the per-table collision check
@@ -470,9 +460,7 @@ export function generate(manifestDir) {
470
460
  targets,
471
461
  backend: manifest.queryBackend,
472
462
  };
473
- for (const table of ir.tables) {
474
- buildNamingMap(table.columns.map((c) => c.name), manifest.naming, MANIFEST_FILENAME, `table ${table.name}`, targets);
475
- }
463
+ validateSchemaIdentifiers(ir.tables, manifest.naming, targets, MANIFEST_FILENAME);
476
464
  const irJson = serializeIr(ir);
477
465
  const hash = irHash(irJson);
478
466
  const module = emitModule(ir, hash, manifest.naming);
package/dist/init.js CHANGED
@@ -22,11 +22,7 @@ const STARTER_MANIFEST = `{
22
22
  "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
23
23
  "tables": [{ "name": "notes", "scopes": ["list:{list_id}"] }],
24
24
  "subscriptions": [
25
- {
26
- "name": "notesInList",
27
- "table": "notes",
28
- "scopes": { "list_id": ["{listId}"] }
29
- }
25
+ { "name": "notesInList", "scopes": { "list_id": "{listId}" } }
30
26
  ]
31
27
  }
32
28
  `;
@@ -38,6 +34,9 @@ CREATE TABLE notes (
38
34
  body TEXT NOT NULL,
39
35
  updated_at_ms INTEGER NOT NULL
40
36
  );
37
+
38
+ -- The starter query reads one list; this index lets SQLite search it.
39
+ CREATE INDEX idx_notes_list ON notes (list_id);
41
40
  `;
42
41
  // A starter NAMED query (the typed .sql read tier). typegen type-checks it
43
42
  // against the schema via SQLite and emits a typed \`notesInList(client, listId)\`
@@ -85,7 +84,7 @@ export function initProject(dir) {
85
84
  mkdirSync(queriesDir, { recursive: true });
86
85
  writeFileSync(manifestPath, STARTER_MANIFEST, 'utf8');
87
86
  writeFileSync(migrationPath, STARTER_MIGRATION, 'utf8');
88
- writeFileSync(migrationLockPath, serializeMigrationLock(buildMigrationLock([{ name: '0001_initial', sql: STARTER_MIGRATION }])), 'utf8');
87
+ writeFileSync(migrationLockPath, serializeMigrationLock(buildMigrationLock([{ name: '0001_initial', sql: STARTER_MIGRATION }], [{ version: 1, through: '0001_initial' }])), 'utf8');
89
88
  writeFileSync(queryPath, STARTER_QUERY, 'utf8');
90
89
  return {
91
90
  written: [manifestPath, migrationPath, migrationLockPath, queryPath],
package/dist/ir.d.ts CHANGED
@@ -17,6 +17,10 @@ export interface IrColumn {
17
17
  /** §5.11: the app-side type of an encrypted column. Present iff `encrypted`. */
18
18
  readonly declaredType?: IrColumnType;
19
19
  }
20
+ /** §5.11: the app-side type of a column. An encrypted column rides the wire
21
+ * as `bytes`; generated rows expose its declared type (the local mirror is
22
+ * plaintext). */
23
+ export declare function appColumnType(column: IrColumn): IrColumnType;
20
24
  /** One §3.1 scope pattern, fully resolved (no re-parsing downstream). */
21
25
  export interface IrScope {
22
26
  readonly pattern: string;
@@ -80,11 +84,12 @@ export type IrScopeValue = {
80
84
  };
81
85
  export interface IrSubscriptionScope {
82
86
  readonly variable: string;
83
- readonly values: readonly IrScopeValue[];
87
+ readonly value: IrScopeValue;
84
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. */
85
91
  export interface IrSubscription {
86
92
  readonly name: string;
87
- readonly table: string;
88
93
  /** Sorted by variable for stable diffs. */
89
94
  readonly scopes: readonly IrSubscriptionScope[];
90
95
  }
@@ -108,5 +113,12 @@ export interface IrDocument {
108
113
  export declare function canonicalizeExtensions(value: unknown): unknown;
109
114
  /** Serialize with a fixed key order — byte-deterministic for equal IRs. */
110
115
  export declare function serializeIr(ir: IrDocument): string;
116
+ /**
117
+ * The ServerSchema-compatible schema object (§2.4, §3.1) as 2-space JSON.
118
+ * Every emitter embeds these exact bytes: TS as an object literal, Swift,
119
+ * Kotlin, and Dart as a string literal they parse, so every platform hands
120
+ * its client the same tables, scopes, references, and indexes.
121
+ */
122
+ export declare function serializeSchema(ir: IrDocument): string;
111
123
  /** Hash of the exact IR file bytes; stamped into generated modules. */
112
124
  export declare function irHash(irJson: string): string;