@syncular/typegen 0.2.0 → 0.3.0

package/src/emit-queries-kotlin.ts

@@ -11,7 +11,8 @@
  * separate output). 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 KOTLIN_TYPE: Readonly<Record<IrColumnType, string>> = {
   string: 'String',
@@ -32,9 +33,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 {
@@ -46,7 +47,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':
@@ -81,6 +82,45 @@ function paramValue(type: IrColumnType, name: string): string {
   }
 }
 
+/** Bind for a §4 OPTIONAL param: `null` rides as JSON null (the §7
+ * neutralization guards make it a no-op). */
+function optionalParamValue(type: IrColumnType, name: string): string {
+  switch (type) {
+    case 'integer':
+      return `${name}?.let { JsonValue.of(it.toDouble()) } ?: JsonValue.Null`;
+    case 'bytes':
+    case 'crdt':
+      return `${name}?.let { queryBindBytes(it) } ?: JsonValue.Null`;
+    default:
+      return `${name}?.let { JsonValue.of(it) } ?: JsonValue.Null`;
+  }
+}
+
+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 class ${typeName(query.name)}OrderBy(val column: String) {`);
+  lines.push(
+    query.orderBy.allowed
+      .map((col) => `    ${camelCase(col.langName)}(${quote(col.name)})`)
+      .join(',\n') + ';',
+  );
+  lines.push('}');
+  return lines;
+}
+
 function emitDataClass(query: AnalyzedQuery): string[] {
   const Row = `${typeName(query.name)}Row`;
   const lines: string[] = [];
@@ -89,14 +129,14 @@ function emitDataClass(query: AnalyzedQuery): string[] {
   for (const column of query.columns) {
     const opt = column.nullable ? '?' : '';
     lines.push(
-      `    val ${camelCase(column.name)}: ${KOTLIN_TYPE[column.type]}${opt},`,
+      `    val ${camelCase(column.langName)}: ${KOTLIN_TYPE[column.type]}${opt},`,
     );
   }
   lines.push(') {');
   lines.push('    companion object {');
   lines.push(`        fun fromRow(row: JsonValue): ${Row}? {`);
   for (const column of query.columns) {
-    const name = camelCase(column.name);
+    const name = camelCase(column.langName);
     const accessor = rowAccessor(column);
     if (column.nullable) {
       lines.push(`            val ${name} = ${accessor}`);
@@ -104,7 +144,7 @@ function emitDataClass(query: AnalyzedQuery): string[] {
       lines.push(`            val ${name} = ${accessor} ?: return null`);
     }
   }
-  const args = query.columns.map((c) => camelCase(c.name)).join(', ');
+  const args = query.columns.map((c) => camelCase(c.langName)).join(', ');
   lines.push(`            return ${Row}(${args})`);
   lines.push('        }');
   lines.push('    }');
@@ -118,30 +158,69 @@ function emitRunner(query: AnalyzedQuery): string[] {
   lines.push(
     `        val ${query.name}Tables = listOf(${query.tables.map(quote).join(', ')})`,
   );
-  lines.push(
-    `        private const val ${query.name}Sql = ${quote(query.positionalSql)}`,
-  );
+  if (query.orderBy !== undefined) {
+    lines.push(
+      `        private const val ${query.name}SqlBase = ${quote(query.positionalSqlBase ?? '')}`,
+    );
+  } else {
+    lines.push(
+      `        private const val ${query.name}Sql = ${quote(query.positionalSql)}`,
+    );
+  }
   lines.push('');
   lines.push(`        /** Run the ${query.name} named query (SELECT-only). */`);
-  const args = query.params
-    .map((p) => `${camelCase(p.name)}: ${KOTLIN_TYPE[p.type]}`)
-    .join(', ');
+  const args: string[] = [];
+  for (const p of query.params) {
+    const name = camelCase(p.langName);
+    if (isOptionalParam(query, p)) {
+      args.push(`${name}: ${KOTLIN_TYPE[p.type]}? = null`);
+    } else {
+      args.push(`${name}: ${KOTLIN_TYPE[p.type]}`);
+    }
+  }
+  if (query.orderBy !== undefined) {
+    const defaultCase = camelCase(
+      query.orderBy.allowed.find((c) => c.name === query.orderBy?.defaultColumn)
+        ?.langName ?? query.orderBy.defaultColumn,
+    );
+    args.push(
+      `orderBy: ${typeName(query.name)}OrderBy = ${typeName(query.name)}OrderBy.${defaultCase}`,
+    );
+    args.push(
+      `dir: SyncularQueryDir = SyncularQueryDir.${query.orderBy.defaultDir.toUpperCase()}`,
+    );
+  }
   const signature =
-    query.params.length > 0
-      ? `client: SyncularClient, ${args}`
+    args.length > 0
+      ? `client: SyncularClient, ${args.join(', ')}`
       : 'client: SyncularClient';
   lines.push(`        fun ${query.name}(${signature}): List<${Row}> {`);
+  if (query.orderBy !== undefined) {
+    const limitTail =
+      query.positionalLimitTail !== undefined
+        ? ` + ${quote(query.positionalLimitTail)}`
+        : '';
+    lines.push(
+      `            val sql = ${query.name}SqlBase + " order by " + orderBy.column + " " + dir.sql${limitTail}`,
+    );
+  }
+  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(`            val params = listOf(${binds})`);
     lines.push(
-      `            return client.query(${query.name}Sql, params).mapNotNull { ${Row}.fromRow(it) }`,
+      `            return client.query(${sqlRef}, params).mapNotNull { ${Row}.fromRow(it) }`,
     );
   } else {
     lines.push(
-      `            return client.query(${query.name}Sql).mapNotNull { ${Row}.fromRow(it) }`,
+      `            return client.query(${sqlRef}).mapNotNull { ${Row}.fromRow(it) }`,
     );
   }
   lines.push('        }');
@@ -194,8 +273,22 @@ export function emitQueriesKotlinModule(
     ].join('\n'),
   );
 
+  if (queries.some((q) => q.orderBy !== undefined)) {
+    parts.push(
+      [
+        '/** §6 orderBy direction (shared by every orderBy-knob query). */',
+        'enum class SyncularQueryDir(val sql: String) {',
+        '    ASC("asc"),',
+        '    DESC("desc");',
+        '}',
+      ].join('\n'),
+    );
+  }
+
   for (const query of queries) {
     parts.push(emitDataClass(query).join('\n'));
+    const orderByEnum = emitOrderByEnum(query);
+    if (orderByEnum.length > 0) parts.push(orderByEnum.join('\n'));
   }
 
   const objLines: string[] = [];

package/src/emit-queries-swift.ts

@@ -13,7 +13,8 @@
  * bytes decode). 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 SWIFT_TYPE: Readonly<Record<IrColumnType, string>> = {
   string: 'String',
@@ -34,9 +35,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);
 }
 
 /** The query function/type name: already camelCase; PascalCase for the type. */
@@ -49,7 +50,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':
@@ -82,6 +83,32 @@ function paramValue(type: IrColumnType, name: string): string {
   }
 }
 
+/** Bind for a §4 OPTIONAL param: `nil` rides as JSON null (the §7
+ * neutralization guards make it a no-op). */
+function optionalParamValue(type: IrColumnType, name: string): string {
+  switch (type) {
+    case 'integer':
+      return `${name}.map { JSONValue.number(Double($0)) } ?? .null`;
+    case 'float':
+      return `${name}.map { JSONValue.number($0) } ?? .null`;
+    case 'boolean':
+      return `${name}.map { JSONValue.bool($0) } ?? .null`;
+    case 'bytes':
+    case 'crdt':
+      return `${name}.map { SyncularSchemaQueryBind.bytes($0) } ?? .null`;
+    default:
+      return `${name}.map { JSONValue.string($0) } ?? .null`;
+  }
+}
+
+function isOptionalParam(query: AnalyzedQuery, p: QueryParam): boolean {
+  return (
+    p.optional === true ||
+    p.flag === true ||
+    (query.limit !== undefined && p.name === 'limit')
+  );
+}
+
 function emitRowStruct(query: AnalyzedQuery): string[] {
   const Row = `${typeName(query.name)}Row`;
   const lines: string[] = [];
@@ -90,13 +117,13 @@ function emitRowStruct(query: AnalyzedQuery): string[] {
   for (const column of query.columns) {
     const opt = column.nullable ? '?' : '';
     lines.push(
-      `    public let ${camelCase(column.name)}: ${SWIFT_TYPE[column.type]}${opt}`,
+      `    public let ${camelCase(column.langName)}: ${SWIFT_TYPE[column.type]}${opt}`,
     );
   }
   lines.push('');
   lines.push('    public init?(row: [String: JSONValue]) {');
   for (const column of query.columns) {
-    const name = camelCase(column.name);
+    const name = camelCase(column.langName);
     const accessor = rowAccessor(column);
     if (column.nullable) {
       lines.push(`        self.${name} = ${accessor}`);
@@ -110,38 +137,86 @@ function emitRowStruct(query: AnalyzedQuery): string[] {
   return lines;
 }
 
+/** Per-query orderBy allowlist enum (rawValue = 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(`public enum ${typeName(query.name)}OrderBy: String, Sendable {`);
+  for (const col of query.orderBy.allowed) {
+    lines.push(`    case ${camelCase(col.langName)} = ${quote(col.name)}`);
+  }
+  lines.push('}');
+  return lines;
+}
+
 function emitRunner(query: AnalyzedQuery): string[] {
   const Row = `${typeName(query.name)}Row`;
   const lines: string[] = [];
   lines.push(
     `    public static let ${query.name}Tables = [${query.tables.map(quote).join(', ')}]`,
   );
-  lines.push(
-    `    private static let ${query.name}Sql = ${quote(query.positionalSql)}`,
-  );
+  if (query.orderBy !== undefined) {
+    lines.push(
+      `    private static let ${query.name}SqlBase = ${quote(query.positionalSqlBase ?? '')}`,
+    );
+  } else {
+    lines.push(
+      `    private static let ${query.name}Sql = ${quote(query.positionalSql)}`,
+    );
+  }
   lines.push('');
   lines.push(`    /// Run the ${query.name} named query (SELECT-only).`);
-  const args = query.params
-    .map((p) => `${camelCase(p.name)}: ${SWIFT_TYPE[p.type]}`)
-    .join(', ');
+  const args: string[] = [];
+  for (const p of query.params) {
+    const name = camelCase(p.langName);
+    if (isOptionalParam(query, p)) {
+      args.push(`${name}: ${SWIFT_TYPE[p.type]}? = nil`);
+    } else {
+      args.push(`${name}: ${SWIFT_TYPE[p.type]}`);
+    }
+  }
+  if (query.orderBy !== undefined) {
+    const defaultCase = camelCase(
+      query.orderBy.allowed.find((c) => c.name === query.orderBy?.defaultColumn)
+        ?.langName ?? query.orderBy.defaultColumn,
+    );
+    args.push(`orderBy: ${typeName(query.name)}OrderBy = .${defaultCase}`);
+    args.push(`dir: SyncularQueryDir = .${query.orderBy.defaultDir}`);
+  }
   const signature =
-    query.params.length > 0
-      ? `client: SyncularClient, ${args}`
+    args.length > 0
+      ? `client: SyncularClient, ${args.join(', ')}`
       : 'client: SyncularClient';
   lines.push(
     `    public static func ${query.name}(${signature}) throws -> [${Row}] {`,
   );
+  const sqlExpr =
+    query.orderBy !== undefined
+      ? `${query.name}SqlBase + " order by " + orderBy.rawValue + " " + dir.rawValue${query.positionalLimitTail !== undefined ? ` + ${quote(query.positionalLimitTail)}` : ''}`
+      : `${query.name}Sql`;
+  if (query.orderBy !== undefined) {
+    lines.push(`        let sql = ${sqlExpr}`);
+  }
+  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(`        let params: [JSONValue] = [${binds}]`);
     lines.push(
-      `        return try client.query(${query.name}Sql, params: params).compactMap { row in`,
+      `        return try client.query(${sqlRef}, params: params).compactMap { row in`,
     );
   } else {
     lines.push(
-      `        return try client.query(${query.name}Sql).compactMap { row in`,
+      `        return try client.query(${sqlRef}).compactMap { row in`,
     );
   }
   lines.push(
@@ -183,8 +258,22 @@ export function emitQueriesSwiftModule(
     ].join('\n'),
   );
 
+  if (queries.some((q) => q.orderBy !== undefined)) {
+    parts.push(
+      [
+        '/// §6 orderBy direction (shared by every orderBy-knob query).',
+        'public enum SyncularQueryDir: String, Sendable {',
+        '    case asc = "asc"',
+        '    case desc = "desc"',
+        '}',
+      ].join('\n'),
+    );
+  }
+
   for (const query of queries) {
     parts.push(emitRowStruct(query).join('\n'));
+    const orderByEnum = emitOrderByEnum(query);
+    if (orderByEnum.length > 0) parts.push(orderByEnum.join('\n'));
   }
 
   const enumLines: string[] = [];