@syncular/typegen 0.5.1 → 0.7.0

package/dist/manifest.d.ts

@@ -77,9 +77,7 @@ export interface Manifest {
      * generated row types/params (queries lower with `AS` aliases); "preserve"
      * keeps SQL-truth names everywhere. */
     readonly naming: NamingMode;
-    /** §7 `.syql` backend: "neutralize" (default), "variants" (enumerate
-     * whenever eligible), or "auto" (enumerate at ≤ 2 optional groups). The
-     * per-query `variants` knob always forces enumeration. */
+    /** §7 `.syql` backend: "auto" (default), "neutralize", or "variants". */
     readonly queryBackend: ManifestQueryBackend;
     readonly output: ManifestOutput;
     readonly schemaVersions: readonly ManifestSchemaVersion[];

package/dist/manifest.js

@@ -232,7 +232,7 @@ export function parseManifest(raw) {
         }
         naming = obj.naming;
     }
-    let queryBackend = 'neutralize';
+    let queryBackend = 'auto';
     if (obj.queryBackend !== undefined) {
         if (obj.queryBackend !== 'neutralize' &&
             obj.queryBackend !== 'variants' &&

package/dist/query-ir.js

@@ -1,7 +1,7 @@
 /** Serialize analyzed queries as the deterministic QueryIR JSON document. */
 export function serializeQueryIr(queries) {
     const doc = {
-        queryIrVersion: 2,
+        queryIrVersion: 3,
         queries: queries.map((query) => ({
             name: query.name,
             file: query.file,
@@ -12,11 +12,6 @@ export function serializeQueryIr(queries) {
                 name: param.name,
                 langName: param.langName,
                 type: param.type,
-                // §4 metadata — emitted only when set, so `.sql`-tier IR bytes are
-                // unchanged from before the DSL existed.
-                ...(param.optional === true ? { optional: true } : {}),
-                ...(param.group !== undefined ? { group: param.group } : {}),
-                ...(param.flag === true ? { flag: true } : {}),
             })),
             columns: query.columns.map((column) => ({
                 name: column.name,
@@ -49,43 +44,59 @@ export function serializeQueryIr(queries) {
                     ? { rowKey: query.reactive.rowKey }
                     : {}),
             },
-            // §6 knob metadata — emitted only when declared.
-            ...(query.orderBy !== undefined
-                ? {
-                    orderBy: {
-                        allowed: query.orderBy.allowed.map((c) => ({
-                            name: c.name,
-                            langName: c.langName,
-                        })),
-                        defaultColumn: query.orderBy.defaultColumn,
-                        defaultDir: query.orderBy.defaultDir,
+            ...(query.syql === undefined
+                ? {}
+                : {
+                    syql: {
+                        revision: query.syql.revision,
+                        inputs: query.syql.inputs.map((input) => {
+                            if (input.kind === 'value')
+                                return { ...input };
+                            if (input.kind === 'group') {
+                                return {
+                                    kind: input.kind,
+                                    name: input.name,
+                                    langName: input.langName,
+                                    members: input.members.map((member) => ({ ...member })),
+                                };
+                            }
+                            if (input.kind === 'sort') {
+                                return {
+                                    kind: input.kind,
+                                    name: input.name,
+                                    langName: input.langName,
+                                    defaultProfile: input.defaultProfile,
+                                    profiles: input.profiles.map((profile) => ({ ...profile })),
+                                };
+                            }
+                            return { ...input };
+                        }),
+                        plan: {
+                            backend: query.syql.plan.backend,
+                            activationControls: query.syql.plan.activationControls,
+                            conditions: query.syql.plan.conditions.map((condition) => ({
+                                controls: condition.controls,
+                                ...(condition.bind === undefined
+                                    ? {}
+                                    : { bind: condition.bind }),
+                            })),
+                            statements: query.syql.plan.statements.map((statement) => ({
+                                ...(statement.sortProfile === undefined
+                                    ? {}
+                                    : { sortProfile: statement.sortProfile }),
+                                ...(statement.activationMask === undefined
+                                    ? {}
+                                    : { activationMask: statement.activationMask }),
+                                sql: statement.sql,
+                                positionalSql: statement.positionalSql,
+                                binds: statement.binds.map((bind) => ({ ...bind })),
+                            })),
+                        },
+                        ...(query.syql.identity === undefined
+                            ? {}
+                            : { identity: query.syql.identity }),
                     },
-                }
-                : {}),
-            ...(query.limit !== undefined ? { limit: query.limit } : {}),
-            ...(query.positionalSqlBase !== undefined
-                ? { positionalSqlBase: query.positionalSqlBase }
-                : {}),
-            // §7 variant backend — emitted only when the query opts in.
-            ...(query.variantGroups !== undefined
-                ? {
-                    variantGroups: query.variantGroups.map((g) => ({
-                        key: g.key,
-                        params: g.params,
-                        flag: g.flag,
-                    })),
-                }
-                : {}),
-            ...(query.variants !== undefined
-                ? {
-                    variants: query.variants.map((v) => ({
-                        when: v.when,
-                        sql: v.sql,
-                        positionalSql: v.positionalSql,
-                        params: v.params,
-                    })),
-                }
-                : {}),
+                }),
         })),
     };
     return `${JSON.stringify(doc, null, 2)}\n`;

package/dist/query.d.ts

@@ -10,31 +10,6 @@ export interface QueryParam {
     readonly type: QueryParamType;
     /** How the type was resolved — for the docs/tests, not emitted. */
     readonly source: 'inferred' | 'comment';
-    /** §4 (DESIGN-queries.md): an optional param — its auto-guarded conjunct
-     * applies only when it is provided. Always false for the `.sql` tier. */
-    readonly optional?: boolean;
-    /** §4: the `from+to` pairing — params sharing a group apply together. */
-    readonly group?: string;
-    /** §3: a `: flag` boolean guard param (never in a predicate as written;
-     * the lowering binds it). Implies optional. */
-    readonly flag?: boolean;
-}
-/** §6 orderBy knob: a generate-time allowlist (identifiers cannot bind). */
-export interface QueryOrderBy {
-    /** Allowed columns: authored SQL name + the language-facing key the
-     * generated signature accepts. Each is SQLite-checked at generate time. */
-    readonly allowed: readonly {
-        name: string;
-        langName: string;
-    }[];
-    /** Default column (authored SQL name). */
-    readonly defaultColumn: string;
-    readonly defaultDir: 'asc' | 'desc';
-}
-/** §6 limit knob: a bound value with a codegen clamp + default. */
-export interface QueryLimit {
-    readonly max?: number;
-    readonly default?: number;
 }
 export interface QueryColumn {
     /** SQL-truth result name (pre-lowering, as authored). */
@@ -77,7 +52,7 @@ export interface QueryReactiveMetadata {
     /** Language-facing projection fields forming a proven unique row key. */
     readonly rowKey?: readonly string[];
 }
-/** §7/§8 backend selection: neutralization (default), always-variants, or
+/** §7/§8 backend selection: neutralization, always-variants, or
  * the small-N heuristic (`auto`: enumerate at ≤ 2 optional groups). */
 export type QueryBackend = 'neutralize' | 'variants' | 'auto';
 /** Naming/backend options threaded from the manifest into query analysis. */
@@ -86,9 +61,98 @@ export interface QueryNamingOptions {
     /** Emitter targets this run generates — keyword hazards are only real on
      * targets that exist. */
     readonly targets: readonly NamingTarget[];
-    /** `.syql` conditional-lowering backend (default `neutralize`); the
-     * per-query `variants` knob always forces enumeration. */
+    /** `.syql` conditional-lowering policy (default `auto`). */
     readonly backend?: QueryBackend;
+    /** Compiler-reserved physical binds. They retain their exact names and do
+     * not participate in public target-language keyword/private-name checks. */
+    readonly internalParams?: readonly string[];
+}
+/** SYQL public inputs. These are deliberately separate from SQL binds: groups
+ * and compiler-generated parameters have distinct public/runtime shapes. */
+export type QuerySyqlPublicInput = {
+    readonly kind: 'value';
+    readonly name: string;
+    readonly langName: string;
+    readonly type: QueryParamType;
+    readonly nullable: boolean;
+    readonly required: boolean;
+    readonly default?: false;
+} | {
+    readonly kind: 'group';
+    readonly name: string;
+    readonly langName: string;
+    readonly members: readonly {
+        readonly name: string;
+        readonly langName: string;
+        readonly type: QueryParamType;
+        readonly nullable: boolean;
+    }[];
+} | {
+    readonly kind: 'sort';
+    readonly name: string;
+    readonly langName: string;
+    readonly defaultProfile: string;
+    readonly profiles: readonly {
+        readonly name: string;
+        readonly langName: string;
+    }[];
+} | {
+    readonly kind: 'limit';
+    readonly name: string;
+    readonly langName: string;
+    readonly defaultSize: number;
+    readonly maxSize: number;
+};
+/** One distinct SQLite bind in a physical revision-1 statement. */
+export type QuerySyqlPlanBind = {
+    readonly kind: 'value';
+    readonly name: string;
+    readonly type: QueryParamType;
+    readonly input: string;
+} | {
+    readonly kind: 'group-member';
+    readonly name: string;
+    readonly type: QueryParamType;
+    readonly input: string;
+    readonly member: string;
+} | {
+    readonly kind: 'condition-active';
+    readonly name: string;
+    readonly type: 'boolean';
+    readonly condition: number;
+    readonly controls: readonly string[];
+} | {
+    readonly kind: 'limit';
+    readonly name: string;
+    readonly type: 'integer';
+    readonly input: string;
+};
+/** One SQLite-checked statement selected by sort profile and, for the
+ * enumerated backend, the activation bitmask. */
+export interface QuerySyqlStatement {
+    readonly sortProfile?: string;
+    readonly activationMask?: number;
+    readonly sql: string;
+    readonly positionalSql: string;
+    readonly binds: readonly QuerySyqlPlanBind[];
+}
+/** The target-neutral physical plan every emitter must implement exactly. */
+export interface QuerySyqlExecutionPlan {
+    readonly backend: Exclude<QueryBackend, 'auto'>;
+    /** One bit per conditional activation control, in declaration order. */
+    readonly activationControls: readonly string[];
+    readonly conditions: readonly {
+        readonly controls: readonly string[];
+        /** Present only for neutralized plans. */
+        readonly bind?: string;
+    }[];
+    readonly statements: readonly QuerySyqlStatement[];
+}
+export interface QuerySyqlMetadata {
+    readonly revision: 1;
+    readonly inputs: readonly QuerySyqlPublicInput[];
+    readonly plan: QuerySyqlExecutionPlan;
+    readonly identity?: readonly string[];
 }
 export interface AnalyzedQuery {
     /** camelCase function name (path-derived, or a `-- name:` override). */
@@ -111,41 +175,9 @@ export interface AnalyzedQuery {
     /** IR tables this query reads (the useRawSql `{tables}` set), sorted. */
     readonly tables: readonly string[];
     readonly reactive: QueryReactiveMetadata;
-    /** §6 orderBy knob (`.syql` tier). When present, `sql`/`positionalSql`
-     * carry the DEFAULT order-by tail and `positionalSqlBase` is the static
-     * prefix emitters compose the selected column onto. */
-    readonly orderBy?: QueryOrderBy;
-    /** §6 limit knob (`.syql` tier): the trailing `LIMIT ?` bind's clamp. */
-    readonly limit?: QueryLimit;
-    /** positional SQL WITHOUT the dynamic ORDER BY/LIMIT tail; present only
-     * when `orderBy` is (emitters build `base + ORDER BY <baked> + limit
-     * tail`). */
-    readonly positionalSqlBase?: string;
-    /** The positional limit tail (e.g. ` limit min(coalesce(?, 50), 100)` —
-     * the default+clamp live IN the SQL, so runtimes bind `limit ?? null`).
-     * Present only when BOTH knobs are declared (composers need it verbatim). */
-    readonly positionalLimitTail?: string;
-    /** §7 variant-enumeration backend (opt-in `variants` knob): one checked
-     * statement per combination of provided optional groups. Semantically
-     * identical to the neutralization `sql` by construction; the TS emitter
-     * dispatches on provided-ness for perfect index use. `when` lists the
-     * provided group keys; `params` are the DISTINCT param names this variant
-     * binds, positional order. */
-    readonly variants?: readonly {
-        readonly when: readonly string[];
-        readonly sql: string;
-        readonly positionalSql: string;
-        readonly params: readonly string[];
-    }[];
-    /** The optional-group keys, in dispatch-bit order (bit i of the variant
-     * index = group i provided). Present iff `variants` is. */
-    readonly variantGroups?: readonly {
-        readonly key: string;
-        /** Params whose provision defines the group (all must be non-null; a
-         * flag group is "on" when its single param is TRUE). */
-        readonly params: readonly string[];
-        readonly flag: boolean;
-    }[];
+    /** Revision-1 frontend/public-input and physical execution contract. When
+     * present, emitters use this instead of treating `params` as the API. */
+    readonly syql?: QuerySyqlMetadata;
 }
 /**
  * Path-relative default name. `billing/invoices/list.sql` → `billingInvoicesList`;
@@ -171,6 +203,9 @@ export interface SplitStatement {
 export declare function splitStatements(content: string): SplitStatement[];
 /** The `-- name:` override in a statement's leading comment block, or null. */
 export declare function parseStatementName(statementText: string, location: string): string | null;
+/** Strip `--` and block comments so identifier scans don't hit commented SQL,
+ * and string literals so `':x'` inside a string isn't read as a param. */
+export declare function stripCommentsAndStrings(sql: string): string;
 /** Rewrite `:name` → positional placeholders AND strip comments + collapse
  * whitespace, producing a clean single-line SQL string suitable for
  * embedding in a generated string literal. String literals are preserved
@@ -182,6 +217,18 @@ export declare function parseStatementName(statementText: string, location: stri
  * form — one bound value per DISTINCT param, reuse resolved by SQLite —
  * so the generated bind array stays one-entry-per-param. */
 export declare function toPositionalSql(sql: string): string;
+export interface TableRef {
+    readonly table: string;
+    /** Alias (or the table name when un-aliased). */
+    readonly alias: string;
+}
+export declare function scanTableRefs(sql: string, ir: IrDocument): TableRef[];
+/**
+ * Return every revision-1 column/LIKE type constraint for one bind. Unlike
+ * `inferParamType` (the legacy first-match helper), SYQL uses the complete set
+ * so conflicting checked uses cannot be silently accepted.
+ */
+export declare function inferParamTypeEvidence(paramName: string, sql: string, refs: readonly TableRef[], ir: IrDocument): readonly IrColumnType[];
 export interface QueryDb {
     /** Prepare + return the result columns / declared types / param count.
      * Throws (with SQLite's message) when the SQL is invalid against the DDL. */

package/dist/query.js

@@ -84,6 +84,8 @@ const DECLTYPE_MAP = {
     BLOBREF: 'blob_ref',
     CRDT: 'crdt',
 };
+/** Local client protocol column; query-only and never part of schema IR. */
+const SYNC_VERSION_COLUMN = '_sync_version';
 const DEFAULT_NAMING = { naming: 'camel', targets: ['ts'] };
 // -- path → name --------------------------------------------------------------
 /** A single kebab-case path segment (folder) or filename stem. */
@@ -290,7 +292,7 @@ function parseCommentParams(file, raw) {
 }
 /** Strip `--` and block comments so identifier scans don't hit commented SQL,
  * and string literals so `':x'` inside a string isn't read as a param. */
-function stripCommentsAndStrings(sql) {
+export function stripCommentsAndStrings(sql) {
     let out = '';
     let i = 0;
     while (i < sql.length) {
@@ -453,7 +455,7 @@ const RESERVED_ALIAS = new Set([
     'limit',
     'having',
 ]);
-function scanTableRefs(sql, ir) {
+export function scanTableRefs(sql, ir) {
     const cleaned = stripCommentsAndStrings(sql);
     const known = new Map(ir.tables.map((t) => [t.name, t]));
     const refs = [];
@@ -533,6 +535,17 @@ function resolveSource(item, refs, ir) {
     }
     return null;
 }
+/** Resolve the one supported query-only protocol column. SQLite still proves
+ * qualifier/ambiguity against the synthesized local tables. */
+function isSyncVersionSource(item, refs) {
+    const match = PLAIN_REF_RE.exec(item.expr);
+    if (match === null || match[2] !== SYNC_VERSION_COLUMN)
+        return false;
+    const qualifier = match[1];
+    return qualifier === undefined
+        ? refs.length === 1
+        : refs.some((ref) => ref.alias === qualifier);
+}
 // -- param type inference -----------------------------------------------------
 //
 // Infer a param's type from `col <op> :name` or `col IN (:name, …)` where `col`
@@ -603,6 +616,57 @@ function inferParamType(paramName, sql, refs, ir) {
         return 'string';
     return null;
 }
+/**
+ * Return every revision-1 column/LIKE type constraint for one bind. Unlike
+ * `inferParamType` (the legacy first-match helper), SYQL uses the complete set
+ * so conflicting checked uses cannot be silently accepted.
+ */
+export function inferParamTypeEvidence(paramName, sql, refs, ir) {
+    const cleaned = stripCommentsAndStrings(sql);
+    const byName = new Map(ir.tables.map((table) => [table.name, table]));
+    const evidence = [];
+    const add = (qualifier, column) => {
+        if (qualifier !== undefined) {
+            const ref = refs.find((candidate) => candidate.alias === qualifier);
+            const table = ref === undefined ? undefined : byName.get(ref.table);
+            const type = table?.columns.find((item) => item.name === column)?.type;
+            if (type !== undefined)
+                evidence.push(type);
+            return;
+        }
+        const matches = refs.flatMap((ref) => {
+            const table = byName.get(ref.table);
+            const type = table?.columns.find((item) => item.name === column)?.type;
+            return type === undefined ? [] : [type];
+        });
+        if (matches.length === 1)
+            evidence.push(matches[0]);
+    };
+    const comparison = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s*(?:=|==|!=|<>|<=|>=|<|>|\\bLIKE\\b|\\bIS\\b)\\s*:${paramName}\\b`, 'gi');
+    for (const match of cleaned.matchAll(comparison)) {
+        add(match[1], match[2]);
+    }
+    const reversed = new RegExp(`:${paramName}\\b\\s*(?:=|==|!=|<>|<=|>=|<|>)\\s*(?:(${IDENT})\\.)?(${IDENT})`, 'gi');
+    for (const match of cleaned.matchAll(reversed)) {
+        add(match[1], match[2]);
+    }
+    const inList = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+IN\\s*\\(([^)]*:${paramName}\\b[^)]*)\\)`, 'gi');
+    for (const match of cleaned.matchAll(inList)) {
+        add(match[1], match[2]);
+    }
+    const betweenLeft = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+:${paramName}\\b`, 'gi');
+    for (const match of cleaned.matchAll(betweenLeft)) {
+        add(match[1], match[2]);
+    }
+    const betweenRight = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+\\S+\\s+AND\\s+:${paramName}\\b`, 'gi');
+    for (const match of cleaned.matchAll(betweenRight)) {
+        add(match[1], match[2]);
+    }
+    const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'gi');
+    if (like.test(cleaned))
+        evidence.push('string');
+    return evidence;
+}
 // -- fallback column typing (computed expressions) ----------------------------
 const AGG_RE = /\b(count|sum|total|avg|min|max)\s*\(/i;
 /** decltype-null column: the documented honest fallback. Aggregates and
@@ -665,9 +729,7 @@ function inferReactiveMetadata(sql, refs, ir, params, columns) {
                         continue;
                     const name = match[1] ?? match[2];
                     const param = name === undefined ? undefined : byParam.get(name);
-                    if (param !== undefined &&
-                        param.optional !== true &&
-                        param.flag !== true) {
+                    if (param !== undefined) {
                         found.push(param.name);
                     }
                 }
@@ -677,9 +739,7 @@ function inferReactiveMetadata(sql, refs, ir, params, columns) {
                         continue;
                     for (const paramMatch of (match[1] ?? '').matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
                         const param = byParam.get(paramMatch[1]);
-                        if (param !== undefined &&
-                            param.optional !== true &&
-                            param.flag !== true) {
+                        if (param !== undefined) {
                             found.push(param.name);
                         }
                     }
@@ -750,6 +810,10 @@ export function synthesizeDdl(ir) {
             const pk = c.name === table.primaryKey ? ' PRIMARY KEY' : '';
             return `  ${c.name} ${SQL_TYPE[c.type]}${pk}${notNull}`;
         });
+        // The materialized local client table always carries this hidden protocol
+        // token. It is absent from IR mutation types but may be explicitly aliased
+        // by a named read query for optimistic concurrency.
+        cols.push(`  ${SYNC_VERSION_COLUMN} INTEGER NOT NULL DEFAULT -1`);
         lines.push(`CREATE TABLE ${table.name} (\n${cols.join(',\n')}\n);`);
         // Create the declared indexes too — harmless for prepare()/decltype, and
         // keeps the type-check DB's shape honest with what the client materializes.
@@ -834,6 +898,18 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
         const source = item !== undefined ? resolveSource(item, refs, ir) : null;
         const sqlName = sqlNames[index] ?? colName;
         const langName = langNames[index] ?? colName;
+        if (item !== undefined && isSyncVersionSource(item, refs)) {
+            if (sqlName === SYNC_VERSION_COLUMN) {
+                throw new TypegenError(file, `${SYNC_VERSION_COLUMN} is stripped from app-facing query rows unless explicitly aliased (for example \`${SYNC_VERSION_COLUMN} AS server_version\`)`);
+            }
+            return {
+                name: sqlName,
+                langName,
+                type: 'integer',
+                nullable: false,
+                fidelity: 'exact',
+            };
+        }
         if (source !== null) {
             // Exact: IR column type + IR nullability. (decltype agrees; we prefer
             // the IR type so blob_ref/crdt/json semantic types survive.)
@@ -867,10 +943,12 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
         // Defensive: our scan and SQLite disagree (shouldn't happen for the subset).
         throw new TypegenError(file, `internal: scanned ${paramNames.length} params (${paramNames.join(', ')}) but SQLite reports ${described.paramsCount}`);
     }
-    const paramLangNames = buildNamingMap(paramNames, naming.naming, file, 'params', naming.targets);
+    const internalParams = new Set(naming.internalParams ?? []);
+    const publicParamLangNames = buildNamingMap(paramNames.filter((name) => !internalParams.has(name)), naming.naming, file, 'params', naming.targets);
+    const langNameByParam = new Map(publicParamLangNames.map((mapping) => [mapping.sqlName, mapping.langName]));
     const commentByName = new Map(commentParams.map((p) => [p.name, p.type]));
-    const params = paramNames.map((paramName, index) => {
-        const langName = paramLangNames[index]?.langName ?? paramName;
+    const params = paramNames.map((paramName) => {
+        const langName = langNameByParam.get(paramName) ?? paramName;
         const commented = commentByName.get(paramName);
         if (commented !== undefined) {
             return { name: paramName, langName, type: commented, source: 'comment' };

package/dist/syql-ast.d.ts

@@ -19,15 +19,8 @@ export type SyqlSemanticTemplateNode = {
 } | {
     readonly kind: 'when';
     readonly controls: readonly string[];
+    readonly explicitPresence: readonly boolean[];
     readonly body: readonly SyqlSemanticTemplateNode[];
-} | {
-    readonly kind: 'scope' | 'cover';
-    readonly bindings: readonly {
-        readonly qualifier: string;
-        readonly column: string;
-        readonly operator: 'equal' | 'in';
-        readonly values: readonly string[];
-    }[];
 };
 export interface SyqlSemanticTemplate {
     readonly mode: SyqlTemplate['tree']['mode'];
@@ -38,10 +31,12 @@ export type SyqlSemanticQueryParameter = {
     readonly name: string;
     readonly optional: boolean;
     readonly type?: SyqlSemanticType;
+    readonly default?: false;
 } | {
-    readonly kind: 'switch';
+    readonly kind: 'range';
     readonly name: string;
-    readonly optional: true;
+    readonly optional: boolean;
+    readonly type?: SyqlSemanticType;
 } | {
     readonly kind: 'group';
     readonly name: string;
@@ -62,8 +57,13 @@ export type SyqlSemanticDeclaration = {
 } | {
     readonly kind: 'query';
     readonly name: string;
+    readonly sync: boolean;
+    readonly syncBy?: {
+        readonly qualifier: string;
+        readonly column: string;
+    };
     readonly parameters: readonly SyqlSemanticQueryParameter[];
-    readonly sql: SyqlSemanticTemplate;
+    readonly statement: SyqlSemanticTemplate;
     readonly sort?: {
         readonly control: string;
         readonly defaultProfile: string;
@@ -72,12 +72,11 @@ export type SyqlSemanticDeclaration = {
             readonly order: SyqlSemanticTemplate;
         }[];
     };
-    readonly page?: {
+    readonly limit?: {
         readonly control: string;
         readonly defaultSize: number;
         readonly maxSize: number;
     };
-    readonly identity?: readonly string[];
 };
 export interface SyqlSemanticFile {
     readonly kind: 'syql-file';

package/dist/syql-ast.js

@@ -10,8 +10,14 @@ function semanticMember(member) {
     return { name: member.name, ...(type === undefined ? {} : { type }) };
 }
 function semanticParameter(parameter) {
-    if (parameter.kind === 'switch') {
-        return { kind: 'switch', name: parameter.name, optional: true };
+    if (parameter.kind === 'range') {
+        const type = semanticType(parameter.type);
+        return {
+            kind: 'range',
+            name: parameter.name,
+            optional: parameter.optional,
+            ...(type === undefined ? {} : { type }),
+        };
     }
     if (parameter.kind === 'group') {
         return {
@@ -27,6 +33,7 @@ function semanticParameter(parameter) {
         name: parameter.name,
         optional: parameter.optional,
         ...(type === undefined ? {} : { type }),
+        ...(parameter.default === undefined ? {} : { default: parameter.default }),
     };
 }
 function semanticRawTokens(tokens) {
@@ -50,18 +57,11 @@ function semanticNode(node) {
         return {
             kind: 'when',
             controls: node.controls,
+            explicitPresence: node.explicitPresence,
             body: semanticNodes(node.body.nodes),
         };
     }
-    return {
-        kind: node.kind,
-        bindings: node.bindings.map((binding) => ({
-            qualifier: binding.column.qualifier,
-            column: binding.column.name,
-            operator: binding.operator,
-            values: binding.values.map((value) => value.name),
-        })),
-    };
+    return undefined;
 }
 function semanticNodes(nodes) {
     return nodes.flatMap((node) => {
@@ -93,8 +93,17 @@ function semanticDeclaration(declaration) {
     return {
         kind: 'query',
         name: declaration.name,
+        sync: declaration.sync,
+        ...(declaration.syncBy === undefined
+            ? {}
+            : {
+                syncBy: {
+                    qualifier: declaration.syncBy.qualifier,
+                    column: declaration.syncBy.column,
+                },
+            }),
         parameters: declaration.parameters.map(semanticParameter),
-        sql: semanticTemplate(declaration.sql.body),
+        statement: semanticTemplate(declaration.statement),
         ...(declaration.sort === undefined
             ? {}
             : {
@@ -107,18 +116,15 @@ function semanticDeclaration(declaration) {
                     })),
                 },
             }),
-        ...(declaration.page === undefined
+        ...(declaration.limit === undefined
             ? {}
             : {
-                page: {
-                    control: declaration.page.control,
-                    defaultSize: declaration.page.defaultSize,
-                    maxSize: declaration.page.maxSize,
+                limit: {
+                    control: declaration.limit.control,
+                    defaultSize: declaration.limit.defaultSize,
+                    maxSize: declaration.limit.maxSize,
                 },
             }),
-        ...(declaration.identity === undefined
-            ? {}
-            : { identity: declaration.identity.fields }),
     };
 }
 /** Return the stable syntax/semantic AST pinned by `spec/syql` fixtures. */

package/dist/syql-lexer.d.ts

@@ -38,3 +38,5 @@ export declare class SyqlFrontendError extends TypegenError {
 export declare function isSyqlTrivia(token: SyqlToken): boolean;
 /** Lex one complete `.syql` source file, including trivia and an EOF token. */
 export declare function lexSyqlSource(file: string, source: string): readonly SyqlToken[];
+/** Lex an isolated SQL/template string without import-path contextual rules. */
+export declare function lexSyqlSqlSource(file: string, source: string): readonly SyqlToken[];