@syncular/typegen 0.2.1 → 0.3.0

package/dist/naming.js

@@ -0,0 +1,240 @@
+/**
+ * The pinned naming-map algorithm (DESIGN-queries.md §5, §12): SQL stays
+ * snake_case; emitters render their language's convention. The IR carries
+ * SQL-truth names plus a derived, collision-checked map — this module is
+ * that derivation.
+ *
+ * `snake_case → camelCase`, pinned:
+ * 1. A leading run of `_` is preserved as a prefix, a trailing run as a
+ *    suffix (they carry intent — privacy markers, disambiguation).
+ * 2. The middle splits on `_`; empty segments from doubled underscores drop.
+ * 3. First segment verbatim; each later segment upper-cases its first
+ *    character, rest verbatim. No acronym awareness (`id_url` → `idUrl`).
+ * 4. Prefix/suffix re-attach. `created_at`→`createdAt`, `col_2`→`col2`,
+ *    `_internal`→`_internal`, `__foo_bar`→`__fooBar`, `row_`→`row_`.
+ *
+ * Collisions and hazards are generate-time ERRORS, not warnings: two SQL
+ * names mapping to one language name, a mapped name hitting a target-language
+ * keyword, or a leading underscore on the Dart target (library-private).
+ */
+import { TypegenError } from './errors.js';
+/** A name the mapper touches: a plain (optionally underscore-framed)
+ * snake_case identifier. Expression-shaped result names (`count(*)`) pass
+ * through unmapped. */
+const MAPPABLE_RE = /^_*[A-Za-z][A-Za-z0-9_]*$/;
+/** The pinned §12 snake→camel conversion. Non-identifier names (computed
+ * result columns like `count(*)`) are returned unchanged. */
+export function snakeToCamel(name) {
+    if (!MAPPABLE_RE.test(name))
+        return name;
+    const lead = /^_*/.exec(name)?.[0] ?? '';
+    const bare = name.slice(lead.length);
+    const trail = /_*$/.exec(bare)?.[0] ?? '';
+    const middle = bare.slice(0, bare.length - trail.length);
+    const segments = middle.split('_').filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return name;
+    const first = segments[0];
+    const rest = segments
+        .slice(1)
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1));
+    return lead + first + rest.join('') + trail;
+}
+/** Reserved words that cannot be a generated field/property name on each
+ * target. Deliberately the core keyword lists — mechanical and predictable
+ * beats exhaustive; an escape hatch (`AS` alias / "preserve") always exists. */
+const TARGET_KEYWORDS = {
+    // TS interface properties/object keys may be quoted, so only names that
+    // would break generated code paths matter; keep the ES reserved core.
+    ts: new Set([
+        'break',
+        'case',
+        'catch',
+        'class',
+        'const',
+        'continue',
+        'debugger',
+        'default',
+        'delete',
+        'do',
+        'else',
+        'enum',
+        'export',
+        'extends',
+        'false',
+        'finally',
+        'for',
+        'function',
+        'if',
+        'import',
+        'in',
+        'instanceof',
+        'new',
+        'null',
+        'return',
+        'super',
+        'switch',
+        'this',
+        'throw',
+        'true',
+        'try',
+        'typeof',
+        'var',
+        'void',
+        'while',
+        'with',
+    ]),
+    swift: new Set([
+        'associatedtype',
+        'class',
+        'deinit',
+        'enum',
+        'extension',
+        'fileprivate',
+        'func',
+        'import',
+        'init',
+        'inout',
+        'internal',
+        'let',
+        'open',
+        'operator',
+        'private',
+        'protocol',
+        'public',
+        'rethrows',
+        'static',
+        'struct',
+        'subscript',
+        'typealias',
+        'var',
+        'break',
+        'case',
+        'continue',
+        'default',
+        'defer',
+        'do',
+        'else',
+        'fallthrough',
+        'for',
+        'guard',
+        'if',
+        'in',
+        'repeat',
+        'return',
+        'switch',
+        'where',
+        'while',
+        'as',
+        'catch',
+        'false',
+        'is',
+        'nil',
+        'super',
+        'self',
+        'throw',
+        'throws',
+        'true',
+        'try',
+    ]),
+    kotlin: new Set([
+        'as',
+        'break',
+        'class',
+        'continue',
+        'do',
+        'else',
+        'false',
+        'for',
+        'fun',
+        'if',
+        'in',
+        'interface',
+        'is',
+        'null',
+        'object',
+        'package',
+        'return',
+        'super',
+        'this',
+        'throw',
+        'true',
+        'try',
+        'typealias',
+        'typeof',
+        'val',
+        'var',
+        'when',
+        'while',
+    ]),
+    dart: new Set([
+        'assert',
+        'break',
+        'case',
+        'catch',
+        'class',
+        'const',
+        'continue',
+        'default',
+        'do',
+        'else',
+        'enum',
+        'extends',
+        'false',
+        'final',
+        'finally',
+        'for',
+        'if',
+        'in',
+        'is',
+        'new',
+        'null',
+        'rethrow',
+        'return',
+        'super',
+        'switch',
+        'this',
+        'throw',
+        'true',
+        'try',
+        'var',
+        'void',
+        'while',
+        'with',
+    ]),
+};
+/**
+ * Map a set of SQL names to language names under `mode`, enforcing the §12
+ * hard errors within the scope (one table's columns / one query's projection
+ * / one query's params). `context` and `scope` name the error location
+ * (e.g. `queries/list.sql`, `table todos`); `targets` are the emitters this
+ * run generates — keyword hazards are only real on targets that exist.
+ */
+export function buildNamingMap(sqlNames, mode, context, scope, targets) {
+    if (mode === 'preserve') {
+        return sqlNames.map((sqlName) => ({ sqlName, langName: sqlName }));
+    }
+    const bySqlName = new Map();
+    const byLangName = new Map();
+    for (const sqlName of sqlNames) {
+        const langName = snakeToCamel(sqlName);
+        const clash = byLangName.get(langName);
+        if (clash !== undefined && clash !== sqlName) {
+            throw new TypegenError(context, `${scope}: ${JSON.stringify(clash)} and ${JSON.stringify(sqlName)} both map to ${JSON.stringify(langName)} under camelCase naming — rename one, alias it in SQL (AS), or set "naming": "preserve" in syncular.json`);
+        }
+        for (const target of targets) {
+            if (TARGET_KEYWORDS[target].has(langName)) {
+                throw new TypegenError(context, `${scope}: ${JSON.stringify(sqlName)} maps to ${JSON.stringify(langName)}, a reserved word on the ${target} target — rename it, alias it in SQL (AS), or set "naming": "preserve" in syncular.json`);
+            }
+            if (target === 'dart' && langName.startsWith('_')) {
+                throw new TypegenError(context, `${scope}: ${JSON.stringify(sqlName)} maps to ${JSON.stringify(langName)} — a leading underscore is library-private on the dart target. Alias it in SQL (AS) or set "naming": "preserve" in syncular.json`);
+            }
+        }
+        bySqlName.set(sqlName, langName);
+        byLangName.set(langName, sqlName);
+    }
+    return sqlNames.map((sqlName) => ({
+        sqlName,
+        langName: bySqlName.get(sqlName),
+    }));
+}

package/dist/query-ir.d.ts

@@ -0,0 +1,14 @@
+/**
+ * QueryIR serialization (DESIGN-queries.md §1): the frontend-agnostic,
+ * deterministic JSON form of analyzed queries. This is the golden-fixture
+ * format — equivalent inputs in any frontend (`.sql` today, `.syql` later)
+ * must produce byte-identical IR JSON, the same trick the wire protocol
+ * uses for the two cores. Fixed key order, 2-space indent, trailing
+ * newline.
+ *
+ * Names are SQL-truth (`name`) plus the collision-checked language name
+ * (`langName`, §5); `sql` is the LOWERED statement (what actually runs).
+ */
+import type { AnalyzedQuery } from './query.js';
+/** Serialize analyzed queries as the deterministic QueryIR JSON document. */
+export declare function serializeQueryIr(queries: readonly AnalyzedQuery[]): string;

package/dist/query-ir.js

@@ -0,0 +1,69 @@
+/** Serialize analyzed queries as the deterministic QueryIR JSON document. */
+export function serializeQueryIr(queries) {
+    const doc = {
+        queryIrVersion: 1,
+        queries: queries.map((query) => ({
+            name: query.name,
+            file: query.file,
+            sourceSql: query.sourceSql,
+            sql: query.sql,
+            positionalSql: query.positionalSql,
+            params: query.params.map((param) => ({
+                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,
+                langName: column.langName,
+                type: column.type,
+                nullable: column.nullable,
+                fidelity: column.fidelity,
+            })),
+            tables: query.tables,
+            // §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.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

@@ -1,36 +1,121 @@
 import type { IrColumnType, IrDocument } from './ir.js';
+import { type NamingMode, type NamingTarget } from './naming.js';
 /** A param type is one of the §2.4 types (the columns params compare to). */
 export type QueryParamType = IrColumnType;
 export interface QueryParam {
+    /** SQL-truth `:name` (as authored). */
     readonly name: string;
+    /** Language-facing name (§5 naming map; equals `name` under "preserve"). */
+    readonly langName: string;
     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). */
     readonly name: string;
+    /** Language-facing name — the RUNTIME result key after §5 projection
+     * lowering (equals `name` under "preserve"). */
+    readonly langName: string;
     readonly type: IrColumnType;
     readonly nullable: boolean;
     /** `exact` = resolved to an IR column (plain ref); `fallback` = a computed
      * expression typed by the documented honest fallback. */
     readonly fidelity: 'exact' | 'fallback';
 }
+/** §7/§8 backend selection: neutralization (default), 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. */
+export interface QueryNamingOptions {
+    readonly naming: NamingMode;
+    /** 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. */
+    readonly backend?: QueryBackend;
+}
 export interface AnalyzedQuery {
     /** camelCase function name (path-derived, or a `-- name:` override). */
     readonly name: string;
     /** Source location for errors, e.g. `billing/list.sql` (or `list.sql#2`
      * for the 2nd statement of a multi-statement file). */
     readonly file: string;
-    /** The SQL as written (named `:params`), trimmed. */
+    /** The SQL as authored (named `:params`), trimmed — pre-lowering. */
+    readonly sourceSql: string;
+    /** The LOWERED SQL (named `:params`): §5 projection aliasing applied, so
+     * runtime result keys are the language-facing names. Equals `sourceSql`
+     * when nothing needed rewriting. */
     readonly sql: string;
-    /** The SQL with `:name` rewritten to positional `?` (wrapper surface). */
+    /** The lowered SQL with `:name` rewritten to positional `?`. */
     readonly positionalSql: string;
     /** Params in first-occurrence (positional) order. */
     readonly params: readonly QueryParam[];
     /** Result columns in SELECT order. */
     readonly columns: readonly QueryColumn[];
-    /** IR tables this query reads (the useSyncQuery `{tables}` set), sorted. */
+    /** IR tables this query reads (the useRawSql `{tables}` set), sorted. */
     readonly tables: readonly string[];
+    /** §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;
+    }[];
 }
 /**
  * Path-relative default name. `billing/invoices/list.sql` → `billingInvoicesList`;
@@ -56,6 +141,17 @@ 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;
+/** 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).
+ *
+ * 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 declare function toPositionalSql(sql: string): string;
 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. */
@@ -77,7 +173,7 @@ export declare function synthesizeDdl(ir: IrDocument): string;
  * top-level `;`). This is the per-statement core; {@link analyzeQueryFile}
  * splits a file and drives it.
  */
-export declare function analyzeStatement(name: string, location: string, statementText: string, ir: IrDocument, db: QueryDb): AnalyzedQuery;
+export declare function analyzeStatement(name: string, location: string, statementText: string, ir: IrDocument, db: QueryDb, naming?: QueryNamingOptions): AnalyzedQuery;
 /**
  * Analyze a whole query FILE: split into statements, resolve each statement's
  * name (path-derived default, or a `-- name:` override), enforce the
@@ -89,8 +185,8 @@ export declare function analyzeStatement(name: string, location: string, stateme
  * - A file with MULTIPLE statements requires `-- name:` on EVERY statement; a
  *   missing one errors, naming the file + the statement's position/first line.
  */
-export declare function analyzeQueryFile(relPath: string, content: string, ir: IrDocument, db: QueryDb): AnalyzedQuery[];
+export declare function analyzeQueryFile(relPath: string, content: string, ir: IrDocument, db: QueryDb, naming?: QueryNamingOptions): AnalyzedQuery[];
 /** 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 declare function analyzeQuery(file: string, raw: string, ir: IrDocument, db: QueryDb): AnalyzedQuery;
+export declare function analyzeQuery(file: string, raw: string, ir: IrDocument, db: QueryDb, naming?: QueryNamingOptions): AnalyzedQuery;