@shotleybuilder/svelte-gridlite-kit 0.1.0

package/dist/query/builder.js

@@ -0,0 +1,432 @@
+/**
+ * SQL Query Builder for GridLite
+ *
+ * Translates FilterCondition[], SortConfig[], GroupConfig[], and pagination
+ * into parameterized SQL queries. All user input is parameterized — never
+ * interpolated into SQL strings.
+ *
+ * Column names are validated against an allowlist (from schema introspection)
+ * to prevent SQL injection via identifier manipulation.
+ */
+// ─── Column Name Validation ─────────────────────────────────────────────────
+/**
+ * Valid SQL identifier pattern: letters, digits, underscores.
+ * Rejects anything that could be used for SQL injection via identifiers.
+ */
+const VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validate and quote a column name as a SQL identifier.
+ * Throws if the name is not a valid identifier.
+ *
+ * When `allowedColumns` is provided, also checks the name is in the allowlist.
+ */
+export function quoteIdentifier(name, allowedColumns) {
+    if (!VALID_IDENTIFIER.test(name)) {
+        throw new Error(`Invalid column name: ${JSON.stringify(name)}`);
+    }
+    if (allowedColumns && !allowedColumns.includes(name)) {
+        throw new Error(`Column not found: ${JSON.stringify(name)}`);
+    }
+    return `"${name}"`;
+}
+// ─── WHERE Clause Builder ───────────────────────────────────────────────────
+/**
+ * Build a WHERE clause from filter conditions.
+ *
+ * Returns `{ sql: string, params: unknown[] }` where sql is empty string
+ * if there are no valid conditions.
+ *
+ * @param conditions - Filter conditions from the UI
+ * @param logic - 'and' or 'or' between conditions
+ * @param paramOffset - Starting parameter index (for $1, $2, ...) when composing with other clauses
+ * @param allowedColumns - Optional allowlist of column names from schema introspection
+ */
+export function buildWhereClause(conditions, logic = "and", paramOffset = 0, allowedColumns) {
+    // Filter out invalid conditions
+    const valid = conditions.filter((c) => c.field &&
+        (c.operator === "is_empty" ||
+            c.operator === "is_not_empty" ||
+            (c.value !== null && c.value !== undefined && c.value !== "")));
+    if (valid.length === 0) {
+        return { sql: "", params: [] };
+    }
+    const parts = [];
+    const params = [];
+    let paramIndex = paramOffset + 1; // PostgreSQL params are 1-indexed
+    for (const condition of valid) {
+        const col = quoteIdentifier(condition.field, allowedColumns);
+        const result = buildConditionSQL(col, condition, paramIndex);
+        parts.push(result.sql);
+        params.push(...result.params);
+        paramIndex += result.params.length;
+    }
+    const joiner = logic === "or" ? " OR " : " AND ";
+    const sql = `WHERE ${parts.join(joiner)}`;
+    return { sql, params };
+}
+/**
+ * Build SQL for a single filter condition.
+ */
+function buildConditionSQL(quotedCol, condition, paramIndex) {
+    const p = (offset = 0) => `$${paramIndex + offset}`;
+    switch (condition.operator) {
+        // String operators
+        case "equals":
+            return { sql: `${quotedCol} = ${p()}`, params: [condition.value] };
+        case "not_equals":
+            return { sql: `${quotedCol} != ${p()}`, params: [condition.value] };
+        case "contains":
+            return {
+                sql: `${quotedCol} ILIKE '%' || ${p()} || '%'`,
+                params: [condition.value],
+            };
+        case "not_contains":
+            return {
+                sql: `${quotedCol} NOT ILIKE '%' || ${p()} || '%'`,
+                params: [condition.value],
+            };
+        case "starts_with":
+            return {
+                sql: `${quotedCol} ILIKE ${p()} || '%'`,
+                params: [condition.value],
+            };
+        case "ends_with":
+            return {
+                sql: `${quotedCol} ILIKE '%' || ${p()}`,
+                params: [condition.value],
+            };
+        case "is_empty":
+            return { sql: `(${quotedCol} IS NULL OR ${quotedCol} = '')`, params: [] };
+        case "is_not_empty":
+            return {
+                sql: `(${quotedCol} IS NOT NULL AND ${quotedCol} != '')`,
+                params: [],
+            };
+        // Numeric operators
+        case "greater_than":
+            return { sql: `${quotedCol} > ${p()}`, params: [condition.value] };
+        case "less_than":
+            return { sql: `${quotedCol} < ${p()}`, params: [condition.value] };
+        case "greater_or_equal":
+            return { sql: `${quotedCol} >= ${p()}`, params: [condition.value] };
+        case "less_or_equal":
+            return { sql: `${quotedCol} <= ${p()}`, params: [condition.value] };
+        // Date operators
+        case "is_before":
+            return { sql: `${quotedCol} < ${p()}`, params: [condition.value] };
+        case "is_after":
+            return { sql: `${quotedCol} > ${p()}`, params: [condition.value] };
+        default:
+            throw new Error(`Unknown filter operator: ${condition.operator}`);
+    }
+}
+// ─── ORDER BY Clause Builder ────────────────────────────────────────────────
+/**
+ * Build an ORDER BY clause from sort configurations.
+ */
+export function buildOrderByClause(sorting, allowedColumns) {
+    if (sorting.length === 0)
+        return "";
+    const parts = sorting.map((s) => {
+        const col = quoteIdentifier(s.column, allowedColumns);
+        const dir = s.direction === "desc" ? "DESC" : "ASC";
+        return `${col} ${dir}`;
+    });
+    return `ORDER BY ${parts.join(", ")}`;
+}
+// ─── GROUP BY Clause Builder ────────────────────────────────────────────────
+const VALID_AGGREGATES = [
+    "count",
+    "sum",
+    "avg",
+    "min",
+    "max",
+];
+/**
+ * Build GROUP BY clause and adjust SELECT for grouped queries.
+ *
+ * Returns the GROUP BY clause and the SELECT column list.
+ */
+export function buildGroupByClause(grouping, allowedColumns) {
+    if (grouping.length === 0) {
+        return { selectColumns: "*", groupBy: "" };
+    }
+    const groupCols = grouping.map((g) => quoteIdentifier(g.column, allowedColumns));
+    const aggParts = [];
+    for (const group of grouping) {
+        if (group.aggregations) {
+            for (const agg of group.aggregations) {
+                if (!VALID_AGGREGATES.includes(agg.function)) {
+                    throw new Error(`Invalid aggregate function: ${agg.function}`);
+                }
+                const aggCol = quoteIdentifier(agg.column, allowedColumns);
+                const alias = agg.alias
+                    ? quoteIdentifier(agg.alias)
+                    : `"${agg.function}_${agg.column}"`;
+                aggParts.push(`${agg.function.toUpperCase()}(${aggCol}) AS ${alias}`);
+            }
+        }
+    }
+    // Always include COUNT(*) for grouped results
+    aggParts.push('COUNT(*) AS "_count"');
+    const selectColumns = [...groupCols, ...aggParts].join(", ");
+    const groupBy = `GROUP BY ${groupCols.join(", ")}`;
+    return { selectColumns, groupBy };
+}
+// ─── Pagination ─────────────────────────────────────────────────────────────
+/**
+ * Build LIMIT/OFFSET clause for pagination.
+ */
+export function buildPaginationClause(page, pageSize) {
+    if (pageSize <= 0)
+        throw new Error("pageSize must be positive");
+    if (page < 0)
+        throw new Error("page must be non-negative");
+    const offset = page * pageSize;
+    return `LIMIT ${pageSize} OFFSET ${offset}`;
+}
+// ─── Global Search ──────────────────────────────────────────────────────────
+/**
+ * Build a WHERE-compatible clause for global search across text columns.
+ *
+ * Generates `(col1::text ILIKE '%' || $N || '%' OR col2::text ILIKE ...)`
+ * using a single parameter for the search term. The `::text` cast allows
+ * searching non-text columns (numbers, dates, booleans) as strings.
+ *
+ * @param searchTerm - The search string
+ * @param textColumns - Column names to search across
+ * @param paramOffset - Starting parameter index
+ * @param allowedColumns - Optional allowlist
+ */
+export function buildGlobalSearchClause(searchTerm, textColumns, paramOffset = 0, allowedColumns) {
+    if (!searchTerm || textColumns.length === 0) {
+        return { sql: "", params: [] };
+    }
+    const paramIndex = paramOffset + 1;
+    const p = `$${paramIndex}`;
+    const parts = textColumns.map((col) => {
+        const quoted = quoteIdentifier(col, allowedColumns);
+        return `${quoted}::text ILIKE '%' || ${p} || '%'`;
+    });
+    return {
+        sql: `(${parts.join(" OR ")})`,
+        params: [searchTerm],
+    };
+}
+/**
+ * Build a query that returns distinct group values with COUNT(*) and
+ * optional aggregations. Used for the group header rows.
+ *
+ * Example output for grouping by department with avg(salary):
+ *   SELECT "department", COUNT(*) AS "_count", AVG("salary") AS "avg_salary"
+ *   FROM "employees" WHERE ... GROUP BY "department" ORDER BY "department"
+ */
+export function buildGroupSummaryQuery(options) {
+    const { table, grouping, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, sorting = [], page, pageSize, } = options;
+    if (grouping.length === 0) {
+        throw new Error("buildGroupSummaryQuery requires at least one group");
+    }
+    const tableName = quoteIdentifier(table);
+    const { selectColumns, groupBy } = buildGroupByClause(grouping, allowedColumns);
+    // WHERE from filters
+    const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
+    // Global search
+    const searchCols = searchColumns ?? allowedColumns ?? [];
+    const globalSearchClause = buildGlobalSearchClause(globalSearch ?? "", searchCols, where.params.length, allowedColumns);
+    const allParams = [...where.params, ...globalSearchClause.params];
+    let whereSQL = "";
+    if (where.sql && globalSearchClause.sql) {
+        whereSQL = `WHERE ${where.sql.replace(/^WHERE /, "")} AND ${globalSearchClause.sql}`;
+    }
+    else if (where.sql) {
+        whereSQL = where.sql;
+    }
+    else if (globalSearchClause.sql) {
+        whereSQL = `WHERE ${globalSearchClause.sql}`;
+    }
+    // Sort by group columns if no explicit sort, or by specified sort
+    let orderBy = "";
+    if (sorting.length > 0) {
+        orderBy = buildOrderByClause(sorting, allowedColumns);
+    }
+    else {
+        // Default: sort by group columns ascending
+        const groupCols = grouping.map((g) => quoteIdentifier(g.column, allowedColumns));
+        orderBy = `ORDER BY ${groupCols.join(", ")}`;
+    }
+    // Pagination on groups
+    const pagination = page !== undefined && pageSize !== undefined
+        ? buildPaginationClause(page, pageSize)
+        : "";
+    const parts = [
+        `SELECT ${selectColumns}`,
+        `FROM ${tableName}`,
+        whereSQL,
+        groupBy,
+        orderBy,
+        pagination,
+    ].filter(Boolean);
+    return { sql: parts.join(" "), params: allParams };
+}
+/**
+ * Build a count query for group summaries (how many groups exist).
+ */
+export function buildGroupCountQuery(options) {
+    const { table, grouping, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, } = options;
+    if (grouping.length === 0) {
+        throw new Error("buildGroupCountQuery requires at least one group");
+    }
+    const tableName = quoteIdentifier(table);
+    const groupCols = grouping.map((g) => quoteIdentifier(g.column, allowedColumns));
+    const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
+    const searchCols = searchColumns ?? allowedColumns ?? [];
+    const globalSearchClause = buildGlobalSearchClause(globalSearch ?? "", searchCols, where.params.length, allowedColumns);
+    const allParams = [...where.params, ...globalSearchClause.params];
+    let whereSQL = "";
+    if (where.sql && globalSearchClause.sql) {
+        whereSQL = `WHERE ${where.sql.replace(/^WHERE /, "")} AND ${globalSearchClause.sql}`;
+    }
+    else if (where.sql) {
+        whereSQL = where.sql;
+    }
+    else if (globalSearchClause.sql) {
+        whereSQL = `WHERE ${globalSearchClause.sql}`;
+    }
+    const parts = [
+        `SELECT COUNT(*) AS "total" FROM (SELECT 1 FROM ${tableName}`,
+        whereSQL,
+        `GROUP BY ${groupCols.join(", ")}`,
+        `) AS "_groups"`,
+    ].filter(Boolean);
+    return { sql: parts.join(" "), params: allParams };
+}
+/**
+ * Build a query that returns the detail rows for an expanded group.
+ *
+ * Adds WHERE constraints for each group column value on top of any
+ * existing filters. Used when a user expands a group header.
+ *
+ * Example: grouping by department, expanded "Engineering":
+ *   SELECT * FROM "employees" WHERE ... AND "department" = $N ORDER BY ...
+ */
+export function buildGroupDetailQuery(options) {
+    const { table, groupValues, filters = [], filterLogic = "and", sorting = [], allowedColumns, globalSearch, searchColumns, } = options;
+    if (groupValues.length === 0) {
+        throw new Error("buildGroupDetailQuery requires at least one group value");
+    }
+    const tableName = quoteIdentifier(table);
+    // Base WHERE from filters
+    const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
+    // Global search
+    const searchCols = searchColumns ?? allowedColumns ?? [];
+    const globalSearchClause = buildGlobalSearchClause(globalSearch ?? "", searchCols, where.params.length, allowedColumns);
+    let allParams = [...where.params, ...globalSearchClause.params];
+    // Build the combined WHERE from filters + global search
+    let baseWhereParts = [];
+    if (where.sql) {
+        baseWhereParts.push(where.sql.replace(/^WHERE /, ""));
+    }
+    if (globalSearchClause.sql) {
+        baseWhereParts.push(globalSearchClause.sql);
+    }
+    // Add group value constraints
+    const groupConstraints = [];
+    for (const gv of groupValues) {
+        const col = quoteIdentifier(gv.column, allowedColumns);
+        const paramIdx = allParams.length + 1;
+        if (gv.value === null) {
+            groupConstraints.push(`${col} IS NULL`);
+        }
+        else {
+            groupConstraints.push(`${col} = $${paramIdx}`);
+            allParams = [...allParams, gv.value];
+        }
+    }
+    const allWhereParts = [...baseWhereParts, ...groupConstraints];
+    const whereSQL = allWhereParts.length > 0 ? `WHERE ${allWhereParts.join(" AND ")}` : "";
+    const orderBy = buildOrderByClause(sorting, allowedColumns);
+    const parts = [`SELECT *`, `FROM ${tableName}`, whereSQL, orderBy].filter(Boolean);
+    return { sql: parts.join(" "), params: allParams };
+}
+/**
+ * Build a complete parameterized SELECT query from grid state.
+ *
+ * This is the main entry point for the query builder. It composes
+ * WHERE, ORDER BY, GROUP BY, and LIMIT/OFFSET clauses into a single query.
+ */
+export function buildQuery(options) {
+    const { table, filters = [], filterLogic = "and", sorting = [], grouping = [], page, pageSize, allowedColumns, globalSearch, searchColumns, } = options;
+    const tableName = quoteIdentifier(table);
+    // GROUP BY affects SELECT columns
+    const { selectColumns, groupBy } = buildGroupByClause(grouping, allowedColumns);
+    // WHERE clause from filters
+    const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
+    // Global search clause
+    const searchCols = searchColumns ?? allowedColumns ?? [];
+    const globalSearchClause = buildGlobalSearchClause(globalSearch ?? "", searchCols, where.params.length, allowedColumns);
+    // Combine WHERE and global search
+    const allParams = [...where.params, ...globalSearchClause.params];
+    let whereSQL = "";
+    if (where.sql && globalSearchClause.sql) {
+        // Strip "WHERE " prefix from where.sql, combine with AND
+        whereSQL = `WHERE ${where.sql.replace(/^WHERE /, "")} AND ${globalSearchClause.sql}`;
+    }
+    else if (where.sql) {
+        whereSQL = where.sql;
+    }
+    else if (globalSearchClause.sql) {
+        whereSQL = `WHERE ${globalSearchClause.sql}`;
+    }
+    // ORDER BY clause
+    const orderBy = buildOrderByClause(sorting, allowedColumns);
+    // LIMIT/OFFSET clause
+    const pagination = page !== undefined && pageSize !== undefined
+        ? buildPaginationClause(page, pageSize)
+        : "";
+    // Compose
+    const parts = [
+        `SELECT ${selectColumns}`,
+        `FROM ${tableName}`,
+        whereSQL,
+        groupBy,
+        orderBy,
+        pagination,
+    ].filter(Boolean);
+    return {
+        sql: parts.join(" "),
+        params: allParams,
+    };
+}
+/**
+ * Build a COUNT query for pagination total.
+ * Uses the same filters but no sorting/grouping/pagination.
+ */
+export function buildCountQuery(options) {
+    const { table, filters = [], filterLogic = "and", allowedColumns, globalSearch, searchColumns, } = options;
+    const tableName = quoteIdentifier(table);
+    const where = buildWhereClause(filters, filterLogic, 0, allowedColumns);
+    // Global search clause
+    const searchCols = searchColumns ?? allowedColumns ?? [];
+    const globalSearchClause = buildGlobalSearchClause(globalSearch ?? "", searchCols, where.params.length, allowedColumns);
+    // Combine WHERE and global search
+    const allParams = [...where.params, ...globalSearchClause.params];
+    let whereSQL = "";
+    if (where.sql && globalSearchClause.sql) {
+        whereSQL = `WHERE ${where.sql.replace(/^WHERE /, "")} AND ${globalSearchClause.sql}`;
+    }
+    else if (where.sql) {
+        whereSQL = where.sql;
+    }
+    else if (globalSearchClause.sql) {
+        whereSQL = `WHERE ${globalSearchClause.sql}`;
+    }
+    const parts = [
+        'SELECT COUNT(*) AS "total"',
+        `FROM ${tableName}`,
+        whereSQL,
+    ].filter(Boolean);
+    return {
+        sql: parts.join(" "),
+        params: allParams,
+    };
+}

package/dist/query/live.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Svelte Store Wrapper for PGLite Live Queries
+ *
+ * Bridges PGLite's live.query() API with Svelte's store contract.
+ * Provides loading/error/data states and handles subscription lifecycle.
+ *
+ * Usage:
+ *   const store = createLiveQueryStore(db, 'SELECT * FROM users WHERE active = $1', [true]);
+ *   // In Svelte: $store.rows, $store.loading, $store.error
+ *   // Call store.destroy() on component unmount
+ */
+import type { PGlite } from '@electric-sql/pglite';
+import type { LiveNamespace } from '@electric-sql/pglite/live';
+import type { ParameterizedQuery } from '../types.js';
+export interface LiveQueryState<T = Record<string, unknown>> {
+    rows: T[];
+    fields: {
+        name: string;
+        dataTypeID: number;
+    }[];
+    totalCount?: number;
+    loading: boolean;
+    error: Error | null;
+}
+export interface LiveQueryStore<T = Record<string, unknown>> {
+    subscribe: (callback: (state: LiveQueryState<T>) => void) => () => void;
+    refresh: () => Promise<void>;
+    update: (query: string, params?: unknown[]) => Promise<void>;
+    destroy: () => Promise<void>;
+}
+/** A PGLite instance that has the live extension loaded */
+export type PGliteWithLive = PGlite & {
+    live: LiveNamespace;
+};
+/**
+ * Create a Svelte-compatible store backed by a PGLite live query.
+ *
+ * The store follows Svelte's store contract (has a `subscribe` method that
+ * returns an unsubscribe function). It also exposes `refresh`, `update`,
+ * and `destroy` methods.
+ *
+ * @param db - PGLite instance with the live extension loaded
+ * @param query - SQL query string with $1, $2, ... parameters
+ * @param params - Parameter values for the query
+ */
+export declare function createLiveQueryStore<T = Record<string, unknown>>(db: PGliteWithLive, query: string, params?: unknown[]): LiveQueryStore<T>;
+/**
+ * Convenience: create a live query store from a ParameterizedQuery object.
+ */
+export declare function createLiveQueryStoreFromQuery<T = Record<string, unknown>>(db: PGliteWithLive, parameterizedQuery: ParameterizedQuery): LiveQueryStore<T>;

package/dist/query/live.js

@@ -0,0 +1,118 @@
+/**
+ * Svelte Store Wrapper for PGLite Live Queries
+ *
+ * Bridges PGLite's live.query() API with Svelte's store contract.
+ * Provides loading/error/data states and handles subscription lifecycle.
+ *
+ * Usage:
+ *   const store = createLiveQueryStore(db, 'SELECT * FROM users WHERE active = $1', [true]);
+ *   // In Svelte: $store.rows, $store.loading, $store.error
+ *   // Call store.destroy() on component unmount
+ */
+// ─── Store Factory ──────────────────────────────────────────────────────────
+/**
+ * Create a Svelte-compatible store backed by a PGLite live query.
+ *
+ * The store follows Svelte's store contract (has a `subscribe` method that
+ * returns an unsubscribe function). It also exposes `refresh`, `update`,
+ * and `destroy` methods.
+ *
+ * @param db - PGLite instance with the live extension loaded
+ * @param query - SQL query string with $1, $2, ... parameters
+ * @param params - Parameter values for the query
+ */
+export function createLiveQueryStore(db, query, params = []) {
+    let state = {
+        rows: [],
+        fields: [],
+        loading: true,
+        error: null
+    };
+    const subscribers = new Set();
+    // Internal unsubscribe from PGLite live query
+    let liveUnsubscribe = null;
+    let liveRefresh = null;
+    let destroyed = false;
+    function notify() {
+        for (const cb of subscribers) {
+            cb(state);
+        }
+    }
+    function setState(partial) {
+        state = { ...state, ...partial };
+        notify();
+    }
+    function handleResults(results) {
+        setState({
+            rows: results.rows,
+            fields: results.fields,
+            totalCount: results.totalCount,
+            loading: false,
+            error: null
+        });
+    }
+    async function setupLiveQuery(sql, queryParams) {
+        // Tear down existing subscription
+        if (liveUnsubscribe) {
+            await liveUnsubscribe();
+            liveUnsubscribe = null;
+            liveRefresh = null;
+        }
+        if (destroyed)
+            return;
+        setState({ loading: true, error: null });
+        try {
+            const liveQuery = await db.live.query(sql, queryParams, handleResults);
+            if (destroyed) {
+                // Component was destroyed while we were setting up
+                await liveQuery.unsubscribe();
+                return;
+            }
+            liveUnsubscribe = liveQuery.unsubscribe;
+            liveRefresh = liveQuery.refresh;
+            // Initial results are delivered via the callback, but also available here
+            handleResults(liveQuery.initialResults);
+        }
+        catch (err) {
+            setState({
+                loading: false,
+                error: err instanceof Error ? err : new Error(String(err))
+            });
+        }
+    }
+    // Start the initial live query
+    setupLiveQuery(query, params);
+    return {
+        subscribe(callback) {
+            subscribers.add(callback);
+            // Immediately deliver current state (Svelte store contract)
+            callback(state);
+            return () => {
+                subscribers.delete(callback);
+            };
+        },
+        async refresh() {
+            if (liveRefresh) {
+                await liveRefresh();
+            }
+        },
+        async update(newQuery, newParams = []) {
+            await setupLiveQuery(newQuery, newParams);
+        },
+        async destroy() {
+            destroyed = true;
+            if (liveUnsubscribe) {
+                await liveUnsubscribe();
+                liveUnsubscribe = null;
+                liveRefresh = null;
+            }
+            subscribers.clear();
+        }
+    };
+}
+/**
+ * Convenience: create a live query store from a ParameterizedQuery object.
+ */
+export function createLiveQueryStoreFromQuery(db, parameterizedQuery) {
+    return createLiveQueryStore(db, parameterizedQuery.sql, parameterizedQuery.params);
+}

package/dist/query/schema.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Schema Introspection for GridLite
+ *
+ * Queries information_schema.columns to discover column names, types,
+ * and nullability for a given table. Maps Postgres data types to
+ * GridLite's ColumnDataType for filter operator selection and UI rendering.
+ */
+import type { PGlite } from '@electric-sql/pglite';
+import type { ColumnDataType, ColumnMetadata } from '../types.js';
+/**
+ * Map a Postgres data_type string (from information_schema.columns)
+ * to a GridLite ColumnDataType.
+ */
+export declare function mapPostgresType(postgresType: string): ColumnDataType;
+/**
+ * Introspect a table's schema using information_schema.columns.
+ *
+ * Returns an array of ColumnMetadata in column ordinal position order.
+ * The table name is parameterized to prevent SQL injection.
+ *
+ * @param db - PGLite instance
+ * @param tableName - The table to introspect
+ * @param schema - The schema to search (defaults to 'public')
+ */
+export declare function introspectTable(db: PGlite, tableName: string, schema?: string): Promise<ColumnMetadata[]>;
+/**
+ * Get the list of column names for a table.
+ * Useful for the query builder's allowedColumns parameter.
+ */
+export declare function getColumnNames(db: PGlite, tableName: string, schema?: string): Promise<string[]>;