@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/studio/user-error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * UserError - a mistake the person at the keyboard can fix (a typo in a
+ * connection string, an empty table selection, a folder that already holds
+ * another app), as opposed to a defect in Studio.
+ *
+ * The CLI prints these plainly and stops. Everything else is treated as a crash
+ * and gets a sanitized bug report plus a prefilled issue link, so ordinary
+ * fat-fingering never looks like something worth reporting.
+ *
+ * `isUserError` is duck-typed rather than an `instanceof` check: the class can
+ * cross a bundle boundary (browser ESM source vs. the Node build), and a
+ * mis-detected user error would send someone to file an issue about their own
+ * typo.
+ */
+export declare class UserError extends Error {
+    /** Marker read by `isUserError`; survives bundling and subclassing. */
+    readonly isUserError = true;
+    /** Optional follow-up: what to try instead. */
+    readonly hint?: string;
+    constructor(message: string, hint?: string);
+}
+/** True for anything thrown as a `UserError`, across module instances. */
+export declare function isUserError(err: unknown): err is UserError;

package/{src/studio/user-error.ts → dist/studio/user-error.js}

@@ -13,19 +13,16 @@
  * typo.
  */
 export class UserError extends Error {
-  /** Marker read by `isUserError`; survives bundling and subclassing. */
-  readonly isUserError = true
-  /** Optional follow-up: what to try instead. */
-  readonly hint?: string
-
-  constructor(message: string, hint?: string) {
-    super(message)
-    this.name = 'UserError'
-    if (hint !== undefined) this.hint = hint
-  }
+    constructor(message, hint) {
+        super(message);
+        /** Marker read by `isUserError`; survives bundling and subclassing. */
+        this.isUserError = true;
+        this.name = 'UserError';
+        if (hint !== undefined)
+            this.hint = hint;
+    }
 }
-
 /** True for anything thrown as a `UserError`, across module instances. */
-export function isUserError(err: unknown): err is UserError {
-  return !!err && typeof err === 'object' && (err as { isUserError?: unknown }).isUserError === true
+export function isUserError(err) {
+    return !!err && typeof err === 'object' && err.isUserError === true;
 }

package/dist/studio/verify.d.ts

@@ -0,0 +1,34 @@
+/**
+ * verifyScaffold - the generator's self-check. Compiles each generated
+ * `.svelte` file with Svelte's own compiler and reports any errors, so
+ * malformed output is caught BEFORE it's written to a project. This is the
+ * cheap first gate of the verify loop; the deep gate (type resolution across
+ * real imports) is the host running the project's own `svelte-check`.
+ *
+ * The Svelte compiler is imported dynamically and best-effort: if it can't be
+ * resolved (e.g. a bare `npx @svgrid/mcp` with no svelte on disk), those files
+ * are counted as `skipped` rather than failing - the function never throws and
+ * carries no hard dependency, so it's safe in Node and in the browser.
+ *
+ * `.ts` files aren't compiled here (that needs the project's tsc + imports);
+ * they're reported as skipped.
+ */
+import type { GeneratedFile } from './scaffold.js';
+export type VerifySeverity = 'error' | 'warning';
+export type VerifyIssue = {
+    path: string;
+    severity: VerifySeverity;
+    message: string;
+};
+export type VerifyResult = {
+    /** True when no error-level issues were found (warnings are allowed). */
+    ok: boolean;
+    issues: VerifyIssue[];
+    /** How many files were actually compiled. */
+    checked: number;
+    /** How many files were skipped (non-svelte, or compiler unavailable). */
+    skipped: number;
+};
+export declare function verifyScaffold(files: ReadonlyArray<GeneratedFile>): Promise<VerifyResult>;
+/** One-line human summary of a verify result, for tool output / logs. */
+export declare function summarizeVerify(result: VerifyResult): string;

package/dist/studio/verify.js

@@ -0,0 +1,47 @@
+export async function verifyScaffold(files) {
+    const issues = [];
+    let checked = 0;
+    let skipped = 0;
+    let compile;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = await import('svelte/compiler');
+        compile = mod.compile;
+    }
+    catch {
+        compile = undefined;
+    }
+    for (const file of files) {
+        if (!file.path.endsWith('.svelte') || !compile) {
+            skipped++;
+            continue;
+        }
+        try {
+            const { warnings } = compile(file.contents, { filename: file.path, generate: 'client' });
+            checked++;
+            for (const w of warnings) {
+                issues.push({ path: file.path, severity: 'warning', message: w.message ?? 'warning' });
+            }
+        }
+        catch (err) {
+            checked++;
+            issues.push({
+                path: file.path,
+                severity: 'error',
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { ok: !issues.some((i) => i.severity === 'error'), issues, checked, skipped };
+}
+/** One-line human summary of a verify result, for tool output / logs. */
+export function summarizeVerify(result) {
+    if (result.checked === 0) {
+        return 'verification skipped (Svelte compiler unavailable) - run svelte-check in your project.';
+    }
+    const errors = result.issues.filter((i) => i.severity === 'error');
+    if (errors.length === 0)
+        return `verified: ${result.checked} file(s) compile.`;
+    return `VERIFICATION FAILED (${errors.length} error(s)):\n` +
+        errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+}

package/dist/sveltekit/in-memory.d.ts

@@ -0,0 +1,14 @@
+/**
+ * In-memory reference `ServerDataSource`. Applies a `QueryPlan` to a plain
+ * array - filter, global search, sort, page - and supports the full CRUD
+ * contract. It is the executable specification of what a backend adapter must
+ * do, and is genuinely useful on its own for small datasets, tests, demos,
+ * and prototyping a schema before a database exists behind it.
+ */
+import type { RowData } from '@svgrid/grid';
+import { type EntitySchema } from '../schema';
+import type { WritableDataSource } from './types';
+import { type AggregateSource } from '../sources/aggregate';
+export declare function createInMemoryDataSource<TData extends RowData>(initial: ReadonlyArray<TData>, schema: EntitySchema<TData>): WritableDataSource<TData> & AggregateSource & {
+    rows(): ReadonlyArray<TData>;
+};

package/dist/sveltekit/in-memory.js

@@ -0,0 +1,113 @@
+import { resolveIdField } from '../schema';
+import { planQuery } from './query-plan';
+import { aggregateRows } from '../sources/aggregate';
+function asString(v) {
+    return v == null ? '' : String(v);
+}
+function num(v) {
+    return typeof v === 'number' ? v : Number(v);
+}
+function matchesPredicate(row, p) {
+    const cell = row[p.field];
+    switch (p.op) {
+        case 'eq':
+            return asString(cell) === asString(p.value);
+        case 'contains':
+            return asString(cell).toLowerCase().includes(asString(p.value).toLowerCase());
+        case 'startsWith':
+            return asString(cell).toLowerCase().startsWith(asString(p.value).toLowerCase());
+        case 'gt':
+            return typeof p.value === 'number' ? num(cell) > p.value : asString(cell) > asString(p.value);
+        case 'lt':
+            return typeof p.value === 'number' ? num(cell) < p.value : asString(cell) < asString(p.value);
+        case 'between': {
+            if (typeof p.value === 'number' && typeof p.valueTo === 'number') {
+                return num(cell) >= p.value && num(cell) <= p.valueTo;
+            }
+            return asString(cell) >= asString(p.value) && asString(cell) <= asString(p.valueTo);
+        }
+        case 'isBlank':
+            return cell == null || cell === '';
+        case 'in':
+            return (p.values ?? []).some((v) => asString(v) === asString(cell));
+        default:
+            return true;
+    }
+}
+function matches(row, plan) {
+    if (plan.search) {
+        const term = plan.search.term.toLowerCase();
+        const hit = plan.search.fields.some((f) => asString(row[f]).toLowerCase().includes(term));
+        if (!hit)
+            return false;
+    }
+    return plan.where.every((p) => matchesPredicate(row, p));
+}
+function sortRows(rows, orderBy) {
+    if (orderBy.length === 0)
+        return rows;
+    // Stable multi-key sort: decorate with index, compare keys in order, fall back to index.
+    return rows
+        .map((row, index) => ({ row, index }))
+        .sort((a, b) => {
+        for (const { field, desc } of orderBy) {
+            const av = a.row[field];
+            const bv = b.row[field];
+            let cmp;
+            if (typeof av === 'number' && typeof bv === 'number')
+                cmp = av - bv;
+            else
+                cmp = asString(av).localeCompare(asString(bv));
+            if (cmp !== 0)
+                return desc ? -cmp : cmp;
+        }
+        return a.index - b.index;
+    })
+        .map((d) => d.row);
+}
+export function createInMemoryDataSource(initial, schema) {
+    let store = [...initial];
+    const idField = resolveIdField(schema);
+    return {
+        async getRows(request) {
+            const plan = planQuery(schema, request);
+            const filtered = sortRows(store.filter((r) => matches(r, plan)), plan.orderBy);
+            return {
+                rows: filtered.slice(plan.offset, plan.offset + plan.limit),
+                rowCount: filtered.length,
+            };
+        },
+        async createRow(input) {
+            const row = { ...input };
+            store = [...store, row];
+            return row;
+        },
+        async updateRow(id, patch) {
+            let updated;
+            store = store.map((r) => {
+                if (asString(r[idField]) === id) {
+                    updated = { ...r, ...patch };
+                    return updated;
+                }
+                return r;
+            });
+            if (!updated)
+                throw new Error(`createInMemoryDataSource: no row with ${idField}="${id}"`);
+            return updated;
+        },
+        async deleteRow(id) {
+            store = store.filter((r) => asString(r[idField]) !== id);
+        },
+        async getAggregate(request) {
+            // Apply the (optional) filter using the same plan machinery as getRows,
+            // over the whole store (no paging), then reduce in memory.
+            const plan = planQuery(schema, {
+                startRow: 0, endRow: store.length, pageIndex: 0, pageSize: store.length,
+                sortModel: [], filterModel: request.filterModel ?? {},
+            });
+            const filtered = store.filter((r) => matches(r, plan));
+            return aggregateRows(filtered, request);
+        },
+        rows: () => store,
+    };
+}

package/dist/sveltekit/index.d.ts

@@ -0,0 +1,6 @@
+export { planQuery, coerce, type QueryPlan, type PlanPredicate, type PlanOp, } from './query-plan';
+export { createInMemoryDataSource } from './in-memory';
+export { createKitDataSource, createKitHandlers, type KitDataSourceOptions, type KitHandlerOptions, type KitScope, type KitHandlers, type KitMessage, } from './transport';
+export { planToSql, type SqlDialect, type SqlPlan } from './sql';
+export { createSqlDataSource, type SqlExecutor, type SqlDataSourceConfig, } from './sql-source';
+export type { WritableDataSource } from './types';

package/dist/sveltekit/index.js

@@ -0,0 +1,5 @@
+export { planQuery, coerce, } from './query-plan';
+export { createInMemoryDataSource } from './in-memory';
+export { createKitDataSource, createKitHandlers, } from './transport';
+export { planToSql } from './sql';
+export { createSqlDataSource, } from './sql-source';

package/dist/sveltekit/query-plan.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The query-plan seam. `planQuery` turns the grid's `ServerRequest` (sort +
+ * filter + paging) into a neutral, backend-agnostic `QueryPlan`. Every backend
+ * adapter - the in-memory reference source, `planToSql` for any SQL database,
+ * a Drizzle/Supabase mapping - consumes this one plan, so the request-shaping
+ * logic (operator mapping, type coercion, field whitelisting) lives and is
+ * tested in exactly one place.
+ *
+ * Security note: only fields declared on the `EntitySchema` reach the plan.
+ * Unknown column names in the request are dropped, so a client cannot smuggle
+ * arbitrary identifiers through to SQL.
+ */
+import type { RowData, ServerRequest } from '@svgrid/grid';
+import type { EntityFieldType, EntitySchema } from '../schema';
+/** Normalized predicate operators (a stable superset of the grid's filter operators). */
+export type PlanOp = 'eq' | 'contains' | 'startsWith' | 'gt' | 'lt' | 'between' | 'isBlank' | 'in';
+export type PlanPredicate = {
+    field: string;
+    op: PlanOp;
+    /** Single operand (eq / contains / startsWith / gt / lt, and the low bound of between). */
+    value?: unknown;
+    /** Upper bound for `between`. */
+    valueTo?: unknown;
+    /** Operands for `in` (set / facet filter). */
+    values?: unknown[];
+};
+export type QueryPlan = {
+    /** AND-combined column predicates. */
+    where: PlanPredicate[];
+    /** Global free-text search: OR `contains` across these textual fields. Null when no search term. */
+    search: {
+        term: string;
+        fields: string[];
+    } | null;
+    orderBy: Array<{
+        field: string;
+        desc: boolean;
+    }>;
+    limit: number;
+    offset: number;
+};
+/** Coerce a raw string request value to the field's runtime type for correct comparisons. */
+export declare function coerce(type: EntityFieldType, raw: unknown): unknown;
+export declare function planQuery<TData extends RowData>(schema: EntitySchema<TData>, request: ServerRequest): QueryPlan;

package/dist/sveltekit/query-plan.js

@@ -0,0 +1,76 @@
+/** Grid filter operator -> normalized plan operator. Unmapped operators are ignored. */
+const OP_MAP = {
+    equals: 'eq',
+    contains: 'contains',
+    startsWith: 'startsWith',
+    greaterThan: 'gt',
+    lessThan: 'lt',
+    between: 'between',
+    isBlank: 'isBlank',
+};
+/** Field types that global text search scans. */
+const TEXTUAL = new Set(['text', 'enum']);
+/** Coerce a raw string request value to the field's runtime type for correct comparisons. */
+export function coerce(type, raw) {
+    if (raw == null)
+        return raw;
+    switch (type) {
+        case 'number': {
+            const n = Number(raw);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        case 'boolean':
+            return raw === true || raw === 'true';
+        default:
+            // text / date / dateString / datetime / enum / relation / json: compared as strings
+            return typeof raw === 'string' ? raw : String(raw);
+    }
+}
+export function planQuery(schema, request) {
+    const fields = new Map(schema.fields.map((f) => [f.field, f]));
+    const where = [];
+    const fm = request.filterModel ?? {};
+    for (const [field, spec] of Object.entries(fm.columns ?? {})) {
+        const def = fields.get(field);
+        if (!def)
+            continue; // whitelist: ignore columns not on the schema
+        // A facet / set selection wins over the operator filter.
+        if (spec.selectedValues && spec.selectedValues.length > 0) {
+            where.push({ field, op: 'in', values: spec.selectedValues.map((v) => coerce(def.type, v)) });
+            continue;
+        }
+        const op = OP_MAP[spec.operator];
+        if (!op)
+            continue;
+        if (op === 'isBlank') {
+            where.push({ field, op });
+            continue;
+        }
+        if (op === 'between') {
+            where.push({
+                field,
+                op,
+                value: coerce(def.type, spec.value),
+                valueTo: coerce(def.type, spec.valueTo),
+            });
+            continue;
+        }
+        if (spec.value === '' || spec.value == null)
+            continue;
+        where.push({ field, op, value: coerce(def.type, spec.value) });
+    }
+    const term = (fm.global ?? '').trim();
+    const search = term.length > 0
+        ? {
+            term,
+            // Textual, non-key fields: searching a primary key by substring is noise.
+            fields: schema.fields
+                .filter((f) => TEXTUAL.has(f.type) && !f.primaryKey && f.field !== schema.idField)
+                .map((f) => f.field),
+        }
+        : null;
+    const orderBy = (request.sortModel ?? [])
+        .filter((s) => fields.has(s.id))
+        .map((s) => ({ field: s.id, desc: !!s.desc }));
+    return { where, search, orderBy, limit: request.pageSize, offset: request.startRow };
+}

package/dist/sveltekit/sql-source.d.ts

@@ -0,0 +1,47 @@
+/**
+ * createSqlDataSource - a production `ServerDataSource` backed by any SQL
+ * database. It plans the read with `planQuery` + `planToSql`, and builds
+ * parameterized INSERT / UPDATE / DELETE for writes. You supply one thing: an
+ * `execute(sql, params)` that runs a query and returns rows. Every SQL client
+ * SvelteKit teams use provides that - Drizzle (`db.execute`), postgres.js,
+ * better-sqlite3, mysql2 - so this is the turnkey "point at your database"
+ * adapter, the sibling of `createInMemoryDataSource`.
+ *
+ * All values are parameterized; identifiers come from the schema-whitelisted
+ * plan and are quoted. No string interpolation of user input.
+ *
+ * Drizzle (Postgres) example:
+ *
+ *     import { sql } from 'drizzle-orm'
+ *     const source = createSqlDataSource({
+ *       schema: customerSchema,
+ *       table: 'customers',
+ *       dialect: { placeholders: '$', ilike: true },
+ *       execute: (text, params) =>
+ *         db.execute(sql.raw(text, params)).then((r) => r.rows),
+ *     })
+ */
+import type { RowData } from '@svgrid/grid';
+import { type EntitySchema } from '../schema';
+import { type SqlDialect } from './sql';
+import type { WritableDataSource } from './types';
+import type { AggregateSource } from '../sources/aggregate';
+/** Run a parameterized query, resolving to the result rows. */
+export type SqlExecutor = (sql: string, params: unknown[]) => Promise<ReadonlyArray<Record<string, unknown>>>;
+export type SqlDataSourceConfig<TData extends RowData> = {
+    schema: EntitySchema<TData>;
+    /** Table (or view) name. Quoted per the dialect; not interpolated raw. */
+    table: string;
+    /** DB schema / namespace (e.g. Postgres `public`, SQL Server `dbo`). When set,
+     *  the table is addressed as `"schema"."table"`. Each part is quoted separately. */
+    dbSchema?: string;
+    execute: SqlExecutor;
+    dialect?: SqlDialect;
+    /**
+     * Append `RETURNING *` to writes and return the row the database echoes back
+     * (Postgres / SQLite). Set false for MySQL, where the input is returned as-is.
+     * Default true.
+     */
+    returning?: boolean;
+};
+export declare function createSqlDataSource<TData extends RowData>(config: SqlDataSourceConfig<TData>): WritableDataSource<TData> & AggregateSource;

package/dist/sveltekit/sql-source.js

@@ -0,0 +1,106 @@
+import { resolveIdField } from '../schema';
+import { nudgeEnterprise } from '../license';
+import { planQuery } from './query-plan';
+import { planToSql } from './sql';
+const SQL_AGG = { sum: 'SUM', avg: 'AVG', min: 'MIN', max: 'MAX' };
+function quoter(dialect) {
+    const q = dialect.quote ?? '"';
+    return (name) => `${q}${name.replace(new RegExp(q, 'g'), q + q)}${q}`;
+}
+function binder(dialect, params) {
+    return (value) => {
+        params.push(value);
+        if (dialect.placeholders === '$')
+            return `$${params.length}`;
+        if (dialect.placeholders === '@')
+            return `@p${params.length}`;
+        return '?';
+    };
+}
+const squish = (sql) => sql.replace(/\s+/g, ' ').trim();
+export function createSqlDataSource(config) {
+    nudgeEnterprise('Studio'); // soft-gate; never blocks, safe on the server
+    const { schema, execute } = config;
+    const dialect = config.dialect ?? {};
+    const returning = config.returning ?? true;
+    const id = quoter(dialect);
+    const idField = resolveIdField(schema);
+    // Optionally schema-qualify the table: "schema"."table" (each part quoted separately).
+    const qtable = config.dbSchema ? `${id(config.dbSchema)}.${id(config.table)}` : id(config.table);
+    // Column mapping: when a field has a `dbColumn` (e.g. Drizzle `created_at` vs
+    // key `createdAt`), read/write the real column and alias it back to the field.
+    // With no renames, everything is identity - the emitted SQL is byte-identical.
+    const dbCol = new Map(schema.fields.filter((f) => f.dbColumn).map((f) => [f.field, f.dbColumn]));
+    const hasRenames = dbCol.size > 0;
+    const columnOf = (field) => dbCol.get(field) ?? field;
+    const col = (field) => id(columnOf(field));
+    const projection = hasRenames
+        ? schema.fields.map((f) => `${id(columnOf(f.field))} AS ${id(f.field)}`).join(', ')
+        : '*';
+    const planDialect = hasRenames ? { ...dialect, column: columnOf } : dialect;
+    const RET = returning ? ` RETURNING ${projection}` : '';
+    return {
+        async getRows(request) {
+            const plan = planQuery(schema, request);
+            const sql = planToSql(plan, planDialect);
+            const t = qtable;
+            const rowsSql = squish(`SELECT ${projection} FROM ${t} ${sql.whereText} ${sql.orderByText} LIMIT ${sql.limit} OFFSET ${sql.offset}`);
+            const countSql = squish(`SELECT COUNT(*) AS count FROM ${t} ${sql.whereText}`);
+            const rows = await execute(rowsSql, sql.params);
+            const countRows = await execute(countSql, sql.params);
+            const rowCount = Number(countRows[0]?.count ?? rows.length);
+            return { rows: rows, rowCount };
+        },
+        async createRow(input) {
+            const cols = Object.keys(input);
+            if (cols.length === 0)
+                throw new Error('createSqlDataSource: createRow needs at least one field');
+            const params = [];
+            const bind = binder(dialect, params);
+            const values = cols.map((c) => bind(input[c]));
+            const sql = squish(`INSERT INTO ${qtable} (${cols.map(col).join(', ')}) VALUES (${values.join(', ')})${RET}`);
+            const rows = await execute(sql, params);
+            return (rows[0] ?? input);
+        },
+        async updateRow(rowIdValue, patch) {
+            const cols = Object.keys(patch);
+            if (cols.length === 0)
+                throw new Error('createSqlDataSource: updateRow needs at least one field');
+            const params = [];
+            const bind = binder(dialect, params);
+            const sets = cols.map((c) => `${col(c)} = ${bind(patch[c])}`);
+            const where = `${col(idField)} = ${bind(rowIdValue)}`;
+            const sql = squish(`UPDATE ${qtable} SET ${sets.join(', ')} WHERE ${where}${RET}`);
+            const rows = await execute(sql, params);
+            return (rows[0] ?? { ...patch, [idField]: rowIdValue });
+        },
+        async deleteRow(rowIdValue) {
+            const params = [];
+            const bind = binder(dialect, params);
+            const sql = squish(`DELETE FROM ${qtable} WHERE ${col(idField)} = ${bind(rowIdValue)}`);
+            await execute(sql, params);
+        },
+        async getAggregate(request) {
+            // Server-side GROUP BY. Identifiers are schema-quoted (no interpolation of
+            // user input); the WHERE + params come from the shared query plan.
+            const plan = planQuery(schema, {
+                startRow: 0, endRow: 0, pageIndex: 0, pageSize: 0, sortModel: [],
+                filterModel: request.filterModel ?? {},
+            });
+            const sql = planToSql(plan, planDialect);
+            const fn = request.reduce === 'count' || !request.measure
+                ? 'COUNT(*)'
+                : `${SQL_AGG[request.reduce]}(${col(request.measure)})`;
+            // No dimension -> a single grand total (a KPI), no GROUP BY.
+            if (!request.dimension) {
+                const text = squish(`SELECT ${fn} AS value FROM ${qtable} ${sql.whereText}`);
+                const rows = await execute(text, sql.params);
+                return [{ category: '', value: Number(rows[0]?.value ?? 0) }];
+            }
+            const dim = col(request.dimension);
+            const text = squish(`SELECT ${dim} AS category, ${fn} AS value FROM ${qtable} ${sql.whereText} GROUP BY ${dim} ORDER BY value DESC`);
+            const rows = await execute(text, sql.params);
+            return rows.map((r) => ({ category: String(r.category ?? ''), value: Number(r.value ?? 0) }));
+        },
+    };
+}

package/dist/sveltekit/sql.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `planToSql` - turn a `QueryPlan` into a portable, parameterized SQL fragment.
+ * This is the backend seam for every SQL database: Drizzle, postgres.js,
+ * better-sqlite3, mysql2. It emits only a WHERE body, an ORDER BY body, and a
+ * params array - never a full statement - so you keep control of the SELECT,
+ * the table, joins, and execution.
+ *
+ * All values are parameterized (never interpolated) and every identifier comes
+ * from the plan, which `planQuery` already whitelisted against the schema - so
+ * there is no SQL-injection surface here.
+ *
+ * Drizzle usage (Postgres):
+ *
+ *     import { sql } from 'drizzle-orm'
+ *     const { whereText, orderByText, params, limit, offset } =
+ *       planToSql(plan, { placeholders: '$', ilike: true })
+ *     const rows = await db.execute(
+ *       sql.raw(`select * from customers ${whereText} ${orderByText} limit ${limit} offset ${offset}`, params)
+ *     )
+ *
+ * (Or map `plan.where` to Drizzle operators directly - the plan is the seam
+ * either way.)
+ */
+import type { QueryPlan } from './query-plan';
+export type SqlDialect = {
+    /** Identifier quote char. Default `"` (ANSI / Postgres / SQLite). MySQL: `` ` ``. */
+    quote?: string;
+    /** Placeholder style: `'?'` (SQLite / MySQL), `'$'` for `$1, $2` (Postgres), or `'@'` for `@p1, @p2` (SQL Server). Default `'?'`. */
+    placeholders?: '?' | '$' | '@';
+    /** Use `ILIKE` for case-insensitive matching (Postgres) instead of `LOWER(col) LIKE LOWER(?)`. */
+    ilike?: boolean;
+    /** Map a schema `field` to its real DB column. Default: identity. Lets renamed columns (Drizzle `created_at` vs key `createdAt`) plan correctly. */
+    column?: (field: string) => string;
+};
+export type SqlPlan = {
+    /** WHERE body without the keyword, e.g. `"age" > ? AND "name" ILIKE ?`. Empty string when no predicates. */
+    where: string;
+    /** WHERE body with the leading `WHERE ` keyword, or `''`. */
+    whereText: string;
+    /** ORDER BY body without the keyword, e.g. `"name" ASC, "age" DESC`. */
+    orderBy: string;
+    /** ORDER BY body with the leading `ORDER BY ` keyword, or `''`. */
+    orderByText: string;
+    params: unknown[];
+    limit: number;
+    offset: number;
+};
+export declare function planToSql(plan: QueryPlan, dialect?: SqlDialect): SqlPlan;