@syncular/typegen 0.1.2 → 0.2.0

package/dist/query.d.ts

@@ -0,0 +1,96 @@
+import type { IrColumnType, IrDocument } from './ir.js';
+/** A param type is one of the §2.4 types (the columns params compare to). */
+export type QueryParamType = IrColumnType;
+export interface QueryParam {
+    readonly name: string;
+    readonly type: QueryParamType;
+    /** How the type was resolved — for the docs/tests, not emitted. */
+    readonly source: 'inferred' | 'comment';
+}
+export interface QueryColumn {
+    readonly name: 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';
+}
+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. */
+    readonly sql: string;
+    /** The SQL with `:name` rewritten to positional `?` (wrapper surface). */
+    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. */
+    readonly tables: readonly string[];
+}
+/**
+ * Path-relative default name. `billing/invoices/list.sql` → `billingInvoicesList`;
+ * a flat `list-todos.sql` → `listTodos` (unchanged). Every folder segment AND
+ * the filename stem must be lowercase kebab-case — rejects loudly, naming the
+ * offending segment, so a stray `List.sql` or `Billing/` fails at generate time.
+ */
+export declare function queryNameFromPath(relPath: string): string;
+/** Back-compat flat-file helper: `list-todos.sql` → `listTodos`. Rejects a
+ * path with folders (use {@link queryNameFromPath} for nested queries). */
+export declare function queryNameFromFile(file: string): string;
+/** Validate a `-- name:` override is a camelCase identifier (loud otherwise). */
+export declare function validateOverrideName(name: string, location: string): string;
+export interface SplitStatement {
+    /** The raw statement text (leading comment block + SQL), as written. */
+    readonly text: string;
+    /** 1-based line number of the statement's first character in the file. */
+    readonly startLine: number;
+}
+/** Split file content into statements on top-level `;` (string/comment-aware).
+ * Blank/comment-only tails are dropped; each statement keeps its own leading
+ * comment block (everything between the previous `;` and this SQL). */
+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;
+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. */
+    analyze(sql: string): {
+        columnNames: readonly string[];
+        declaredTypes: readonly (string | null)[];
+        paramsCount: number;
+    };
+}
+/** Synthesize the schema DDL from the IR (the reverse of the migration
+ * parser): a `CREATE TABLE` per IR table with each column's declared SQLite
+ * type + NOT NULL, so `prepare()` validates references and decltype resolves.
+ * This is exported so the generator can build one in-memory DB per run. */
+export declare function synthesizeDdl(ir: IrDocument): string;
+/**
+ * Analyze ONE already-split statement against the IR + a prepared-DDL DB. The
+ * name is pre-resolved (path-derived or a `-- name:` override) by the caller;
+ * `statementText` is a single statement's leading comment block + SQL (no
+ * 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;
+/**
+ * Analyze a whole query FILE: split into statements, resolve each statement's
+ * name (path-derived default, or a `-- name:` override), enforce the
+ * multi-statement contract, and analyze each. `relPath` is the file's path
+ * relative to the queries root (drives the default name + error locations).
+ *
+ * Rules (agreed 2026-07-04):
+ * - A file with ONE statement may omit `-- name:` → the path-derived default.
+ * - 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[];
+/** 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;