@syncular/typegen 0.4.1 → 0.5.0

package/src/emit-queries.ts

@@ -71,7 +71,27 @@ function bindExpr(
   return isOptional(param) ? `${access}.${key} ?? null` : `params.${key}`;
 }
 
-function emitQuery(query: AnalyzedQuery): string {
+function reactiveParam(query: AnalyzedQuery, name: string): string {
+  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: AnalyzedQuery,
+  pattern: string,
+  variable: string,
+  param: string,
+): string {
+  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: AnalyzedQuery, hash: string): string {
   const Row = `${pascalCase(query.name)}Row`;
   const Params = `${pascalCase(query.name)}Params`;
   const lines: string[] = [];
@@ -130,7 +150,7 @@ function emitQuery(query: AnalyzedQuery): string {
 
   // Tables dependency set (for useRawSql {tables} / useQuery).
   lines.push(
-    `/** Tables ${quote(query.name)} reads — the exact useRawSql \`{tables}\` set. */`,
+    `/** Tables ${quote(query.name)} reads (compatibility/export surface). */`,
   );
   lines.push(
     `export const ${query.name}Tables = [${query.tables.map(quote).join(', ')}] as const;`,
@@ -253,12 +273,14 @@ function emitQuery(query: AnalyzedQuery): string {
   // 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. */`,
+    `/** 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,`);
@@ -266,6 +288,40 @@ function emitQuery(query: AnalyzedQuery): string {
     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,`);
   } else if (hasParams) {
@@ -273,6 +329,11 @@ function emitQuery(query: AnalyzedQuery): string {
   } 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');
 }
@@ -311,24 +372,44 @@ export function emitQueriesModule(
       '  ): 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/src/emit.ts

@@ -163,6 +163,26 @@ function emitRowInterfaces(table: IrTable, naming: NamingMode): string {
   return lines.join('\n');
 }
 
+function emitTableDescriptor(table: IrTable, naming: NamingMode): string {
+  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: IrSubscription): string {
   const params: string[] = [];
   for (const scope of sub.scopes) {
@@ -218,9 +238,27 @@ export function emitModule(
       `// 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/src/generate.ts

@@ -48,6 +48,7 @@ import {
   type QueryNamingOptions,
   synthesizeDdl,
 } from './query';
+import { serializeQueryIr } from './query-ir';
 import { applyMigrationSql, type ParsedTable } from './sql';
 import { analyzeSyqlFile } from './syql';
 
@@ -463,6 +464,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;
@@ -525,12 +530,19 @@ export function generate(manifestDir: string): GenerateResult {
     { 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 =
+    queryIrPath !== undefined ||
     tsQueriesPath !== undefined ||
     swift?.queriesPath !== undefined ||
     kotlin?.queriesPath !== undefined ||
@@ -549,10 +561,19 @@ export function generate(manifestDir: string): GenerateResult {
     );
   }
 
+  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) {
@@ -565,7 +586,7 @@ export function generate(manifestDir: string): GenerateResult {
         path: resolve(manifestDir, swift.queriesPath),
         content: emitQueriesSwiftModule(
           analyzedQueries,
-          hash,
+          queryHash,
           ir.irVersion,
           swift.enumName,
         ),
@@ -582,7 +603,7 @@ export function generate(manifestDir: string): GenerateResult {
         path: resolve(manifestDir, kotlin.queriesPath),
         content: emitQueriesKotlinModule(
           analyzedQueries,
-          hash,
+          queryHash,
           ir.irVersion,
           kotlin.package,
           kotlin.objectName,
@@ -598,7 +619,11 @@ export function generate(manifestDir: string): GenerateResult {
     if (dart.queriesPath !== undefined) {
       outputs.push({
         path: resolve(manifestDir, dart.queriesPath),
-        content: emitQueriesDartModule(analyzedQueries, hash, ir.irVersion),
+        content: emitQueriesDartModule(
+          analyzedQueries,
+          queryHash,
+          ir.irVersion,
+        ),
       });
     }
   }
@@ -606,6 +631,8 @@ export function generate(manifestDir: string): GenerateResult {
     ir,
     irJson,
     hash,
+    queryIrJson,
+    queryHash,
     module,
     irPath,
     modulePath,

package/src/index.ts

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

package/src/manifest.ts

@@ -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
@@ -105,6 +106,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;
@@ -400,6 +404,7 @@ export function parseManifest(raw: unknown): Manifest {
   }
   let ir = './syncular.ir.json';
   let module = './syncular.generated.ts';
+  let queryIr: string | undefined;
   let queriesOut: string | undefined;
   let swift: SwiftOutput | undefined;
   let kotlin: KotlinOutput | undefined;
@@ -408,13 +413,16 @@ export function parseManifest(raw: unknown): Manifest {
     const output = asObject(obj.output, 'output');
     rejectUnknownKeys(
       output,
-      ['ir', 'module', 'queries', 'swift', 'kotlin', 'dart'],
+      ['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');
     }
@@ -427,6 +435,7 @@ export function parseManifest(raw: unknown): Manifest {
   const outputSpec: ManifestOutput = {
     ir,
     module,
+    ...(queryIr !== undefined ? { queryIr } : {}),
     ...(queriesOut !== undefined ? { queries: queriesOut } : {}),
     ...(swift !== undefined ? { swift } : {}),
     ...(kotlin !== undefined ? { kotlin } : {}),

package/src/query-ir.ts

@@ -14,7 +14,7 @@ import type { AnalyzedQuery } from './query';
 /** Serialize analyzed queries as the deterministic QueryIR JSON document. */
 export function serializeQueryIr(queries: readonly AnalyzedQuery[]): string {
   const doc = {
-    queryIrVersion: 1,
+    queryIrVersion: 2,
     queries: queries.map((query) => ({
       name: query.name,
       file: query.file,
@@ -37,8 +37,31 @@ export function serializeQueryIr(queries: readonly AnalyzedQuery[]): string {
         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
         ? {