@syncular/typegen 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -31,7 +31,7 @@
   "exports": {
     ".": {
       "bun": "./src/index.ts",
-      "browser": "./src/index.ts",
+      "browser": "./dist/index.js",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -48,7 +48,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/core": "0.2.0",
-    "@syncular/server": "0.2.0"
+    "@syncular/core": "0.2.1",
+    "@syncular/server": "0.2.1"
   }
 }

package/src/cli.ts

@@ -15,11 +15,13 @@
  * The generate CONTRACT (inputs, outputs, byte-exact `--check`) is unchanged;
  * this file only adds `init`, `--watch`, and friendlier errors.
  */
-import { watch } from 'node:fs';
+import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { checkOutputs, generate, writeOutputs } from './generate';
+import { formatSyql } from './fmt';
+import { checkOutputs, generate, loadQueries, writeOutputs } from './generate';
 import { InitError, initProject } from './init';
-import { MANIFEST_FILENAME } from './manifest';
+import { runLspStdio } from './lsp';
+import { MANIFEST_FILENAME, parseManifest } from './manifest';
 
 const DOCS_HINT =
   'See the schema guide: https://github.com/bkniffler/syncular (guide-schema), ' +
@@ -29,12 +31,22 @@ const USAGE = `usage: syncular <command> [options]
 
 commands:
   generate   build the IR + typed module from syncular.json + migrations/
+  fmt        format .syql query files canonically (one style, no options)
+  lsp        run the .syql language server over stdio (editor tooling)
   init       scaffold a starter syncular.json + migrations/0001_initial
 
 generate options:
   --manifest-dir <dir>   directory holding syncular.json (default: .)
   --check                fail unless generated files are byte-exactly fresh
   --watch                regenerate on file change (Ctrl-C to stop)
+  --print <name>         print one named query's lowered, checked SQL
+                         (params, tables, knob variants) and exit
+
+fmt options:
+  [files…]               .syql files to format (default: the manifest's
+                         queries directory, recursively)
+  --manifest-dir <dir>   directory holding syncular.json (default: .)
+  --check                fail unless every file is already canonical
 
 init options:
   --manifest-dir <dir>   directory to scaffold into (default: .)`;
@@ -48,10 +60,16 @@ interface GenerateArgs {
   manifestDir: string;
   check: boolean;
   watch: boolean;
+  print: string | undefined;
 }
 
 function parseGenerateArgs(argv: readonly string[]): GenerateArgs {
-  const args: GenerateArgs = { manifestDir: '.', check: false, watch: false };
+  const args: GenerateArgs = {
+    manifestDir: '.',
+    check: false,
+    watch: false,
+    print: undefined,
+  };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--check') {
@@ -63,6 +81,11 @@ function parseGenerateArgs(argv: readonly string[]): GenerateArgs {
       if (value === undefined) fail('--manifest-dir requires a value');
       args.manifestDir = value;
       i += 1;
+    } else if (arg === '--print') {
+      const value = argv[i + 1];
+      if (value === undefined) fail('--print requires a query name');
+      args.print = value;
+      i += 1;
     } else {
       fail(`unknown argument ${JSON.stringify(arg)}\n${USAGE}`);
     }
@@ -70,9 +93,59 @@ function parseGenerateArgs(argv: readonly string[]): GenerateArgs {
   if (args.check && args.watch) {
     fail('--check and --watch cannot be combined');
   }
+  if (args.print !== undefined && (args.check || args.watch)) {
+    fail('--print cannot be combined with --check/--watch');
+  }
   return args;
 }
 
+/** `generate --print <name>`: "what does this actually run" — the lowered,
+ * checked SQL for one named query, plus its params/tables/knob variants. */
+function runGeneratePrint(args: GenerateArgs, name: string): void {
+  let result: ReturnType<typeof generate>;
+  try {
+    result = generate(args.manifestDir);
+  } catch (error) {
+    fail(friendlyGenerateError(error));
+  }
+  const query = result.queries.find((q) => q.name === name);
+  if (query === undefined) {
+    const known = result.queries.map((q) => q.name).join(', ');
+    fail(
+      `no named query ${JSON.stringify(name)} — this manifest defines: ${known.length > 0 ? known : '(none)'}`,
+    );
+  }
+  console.log(`-- ${query.name} (${query.file})`);
+  console.log(`-- tables: ${query.tables.join(', ')}`);
+  if (query.params.length > 0) {
+    console.log('-- params:');
+    for (const param of query.params) {
+      const marks = [
+        param.optional === true ? 'optional' : 'required',
+        ...(param.flag === true ? ['flag'] : []),
+        ...(param.group !== undefined ? [`group ${param.group}`] : []),
+      ].join(', ');
+      console.log(`--   :${param.name} ${param.type} (${marks})`);
+    }
+  }
+  console.log(query.sql);
+  if (query.orderBy !== undefined) {
+    console.log('-- orderBy variants (each checked against the schema):');
+    const base = query.positionalSqlBase ?? '';
+    for (const col of query.orderBy.allowed) {
+      const isDefault = col.name === query.orderBy.defaultColumn;
+      console.log(
+        `--   ${col.langName}: ${base} order by ${col.name} asc|desc${query.positionalLimitTail ?? ''}${isDefault ? '   (default)' : ''}`,
+      );
+    }
+  }
+  if (query.limit !== undefined) {
+    console.log(
+      `-- limit: bound value, default ${query.limit.default ?? query.limit.max}${query.limit.max !== undefined ? `, clamped to ${query.limit.max}` : ''}`,
+    );
+  }
+}
+
 function parseManifestDir(argv: readonly string[]): string {
   let manifestDir = '.';
   for (let i = 0; i < argv.length; i++) {
@@ -150,10 +223,80 @@ function runGenerateWatch(args: GenerateArgs): void {
   });
 }
 
+/** `syncular fmt`: canonicalize `.syql` files in place (or `--check`). */
+function runFmt(argv: readonly string[]): void {
+  let manifestDir = '.';
+  let check = false;
+  const files: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] as string;
+    if (arg === '--check') check = true;
+    else if (arg === '--manifest-dir') {
+      const value = argv[i + 1];
+      if (value === undefined) fail('--manifest-dir requires a value');
+      manifestDir = value;
+      i += 1;
+    } else if (arg.startsWith('--')) {
+      fail(`unknown argument ${JSON.stringify(arg)}\n${USAGE}`);
+    } else {
+      files.push(arg);
+    }
+  }
+  let targets: string[];
+  if (files.length > 0) {
+    targets = files.map((f) => resolve(f));
+  } else {
+    const manifestPath = resolve(manifestDir, MANIFEST_FILENAME);
+    if (!existsSync(manifestPath)) {
+      fail(
+        `no files given and no ${MANIFEST_FILENAME} in ${manifestDir} — pass .syql files or --manifest-dir`,
+      );
+    }
+    const manifest = parseManifest(
+      JSON.parse(readFileSync(manifestPath, 'utf8')),
+    );
+    const queriesDir = resolve(manifestDir, manifest.queries);
+    targets = loadQueries(queriesDir)
+      .filter((q) => q.file.endsWith('.syql'))
+      .map((q) => resolve(queriesDir, q.file));
+  }
+  if (targets.length === 0) {
+    console.log('no .syql files to format');
+    return;
+  }
+  let drifted = 0;
+  for (const path of targets) {
+    if (!path.endsWith('.syql')) {
+      fail(`fmt formats .syql files only, got ${path}`);
+    }
+    const source = readFileSync(path, 'utf8');
+    let formatted: string;
+    try {
+      formatted = formatSyql(path, source);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+    if (formatted === source) continue;
+    drifted += 1;
+    if (check) {
+      console.error(`${path}: not canonical — run \`syncular fmt\``);
+    } else {
+      writeFileSync(path, formatted, 'utf8');
+      console.log(`formatted ${path}`);
+    }
+  }
+  if (check && drifted > 0) process.exit(1);
+  if (drifted === 0) console.log('all .syql files canonical');
+}
+
 export function runCli(argv: readonly string[]): void {
   const command = argv[0];
   if (command === 'generate') {
     const args = parseGenerateArgs(argv.slice(1));
+    if (args.print !== undefined) {
+      runGeneratePrint(args, args.print);
+      return;
+    }
     if (args.watch) {
       runGenerateWatch(args);
       return;
@@ -161,6 +304,14 @@ export function runCli(argv: readonly string[]): void {
     runGenerateOnce(args);
     return;
   }
+  if (command === 'fmt') {
+    runFmt(argv.slice(1));
+    return;
+  }
+  if (command === 'lsp') {
+    void runLspStdio();
+    return;
+  }
   if (command === 'init') {
     const dir = parseManifestDir(argv.slice(1));
     try {

package/src/emit-dart.ts

@@ -14,6 +14,7 @@
  * verifies freshness byte-exactly.
  */
 import type { IrColumnType, IrDocument, IrSubscription, IrTable } from './ir';
+import { snakeToCamel } from './naming';
 
 /** §2.4 column type → honest Dart type. `json`/`blob_ref` are the raw
  * canonical JSON string; `bytes`/`crdt` are opaque `List<int>`. */
@@ -45,9 +46,9 @@ function pascalCase(name: string): string {
     .join('');
 }
 
+/** Language-facing field name — the pinned §12 naming map. */
 function camelCase(name: string): string {
-  const pascal = pascalCase(name);
-  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  return snakeToCamel(name);
 }
 
 function quote(value: string): string {

package/src/emit-kotlin.ts

@@ -13,6 +13,7 @@
  * the IR hash so `--check` verifies freshness byte-exactly.
  */
 import type { IrColumnType, IrDocument, IrSubscription, IrTable } from './ir';
+import { snakeToCamel } from './naming';
 
 /** §2.4 column type → honest Kotlin type. `json`/`blob_ref` are the raw
  * canonical JSON string; `bytes`/`crdt` are opaque `ByteArray`. */
@@ -44,9 +45,9 @@ function pascalCase(name: string): string {
     .join('');
 }
 
+/** Language-facing field name — the pinned §12 naming map. */
 function camelCase(name: string): string {
-  const pascal = pascalCase(name);
-  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  return snakeToCamel(name);
 }
 
 function quote(value: string): string {

package/src/emit-queries-dart.ts

@@ -8,7 +8,8 @@
  * Header carries the IR hash for byte-exact `--check`.
  */
 import type { IrColumnType } from './ir';
-import type { AnalyzedQuery, QueryColumn } from './query';
+import { snakeToCamel } from './naming';
+import type { AnalyzedQuery, QueryColumn, QueryParam } from './query';
 
 const DART_TYPE: Readonly<Record<IrColumnType, string>> = {
   string: 'String',
@@ -29,9 +30,9 @@ function pascalCase(name: string): string {
     .join('');
 }
 
+/** Language-facing field name — the pinned §12 naming map. */
 function camelCase(name: string): string {
-  const pascal = pascalCase(name);
-  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  return snakeToCamel(name);
 }
 
 function typeName(name: string): string {
@@ -43,7 +44,7 @@ function quote(value: string): string {
 }
 
 function rowAccessor(column: QueryColumn): string {
-  const key = `row[${quote(column.name)}]`;
+  const key = `row[${quote(column.langName)}]`;
   switch (column.type) {
     case 'string':
     case 'json':
@@ -72,6 +73,46 @@ function paramValue(type: IrColumnType, name: string): string {
   }
 }
 
+/** Bind for a §4 OPTIONAL param: Dart `null` rides as JSON null (the §7
+ * neutralization guards make it a no-op). */
+function optionalParamValue(type: IrColumnType, name: string): string {
+  switch (type) {
+    case 'bytes':
+    case 'crdt':
+      return `${name} == null ? null : _queryBindBytes(${name})`;
+    default:
+      return name;
+  }
+}
+
+function isOptionalParam(query: AnalyzedQuery, p: QueryParam): boolean {
+  return (
+    p.optional === true ||
+    p.flag === true ||
+    (query.limit !== undefined && p.name === 'limit')
+  );
+}
+
+/** Per-query orderBy allowlist enum (column = the checked SQL column). */
+function emitOrderByEnum(query: AnalyzedQuery): string[] {
+  if (query.orderBy === undefined) return [];
+  const lines: string[] = [];
+  lines.push(
+    `/// §6 orderBy allowlist for ${query.name} — checked at generate time.`,
+  );
+  lines.push(`enum ${typeName(query.name)}OrderBy {`);
+  lines.push(
+    query.orderBy.allowed
+      .map((col) => `  ${camelCase(col.langName)}(${quote(col.name)})`)
+      .join(',\n') + ';',
+  );
+  lines.push('');
+  lines.push(`  const ${typeName(query.name)}OrderBy(this.column);`);
+  lines.push('  final String column;');
+  lines.push('}');
+  return lines;
+}
+
 function emitClass(query: AnalyzedQuery): string[] {
   const Row = `${typeName(query.name)}Row`;
   const lines: string[] = [];
@@ -80,26 +121,26 @@ function emitClass(query: AnalyzedQuery): string[] {
   for (const column of query.columns) {
     const opt = column.nullable ? '?' : '';
     lines.push(
-      `  final ${DART_TYPE[column.type]}${opt} ${camelCase(column.name)};`,
+      `  final ${DART_TYPE[column.type]}${opt} ${camelCase(column.langName)};`,
     );
   }
   lines.push('');
   const ctorParams = query.columns
-    .map((c) => `${c.nullable ? '' : 'required '}this.${camelCase(c.name)}`)
+    .map((c) => `${c.nullable ? '' : 'required '}this.${camelCase(c.langName)}`)
     .join(', ');
   lines.push(`  const ${Row}({${ctorParams}});`);
   lines.push('');
   lines.push(`  static ${Row}? fromRow(Map<String, Object?> row) {`);
   for (const column of query.columns) {
     if (!column.nullable) {
-      const name = camelCase(column.name);
+      const name = camelCase(column.langName);
       lines.push(`    final ${name} = ${rowAccessor(column)};`);
       lines.push(`    if (${name} == null) return null;`);
     }
   }
   const args = query.columns
     .map((c) => {
-      const name = camelCase(c.name);
+      const name = camelCase(c.langName);
       return c.nullable ? `${name}: ${rowAccessor(c)}` : `${name}: ${name}`;
     })
     .join(', ');
@@ -120,27 +161,68 @@ function emitRunner(query: AnalyzedQuery): string[] {
     `const List<String> syncular${Pascal}QueryTables = [${query.tables.map(quote).join(', ')}];`,
   );
   lines.push('');
-  lines.push(`const String _${query.name}Sql = ${quote(query.positionalSql)};`);
+  if (query.orderBy !== undefined) {
+    lines.push(
+      `const String _${query.name}SqlBase = ${quote(query.positionalSqlBase ?? '')};`,
+    );
+  } else {
+    lines.push(
+      `const String _${query.name}Sql = ${quote(query.positionalSql)};`,
+    );
+  }
   lines.push('');
   lines.push(`/// Run the ${query.name} named query (SELECT-only).`);
-  const args = query.params
-    .map((p) => `required ${DART_TYPE[p.type]} ${camelCase(p.name)}`)
-    .join(', ');
-  const argsClause = query.params.length > 0 ? `, {${args}}` : '';
+  const args: string[] = [];
+  for (const p of query.params) {
+    const name = camelCase(p.langName);
+    if (isOptionalParam(query, p)) {
+      args.push(`${DART_TYPE[p.type]}? ${name}`);
+    } else {
+      args.push(`required ${DART_TYPE[p.type]} ${name}`);
+    }
+  }
+  if (query.orderBy !== undefined) {
+    const defaultCase = camelCase(
+      query.orderBy.allowed.find((c) => c.name === query.orderBy?.defaultColumn)
+        ?.langName ?? query.orderBy.defaultColumn,
+    );
+    args.push(
+      `${typeName(query.name)}OrderBy orderBy = ${typeName(query.name)}OrderBy.${defaultCase}`,
+    );
+    args.push(
+      `SyncularQueryDir dir = SyncularQueryDir.${query.orderBy.defaultDir}`,
+    );
+  }
+  const argsClause = args.length > 0 ? `, {${args.join(', ')}}` : '';
   lines.push(
     `List<${Row}> syncular${Pascal}Query(SyncularClient client${argsClause}) {`,
   );
+  if (query.orderBy !== undefined) {
+    const limitTail =
+      query.positionalLimitTail !== undefined
+        ? ` ${quote(query.positionalLimitTail.trim())}`
+        : '';
+    lines.push(
+      `  final sql = '$_${query.name}SqlBase order by \${orderBy.column} \${dir.name}'${limitTail === '' ? '' : `\n      ' ' ${limitTail.trim()}`};`,
+    );
+  }
+  const sqlRef = query.orderBy !== undefined ? 'sql' : `_${query.name}Sql`;
   if (query.params.length > 0) {
     const binds = query.params
-      .map((p) => paramValue(p.type, camelCase(p.name)))
+      .map((p) => {
+        const name = camelCase(p.langName);
+        return isOptionalParam(query, p)
+          ? optionalParamValue(p.type, name)
+          : paramValue(p.type, name);
+      })
       .join(', ');
     lines.push(`  final params = <Object?>[${binds}];`);
     lines.push(
-      `  return client.query(_${query.name}Sql, params: params).map(${Row}.fromRow).whereType<${Row}>().toList();`,
+      `  return client.query(${sqlRef}, params: params).map(${Row}.fromRow).whereType<${Row}>().toList();`,
     );
   } else {
     lines.push(
-      `  return client.query(_${query.name}Sql).map(${Row}.fromRow).whereType<${Row}>().toList();`,
+      `  return client.query(${sqlRef}).map(${Row}.fromRow).whereType<${Row}>().toList();`,
     );
   }
   lines.push('}');
@@ -192,8 +274,19 @@ export function emitQueriesDartModule(
     ].join('\n'),
   );
 
+  if (queries.some((q) => q.orderBy !== undefined)) {
+    parts.push(
+      [
+        '/// §6 orderBy direction (shared by every orderBy-knob query).',
+        'enum SyncularQueryDir { asc, desc }',
+      ].join('\n'),
+    );
+  }
+
   for (const query of queries) {
     parts.push(emitClass(query).join('\n'));
+    const orderByEnum = emitOrderByEnum(query);
+    if (orderByEnum.length > 0) parts.push(orderByEnum.join('\n'));
   }
   for (const query of queries) {
     parts.push(emitRunner(query).join('\n'));