@syncular/typegen 0.20.1 → 0.21.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/dist/emit.js CHANGED
@@ -67,6 +67,15 @@ function emitSchema(ir) {
67
67
  lines.push(` { pattern: ${quote(scope.pattern)}, column: ${quote(scope.column)} },`);
68
68
  }
69
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
+ }
70
79
  // Local secondary indexes — emitted only when the table declares any, so
71
80
  // index-free tables keep their exact pre-index generated bytes.
72
81
  if (table.indexes.length > 0) {
package/dist/generate.js CHANGED
@@ -57,6 +57,13 @@ function buildTable(manifestTable, parsed) {
57
57
  primaryKey: parsed.primaryKey,
58
58
  columns,
59
59
  scopes,
60
+ // Declared references (§6.11), in declaration order. The generated index
61
+ // over each child column already rides in `parsed.indexes`.
62
+ references: parsed.references.map((reference) => ({
63
+ column: reference.column,
64
+ parentTable: reference.parentTable,
65
+ onDelete: reference.onDelete,
66
+ })),
60
67
  // Indexes flow through from the migration parser (already validated:
61
68
  // columns exist, names unique per schema) in declaration order.
62
69
  indexes: parsed.indexes,
@@ -103,6 +110,43 @@ function applyEncryption(parsed, scopes, encryptedColumns) {
103
110
  };
104
111
  });
105
112
  }
113
+ /**
114
+ * §6.11 hard errors: a declared reference must name an existing parent table
115
+ * whose primary key has the child column's type, and parent and child must
116
+ * declare the same scope patterns so a cascade never crosses an
117
+ * authorization boundary.
118
+ */
119
+ function validateReferences(tables, parsedTables) {
120
+ const patternsOf = (table) => table.scopes
121
+ .map((scope) => scope.pattern)
122
+ .sort()
123
+ .join('\u0000');
124
+ for (const table of tables) {
125
+ for (const reference of table.references) {
126
+ const parent = tables.find((candidate) => candidate.name === reference.parentTable);
127
+ if (parent === undefined) {
128
+ throw new TypegenError(MANIFEST_FILENAME, `table ${table.name}: reference column ${JSON.stringify(reference.column)} names unknown table ${JSON.stringify(reference.parentTable)}`);
129
+ }
130
+ const parsed = parsedTables
131
+ .get(table.name)
132
+ ?.references.find((candidate) => candidate.column === reference.column);
133
+ if (parsed !== undefined && parsed.parentPk !== parent.primaryKey) {
134
+ throw new TypegenError(MANIFEST_FILENAME, `table ${table.name}: reference column ${JSON.stringify(reference.column)} names ${parent.name}.${parsed.parentPk}, but a reference only targets the parent's primary key ${parent.name}.${parent.primaryKey} (§6.11)`);
135
+ }
136
+ const child = table.columns.find((c) => c.name === reference.column);
137
+ const parentKey = parent.columns.find((c) => c.name === parent.primaryKey);
138
+ if (child === undefined || parentKey === undefined) {
139
+ throw new Error(`unreachable: ${table.name}.${reference.column} or ${parent.name}.${parent.primaryKey} is missing`);
140
+ }
141
+ if (child.type !== parentKey.type) {
142
+ 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
+ }
144
+ if (patternsOf(table) !== patternsOf(parent)) {
145
+ 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
+ }
147
+ }
148
+ }
149
+ }
106
150
  function buildSubscription(sub, tables) {
107
151
  const table = tables.find((t) => t.name === sub.table);
108
152
  if (table === undefined) {
@@ -176,6 +220,7 @@ export function buildIr(manifest, migrations, lockedNames) {
176
220
  throw new TypegenError(MANIFEST_FILENAME, `migrated table ${JSON.stringify(name)} is missing from the manifest's tables list — every migrated table must be declared (fail loud; internal tables are a future manifest extension)`);
177
221
  }
178
222
  }
223
+ validateReferences(tables, parsedTables);
179
224
  const subscriptions = manifest.subscriptions.map((sub) => buildSubscription(sub, tables));
180
225
  const last = manifest.schemaVersions[manifest.schemaVersions.length - 1];
181
226
  if (last === undefined)
package/dist/ir.d.ts CHANGED
@@ -37,6 +37,15 @@ export interface IrIndex {
37
37
  readonly columns: readonly string[];
38
38
  readonly unique: boolean;
39
39
  }
40
+ /** One declared reference (§6.11): a column constraint the server enforces
41
+ * with `RESTRICT`, `CASCADE`, or `SET NULL`. `parentTable` is the referenced
42
+ * table; the referenced column is that table's primary key. IR metadata:
43
+ * the local replica DDL omits the clause (§6.11). */
44
+ export interface IrReference {
45
+ readonly column: string;
46
+ readonly parentTable: string;
47
+ readonly onDelete: 'RESTRICT' | 'CASCADE' | 'SET NULL';
48
+ }
40
49
  /** One client-local contentful FTS5 projection. It is owned by the
41
50
  * synced table in whose `ftsIndexes` array it appears and never enters the
42
51
  * row codec, server schema, scopes, or mutation surface. */
@@ -51,6 +60,9 @@ export interface IrTable {
51
60
  /** Declaration order — this IS the §2.4 row-codec positional order. */
52
61
  readonly columns: readonly IrColumn[];
53
62
  readonly scopes: readonly IrScope[];
63
+ /** Declared references (§6.11), in declaration order. Additive under
64
+ * irVersion 1: omitted for tables that declare none. */
65
+ readonly references: readonly IrReference[];
54
66
  /** Local secondary indexes (§migration subset), in declaration order.
55
67
  * Additive under irVersion 1: absent/empty for tables that declare none. */
56
68
  readonly indexes: readonly IrIndex[];
package/dist/ir.js CHANGED
@@ -62,6 +62,14 @@ export function serializeIr(ir) {
62
62
  variable: scope.variable,
63
63
  column: scope.column,
64
64
  })),
65
+ // Declared references (§6.11) are additive under irVersion 1: emitted
66
+ // only when the table declares at least one, so reference-free tables
67
+ // stay byte-identical.
68
+ ...(table.references.length > 0
69
+ ? {
70
+ references: table.references.map((reference) => ({ ...reference })),
71
+ }
72
+ : {}),
65
73
  // Indexes are additive under irVersion 1: emitted only when the table
66
74
  // declares at least one, so index-free tables (every pre-index manifest)
67
75
  // stay byte-identical and --check fresh. Declaration order preserved.
package/dist/sql.d.ts CHANGED
@@ -1,8 +1,19 @@
1
- import type { IrColumn, IrFtsIndex, IrIndex } from './ir.js';
1
+ import type { IrColumn, IrFtsIndex, IrIndex, IrReference } from './ir.js';
2
+ /** Parse-time declared reference (§6.11). `parentPk` is validated against
3
+ * the parent's primary key once every migration has been applied; the IR
4
+ * keeps only `{ column, parentTable, onDelete }`. */
5
+ export interface ParsedReference {
6
+ readonly column: string;
7
+ readonly parentTable: string;
8
+ readonly parentPk: string;
9
+ readonly onDelete: IrReference['onDelete'];
10
+ }
2
11
  export interface ParsedTable {
3
12
  readonly name: string;
4
13
  primaryKey: string;
5
14
  readonly columns: IrColumn[];
15
+ /** Declared references (§6.11), in declaration order. */
16
+ readonly references: ParsedReference[];
6
17
  /** Local secondary indexes, in declaration order (CREATE INDEX subset). */
7
18
  readonly indexes: IrIndex[];
8
19
  /** Client-local contentful FTS5 projections. */
package/dist/sql.js CHANGED
@@ -12,7 +12,8 @@
12
12
  * - `CREATE VIRTUAL TABLE name USING fts5(cols…, content=table,
13
13
  * [tokenize='allowlisted tokenizer'])` (client-local FTS5 projection)
14
14
  * - column defs: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL]
15
- * [DEFAULT literal]`; `ALTER TABLE … ADD COLUMN` is restricted to nullable
15
+ * [DEFAULT literal] [REFERENCES parent(pk) [ON DELETE RESTRICT | CASCADE |
16
+ * SET NULL]]`; `ALTER TABLE … ADD COLUMN` is restricted to nullable
16
17
  * columns because Syncular does not execute SQL-default backfills
17
18
  * - `--` and C-style comments
18
19
  *
@@ -260,6 +261,7 @@ function parseColumnDef(cursor, allowPrimaryKey) {
260
261
  const type = parseColumnType(cursor, name);
261
262
  let nullable = true;
262
263
  let primaryKey = false;
264
+ let reference;
263
265
  for (;;) {
264
266
  const token = cursor.peek();
265
267
  if (token === undefined || token.kind === 'punct')
@@ -291,17 +293,77 @@ function parseColumnDef(cursor, allowPrimaryKey) {
291
293
  // Literal defaults are accepted and ignored: typegen extracts the
292
294
  // schema shape; running migrations is the host's job.
293
295
  }
296
+ else if (word === 'REFERENCES') {
297
+ if (reference !== undefined) {
298
+ cursor.fail(`column ${name}: at most one REFERENCES clause is allowed`);
299
+ }
300
+ cursor.next();
301
+ const parentTable = cursor.identifier(`a referenced table for ${name}`);
302
+ cursor.expectPunct('(', `after REFERENCES ${parentTable}`);
303
+ const parentPk = cursor.identifier(`a referenced column for ${name}`);
304
+ cursor.expectPunct(')', 'after the referenced column');
305
+ let onDelete = 'RESTRICT';
306
+ if (cursor.eatWord('ON')) {
307
+ const action = cursor.identifier('ON DELETE for a reference');
308
+ const actionKind = action.toUpperCase();
309
+ if (actionKind === 'UPDATE') {
310
+ cursor.fail(`column ${name}: ON UPDATE is unsupported — the primary key is immutable`);
311
+ }
312
+ if (actionKind !== 'DELETE') {
313
+ cursor.fail(`column ${name}: unsupported reference action ${JSON.stringify(action)} (only ON DELETE)`);
314
+ }
315
+ const behavior = cursor.identifier('an ON DELETE behavior');
316
+ const behaviorKind = behavior.toUpperCase();
317
+ if (behaviorKind === 'RESTRICT') {
318
+ onDelete = 'RESTRICT';
319
+ }
320
+ else if (behaviorKind === 'CASCADE') {
321
+ onDelete = 'CASCADE';
322
+ }
323
+ else if (behaviorKind === 'SET') {
324
+ const second = cursor.identifier('SET NULL');
325
+ if (second.toUpperCase() === 'NULL') {
326
+ onDelete = 'SET NULL';
327
+ }
328
+ else if (second.toUpperCase() === 'DEFAULT') {
329
+ cursor.fail(`column ${name}: SET DEFAULT is unsupported (absent ON DELETE means RESTRICT)`);
330
+ }
331
+ else {
332
+ cursor.fail(`column ${name}: unsupported ON DELETE behavior ${JSON.stringify(`SET ${second}`)} (only RESTRICT, CASCADE, or SET NULL)`);
333
+ }
334
+ }
335
+ else if (behaviorKind === 'NO') {
336
+ cursor.expectWord('ACTION', 'after NO');
337
+ cursor.fail(`column ${name}: NO ACTION is unsupported (absent ON DELETE means RESTRICT)`);
338
+ }
339
+ else {
340
+ cursor.fail(`column ${name}: unsupported ON DELETE behavior ${JSON.stringify(behavior)} (only RESTRICT, CASCADE, or SET NULL)`);
341
+ }
342
+ }
343
+ reference = { column: name, parentTable, parentPk, onDelete };
344
+ }
294
345
  else {
295
346
  cursor.fail(`column ${name}: unsupported column constraint ${JSON.stringify(token.text)}`);
296
347
  }
297
348
  }
298
349
  if (primaryKey)
299
350
  nullable = false;
351
+ // §6.11: SET NULL needs a nullable child column; the check runs after the
352
+ // whole constraint list so clause order does not matter.
353
+ if (reference !== undefined &&
354
+ reference.onDelete === 'SET NULL' &&
355
+ !nullable) {
356
+ cursor.fail(`column ${name}: ON DELETE SET NULL requires a nullable column`);
357
+ }
300
358
  // §5.10.1: a crdt column carries a crdtType (default `yjs-doc`).
301
359
  const column = type === 'crdt'
302
360
  ? { name, type, nullable, crdtType: DEFAULT_CRDT_TYPE }
303
361
  : { name, type, nullable };
304
- return { column, primaryKey };
362
+ return {
363
+ column,
364
+ primaryKey,
365
+ ...(reference !== undefined ? { reference } : {}),
366
+ };
305
367
  }
306
368
  /**
307
369
  * Dispatch a `CREATE …` statement: `CREATE TABLE`, `CREATE INDEX`, or
@@ -434,6 +496,35 @@ function parseCreateVirtualTable(cursor, tables, source, options) {
434
496
  if (options.lockedHistory === true)
435
497
  lockedHistoryObjects.add(ftsIndex);
436
498
  }
499
+ /**
500
+ * §6.11: record one declared reference on its table and emit the non-unique
501
+ * index over the child column, so the server reaches children through
502
+ * `scanRowsByIndex` (§6.8). Index names share the schema namespace, so a
503
+ * collision with a table, index, or FTS projection is a hard error.
504
+ */
505
+ function addReference(tables, table, reference, source, options) {
506
+ const name = `idx_${table.name}_${reference.column}_ref`;
507
+ if (tables.has(name)) {
508
+ throw new TypegenError(source, `table ${table.name}: reference index ${name} conflicts with a synced table`);
509
+ }
510
+ for (const candidate of tables.values()) {
511
+ if (candidate.indexes.some((index) => index.name === name) ||
512
+ candidate.ftsIndexes.some((index) => index.name === name)) {
513
+ throw new TypegenError(source, `table ${table.name}: reference index ${name} conflicts with another schema object`);
514
+ }
515
+ }
516
+ table.references.push({
517
+ column: reference.column,
518
+ parentTable: reference.parentTable,
519
+ parentPk: reference.parentPk,
520
+ onDelete: reference.onDelete,
521
+ });
522
+ const index = { name, columns: [reference.column], unique: false };
523
+ table.indexes.push(index);
524
+ indexIdentifierSources.set(index, source);
525
+ if (options.lockedHistory === true)
526
+ lockedHistoryObjects.add(index);
527
+ }
437
528
  function parseCreateTable(cursor, tables, droppedTables, source, options) {
438
529
  if (cursor.eatWord('IF')) {
439
530
  cursor.expectWord('NOT', 'after IF');
@@ -455,6 +546,7 @@ function parseCreateTable(cursor, tables, droppedTables, source, options) {
455
546
  cursor.expectPunct('(', `after CREATE TABLE ${name}`);
456
547
  const columns = [];
457
548
  const primaryKeys = [];
549
+ const references = [];
458
550
  for (;;) {
459
551
  const head = cursor.peek();
460
552
  if (head?.kind === 'word') {
@@ -483,6 +575,8 @@ function parseCreateTable(cursor, tables, droppedTables, source, options) {
483
575
  columns.push(def.column);
484
576
  if (def.primaryKey)
485
577
  primaryKeys.push(def.column.name);
578
+ if (def.reference !== undefined)
579
+ references.push(def.reference);
486
580
  }
487
581
  }
488
582
  else {
@@ -515,6 +609,7 @@ function parseCreateTable(cursor, tables, droppedTables, source, options) {
515
609
  name,
516
610
  primaryKey,
517
611
  columns: finalColumns,
612
+ references: [],
518
613
  indexes: [],
519
614
  ftsIndexes: [],
520
615
  };
@@ -527,6 +622,9 @@ function parseCreateTable(cursor, tables, droppedTables, source, options) {
527
622
  if (options.lockedHistory === true)
528
623
  lockedHistoryObjects.add(column);
529
624
  }
625
+ for (const reference of references) {
626
+ addReference(tables, table, reference, source, options);
627
+ }
530
628
  }
531
629
  /**
532
630
  * `CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON table (col [, col…])`.
@@ -628,6 +726,9 @@ function parseAlterTable(cursor, tables, source, options) {
628
726
  columnIdentifierSources.set(def.column, source);
629
727
  if (options.lockedHistory === true)
630
728
  lockedHistoryObjects.add(def.column);
729
+ if (def.reference !== undefined) {
730
+ addReference(tables, table, def.reference, source, options);
731
+ }
631
732
  }
632
733
  /** `DROP TABLE [IF EXISTS] name`; table-name reuse remains unsupported. */
633
734
  function parseDropTable(cursor, tables, droppedTables) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/typegen",
3
- "version": "0.20.1",
3
+ "version": "0.21.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.20.1"
59
+ "@syncular/core": "0.21.1"
60
60
  },
61
61
  "devDependencies": {
62
- "@syncular/server": "0.20.1"
62
+ "@syncular/server": "0.21.1"
63
63
  }
64
64
  }
package/src/emit.ts CHANGED
@@ -96,6 +96,17 @@ function emitSchema(ir: IrDocument): string {
96
96
  );
97
97
  }
98
98
  lines.push(' ],');
99
+ // §6.11 declared references — emitted only when the table declares any,
100
+ // so reference-free tables keep their exact pre-reference generated bytes.
101
+ if (table.references.length > 0) {
102
+ lines.push(' references: [');
103
+ for (const reference of table.references) {
104
+ lines.push(
105
+ ` { column: ${quote(reference.column)}, parentTable: ${quote(reference.parentTable)}, onDelete: ${quote(reference.onDelete)} },`,
106
+ );
107
+ }
108
+ lines.push(' ],');
109
+ }
99
110
  // Local secondary indexes — emitted only when the table declares any, so
100
111
  // index-free tables keep their exact pre-index generated bytes.
101
112
  if (table.indexes.length > 0) {
package/src/generate.ts CHANGED
@@ -132,6 +132,13 @@ function buildTable(
132
132
  primaryKey: parsed.primaryKey,
133
133
  columns,
134
134
  scopes,
135
+ // Declared references (§6.11), in declaration order. The generated index
136
+ // over each child column already rides in `parsed.indexes`.
137
+ references: parsed.references.map((reference) => ({
138
+ column: reference.column,
139
+ parentTable: reference.parentTable,
140
+ onDelete: reference.onDelete,
141
+ })),
135
142
  // Indexes flow through from the migration parser (already validated:
136
143
  // columns exist, names unique per schema) in declaration order.
137
144
  indexes: parsed.indexes,
@@ -197,6 +204,66 @@ function applyEncryption(
197
204
  });
198
205
  }
199
206
 
207
+ /**
208
+ * §6.11 hard errors: a declared reference must name an existing parent table
209
+ * whose primary key has the child column's type, and parent and child must
210
+ * declare the same scope patterns so a cascade never crosses an
211
+ * authorization boundary.
212
+ */
213
+ function validateReferences(
214
+ tables: readonly IrTable[],
215
+ parsedTables: ReadonlyMap<string, ParsedTable>,
216
+ ): void {
217
+ const patternsOf = (table: IrTable): string =>
218
+ table.scopes
219
+ .map((scope) => scope.pattern)
220
+ .sort()
221
+ .join('\u0000');
222
+ for (const table of tables) {
223
+ for (const reference of table.references) {
224
+ const parent = tables.find(
225
+ (candidate) => candidate.name === reference.parentTable,
226
+ );
227
+ if (parent === undefined) {
228
+ throw new TypegenError(
229
+ MANIFEST_FILENAME,
230
+ `table ${table.name}: reference column ${JSON.stringify(reference.column)} names unknown table ${JSON.stringify(reference.parentTable)}`,
231
+ );
232
+ }
233
+ const parsed = parsedTables
234
+ .get(table.name)
235
+ ?.references.find((candidate) => candidate.column === reference.column);
236
+ if (parsed !== undefined && parsed.parentPk !== parent.primaryKey) {
237
+ throw new TypegenError(
238
+ MANIFEST_FILENAME,
239
+ `table ${table.name}: reference column ${JSON.stringify(reference.column)} names ${parent.name}.${parsed.parentPk}, but a reference only targets the parent's primary key ${parent.name}.${parent.primaryKey} (§6.11)`,
240
+ );
241
+ }
242
+ const child = table.columns.find((c) => c.name === reference.column);
243
+ const parentKey = parent.columns.find(
244
+ (c) => c.name === parent.primaryKey,
245
+ );
246
+ if (child === undefined || parentKey === undefined) {
247
+ throw new Error(
248
+ `unreachable: ${table.name}.${reference.column} or ${parent.name}.${parent.primaryKey} is missing`,
249
+ );
250
+ }
251
+ if (child.type !== parentKey.type) {
252
+ throw new TypegenError(
253
+ MANIFEST_FILENAME,
254
+ `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)`,
255
+ );
256
+ }
257
+ if (patternsOf(table) !== patternsOf(parent)) {
258
+ throw new TypegenError(
259
+ MANIFEST_FILENAME,
260
+ `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)`,
261
+ );
262
+ }
263
+ }
264
+ }
265
+ }
266
+
200
267
  function buildSubscription(
201
268
  sub: Manifest['subscriptions'][number],
202
269
  tables: readonly IrTable[],
@@ -312,6 +379,7 @@ export function buildIr(
312
379
  );
313
380
  }
314
381
  }
382
+ validateReferences(tables, parsedTables);
315
383
  const subscriptions = manifest.subscriptions.map((sub) =>
316
384
  buildSubscription(sub, tables),
317
385
  );
package/src/ir.ts CHANGED
@@ -64,6 +64,16 @@ export interface IrIndex {
64
64
  readonly unique: boolean;
65
65
  }
66
66
 
67
+ /** One declared reference (§6.11): a column constraint the server enforces
68
+ * with `RESTRICT`, `CASCADE`, or `SET NULL`. `parentTable` is the referenced
69
+ * table; the referenced column is that table's primary key. IR metadata:
70
+ * the local replica DDL omits the clause (§6.11). */
71
+ export interface IrReference {
72
+ readonly column: string;
73
+ readonly parentTable: string;
74
+ readonly onDelete: 'RESTRICT' | 'CASCADE' | 'SET NULL';
75
+ }
76
+
67
77
  /** One client-local contentful FTS5 projection. It is owned by the
68
78
  * synced table in whose `ftsIndexes` array it appears and never enters the
69
79
  * row codec, server schema, scopes, or mutation surface. */
@@ -79,6 +89,9 @@ export interface IrTable {
79
89
  /** Declaration order — this IS the §2.4 row-codec positional order. */
80
90
  readonly columns: readonly IrColumn[];
81
91
  readonly scopes: readonly IrScope[];
92
+ /** Declared references (§6.11), in declaration order. Additive under
93
+ * irVersion 1: omitted for tables that declare none. */
94
+ readonly references: readonly IrReference[];
82
95
  /** Local secondary indexes (§migration subset), in declaration order.
83
96
  * Additive under irVersion 1: absent/empty for tables that declare none. */
84
97
  readonly indexes: readonly IrIndex[];
@@ -175,6 +188,14 @@ export function serializeIr(ir: IrDocument): string {
175
188
  variable: scope.variable,
176
189
  column: scope.column,
177
190
  })),
191
+ // Declared references (§6.11) are additive under irVersion 1: emitted
192
+ // only when the table declares at least one, so reference-free tables
193
+ // stay byte-identical.
194
+ ...(table.references.length > 0
195
+ ? {
196
+ references: table.references.map((reference) => ({ ...reference })),
197
+ }
198
+ : {}),
178
199
  // Indexes are additive under irVersion 1: emitted only when the table
179
200
  // declares at least one, so index-free tables (every pre-index manifest)
180
201
  // stay byte-identical and --check fresh. Declaration order preserved.
package/src/sql.ts CHANGED
@@ -12,7 +12,8 @@
12
12
  * - `CREATE VIRTUAL TABLE name USING fts5(cols…, content=table,
13
13
  * [tokenize='allowlisted tokenizer'])` (client-local FTS5 projection)
14
14
  * - column defs: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL]
15
- * [DEFAULT literal]`; `ALTER TABLE … ADD COLUMN` is restricted to nullable
15
+ * [DEFAULT literal] [REFERENCES parent(pk) [ON DELETE RESTRICT | CASCADE |
16
+ * SET NULL]]`; `ALTER TABLE … ADD COLUMN` is restricted to nullable
16
17
  * columns because Syncular does not execute SQL-default backfills
17
18
  * - `--` and C-style comments
18
19
  *
@@ -23,7 +24,13 @@
23
24
  */
24
25
  import { validatePortableRelationalIdentifier } from '@syncular/core';
25
26
  import { TypegenError } from './errors';
26
- import type { IrColumn, IrColumnType, IrFtsIndex, IrIndex } from './ir';
27
+ import type {
28
+ IrColumn,
29
+ IrColumnType,
30
+ IrFtsIndex,
31
+ IrIndex,
32
+ IrReference,
33
+ } from './ir';
27
34
 
28
35
  /** SQL type keyword → the §2.4 column types. Case-insensitive. */
29
36
  const TYPE_MAP: Readonly<Record<string, IrColumnType>> = {
@@ -55,10 +62,22 @@ const TYPE_MAP: Readonly<Record<string, IrColumnType>> = {
55
62
  /** Default `crdtType` for a bare `CRDT` keyword (§5.10.1). */
56
63
  const DEFAULT_CRDT_TYPE = 'yjs-doc';
57
64
 
65
+ /** Parse-time declared reference (§6.11). `parentPk` is validated against
66
+ * the parent's primary key once every migration has been applied; the IR
67
+ * keeps only `{ column, parentTable, onDelete }`. */
68
+ export interface ParsedReference {
69
+ readonly column: string;
70
+ readonly parentTable: string;
71
+ readonly parentPk: string;
72
+ readonly onDelete: IrReference['onDelete'];
73
+ }
74
+
58
75
  export interface ParsedTable {
59
76
  readonly name: string;
60
77
  primaryKey: string;
61
78
  readonly columns: IrColumn[];
79
+ /** Declared references (§6.11), in declaration order. */
80
+ readonly references: ParsedReference[];
62
81
  /** Local secondary indexes, in declaration order (CREATE INDEX subset). */
63
82
  readonly indexes: IrIndex[];
64
83
  /** Client-local contentful FTS5 projections. */
@@ -322,6 +341,14 @@ class Cursor {
322
341
  interface ColumnDef {
323
342
  readonly column: IrColumn;
324
343
  readonly primaryKey: boolean;
344
+ /** §6.11: parsed `REFERENCES parent(pk) [ON DELETE …]`, validated against
345
+ * the accumulated schema after every migration has been applied. */
346
+ readonly reference?: {
347
+ readonly column: string;
348
+ readonly parentTable: string;
349
+ readonly parentPk: string;
350
+ readonly onDelete: IrReference['onDelete'];
351
+ };
325
352
  }
326
353
 
327
354
  function parseColumnType(cursor: Cursor, columnName: string): IrColumnType {
@@ -345,6 +372,7 @@ function parseColumnDef(cursor: Cursor, allowPrimaryKey: boolean): ColumnDef {
345
372
  const type = parseColumnType(cursor, name);
346
373
  let nullable = true;
347
374
  let primaryKey = false;
375
+ let reference: ColumnDef['reference'];
348
376
  for (;;) {
349
377
  const token = cursor.peek();
350
378
  if (token === undefined || token.kind === 'punct') break;
@@ -375,6 +403,60 @@ function parseColumnDef(cursor: Cursor, allowPrimaryKey: boolean): ColumnDef {
375
403
  }
376
404
  // Literal defaults are accepted and ignored: typegen extracts the
377
405
  // schema shape; running migrations is the host's job.
406
+ } else if (word === 'REFERENCES') {
407
+ if (reference !== undefined) {
408
+ cursor.fail(`column ${name}: at most one REFERENCES clause is allowed`);
409
+ }
410
+ cursor.next();
411
+ const parentTable = cursor.identifier(`a referenced table for ${name}`);
412
+ cursor.expectPunct('(', `after REFERENCES ${parentTable}`);
413
+ const parentPk = cursor.identifier(`a referenced column for ${name}`);
414
+ cursor.expectPunct(')', 'after the referenced column');
415
+ let onDelete: IrReference['onDelete'] = 'RESTRICT';
416
+ if (cursor.eatWord('ON')) {
417
+ const action = cursor.identifier('ON DELETE for a reference');
418
+ const actionKind = action.toUpperCase();
419
+ if (actionKind === 'UPDATE') {
420
+ cursor.fail(
421
+ `column ${name}: ON UPDATE is unsupported — the primary key is immutable`,
422
+ );
423
+ }
424
+ if (actionKind !== 'DELETE') {
425
+ cursor.fail(
426
+ `column ${name}: unsupported reference action ${JSON.stringify(action)} (only ON DELETE)`,
427
+ );
428
+ }
429
+ const behavior = cursor.identifier('an ON DELETE behavior');
430
+ const behaviorKind = behavior.toUpperCase();
431
+ if (behaviorKind === 'RESTRICT') {
432
+ onDelete = 'RESTRICT';
433
+ } else if (behaviorKind === 'CASCADE') {
434
+ onDelete = 'CASCADE';
435
+ } else if (behaviorKind === 'SET') {
436
+ const second = cursor.identifier('SET NULL');
437
+ if (second.toUpperCase() === 'NULL') {
438
+ onDelete = 'SET NULL';
439
+ } else if (second.toUpperCase() === 'DEFAULT') {
440
+ cursor.fail(
441
+ `column ${name}: SET DEFAULT is unsupported (absent ON DELETE means RESTRICT)`,
442
+ );
443
+ } else {
444
+ cursor.fail(
445
+ `column ${name}: unsupported ON DELETE behavior ${JSON.stringify(`SET ${second}`)} (only RESTRICT, CASCADE, or SET NULL)`,
446
+ );
447
+ }
448
+ } else if (behaviorKind === 'NO') {
449
+ cursor.expectWord('ACTION', 'after NO');
450
+ cursor.fail(
451
+ `column ${name}: NO ACTION is unsupported (absent ON DELETE means RESTRICT)`,
452
+ );
453
+ } else {
454
+ cursor.fail(
455
+ `column ${name}: unsupported ON DELETE behavior ${JSON.stringify(behavior)} (only RESTRICT, CASCADE, or SET NULL)`,
456
+ );
457
+ }
458
+ }
459
+ reference = { column: name, parentTable, parentPk, onDelete };
378
460
  } else {
379
461
  cursor.fail(
380
462
  `column ${name}: unsupported column constraint ${JSON.stringify(token.text)}`,
@@ -382,12 +464,27 @@ function parseColumnDef(cursor: Cursor, allowPrimaryKey: boolean): ColumnDef {
382
464
  }
383
465
  }
384
466
  if (primaryKey) nullable = false;
467
+ // §6.11: SET NULL needs a nullable child column; the check runs after the
468
+ // whole constraint list so clause order does not matter.
469
+ if (
470
+ reference !== undefined &&
471
+ reference.onDelete === 'SET NULL' &&
472
+ !nullable
473
+ ) {
474
+ cursor.fail(
475
+ `column ${name}: ON DELETE SET NULL requires a nullable column`,
476
+ );
477
+ }
385
478
  // §5.10.1: a crdt column carries a crdtType (default `yjs-doc`).
386
479
  const column: IrColumn =
387
480
  type === 'crdt'
388
481
  ? { name, type, nullable, crdtType: DEFAULT_CRDT_TYPE }
389
482
  : { name, type, nullable };
390
- return { column, primaryKey };
483
+ return {
484
+ column,
485
+ primaryKey,
486
+ ...(reference !== undefined ? { reference } : {}),
487
+ };
391
488
  }
392
489
 
393
490
  /**
@@ -559,6 +656,49 @@ function parseCreateVirtualTable(
559
656
  if (options.lockedHistory === true) lockedHistoryObjects.add(ftsIndex);
560
657
  }
561
658
 
659
+ /**
660
+ * §6.11: record one declared reference on its table and emit the non-unique
661
+ * index over the child column, so the server reaches children through
662
+ * `scanRowsByIndex` (§6.8). Index names share the schema namespace, so a
663
+ * collision with a table, index, or FTS projection is a hard error.
664
+ */
665
+ function addReference(
666
+ tables: Map<string, ParsedTable>,
667
+ table: ParsedTable,
668
+ reference: NonNullable<ColumnDef['reference']>,
669
+ source: string,
670
+ options: ApplyMigrationSqlOptions,
671
+ ): void {
672
+ const name = `idx_${table.name}_${reference.column}_ref`;
673
+ if (tables.has(name)) {
674
+ throw new TypegenError(
675
+ source,
676
+ `table ${table.name}: reference index ${name} conflicts with a synced table`,
677
+ );
678
+ }
679
+ for (const candidate of tables.values()) {
680
+ if (
681
+ candidate.indexes.some((index) => index.name === name) ||
682
+ candidate.ftsIndexes.some((index) => index.name === name)
683
+ ) {
684
+ throw new TypegenError(
685
+ source,
686
+ `table ${table.name}: reference index ${name} conflicts with another schema object`,
687
+ );
688
+ }
689
+ }
690
+ table.references.push({
691
+ column: reference.column,
692
+ parentTable: reference.parentTable,
693
+ parentPk: reference.parentPk,
694
+ onDelete: reference.onDelete,
695
+ });
696
+ const index: IrIndex = { name, columns: [reference.column], unique: false };
697
+ table.indexes.push(index);
698
+ indexIdentifierSources.set(index, source);
699
+ if (options.lockedHistory === true) lockedHistoryObjects.add(index);
700
+ }
701
+
562
702
  function parseCreateTable(
563
703
  cursor: Cursor,
564
704
  tables: Map<string, ParsedTable>,
@@ -590,6 +730,7 @@ function parseCreateTable(
590
730
  cursor.expectPunct('(', `after CREATE TABLE ${name}`);
591
731
  const columns: IrColumn[] = [];
592
732
  const primaryKeys: string[] = [];
733
+ const references: NonNullable<ColumnDef['reference']>[] = [];
593
734
  for (;;) {
594
735
  const head = cursor.peek();
595
736
  if (head?.kind === 'word') {
@@ -621,6 +762,7 @@ function parseCreateTable(
621
762
  }
622
763
  columns.push(def.column);
623
764
  if (def.primaryKey) primaryKeys.push(def.column.name);
765
+ if (def.reference !== undefined) references.push(def.reference);
624
766
  }
625
767
  } else {
626
768
  cursor.fail(`table ${name}: expected a column definition`);
@@ -660,6 +802,7 @@ function parseCreateTable(
660
802
  name,
661
803
  primaryKey,
662
804
  columns: finalColumns,
805
+ references: [],
663
806
  indexes: [],
664
807
  ftsIndexes: [],
665
808
  };
@@ -670,6 +813,9 @@ function parseCreateTable(
670
813
  columnIdentifierSources.set(column, source);
671
814
  if (options.lockedHistory === true) lockedHistoryObjects.add(column);
672
815
  }
816
+ for (const reference of references) {
817
+ addReference(tables, table, reference, source, options);
818
+ }
673
819
  }
674
820
 
675
821
  /**
@@ -804,6 +950,9 @@ function parseAlterTable(
804
950
  table.columns.push(def.column);
805
951
  columnIdentifierSources.set(def.column, source);
806
952
  if (options.lockedHistory === true) lockedHistoryObjects.add(def.column);
953
+ if (def.reference !== undefined) {
954
+ addReference(tables, table, def.reference, source, options);
955
+ }
807
956
  }
808
957
 
809
958
  /** `DROP TABLE [IF EXISTS] name`; table-name reuse remains unsupported. */