@syncular/typegen 0.5.1 → 0.6.0

package/dist/emit-queries.js

@@ -20,25 +20,264 @@ 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}`;
+const SYQL_PARAM_TS_TYPE = {
+    ...TS_TYPE,
+    integer: 'bigint',
+};
+function bindExpr(param) {
+    return `params.${propertyKey(param.langName)}`;
 }
 function reactiveParam(query, name) {
+    if (query.syql !== undefined) {
+        const input = query.syql.inputs.find((candidate) => candidate.kind === 'value' && candidate.name === name);
+        if (input?.kind !== 'value')
+            throw new Error(`unknown reactive input ${name}`);
+        return `String(params.${propertyKey(input.langName)})`;
+    }
     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 syqlInput(query, name) {
+    const input = query.syql?.inputs.find((candidate) => candidate.name === name);
+    if (input === undefined)
+        throw new Error(`unknown SYQL input ${name}`);
+    return input;
+}
+function syqlTsValueType(type, nullable) {
+    return `${SYQL_PARAM_TS_TYPE[type]}${nullable ? ' | null' : ''}`;
+}
+function syqlTsTypeCheck(expression, type, nullable) {
+    let check;
+    switch (type) {
+        case 'integer':
+            check = `typeof ${expression} === 'bigint'`;
+            break;
+        case 'float':
+            check = `typeof ${expression} === 'number' && Number.isFinite(${expression})`;
+            break;
+        case 'boolean':
+            check = `typeof ${expression} === 'boolean'`;
+            break;
+        case 'bytes':
+        case 'crdt':
+            check = `${expression} instanceof Uint8Array`;
+            break;
+        default:
+            check = `typeof ${expression} === 'string'`;
+    }
+    return nullable ? `${expression} === null || (${check})` : check;
+}
+function syqlControlActive(query, control, params) {
+    const input = syqlInput(query, control);
+    const access = `${params}.${propertyKey(input.langName)}`;
+    if (input.kind === 'switch')
+        return `${access} === true`;
+    if (input.kind === 'value' || input.kind === 'group') {
+        return `${access} !== undefined`;
+    }
+    throw new Error(`${control} is not an activation control`);
+}
+function syqlBindExpr(query, bind, params) {
+    if (bind.kind === 'condition-active') {
+        return bind.controls
+            .map((control) => syqlControlActive(query, control, params))
+            .join(' && ');
+    }
+    const input = syqlInput(query, bind.input);
+    const access = `${params}.${propertyKey(input.langName)}`;
+    if (bind.kind === 'page') {
+        if (input.kind !== 'page')
+            throw new Error('page bind/input mismatch');
+        return `${access} ?? ${input.defaultSize}`;
+    }
+    if (bind.kind === 'group-member') {
+        if (input.kind !== 'group')
+            throw new Error('group bind/input mismatch');
+        const member = input.members.find((candidate) => candidate.name === bind.member);
+        if (member === undefined)
+            throw new Error(`unknown group member ${bind.member}`);
+        return `${access}?.${propertyKey(member.langName)} ?? null`;
+    }
+    if (input.kind !== 'value')
+        throw new Error('value bind/input mismatch');
+    if (input.required)
+        return access;
+    return input.nullable ? `${access}?.value ?? null` : `${access} ?? null`;
+}
+function emitSyqlValidation(query, Params) {
+    const inputs = query.syql?.inputs ?? [];
+    const lines = [];
+    lines.push(`function ${query.name}Validate(raw?: ${Params}): ${Params} {`, `  const params = raw ?? ({} as ${Params});`, `  const allowed = new Set([${inputs.map((input) => quote(input.langName)).join(', ')}]);`, '  for (const key of Object.keys(params)) {', `    if (!allowed.has(key)) throw new SyqlInputError('SYQL_RUNTIME_UNKNOWN_INPUT', ${quote(query.name)} + ': unknown input ' + key);`, '  }');
+    for (const input of inputs) {
+        const key = propertyKey(input.langName);
+        const access = `params.${key}`;
+        if (input.kind === 'value') {
+            if (input.required) {
+                lines.push(`  if (!Object.prototype.hasOwnProperty.call(params, ${quote(input.langName)})) throw new SyqlInputError('SYQL_RUNTIME_MISSING_REQUIRED_INPUT', ${quote(`${query.name}: missing required input ${input.name}`)});`, `  if (!(${syqlTsTypeCheck(access, input.type, input.nullable)})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_INPUT', ${quote(`${query.name}: invalid input ${input.name}`)});`);
+            }
+            else if (input.nullable) {
+                lines.push(`  if (${access} !== undefined && (typeof ${access} !== 'object' || ${access} === null || ${access}.present !== true || !(${syqlTsTypeCheck(`${access}.value`, input.type, true)}))) throw new SyqlInputError('SYQL_RUNTIME_INVALID_INPUT', ${quote(`${query.name}: invalid optional input ${input.name}`)});`);
+            }
+            else {
+                lines.push(`  if (${access} !== undefined && !(${syqlTsTypeCheck(access, input.type, false)})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_INPUT', ${quote(`${query.name}: invalid optional input ${input.name}`)});`);
+            }
+        }
+        else if (input.kind === 'group') {
+            lines.push(`  if (${access} !== undefined) {`, `    if (typeof ${access} !== 'object' || ${access} === null) throw new SyqlInputError('SYQL_RUNTIME_INVALID_GROUP', ${quote(`${query.name}: invalid group ${input.name}`)});`, `    const allowedMembers = new Set([${input.members.map((member) => quote(member.langName)).join(', ')}]);`, `    if (Object.keys(${access}).some((key) => !allowedMembers.has(key))) throw new SyqlInputError('SYQL_RUNTIME_INVALID_GROUP', ${quote(`${query.name}: unknown member in group ${input.name}`)});`);
+            for (const member of input.members) {
+                const memberAccess = `${access}.${propertyKey(member.langName)}`;
+                lines.push(`    if (!Object.prototype.hasOwnProperty.call(${access}, ${quote(member.langName)}) || !(${syqlTsTypeCheck(memberAccess, member.type, member.nullable)})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_GROUP', ${quote(`${query.name}: invalid or partial group ${input.name}`)});`);
+            }
+            lines.push('  }');
+        }
+        else if (input.kind === 'switch') {
+            lines.push(`  if (${access} !== undefined && typeof ${access} !== 'boolean') throw new SyqlInputError('SYQL_RUNTIME_INVALID_INPUT', ${quote(`${query.name}: invalid switch ${input.name}`)});`);
+        }
+        else if (input.kind === 'sort') {
+            lines.push(`  if (${access} !== undefined && ![${input.profiles.map((profile) => quote(profile.langName)).join(', ')}].includes(${access})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_SORT', ${quote(`${query.name}: invalid sort profile`)});`);
+        }
+        else {
+            lines.push(`  if (${access} !== undefined && (!Number.isSafeInteger(${access}) || ${access} < 1 || ${access} > ${input.maxSize})) throw new SyqlInputError('SYQL_RUNTIME_INVALID_PAGE', ${quote(`${query.name}: page size must be an integer from 1 through ${input.maxSize}`)});`);
+        }
+    }
+    lines.push('  return params;', '}');
+    return lines;
+}
+function emitSyqlQuery(query, hash) {
+    const metadata = query.syql;
+    if (metadata === undefined)
+        throw new Error('missing SYQL metadata');
+    const Row = `${pascalCase(query.name)}Row`;
+    const Params = `${pascalCase(query.name)}Params`;
+    const inputs = metadata.inputs;
+    const hasParams = inputs.length > 0;
+    const requiresParams = inputs.some((input) => input.kind === 'value' && input.required);
+    const lines = [];
+    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.langName)}: ${TS_TYPE[column.type]}${column.nullable ? ' | null' : ''};`);
+    }
+    lines.push('}', '');
+    for (const input of inputs) {
+        if (input.kind === 'group') {
+            lines.push(`export interface ${pascalCase(query.name)}${pascalCase(input.langName)} {`);
+            for (const member of input.members) {
+                lines.push(`  ${propertyKey(member.langName)}: ${syqlTsValueType(member.type, member.nullable)};`);
+            }
+            lines.push('}', '');
+        }
+    }
+    if (hasParams) {
+        lines.push(`/** Public revision-1 SYQL inputs for ${quote(query.name)}. */`);
+        lines.push(`export interface ${Params} {`);
+        for (const input of inputs) {
+            const key = propertyKey(input.langName);
+            if (input.kind === 'value') {
+                const optional = !input.required;
+                const type = syqlTsValueType(input.type, input.nullable);
+                lines.push(`  ${key}${optional ? '?' : ''}: ${optional && input.nullable ? `SyqlPresent<${type}>` : type};`);
+            }
+            else if (input.kind === 'group') {
+                lines.push(`  ${key}?: ${pascalCase(query.name)}${pascalCase(input.langName)};`);
+            }
+            else if (input.kind === 'switch') {
+                lines.push(`  ${key}?: boolean;`);
+            }
+            else if (input.kind === 'sort') {
+                lines.push(`  ${key}?: ${input.profiles.map((profile) => quote(profile.langName)).join(' | ')};`);
+            }
+            else {
+                lines.push(`  ${key}?: number;`);
+            }
+        }
+        lines.push('}', '');
+        lines.push(...emitSyqlValidation(query, Params), '');
+    }
+    lines.push(`/** Tables ${quote(query.name)} reads (compatibility/export surface). */`, `export const ${query.name}Tables = [${query.tables.map(quote).join(', ')}] as const;`, '');
+    const paramDecl = !hasParams
+        ? ''
+        : requiresParams
+            ? `raw: ${Params}`
+            : `raw?: ${Params}`;
+    const validated = hasParams ? `${query.name}Validate(raw)` : undefined;
+    const statementType = hasParams
+        ? `{ sql: string; bind: (params: ${Params}) => QueryValue[] }`
+        : '{ sql: string; bind: () => QueryValue[] }';
+    lines.push(`const ${query.name}Statements: ${statementType}[] = [`);
+    for (const statement of metadata.plan.statements) {
+        const binds = statement.binds
+            .map((bind) => syqlBindExpr(query, bind, 'params'))
+            .join(', ');
+        lines.push(`  { sql: ${quote(statement.positionalSql)}, bind: (${hasParams ? 'params' : ''}) => [${binds}] },`);
+    }
+    lines.push('];');
+    const sort = inputs.find((input) => input.kind === 'sort');
+    if (sort?.kind === 'sort') {
+        lines.push(`const ${query.name}SortIndexes = { ${sort.profiles.map((profile, index) => `${propertyKey(profile.langName)}: ${index}`).join(', ')} } as const;`);
+    }
+    lines.push(`function ${query.name}Select(${paramDecl}): { sql: string; bind: QueryValue[] } {`);
+    if (validated !== undefined)
+        lines.push(`  const params = ${validated};`);
+    let maskExpression = '0';
+    if (metadata.plan.backend === 'variants') {
+        lines.push('  let mask = 0;');
+        metadata.plan.activationControls.forEach((control, index) => {
+            lines.push(`  if (${syqlControlActive(query, control, 'params')}) mask |= ${2 ** index};`);
+        });
+        maskExpression = 'mask';
+    }
+    let sortExpression = '0';
+    const profileCount = sort?.kind === 'sort' ? sort.profiles.length : 1;
+    if (sort?.kind === 'sort') {
+        sortExpression = `${query.name}SortIndexes[params.${propertyKey(sort.langName)} ?? ${quote(sort.profiles.find((profile) => profile.name === sort.defaultProfile)?.langName ?? sort.defaultProfile)}]`;
+    }
+    const indexExpression = metadata.plan.backend === 'variants'
+        ? `${maskExpression} * ${profileCount} + ${sortExpression}`
+        : sortExpression;
+    lines.push(`  const statement = ${query.name}Statements[${indexExpression}];`, `  if (statement === undefined) throw new Error('invalid generated SYQL statement index');`, `  return { sql: statement.sql, bind: statement.bind(${hasParams ? 'params' : ''}) };`, '}', '');
+    const runnerParam = !hasParams
+        ? ''
+        : requiresParams
+            ? `, params: ${Params}`
+            : `, params?: ${Params}`;
+    lines.push(`/** Run the ${quote(query.name)} named query (SELECT-only). */`, `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}[];`, '}', '');
+    const paramsType = hasParams ? Params : 'undefined';
+    const defaultStatement = metadata.plan.statements.find((statement) => (statement.activationMask === undefined ||
+        statement.activationMask === 0) &&
+        (sort?.kind !== 'sort' || statement.sortProfile === sort.defaultProfile));
+    lines.push(`/** Revisioned reactive descriptor for \`useQuery(${query.name}Query${hasParams ? ', params' : ''})\`. */`, `export const ${query.name}Query: NamedQuery<${Row}, ${paramsType}> = {`, `  id: ${quote(`${hash}/${query.name}`)},`, `  hasParams: ${hasParams},`, `  sql: ${quote(defaultStatement?.positionalSql ?? query.positionalSql)},`);
+    if (hasParams) {
+        lines.push(`  sqlFor: (params: ${Params}) => ${query.name}Select(params).sql,`);
+    }
+    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(', ');
+        lines.push(`    { base: { table: ${quote(coverage.table)}, variable: ${quote(coverage.variable)}${fixed.length > 0 ? `, fixedScopes: { ${fixed} }` : ''} }, units: [${coverage.units.map((param) => reactiveParam(query, param)).join(', ')}] },`);
+    }
+    lines.push('  ],', hasParams
+        ? `  bind: (params: ${Params}) => ${query.name}Select(params).bind,`
+        : `  bind: () => ${query.name}Select().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');
+}
 function scopeKeyExpression(query, pattern, variable, param) {
     const marker = `{${variable}}`;
     const index = pattern.indexOf(marker);
@@ -49,11 +288,11 @@ function scopeKeyExpression(query, pattern, variable, param) {
     return `${quote(prefix)} + ${reactiveParam(query, param)} + ${quote(suffix)}`;
 }
 function emitQuery(query, hash) {
+    if (query.syql !== undefined)
+        return emitSyqlQuery(query, hash);
     const Row = `${pascalCase(query.name)}Row`;
     const Params = `${pascalCase(query.name)}Params`;
     const lines = [];
-    // 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) {
@@ -61,138 +300,42 @@ function emitQuery(query, hash) {
     }
     lines.push('}');
     lines.push('');
-    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).
+    const hasParams = query.params.length > 0;
     if (hasParams) {
         lines.push(`/** Named parameters for ${quote(query.name)}. */`);
         lines.push(`export interface ${Params} {`);
         for (const param of query.params) {
-            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(`  ${propertyKey(param.langName)}: ${PARAM_TS_TYPE[param.type]};`);
         }
         lines.push('}');
         lines.push('');
     }
-    // Tables dependency set (for useRawSql {tables} / useQuery).
     lines.push(`/** Tables ${quote(query.name)} reads (compatibility/export surface). */`);
     lines.push(`export const ${query.name}Tables = [${query.tables.map(quote).join(', ')}] as const;`);
     lines.push('');
-    // 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) => bindExpr(query, p, access)).join(', ')}]`
+        ? `[${query.params.map(bindExpr).join(', ')}]`
         : '[]';
-    // §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 (query.variants !== undefined) {
-        lines.push(`  const variant = ${selectFn}(params);`);
-        lines.push('  const rows = await client.query(variant.sql, variant.bind);');
+    lines.push(`export async function ${query.name}(client: QueryClient${hasParams ? `, params: ${Params}` : ''}): Promise<${Row}[]> {`);
+    if (hasParams) {
+        lines.push(`  const rows = await client.query(${sqlConst}, ${positional});`);
     }
     else {
-        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(`  const rows = await client.query(${sqlConst});`);
     }
     lines.push(`  return rows as unknown as ${Row}[];`);
     lines.push('}');
     lines.push('');
-    // 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(`/** 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,`);
-    }
-    else if (query.orderBy !== undefined) {
-        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' : ''}) => [`);
@@ -212,10 +355,7 @@ function emitQuery(query, hash) {
         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) {
+    if (hasParams) {
         lines.push(`  bind: (params: ${Params}) => ${positional},`);
     }
     else {
@@ -234,6 +374,33 @@ export function emitQueriesModule(queries, hash, irVersion) {
         `// irVersion: ${irVersion}`,
         `// irHash: ${hash}`,
     ].join('\n'));
+    if (queries.some((query) => query.syql !== undefined)) {
+        parts.push([
+            'export type SyqlRuntimeErrorCode =',
+            "  | 'SYQL_RUNTIME_MISSING_REQUIRED_INPUT'",
+            "  | 'SYQL_RUNTIME_UNKNOWN_INPUT'",
+            "  | 'SYQL_RUNTIME_INVALID_INPUT'",
+            "  | 'SYQL_RUNTIME_INVALID_GROUP'",
+            "  | 'SYQL_RUNTIME_INVALID_SORT'",
+            "  | 'SYQL_RUNTIME_INVALID_PAGE';",
+            '',
+            'export class SyqlInputError extends Error {',
+            "  readonly name = 'SyqlInputError';",
+            '  constructor(readonly code: SyqlRuntimeErrorCode, message: string) {',
+            '    super(message);',
+            '  }',
+            '}',
+            '',
+            'export interface SyqlPresent<T> {',
+            '  readonly present: true;',
+            '  readonly value: T;',
+            '}',
+            '',
+            'export function syqlPresent<T>(value: T): SyqlPresent<T> {',
+            '  return { present: true, value };',
+            '}',
+        ].join('\n'));
+    }
     parts.push([
         "/** A bindable SQL param/row value (the wrapper's SqlValue subset). */",
         'export type QueryValue =',
@@ -258,8 +425,7 @@ export function emitQueriesModule(queries, hash, irVersion) {
         ' *  `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. */',
+        ' *  selects a checked revision-1 SYQL physical statement when needed. */',
         'export interface NamedQuery<Row, Params = undefined> {',
         '  readonly id: string;',
         '  readonly hasParams: boolean;',

package/dist/fmt.d.ts

@@ -1,3 +1,3 @@
-/** Format one `.syql` source file into its canonical form. Throws
- * {@link TypegenError} when the source does not parse. */
+/** Format one `.syql` source. Invalid or non-equivalent output is rejected so
+ * the CLI never writes a partially understood file. */
 export declare function formatSyql(file: string, source: string): string;