@syncular/typegen 0.15.13 → 0.15.15

package/src/emit-queries.ts

@@ -49,6 +49,29 @@ function propertyKey(name: string): string {
   return IDENTIFIER_RE.test(name) ? name : quote(name);
 }
 
+function emitResultMapper(query: AnalyzedQuery, Row: string): string[] {
+  const booleans = query.columns.filter((column) => column.type === 'boolean');
+  const lines = [
+    `/** Decode one storage-shaped result row for ${quote(query.name)}. */`,
+    `export function ${query.name}MapRow(row: Readonly<Record<string, unknown>>): ${Row} {`,
+  ];
+  if (booleans.length === 0) {
+    lines.push(`  return row as unknown as ${Row};`);
+  } else {
+    lines.push('  return {', '    ...row,');
+    for (const column of booleans) {
+      const access = `row[${quote(column.langName)}]`;
+      const decoded = `decodeQueryBoolean(${access}, ${quote(query.name)}, ${quote(column.langName)})`;
+      lines.push(
+        `    ${propertyKey(column.langName)}: ${column.nullable ? `${access} === null ? null : ${decoded}` : decoded},`,
+      );
+    }
+    lines.push(`  } as unknown as ${Row};`);
+  }
+  lines.push('}');
+  return lines;
+}
+
 /** A named-query param value is the SqlValue subset its type maps to. */
 const PARAM_TS_TYPE: Readonly<Record<IrColumnType, string>> = TS_TYPE;
 const SYQL_PARAM_TS_TYPE: Readonly<Record<IrColumnType, string>> = {
@@ -235,6 +258,7 @@ function emitSyqlQuery(query: AnalyzedQuery, hash: string): string {
     );
   }
   lines.push('}', '');
+  lines.push(...emitResultMapper(query, Row), '');
 
   for (const input of inputs) {
     if (input.kind === 'group') {
@@ -349,7 +373,7 @@ function emitSyqlQuery(query: AnalyzedQuery, hash: string): string {
     `export async function ${query.name}(client: QueryClient${runnerParam}): Promise<${Row}[]> {`,
     `  const selected = ${query.name}Select(${hasParams ? 'params' : ''});`,
     '  const rows = await client.query(selected.sql, selected.bind);',
-    `  return rows as unknown as ${Row}[];`,
+    `  return rows.map((row) => ${query.name}MapRow(row as Readonly<Record<string, unknown>>));`,
     '}',
     '',
   );
@@ -367,6 +391,7 @@ function emitSyqlQuery(query: AnalyzedQuery, hash: string): string {
     `  id: ${quote(`${hash}/${query.name}`)},`,
     `  hasParams: ${hasParams},`,
     `  sql: ${quote(defaultStatement?.positionalSql ?? query.positionalSql)},`,
+    `  mapRow: ${query.name}MapRow,`,
   );
   if (hasParams) {
     lines.push(
@@ -452,6 +477,8 @@ function emitQuery(query: AnalyzedQuery, hash: string): string {
   }
   lines.push('}');
   lines.push('');
+  lines.push(...emitResultMapper(query, Row));
+  lines.push('');
 
   const hasParams = query.params.length > 0;
   if (hasParams) {
@@ -492,7 +519,9 @@ function emitQuery(query: AnalyzedQuery, hash: string): string {
   } else {
     lines.push(`  const rows = await client.query(${sqlConst});`);
   }
-  lines.push(`  return rows as unknown as ${Row}[];`);
+  lines.push(
+    `  return rows.map((row) => ${query.name}MapRow(row as Readonly<Record<string, unknown>>));`,
+  );
   lines.push('}');
   lines.push('');
 
@@ -506,6 +535,7 @@ function emitQuery(query: AnalyzedQuery, hash: string): string {
   lines.push(`  id: ${quote(`${hash}/${query.name}`)},`);
   lines.push(`  hasParams: ${hasParams},`);
   lines.push(`  sql: ${sqlConst},`);
+  lines.push(`  mapRow: ${query.name}MapRow,`);
   lines.push(`  tables: ${query.name}Tables,`);
   const reactiveUsesParams = query.reactive.dependencies.some((dependency) =>
     dependency.scopes.some((scope) => scope.params.length > 0),
@@ -597,6 +627,30 @@ export function emitQueriesModule(
       ].join('\n'),
     );
   }
+  if (
+    queries.some((query) =>
+      query.columns.some((column) => column.type === 'boolean'),
+    )
+  ) {
+    parts.push(
+      [
+        '/** A generated named-query row did not match its analyzed result type. */',
+        'export class QueryResultDecodeError extends TypeError {',
+        "  readonly name = 'QueryResultDecodeError';",
+        '  constructor(readonly query: string, readonly column: string) {',
+        "    super(query + ': result column ' + column + ' is not a SQLite boolean');",
+        '  }',
+        '}',
+        '',
+        '/** Lift a SQLite boolean: preserve booleans, map 0 to false and finite non-zero numbers to true. */',
+        'function decodeQueryBoolean(value: unknown, query: string, column: string): boolean {',
+        "  if (typeof value === 'boolean') return value;",
+        "  if (typeof value === 'number' && Number.isFinite(value)) return value !== 0;",
+        '  throw new QueryResultDecodeError(query, column);',
+        '}',
+      ].join('\n'),
+    );
+  }
   parts.push(
     [
       "/** A bindable SQL param/row value (the wrapper's SqlValue subset). */",
@@ -627,6 +681,7 @@ export function emitQueriesModule(
       '  readonly id: string;',
       '  readonly hasParams: boolean;',
       '  readonly sql: string;',
+      '  readonly mapRow: (row: Readonly<Record<string, unknown>>) => Row;',
       '  readonly tables: readonly string[];',
       '  readonly bind: (params: Params) => readonly QueryValue[];',
       '  readonly sqlFor?: (params: Params) => string;',

package/src/generate.ts

@@ -18,6 +18,7 @@ import { emitKotlinModule } from './emit-kotlin';
 import { emitQueriesModule } from './emit-queries';
 import { emitQueriesDartModule } from './emit-queries-dart';
 import { emitQueriesKotlinModule } from './emit-queries-kotlin';
+import { emitQueriesRustModule } from './emit-queries-rust';
 import { emitQueriesSwiftModule } from './emit-queries-swift';
 import { emitSwiftModule } from './emit-swift';
 import { TypegenError } from './errors';
@@ -555,6 +556,7 @@ export function generate(manifestDir: string): GenerateResult {
   if (manifest.output.swift !== undefined) targets.push('swift');
   if (manifest.output.kotlin !== undefined) targets.push('kotlin');
   if (manifest.output.dart !== undefined) targets.push('dart');
+  if (manifest.output.rust !== undefined) targets.push('rust');
   const naming: QueryNamingOptions = {
     naming: manifest.naming,
     targets,
@@ -586,6 +588,7 @@ export function generate(manifestDir: string): GenerateResult {
     swift,
     kotlin,
     dart,
+    rust,
   } = manifest.output;
 
   // Named queries: analyzed once (SELECT-only, typed against the IR via
@@ -596,7 +599,8 @@ export function generate(manifestDir: string): GenerateResult {
     tsQueriesPath !== undefined ||
     swift?.queriesPath !== undefined ||
     kotlin?.queriesPath !== undefined ||
-    dart?.queriesPath !== undefined;
+    dart?.queriesPath !== undefined ||
+    rust?.queriesPath !== undefined;
   const analyzedQueries = wantsQueries
     ? analyzeQueries(
         ir,
@@ -678,6 +682,17 @@ export function generate(manifestDir: string): GenerateResult {
       });
     }
   }
+  if (rust !== undefined) {
+    outputs.push({
+      path: resolve(manifestDir, rust.queriesPath),
+      content: emitQueriesRustModule(
+        analyzedQueries,
+        queryHash,
+        ir.irVersion,
+        rust.clientCrate,
+      ),
+    });
+  }
   return {
     ir,
     irJson,

package/src/index.ts

@@ -9,6 +9,7 @@ export * from './emit-kotlin';
 export * from './emit-queries';
 export * from './emit-queries-dart';
 export * from './emit-queries-kotlin';
+export * from './emit-queries-rust';
 export * from './emit-queries-swift';
 export * from './emit-swift';
 export * from './errors';

package/src/lsp.ts

@@ -269,6 +269,7 @@ export class SyqlLanguageServer {
       if (manifest.output.swift !== undefined) targets.push('swift');
       if (manifest.output.kotlin !== undefined) targets.push('kotlin');
       if (manifest.output.dart !== undefined) targets.push('dart');
+      if (manifest.output.rust !== undefined) targets.push('rust');
       const lookup: ProjectLookup = {
         kind: 'ready',
         context: {

package/src/manifest.ts

@@ -28,20 +28,21 @@
  *   placeholders (partial templates are unsupported).
  * - `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
+ *   `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native schema
  *   emitters — a bare string is the output path; an object carries
  *   language-appropriate options (Kotlin `package`/`objectName`, Swift
  *   `enumName`; Dart takes `path` only). This is additive within the `output`
  *   object (the same forward-extension shape `output.ir`/`output.module`
  *   already use); no `manifestVersion` bump — new *recognized* keys, not
  *   tolerated-unknown ones. Absent → that language is not generated (TS
- *   stays the default).
+ *   stays the default). `output.rust.queriesPath` opts into Rust named-query
+ *   source over the neutral schema IR consumed by `syncular-client`.
  * - Unknown keys are hard errors everywhere (fail loud; growth happens by
  *   bumping `manifestVersion`), except inside `extensions`, the reserved
  *   WP-49 passthrough slot copied verbatim into the IR.
  */
 import { TypegenError } from './errors';
-import type { NamingMode } from './naming';
+import { isRustKeyword, type NamingMode } from './naming';
 
 /** §7/§8 `.syql` conditional-lowering backend selection. */
 export type ManifestQueryBackend = 'neutralize' | 'variants' | 'auto';
@@ -103,6 +104,14 @@ export interface DartOutput {
   readonly queriesPath?: string;
 }
 
+/** Rust named-query output. Rust consumes neutral schema IR at runtime, so
+ * revision 1 has no separate generated schema source path. */
+export interface RustOutput {
+  readonly queriesPath: string;
+  /** Rust module identifier for the `syncular-client` Cargo dependency. */
+  readonly clientCrate: string;
+}
+
 export interface ManifestOutput {
   readonly ir: string;
   readonly module: string;
@@ -116,6 +125,7 @@ export interface ManifestOutput {
   readonly swift?: SwiftOutput;
   readonly kotlin?: KotlinOutput;
   readonly dart?: DartOutput;
+  readonly rust?: RustOutput;
 }
 
 export interface Manifest {
@@ -254,6 +264,26 @@ function parseDartOutput(value: unknown): DartOutput {
   };
 }
 
+const RUST_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function parseRustOutput(value: unknown): RustOutput {
+  const obj = asObject(value, 'output.rust');
+  rejectUnknownKeys(obj, ['queriesPath', 'clientCrate'], 'output.rust');
+  const clientCrate =
+    obj.clientCrate === undefined
+      ? 'syncular_client'
+      : asString(obj.clientCrate, 'output.rust.clientCrate');
+  if (!RUST_IDENTIFIER_RE.test(clientCrate) || isRustKeyword(clientCrate)) {
+    fail(
+      `output.rust.clientCrate must be one Rust identifier, got ${JSON.stringify(clientCrate)}`,
+    );
+  }
+  return {
+    queriesPath: asString(obj.queriesPath, 'output.rust.queriesPath'),
+    clientCrate,
+  };
+}
+
 function parseTable(value: unknown, index: number): ManifestTable {
   const context = `tables[${index}]`;
   const obj = asObject(value, context);
@@ -407,11 +437,12 @@ export function parseManifest(raw: unknown): Manifest {
   let swift: SwiftOutput | undefined;
   let kotlin: KotlinOutput | undefined;
   let dart: DartOutput | undefined;
+  let rust: RustOutput | undefined;
   if (obj.output !== undefined) {
     const output = asObject(obj.output, 'output');
     rejectUnknownKeys(
       output,
-      ['ir', 'module', 'queryIr', 'queries', 'swift', 'kotlin', 'dart'],
+      ['ir', 'module', 'queryIr', 'queries', 'swift', 'kotlin', 'dart', 'rust'],
       'output',
     );
     if (output.ir !== undefined) ir = asString(output.ir, 'output.ir');
@@ -427,6 +458,7 @@ export function parseManifest(raw: unknown): Manifest {
     if (output.swift !== undefined) swift = parseSwiftOutput(output.swift);
     if (output.kotlin !== undefined) kotlin = parseKotlinOutput(output.kotlin);
     if (output.dart !== undefined) dart = parseDartOutput(output.dart);
+    if (output.rust !== undefined) rust = parseRustOutput(output.rust);
   }
   // Build `output` with only the keys that are set — `exactOptionalPropertyTypes`
   // forbids explicit `undefined` on optional properties.
@@ -438,6 +470,7 @@ export function parseManifest(raw: unknown): Manifest {
     ...(swift !== undefined ? { swift } : {}),
     ...(kotlin !== undefined ? { kotlin } : {}),
     ...(dart !== undefined ? { dart } : {}),
+    ...(rust !== undefined ? { rust } : {}),
   };
   if (!Array.isArray(obj.schemaVersions) || obj.schemaVersions.length === 0) {
     fail('schemaVersions must be a non-empty array (§1.5 version history)');

package/src/naming.ts

@@ -47,7 +47,7 @@ export function snakeToCamel(name: string): string {
 /** The emitter targets whose keyword sets we police. `ts` is included for
  * completeness (its emitters can quote any property, so its list is the
  * small set that breaks generated FUNCTION/const identifiers). */
-export type NamingTarget = 'ts' | 'swift' | 'kotlin' | 'dart';
+export type NamingTarget = 'ts' | 'swift' | 'kotlin' | 'dart' | 'rust';
 
 /** Reserved words that cannot be a generated field/property name on each
  * target. Deliberately the core keyword lists — mechanical and predictable
@@ -211,8 +211,157 @@ const TARGET_KEYWORDS: Readonly<Record<NamingTarget, ReadonlySet<string>>> = {
     'while',
     'with',
   ]),
+  rust: new Set([
+    'abstract',
+    'as',
+    'async',
+    'await',
+    'become',
+    'box',
+    'break',
+    'const',
+    'continue',
+    'crate',
+    'do',
+    'dyn',
+    'else',
+    'enum',
+    'extern',
+    'false',
+    'final',
+    'fn',
+    'for',
+    'gen',
+    'if',
+    'impl',
+    'in',
+    'let',
+    'loop',
+    'macro',
+    'match',
+    'mod',
+    'move',
+    'mut',
+    'override',
+    'priv',
+    'pub',
+    'ref',
+    'return',
+    'self',
+    'static',
+    'struct',
+    'super',
+    'trait',
+    'true',
+    'try',
+    'type',
+    'typeof',
+    'unsafe',
+    'unsized',
+    'use',
+    'virtual',
+    'where',
+    'while',
+    'yield',
+  ]),
 };
 
+export function isRustKeyword(name: string): boolean {
+  return TARGET_KEYWORDS.rust.has(name);
+}
+
+/** Pinned Rust identifier conversion from RFC 0006. */
+export function rustSnakeCase(name: string): string {
+  if (!/^_*[A-Za-z][A-Za-z0-9_]*$/.test(name)) return name;
+  const lead = /^_*/.exec(name)?.[0] ?? '';
+  const withoutLead = name.slice(lead.length);
+  const trail = /_*$/.exec(withoutLead)?.[0] ?? '';
+  const middle = withoutLead.slice(0, withoutLead.length - trail.length);
+  const out: string[] = [];
+  for (let index = 0; index < middle.length; index++) {
+    const char = middle[index] as string;
+    if (char === '_') {
+      if (out.length > 0 && out[out.length - 1] !== '_') out.push('_');
+      continue;
+    }
+    const previous = index > 0 ? middle[index - 1] : undefined;
+    const next = index + 1 < middle.length ? middle[index + 1] : undefined;
+    const uppercase = char >= 'A' && char <= 'Z';
+    const previousLowerOrDigit =
+      previous !== undefined && /[a-z0-9]/.test(previous);
+    const acronymBoundary =
+      uppercase &&
+      previous !== undefined &&
+      /[A-Z]/.test(previous) &&
+      next !== undefined &&
+      /[a-z]/.test(next);
+    if (
+      uppercase &&
+      (previousLowerOrDigit || acronymBoundary) &&
+      out.length > 0 &&
+      out[out.length - 1] !== '_'
+    ) {
+      out.push('_');
+    }
+    out.push(char.toLowerCase());
+  }
+  return lead + out.join('') + trail;
+}
+
+export function rustPascalCase(name: string): string {
+  const snake = rustSnakeCase(name);
+  const lead = /^_*/.exec(snake)?.[0] ?? '';
+  const bare = snake.slice(lead.length).replace(/_*$/, '');
+  const suffix = snake.slice(lead.length + bare.length);
+  return (
+    lead +
+    bare
+      .split('_')
+      .filter((part) => part.length > 0)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join('') +
+    suffix
+  );
+}
+
+export interface RustNameMapping {
+  readonly langName: string;
+  readonly rustName: string;
+}
+
+/** Validate and map QueryIR runtime names to emitted Rust identifiers. */
+export function buildRustNamingMap(
+  langNames: readonly string[],
+  context: string,
+  scope: string,
+): RustNameMapping[] {
+  const seen = new Map<string, string>();
+  return langNames.map((langName) => {
+    const rustName = rustSnakeCase(langName);
+    if (!/^_*[a-z][a-z0-9_]*$/.test(rustName)) {
+      throw new TypegenError(
+        context,
+        `${scope}: ${JSON.stringify(langName)} cannot be emitted as a Rust identifier — alias it in SQL (AS)`,
+      );
+    }
+    if (TARGET_KEYWORDS.rust.has(rustName)) {
+      throw new TypegenError(
+        context,
+        `${scope}: ${JSON.stringify(langName)} maps to ${JSON.stringify(rustName)}, a reserved word on the rust target — alias it in SQL (AS)`,
+      );
+    }
+    const clash = seen.get(rustName);
+    if (clash !== undefined && clash !== langName) {
+      throw new TypegenError(
+        context,
+        `${scope}: ${JSON.stringify(clash)} and ${JSON.stringify(langName)} both map to ${JSON.stringify(rustName)} on the rust target — alias one in SQL (AS)`,
+      );
+    }
+    seen.set(rustName, langName);
+    return { langName, rustName };
+  });
+}
+
 /** One naming-map entry: the SQL-truth name and its language-facing name. */
 export interface NameMapping {
   readonly sqlName: string;
@@ -248,10 +397,11 @@ export function buildNamingMap(
       );
     }
     for (const target of targets) {
-      if (TARGET_KEYWORDS[target].has(langName)) {
+      const targetName = target === 'rust' ? rustSnakeCase(langName) : langName;
+      if (TARGET_KEYWORDS[target].has(targetName)) {
         throw new TypegenError(
           context,
-          `${scope}: ${JSON.stringify(sqlName)} maps to ${JSON.stringify(langName)}, a reserved word on the ${target} target — rename it, alias it in SQL (AS), or set "naming": "preserve" in syncular.json`,
+          `${scope}: ${JSON.stringify(sqlName)} maps to ${JSON.stringify(targetName)}, a reserved word on the ${target} target — rename it, alias it in SQL (AS), or set "naming": "preserve" in syncular.json`,
         );
       }
       if (target === 'dart' && langName.startsWith('_')) {