@syncular/typegen 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,7 +48,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/core": "0.5.0",
-    "@syncular/server": "0.5.0"
+    "@syncular/core": "0.6.0",
+    "@syncular/server": "0.6.0"
   }
 }

package/src/cli.ts

@@ -117,33 +117,63 @@ function runGeneratePrint(args: GenerateArgs, name: string): void {
   }
   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})`);
+  if (query.syql !== undefined) {
+    console.log('-- revision: SYQL 1');
+    console.log(`-- backend: ${query.syql.plan.backend}`);
+    if (query.syql.inputs.length > 0) {
+      console.log('-- public inputs:');
+      for (const input of query.syql.inputs) {
+        if (input.kind === 'value') {
+          console.log(
+            `--   ${input.name}: ${input.type}${input.nullable ? ' | null' : ''} (${input.required ? 'required' : 'optional'})`,
+          );
+        } else if (input.kind === 'group') {
+          console.log(
+            `--   ${input.name}: optional group (${input.members.map((member) => `${member.name}: ${member.type}${member.nullable ? ' | null' : ''}`).join(', ')})`,
+          );
+        } else if (input.kind === 'switch') {
+          console.log(`--   ${input.name}: switch (default false)`);
+        } else if (input.kind === 'sort') {
+          console.log(
+            `--   ${input.name}: sort [${input.profiles.map((profile) => profile.name).join(', ')}] (default ${input.defaultProfile})`,
+          );
+        } else {
+          console.log(
+            `--   ${input.name}: page 1..${input.maxSize} (default ${input.defaultSize})`,
+          );
+        }
+      }
     }
-  }
-  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;
+    if (query.syql.identity !== undefined) {
+      console.log(`-- identity: ${query.syql.identity.join(', ')}`);
+    }
+    console.log(
+      `-- checked statements: ${query.syql.plan.statements.length} (activation controls: ${query.syql.plan.activationControls.join(', ') || 'none'})`,
+    );
+    for (const statement of query.syql.plan.statements) {
+      const selectors = [
+        ...(statement.activationMask === undefined
+          ? []
+          : [`mask=${statement.activationMask}`]),
+        ...(statement.sortProfile === undefined
+          ? []
+          : [`sort=${statement.sortProfile}`]),
+      ];
+      console.log(`-- [${selectors.join(', ') || 'default'}]`);
+      console.log(statement.sql);
       console.log(
-        `--   ${col.langName}: ${base} order by ${col.name} asc|desc${query.positionalLimitTail ?? ''}${isDefault ? '   (default)' : ''}`,
+        `-- binds: ${statement.binds.map((bind) => `:${bind.name}`).join(', ') || '(none)'}`,
       );
     }
+    return;
   }
-  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}` : ''}`,
-    );
+  if (query.params.length > 0) {
+    console.log('-- params:');
+    for (const param of query.params) {
+      console.log(`--   :${param.name} ${param.type} (required)`);
+    }
   }
+  console.log(query.sql);
 }
 
 function parseManifestDir(argv: readonly string[]): string {

package/src/emit-queries-dart.ts

@@ -9,7 +9,12 @@
  */
 import type { IrColumnType } from './ir';
 import { snakeToCamel } from './naming';
-import type { AnalyzedQuery, QueryColumn, QueryParam } from './query';
+import type {
+  AnalyzedQuery,
+  QueryColumn,
+  QuerySyqlPlanBind,
+  QuerySyqlPublicInput,
+} from './query';
 
 const DART_TYPE: Readonly<Record<IrColumnType, string>> = {
   string: 'String',
@@ -85,31 +90,174 @@ function optionalParamValue(type: IrColumnType, name: string): string {
   }
 }
 
-function isOptionalParam(query: AnalyzedQuery, p: QueryParam): boolean {
-  return (
-    p.optional === true ||
-    p.flag === true ||
-    (query.limit !== undefined && p.name === 'limit')
-  );
+function syqlInput(query: AnalyzedQuery, name: string): QuerySyqlPublicInput {
+  const input = query.syql?.inputs.find((candidate) => candidate.name === name);
+  if (input === undefined) throw new Error(`unknown SYQL input ${name}`);
+  return input;
+}
+
+function syqlDartType(type: IrColumnType, nullable: boolean): string {
+  return `${DART_TYPE[type]}${nullable ? '?' : ''}`;
+}
+
+function syqlControlActive(query: AnalyzedQuery, name: string): string {
+  const input = syqlInput(query, name);
+  const access = camelCase(input.langName);
+  if (input.kind === 'switch') return access;
+  if (input.kind === 'value' && input.nullable) return `${access}.isPresent`;
+  if (input.kind === 'value' || input.kind === 'group') {
+    return `${access} != null`;
+  }
+  throw new Error(`${name} is not an activation control`);
+}
+
+function syqlBindExpr(query: AnalyzedQuery, bind: QuerySyqlPlanBind): string {
+  if (bind.kind === 'condition-active') {
+    return bind.controls
+      .map((control) => syqlControlActive(query, control))
+      .join(' && ');
+  }
+  const input = syqlInput(query, bind.input);
+  const access = camelCase(input.langName);
+  if (bind.kind === 'page') return `effective${typeName(access)}`;
+  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}`);
+    const memberAccess = `${access}.${camelCase(member.langName)}`;
+    const value = member.nullable
+      ? optionalParamValue(member.type, memberAccess)
+      : paramValue(member.type, memberAccess);
+    return `${access} == null ? null : ${value}`;
+  }
+  if (input.kind !== 'value') throw new Error('value bind/input mismatch');
+  if (input.required) {
+    return input.nullable
+      ? optionalParamValue(input.type, access)
+      : paramValue(input.type, access);
+  }
+  return input.nullable
+    ? `${access}.isPresent ? ${optionalParamValue(input.type, `${access}.value`)} : null`
+    : optionalParamValue(input.type, access);
+}
+
+function emitSyqlDartTypes(query: AnalyzedQuery): string[] {
+  const lines: string[] = [];
+  for (const input of query.syql?.inputs ?? []) {
+    if (input.kind === 'group') {
+      const name = `${typeName(query.name)}${typeName(input.langName)}`;
+      lines.push(`class ${name} {`);
+      for (const member of input.members) {
+        lines.push(
+          `  final ${syqlDartType(member.type, member.nullable)} ${camelCase(member.langName)};`,
+        );
+      }
+      const args = input.members
+        .map((member) => `required this.${camelCase(member.langName)}`)
+        .join(', ');
+      lines.push(`  const ${name}({${args}});`, '}', '');
+    } else if (input.kind === 'sort') {
+      const name = `${typeName(query.name)}${typeName(input.langName)}`;
+      lines.push(
+        `enum ${name} { ${input.profiles.map((profile) => camelCase(profile.langName)).join(', ')} }`,
+        '',
+      );
+    }
+  }
+  if (lines[lines.length - 1] === '') lines.pop();
+  return lines;
 }
 
-/** Per-query orderBy allowlist enum (column = the checked SQL column). */
-function emitOrderByEnum(query: AnalyzedQuery): string[] {
-  if (query.orderBy === undefined) return [];
+function emitSyqlDartRunner(query: AnalyzedQuery): string[] {
+  const metadata = query.syql;
+  if (metadata === undefined) throw new Error('missing SYQL metadata');
+  const Row = `${typeName(query.name)}Row`;
+  const Pascal = pascalCase(query.name);
   const lines: string[] = [];
   lines.push(
-    `/// §6 orderBy allowlist for ${query.name} — checked at generate time.`,
+    `/// Tables the ${query.name} query reads (exact invalidation set).`,
+    `const List<String> syncular${Pascal}QueryTables = [${query.tables.map(quote).join(', ')}];`,
+    '',
+    `/// Run the ${query.name} revision-1 SYQL query.`,
   );
-  lines.push(`enum ${typeName(query.name)}OrderBy {`);
+  const args: string[] = [];
+  for (const input of metadata.inputs) {
+    const name = camelCase(input.langName);
+    if (input.kind === 'value') {
+      const type = syqlDartType(input.type, input.nullable);
+      if (input.required) args.push(`required ${type} ${name}`);
+      else if (input.nullable) {
+        args.push(
+          `SyqlQueryPresence<${type}> ${name} = const SyqlQueryPresence.absent()`,
+        );
+      } else args.push(`${type}? ${name}`);
+    } else if (input.kind === 'group') {
+      args.push(`${typeName(query.name)}${typeName(input.langName)}? ${name}`);
+    } else if (input.kind === 'switch') {
+      args.push(`bool ${name} = false`);
+    } else if (input.kind === 'sort') {
+      const defaultCase =
+        input.profiles.find((profile) => profile.name === input.defaultProfile)
+          ?.langName ?? input.defaultProfile;
+      const type = `${typeName(query.name)}${typeName(input.langName)}`;
+      args.push(`${type} ${name} = ${type}.${camelCase(defaultCase)}`);
+    } else {
+      args.push(`int? ${name}`);
+    }
+  }
+  const argsClause = args.length > 0 ? `, {${args.join(', ')}}` : '';
   lines.push(
-    `${query.orderBy.allowed
-      .map((col) => `  ${camelCase(col.langName)}(${quote(col.name)})`)
-      .join(',\n')};`,
+    `List<${Row}> syncular${Pascal}Query(SyncularClient client${argsClause}) {`,
+  );
+  const page = metadata.inputs.find((input) => input.kind === 'page');
+  if (page?.kind === 'page') {
+    const name = camelCase(page.langName);
+    lines.push(
+      `  final effective${typeName(name)} = ${name} ?? ${page.defaultSize};`,
+      `  if (effective${typeName(name)} < 1 || effective${typeName(name)} > ${page.maxSize}) {`,
+      `    throw SyqlQueryInputException('SYQL_RUNTIME_INVALID_PAGE', ${quote(`${query.name}: invalid page size`)});`,
+      '  }',
+    );
+  }
+  if (metadata.plan.backend === 'variants') {
+    lines.push('  var activationMask = 0;');
+    metadata.plan.activationControls.forEach((control, index) => {
+      lines.push(
+        `  if (${syqlControlActive(query, control)}) activationMask |= ${2 ** index};`,
+      );
+    });
+  }
+  const sort = metadata.inputs.find((input) => input.kind === 'sort');
+  const profileCount = sort?.kind === 'sort' ? sort.profiles.length : 1;
+  const sortIndex =
+    sort?.kind === 'sort' ? `${camelCase(sort.langName)}.index` : '0';
+  const index =
+    metadata.plan.backend === 'variants'
+      ? `activationMask * ${profileCount} + ${sortIndex}`
+      : sortIndex;
+  lines.push(
+    `  final statementIndex = ${index};`,
+    '  late final String sql;',
+    '  late final List<Object?> params;',
+    '  switch (statementIndex) {',
+  );
+  metadata.plan.statements.forEach((statement, statementIndex) => {
+    const binds = statement.binds
+      .map((bind) => syqlBindExpr(query, bind))
+      .join(', ');
+    lines.push(
+      `    case ${statementIndex}: sql = ${quote(statement.positionalSql)}; params = <Object?>[${binds}]; break;`,
+    );
+  });
+  lines.push(
+    "    default: throw StateError('invalid generated SYQL statement index');",
+    '  }',
+    `  return client.query(sql, params: params).map(${Row}.fromRow).whereType<${Row}>().toList();`,
+    '}',
   );
-  lines.push('');
-  lines.push(`  const ${typeName(query.name)}OrderBy(this.column);`);
-  lines.push('  final String column;');
-  lines.push('}');
   return lines;
 }
 
@@ -151,6 +299,7 @@ function emitClass(query: AnalyzedQuery): string[] {
 }
 
 function emitRunner(query: AnalyzedQuery): string[] {
+  if (query.syql !== undefined) return emitSyqlDartRunner(query);
   const Row = `${typeName(query.name)}Row`;
   const Pascal = pascalCase(query.name);
   const lines: string[] = [];
@@ -161,59 +310,24 @@ function emitRunner(query: AnalyzedQuery): string[] {
     `const List<String> syncular${Pascal}QueryTables = [${query.tables.map(quote).join(', ')}];`,
   );
   lines.push('');
-  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(`const String _${query.name}Sql = ${quote(query.positionalSql)};`);
   lines.push('');
   lines.push(`/// Run the ${query.name} named query (SELECT-only).`);
   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}`,
-    );
+    args.push(`required ${DART_TYPE[p.type]} ${name}`);
   }
   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`;
+  const sqlRef = `_${query.name}Sql`;
   if (query.params.length > 0) {
     const binds = query.params
       .map((p) => {
         const name = camelCase(p.langName);
-        return isOptionalParam(query, p)
-          ? optionalParamValue(p.type, name)
-          : paramValue(p.type, name);
+        return paramValue(p.type, name);
       })
       .join(', ');
     lines.push(`  final params = <Object?>[${binds}];`);
@@ -246,6 +360,27 @@ export function emitQueriesDartModule(
     ].join('\n'),
   );
 
+  if (queries.some((query) => query.syql !== undefined)) {
+    parts.push(
+      [
+        'class SyqlQueryPresence<T> {',
+        '  final bool isPresent;',
+        '  final T? value;',
+        '  const SyqlQueryPresence.absent() : isPresent = false, value = null;',
+        '  const SyqlQueryPresence.present(this.value) : isPresent = true;',
+        '}',
+        '',
+        'class SyqlQueryInputException implements Exception {',
+        '  final String code;',
+        '  final String message;',
+        '  const SyqlQueryInputException(this.code, this.message);',
+        '  @override',
+        "  String toString() => '$code: $message';",
+        '}',
+      ].join('\n'),
+    );
+  }
+
   parts.push(
     [
       '/// Lift a SQLite boolean: a real bool, or 0/1 as a number.',
@@ -274,19 +409,10 @@ 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) {
+    const syqlTypes = emitSyqlDartTypes(query);
+    if (syqlTypes.length > 0) parts.push(syqlTypes.join('\n'));
     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'));