@syncular/typegen 0.4.1 → 0.5.1

package/README.md

@@ -72,6 +72,7 @@ schema guide and suggests `syncular init`.
 | `queryBackend` | no (default `"neutralize"`) | `.syql` conditional lowering: `"neutralize"` (one guarded statement), `"variants"` (enumerate per provided-combination whenever eligible), `"auto"` (enumerate at ≤ 2 optional groups). The per-query `variants` knob always forces. |
 | `output.ir` | no (default `./syncular.ir.json`) | IR output path, relative to the manifest. |
 | `output.module` | no (default `./syncular.generated.ts`) | Generated TS module path, relative to the manifest. |
+| `output.queryIr` | no | Deterministic analyzed QueryIR JSON. Its hash keys generated reactive query descriptors, so SQL-only changes invalidate caches. |
 | `output.queries` | no | Opt-in TS named-queries output path (see §6). A sibling `.ts` file. |
 | `output.swift` | no | Opt-in Swift emitter (see §5). A path string, or `{ "path", "enumName", "queriesPath" }` (default `enumName` `SyncularSchema`; `queriesPath` opts into §6 Swift named queries). |
 | `output.kotlin` | no | Opt-in Kotlin emitter (see §5). A path string, or `{ "path", "package", "objectName", "queriesPath" }` (defaults `syncular.generated` / `SyncularSchema`). |
@@ -440,17 +441,45 @@ so the emitted SQL rewrites `:name` → `?` (repeats included) and each runner
 reorders the named params object into the positional array. Comments are
 stripped and whitespace collapsed to a clean one-line string.
 
-**The tables dependency set** (for React's exact invalidation). Each query
-emits a `tables` set — the FROM/JOIN tables it reads, resolved against the IR
-and *validated by the same SQLite `prepare()`* (an unknown table would have
-thrown). This feeds `useRawSql`'s `{tables}` option so a named query
-re-runs exactly when a depended-on table invalidates. **Boundary**:
+**Reactive metadata.** Each query emits a QueryIR-derived cache id, the
+FROM/JOIN table set, table-associated scope dependencies, provable window
+coverage, and a safe row identity when the primary key is projected by an
+unambiguous single-table query. React uses these facts to share one query per
+revision, route exact change batches, claim window coverage, and retain
+unchanged row objects. The cache id is derived from the query IR rather than
+the schema IR, so a SQL-only change cannot reuse old state. **Boundary**:
 `bun:sqlite` exposes no authorizer and no statement table-list, and EXPLAIN
 opcodes are fragile — so the set is derived by scanning every `FROM`/`JOIN`
 identifier and keeping those that name an IR table. This captures subquery /
 `WHERE EXISTS (…)` tables (they still appear under `FROM`/`JOIN`), and the
 prepare() still guarantees the SQL itself is correct.
 
+Inference is deliberately conservative around `OR`, joins, grouping, and
+computed identity. A `.syql` query can state the missing fact explicitly:
+
+```syql
+query compareLists(left, right)
+  depends tasks on project_id = left | right
+  window tasks by project_id = left | right
+  key by id
+{
+  select id, title from tasks
+  where project_id = :left or project_id = :right
+}
+```
+
+The declaration grammar is:
+
+- `depends <table> on <scope> = <param> | <param>`;
+- `window <table> by <scope> = <param> | <param>` with optional
+  `fixed <other_scope> = <param>, ...` for every other scope on that table;
+- `key by <result-column> | <result-column>`.
+
+These escape hatches are checked against the prepared query, schema, inferred
+param types, and result projection. They reject unread tables, unknown scopes
+or params, optional/incompatible coverage params, incomplete fixed scopes,
+duplicate declarations, and unprojected key fields.
+
 **Emitted shape, per language** (one query, five outputs — abbreviated):
 
 | | Output |
@@ -467,11 +496,11 @@ the schema structs. `--check` gates every queries file byte-exactly, like the
 schema files; each carries the DO-NOT-EDIT header + IR hash.
 
 **React helper.** `@syncular/react` exports `useQuery(query, params?)`,
-which takes the TS `NamedQuery` descriptor and reuses `useRawSql`'s
-invalidation machinery with the descriptor's exact `tables` set:
+which takes the TS `NamedQuery` descriptor and observes the client-scoped
+revisioned store:
 
 ```ts
 import { listTodosQuery } from './syncular.queries';
-const { rows } = useQuery(listTodosQuery, { listId });
-//      ^ ListTodosRow[] — typed by the query's own projection
+const todos = useQuery(listTodosQuery, { listId });
+// todos.rows: ListTodosRow[]; todos.phase: loading | partial | ready | error
 ```

package/dist/emit-queries.js

@@ -33,7 +33,22 @@ function bindExpr(query, param, access) {
     const key = propertyKey(param.langName);
     return isOptional(param) ? `${access}.${key} ?? null` : `params.${key}`;
 }
-function emitQuery(query) {
+function reactiveParam(query, name) {
+    const param = query.params.find((candidate) => candidate.name === name);
+    if (param === undefined)
+        throw new Error(`unknown reactive param ${name}`);
+    return `String(params.${propertyKey(param.langName)})`;
+}
+function scopeKeyExpression(query, pattern, variable, param) {
+    const marker = `{${variable}}`;
+    const index = pattern.indexOf(marker);
+    if (index < 0)
+        throw new Error(`scope pattern ${pattern} lacks ${marker}`);
+    const prefix = pattern.slice(0, index);
+    const suffix = pattern.slice(index + marker.length);
+    return `${quote(prefix)} + ${reactiveParam(query, param)} + ${quote(suffix)}`;
+}
+function emitQuery(query, hash) {
     const Row = `${pascalCase(query.name)}Row`;
     const Params = `${pascalCase(query.name)}Params`;
     const lines = [];
@@ -75,7 +90,7 @@ function emitQuery(query) {
         lines.push('');
     }
     // Tables dependency set (for useRawSql {tables} / useQuery).
-    lines.push(`/** Tables ${quote(query.name)} reads — the exact useRawSql \`{tables}\` set. */`);
+    lines.push(`/** Tables ${quote(query.name)} reads (compatibility/export surface). */`);
     lines.push(`export const ${query.name}Tables = [${query.tables.map(quote).join(', ')}] as const;`);
     lines.push('');
     // SQL constants: the static default statement, plus (orderBy knob) the
@@ -166,9 +181,11 @@ function emitQuery(query) {
     // the baked allowlist, or variant-selected), the exact table dependency
     // set, and a `bind(params)` → positional array (always paired with the
     // sqlFor selection). Typed by the query's own Row/Params.
-    lines.push(`/** Descriptor for \`useQuery(${query.name}Query${hasParams ? ', params' : ''})\` — sql + tables + row type. */`);
+    lines.push(`/** Revisioned reactive descriptor for \`useQuery(${query.name}Query${hasParams ? ', params' : ''})\`. */`);
     const paramsTypeArg = hasParams ? Params : 'undefined';
     lines.push(`export const ${query.name}Query: NamedQuery<${Row}, ${paramsTypeArg}> = {`);
+    lines.push(`  id: ${quote(`${hash}/${query.name}`)},`);
+    lines.push(`  hasParams: ${hasParams},`);
     lines.push(`  sql: ${sqlConst},`);
     if (query.variants !== undefined) {
         lines.push(`  sqlFor: (params: ${Params}) => ${selectFn}(params).sql,`);
@@ -177,6 +194,24 @@ function emitQuery(query) {
         lines.push(`  sqlFor: (params: ${Params}) => ${composeFn}(params),`);
     }
     lines.push(`  tables: ${query.name}Tables,`);
+    const reactiveUsesParams = query.reactive.dependencies.some((dependency) => dependency.scopes.some((scope) => scope.params.length > 0));
+    lines.push(`  dependencies: (${reactiveUsesParams ? 'params' : ''}) => [`);
+    for (const dependency of query.reactive.dependencies) {
+        const keys = dependency.scopes.flatMap((scope) => scope.params.map((param) => scopeKeyExpression(query, scope.pattern, scope.variable, param)));
+        lines.push(`    { table: ${quote(dependency.table)}${keys.length > 0 ? `, scopeKeys: [${keys.join(', ')}]` : ''} },`);
+    }
+    lines.push('  ],');
+    const coverageUsesParams = query.reactive.coverage.some((coverage) => coverage.units.length > 0 ||
+        coverage.fixedScopes.some((scope) => scope.params.length > 0));
+    lines.push(`  coverage: (${coverageUsesParams ? 'params' : ''}) => [`);
+    for (const coverage of query.reactive.coverage) {
+        const fixed = coverage.fixedScopes
+            .map((scope) => `${propertyKey(scope.variable)}: [${scope.params.map((param) => reactiveParam(query, param)).join(', ')}]`)
+            .join(', ');
+        const fixedPart = fixed.length > 0 ? `, fixedScopes: { ${fixed} }` : '';
+        lines.push(`    { base: { table: ${quote(coverage.table)}, variable: ${quote(coverage.variable)}${fixedPart} }, units: [${coverage.units.map((param) => reactiveParam(query, param)).join(', ')}] },`);
+    }
+    lines.push('  ],');
     if (query.variants !== undefined) {
         lines.push(`  bind: (params: ${Params}) => ${selectFn}(params).bind,`);
     }
@@ -186,6 +221,9 @@ function emitQuery(query) {
     else {
         lines.push('  bind: () => [],');
     }
+    if (query.reactive.rowKey !== undefined) {
+        lines.push(`  rowKey: (row) => [${query.reactive.rowKey.map((key) => `row.${propertyKey(key)}`).join(', ')}],`);
+    }
     lines.push('};');
     return lines.join('\n');
 }
@@ -216,23 +254,43 @@ export function emitQueriesModule(queries, hash, irVersion) {
         '  ): unknown[] | Promise<unknown[]>;',
         '}',
         '',
-        '/** A named-query descriptor — sql + its exact table dependency set + a',
+        '/** A named-query descriptor — checked SQL plus revisioned reactive metadata and a',
         ' *  `bind(params)` → positional args. Consumed by',
         " *  `@syncular/react`'s `useQuery`. `Row` is the projection row",
         ' *  type; `Params` is `undefined` for a param-less query. `sqlFor`',
         ' *  (present only with an orderBy knob) composes the statement from a',
         ' *  generate-time-checked column allowlist. */',
         'export interface NamedQuery<Row, Params = undefined> {',
+        '  readonly id: string;',
+        '  readonly hasParams: boolean;',
         '  readonly sql: string;',
         '  readonly tables: readonly string[];',
         '  readonly bind: (params: Params) => readonly QueryValue[];',
         '  readonly sqlFor?: (params: Params) => string;',
+        '  readonly dependencies: (params: Params) => readonly QueryDependency[];',
+        '  readonly coverage: (params: Params) => readonly WindowCoverage[];',
+        '  readonly rowKey?: (row: Row) => readonly QueryValue[];',
         '  /** Phantom — carries the Row type for `useQuery` inference. */',
         '  readonly __row?: Row;',
         '}',
+        '',
+        'export interface QueryDependency {',
+        '  readonly table: string;',
+        '  readonly scopeKeys?: readonly string[];',
+        '}',
+        '',
+        'export interface WindowCoverage {',
+        '  readonly base: {',
+        '    readonly table: string;',
+        '    readonly variable: string;',
+        '    readonly fixedScopes?: Readonly<Record<string, readonly string[]>>;',
+        '    readonly params?: string;',
+        '  };',
+        '  readonly units: readonly string[];',
+        '}',
     ].join('\n'));
     for (const query of queries) {
-        parts.push(emitQuery(query));
+        parts.push(emitQuery(query, hash));
     }
     return `${parts.join('\n\n')}\n`;
 }

package/dist/emit.js

@@ -122,6 +122,22 @@ function emitRowInterfaces(table, naming) {
     lines.push('}');
     return lines.join('\n');
 }
+function emitTableDescriptor(table, naming) {
+    const type = pascalCase(table.name);
+    const primary = table.columns.find((column) => column.name === table.primaryKey);
+    if (primary === undefined)
+        throw new Error(`table ${table.name} lacks its primary key`);
+    const field = naming === 'camel' ? snakeToCamel(table.primaryKey) : table.primaryKey;
+    const constant = `${naming === 'camel' ? snakeToCamel(table.name) : table.name}Table`;
+    return [
+        `/** Typed mutation/resource descriptor for ${quote(table.name)}. */`,
+        `export const ${constant}: SyncTable<${type}Row, ${type}Insert, ${type}Update, ${appTsType(primary)}> = {`,
+        `  name: ${quote(table.name)},`,
+        `  primaryKey: ${quote(field)},`,
+        `  physicalPrimaryKey: ${quote(table.primaryKey)},`,
+        '};',
+    ].join('\n');
+}
 function emitSubscription(sub) {
     const params = [];
     for (const scope of sub.scopes) {
@@ -166,9 +182,25 @@ export function emitModule(ir, hash, naming = 'camel') {
         `// irVersion: ${ir.irVersion}`,
         `// irHash: ${hash}`,
     ].join('\n'));
+    parts.push([
+        '/** Structural descriptor consumed by renderer bindings; phantom type',
+        ' * fields make row/insert/update/id inference available without imports. */',
+        'export interface SyncTable<Row, Insert, Update, Id> {',
+        '  readonly name: string;',
+        '  /** Language-facing key used in generated row and mutation types. */',
+        '  readonly primaryKey: keyof Row & string;',
+        '  /** Physical SQLite/wire primary-key column. */',
+        '  readonly physicalPrimaryKey: string;',
+        '  readonly __row?: Row;',
+        '  readonly __insert?: Insert;',
+        '  readonly __update?: Update;',
+        '  readonly __id?: Id;',
+        '}',
+    ].join('\n'));
     parts.push(emitSchema(ir));
     for (const table of ir.tables) {
         parts.push(emitRowInterfaces(table, naming));
+        parts.push(emitTableDescriptor(table, naming));
     }
     for (const sub of ir.subscriptions) {
         parts.push(emitSubscription(sub));

package/dist/generate.d.ts

@@ -48,6 +48,10 @@ export interface GenerateResult {
     /** Serialized IR document (the exact bytes of the `.ir.json` output). */
     readonly irJson: string;
     readonly hash: string;
+    /** Serialized QueryIR and its content hash. Query descriptors use this hash
+     * so a SQL-only edit cannot reuse a stale reactive cache entry. */
+    readonly queryIrJson: string;
+    readonly queryHash: string;
     /** Generated TS module source (the exact bytes of the `.ts` output). */
     readonly module: string;
     readonly irPath: string;

package/dist/generate.js

@@ -18,6 +18,7 @@ import { canonicalizeExtensions, IR_VERSION, irHash, serializeIr, } from './ir.j
 import { MANIFEST_FILENAME, parseManifest, } from './manifest.js';
 import { buildNamingMap } from './naming.js';
 import { analyzeQueryFile, synthesizeDdl, } from './query.js';
+import { serializeQueryIr } from './query-ir.js';
 import { applyMigrationSql } from './sql.js';
 import { analyzeSyqlFile } from './syql.js';
 /** Same grammar the server compiles (§3.1): `prefix:{variable}`. */
@@ -337,11 +338,12 @@ export function generate(manifestDir) {
         { path: modulePath, content: module },
     ];
     // Opt-in native emitters — each present only when the manifest requests it.
-    const { queries: tsQueriesPath, swift, kotlin, dart } = manifest.output;
+    const { queryIr: queryIrPath, queries: tsQueriesPath, swift, kotlin, dart, } = manifest.output;
     // Named queries: analyzed once (SELECT-only, typed against the IR via
     // SQLite), then emitted per-language into its OWN file so schema-only
     // consumers never churn. Only analyzed when SOME query output is requested.
-    const wantsQueries = tsQueriesPath !== undefined ||
+    const wantsQueries = queryIrPath !== undefined ||
+        tsQueriesPath !== undefined ||
         swift?.queriesPath !== undefined ||
         kotlin?.queriesPath !== undefined ||
         dart?.queriesPath !== undefined;
@@ -351,10 +353,18 @@ export function generate(manifestDir) {
     if (wantsQueries && analyzedQueries.length === 0) {
         throw new TypegenError(resolve(manifestDir, manifest.queries), `an output requests named queries but no .sql files were found in ${manifest.queries} — add a query file or drop the queries output`);
     }
+    const queryIrJson = serializeQueryIr(analyzedQueries);
+    const queryHash = irHash(queryIrJson);
+    if (queryIrPath !== undefined) {
+        outputs.push({
+            path: resolve(manifestDir, queryIrPath),
+            content: queryIrJson,
+        });
+    }
     if (tsQueriesPath !== undefined) {
         outputs.push({
             path: resolve(manifestDir, tsQueriesPath),
-            content: emitQueriesModule(analyzedQueries, hash, ir.irVersion),
+            content: emitQueriesModule(analyzedQueries, queryHash, ir.irVersion),
         });
     }
     if (swift !== undefined) {
@@ -365,7 +375,7 @@ export function generate(manifestDir) {
         if (swift.queriesPath !== undefined) {
             outputs.push({
                 path: resolve(manifestDir, swift.queriesPath),
-                content: emitQueriesSwiftModule(analyzedQueries, hash, ir.irVersion, swift.enumName),
+                content: emitQueriesSwiftModule(analyzedQueries, queryHash, ir.irVersion, swift.enumName),
             });
         }
     }
@@ -377,7 +387,7 @@ export function generate(manifestDir) {
         if (kotlin.queriesPath !== undefined) {
             outputs.push({
                 path: resolve(manifestDir, kotlin.queriesPath),
-                content: emitQueriesKotlinModule(analyzedQueries, hash, ir.irVersion, kotlin.package, kotlin.objectName),
+                content: emitQueriesKotlinModule(analyzedQueries, queryHash, ir.irVersion, kotlin.package, kotlin.objectName),
             });
         }
     }
@@ -389,7 +399,7 @@ export function generate(manifestDir) {
         if (dart.queriesPath !== undefined) {
             outputs.push({
                 path: resolve(manifestDir, dart.queriesPath),
-                content: emitQueriesDartModule(analyzedQueries, hash, ir.irVersion),
+                content: emitQueriesDartModule(analyzedQueries, queryHash, ir.irVersion),
             });
         }
     }
@@ -397,6 +407,8 @@ export function generate(manifestDir) {
         ir,
         irJson,
         hash,
+        queryIrJson,
+        queryHash,
         module,
         irPath,
         modulePath,

package/dist/index.d.ts

@@ -23,3 +23,8 @@ export * from './query.js';
 export * from './query-ir.js';
 export * from './sql.js';
 export * from './syql.js';
+export * from './syql-ast.js';
+export * from './syql-lexer.js';
+export * from './syql-modules.js';
+export * from './syql-parser.js';
+export * from './syql-template-parser.js';

package/dist/index.js

@@ -23,3 +23,8 @@ export * from './query.js';
 export * from './query-ir.js';
 export * from './sql.js';
 export * from './syql.js';
+export * from './syql-ast.js';
+export * from './syql-lexer.js';
+export * from './syql-modules.js';
+export * from './syql-parser.js';
+export * from './syql-template-parser.js';

package/dist/manifest.d.ts

@@ -56,6 +56,9 @@ export interface DartOutput {
 export interface ManifestOutput {
     readonly ir: string;
     readonly module: string;
+    /** Opt-in deterministic QueryIR JSON. This is also the source of the
+     * generated query-descriptor hash, so SQL-only changes rotate cache IDs. */
+    readonly queryIr?: string;
     /** Opt-in TS named-queries output path (a sibling `.ts` file). Undefined →
      * named queries are not generated for TS. */
     readonly queries?: string;

package/dist/manifest.js

@@ -26,7 +26,8 @@
  *   final entry must cover the final migration.
  * - Subscription scope values are literals or whole-value `{param}`
  *   placeholders (partial templates are unsupported).
- * - `output.ir` / `output.module` are the always-emitted TS defaults.
+ * - `output.ir` / `output.module` are the always-emitted TS defaults;
+ *   `output.queryIr` opts into the deterministic analyzed-query document.
  *   `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native
  *   emitters — a bare string is the output path; an object carries
  *   language-appropriate options (Kotlin `package`/`objectName`, Swift
@@ -242,18 +243,22 @@ export function parseManifest(raw) {
     }
     let ir = './syncular.ir.json';
     let module = './syncular.generated.ts';
+    let queryIr;
     let queriesOut;
     let swift;
     let kotlin;
     let dart;
     if (obj.output !== undefined) {
         const output = asObject(obj.output, 'output');
-        rejectUnknownKeys(output, ['ir', 'module', 'queries', 'swift', 'kotlin', 'dart'], 'output');
+        rejectUnknownKeys(output, ['ir', 'module', 'queryIr', 'queries', 'swift', 'kotlin', 'dart'], 'output');
         if (output.ir !== undefined)
             ir = asString(output.ir, 'output.ir');
         if (output.module !== undefined) {
             module = asString(output.module, 'output.module');
         }
+        if (output.queryIr !== undefined) {
+            queryIr = asString(output.queryIr, 'output.queryIr');
+        }
         if (output.queries !== undefined) {
             queriesOut = asString(output.queries, 'output.queries');
         }
@@ -269,6 +274,7 @@ export function parseManifest(raw) {
     const outputSpec = {
         ir,
         module,
+        ...(queryIr !== undefined ? { queryIr } : {}),
         ...(queriesOut !== undefined ? { queries: queriesOut } : {}),
         ...(swift !== undefined ? { swift } : {}),
         ...(kotlin !== undefined ? { kotlin } : {}),

package/dist/query-ir.js

@@ -1,7 +1,7 @@
 /** Serialize analyzed queries as the deterministic QueryIR JSON document. */
 export function serializeQueryIr(queries) {
     const doc = {
-        queryIrVersion: 1,
+        queryIrVersion: 2,
         queries: queries.map((query) => ({
             name: query.name,
             file: query.file,
@@ -24,8 +24,31 @@ export function serializeQueryIr(queries) {
                 type: column.type,
                 nullable: column.nullable,
                 fidelity: column.fidelity,
+                ...(column.origin !== undefined ? { origin: column.origin } : {}),
             })),
             tables: query.tables,
+            reactive: {
+                dependencies: query.reactive.dependencies.map((dependency) => ({
+                    table: dependency.table,
+                    scopes: dependency.scopes.map((scope) => ({
+                        variable: scope.variable,
+                        pattern: scope.pattern,
+                        params: scope.params,
+                    })),
+                })),
+                coverage: query.reactive.coverage.map((coverage) => ({
+                    table: coverage.table,
+                    variable: coverage.variable,
+                    units: coverage.units,
+                    fixedScopes: coverage.fixedScopes.map((scope) => ({
+                        variable: scope.variable,
+                        params: scope.params,
+                    })),
+                })),
+                ...(query.reactive.rowKey !== undefined
+                    ? { rowKey: query.reactive.rowKey }
+                    : {}),
+            },
             // §6 knob metadata — emitted only when declared.
             ...(query.orderBy !== undefined
                 ? {

package/dist/query.d.ts

@@ -47,6 +47,35 @@ export interface QueryColumn {
     /** `exact` = resolved to an IR column (plain ref); `fallback` = a computed
      * expression typed by the documented honest fallback. */
     readonly fidelity: 'exact' | 'fallback';
+    /** Proven physical origin for reactive row identity and diagnostics. */
+    readonly origin?: {
+        readonly table: string;
+        readonly column: string;
+    };
+}
+export interface QueryScopeBinding {
+    readonly table: string;
+    readonly variable: string;
+    readonly pattern: string;
+    readonly params: readonly string[];
+}
+export interface QueryCoverageBinding {
+    readonly table: string;
+    readonly variable: string;
+    readonly units: readonly string[];
+    readonly fixedScopes: readonly {
+        readonly variable: string;
+        readonly params: readonly string[];
+    }[];
+}
+export interface QueryReactiveMetadata {
+    readonly dependencies: readonly {
+        readonly table: string;
+        readonly scopes: readonly QueryScopeBinding[];
+    }[];
+    readonly coverage: readonly QueryCoverageBinding[];
+    /** Language-facing projection fields forming a proven unique row key. */
+    readonly rowKey?: readonly string[];
 }
 /** §7/§8 backend selection: neutralization (default), always-variants, or
  * the small-N heuristic (`auto`: enumerate at ≤ 2 optional groups). */
@@ -81,6 +110,7 @@ export interface AnalyzedQuery {
     readonly columns: readonly QueryColumn[];
     /** IR tables this query reads (the useRawSql `{tables}` set), sorted. */
     readonly tables: readonly string[];
+    readonly reactive: QueryReactiveMetadata;
     /** §6 orderBy knob (`.syql` tier). When present, `sql`/`positionalSql`
      * carry the DEFAULT order-by tail and `positionalSqlBase` is the static
      * prefix emitters compose the selected column onto. */