@syncular/typegen 0.30.15 → 0.31.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 (2) hide show
  1. package/README.md +44 -2
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -259,7 +259,7 @@ duplicate ordinals are errors). The parser accepts exactly:
259
259
  - `DROP INDEX [IF EXISTS] name`
260
260
  - `DROP TABLE [IF EXISTS] name`
261
261
  - `CREATE VIRTUAL TABLE [IF NOT EXISTS] name USING fts5( text-col [, text-col…], content = table [, tokenize = 'allowlisted tokenizer'] )`
262
- - column-def: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL] [DEFAULT literal]`
262
+ - column-def: `name TYPE [PRIMARY KEY] [NOT NULL] [NULL] [DEFAULT literal] [REFERENCES parent(pk) [ON DELETE RESTRICT | CASCADE | SET NULL]]`
263
263
  - `--` line comments and `/* … */` block comments
264
264
 
265
265
  Type map (case-insensitive) to the six §2.4 types:
@@ -343,7 +343,7 @@ statement (`CREATE TRIGGER/VIEW`, DML, `ALTER … RENAME`, …); unknown
343
343
  or parameterized types (`VARCHAR(36)`); quoted identifiers
344
344
  (`"t"`, `` `t` ``, `[t]`); table constraints (`FOREIGN KEY`, `UNIQUE`,
345
345
  `CHECK`, `CONSTRAINT`); column constraints beyond the list above
346
- (`REFERENCES`, `CHECK`, `COLLATE`, …); `DEFAULT (expression)`; composite
346
+ (`CHECK`, `COLLATE`, …); `DEFAULT (expression)`; composite
347
347
  or missing primary keys; `PRIMARY KEY` on `ADD COLUMN`; duplicate
348
348
  tables/columns; ASC/DESC, expression, or partial (`WHERE`) index columns; a
349
349
  duplicate or unknown-column index; unsupported virtual-table modules or FTS5
@@ -356,6 +356,48 @@ the host's job. Recording them is not needed by any emitter today. On
356
356
  `ALTER TABLE … ADD COLUMN`, a literal default does not make a non-null append
357
357
  safe and is rejected as described in the migration-lock section above.
358
358
 
359
+ ### Constraints: support and enforcement
360
+
361
+ Typegen accepts the declarations below. Unsupported constraints fail during
362
+ parsing; accepted declarations are enforced at the listed layers.
363
+
364
+ | Declaration | Accepted | Enforced by |
365
+ |---|---|---|
366
+ | Column `NOT NULL`, or a primary-key column | yes | The §2.4 row codec, logically: the server candidate commit and every client write/apply reject a null in a non-nullable column. The TS local mirror also declares `NOT NULL`; the Rust local tables carry bare column names and rely on the codec. |
367
+ | Single-column `PRIMARY KEY`, inline or table-level | yes | The row codec validates the key. Both client mirrors declare a primary key; the server projection keys rows by partition and the encoded row identity. |
368
+ | Column `DEFAULT literal` | accepted, ignored | Nothing. Typegen records no default and fills none; the host runs the migration SQL where a default matters. |
369
+ | Nullable `ALTER TABLE … ADD COLUMN` | yes | A physical column in every mirror. A SQL `DEFAULT` on the same statement is ignored and never backfills Syncular payloads. |
370
+ | `ALTER TABLE … ADD COLUMN … NOT NULL` | rejected | not applicable |
371
+ | Column `REFERENCES parent(pk) [ON DELETE RESTRICT\|CASCADE\|SET NULL]` | yes | The server commit boundary only (§6.11); the local SQLite DDL deliberately omits the clause. |
372
+ | `CREATE [UNIQUE] INDEX` over existing columns | yes | A physical index in both client mirrors, the server relational projection, and typegen's named-query type-check DB. The `UNIQUE` variant additionally enforces uniqueness atomically on a local write (§7.2: `sync.constraint_violation`, no outbox entry, no revision advance) and on the server commit. |
373
+ | Inline column `CHECK (expr)` | rejected | not applicable (see the gap below) |
374
+ | Table-level `UNIQUE (…)`, `CHECK (…)`, `CONSTRAINT name …`, `FOREIGN KEY …` | rejected | not applicable (see the gap below) |
375
+ | Column `COLLATE …` | rejected | not applicable |
376
+
377
+ **The closed-value-set gap.** The IR column (`IrColumn`) carries no `enum` or
378
+ `check` metadata, so a closed value set such as a state column cannot be
379
+ declared in migration SQL. Inline `CHECK` is rejected twice over: `CHECK (n)`
380
+ reads `CHECK` as an unsupported column constraint, and `CHECK (n > 0)` fails at
381
+ `>` because the lexer does not read comparison operators. Table-level `CHECK`
382
+ and `CONSTRAINT` are rejected as unsupported table constraints. Declare the
383
+ column with the type it stores and put the rule in a §6.7 server
384
+ write-validator, which validates each candidate row operation during commit
385
+ application. A `ValidationRejection` carries the host rejection code. That validator does not run on optimistic local
386
+ writes, so an application that needs immediate local feedback repeats the rule
387
+ in its own pre-write guard. The physical server projection does not carry an
388
+ app `CHECK` either; on a fresh `CREATE TABLE` it declares `NOT NULL` per the
389
+ schema, while columns appended by `ALTER TABLE` are physically nullable and the
390
+ row codec remains the type authority.
391
+
392
+ **Uniqueness without table-level `UNIQUE`.** SQLite accepts `UNIQUE (a, b)`,
393
+ but the IR models uniqueness as a named `CREATE UNIQUE INDEX` entry, so
394
+ typegen rejects the table constraint. Declare
395
+ `CREATE UNIQUE INDEX name ON table (a, b)` instead. It is accepted with
396
+ `IF NOT EXISTS`, preserves column order, and is materialized by every mirror.
397
+ `NULL` values never conflict, matching SQLite unique-index semantics.
398
+ Table-level `FOREIGN KEY` stays rejected: a reference is a column constraint
399
+ (§6.11).
400
+
359
401
  ## 4. Generated-module contract
360
402
 
361
403
  The emitted `*.generated.ts` module:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/typegen",
3
- "version": "0.30.15",
3
+ "version": "0.31.0",
4
4
  "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Benjamin Kniffler",
@@ -56,9 +56,9 @@
56
56
  "!dist/**/*.test.d.ts"
57
57
  ],
58
58
  "dependencies": {
59
- "@syncular/core": "0.30.15"
59
+ "@syncular/core": "0.31.0"
60
60
  },
61
61
  "devDependencies": {
62
- "@syncular/server": "0.30.15"
62
+ "@syncular/server": "0.31.0"
63
63
  }
64
64
  }