@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 +9 -0
- package/dist/generate.js +45 -0
- package/dist/ir.d.ts +12 -0
- package/dist/ir.js +8 -0
- package/dist/sql.d.ts +12 -1
- package/dist/sql.js +103 -2
- package/package.json +3 -3
- package/src/emit.ts +11 -0
- package/src/generate.ts +68 -0
- package/src/ir.ts +21 -0
- package/src/sql.ts +152 -3
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]
|
|
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 {
|
|
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.
|
|
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.
|
|
59
|
+
"@syncular/core": "0.21.1"
|
|
60
60
|
},
|
|
61
61
|
"devDependencies": {
|
|
62
|
-
"@syncular/server": "0.
|
|
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]
|
|
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 {
|
|
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 {
|
|
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. */
|