@syncular/typegen 0.6.0 → 0.7.0

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. */
@@ -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`
@@ -797,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.
@@ -881,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.)

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-lowering.js

@@ -3,26 +3,17 @@ import { TypegenError } from './errors.js';
 import { buildNamingMap } from './naming.js';
 import { analyzeStatement, } from './query.js';
 import { lexSyqlSqlSource } from './syql-lexer.js';
+import { syqlRangeEndBind, syqlRangeStartBind } from './syql-semantics.js';
 const DEFAULT_NAMING = {
     naming: 'camel',
     targets: ['ts'],
     backend: 'auto',
 };
 const DEFAULT_ENUMERATION_LIMIT = 256;
-const PAGE_BIND = '__syqlPageSize';
+const LIMIT_BIND = '__syqlLimit';
 function fail(code, query, message) {
     throw new TypegenError(`${query.module.file} (query ${query.declaration.name})`, `${code}: ${message}`);
 }
-function renderDirective(node) {
-    const predicates = node.directive.bindings.map((binding) => {
-        const column = `${binding.column.qualifier}.${binding.column.name}`;
-        const values = binding.values.map((value) => `:${value.name}`);
-        return binding.operator === 'equal'
-            ? `${column} = ${values[0]}`
-            : `${column} in (${values.join(', ')})`;
-    });
-    return `(${predicates.join(' and ')})`;
-}
 function renderTemplate(nodes, conditions, mode) {
     return nodes
         .map((node) => {
@@ -34,9 +25,6 @@ function renderTemplate(nodes, conditions, mode) {
         if (node.kind === 'predicate') {
             return `(${renderTemplate(node.body, conditions, mode)})`;
         }
-        if (node.kind === 'scope' || node.kind === 'cover') {
-            return renderDirective(node);
-        }
         if (node.kind !== 'when') {
             throw new Error('revision-1 lowering found an unknown logical node');
         }
@@ -75,7 +63,7 @@ function outerLimitOffset(sql, file) {
     }
     return sql.length;
 }
-function composeControls(sql, file, sortSql, page) {
+function composeControls(sql, file, sortSql, limit) {
     let out = sql.trim();
     if (sortSql !== undefined) {
         const insertion = outerLimitOffset(out, file);
@@ -83,10 +71,10 @@ function composeControls(sql, file, sortSql, page) {
             .slice(insertion)
             .trimStart()}`.trim();
     }
-    if (page !== undefined) {
+    if (limit !== undefined) {
         // `coalesce` gives the generator's metadata-only execution a valid value;
         // runtimes still validate and bind the effective size before execution.
-        out = `${out.trimEnd()} limit min(coalesce(:${PAGE_BIND}, ${page.defaultSize}), ${page.maxSize})`;
+        out = `${out.trimEnd()} limit min(coalesce(:${LIMIT_BIND}, ${limit.defaultSize}), ${limit.maxSize})`;
     }
     return out;
 }
@@ -101,7 +89,7 @@ function distinctBindNames(sql, file) {
     }
     return names;
 }
-function headersFor(names, valueOwners, conditionBinds, page, query) {
+function headersFor(names, valueOwners, conditionBinds, limit, query) {
     return names
         .map((name) => {
         const value = valueOwners.get(name);
@@ -109,13 +97,13 @@ function headersFor(names, valueOwners, conditionBinds, page, query) {
             return `-- param :${name} ${value.type}`;
         if (conditionBinds.has(name))
             return `-- param :${name} boolean`;
-        if (name === PAGE_BIND && page !== undefined)
+        if (name === LIMIT_BIND && limit !== undefined)
             return `-- param :${name} integer`;
         return fail('SYQL7002_INTERNAL_LOWERING', query, `generated SQL contains unresolved bind :${name}`);
     })
         .join('\n');
 }
-function planBind(name, valueOwners, conditionBinds, conditions, page, query) {
+function planBind(name, valueOwners, conditionBinds, conditions, limit, query) {
     const value = valueOwners.get(name);
     if (value?.kind === 'value') {
         return { kind: 'value', name, type: value.type, input: value.input };
@@ -139,12 +127,12 @@ function planBind(name, valueOwners, conditionBinds, conditions, page, query) {
             controls: conditions[condition].controls,
         };
     }
-    if (name === PAGE_BIND && page !== undefined) {
+    if (name === LIMIT_BIND && limit !== undefined) {
         return {
-            kind: 'page',
+            kind: 'limit',
             name,
             type: 'integer',
-            input: page.control,
+            input: limit.control,
         };
     }
     return fail('SYQL7002_INTERNAL_LOWERING', query, `cannot describe generated bind :${name}`);
@@ -155,17 +143,34 @@ function publicInputs(validated, naming) {
     const publicNames = [
         ...declaration.parameters.map((parameter) => parameter.name),
         ...(declaration.sort === undefined ? [] : [declaration.sort.control]),
-        ...(declaration.page === undefined ? [] : [declaration.page.control]),
+        ...(declaration.limit === undefined ? [] : [declaration.limit.control]),
     ];
     const mapped = new Map(buildNamingMap(publicNames, naming.naming, query.module.file, `query ${declaration.name} public inputs`, naming.targets).map((entry) => [entry.sqlName, entry.langName]));
     const result = declaration.parameters.map((parameter) => {
         const langName = mapped.get(parameter.name);
-        if (parameter.kind === 'switch') {
+        if (parameter.kind === 'range') {
+            const type = validated.bindTypes.get(syqlRangeStartBind(parameter.name));
+            if (type === undefined) {
+                return fail('SYQL7002_INTERNAL_LOWERING', query, `range ${parameter.name} has no resolved element type`);
+            }
             return {
-                kind: 'switch',
+                kind: 'group',
                 name: parameter.name,
                 langName,
-                default: false,
+                members: [
+                    {
+                        name: 'start',
+                        langName: 'start',
+                        type: type.base,
+                        nullable: type.nullable,
+                    },
+                    {
+                        name: 'end',
+                        langName: 'end',
+                        type: type.base,
+                        nullable: type.nullable,
+                    },
+                ],
             };
         }
         if (parameter.kind === 'group') {
@@ -199,7 +204,10 @@ function publicInputs(validated, naming) {
             langName,
             type: type.base,
             nullable: type.nullable,
-            required: !parameter.optional,
+            required: !parameter.optional && parameter.default === undefined,
+            ...(parameter.default === undefined
+                ? {}
+                : { default: parameter.default }),
         };
     });
     if (validated.sort !== undefined) {
@@ -215,13 +223,13 @@ function publicInputs(validated, naming) {
             })),
         });
     }
-    if (validated.page !== undefined) {
+    if (validated.limit !== undefined) {
         result.push({
-            kind: 'page',
-            name: validated.page.control,
-            langName: mapped.get(validated.page.control),
-            defaultSize: validated.page.defaultSize,
-            maxSize: validated.page.maxSize,
+            kind: 'limit',
+            name: validated.limit.control,
+            langName: mapped.get(validated.limit.control),
+            defaultSize: validated.limit.defaultSize,
+            maxSize: validated.limit.maxSize,
         });
     }
     return result;
@@ -229,9 +237,23 @@ function publicInputs(validated, naming) {
 function valueOwners(validated) {
     const owners = new Map();
     for (const parameter of validated.logical.declaration.parameters) {
-        if (parameter.kind === 'switch')
-            continue;
-        if (parameter.kind === 'group') {
+        if (parameter.kind === 'range') {
+            for (const [name, member] of [
+                [syqlRangeStartBind(parameter.name), 'start'],
+                [syqlRangeEndBind(parameter.name), 'end'],
+            ]) {
+                const type = validated.bindTypes.get(name);
+                if (type === undefined)
+                    continue;
+                owners.set(name, {
+                    kind: 'group-member',
+                    input: parameter.name,
+                    member,
+                    type: type.base,
+                });
+            }
+        }
+        else if (parameter.kind === 'group') {
             for (const member of parameter.members) {
                 const type = validated.bindTypes.get(member.name);
                 if (type === undefined)
@@ -267,13 +289,14 @@ function lowerStatement(validated, ir, db, naming, sql, sortProfile, activationM
     const query = validated.logical;
     const location = `${query.module.file} (query ${query.declaration.name}, generated)`;
     const names = distinctBindNames(sql, location);
-    const headers = headersFor(names, owners, conditionBinds, validated.page, query);
+    const headers = headersFor(names, owners, conditionBinds, validated.limit, query);
     const candidate = headers.length === 0 ? sql : `${headers}\n${sql}`;
     const analyzed = analyzeStatement(query.declaration.name, location, candidate, ir, db, {
         ...naming,
         internalParams: [
             ...conditionBinds.keys(),
-            ...(validated.page === undefined ? [] : [PAGE_BIND]),
+            ...(validated.limit === undefined ? [] : [LIMIT_BIND]),
+            ...[...owners.keys()].filter((name) => name.startsWith('__syqlRange')),
         ],
     });
     const namedSql = headers.length === 0
@@ -286,7 +309,7 @@ function lowerStatement(validated, ir, db, naming, sql, sortProfile, activationM
             ...(activationMask === undefined ? {} : { activationMask }),
             sql: namedSql,
             positionalSql: analyzed.positionalSql,
-            binds: bindNames.map((name) => planBind(name, owners, conditionBinds, query.conditions, validated.page, query)),
+            binds: bindNames.map((name) => planBind(name, owners, conditionBinds, query.conditions, validated.limit, query)),
         },
         analysis: { ...analyzed, sourceSql: namedSql, sql: namedSql },
     };
@@ -315,7 +338,7 @@ export function lowerSyqlQuery(validated, ir, db, naming = DEFAULT_NAMING, optio
         const body = renderTemplate(logical.template, conditions, {
             kind: 'neutralized',
         });
-        const sql = composeControls(body, logical.module.file, profile.sql, validated.page);
+        const sql = composeControls(body, logical.module.file, profile.sql, validated.limit);
         const lowered = lowerStatement(validated, ir, db, naming, sql, profile.name, undefined, owners, conditionBinds);
         neutralStatements.push(lowered.statement);
         if (neutralDefault === undefined ||
@@ -347,7 +370,7 @@ export function lowerSyqlQuery(validated, ir, db, naming = DEFAULT_NAMING, optio
                     kind: 'enumerated',
                     active,
                 });
-                const sql = composeControls(body, logical.module.file, profile.sql, validated.page);
+                const sql = composeControls(body, logical.module.file, profile.sql, validated.limit);
                 const lowered = lowerStatement(validated, ir, db, naming, sql, profile.name, mask, owners, new Map());
                 statements.push(lowered.statement);
                 if (mask === 0 &&

package/dist/syql-parser.d.ts

@@ -12,13 +12,17 @@ export interface SyqlValueParameter {
     readonly name: string;
     readonly optional: boolean;
     readonly type?: SyqlValueType;
+    /** A source-level default. Revision 1 currently permits only `bool = false`. */
+    readonly default?: false;
     readonly span: SyqlSourceSpan;
     readonly nameSpan: SyqlSourceSpan;
 }
-export interface SyqlSwitchParameter {
-    readonly kind: 'switch';
+export interface SyqlRangeParameter {
+    readonly kind: 'range';
     readonly name: string;
-    readonly optional: true;
+    readonly optional: boolean;
+    /** Element type, inferred from the left side of BETWEEN when omitted. */
+    readonly type?: SyqlValueType;
     readonly span: SyqlSourceSpan;
     readonly nameSpan: SyqlSourceSpan;
 }
@@ -36,7 +40,7 @@ export interface SyqlGroupParameter {
     readonly span: SyqlSourceSpan;
     readonly nameSpan: SyqlSourceSpan;
 }
-export type SyqlQueryParameter = SyqlValueParameter | SyqlSwitchParameter | SyqlGroupParameter;
+export type SyqlQueryParameter = SyqlValueParameter | SyqlRangeParameter | SyqlGroupParameter;
 export interface SyqlPredicateParameter {
     readonly name: string;
     readonly type?: SyqlValueType;
@@ -72,11 +76,6 @@ export interface SyqlPredicateDeclaration {
     readonly span: SyqlSourceSpan;
     readonly nameSpan: SyqlSourceSpan;
 }
-export interface SyqlSqlSection {
-    readonly kind: 'sql';
-    readonly body: SyqlTemplate;
-    readonly span: SyqlSourceSpan;
-}
 export interface SyqlSortProfile {
     readonly name: string;
     readonly order: SyqlTemplate;
@@ -91,27 +90,29 @@ export interface SyqlSortSection {
     readonly span: SyqlSourceSpan;
     readonly controlSpan: SyqlSourceSpan;
 }
-export interface SyqlPageDeclaration {
-    readonly kind: 'page';
+export interface SyqlLimitDeclaration {
+    readonly kind: 'limit';
     readonly control: string;
     readonly defaultSize: number;
     readonly maxSize: number;
     readonly span: SyqlSourceSpan;
     readonly controlSpan: SyqlSourceSpan;
 }
-export interface SyqlIdentityDeclaration {
-    readonly kind: 'identity';
-    readonly fields: readonly string[];
+export interface SyqlSyncDimension {
+    readonly qualifier: string;
+    readonly column: string;
     readonly span: SyqlSourceSpan;
 }
 export interface SyqlQueryDeclaration {
     readonly kind: 'query';
     readonly name: string;
+    readonly sync: boolean;
+    readonly syncBy?: SyqlSyncDimension;
     readonly parameters: readonly SyqlQueryParameter[];
-    readonly sql: SyqlSqlSection;
+    /** The SQL-shaped statement body, excluding its terminating semicolon. */
+    readonly statement: SyqlTemplate;
     readonly sort?: SyqlSortSection;
-    readonly page?: SyqlPageDeclaration;
-    readonly identity?: SyqlIdentityDeclaration;
+    readonly limit?: SyqlLimitDeclaration;
     readonly span: SyqlSourceSpan;
     readonly nameSpan: SyqlSourceSpan;
 }
@@ -127,6 +128,6 @@ export interface SyqlSyntaxFile {
     readonly queries: readonly SyqlQueryDeclaration[];
     readonly span: SyqlSourceSpan;
 }
-export type SyqlParseErrorCode = 'SYQL2001_EXPECTED_TOKEN' | 'SYQL2002_INVALID_NAME' | 'SYQL2003_RESERVED_NAME' | 'SYQL2004_DUPLICATE_NAME' | 'SYQL2005_INVALID_IMPORT' | 'SYQL2006_EMPTY_TEMPLATE' | 'SYQL2007_FORBIDDEN_SEMICOLON' | 'SYQL2008_INVALID_MEMBER' | 'SYQL2009_INVALID_INTEGER' | 'SYQL2010_INVALID_PAGE_RANGE' | 'SYQL2011_INVALID_PARAMETER';
+export type SyqlParseErrorCode = 'SYQL2001_EXPECTED_TOKEN' | 'SYQL2002_INVALID_NAME' | 'SYQL2003_RESERVED_NAME' | 'SYQL2004_DUPLICATE_NAME' | 'SYQL2005_INVALID_IMPORT' | 'SYQL2006_EMPTY_TEMPLATE' | 'SYQL2007_FORBIDDEN_SEMICOLON' | 'SYQL2008_INVALID_MEMBER' | 'SYQL2009_INVALID_INTEGER' | 'SYQL2010_INVALID_PAGE_RANGE' | 'SYQL2011_INVALID_PARAMETER' | 'SYQL2012_INVALID_QUERY_BODY';
 /** Parse one `.syql` file using the destructive revision-1 grammar. */
 export declare function parseSyqlSyntaxFile(file: string, source: string): SyqlSyntaxFile;