@syncular/typegen 0.2.0 → 0.3.0

package/dist/query.js

@@ -48,7 +48,7 @@
  * error listing the fix. bun:sqlite can't name params, so we parse `:name`
  * tokens from the SQL ourselves (first-occurrence order = positional order).
  *
- * ## The tables set (for useSyncQuery `{tables}` — exact invalidation)
+ * ## The tables set (for useRawSql `{tables}` — exact invalidation)
  *
  * bun:sqlite exposes no authorizer and no statement table-list; EXPLAIN
  * opcodes are fragile. The honest mechanism: the FROM/JOIN table set we
@@ -61,6 +61,8 @@
  * for the query shapes this tier supports.
  */
 import { TypegenError } from './errors.js';
+import { lowerProjection, mainVerbAfterWith } from './lower.js';
+import { buildNamingMap } from './naming.js';
 /** The SQL decltype keyword → §2.4 type map (mirrors sql.ts TYPE_MAP so a
  * plain column ref's decltype resolves to the exact IR type). */
 const DECLTYPE_MAP = {
@@ -82,6 +84,7 @@ const DECLTYPE_MAP = {
     BLOBREF: 'blob_ref',
     CRDT: 'crdt',
 };
+const DEFAULT_NAMING = { naming: 'camel', targets: ['ts'] };
 // -- path → name --------------------------------------------------------------
 /** A single kebab-case path segment (folder) or filename stem. */
 const KEBAB_SEGMENT_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -328,11 +331,17 @@ function scanParamNames(sql) {
     }
     return seen;
 }
-/** Rewrite `:name` → positional `?` (repeats included) AND strip comments +
- * collapse whitespace, producing a clean single-line SQL string suitable for
+/** 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
- * verbatim (their inner whitespace is not collapsed). */
-function toPositionalSql(sql) {
+ * verbatim (their inner whitespace is not collapsed).
+ *
+ * When every param occurs exactly once, plain `?` is emitted. When ANY
+ * param repeats (the §7 neutralization guards mention a param in the guard
+ * AND the predicate), the WHOLE statement uses SQLite's numbered `?N`
+ * form — one bound value per DISTINCT param, reuse resolved by SQLite —
+ * so the generated bind array stays one-entry-per-param. */
+export function toPositionalSql(sql) {
     const tokens = [];
     let i = 0;
     while (i < sql.length) {
@@ -379,7 +388,7 @@ function toPositionalSql(sql) {
             while (end < sql.length && /[A-Za-z0-9_]/.test(sql[end])) {
                 end += 1;
             }
-            tokens.push('?');
+            tokens.push({ param: sql.slice(i + 1, end) });
             i = end;
         }
         else if (/\s/.test(ch)) {
@@ -391,8 +400,25 @@ function toPositionalSql(sql) {
             i += 1;
         }
     }
+    const order = [];
+    let repeats = false;
+    for (const token of tokens) {
+        if (typeof token === 'string')
+            continue;
+        if (order.includes(token.param))
+            repeats = true;
+        else
+            order.push(token.param);
+    }
+    const rendered = tokens
+        .map((token) => {
+        if (typeof token === 'string')
+            return token;
+        return repeats ? `?${order.indexOf(token.param) + 1}` : '?';
+    })
+        .join('');
     // Collapse runs of the whitespace placeholders; trim.
-    return tokens.join('').replace(/\s+/g, ' ').trim();
+    return rendered.replace(/\s+/g, ' ').trim();
 }
 const IDENT = '[A-Za-z_][A-Za-z0-9_]*';
 // `FROM tbl [AS] a`, `JOIN tbl [AS] a`. We only need the referenced base
@@ -539,6 +565,28 @@ function inferParamType(paramName, sql, refs, ir) {
         if (t !== null)
             return t;
     }
+    // `col BETWEEN :name AND …` / `col BETWEEN … AND :name` — both endpoints
+    // take the column's type (the §4 from+to group shape).
+    const btwLeft = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+:${paramName}\\b`, 'i');
+    const btwLeftM = btwLeft.exec(cleaned);
+    if (btwLeftM !== null) {
+        const t = lookup(btwLeftM[1], btwLeftM[2]);
+        if (t !== null)
+            return t;
+    }
+    const btwRight = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+\\S+\\s+AND\\s+:${paramName}\\b`, 'i');
+    const btwRightM = btwRight.exec(cleaned);
+    if (btwRightM !== null) {
+        const t = lookup(btwRightM[1], btwRightM[2]);
+        if (t !== null)
+            return t;
+    }
+    // `… LIKE <expr mentioning :name>` — a LIKE operand is TEXT, even inside
+    // a concatenation (`title like '%' || :q || '%'`, the search-fragment
+    // shape).
+    const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'i');
+    if (like.test(cleaned))
+        return 'string';
     return null;
 }
 // -- fallback column typing (computed expressions) ----------------------------
@@ -591,45 +639,79 @@ export function synthesizeDdl(ir) {
  * top-level `;`). This is the per-statement core; {@link analyzeQueryFile}
  * splits a file and drives it.
  */
-export function analyzeStatement(name, location, statementText, ir, db) {
+export function analyzeStatement(name, location, statementText, ir, db, naming = DEFAULT_NAMING) {
     const file = location;
     const commentParams = parseCommentParams(file, statementText);
-    const sql = statementText.trim();
-    if (sql.length === 0) {
+    const sourceSql = statementText.trim();
+    if (sourceSql.length === 0) {
         throw new TypegenError(file, 'query file is empty');
     }
-    // SELECT-only (the read tier). Reject the first keyword loudly otherwise.
+    // SELECT-only (the read tier). A `WITH` is allowed when its main statement
+    // is a SELECT (SQLite also allows WITH … INSERT/UPDATE/DELETE — writes).
     const firstKeyword = /^\s*([A-Za-z]+)/.exec(stripCommentsAndStrings(statementText).trimStart())?.[1];
-    if (firstKeyword === undefined || firstKeyword.toUpperCase() !== 'SELECT') {
-        throw new TypegenError(file, `named queries are SELECT-only (the read tier); found ${JSON.stringify(firstKeyword ?? '')}. Writes go through mutate() (SPEC §7.1).`);
-    }
-    // Let SQLite validate + describe the query. Any bad reference throws here
-    // with SQLite's own message (which names the offending table/column).
-    let described;
-    try {
-        described = db.analyze(sql);
+    const upperKeyword = firstKeyword?.toUpperCase();
+    if (upperKeyword === 'WITH') {
+        const main = mainVerbAfterWith(stripCommentsAndStrings(statementText));
+        if (main !== 'SELECT') {
+            throw new TypegenError(file, `named queries are SELECT-only (the read tier); this WITH statement's main verb is ${JSON.stringify(main ?? '')}. Writes go through mutate() (SPEC §7.1).`);
+        }
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new TypegenError(file, `SQL rejected by SQLite: ${message}`);
+    else if (upperKeyword !== 'SELECT') {
+        throw new TypegenError(file, `named queries are SELECT-only (the read tier); found ${JSON.stringify(firstKeyword ?? '')}. Writes go through mutate() (SPEC §7.1).`);
     }
-    const refs = scanTableRefs(sql, ir);
+    // Let SQLite validate + describe the AUTHORED query first. Any bad
+    // reference throws here with SQLite's own message.
+    const analyze = (candidate) => {
+        try {
+            return db.analyze(candidate);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new TypegenError(file, `SQL rejected by SQLite: ${message}`);
+        }
+    };
+    let described = analyze(sourceSql);
+    const refs = scanTableRefs(sourceSql, ir);
     const tableSet = new Set(refs.map((r) => r.table));
     const tables = [...tableSet].sort();
     if (tables.length === 0) {
         throw new TypegenError(file, 'query reads no synced table — every named query must read at least one IR table (for exact invalidation)');
     }
-    // Columns: pair bun's column names + decltypes with our source resolution.
+    // §5 lowering: rewrite the projection so runtime result keys are the
+    // language-facing names ("camel"); a no-op pass-through under "preserve".
+    let sql = sourceSql;
+    let sqlNames = described.columnNames;
+    let langNames = described.columnNames;
+    if (naming.naming === 'camel') {
+        const lowered = lowerProjection(sourceSql, refs, ir, file, (candidate) => analyze(candidate).columnNames, (names) => buildNamingMap(names, 'camel', file, 'projection', naming.targets).map((m) => m.langName));
+        sqlNames = lowered.sqlNames;
+        langNames = lowered.langNames;
+        if (lowered.changed) {
+            sql = lowered.sql;
+            described = analyze(sql);
+            // Defensive: the rewritten projection's runtime keys must BE the
+            // language names — this is the whole point of the lowering.
+            if (described.columnNames.length !== langNames.length ||
+                described.columnNames.some((n, i) => n !== langNames[i])) {
+                throw new TypegenError(file, `internal: lowered projection keys [${described.columnNames.join(', ')}] do not match the naming map [${langNames.join(', ')}]`);
+            }
+        }
+    }
+    // Columns: pair bun's column names + decltypes with our source resolution
+    // (against the LOWERED sql — aliased plain refs still resolve exactly).
     const items = splitSelectList(sql);
     const columns = described.columnNames.map((colName, index) => {
         const decl = described.declaredTypes[index];
         const item = items?.[index];
         const source = item !== undefined ? resolveSource(item, refs, ir) : null;
+        const sqlName = sqlNames[index] ?? colName;
+        const langName = langNames[index] ?? colName;
         if (source !== null) {
             // Exact: IR column type + IR nullability. (decltype agrees; we prefer
             // the IR type so blob_ref/crdt/json semantic types survive.)
             return {
-                name: colName,
+                name: sqlName,
+                langName,
                 type: source.column.type,
                 nullable: source.column.nullable,
                 fidelity: 'exact',
@@ -640,24 +722,33 @@ export function analyzeStatement(name, location, statementText, ir, db) {
             ? DECLTYPE_MAP[decl.toUpperCase()]
             : undefined;
         const type = mapped ?? (item !== undefined ? fallbackColumnType(item.expr) : 'string');
-        return { name: colName, type, nullable: true, fidelity: 'fallback' };
+        return {
+            name: sqlName,
+            langName,
+            type,
+            nullable: true,
+            fidelity: 'fallback',
+        };
     });
     // Params: names from the text (positional order), types from inference or
-    // the `-- param` comment; every param must resolve.
+    // the `-- param` comment; every param must resolve. Param langNames go
+    // through the same §12 map (authored camelCase params are identity).
     const paramNames = scanParamNames(sql);
     if (paramNames.length !== described.paramsCount) {
         // 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 commentByName = new Map(commentParams.map((p) => [p.name, p.type]));
-    const params = paramNames.map((paramName) => {
+    const params = paramNames.map((paramName, index) => {
+        const langName = paramLangNames[index]?.langName ?? paramName;
         const commented = commentByName.get(paramName);
         if (commented !== undefined) {
-            return { name: paramName, type: commented, source: 'comment' };
+            return { name: paramName, langName, type: commented, source: 'comment' };
         }
         const inferred = inferParamType(paramName, sql, refs, ir);
         if (inferred !== null) {
-            return { name: paramName, type: inferred, source: 'inferred' };
+            return { name: paramName, langName, type: inferred, source: 'inferred' };
         }
         throw new TypegenError(file, `cannot infer a type for param :${paramName} (it is not compared to a plain column). Add a header comment: \`-- param :${paramName} <type>\` (one of ${[...PARAM_TYPES].join(', ')}).`);
     });
@@ -670,6 +761,7 @@ export function analyzeStatement(name, location, statementText, ir, db) {
     return {
         name,
         file,
+        sourceSql,
         sql,
         positionalSql: toPositionalSql(sql),
         params,
@@ -688,7 +780,7 @@ export function analyzeStatement(name, location, statementText, ir, db) {
  * - A file with MULTIPLE statements requires `-- name:` on EVERY statement; a
  *   missing one errors, naming the file + the statement's position/first line.
  */
-export function analyzeQueryFile(relPath, content, ir, db) {
+export function analyzeQueryFile(relPath, content, ir, db, naming = DEFAULT_NAMING) {
     const statements = splitStatements(content);
     if (statements.length === 0) {
         throw new TypegenError(relPath, 'query file is empty');
@@ -703,17 +795,17 @@ export function analyzeQueryFile(relPath, content, ir, db) {
             throw new TypegenError(location, `${relPath} holds ${statements.length} statements, so each requires a \`-- name: <camelCase>\` marker; statement #${index + 1} (line ${stmt.startLine}: ${JSON.stringify(firstLine.slice(0, 60))}) has none`);
         }
         const name = override ?? defaultName;
-        return analyzeStatement(name, location, stmt.text, ir, db);
+        return analyzeStatement(name, location, stmt.text, ir, db, naming);
     });
 }
 /** Back-compat single-statement analyzer: resolve the name from the file path
  * (or a `-- name:` override) and analyze. Rejects a `;`-separated file loudly
  * — use {@link analyzeQueryFile} for the multi-statement contract. */
-export function analyzeQuery(file, raw, ir, db) {
+export function analyzeQuery(file, raw, ir, db, naming = DEFAULT_NAMING) {
     const statements = splitStatements(raw);
     if (statements.length > 1) {
         throw new TypegenError(file, 'a query file holds exactly one SELECT statement here (found a `;` separating statements) — use analyzeQueryFile for multi-statement files');
     }
-    const results = analyzeQueryFile(file, raw, ir, db);
+    const results = analyzeQueryFile(file, raw, ir, db, naming);
     return results[0];
 }

package/dist/syql.d.ts

@@ -0,0 +1,83 @@
+import type { IrDocument } from './ir.js';
+import { type AnalyzedQuery, type QueryDb, type QueryNamingOptions } from './query.js';
+export interface SyqlParamDecl {
+    readonly name: string;
+    readonly optional: boolean;
+    /** `from+to?` pairing: both params share the group key. */
+    readonly group?: string;
+    /** `name?: flag` — a boolean guard param (§3). */
+    readonly flag: boolean;
+}
+export interface SyqlOrderBy {
+    readonly allowed: readonly string[];
+    readonly defaultColumn: string;
+    readonly defaultDir: 'asc' | 'desc';
+}
+export interface SyqlLimit {
+    readonly max?: number;
+    readonly default?: number;
+}
+export interface SyqlFragmentDecl {
+    readonly name: string;
+    readonly params: readonly SyqlParamDecl[];
+    /** The predicate body (raw SQL expression text). */
+    readonly body: string;
+    /** Source offset of the `fragment` keyword (editor tooling). */
+    readonly offset: number;
+}
+export interface SyqlQueryDecl {
+    readonly name: string;
+    readonly params: readonly SyqlParamDecl[];
+    readonly orderBy?: SyqlOrderBy;
+    readonly limit?: SyqlLimit;
+    /** §7 opt-in: lower to 2^N enumerated statements (perfect index use)
+     * instead of one neutralized statement. API-invisible. */
+    readonly variants?: boolean;
+    /** The SQL-shaped body (may contain @fragment refs and if-guards). */
+    readonly body: string;
+    /** Source offset of the `query` keyword (editor tooling). */
+    readonly offset: number;
+}
+export interface SyqlFile {
+    readonly fragments: readonly SyqlFragmentDecl[];
+    readonly queries: readonly SyqlQueryDecl[];
+}
+/** Parse one `.syql` file into its declarations (no lowering yet). */
+export declare function parseSyqlFile(file: string, content: string): SyqlFile;
+interface ParamInfo {
+    optional: boolean;
+    group?: string;
+    flag: boolean;
+    declared: boolean;
+}
+/** One top-level WHERE conjunct after guard analysis: `governing` is the
+ * set of OPTIONAL param names gating it (empty = required conjunct). */
+export interface LoweredConjunct {
+    readonly pred: string;
+    readonly governing: readonly string[];
+}
+export interface LoweredSyqlQuery {
+    /** The lowered single SQL statement (named params, no knob tails). */
+    readonly sql: string;
+    /** Params discovered/declared, in signature-then-first-use order. */
+    readonly paramInfo: ReadonlyMap<string, ParamInfo>;
+    /** Statement text before the `where` keyword (whole statement when there
+     * is no WHERE). */
+    readonly prefix: string;
+    /** Statement text after the WHERE clause (may be empty). */
+    readonly suffix: string;
+    /** The structured conjuncts (empty when there is no WHERE) — the §7
+     * variant backend re-assembles per provided-combination from these. */
+    readonly conjuncts: readonly LoweredConjunct[];
+}
+/**
+ * Lower one query body: splice fragments, auto-guard optional conjuncts,
+ * expand `if` guards, enforce B1. Returns plain SQL (knob tails are the
+ * caller's job).
+ */
+export declare function lowerSyqlBody(decl: SyqlQueryDecl, fragments: ReadonlyMap<string, SyqlFragmentDecl>, location: string): LoweredSyqlQuery;
+/** Analyze every query of one `.syql` file into `AnalyzedQuery` units —
+ * byte-compatible with the `.sql` frontend's output (§1: nothing below the
+ * IR knows the frontend). */
+export declare function analyzeSyqlFile(relPath: string, content: string, ir: IrDocument, db: QueryDb, naming?: QueryNamingOptions): AnalyzedQuery[];
+export {};