@syncular/typegen 0.2.1 → 0.3.1

package/dist/emit-queries-kotlin.js

@@ -1,3 +1,4 @@
+import { snakeToCamel } from './naming.js';
 const KOTLIN_TYPE = {
     string: 'String',
     integer: 'Long',
@@ -15,9 +16,9 @@ function pascalCase(name) {
         .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
         .join('');
 }
+/** Language-facing field name — the pinned §12 naming map. */
 function camelCase(name) {
-    const pascal = pascalCase(name);
-    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+    return snakeToCamel(name);
 }
 function typeName(name) {
     return name.charAt(0).toUpperCase() + name.slice(1);
@@ -26,7 +27,7 @@ function quote(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$')}"`;
 }
 function rowAccessor(column) {
-    const key = `row[${quote(column.name)}]`;
+    const key = `row[${quote(column.langName)}]`;
     switch (column.type) {
         case 'string':
         case 'json':
@@ -59,6 +60,37 @@ function paramValue(type, name) {
             return `JsonValue.of(${name})`;
     }
 }
+/** Bind for a §4 OPTIONAL param: `null` rides as JSON null (the §7
+ * neutralization guards make it a no-op). */
+function optionalParamValue(type, name) {
+    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, p) {
+    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) {
+    if (query.orderBy === undefined)
+        return [];
+    const lines = [];
+    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) {
     const Row = `${typeName(query.name)}Row`;
     const lines = [];
@@ -66,13 +98,13 @@ function emitDataClass(query) {
     lines.push(`data class ${Row}(`);
     for (const column of query.columns) {
         const opt = column.nullable ? '?' : '';
-        lines.push(`    val ${camelCase(column.name)}: ${KOTLIN_TYPE[column.type]}${opt},`);
+        lines.push(`    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}`);
@@ -81,7 +113,7 @@ function emitDataClass(query) {
             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('    }');
@@ -92,25 +124,55 @@ function emitRunner(query) {
     const Row = `${typeName(query.name)}Row`;
     const lines = [];
     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 signature = query.params.length > 0
-        ? `client: SyncularClient, ${args}`
+    const args = [];
+    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 = 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) }`);
+        lines.push(`            return client.query(${sqlRef}, params).mapNotNull { ${Row}.fromRow(it) }`);
     }
     else {
-        lines.push(`            return client.query(${query.name}Sql).mapNotNull { ${Row}.fromRow(it) }`);
+        lines.push(`            return client.query(${sqlRef}).mapNotNull { ${Row}.fromRow(it) }`);
     }
     lines.push('        }');
     return lines;
@@ -149,8 +211,20 @@ export function emitQueriesKotlinModule(queries, hash, irVersion, packageName, o
         '    return JsonValue.obj("\\$bytes" to JsonValue.of(hex))',
         '}',
     ].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 = [];
     objLines.push('/** Typed named queries (the sqlc/SQLDelight tier). */');

package/dist/emit-queries-swift.js

@@ -1,3 +1,4 @@
+import { snakeToCamel } from './naming.js';
 const SWIFT_TYPE = {
     string: 'String',
     integer: 'Int',
@@ -15,9 +16,9 @@ function pascalCase(name) {
         .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
         .join('');
 }
+/** Language-facing field name — the pinned §12 naming map. */
 function camelCase(name) {
-    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. */
 function typeName(name) {
@@ -27,7 +28,7 @@ function quote(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 function rowAccessor(column) {
-    const key = `row[${quote(column.name)}]`;
+    const key = `row[${quote(column.langName)}]`;
     switch (column.type) {
         case 'string':
         case 'json':
@@ -58,6 +59,28 @@ function paramValue(type, name) {
             return `.string(${name})`;
     }
 }
+/** Bind for a §4 OPTIONAL param: `nil` rides as JSON null (the §7
+ * neutralization guards make it a no-op). */
+function optionalParamValue(type, name) {
+    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, p) {
+    return (p.optional === true ||
+        p.flag === true ||
+        (query.limit !== undefined && p.name === 'limit'));
+}
 function emitRowStruct(query) {
     const Row = `${typeName(query.name)}Row`;
     const lines = [];
@@ -65,12 +88,12 @@ function emitRowStruct(query) {
     lines.push(`public struct ${Row}: Sendable, Equatable {`);
     for (const column of query.columns) {
         const opt = column.nullable ? '?' : '';
-        lines.push(`    public let ${camelCase(column.name)}: ${SWIFT_TYPE[column.type]}${opt}`);
+        lines.push(`    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}`);
@@ -84,29 +107,72 @@ function emitRowStruct(query) {
     lines.push('}');
     return lines;
 }
+/** Per-query orderBy allowlist enum (rawValue = the checked SQL column). */
+function emitOrderByEnum(query) {
+    if (query.orderBy === undefined)
+        return [];
+    const lines = [];
+    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) {
     const Row = `${typeName(query.name)}Row`;
     const lines = [];
     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 signature = query.params.length > 0
-        ? `client: SyncularClient, ${args}`
+    const args = [];
+    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 = 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`);
+        lines.push(`        return try client.query(${sqlRef}, params: params).compactMap { row in`);
     }
     else {
-        lines.push(`        return try client.query(${query.name}Sql).compactMap { row in`);
+        lines.push(`        return try client.query(${sqlRef}).compactMap { row in`);
     }
     lines.push('            guard case let .object(fields) = row else { return nil }');
     lines.push(`            return ${Row}(row: fields)`);
@@ -133,8 +199,20 @@ export function emitQueriesSwiftModule(queries, hash, irVersion, enumName) {
         '    }',
         '}',
     ].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 = [];
     enumLines.push('/// Typed named queries (the sqlc/SQLDelight tier).');

package/dist/emit-queries.js

@@ -20,61 +20,167 @@ function propertyKey(name) {
 }
 /** A named-query param value is the SqlValue subset its type maps to. */
 const PARAM_TS_TYPE = TS_TYPE;
+function isOptional(param) {
+    return param.optional === true || param.flag === true;
+}
+/** The positional bind expression for one param. `access` is `params` or
+ * `params?` depending on whether the params object itself may be absent. */
+function bindExpr(query, param, access) {
+    if (query.limit !== undefined && param.name === 'limit') {
+        // The default + clamp live IN the SQL (`min(coalesce(?, d), m)`).
+        return `${access}.limit ?? null`;
+    }
+    const key = propertyKey(param.langName);
+    return isOptional(param) ? `${access}.${key} ?? null` : `params.${key}`;
+}
 function emitQuery(query) {
     const Row = `${pascalCase(query.name)}Row`;
     const Params = `${pascalCase(query.name)}Params`;
     const lines = [];
-    // Row interface.
+    // Row interface — keyed by the language-facing names, which ARE the
+    // runtime result keys (§5 projection lowering aliases them in SQL).
     lines.push(`/** One row of the ${quote(query.name)} query (its projection). */`);
     lines.push(`export interface ${Row} {`);
     for (const column of query.columns) {
-        lines.push(`  ${propertyKey(column.name)}: ${TS_TYPE[column.type]}${column.nullable ? ' | null' : ''};`);
+        lines.push(`  ${propertyKey(column.langName)}: ${TS_TYPE[column.type]}${column.nullable ? ' | null' : ''};`);
     }
     lines.push('}');
     lines.push('');
-    // Params interface (only when there are params).
-    const hasParams = query.params.length > 0;
+    const hasParams = query.params.length > 0 || query.orderBy !== undefined;
+    const requiresParams = query.params.some((p) => !isOptional(p) && !(query.limit !== undefined && p.name === 'limit'));
+    // Params interface (params and/or knob keys).
     if (hasParams) {
         lines.push(`/** Named parameters for ${quote(query.name)}. */`);
         lines.push(`export interface ${Params} {`);
         for (const param of query.params) {
-            lines.push(`  ${propertyKey(param.name)}: ${PARAM_TS_TYPE[param.type]};`);
+            if (query.limit !== undefined && param.name === 'limit')
+                continue;
+            const opt = isOptional(param);
+            lines.push(`  ${propertyKey(param.langName)}${opt ? '?' : ''}: ${PARAM_TS_TYPE[param.type]}${opt ? ' | null' : ''};`);
+        }
+        if (query.orderBy !== undefined) {
+            const keys = query.orderBy.allowed
+                .map((c) => quote(c.langName))
+                .join(' | ');
+            lines.push(`  /** §6 orderBy knob — a generate-time-checked allowlist. */`);
+            lines.push(`  orderBy?: ${keys};`);
+            lines.push(`  dir?: 'asc' | 'desc';`);
+        }
+        if (query.limit !== undefined) {
+            const clamp = query.limit.max !== undefined ? ` (clamped to ${query.limit.max})` : '';
+            lines.push(`  /** §6 limit knob — binds as a value${clamp}; default ${query.limit.default ?? query.limit.max}. */`);
+            lines.push('  limit?: number;');
         }
         lines.push('}');
         lines.push('');
     }
-    // Tables dependency set (for useSyncQuery {tables} / useNamedQuery).
-    lines.push(`/** Tables ${quote(query.name)} reads — the exact useSyncQuery \`{tables}\` set. */`);
+    // Tables dependency set (for useRawSql {tables} / useQuery).
+    lines.push(`/** Tables ${quote(query.name)} reads — the exact useRawSql \`{tables}\` set. */`);
     lines.push(`export const ${query.name}Tables = [${query.tables.map(quote).join(', ')}] as const;`);
     lines.push('');
-    // The runner. SQL is the positional form; params reorder into the array.
-    const paramArg = hasParams ? `params: ${Params}` : '';
+    // SQL constants: the static default statement, plus (orderBy knob) the
+    // baked base + column map + compose function.
     const sqlConst = `${query.name}Sql`;
+    lines.push(`const ${sqlConst} = ${quote(query.positionalSql)};`);
+    const composeFn = `${query.name}ComposeSql`;
+    if (query.orderBy !== undefined) {
+        const base = `${query.name}SqlBase`;
+        const colsConst = `${query.name}OrderColumns`;
+        const defaultLang = query.orderBy.allowed.find((c) => c.name === query.orderBy?.defaultColumn)
+            ?.langName ?? query.orderBy.defaultColumn;
+        lines.push(`const ${base} = ${quote(query.positionalSqlBase ?? '')};`);
+        lines.push(`const ${colsConst} = { ${query.orderBy.allowed
+            .map((c) => `${propertyKey(c.langName)}: ${quote(c.name)}`)
+            .join(', ')} } as const;`);
+        lines.push(`function ${composeFn}(params?: ${Params}): string {`);
+        lines.push(`  const column = ${colsConst}[params?.orderBy ?? ${quote(defaultLang)}] ?? ${quote(query.orderBy.defaultColumn)};`);
+        lines.push(`  const dir = (params?.dir ?? ${quote(query.orderBy.defaultDir)}) === 'desc' ? 'desc' : 'asc';`);
+        lines.push(`  return \`\${${base}} order by \${column} \${dir}${query.positionalLimitTail ?? ''}\`;`);
+        lines.push('}');
+    }
+    // Positional bind list.
+    const access = requiresParams ? 'params' : 'params?';
     const positional = hasParams
-        ? `[${query.params.map((p) => `params.${propertyKey(p.name)}`).join(', ')}]`
+        ? `[${query.params.map((p) => bindExpr(query, p, access)).join(', ')}]`
         : '[]';
-    lines.push(`const ${sqlConst} = ${quote(query.positionalSql)};`);
+    // §7 variant backend: one statement per provided-combination, selected by
+    // a bitmask over the optional groups (bit i = group i provided/true). The
+    // neutralization statement above stays the canonical/default form.
+    const selectFn = `${query.name}SelectVariant`;
+    const paramArgDecl = requiresParams
+        ? `params: ${Params}`
+        : `params?: ${Params}`;
+    if (query.variants !== undefined && query.variantGroups !== undefined) {
+        const variantsConst = `${query.name}Variants`;
+        lines.push(`const ${variantsConst}: { sql: string; bind: (${paramArgDecl}) => QueryValue[] }[] = [`);
+        for (const variant of query.variants) {
+            const binds = variant.params
+                .map((name) => {
+                const param = query.params.find((p) => p.name === name);
+                if (param === undefined)
+                    throw new Error(`unknown param ${name}`);
+                return bindExpr(query, param, access);
+            })
+                .join(', ');
+            lines.push(`  // [${variant.when.join(' + ') || 'no optional filters'}]`);
+            lines.push(`  { sql: ${quote(variant.positionalSql)}, bind: (${requiresParams ? 'params' : 'params?'}) => [${binds}] },`);
+        }
+        lines.push('];');
+        lines.push(`function ${selectFn}(${paramArgDecl}): { sql: string; bind: QueryValue[] } {`);
+        lines.push('  let mask = 0;');
+        query.variantGroups.forEach((group, index) => {
+            const langOf = (name) => query.params.find((p) => p.name === name)?.langName ?? name;
+            const condition = group.flag
+                ? `params?.${propertyKey(langOf(group.params[0]))} === true`
+                : group.params
+                    .map((name) => `(params?.${propertyKey(langOf(name))} ?? null) !== null`)
+                    .join(' && ');
+            lines.push(`  if (${condition}) mask |= ${1 << index};`);
+        });
+        lines.push(`  const variant = ${variantsConst}[mask] as (typeof ${variantsConst})[number];`);
+        lines.push('  return { sql: variant.sql, bind: variant.bind(params) };');
+        lines.push('}');
+    }
     lines.push('');
+    // The runner.
+    const paramArg = !hasParams ? '' : paramArgDecl;
     lines.push(`/** Run the ${quote(query.name)} named query (SELECT-only). */`);
     lines.push(`export async function ${query.name}(client: QueryClient${hasParams ? `, ${paramArg}` : ''}): Promise<${Row}[]> {`);
-    if (hasParams) {
-        lines.push(`  const rows = await client.query(${sqlConst}, ${positional});`);
+    if (query.variants !== undefined) {
+        lines.push(`  const variant = ${selectFn}(params);`);
+        lines.push('  const rows = await client.query(variant.sql, variant.bind);');
     }
     else {
-        lines.push(`  const rows = await client.query(${sqlConst});`);
+        const sqlExpr = query.orderBy !== undefined ? `${composeFn}(params)` : sqlConst;
+        if (hasParams) {
+            lines.push(`  const rows = await client.query(${sqlExpr}, ${positional});`);
+        }
+        else {
+            lines.push(`  const rows = await client.query(${sqlExpr});`);
+        }
     }
     lines.push(`  return rows as unknown as ${Row}[];`);
     lines.push('}');
     lines.push('');
-    // A descriptor for react's `useNamedQuery` — the SQL, the exact table
-    // dependency set, and a `bind(params)` → positional array. Typed by the
-    // query's own Row/Params so the hook stays fully typed.
-    lines.push(`/** Descriptor for \`useNamedQuery(${query.name}Query${hasParams ? ', params' : ''})\` — sql + tables + row type. */`);
+    // A descriptor for react's `useQuery` — the SQL (static, composed from
+    // 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. */`);
     const paramsTypeArg = hasParams ? Params : 'undefined';
     lines.push(`export const ${query.name}Query: NamedQuery<${Row}, ${paramsTypeArg}> = {`);
     lines.push(`  sql: ${sqlConst},`);
+    if (query.variants !== undefined) {
+        lines.push(`  sqlFor: (params: ${Params}) => ${selectFn}(params).sql,`);
+    }
+    else if (query.orderBy !== undefined) {
+        lines.push(`  sqlFor: (params: ${Params}) => ${composeFn}(params),`);
+    }
     lines.push(`  tables: ${query.name}Tables,`);
-    if (hasParams) {
+    if (query.variants !== undefined) {
+        lines.push(`  bind: (params: ${Params}) => ${selectFn}(params).bind,`);
+    }
+    else if (hasParams) {
         lines.push(`  bind: (params: ${Params}) => ${positional},`);
     }
     else {
@@ -112,13 +218,16 @@ export function emitQueriesModule(queries, hash, irVersion) {
         '',
         '/** A named-query descriptor — sql + its exact table dependency set + a',
         ' *  `bind(params)` → positional args. Consumed by',
-        " *  `@syncular/react`'s `useNamedQuery`. `Row` is the projection row",
-        ' *  type; `Params` is `undefined` for a param-less query. */',
+        " *  `@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 sql: string;',
         '  readonly tables: readonly string[];',
         '  readonly bind: (params: Params) => readonly QueryValue[];',
-        '  /** Phantom — carries the Row type for `useNamedQuery` inference. */',
+        '  readonly sqlFor?: (params: Params) => string;',
+        '  /** Phantom — carries the Row type for `useQuery` inference. */',
         '  readonly __row?: Row;',
         '}',
     ].join('\n'));

package/dist/emit-swift.js

@@ -1,3 +1,4 @@
+import { snakeToCamel } from './naming.js';
 /**
  * §2.4 column type → honest Swift type. `json`/`blob_ref` are the raw
  * canonical JSON string (the client's blob API parses blob_ref); `bytes`/
@@ -27,9 +28,9 @@ function pascalCase(name) {
         .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
         .join('');
 }
+/** Language-facing field name — the pinned §12 naming map. */
 function camelCase(name) {
-    const pascal = pascalCase(name);
-    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+    return snakeToCamel(name);
 }
 function quote(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;

package/dist/emit.d.ts

@@ -13,4 +13,5 @@
  * byte-exactly.
  */
 import type { IrDocument } from './ir.js';
-export declare function emitModule(ir: IrDocument, hash: string): string;
+import { type NamingMode } from './naming.js';
+export declare function emitModule(ir: IrDocument, hash: string, naming?: NamingMode): string;