@syncular/typegen 0.99.0 → 0.101.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/generate.js CHANGED
@@ -15,13 +15,13 @@ import { emitQueriesRustModule } from './emit-queries-rust.js';
15
15
  import { emitQueriesSwiftModule } from './emit-queries-swift.js';
16
16
  import { emitSwiftModule } from './emit-swift.js';
17
17
  import { TypegenError } from './errors.js';
18
- import { canonicalizeExtensions, IR_VERSION, irHash, serializeIr, tableGeneration, } from './ir.js';
18
+ import { canonicalizeExtensions, IR_VERSION, irHash, serializeIr, projectionGeneration, tableGeneration, } from './ir.js';
19
19
  import { MANIFEST_FILENAME, parseManifest, } from './manifest.js';
20
20
  import { buildMigrationLock, buildSchemaVersions, lockedMigrationNames, MIGRATION_LOCK_FILENAME, MIGRATION_LOCK_FORMAT_VERSION, readMigrationLock, serializeMigrationLock, updateMigrationLock, upgradeMigrationLock, } from './migration-lock.js';
21
21
  import { validateSchemaIdentifiers } from './naming.js';
22
22
  import { analyzeQueryFile, checkQueryPlan, synthesizeDdl, } from './query.js';
23
23
  import { serializeQueryIr } from './query-ir.js';
24
- import { applyMigrationSql, validateFinalSchemaIdentifiers, } from './sql.js';
24
+ import { ALLOWED_FTS_TOKENIZERS, applyMigrationSql, validateFinalSchemaIdentifiers, } from './sql.js';
25
25
  import { lowerSyqlQuery } from './syql-lowering.js';
26
26
  import { buildSyqlModuleGraph } from './syql-modules.js';
27
27
  import { analyzeSyqlSemantics } from './syql-semantics.js';
@@ -72,6 +72,19 @@ function buildTable(manifestTable, parsed) {
72
72
  // columns exist, names unique per schema) in declaration order.
73
73
  indexes: parsed.indexes,
74
74
  ftsIndexes: parsed.ftsIndexes,
75
+ ...(manifestTable.localProjections
76
+ ? {
77
+ localProjections: manifestTable.localProjections.map((projection) => ({
78
+ name: projection.name,
79
+ generation: projectionGeneration(parsed.name, projection),
80
+ columns: projection.columns,
81
+ ...(projection.fts ? { fts: projection.fts } : {}),
82
+ ...(projection.dependencies
83
+ ? { dependencies: projection.dependencies }
84
+ : {}),
85
+ })),
86
+ }
87
+ : {}),
75
88
  extensions: canonicalizeExtensions(manifestTable.extensions),
76
89
  };
77
90
  }
@@ -249,6 +262,53 @@ export function buildIr(manifest, migrations, lockedNames) {
249
262
  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)`);
250
263
  }
251
264
  }
265
+ const names = new Set(tables
266
+ .flatMap((table) => [
267
+ table.name,
268
+ ...table.indexes.map((index) => index.name),
269
+ ...table.ftsIndexes.map((index) => index.name),
270
+ ])
271
+ .map((name) => name.toLowerCase()));
272
+ const projectionIdentifier = (value) => /^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(value) &&
273
+ !/^(?:_sync|sync_|sqlite_)/i.test(value);
274
+ for (const table of tables) {
275
+ for (const projection of table.localProjections ?? []) {
276
+ const { name } = projection;
277
+ const lower = name.toLowerCase();
278
+ const invalid = (column) => {
279
+ throw new TypegenError(MANIFEST_FILENAME, 'invalid local projection declaration', 'client.schema_invalid', { name, ...(column === undefined ? {} : { column }) });
280
+ };
281
+ if (!projectionIdentifier(name) ||
282
+ names.has(lower) ||
283
+ (projection.fts &&
284
+ (!ALLOWED_FTS_TOKENIZERS.has(projection.fts.tokenize) ||
285
+ !projection.fts.columns.length ||
286
+ new Set(projection.fts.columns).size !==
287
+ projection.fts.columns.length ||
288
+ !projection.fts.columns.every((name) => projection.columns.some((column) => column.name === name && column.declaredType === 'string')))))
289
+ invalid();
290
+ names.add(lower);
291
+ const columns = new Set(projection.fts ? [lower, 'rowid', 'rank'] : []);
292
+ for (const column of projection.columns) {
293
+ const key = column.name.toLowerCase();
294
+ if (!projectionIdentifier(column.name) || columns.has(key))
295
+ invalid(column.name);
296
+ columns.add(key);
297
+ }
298
+ for (const dependency of projection.dependencies ?? []) {
299
+ const dependencyTable = tables.find((item) => item.name === dependency.table);
300
+ const match = dependencyTable?.columns.find((col) => col.name === dependency.column);
301
+ const source = table.columns.find((col) => col.name === dependency.sourceColumn);
302
+ if (!match ||
303
+ !source ||
304
+ match.encrypted ||
305
+ source.encrypted ||
306
+ (table.primaryKey !== dependency.sourceColumn &&
307
+ !table.indexes.some((index) => index.columns[0] === dependency.sourceColumn)))
308
+ invalid(dependency.sourceColumn);
309
+ }
310
+ }
311
+ }
252
312
  validateReferences(tables, parsedTables);
253
313
  const subscriptions = manifest.subscriptions.map((sub) => buildSubscription(sub, tables));
254
314
  const last = manifest.schemaVersions[manifest.schemaVersions.length - 1];
package/dist/ir.d.ts CHANGED
@@ -66,6 +66,23 @@ export interface IrFtsIndex {
66
66
  readonly columns: readonly string[];
67
67
  readonly tokenize: string;
68
68
  }
69
+ export interface IrLocalProjection {
70
+ readonly name: string;
71
+ readonly generation: string;
72
+ readonly columns: readonly {
73
+ readonly name: string;
74
+ readonly declaredType: 'string' | 'integer' | 'real' | 'boolean' | 'json';
75
+ }[];
76
+ readonly fts?: {
77
+ readonly tokenize: string;
78
+ readonly columns: readonly string[];
79
+ };
80
+ readonly dependencies?: readonly {
81
+ readonly table: string;
82
+ readonly column: string;
83
+ readonly sourceColumn: string;
84
+ }[];
85
+ }
69
86
  export interface IrTable {
70
87
  readonly name: string;
71
88
  /** §7.4.3 table generation: an opaque string that changes whenever the
@@ -85,6 +102,7 @@ export interface IrTable {
85
102
  readonly indexes: readonly IrIndex[];
86
103
  /** Client-local FTS5 projections, in migration declaration order. */
87
104
  readonly ftsIndexes: readonly IrFtsIndex[];
105
+ readonly localProjections?: readonly IrLocalProjection[];
88
106
  /** Reserved per-table hook slot (WP-49); empty object for now. */
89
107
  readonly extensions: Readonly<Record<string, unknown>>;
90
108
  }
@@ -133,6 +151,7 @@ export declare function canonicalizeExtensions(value: unknown): unknown;
133
151
  * declaration is unchanged stays equal across schema versions.
134
152
  */
135
153
  export declare function tableGeneration(table: IrTable, migrations: readonly string[]): string;
154
+ export declare function projectionGeneration(table: string, projection: Omit<IrLocalProjection, 'generation'>): string;
136
155
  /** Serialize with a fixed key order — byte-deterministic for equal IRs. */
137
156
  export declare function serializeIr(ir: IrDocument): string;
138
157
  /**
package/dist/ir.js CHANGED
@@ -109,6 +109,12 @@ export function tableGeneration(table, migrations) {
109
109
  .digest('hex')
110
110
  .slice(0, 32);
111
111
  }
112
+ export function projectionGeneration(table, projection) {
113
+ return createHash('sha256')
114
+ .update(JSON.stringify({ table, projection }), 'utf8')
115
+ .digest('hex')
116
+ .slice(0, 32);
117
+ }
112
118
  /** Serialize with a fixed key order — byte-deterministic for equal IRs. */
113
119
  export function serializeIr(ir) {
114
120
  const doc = {
@@ -124,6 +130,9 @@ export function serializeIr(ir) {
124
130
  variable: scope.variable,
125
131
  column: scope.column,
126
132
  }))),
133
+ ...(table.localProjections?.length
134
+ ? { localProjections: table.localProjections }
135
+ : {}),
127
136
  extensions: canonicalizeExtensions(table.extensions),
128
137
  })),
129
138
  subscriptions: ir.subscriptions.map((sub) => ({
@@ -146,10 +155,15 @@ export function serializeIr(ir) {
146
155
  export function serializeSchema(ir) {
147
156
  return JSON.stringify({
148
157
  version: ir.schemaVersion,
149
- tables: ir.tables.map((table) => serializeTableShape(table, table.scopes.map((scope) => ({
150
- pattern: scope.pattern,
151
- column: scope.column,
152
- })))),
158
+ tables: ir.tables.map((table) => ({
159
+ ...serializeTableShape(table, table.scopes.map((scope) => ({
160
+ pattern: scope.pattern,
161
+ column: scope.column,
162
+ }))),
163
+ ...(table.localProjections?.length
164
+ ? { localProjections: table.localProjections }
165
+ : {}),
166
+ })),
153
167
  }, null, 2);
154
168
  }
155
169
  /** Hash of the exact IR file bytes; stamped into generated modules. */
@@ -1,3 +1,49 @@
1
+ /**
2
+ * `syncular.json` manifest: minimal but
3
+ * forward-extensible:
4
+ *
5
+ * ```json
6
+ * {
7
+ * "manifestVersion": 1,
8
+ * "migrations": "./migrations",
9
+ * "output": { "ir": "./syncular.ir.json",
10
+ * "module": "./syncular.generated.ts",
11
+ * "swift": "./Sources/App/Syncular.generated.swift",
12
+ * "kotlin": { "path": "./Syncular.generated.kt",
13
+ * "package": "dev.example" },
14
+ * "dart": "./lib/syncular.generated.dart" },
15
+ * "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
16
+ * "tables": [{ "name": "tasks", "scopes": ["project:{project_id}"] }],
17
+ * "subscriptions": [{ "name": "projectTasks",
18
+ * "scopes": { "project_id": "{projectId}" } }],
19
+ * "extensions": {}
20
+ * }
21
+ * ```
22
+ *
23
+ * - `tables` is ordered: it is the handler-declared bootstrap order (§4.7).
24
+ * - `schemaVersions` is the §1.5 version history: strictly increasing
25
+ * versions, each naming the last migration it includes (`through`); the
26
+ * final entry must cover the final migration.
27
+ * - A subscription is a unit template (SPEC §4.1): one literal or
28
+ * whole-value `{param}` placeholder per scope variable (partial templates
29
+ * are unsupported), no table. The unit covers every table declaring all of
30
+ * its variables; a template that covers no table is an error.
31
+ * - `output.ir` / `output.module` are the always-emitted TS defaults;
32
+ * `output.queryIr` opts into the deterministic analyzed-query document.
33
+ * `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native schema
34
+ * emitters — a bare string is the output path; an object carries
35
+ * language-appropriate options (Kotlin `package`/`objectName`, Swift
36
+ * `enumName`; Dart takes `path` only). This is additive within the `output`
37
+ * object (the same forward-extension shape `output.ir`/`output.module`
38
+ * already use); no `manifestVersion` bump — new *recognized* keys, not
39
+ * tolerated-unknown ones. Absent → that language is not generated (TS
40
+ * stays the default). `output.rust.queriesPath` opts into Rust named-query
41
+ * source over the neutral schema IR consumed by `syncular-client`.
42
+ * - Unknown keys are hard errors everywhere (fail loud; growth happens by
43
+ * bumping `manifestVersion`), except inside `extensions`, the reserved
44
+ * WP-49 passthrough slot copied verbatim into the IR.
45
+ */
46
+ import type { IrLocalProjection } from './ir.js';
1
47
  import { type NamingMode } from './naming.js';
2
48
  /** §7/§8 `.syql` conditional-lowering backend selection. */
3
49
  export type ManifestQueryBackend = 'neutralize' | 'variants' | 'auto';
@@ -25,6 +71,7 @@ export interface ManifestTable {
25
71
  * encrypted column) are enforced at generate time.
26
72
  */
27
73
  readonly serverColumns: readonly string[];
74
+ readonly localProjections?: readonly Omit<IrLocalProjection, 'generation'>[];
28
75
  }
29
76
  export interface ManifestSubscription {
30
77
  readonly name: string;
package/dist/manifest.js CHANGED
@@ -1,48 +1,3 @@
1
- /**
2
- * `syncular.json` manifest: minimal but
3
- * forward-extensible:
4
- *
5
- * ```json
6
- * {
7
- * "manifestVersion": 1,
8
- * "migrations": "./migrations",
9
- * "output": { "ir": "./syncular.ir.json",
10
- * "module": "./syncular.generated.ts",
11
- * "swift": "./Sources/App/Syncular.generated.swift",
12
- * "kotlin": { "path": "./Syncular.generated.kt",
13
- * "package": "dev.example" },
14
- * "dart": "./lib/syncular.generated.dart" },
15
- * "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
16
- * "tables": [{ "name": "tasks", "scopes": ["project:{project_id}"] }],
17
- * "subscriptions": [{ "name": "projectTasks",
18
- * "scopes": { "project_id": "{projectId}" } }],
19
- * "extensions": {}
20
- * }
21
- * ```
22
- *
23
- * - `tables` is ordered: it is the handler-declared bootstrap order (§4.7).
24
- * - `schemaVersions` is the §1.5 version history: strictly increasing
25
- * versions, each naming the last migration it includes (`through`); the
26
- * final entry must cover the final migration.
27
- * - A subscription is a unit template (SPEC §4.1): one literal or
28
- * whole-value `{param}` placeholder per scope variable (partial templates
29
- * are unsupported), no table. The unit covers every table declaring all of
30
- * its variables; a template that covers no table is an error.
31
- * - `output.ir` / `output.module` are the always-emitted TS defaults;
32
- * `output.queryIr` opts into the deterministic analyzed-query document.
33
- * `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native schema
34
- * emitters — a bare string is the output path; an object carries
35
- * language-appropriate options (Kotlin `package`/`objectName`, Swift
36
- * `enumName`; Dart takes `path` only). This is additive within the `output`
37
- * object (the same forward-extension shape `output.ir`/`output.module`
38
- * already use); no `manifestVersion` bump — new *recognized* keys, not
39
- * tolerated-unknown ones. Absent → that language is not generated (TS
40
- * stays the default). `output.rust.queriesPath` opts into Rust named-query
41
- * source over the neutral schema IR consumed by `syncular-client`.
42
- * - Unknown keys are hard errors everywhere (fail loud; growth happens by
43
- * bumping `manifestVersion`), except inside `extensions`, the reserved
44
- * WP-49 passthrough slot copied verbatim into the IR.
45
- */
46
1
  import { TypegenError } from './errors.js';
47
2
  import { isRustKeyword } from './naming.js';
48
3
  export const MANIFEST_FILENAME = 'syncular.json';
@@ -156,10 +111,75 @@ function parseRustOutput(value) {
156
111
  clientCrate,
157
112
  };
158
113
  }
114
+ function parseLocalProjection(value) {
115
+ const spec = asObject(value, 'local projection');
116
+ const name = asString(spec.name, 'local projection name');
117
+ const invalid = (column) => {
118
+ throw new TypegenError(SOURCE, 'invalid local projection declaration', 'client.schema_invalid', { name, ...(column === undefined ? {} : { column }) });
119
+ };
120
+ if (Object.keys(spec).some((key) => !['name', 'columns', 'fts', 'dependencies'].includes(key)))
121
+ invalid();
122
+ if (!Array.isArray(spec.columns) || spec.columns.length === 0)
123
+ return invalid();
124
+ const columns = spec.columns.map((entry) => {
125
+ const column = asObject(entry, 'local projection column');
126
+ const columnName = asString(column.name, 'local projection column name');
127
+ const type = column.declaredType;
128
+ if (Object.keys(column).some((key) => key !== 'name' && key !== 'declaredType'))
129
+ return invalid(columnName);
130
+ if (type !== 'string' &&
131
+ type !== 'integer' &&
132
+ type !== 'real' &&
133
+ type !== 'boolean' &&
134
+ type !== 'json')
135
+ return invalid(columnName);
136
+ return { name: columnName, declaredType: type };
137
+ });
138
+ let fts;
139
+ if (spec.fts !== undefined) {
140
+ const options = asObject(spec.fts, 'local projection FTS5');
141
+ if (Object.keys(options).some((key) => key !== 'tokenize' && key !== 'columns') ||
142
+ !Array.isArray(options.columns) ||
143
+ !options.columns.length)
144
+ return invalid();
145
+ fts = {
146
+ tokenize: asString(options.tokenize, 'local projection tokenizer'),
147
+ columns: options.columns.map((column) => typeof column === 'string' ? column : invalid()),
148
+ };
149
+ }
150
+ let dependencies;
151
+ if (spec.dependencies !== undefined) {
152
+ if (!Array.isArray(spec.dependencies))
153
+ return invalid();
154
+ dependencies = spec.dependencies.map((entry) => {
155
+ const dependency = asObject(entry, 'local projection dependency');
156
+ if (Object.keys(dependency).some((key) => !['table', 'column', 'sourceColumn'].includes(key)))
157
+ invalid();
158
+ return {
159
+ table: asString(dependency.table, 'local projection dependency table'),
160
+ column: asString(dependency.column, 'local projection dependency column'),
161
+ sourceColumn: asString(dependency.sourceColumn, 'local projection source column'),
162
+ };
163
+ });
164
+ }
165
+ return {
166
+ name,
167
+ columns,
168
+ ...(fts ? { fts } : {}),
169
+ ...(dependencies?.length ? { dependencies } : {}),
170
+ };
171
+ }
159
172
  function parseTable(value, index) {
160
173
  const context = `tables[${index}]`;
161
174
  const obj = asObject(value, context);
162
- rejectUnknownKeys(obj, ['name', 'scopes', 'extensions', 'encryptedColumns', 'serverColumns'], context);
175
+ rejectUnknownKeys(obj, [
176
+ 'name',
177
+ 'scopes',
178
+ 'extensions',
179
+ 'encryptedColumns',
180
+ 'serverColumns',
181
+ 'localProjections',
182
+ ], context);
163
183
  const name = asString(obj.name, `${context}.name`);
164
184
  if (!Array.isArray(obj.scopes) || obj.scopes.length === 0) {
165
185
  fail(`table ${name}: scopes must be a non-empty array (§3.1)`);
@@ -192,12 +212,18 @@ function parseTable(value, index) {
192
212
  seen.add(col);
193
213
  }
194
214
  }
215
+ if (obj.localProjections !== undefined &&
216
+ !Array.isArray(obj.localProjections))
217
+ fail('localProjections must be an array');
195
218
  return {
196
219
  name,
197
220
  scopes: obj.scopes.map((spec, i) => parseScopeSpec(spec, `table ${name} scopes[${i}]`)),
198
221
  extensions: parseExtensions(obj.extensions, `table ${name}`),
199
222
  encryptedColumns,
200
223
  serverColumns,
224
+ ...(Array.isArray(obj.localProjections) && obj.localProjections.length
225
+ ? { localProjections: obj.localProjections.map(parseLocalProjection) }
226
+ : {}),
201
227
  };
202
228
  }
203
229
  const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
package/dist/query.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type SyqlToken } from './syql-lexer.js';
2
- import type { IrColumnType, IrDocument } from './ir.js';
2
+ import type { IrColumnType, IrDocument, IrTable } from './ir.js';
3
3
  import { type NamingMode, type NamingTarget } from './naming.js';
4
4
  /** A param type is one of the §2.4 types (the columns params compare to). */
5
5
  export type QueryParamType = IrColumnType;
@@ -293,6 +293,7 @@ export interface SqlRelations {
293
293
  * top-level CTE body, `nested` inside any other subquery. */
294
294
  readonly scopeAt: (offset: number) => string;
295
295
  }
296
+ export declare function ftsRelationNames(table: IrTable): string[];
296
297
  export declare function scanTableRefs(sql: string, ir: IrDocument, lowered?: boolean): TableRef[];
297
298
  /** `lowered` scans emitted SQL, whose FTS mapping reads
298
299
  * ({@link lowerFtsSourceIds}) are internal and not relations of the query. */
package/dist/query.js CHANGED
@@ -408,6 +408,14 @@ export function sqlIdentifier(token) {
408
408
  const value = token.text.slice(1, -1);
409
409
  return quote === '[' ? value : value.split(`${quote}${quote}`).join(quote);
410
410
  }
411
+ export function ftsRelationNames(table) {
412
+ return [
413
+ ...table.ftsIndexes.map((index) => index.name),
414
+ ...(table.localProjections ?? [])
415
+ .filter((projection) => projection.fts)
416
+ .map((projection) => projection.name),
417
+ ];
418
+ }
411
419
  export function scanTableRefs(sql, ir, lowered = false) {
412
420
  return scanRelations(sql, ir, lowered).tables;
413
421
  }
@@ -417,10 +425,13 @@ export function scanRelations(sql, ir, lowered = false) {
417
425
  const { tokens, depths, parents, closes } = sqlStructure(sql);
418
426
  const known = new Map(ir.tables.flatMap((table) => [
419
427
  [table.name.toLowerCase(), table.name],
420
- ...table.ftsIndexes.map((index) => [index.name.toLowerCase(), index.name]),
428
+ ...ftsRelationNames(table).map((name) => [name.toLowerCase(), name]),
429
+ ...(table.localProjections ?? [])
430
+ .filter((projection) => !projection.fts)
431
+ .map(({ name }) => [name.toLowerCase(), name]),
421
432
  ]));
422
433
  const mappings = new Set(lowered
423
- ? ir.tables.flatMap((table) => table.ftsIndexes.map((index) => ftsMappingTable(index.name).toLowerCase()))
434
+ ? ir.tables.flatMap((table) => ftsRelationNames(table).map((name) => ftsMappingTable(name).toLowerCase()))
424
435
  : []);
425
436
  const activeFromDepths = new Set();
426
437
  const clauseEnders = new Set([
@@ -870,69 +881,52 @@ export function splitSelectList(sql) {
870
881
  return items;
871
882
  }
872
883
  export const PLAIN_REF_RE = new RegExp(`^(?:(${IDENT})\\.)?(${IDENT})$`);
873
- function declaredFtsProjection(ir, tableName) {
874
- return ir.tables.some((table) => table.ftsIndexes.some((index) => index.name === tableName));
875
- }
876
884
  const FTS_SOURCE_ID_IR_COLUMN = {
877
885
  name: FTS_SOURCE_ID_COLUMN,
878
886
  type: 'string',
879
887
  nullable: false,
880
888
  };
889
+ function relationColumn(ir, table, name) {
890
+ const source = ir.tables.find((entry) => entry.name === table);
891
+ if (source)
892
+ return source.columns.find((column) => column.name.toLowerCase() === name);
893
+ for (const entry of ir.tables) {
894
+ if (name === FTS_SOURCE_ID_COLUMN &&
895
+ ftsRelationNames(entry).includes(table))
896
+ return FTS_SOURCE_ID_IR_COLUMN;
897
+ const projection = entry.localProjections?.find((spec) => spec.name === table);
898
+ if (projection) {
899
+ if (name === FTS_SOURCE_ID_COLUMN)
900
+ return FTS_SOURCE_ID_IR_COLUMN;
901
+ const column = projection.columns.find((field) => field.name.toLowerCase() === name);
902
+ if (column)
903
+ return {
904
+ name: column.name,
905
+ type: column.declaredType === 'real' ? 'float' : column.declaredType,
906
+ nullable: true,
907
+ };
908
+ }
909
+ }
910
+ return undefined;
911
+ }
881
912
  /** Resolve a SELECT item's expression to an IR column, if it is a plain ref. */
882
913
  function resolveSource(item, refs, ir) {
883
914
  const m = PLAIN_REF_RE.exec(item.expr);
884
915
  if (m === null)
885
916
  return null;
886
917
  const qualifier = m[1];
887
- const columnName = m[2];
888
- const byName = new Map(ir.tables.map((t) => [t.name, t]));
889
- if (qualifier !== undefined) {
890
- const ref = refs.find((candidate) => candidate.alias.toLowerCase() === qualifier.toLowerCase());
891
- if (ref === undefined)
892
- return null;
893
- const table = byName.get(ref.table);
894
- const col = table?.columns.find((candidate) => candidate.name.toLowerCase() === columnName.toLowerCase());
895
- if (col !== undefined) {
896
- return {
897
- table: ref.table,
898
- column: col,
899
- nullableByJoin: ref.nullable,
900
- };
901
- }
902
- if (columnName === FTS_SOURCE_ID_COLUMN &&
903
- declaredFtsProjection(ir, ref.table)) {
904
- return {
905
- table: ref.table,
906
- column: FTS_SOURCE_ID_IR_COLUMN,
907
- nullableByJoin: ref.nullable,
908
- };
909
- }
910
- return null;
911
- }
912
- // Unqualified: search every FROM/JOIN table (SQLite already resolved
913
- // ambiguity; a single-table query is the common case). A USING/NATURAL
914
- // coalesced name can have more than one physical origin, so keep it on the
915
- // honest nullable fallback path instead of guessing one side.
916
- const matches = [];
917
- for (const ref of refs) {
918
- const table = byName.get(ref.table);
919
- const col = table?.columns.find((candidate) => candidate.name.toLowerCase() === columnName.toLowerCase());
920
- if (col !== undefined) {
921
- matches.push({
922
- table: ref.table,
923
- column: col,
924
- nullableByJoin: ref.nullable,
925
- });
926
- }
927
- if (columnName === FTS_SOURCE_ID_COLUMN &&
928
- declaredFtsProjection(ir, ref.table)) {
929
- matches.push({
930
- table: ref.table,
931
- column: FTS_SOURCE_ID_IR_COLUMN,
932
- nullableByJoin: ref.nullable,
933
- });
934
- }
935
- }
918
+ const columnName = m[2].toLowerCase();
919
+ const candidates = qualifier === undefined
920
+ ? refs
921
+ : refs
922
+ .filter((ref) => ref.alias.toLowerCase() === qualifier.toLowerCase())
923
+ .slice(0, 1);
924
+ const matches = candidates.flatMap((ref) => {
925
+ const column = relationColumn(ir, ref.table, columnName);
926
+ return column
927
+ ? [{ table: ref.table, column, nullableByJoin: ref.nullable }]
928
+ : [];
929
+ });
936
930
  return matches.length === 1 ? matches[0] : null;
937
931
  }
938
932
  /** Resolve the query-only protocol columns: `_sync_version` and the
@@ -1153,9 +1147,31 @@ export function synthesizeDdl(ir) {
1153
1147
  const unique = index.unique ? 'UNIQUE ' : '';
1154
1148
  lines.push(`CREATE ${unique}INDEX ${index.name} ON ${table.name} (${index.columns.join(', ')});`);
1155
1149
  }
1156
- for (const index of table.ftsIndexes) {
1150
+ const fullText = table.ftsIndexes.map((index) => ({
1151
+ name: index.name,
1152
+ tokenize: index.tokenize,
1153
+ columns: index.columns,
1154
+ }));
1155
+ for (const projection of table.localProjections ?? []) {
1156
+ const name = `"${projection.name}"`;
1157
+ if (projection.fts) {
1158
+ fullText.push({
1159
+ name: projection.name,
1160
+ tokenize: projection.fts.tokenize,
1161
+ columns: projection.columns.map((column) => `"${column.name}"${projection.fts.columns.includes(column.name) ? '' : ' UNINDEXED'}`),
1162
+ });
1163
+ }
1164
+ else {
1165
+ const columns = projection.columns.map((column) => `"${column.name}" ${SQL_TYPE[column.declaredType === 'real' ? 'float' : column.declaredType]}`);
1166
+ lines.push(`CREATE TABLE ${name} (${FTS_SOURCE_ID_COLUMN} TEXT PRIMARY KEY, ${columns.join(', ')});`);
1167
+ }
1168
+ }
1169
+ for (const index of fullText) {
1157
1170
  const tokenize = index.tokenize.replaceAll("'", "''");
1158
- lines.push(`CREATE VIRTUAL TABLE ${index.name} USING fts5(${FTS_SOURCE_ID_COLUMN} UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`, `CREATE TABLE ${ftsMappingTable(index.name)} (id INTEGER PRIMARY KEY, source_id TEXT NOT NULL UNIQUE);`);
1171
+ const name = table.ftsIndexes.some((builtIn) => builtIn.name === index.name)
1172
+ ? index.name
1173
+ : `"${index.name}"`;
1174
+ lines.push(`CREATE VIRTUAL TABLE ${name} USING fts5(${FTS_SOURCE_ID_COLUMN} UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`, `CREATE TABLE ${ftsMappingTable(index.name)} (id INTEGER PRIMARY KEY, source_id TEXT NOT NULL UNIQUE);`);
1159
1175
  }
1160
1176
  }
1161
1177
  return lines.join('\n');
@@ -1208,7 +1224,7 @@ const SELECT_LIST_BOUNDARIES = new Set([
1208
1224
  * reading the projection; both read the same value.
1209
1225
  */
1210
1226
  export function lowerFtsSourceIds(sql, ir) {
1211
- const ftsNames = new Set(ir.tables.flatMap((table) => table.ftsIndexes.map((index) => index.name)));
1227
+ const ftsNames = new Set(ir.tables.flatMap(ftsRelationNames));
1212
1228
  const relations = scanRelations(sql, ir);
1213
1229
  if (!relations.tables.some((ref) => ftsNames.has(ref.table)))
1214
1230
  return sql;
package/dist/sql.d.ts CHANGED
@@ -36,6 +36,7 @@ export interface ApplyMigrationSqlOptions {
36
36
  * immutable, so the name can only be retired by a forward migration).
37
37
  */
38
38
  export declare function validateFinalSchemaIdentifiers(tables: ReadonlyMap<string, ParsedTable>): void;
39
+ export declare const ALLOWED_FTS_TOKENIZERS: Set<string>;
39
40
  /**
40
41
  * Apply one migration file's SQL to the accumulated table map. Columns
41
42
  * accumulate in declaration order — the §2.4 row-codec positional order.
package/dist/sql.js CHANGED
@@ -407,7 +407,7 @@ function parseCreate(cursor, tables, droppedTables, source, options) {
407
407
  const token = cursor.peek();
408
408
  cursor.fail(`unsupported CREATE statement (only CREATE TABLE, CREATE [UNIQUE] INDEX, and CREATE VIRTUAL TABLE … USING fts5), found ${JSON.stringify(token?.text ?? '')}`);
409
409
  }
410
- const ALLOWED_FTS_TOKENIZERS = new Set([
410
+ export const ALLOWED_FTS_TOKENIZERS = new Set([
411
411
  'unicode61',
412
412
  'unicode61 remove_diacritics 0',
413
413
  'unicode61 remove_diacritics 1',
@@ -1,4 +1,4 @@
1
- import { AGGREGATE_FUNCTIONS, analyzeStatement, inferParamTypeEvidence, PLAIN_REF_RE, scanRelations, scopeProofs, sqlIdentifier, splitSelectList, scanTableRefs, stripCommentsAndStrings, } from './query.js';
1
+ import { AGGREGATE_FUNCTIONS, analyzeStatement, inferParamTypeEvidence, PLAIN_REF_RE, scanRelations, scopeProofs, sqlIdentifier, splitSelectList, scanTableRefs, ftsRelationNames, stripCommentsAndStrings, } from './query.js';
2
2
  import { isSyqlTrivia, lexSyqlSqlSource, SyqlFrontendError, } from './syql-lexer.js';
3
3
  import { syqlRangeEndBind, syqlRangeStartBind } from './syql-semantics.js';
4
4
  const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -563,7 +563,7 @@ class Validator {
563
563
  }
564
564
  #validatePortableProfile(sql, span, refs) {
565
565
  const tokens = significant(lexSyqlSqlSource(span.file, sql));
566
- const declaredFtsTables = new Set(this.#ir.tables.flatMap((table) => table.ftsIndexes.map((index) => index.name)));
566
+ const declaredFtsTables = new Set(this.#ir.tables.flatMap(ftsRelationNames));
567
567
  const queryRefs = refs ?? scanTableRefs(sql, this.#ir);
568
568
  const readsDeclaredFts = queryRefs.some((ref) => declaredFtsTables.has(ref.table));
569
569
  for (let index = 0; index < tokens.length; index += 1) {
@@ -626,6 +626,7 @@ class Validator {
626
626
  const tableNames = this.#ir.tables.flatMap((table) => [
627
627
  table.name,
628
628
  ...table.ftsIndexes.map((index) => index.name),
629
+ ...(table.localProjections ?? []).map((projection) => projection.name),
629
630
  ]);
630
631
  const noTable = new RegExp(`no such table:\\s*(?:main\\.)?(${SQLITE_SUBJECT_RE})`, 'i').exec(sqliteMessage);
631
632
  if (noTable !== null) {
@@ -712,6 +713,12 @@ class Validator {
712
713
  const fts = owner.ftsIndexes.find((candidate) => candidate.name === tableName);
713
714
  if (fts !== undefined)
714
715
  return ['_syncular_source_id', ...fts.columns];
716
+ const projection = owner.localProjections?.find((candidate) => candidate.name === tableName);
717
+ if (projection)
718
+ return [
719
+ '_syncular_source_id',
720
+ ...projection.columns.map((column) => column.name),
721
+ ];
715
722
  }
716
723
  return [];
717
724
  }
@@ -1387,7 +1394,8 @@ class Validator {
1387
1394
  const table = this.#ir.tables.find((item) => item.name === tableName);
1388
1395
  if (table !== undefined)
1389
1396
  return table.primaryKey;
1390
- return this.#ir.tables.some((item) => item.ftsIndexes.some((index) => index.name === tableName))
1397
+ return this.#ir.tables.some((item) => item.ftsIndexes.some((index) => index.name === tableName) ||
1398
+ item.localProjections?.some((projection) => projection.name === tableName))
1391
1399
  ? '_syncular_source_id'
1392
1400
  : undefined;
1393
1401
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/typegen",
3
- "version": "0.99.0",
3
+ "version": "0.101.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.99.0"
59
+ "@syncular/core": "0.101.0"
60
60
  },
61
61
  "devDependencies": {
62
- "@syncular/server": "0.99.0"
62
+ "@syncular/server": "0.101.0"
63
63
  }
64
64
  }
package/src/generate.ts CHANGED
@@ -33,12 +33,14 @@ import {
33
33
  type IrTable,
34
34
  irHash,
35
35
  serializeIr,
36
+ projectionGeneration,
36
37
  tableGeneration,
37
38
  } from './ir';
38
39
  import {
39
40
  MANIFEST_FILENAME,
40
41
  type Manifest,
41
42
  type ManifestScopeSpec,
43
+ type ManifestTable,
42
44
  parseManifest,
43
45
  } from './manifest';
44
46
  import {
@@ -63,6 +65,7 @@ import {
63
65
  } from './query';
64
66
  import { serializeQueryIr } from './query-ir';
65
67
  import {
68
+ ALLOWED_FTS_TOKENIZERS,
66
69
  applyMigrationSql,
67
70
  type ParsedTable,
68
71
  validateFinalSchemaIdentifiers,
@@ -114,13 +117,7 @@ function resolveScope(table: ParsedTable, spec: ManifestScopeSpec): IrScope {
114
117
  }
115
118
 
116
119
  function buildTable(
117
- manifestTable: {
118
- readonly name: string;
119
- readonly scopes: readonly ManifestScopeSpec[];
120
- readonly extensions: Readonly<Record<string, unknown>>;
121
- readonly encryptedColumns: readonly string[];
122
- readonly serverColumns: readonly string[];
123
- },
120
+ manifestTable: ManifestTable,
124
121
  parsed: ParsedTable,
125
122
  ): IrTable {
126
123
  const scopes = manifestTable.scopes.map((spec) => resolveScope(parsed, spec));
@@ -156,6 +153,21 @@ function buildTable(
156
153
  // columns exist, names unique per schema) in declaration order.
157
154
  indexes: parsed.indexes,
158
155
  ftsIndexes: parsed.ftsIndexes,
156
+ ...(manifestTable.localProjections
157
+ ? {
158
+ localProjections: manifestTable.localProjections.map(
159
+ (projection) => ({
160
+ name: projection.name,
161
+ generation: projectionGeneration(parsed.name, projection),
162
+ columns: projection.columns,
163
+ ...(projection.fts ? { fts: projection.fts } : {}),
164
+ ...(projection.dependencies
165
+ ? { dependencies: projection.dependencies }
166
+ : {}),
167
+ }),
168
+ ),
169
+ }
170
+ : {}),
159
171
  extensions: canonicalizeExtensions(manifestTable.extensions) as Record<
160
172
  string,
161
173
  unknown
@@ -449,6 +461,78 @@ export function buildIr(
449
461
  );
450
462
  }
451
463
  }
464
+ const names = new Set(
465
+ tables
466
+ .flatMap((table) => [
467
+ table.name,
468
+ ...table.indexes.map((index) => index.name),
469
+ ...table.ftsIndexes.map((index) => index.name),
470
+ ])
471
+ .map((name) => name.toLowerCase()),
472
+ );
473
+ const projectionIdentifier = (value: string) =>
474
+ /^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(value) &&
475
+ !/^(?:_sync|sync_|sqlite_)/i.test(value);
476
+ for (const table of tables) {
477
+ for (const projection of table.localProjections ?? []) {
478
+ const { name } = projection;
479
+ const lower = name.toLowerCase();
480
+ const invalid = (column?: string): never => {
481
+ throw new TypegenError(
482
+ MANIFEST_FILENAME,
483
+ 'invalid local projection declaration',
484
+ 'client.schema_invalid',
485
+ { name, ...(column === undefined ? {} : { column }) },
486
+ );
487
+ };
488
+ if (
489
+ !projectionIdentifier(name) ||
490
+ names.has(lower) ||
491
+ (projection.fts &&
492
+ (!ALLOWED_FTS_TOKENIZERS.has(projection.fts.tokenize) ||
493
+ !projection.fts.columns.length ||
494
+ new Set(projection.fts.columns).size !==
495
+ projection.fts.columns.length ||
496
+ !projection.fts.columns.every((name) =>
497
+ projection.columns.some(
498
+ (column) =>
499
+ column.name === name && column.declaredType === 'string',
500
+ ),
501
+ )))
502
+ )
503
+ invalid();
504
+ names.add(lower);
505
+ const columns = new Set(projection.fts ? [lower, 'rowid', 'rank'] : []);
506
+ for (const column of projection.columns) {
507
+ const key = column.name.toLowerCase();
508
+ if (!projectionIdentifier(column.name) || columns.has(key))
509
+ invalid(column.name);
510
+ columns.add(key);
511
+ }
512
+ for (const dependency of projection.dependencies ?? []) {
513
+ const dependencyTable = tables.find(
514
+ (item) => item.name === dependency.table,
515
+ );
516
+ const match = dependencyTable?.columns.find(
517
+ (col) => col.name === dependency.column,
518
+ );
519
+ const source = table.columns.find(
520
+ (col) => col.name === dependency.sourceColumn,
521
+ );
522
+ if (
523
+ !match ||
524
+ !source ||
525
+ match.encrypted ||
526
+ source.encrypted ||
527
+ (table.primaryKey !== dependency.sourceColumn &&
528
+ !table.indexes.some(
529
+ (index) => index.columns[0] === dependency.sourceColumn,
530
+ ))
531
+ )
532
+ invalid(dependency.sourceColumn);
533
+ }
534
+ }
535
+ }
452
536
  validateReferences(tables, parsedTables);
453
537
  const subscriptions = manifest.subscriptions.map((sub) =>
454
538
  buildSubscription(sub, tables),
package/src/ir.ts CHANGED
@@ -103,6 +103,24 @@ export interface IrFtsIndex {
103
103
  readonly tokenize: string;
104
104
  }
105
105
 
106
+ export interface IrLocalProjection {
107
+ readonly name: string;
108
+ readonly generation: string;
109
+ readonly columns: readonly {
110
+ readonly name: string;
111
+ readonly declaredType: 'string' | 'integer' | 'real' | 'boolean' | 'json';
112
+ }[];
113
+ readonly fts?: {
114
+ readonly tokenize: string;
115
+ readonly columns: readonly string[];
116
+ };
117
+ readonly dependencies?: readonly {
118
+ readonly table: string;
119
+ readonly column: string;
120
+ readonly sourceColumn: string;
121
+ }[];
122
+ }
123
+
106
124
  export interface IrTable {
107
125
  readonly name: string;
108
126
  /** §7.4.3 table generation: an opaque string that changes whenever the
@@ -122,6 +140,7 @@ export interface IrTable {
122
140
  readonly indexes: readonly IrIndex[];
123
141
  /** Client-local FTS5 projections, in migration declaration order. */
124
142
  readonly ftsIndexes: readonly IrFtsIndex[];
143
+ readonly localProjections?: readonly IrLocalProjection[];
125
144
  /** Reserved per-table hook slot (WP-49); empty object for now. */
126
145
  readonly extensions: Readonly<Record<string, unknown>>;
127
146
  }
@@ -261,6 +280,16 @@ export function tableGeneration(
261
280
  .slice(0, 32);
262
281
  }
263
282
 
283
+ export function projectionGeneration(
284
+ table: string,
285
+ projection: Omit<IrLocalProjection, 'generation'>,
286
+ ): string {
287
+ return createHash('sha256')
288
+ .update(JSON.stringify({ table, projection }), 'utf8')
289
+ .digest('hex')
290
+ .slice(0, 32);
291
+ }
292
+
264
293
  /** Serialize with a fixed key order — byte-deterministic for equal IRs. */
265
294
  export function serializeIr(ir: IrDocument): string {
266
295
  const doc = {
@@ -279,6 +308,9 @@ export function serializeIr(ir: IrDocument): string {
279
308
  column: scope.column,
280
309
  })),
281
310
  ),
311
+ ...(table.localProjections?.length
312
+ ? { localProjections: table.localProjections }
313
+ : {}),
282
314
  extensions: canonicalizeExtensions(table.extensions),
283
315
  })),
284
316
  subscriptions: ir.subscriptions.map((sub) => ({
@@ -303,15 +335,18 @@ export function serializeSchema(ir: IrDocument): string {
303
335
  return JSON.stringify(
304
336
  {
305
337
  version: ir.schemaVersion,
306
- tables: ir.tables.map((table) =>
307
- serializeTableShape(
338
+ tables: ir.tables.map((table) => ({
339
+ ...serializeTableShape(
308
340
  table,
309
341
  table.scopes.map((scope) => ({
310
342
  pattern: scope.pattern,
311
343
  column: scope.column,
312
344
  })),
313
345
  ),
314
- ),
346
+ ...(table.localProjections?.length
347
+ ? { localProjections: table.localProjections }
348
+ : {}),
349
+ })),
315
350
  },
316
351
  null,
317
352
  2,
package/src/manifest.ts CHANGED
@@ -43,6 +43,7 @@
43
43
  * bumping `manifestVersion`), except inside `extensions`, the reserved
44
44
  * WP-49 passthrough slot copied verbatim into the IR.
45
45
  */
46
+ import type { IrLocalProjection } from './ir';
46
47
  import { TypegenError } from './errors';
47
48
  import { isRustKeyword, type NamingMode } from './naming';
48
49
 
@@ -72,6 +73,7 @@ export interface ManifestTable {
72
73
  * encrypted column) are enforced at generate time.
73
74
  */
74
75
  readonly serverColumns: readonly string[];
76
+ readonly localProjections?: readonly Omit<IrLocalProjection, 'generation'>[];
75
77
  }
76
78
 
77
79
  export interface ManifestSubscription {
@@ -291,12 +293,112 @@ function parseRustOutput(value: unknown): RustOutput {
291
293
  };
292
294
  }
293
295
 
296
+ function parseLocalProjection(
297
+ value: unknown,
298
+ ): Omit<IrLocalProjection, 'generation'> {
299
+ const spec = asObject(value, 'local projection');
300
+ const name = asString(spec.name, 'local projection name');
301
+ const invalid = (column?: string): never => {
302
+ throw new TypegenError(
303
+ SOURCE,
304
+ 'invalid local projection declaration',
305
+ 'client.schema_invalid',
306
+ { name, ...(column === undefined ? {} : { column }) },
307
+ );
308
+ };
309
+ if (
310
+ Object.keys(spec).some(
311
+ (key) => !['name', 'columns', 'fts', 'dependencies'].includes(key),
312
+ )
313
+ )
314
+ invalid();
315
+ if (!Array.isArray(spec.columns) || spec.columns.length === 0)
316
+ return invalid();
317
+ const columns = spec.columns.map(
318
+ (entry: unknown): IrLocalProjection['columns'][number] => {
319
+ const column = asObject(entry, 'local projection column');
320
+ const columnName = asString(column.name, 'local projection column name');
321
+ const type = column.declaredType;
322
+ if (
323
+ Object.keys(column).some(
324
+ (key) => key !== 'name' && key !== 'declaredType',
325
+ )
326
+ )
327
+ return invalid(columnName);
328
+ if (
329
+ type !== 'string' &&
330
+ type !== 'integer' &&
331
+ type !== 'real' &&
332
+ type !== 'boolean' &&
333
+ type !== 'json'
334
+ )
335
+ return invalid(columnName);
336
+ return { name: columnName, declaredType: type };
337
+ },
338
+ );
339
+ let fts: IrLocalProjection['fts'];
340
+ if (spec.fts !== undefined) {
341
+ const options = asObject(spec.fts, 'local projection FTS5');
342
+ if (
343
+ Object.keys(options).some(
344
+ (key) => key !== 'tokenize' && key !== 'columns',
345
+ ) ||
346
+ !Array.isArray(options.columns) ||
347
+ !options.columns.length
348
+ )
349
+ return invalid();
350
+ fts = {
351
+ tokenize: asString(options.tokenize, 'local projection tokenizer'),
352
+ columns: options.columns.map((column: unknown) =>
353
+ typeof column === 'string' ? column : invalid(),
354
+ ),
355
+ };
356
+ }
357
+ let dependencies: IrLocalProjection['dependencies'];
358
+ if (spec.dependencies !== undefined) {
359
+ if (!Array.isArray(spec.dependencies)) return invalid();
360
+ dependencies = spec.dependencies.map((entry: unknown) => {
361
+ const dependency = asObject(entry, 'local projection dependency');
362
+ if (
363
+ Object.keys(dependency).some(
364
+ (key) => !['table', 'column', 'sourceColumn'].includes(key),
365
+ )
366
+ )
367
+ invalid();
368
+ return {
369
+ table: asString(dependency.table, 'local projection dependency table'),
370
+ column: asString(
371
+ dependency.column,
372
+ 'local projection dependency column',
373
+ ),
374
+ sourceColumn: asString(
375
+ dependency.sourceColumn,
376
+ 'local projection source column',
377
+ ),
378
+ };
379
+ });
380
+ }
381
+ return {
382
+ name,
383
+ columns,
384
+ ...(fts ? { fts } : {}),
385
+ ...(dependencies?.length ? { dependencies } : {}),
386
+ };
387
+ }
388
+
294
389
  function parseTable(value: unknown, index: number): ManifestTable {
295
390
  const context = `tables[${index}]`;
296
391
  const obj = asObject(value, context);
297
392
  rejectUnknownKeys(
298
393
  obj,
299
- ['name', 'scopes', 'extensions', 'encryptedColumns', 'serverColumns'],
394
+ [
395
+ 'name',
396
+ 'scopes',
397
+ 'extensions',
398
+ 'encryptedColumns',
399
+ 'serverColumns',
400
+ 'localProjections',
401
+ ],
300
402
  context,
301
403
  );
302
404
  const name = asString(obj.name, `${context}.name`);
@@ -339,6 +441,11 @@ function parseTable(value: unknown, index: number): ManifestTable {
339
441
  seen.add(col);
340
442
  }
341
443
  }
444
+ if (
445
+ obj.localProjections !== undefined &&
446
+ !Array.isArray(obj.localProjections)
447
+ )
448
+ fail('localProjections must be an array');
342
449
  return {
343
450
  name,
344
451
  scopes: obj.scopes.map((spec, i) =>
@@ -347,6 +454,9 @@ function parseTable(value: unknown, index: number): ManifestTable {
347
454
  extensions: parseExtensions(obj.extensions, `table ${name}`),
348
455
  encryptedColumns,
349
456
  serverColumns,
457
+ ...(Array.isArray(obj.localProjections) && obj.localProjections.length
458
+ ? { localProjections: obj.localProjections.map(parseLocalProjection) }
459
+ : {}),
350
460
  };
351
461
  }
352
462
 
package/src/query.ts CHANGED
@@ -768,6 +768,15 @@ export interface SqlRelations {
768
768
  readonly scopeAt: (offset: number) => string;
769
769
  }
770
770
 
771
+ export function ftsRelationNames(table: IrTable): string[] {
772
+ return [
773
+ ...table.ftsIndexes.map((index) => index.name),
774
+ ...(table.localProjections ?? [])
775
+ .filter((projection) => projection.fts)
776
+ .map((projection) => projection.name),
777
+ ];
778
+ }
779
+
771
780
  export function scanTableRefs(
772
781
  sql: string,
773
782
  ir: IrDocument,
@@ -787,16 +796,19 @@ export function scanRelations(
787
796
  const known = new Map(
788
797
  ir.tables.flatMap((table) => [
789
798
  [table.name.toLowerCase(), table.name] as const,
790
- ...table.ftsIndexes.map(
791
- (index) => [index.name.toLowerCase(), index.name] as const,
799
+ ...ftsRelationNames(table).map(
800
+ (name) => [name.toLowerCase(), name] as const,
792
801
  ),
802
+ ...(table.localProjections ?? [])
803
+ .filter((projection) => !projection.fts)
804
+ .map(({ name }) => [name.toLowerCase(), name] as const),
793
805
  ]),
794
806
  );
795
807
  const mappings = new Set(
796
808
  lowered
797
809
  ? ir.tables.flatMap((table) =>
798
- table.ftsIndexes.map((index) =>
799
- ftsMappingTable(index.name).toLowerCase(),
810
+ ftsRelationNames(table).map((name) =>
811
+ ftsMappingTable(name).toLowerCase(),
800
812
  ),
801
813
  )
802
814
  : [],
@@ -1349,18 +1361,45 @@ interface ResolvedSource {
1349
1361
  readonly nullableByJoin: boolean;
1350
1362
  }
1351
1363
 
1352
- function declaredFtsProjection(ir: IrDocument, tableName: string): boolean {
1353
- return ir.tables.some((table) =>
1354
- table.ftsIndexes.some((index) => index.name === tableName),
1355
- );
1356
- }
1357
-
1358
1364
  const FTS_SOURCE_ID_IR_COLUMN: IrTable['columns'][number] = {
1359
1365
  name: FTS_SOURCE_ID_COLUMN,
1360
1366
  type: 'string',
1361
1367
  nullable: false,
1362
1368
  };
1363
1369
 
1370
+ function relationColumn(
1371
+ ir: IrDocument,
1372
+ table: string,
1373
+ name: string,
1374
+ ): IrColumn | undefined {
1375
+ const source = ir.tables.find((entry) => entry.name === table);
1376
+ if (source)
1377
+ return source.columns.find((column) => column.name.toLowerCase() === name);
1378
+ for (const entry of ir.tables) {
1379
+ if (
1380
+ name === FTS_SOURCE_ID_COLUMN &&
1381
+ ftsRelationNames(entry).includes(table)
1382
+ )
1383
+ return FTS_SOURCE_ID_IR_COLUMN;
1384
+ const projection = entry.localProjections?.find(
1385
+ (spec) => spec.name === table,
1386
+ );
1387
+ if (projection) {
1388
+ if (name === FTS_SOURCE_ID_COLUMN) return FTS_SOURCE_ID_IR_COLUMN;
1389
+ const column = projection.columns.find(
1390
+ (field) => field.name.toLowerCase() === name,
1391
+ );
1392
+ if (column)
1393
+ return {
1394
+ name: column.name,
1395
+ type: column.declaredType === 'real' ? 'float' : column.declaredType,
1396
+ nullable: true,
1397
+ };
1398
+ }
1399
+ }
1400
+ return undefined;
1401
+ }
1402
+
1364
1403
  /** Resolve a SELECT item's expression to an IR column, if it is a plain ref. */
1365
1404
  function resolveSource(
1366
1405
  item: SelectItem,
@@ -1370,64 +1409,19 @@ function resolveSource(
1370
1409
  const m = PLAIN_REF_RE.exec(item.expr);
1371
1410
  if (m === null) return null;
1372
1411
  const qualifier = m[1];
1373
- const columnName = m[2] as string;
1374
- const byName = new Map(ir.tables.map((t) => [t.name, t] as const));
1375
- if (qualifier !== undefined) {
1376
- const ref = refs.find(
1377
- (candidate) => candidate.alias.toLowerCase() === qualifier.toLowerCase(),
1378
- );
1379
- if (ref === undefined) return null;
1380
- const table = byName.get(ref.table);
1381
- const col = table?.columns.find(
1382
- (candidate) => candidate.name.toLowerCase() === columnName.toLowerCase(),
1383
- );
1384
- if (col !== undefined) {
1385
- return {
1386
- table: ref.table,
1387
- column: col,
1388
- nullableByJoin: ref.nullable,
1389
- };
1390
- }
1391
- if (
1392
- columnName === FTS_SOURCE_ID_COLUMN &&
1393
- declaredFtsProjection(ir, ref.table)
1394
- ) {
1395
- return {
1396
- table: ref.table,
1397
- column: FTS_SOURCE_ID_IR_COLUMN,
1398
- nullableByJoin: ref.nullable,
1399
- };
1400
- }
1401
- return null;
1402
- }
1403
- // Unqualified: search every FROM/JOIN table (SQLite already resolved
1404
- // ambiguity; a single-table query is the common case). A USING/NATURAL
1405
- // coalesced name can have more than one physical origin, so keep it on the
1406
- // honest nullable fallback path instead of guessing one side.
1407
- const matches: ResolvedSource[] = [];
1408
- for (const ref of refs) {
1409
- const table = byName.get(ref.table);
1410
- const col = table?.columns.find(
1411
- (candidate) => candidate.name.toLowerCase() === columnName.toLowerCase(),
1412
- );
1413
- if (col !== undefined) {
1414
- matches.push({
1415
- table: ref.table,
1416
- column: col,
1417
- nullableByJoin: ref.nullable,
1418
- });
1419
- }
1420
- if (
1421
- columnName === FTS_SOURCE_ID_COLUMN &&
1422
- declaredFtsProjection(ir, ref.table)
1423
- ) {
1424
- matches.push({
1425
- table: ref.table,
1426
- column: FTS_SOURCE_ID_IR_COLUMN,
1427
- nullableByJoin: ref.nullable,
1428
- });
1429
- }
1430
- }
1412
+ const columnName = m[2]!.toLowerCase();
1413
+ const candidates =
1414
+ qualifier === undefined
1415
+ ? refs
1416
+ : refs
1417
+ .filter((ref) => ref.alias.toLowerCase() === qualifier.toLowerCase())
1418
+ .slice(0, 1);
1419
+ const matches = candidates.flatMap((ref) => {
1420
+ const column = relationColumn(ir, ref.table, columnName);
1421
+ return column
1422
+ ? [{ table: ref.table, column, nullableByJoin: ref.nullable }]
1423
+ : [];
1424
+ });
1431
1425
  return matches.length === 1 ? (matches[0] as ResolvedSource) : null;
1432
1426
  }
1433
1427
 
@@ -1734,10 +1728,41 @@ export function synthesizeDdl(ir: IrDocument): string {
1734
1728
  `CREATE ${unique}INDEX ${index.name} ON ${table.name} (${index.columns.join(', ')});`,
1735
1729
  );
1736
1730
  }
1737
- for (const index of table.ftsIndexes) {
1731
+ const fullText = table.ftsIndexes.map((index) => ({
1732
+ name: index.name,
1733
+ tokenize: index.tokenize,
1734
+ columns: index.columns,
1735
+ }));
1736
+ for (const projection of table.localProjections ?? []) {
1737
+ const name = `"${projection.name}"`;
1738
+ if (projection.fts) {
1739
+ fullText.push({
1740
+ name: projection.name,
1741
+ tokenize: projection.fts.tokenize,
1742
+ columns: projection.columns.map(
1743
+ (column) =>
1744
+ `"${column.name}"${projection.fts!.columns.includes(column.name) ? '' : ' UNINDEXED'}`,
1745
+ ),
1746
+ });
1747
+ } else {
1748
+ const columns = projection.columns.map(
1749
+ (column) =>
1750
+ `"${column.name}" ${SQL_TYPE[column.declaredType === 'real' ? 'float' : column.declaredType]}`,
1751
+ );
1752
+ lines.push(
1753
+ `CREATE TABLE ${name} (${FTS_SOURCE_ID_COLUMN} TEXT PRIMARY KEY, ${columns.join(', ')});`,
1754
+ );
1755
+ }
1756
+ }
1757
+ for (const index of fullText) {
1738
1758
  const tokenize = index.tokenize.replaceAll("'", "''");
1759
+ const name = table.ftsIndexes.some(
1760
+ (builtIn) => builtIn.name === index.name,
1761
+ )
1762
+ ? index.name
1763
+ : `"${index.name}"`;
1739
1764
  lines.push(
1740
- `CREATE VIRTUAL TABLE ${index.name} USING fts5(${FTS_SOURCE_ID_COLUMN} UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`,
1765
+ `CREATE VIRTUAL TABLE ${name} USING fts5(${FTS_SOURCE_ID_COLUMN} UNINDEXED, ${index.columns.join(', ')}, tokenize='${tokenize}');`,
1741
1766
  `CREATE TABLE ${ftsMappingTable(index.name)} (id INTEGER PRIMARY KEY, source_id TEXT NOT NULL UNIQUE);`,
1742
1767
  );
1743
1768
  }
@@ -1795,9 +1820,7 @@ const SELECT_LIST_BOUNDARIES = new Set([
1795
1820
  * reading the projection; both read the same value.
1796
1821
  */
1797
1822
  export function lowerFtsSourceIds(sql: string, ir: IrDocument): string {
1798
- const ftsNames = new Set(
1799
- ir.tables.flatMap((table) => table.ftsIndexes.map((index) => index.name)),
1800
- );
1823
+ const ftsNames = new Set(ir.tables.flatMap(ftsRelationNames));
1801
1824
  const relations = scanRelations(sql, ir);
1802
1825
  if (!relations.tables.some((ref) => ftsNames.has(ref.table))) return sql;
1803
1826
  const { tokens, depths, closes } = sqlStructure(sql);
package/src/sql.ts CHANGED
@@ -550,7 +550,7 @@ function parseCreate(
550
550
  );
551
551
  }
552
552
 
553
- const ALLOWED_FTS_TOKENIZERS = new Set([
553
+ export const ALLOWED_FTS_TOKENIZERS = new Set([
554
554
  'unicode61',
555
555
  'unicode61 remove_diacritics 0',
556
556
  'unicode61 remove_diacritics 1',
@@ -20,6 +20,7 @@ import {
20
20
  sqlIdentifier,
21
21
  splitSelectList,
22
22
  scanTableRefs,
23
+ ftsRelationNames,
23
24
  stripCommentsAndStrings,
24
25
  type TableRef,
25
26
  } from './query';
@@ -904,9 +905,7 @@ class Validator {
904
905
  ): void {
905
906
  const tokens = significant(lexSyqlSqlSource(span.file, sql));
906
907
  const declaredFtsTables = new Set(
907
- this.#ir.tables.flatMap((table) =>
908
- table.ftsIndexes.map((index) => index.name),
909
- ),
908
+ this.#ir.tables.flatMap(ftsRelationNames),
910
909
  );
911
910
  const queryRefs = refs ?? scanTableRefs(sql, this.#ir);
912
911
  const readsDeclaredFts = queryRefs.some((ref) =>
@@ -1019,6 +1018,7 @@ class Validator {
1019
1018
  const tableNames = this.#ir.tables.flatMap((table) => [
1020
1019
  table.name,
1021
1020
  ...table.ftsIndexes.map((index) => index.name),
1021
+ ...(table.localProjections ?? []).map((projection) => projection.name),
1022
1022
  ]);
1023
1023
  const noTable = new RegExp(
1024
1024
  `no such table:\\s*(?:main\\.)?(${SQLITE_SUBJECT_RE})`,
@@ -1143,6 +1143,14 @@ class Validator {
1143
1143
  (candidate) => candidate.name === tableName,
1144
1144
  );
1145
1145
  if (fts !== undefined) return ['_syncular_source_id', ...fts.columns];
1146
+ const projection = owner.localProjections?.find(
1147
+ (candidate) => candidate.name === tableName,
1148
+ );
1149
+ if (projection)
1150
+ return [
1151
+ '_syncular_source_id',
1152
+ ...projection.columns.map((column) => column.name),
1153
+ ];
1146
1154
  }
1147
1155
  return [];
1148
1156
  }
@@ -2065,8 +2073,12 @@ class Validator {
2065
2073
  #primaryKey(tableName: string): string | undefined {
2066
2074
  const table = this.#ir.tables.find((item) => item.name === tableName);
2067
2075
  if (table !== undefined) return table.primaryKey;
2068
- return this.#ir.tables.some((item) =>
2069
- item.ftsIndexes.some((index) => index.name === tableName),
2076
+ return this.#ir.tables.some(
2077
+ (item) =>
2078
+ item.ftsIndexes.some((index) => index.name === tableName) ||
2079
+ item.localProjections?.some(
2080
+ (projection) => projection.name === tableName,
2081
+ ),
2070
2082
  )
2071
2083
  ? '_syncular_source_id'
2072
2084
  : undefined;