@molecule/api-database-duckdb 0.0.0-stage → 0.0.1-stage

package/dist/store.js

@@ -0,0 +1,335 @@
+/**
+ * DuckDB DataStore implementation.
+ *
+ * Translates abstract DataStore CRUD methods to DuckDB SQL. DuckDB binds `?`
+ * and `$1` placeholders natively positionally, so the SQL built here needs no
+ * conversion on its way to the engine.
+ *
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { getLogger } from '@molecule/api-bond';
+import { assertFindManyOptions, assertOptionalWhereConditions, assertWhereConditions, } from '@molecule/api-database/query-guards.js';
+import { parseJsonColumns } from './utilities.js';
+/**
+ * Validates that an identifier (table/column name) is safe for SQL interpolation.
+ * Hyphens are allowed: every interpolation site double-quotes the identifier, and
+ * inside a quoted identifier only `"` itself is dangerous (still rejected). Real
+ * consumers use hyphenated tables (e.g. `@molecule/api-resource-share`'s
+ * `"resource-share-links"`) — parity with the postgresql/sqlite bonds.
+ */
+const SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+/**
+ * Validates that a SQL identifier (table or column name) is safe for interpolation.
+ *
+ * Table/column names cannot be bound as parameters, so they are interpolated
+ * directly into the SQL string. Any value that reaches an interpolation point MUST be
+ * validated here — otherwise a caller passing a user-supplied identifier (e.g. a
+ * `sort_by` column from a query string) opens a SQL-injection hole. The whitelist of
+ * plain `[A-Za-z_][A-Za-z0-9_-]*` identifiers makes the `"..."` quoting unbreakable.
+ *
+ * @param name - The identifier string to validate.
+ */
+function assertSafeIdentifier(name) {
+    if (!SAFE_IDENTIFIER.test(name)) {
+        throw new Error(`Invalid SQL identifier: ${name}`);
+    }
+}
+/**
+ * Builds a SQL WHERE clause from WhereCondition[] using ? placeholders.
+ *
+ * @param conditions - Array of WhereCondition objects to convert to SQL.
+ * @returns An object containing the SQL clause string and bound values array.
+ */
+function buildWhere(conditions) {
+    if (conditions.length === 0) {
+        return { clause: '', values: [] };
+    }
+    const parts = [];
+    const values = [];
+    for (const cond of conditions) {
+        assertSafeIdentifier(cond.field);
+        switch (cond.operator) {
+            case '=':
+            case '!=':
+            case '>':
+            case '<':
+            case '>=':
+            case '<=':
+                // A list given to a one-value operator matches nothing on every store: say so, the way
+                // 'in' given a scalar does.
+                if (Array.isArray(cond.value)) {
+                    throw new Error(`'${cond.operator}' operator takes one value, not a list (field "${cond.field}"); use 'in' for a list`);
+                }
+                parts.push(`"${cond.field}" ${cond.operator} ?`);
+                values.push(cond.value);
+                break;
+            case 'in': {
+                const arr = cond.value;
+                if (!Array.isArray(arr)) {
+                    throw new Error(`'${cond.operator}' operator requires an array value (field "${cond.field}")`);
+                }
+                if (arr.length === 0) {
+                    // `IN ()` is a syntax error; match Postgres `= ANY('{}')` semantics: no match.
+                    parts.push('1 = 0');
+                    break;
+                }
+                const placeholders = arr.map(() => '?').join(', ');
+                parts.push(`"${cond.field}" IN (${placeholders})`);
+                values.push(...arr);
+                break;
+            }
+            case 'not_in': {
+                const arr = cond.value;
+                if (!Array.isArray(arr)) {
+                    throw new Error(`'${cond.operator}' operator requires an array value (field "${cond.field}")`);
+                }
+                if (arr.length === 0) {
+                    // `NOT IN ()` is a syntax error; match Postgres `!= ALL('{}')`: everything matches.
+                    parts.push('1 = 1');
+                    break;
+                }
+                const placeholders = arr.map(() => '?').join(', ');
+                parts.push(`"${cond.field}" NOT IN (${placeholders})`);
+                values.push(...arr);
+                break;
+            }
+            case 'like':
+                // Case-insensitive RAW pattern match — the caller supplies the full SQL
+                // pattern (their own %/_ wildcards are honored, NOT escaped). LOWER()
+                // both sides for the documented core contract: `like` must be
+                // case-insensitive and IDENTICAL across every bond (DuckDB's own LIKE
+                // is case-sensitive; ILIKE exists but LIKE + LOWER() keeps the exact
+                // sqlite/mysql spelling of the contract). ESCAPE '\' pins backslash as
+                // THE escape character in the caller's pattern.
+                parts.push(`LOWER("${cond.field}") LIKE LOWER(?) ESCAPE '\\'`);
+                values.push(cond.value);
+                break;
+            case 'ilike':
+                // Case-insensitive CONTAINS on a literal substring — the documented core
+                // contract (`@molecule/api-database` WhereCondition): escape the value's
+                // LIKE metacharacters, wrap with `%…%`.
+                parts.push(`LOWER("${cond.field}") LIKE LOWER(?) ESCAPE '\\'`);
+                values.push(`%${String(cond.value).replace(/[%_\\]/g, '\\$&')}%`);
+                break;
+            case 'is_null':
+                parts.push(`"${cond.field}" IS NULL`);
+                break;
+            case 'is_not_null':
+                parts.push(`"${cond.field}" IS NOT NULL`);
+                break;
+            default:
+                // Parity with the postgres/sqlite bonds: an unknown operator must FAIL
+                // LOUDLY, not silently drop the condition (which would return unfiltered rows).
+                throw new Error(`Invalid SQL operator: ${String(cond.operator)}. The operators are lowercase: =, !=, >, <, >=, <=, in, not_in, like, ilike, is_null, is_not_null.`);
+        }
+    }
+    return { clause: `WHERE ${parts.join(' AND ')}`, values };
+}
+/**
+ * Builds an ORDER BY clause.
+ *
+ * @param orderBy - Array of field/direction pairs to sort by.
+ * @returns A SQL ORDER BY clause string, or an empty string if none provided.
+ */
+function buildOrderBy(orderBy) {
+    if (!orderBy || orderBy.length === 0)
+        return '';
+    return `ORDER BY ${orderBy
+        .map((o) => {
+        assertSafeIdentifier(o.field);
+        // Whitelist the direction to exactly ASC/DESC — never interpolate an
+        // arbitrary `toUpperCase()` of caller input into the SQL string.
+        const dir = o.direction.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+        return `"${o.field}" ${dir}`;
+    })
+        .join(', ')}`;
+}
+/**
+ * Creates a DataStore backed by a DuckDB DatabasePool.
+ *
+ * @param pool - The DuckDB DatabasePool to use for queries.
+ * @returns A DataStore that translates CRUD operations to DuckDB-compatible SQL.
+ */
+export function createStore(pool) {
+    // Cache of "this table's JSON-typed columns" so rows read back through the
+    // CRUD helpers carry parsed values, not JSON text.
+    const jsonColumnsCache = new Map();
+    /**
+     * The JSON-typed columns of a table, lower-cased (cached). DuckDB's `JSON`
+     * type is an alias over VARCHAR, so a JSON column reads as its JSON text and
+     * the column's type is visible ONLY in `information_schema.columns` — never
+     * in the result metadata. Without this, a `meta` JSON column round-trips as
+     * a string through `create()`/`findMany()` on this bond while the same row
+     * parses on the postgresql/sqlite bonds.
+     *
+     * @param table - The table name to introspect.
+     * @returns Its JSON-typed column names, lower-cased.
+     */
+    function jsonColumnsFor(table) {
+        const cached = jsonColumnsCache.get(table);
+        if (cached)
+            return cached;
+        const query = pool
+            .query("SELECT column_name FROM information_schema.columns WHERE table_name = ? AND data_type = 'JSON'", [table])
+            .then((result) => new Set(result.rows.map((row) => String(row.column_name).toLowerCase())))
+            .catch((error) => {
+            // A missing table has no JSON columns either; the caller's own query
+            // against it will name the real problem, so only log here.
+            getLogger().warn('DuckDB: could not list JSON columns', {
+                error,
+                table,
+            });
+            return new Set();
+        });
+        jsonColumnsCache.set(table, query);
+        return query;
+    }
+    /**
+     * Run a query for `table`, parsing its JSON columns back into values and
+     * naming the table in a column/table error (DuckDB's "does not exist" errors
+     * name neither — the same gap the sqlite store patches with `queryOn`).
+     *
+     * @param table - The table the statement is for.
+     * @param sql - The statement.
+     * @param values - Its parameters.
+     * @returns The query result with JSON columns parsed.
+     */
+    async function queryOn(table, sql, values) {
+        let result;
+        try {
+            result = await pool.query(sql, values);
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                /does not exist|referenced table .* not found|no matching entry/i.test(error.message) &&
+                !error.message.includes(`(table "${table}")`)) {
+                error.message = `${error.message} (table "${table}")`;
+            }
+            throw error;
+        }
+        return {
+            rows: parseJsonColumns(result.rows, await jsonColumnsFor(table)),
+            rowCount: result.rowCount,
+        };
+    }
+    return {
+        async findById(table, id) {
+            assertSafeIdentifier(table);
+            const result = await queryOn(table, `SELECT * FROM "${table}" WHERE "id" = ? LIMIT 1`, [
+                id,
+            ]);
+            return result.rows[0] ?? null;
+        },
+        async findOne(table, where) {
+            assertSafeIdentifier(table);
+            assertWhereConditions(where, 'findOne');
+            const { clause, values } = buildWhere(where);
+            const result = await queryOn(table, `SELECT * FROM "${table}" ${clause} LIMIT 1`, values);
+            return result.rows[0] ?? null;
+        },
+        async findMany(table, options) {
+            assertSafeIdentifier(table);
+            assertFindManyOptions(options);
+            const { clause, values } = buildWhere(options?.where ?? []);
+            const selectFields = options?.select
+                ?.map((s) => {
+                assertSafeIdentifier(s);
+                return `"${s}"`;
+            })
+                .join(', ') ?? '*';
+            const orderBy = buildOrderBy(options?.orderBy);
+            // Safety cap: if caller doesn't specify a limit, apply a default to prevent
+            // unbounded queries from returning millions of rows and exhausting memory.
+            const MAX_DEFAULT_LIMIT = 10_000;
+            const effectiveLimit = Math.max(0, Math.min(Number(options?.limit ?? MAX_DEFAULT_LIMIT), MAX_DEFAULT_LIMIT));
+            const limit = `LIMIT ${effectiveLimit}`;
+            // Validate offset as a non-negative integer to prevent SQL injection.
+            const safeOffset = options?.offset != null ? Math.max(0, Math.floor(Number(options.offset))) : 0;
+            const offset = safeOffset > 0 ? `OFFSET ${safeOffset}` : '';
+            const sql = `SELECT ${selectFields} FROM "${table}" ${clause} ${orderBy} ${limit} ${offset}`.trim();
+            const result = await queryOn(table, sql, values);
+            return result.rows;
+        },
+        async count(table, where) {
+            assertSafeIdentifier(table);
+            assertOptionalWhereConditions(where);
+            const { clause, values } = buildWhere(where ?? []);
+            const result = await queryOn(table, `SELECT COUNT(*) AS "count" FROM "${table}" ${clause}`, values);
+            return Number(result.rows[0]?.count ?? 0);
+        },
+        async create(table, data) {
+            assertSafeIdentifier(table);
+            // The documented bare-create pattern — create('table', { ...fields }) with
+            // no explicit id — relies on the row getting an id. A hand-written
+            // migration may declare `id uuid NOT NULL` with no DEFAULT, so generate
+            // one when the caller omits it (no-op when supplied; composite-PK join
+            // tables without an id column are handled by the engine's own error).
+            if (data.id == null) {
+                data = { id: randomUUID(), ...data };
+            }
+            const keys = Object.keys(data);
+            for (const k of keys)
+                assertSafeIdentifier(k);
+            const columns = keys.map((k) => `"${k}"`).join(', ');
+            const placeholders = keys.map(() => '?').join(', ');
+            const values = keys.map((k) => data[k]);
+            const result = await queryOn(table, `INSERT INTO "${table}" (${columns}) VALUES (${placeholders}) RETURNING *`, values);
+            return { data: result.rows[0] ?? null, affected: result.rowCount ?? 0 };
+        },
+        async updateById(table, id, data) {
+            assertSafeIdentifier(table);
+            const keys = Object.keys(data);
+            // No-op when there are no fields to update — return the existing row
+            // so callers see `affected: 1` for known-id reads (parity with the
+            // postgres/sqlite bonds). Issuing an UPDATE with an empty SET clause is
+            // a SQL syntax error.
+            if (keys.length === 0) {
+                const existing = await queryOn(table, `SELECT * FROM "${table}" WHERE "id" = ? LIMIT 1`, [id]);
+                return { data: existing.rows[0] ?? null, affected: existing.rows.length };
+            }
+            for (const k of keys)
+                assertSafeIdentifier(k);
+            const setClauses = keys.map((k) => `"${k}" = ?`).join(', ');
+            const values = [...keys.map((k) => data[k]), id];
+            const result = await queryOn(table, `UPDATE "${table}" SET ${setClauses} WHERE "id" = ? RETURNING *`, values);
+            return { data: result.rows[0] ?? null, affected: result.rowCount ?? 0 };
+        },
+        async updateMany(table, where, data) {
+            assertWhereConditions(where, 'updateMany');
+            // Refuse an empty WHERE — parity with the postgres/sqlite bonds; an empty
+            // `where` would become an UNSCOPED full-table UPDATE.
+            if (where.length === 0) {
+                throw new Error('updateMany requires at least one WHERE condition to prevent accidental full-table updates');
+            }
+            assertSafeIdentifier(table);
+            const keys = Object.keys(data);
+            for (const k of keys)
+                assertSafeIdentifier(k);
+            const setClauses = keys.map((k) => `"${k}" = ?`).join(', ');
+            const setValues = keys.map((k) => data[k]);
+            const { clause, values: whereValues } = buildWhere(where);
+            const values = [...setValues, ...whereValues];
+            const result = await queryOn(table, `UPDATE "${table}" SET ${setClauses} ${clause}`, values);
+            return { data: null, affected: result.rowCount ?? 0 };
+        },
+        async deleteById(table, id) {
+            assertSafeIdentifier(table);
+            const result = await queryOn(table, `DELETE FROM "${table}" WHERE "id" = ?`, [id]);
+            return { data: null, affected: result.rowCount ?? 0 };
+        },
+        async deleteMany(table, where) {
+            assertWhereConditions(where, 'deleteMany');
+            // Refuse an empty WHERE — parity with the postgres/sqlite bonds (else an
+            // empty `where` becomes an UNSCOPED full-table DELETE).
+            if (where.length === 0) {
+                throw new Error('deleteMany requires at least one WHERE condition to prevent accidental full-table deletes');
+            }
+            assertSafeIdentifier(table);
+            const { clause, values } = buildWhere(where);
+            const result = await queryOn(table, `DELETE FROM "${table}" ${clause}`, values);
+            return { data: null, affected: result.rowCount ?? 0 };
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Type definitions for the DuckDB database provider.
+ *
+ * @module
+ */
+/**
+ * Configuration for the DuckDB database provider.
+ */
+export interface DuckdbConfig {
+    /**
+     * Path of the DuckDB database file — created on first open — or `':memory:'`
+     * for a database that lives only for the process's lifetime. Defaults to the
+     * `DUCKDB_PATH` env var, then `'./data/app.duckdb'`.
+     */
+    path?: string;
+    /**
+     * DuckDB `memory_limit` for the instance. DuckDB's own default is 80% of
+     * system RAM, which on a shared VM lets one query evict everything else, so
+     * this bond caps it at `'1GB'` by default. Accepts DuckDB size strings
+     * (`'512MB'`, `'2GB'`) or a plain byte count as a string. Also settable via
+     * the `DUCKDB_MEMORY_LIMIT` env var.
+     */
+    memoryLimit?: string;
+    /**
+     * DuckDB `threads` for the instance. DuckDB's own default is every CPU core,
+     * which oversubscribes a shared host, so this bond caps it at `4` by default.
+     * Also settable via the `DUCKDB_THREADS` env var.
+     */
+    threads?: number;
+    /**
+     * Open the database read-only (`access_mode = 'READ_ONLY'`). Multiple
+     * processes may read one file concurrently; only read-write mode is
+     * exclusive, so a read-only pool never fights an app holding the write lock.
+     */
+    readOnly?: boolean;
+    /**
+     * Extra DuckDB settings handed to `DuckDBInstance.fromCache(path, options)`
+     * as-is (a flat `Record<string, string>` of setting name → value). Entries
+     * here win over the `memoryLimit`/`threads`/`readOnly` fields.
+     */
+    config?: Record<string, string>;
+    /**
+     * How long (ms) a query, `connect()` or `transaction()` waits for the single
+     * connection before failing with an error that says who is holding it.
+     * Defaults to 30 000.
+     */
+    acquireTimeoutMillis?: number;
+}
+/**
+ * Environment variables consumed by the DuckDB database provider.
+ */
+export interface ProcessEnv {
+    DUCKDB_PATH?: string;
+    DUCKDB_MEMORY_LIMIT?: string;
+    DUCKDB_THREADS?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the DuckDB database provider.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utilities.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Utility functions for DuckDB operations.
+ *
+ * @module
+ */
+import { type DuckDBValue } from '@duckdb/node-api';
+import type { SqlCompatibilityIssue, SqlFeature } from '@molecule/api-database/sql-compatibility.js';
+/**
+ * Options for {@link translateDdlToDuckdb}.
+ */
+export interface TranslateDdlOptions {
+    /** File name the SQL came from; copied into an unsupported-construct error. */
+    source?: string;
+}
+/**
+ * The error this bond's translator throws when a migration needs a construct
+ * DuckDB cannot honour. Named and typed so a caller can tell a genuine dialect
+ * limit apart from malformed SQL, and report it without a migration run.
+ *
+ * The diagnostic itself is described by the core TYPE contract
+ * ({@link SqlCompatibilityIssue}); this class is the bond's own error
+ * construction, next to the translation that raises it.
+ */
+export declare class UnsupportedSqlFeatureError extends Error {
+    /** The construct's feature. */
+    readonly feature: SqlFeature;
+    /** The exact construct found in the migration. */
+    readonly detail: string;
+    /** Where the statement came from, when known. */
+    readonly source?: string;
+    /**
+     * Build the error from a compatibility diagnostic, copying its message and fields.
+     *
+     * @param issue - The diagnostic being refused.
+     */
+    constructor(issue: SqlCompatibilityIssue);
+}
+/**
+ * Translate PostgreSQL-dialect DDL to DuckDB-compatible DDL at migration time.
+ *
+ * Resource/template setup migrations are authored in PostgreSQL dialect. DuckDB
+ * 2.0 already speaks most of it natively — `uuid`/`timestamptz`/`bytea`/`text[]`
+ * type names, `gen_random_uuid()`, `now()`, `CURRENT_TIMESTAMP`, `::` casts,
+ * `ADD COLUMN IF NOT EXISTS`, `DROP COLUMN IF EXISTS`, `ON CONFLICT`, `ILIKE` —
+ * all verified against 2.0.0-r.1. The constructs it rejects are rewritten here,
+ * and only where the rewrite preserves behaviour:
+ *
+ * - `jsonb` → `json`, in both the column-type position and the `::jsonb` cast
+ *   (DuckDB has a `JSON` type, stored as VARCHAR; there is no `jsonb`).
+ * - `USING <method>` on a `CREATE INDEX` (`gin`/`btree`/`hash`/`gist`) →
+ *   removed: DuckDB indexes have no access method.
+ * - A partial index gets no `WHERE` support in DuckDB. A non-unique partial
+ *   index becomes a full index on the same columns — the predicate only narrows
+ *   which rows the index covers, never a query's result. A UNIQUE partial index
+ *   becomes a UNIQUE index over `CASE WHEN <predicate> THEN <column> END` per
+ *   column: rows outside the predicate get NULL keys (distinct in DuckDB), so
+ *   uniqueness applies to exactly the rows PostgreSQL would constrain.
+ *
+ * What it does NOT rewrite is an `ON DELETE`/`ON UPDATE` referential action
+ * (`CASCADE`, `SET NULL`, `SET DEFAULT`): DuckDB rejects the clause at parse
+ * time and has no triggers, so dropping it would turn a cascading delete into a
+ * refusing one. Such SQL throws {@link UnsupportedSqlFeatureError}, naming the
+ * construct — see {@link sqlCapabilities}. The compatibility preflight in the
+ * generator rejects those resource/provider combinations before an app exists;
+ * this throw is the last line of defence for SQL that reaches the runner another
+ * way.
+ *
+ * Everything else passes through untouched — unlike the sqlite bond, no
+ * placeholder conversion or timestamp-default rewriting happens here.
+ *
+ * @param sql - Raw migration SQL, possibly in Postgres dialect.
+ * @param options - The source file name used in an unsupported-construct error.
+ * @returns DuckDB-compatible SQL.
+ * @throws {UnsupportedSqlFeatureError} When the SQL needs a construct DuckDB
+ *   cannot reproduce without changing its behaviour.
+ */
+export declare const translateDdlToDuckdb: (sql: string, options?: TranslateDdlOptions) => string;
+/**
+ * Coerce a JS value into something `@duckdb/node-api` can bind. The client
+ * infers a parameter's type from the VALUE and only understands `null`,
+ * booleans, numbers, bigints and strings — anything else fails at bind time
+ * with `Cannot create values of type ANY. Specify a specific type.`, which
+ * would crash every `create()`/`update()` that passes a `Date`, a boolean-ish
+ * object or a jsonb value. Strings cast on the way in: DuckDB implicitly casts
+ * a bound VARCHAR to UUID/TIMESTAMPTZ/DECIMAL/JSON/LIST parameters, verified
+ * against 2.0.0-r.1.
+ *
+ * @param value - The value to bind.
+ * @returns A `@duckdb/node-api`-bindable value.
+ */
+export declare const coerceDuckdbParam: (value: unknown) => DuckDBValue;
+/**
+ * Normalize DuckDB result rows to the JS shapes the other database bonds hand
+ * back. DuckDB's JS conversion returns a `bigint` for every 64+-bit integer —
+ * `COUNT(*)`, `BIGINT` and `HUGEINT` columns — and `JSON.stringify` THROWS on a
+ * bigint, so a handler that serializes a row with `COUNT(*)` in it would 500.
+ * A bigint within `Number.MAX_SAFE_INTEGER` becomes a JS number (matching the
+ * sqlite bond); a larger one becomes its decimal string (matching node-postgres
+ * `int8AsString`). Mutates rows in place for speed.
+ *
+ * @param rows - Row objects from `result.getRowObjectsJS()`.
+ * @returns The normalized rows.
+ */
+export declare const normalizeDuckdbRows: <T>(rows: Record<string, unknown>[]) => T[];
+/**
+ * Parse the JSON-typed columns of a table's rows into values, matching what
+ * the postgresql/sqlite bonds hand back from a `json`/`jsonb` column. DuckDB's
+ * `JSON` type is an alias over VARCHAR, so a JSON column always READS as its
+ * JSON text — the column's type is only visible in
+ * `information_schema.columns.data_type`, never in the result metadata, which
+ * is why this runs in the DataStore (it knows the table) and not in the pool.
+ * A value that is not valid JSON text is left as the raw string.
+ *
+ * @param rows - Row objects.
+ * @param jsonColumns - The table's JSON-typed column names, lower-cased.
+ * @returns The rows with JSON columns parsed.
+ */
+export declare const parseJsonColumns: <T>(rows: Record<string, unknown>[], jsonColumns: Set<string>) => T[];
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,6CAA6C,CAAA;AAUpG;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IAExB;;;;OAIG;gBACS,KAAK,EAAE,qBAAqB;CAOzC;AAqCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,EAAE,UAAS,mBAAwB,KAAG,MAarF,CAAA;AAqCD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,WAiBlD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAG,CAAC,EAazE,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAChC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,aAAa,GAAG,CAAC,MAAM,CAAC,KACvB,CAAC,EAgBH,CAAA"}