@alisio/core 0.1.0-alpha.21 → 0.1.0-alpha.22

package/dist/analysis/data/infer.js

@@ -0,0 +1,118 @@
+/**
+ * Cell conversion, identifier sanitising and type hints of the dataset ingestion (spec §17.2).
+ * Pure functions with no imports, shared by the ingestion engine (a separate process) and the
+ * tests. Values are stored without loss: a cell becomes a number only when its text is a plain
+ * number (no leading zeros, no separators, safe range); otherwise the exact text is kept.
+ */
+/** Plain decimal number: optional minus, no leading zeros, optional fraction and exponent. */
+const NUMBER = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+const INTEGER = /^-?(?:0|[1-9]\d*)$/;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+const BOOLEAN = /^(?:true|false)$/i;
+/**
+ * Converts one CSV/XLSX text cell. Empty → `null`; plain integers in the safe range → INTEGER
+ * (`bigint`, because node:sqlite binds JS numbers as REAL); plain decimals → REAL; anything else
+ * (`007`, `1,234`, `$12`, `N/A`, `-0`, `1e999`, unsafe integers) keeps its exact text. The only
+ * documented normalisation is `1.50` → `1.5`.
+ */
+export function convertCell(raw) {
+    if (raw === "")
+        return null;
+    if (!NUMBER.test(raw))
+        return raw;
+    if (INTEGER.test(raw)) {
+        if (raw === "-0")
+            return raw;
+        const n = Number(raw);
+        return Number.isSafeInteger(n) ? BigInt(raw) : raw;
+    }
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : raw;
+}
+/** A JSON value stored without loss: numbers stay numbers, nested values become JSON text. */
+export function convertJson(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return String(value);
+        return Number.isSafeInteger(value) && !Object.is(value, -0) ? BigInt(value) : value;
+    }
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return JSON.stringify(value);
+}
+/** Whether every non-empty cell of a row is a plain number (then the row is data, not a header). */
+export function looksLikeData(row) {
+    const cells = row.filter((cell) => cell !== "");
+    return cells.length > 0 && cells.every((cell) => NUMBER.test(cell));
+}
+/** `region`, `año` → `ano`, `Total ($)` → `total`; never empty, never starts with a digit. */
+export function sanitizeIdentifier(label, fallback) {
+    let id = label
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 48);
+    if (!id)
+        return fallback;
+    if (/^[0-9]/.test(id))
+        id = `_${id}`;
+    return id;
+}
+/** Deduplicates names in order (`x`, `x_2`, `x_3`); `taken` carries names across calls. */
+export function uniqueName(name, taken) {
+    let candidate = name;
+    for (let n = 2; taken.has(candidate); n++)
+        candidate = `${name}_${n}`;
+    taken.add(candidate);
+    return candidate;
+}
+/**
+ * Type hint of a column from the storage class and value of its first cells (`kind` is SQLite's
+ * `typeof`). All integers → `integer`; all numbers → `real`; all dates / booleans → those;
+ * anything mixed or empty → `text`.
+ */
+export function inferType(sample) {
+    let integers = 0, reals = 0, texts = 0, dates = 0, booleans = 0;
+    for (const { kind, value } of sample) {
+        if (kind === "null")
+            continue;
+        if (kind === "integer")
+            integers++;
+        else if (kind === "real")
+            reals++;
+        else if (kind === "text") {
+            texts++;
+            const text = String(value);
+            if (ISO_DATE.test(text))
+                dates++;
+            else if (BOOLEAN.test(text))
+                booleans++;
+        }
+        else
+            return "text";
+    }
+    const total = integers + reals + texts;
+    if (!total)
+        return "text";
+    if (texts === 0)
+        return reals === 0 ? "integer" : "real";
+    if (integers + reals > 0)
+        return "text";
+    if (dates === texts)
+        return "date";
+    if (booleans === texts)
+        return "boolean";
+    return "text";
+}
+/** Names SQLite reserves for the row id: a column named so would shadow it. */
+export const RESERVED_NAMES = ["rowid", "oid", "_rowid_"];
+/** A fresh set of taken column names, pre-seeded with the reserved ones. */
+export const newTakenNames = () => new Set(RESERVED_NAMES);
+/** Double-quotes an SQL identifier. */
+export const quoteIdent = (name) => `"${name.replaceAll('"', '""')}"`;

package/dist/analysis/data/ingest-worker.d.ts

@@ -0,0 +1,17 @@
+import type { IngestRequest, IngestResult } from "./engine-types.ts";
+declare const sqlite: typeof import("node:sqlite");
+/** Largest JSON document (not JSON Lines) parsed in memory. */
+export declare const MAX_JSON_BYTES: number;
+export declare class EngineError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Opens a writable database for ingestion (a temporary file, journal off). */
+export declare function openWritable(path: string): InstanceType<typeof sqlite.DatabaseSync>;
+/** UTF-8 (with or without BOM), UTF-16 by BOM, or windows-1252 when the bytes are not UTF-8. */
+export declare function detectEncoding(path: string): Promise<string>;
+/** Builds `req.target` from `req.source` and returns what was ingested. */
+export declare function runIngest(req: IngestRequest, progress: (rows: number) => void): Promise<IngestResult>;
+/** Statistics for a database the Python helper wrote (XLSX), plus the metadata keys. */
+export declare function runFinalize(target: string, sourceName: string, sourceSha256: string): IngestResult;
+export {};

package/dist/analysis/data/ingest-worker.js

@@ -0,0 +1,365 @@
+/**
+ * Ingestion side of the data engine (spec §17.2): streams a CSV/TSV/JSON/JSONL file into one
+ * SQLite file with batched inserts in transactions, then computes the statistics. Runs inside the
+ * engine process, never in the host. Values are stored without loss (see `infer.ts`).
+ */
+import { closeSync, createReadStream, openSync, readFileSync, readSync, rmSync, statSync, } from "node:fs";
+import { CsvError, CsvParser, detectDelimiter } from "./csv.js";
+import { convertCell, convertJson, looksLikeData, newTakenNames, quoteIdent, sanitizeIdentifier, uniqueName, } from "./infer.js";
+import { jsonDocumentRecords, LineSplitter, toRecord } from "./json.js";
+import { finalizeDatabase, INGEST_VERSION, META_SCHEMA } from "./stats.js";
+const sqlite = process.getBuiltinModule("node:sqlite");
+/** Largest JSON document (not JSON Lines) parsed in memory. */
+export const MAX_JSON_BYTES = 50 * 1024 * 1024;
+const BATCH_ROWS = 500;
+const MAX_PARAMS = 32_766;
+const COMMIT_ROWS = 5_000;
+export class EngineError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Opens a writable database for ingestion (a temporary file, journal off). */
+export function openWritable(path) {
+    rmSync(path, { force: true });
+    const db = new sqlite.DatabaseSync(path);
+    db.exec("PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF; PRAGMA cache_size=-65536; PRAGMA temp_store=FILE;");
+    return db;
+}
+function head(path, bytes) {
+    const fd = openSync(path, "r");
+    try {
+        const buffer = Buffer.alloc(bytes);
+        const read = readSync(fd, buffer, 0, bytes, 0);
+        return buffer.subarray(0, read);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+async function* chunks(path) {
+    for await (const chunk of createReadStream(path, { highWaterMark: 1024 * 1024 }))
+        yield chunk;
+}
+/** UTF-8 (with or without BOM), UTF-16 by BOM, or windows-1252 when the bytes are not UTF-8. */
+export async function detectEncoding(path) {
+    const start = head(path, 3);
+    if (start[0] === 0xef && start[1] === 0xbb && start[2] === 0xbf)
+        return "utf-8";
+    if (start[0] === 0xff && start[1] === 0xfe)
+        return "utf-16le";
+    if (start[0] === 0xfe && start[1] === 0xff)
+        return "utf-16be";
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    try {
+        for await (const chunk of chunks(path))
+            decoder.decode(chunk, { stream: true });
+        decoder.decode();
+        return "utf-8";
+    }
+    catch {
+        return "windows-1252";
+    }
+}
+async function* textChunks(path, encoding) {
+    const decoder = new TextDecoder(encoding);
+    for await (const chunk of chunks(path)) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (text)
+            yield text;
+    }
+    const rest = decoder.decode();
+    if (rest)
+        yield rest;
+}
+/** Batched multi-row inserts into one table, committing every few thousand rows. */
+class TableWriter {
+    db;
+    table;
+    columns;
+    maxRows;
+    onRows;
+    pending = [];
+    statements = new Map();
+    sinceCommit = 0;
+    rows = 0;
+    constructor(db, table, columns, maxRows, onRows) {
+        this.db = db;
+        this.table = table;
+        this.columns = columns;
+        this.maxRows = maxRows;
+        this.onRows = onRows;
+        db.exec("BEGIN");
+        db.exec(`CREATE TABLE ${quoteIdent(table)}(${columns.map(quoteIdent).join(", ")})`);
+    }
+    statement(count) {
+        let statement = this.statements.get(count);
+        if (!statement) {
+            const group = `(${this.columns.map(() => "?").join(",")})`;
+            statement = this.db.prepare(`INSERT INTO ${quoteIdent(this.table)} VALUES ${Array(count).fill(group).join(",")}`);
+            this.statements.set(count, statement);
+        }
+        return statement;
+    }
+    add(row) {
+        if (this.rows >= this.maxRows)
+            throw new EngineError("ingest_limit", `The file has more than ${this.maxRows} rows`);
+        this.pending.push(row);
+        this.rows++;
+        if (this.pending.length >= Math.min(BATCH_ROWS, Math.floor(MAX_PARAMS / this.columns.length)))
+            this.flush();
+    }
+    flush() {
+        if (!this.pending.length)
+            return;
+        const width = this.columns.length;
+        const params = [];
+        for (const row of this.pending) {
+            for (let i = 0; i < width; i++)
+                params.push(row[i] ?? null);
+        }
+        this.statement(this.pending.length).run(...params);
+        this.sinceCommit += this.pending.length;
+        this.pending = [];
+        if (this.sinceCommit >= COMMIT_ROWS) {
+            this.db.exec("COMMIT");
+            this.db.exec("BEGIN");
+            this.sinceCommit = 0;
+            this.onRows(this.rows);
+        }
+    }
+    /** Adds a column (JSON keys can appear late); queued rows are written first. */
+    addColumn(name) {
+        this.flush();
+        this.db.exec(`ALTER TABLE ${quoteIdent(this.table)} ADD COLUMN ${quoteIdent(name)}`);
+        this.columns = [...this.columns, name];
+        this.statements.clear();
+    }
+    finish() {
+        this.flush();
+        this.db.exec("COMMIT");
+    }
+}
+function register(db, sheetName, ordinal, table, names, labels) {
+    db.prepare("INSERT INTO _alisio_sheets(ordinal,name,table_name,rows,columns) VALUES(?,?,?,0,?)").run(ordinal, sheetName, table, names.length);
+    const insert = db.prepare("INSERT INTO _alisio_columns(table_name,ordinal,name,label,inferred_type) VALUES(?,?,?,?,'text')");
+    names.forEach((name, i) => {
+        insert.run(table, i + 1, name, labels[i] ?? name);
+    });
+}
+async function ingestDelimited(db, req, encoding, onRows) {
+    let sample = "";
+    for await (const text of textChunks(req.source, encoding)) {
+        sample = text.slice(0, 64 * 1024);
+        break;
+    }
+    const delimiter = req.format === "tsv" ? "\t" : detectDelimiter(sample);
+    let writer;
+    let names = [];
+    let labels = [];
+    let irregular = 0;
+    const addRow = (fields) => {
+        if (fields.length !== names.length)
+            irregular++;
+        const values = [];
+        for (let i = 0; i < names.length; i++)
+            values.push(convertCell(fields[i] ?? ""));
+        writer.add(values);
+    };
+    const parser = new CsvParser(delimiter, (fields) => {
+        if (!writer) {
+            if (fields.length > req.limits.maxColumns)
+                throw new EngineError("ingest_limit", `The file has ${fields.length} columns; the limit is ${req.limits.maxColumns}`);
+            const header = !looksLikeData(fields);
+            const taken = newTakenNames();
+            labels = fields.map((cell, i) => (header && cell !== "" ? cell : `column_${i + 1}`));
+            names = labels.map((label, i) => uniqueName(sanitizeIdentifier(label, `column_${i + 1}`), taken));
+            writer = new TableWriter(db, "data", names, req.limits.maxRows, onRows);
+            if (!header)
+                addRow(fields);
+            return;
+        }
+        addRow(fields);
+    }, req.limits.maxCellChars);
+    try {
+        for await (const text of textChunks(req.source, encoding))
+            parser.write(text);
+        parser.end();
+    }
+    catch (error) {
+        if (error instanceof CsvError)
+            throw new EngineError("ingest_limit", error.message);
+        throw error;
+    }
+    if (!writer)
+        throw new EngineError("ingest_invalid", "The file has no rows");
+    writer.finish();
+    return {
+        registered: { table: "data", names, labels, rows: writer.rows },
+        delimiter,
+        irregular,
+    };
+}
+async function ingestJson(db, req, encoding, onRows) {
+    const names = [];
+    const labels = [];
+    const taken = newTakenNames();
+    const index = new Map();
+    let writer;
+    const addRecord = (record) => {
+        const keys = Object.keys(record);
+        const fresh = keys.filter((key) => !index.has(key));
+        if (fresh.length && names.length + fresh.length > req.limits.maxColumns)
+            throw new EngineError("ingest_limit", `The file has more than ${req.limits.maxColumns} distinct keys`);
+        for (const key of fresh) {
+            const name = uniqueName(sanitizeIdentifier(key, `column_${names.length + 1}`), taken);
+            index.set(key, names.length);
+            names.push(name);
+            labels.push(key);
+            if (writer)
+                writer.addColumn(name);
+        }
+        if (!writer) {
+            if (!names.length) {
+                // An empty object is still a row: keep one placeholder-free table of zero columns? Not
+                // representable in SQLite, so skip it.
+                return;
+            }
+            writer = new TableWriter(db, "data", [...names], req.limits.maxRows, onRows);
+        }
+        const values = Array(names.length).fill(null);
+        for (const key of keys)
+            values[index.get(key)] = convertJson(record[key]);
+        writer.add(values);
+    };
+    const lineHandler = () => {
+        let n = 0;
+        return (line) => {
+            n++;
+            if (!line.trim())
+                return;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                throw new EngineError("ingest_invalid", `Line ${n} is not valid JSON`);
+            }
+            addRecord(toRecord(value));
+        };
+    };
+    if (req.format === "jsonl") {
+        const splitter = new LineSplitter(lineHandler());
+        for await (const text of textChunks(req.source, encoding))
+            splitter.write(text);
+        splitter.end();
+    }
+    else {
+        if (statSync(req.source).size > MAX_JSON_BYTES)
+            throw new EngineError("ingest_limit", `A JSON document is read in memory up to ${MAX_JSON_BYTES / (1024 * 1024)} MiB; use JSON Lines for larger files`);
+        const text = new TextDecoder(encoding).decode(readFileSync(req.source));
+        let records;
+        try {
+            records = jsonDocumentRecords(text);
+        }
+        catch {
+            // Several objects on separate lines: JSON Lines with a .json name.
+            const splitter = new LineSplitter(lineHandler());
+            splitter.write(text);
+            splitter.end();
+            records = [];
+        }
+        for (const record of records)
+            addRecord(record);
+    }
+    if (!writer)
+        throw new EngineError("ingest_invalid", "The file has no records");
+    writer.finish();
+    return {
+        registered: { table: "data", names, labels, rows: writer.rows },
+        irregular: 0,
+    };
+}
+/** Builds `req.target` from `req.source` and returns what was ingested. */
+export async function runIngest(req, progress) {
+    const encoding = await detectEncoding(req.source);
+    const db = openWritable(req.target);
+    let lastProgress = 0;
+    const onRows = (rows) => {
+        const now = Date.now();
+        if (now - lastProgress >= 250) {
+            lastProgress = now;
+            progress(rows);
+        }
+    };
+    try {
+        db.exec(META_SCHEMA);
+        let delimiter;
+        let irregular = 0;
+        let registered;
+        if (req.format === "csv" || req.format === "tsv") {
+            const done = await ingestDelimited(db, req, encoding, onRows);
+            registered = done.registered;
+            delimiter = done.delimiter;
+            irregular = done.irregular;
+        }
+        else {
+            const done = await ingestJson(db, req, encoding, onRows);
+            registered = done.registered;
+        }
+        register(db, "data", 1, registered.table, registered.names, registered.labels);
+        const meta = db.prepare("INSERT OR REPLACE INTO _alisio_meta(key,value) VALUES(?,?)");
+        for (const [key, value] of Object.entries({
+            ingest_version: String(INGEST_VERSION),
+            format: req.format,
+            source_name: req.sourceName,
+            source_sha256: req.sourceSha256,
+            encoding,
+            ...(delimiter ? { delimiter } : {}),
+            irregular_rows: String(irregular),
+            created_at: new Date().toISOString(),
+        }))
+            meta.run(key, value);
+        finalizeDatabase(db);
+        const sheets = db
+            .prepare('SELECT name, table_name AS "table", rows, columns FROM _alisio_sheets ORDER BY ordinal')
+            .all();
+        return {
+            sheets: sheets.map((s) => ({ ...s })),
+            encoding,
+            ...(delimiter ? { delimiter } : {}),
+            irregularRows: irregular,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/** Statistics for a database the Python helper wrote (XLSX), plus the metadata keys. */
+export function runFinalize(target, sourceName, sourceSha256) {
+    const db = new sqlite.DatabaseSync(target);
+    try {
+        db.exec("PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF;");
+        db.exec(META_SCHEMA);
+        const meta = db.prepare("INSERT OR REPLACE INTO _alisio_meta(key,value) VALUES(?,?)");
+        for (const [key, value] of Object.entries({
+            ingest_version: String(INGEST_VERSION),
+            format: "xlsx",
+            source_name: sourceName,
+            source_sha256: sourceSha256,
+            encoding: "utf-8",
+            created_at: new Date().toISOString(),
+        }))
+            meta.run(key, value);
+        finalizeDatabase(db);
+        const sheets = db
+            .prepare('SELECT name, table_name AS "table", rows, columns FROM _alisio_sheets ORDER BY ordinal')
+            .all();
+        return { sheets: sheets.map((s) => ({ ...s })), encoding: "utf-8", irregularRows: 0 };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/analysis/data/json.d.ts

@@ -0,0 +1,19 @@
+/**
+ * JSON and JSON Lines helpers of the dataset ingestion (spec §17.2). Pure: the ingestion engine
+ * feeds decoded text and gets records back. Nested values are stored as JSON text by the caller.
+ */
+/** Splits streamed text into lines (`\n` or `\r\n`); the last partial line waits for more text. */
+export declare class LineSplitter {
+    private readonly onLine;
+    private rest;
+    constructor(onLine: (line: string) => void);
+    write(chunk: string): void;
+    end(): void;
+}
+/** A plain object stays as it is; any other JSON value becomes `{ value }`. */
+export declare function toRecord(value: unknown): Record<string, unknown>;
+/**
+ * The records of a JSON document: an array (each element a record) or a single object (one
+ * record). Throws a `SyntaxError` for invalid JSON.
+ */
+export declare function jsonDocumentRecords(text: string): Array<Record<string, unknown>>;

package/dist/analysis/data/json.js

@@ -0,0 +1,44 @@
+/**
+ * JSON and JSON Lines helpers of the dataset ingestion (spec §17.2). Pure: the ingestion engine
+ * feeds decoded text and gets records back. Nested values are stored as JSON text by the caller.
+ */
+/** Splits streamed text into lines (`\n` or `\r\n`); the last partial line waits for more text. */
+export class LineSplitter {
+    onLine;
+    rest = "";
+    constructor(onLine) {
+        this.onLine = onLine;
+    }
+    write(chunk) {
+        const text = this.rest + chunk;
+        let start = 0;
+        for (;;) {
+            const end = text.indexOf("\n", start);
+            if (end < 0)
+                break;
+            const stop = end > start && text.charCodeAt(end - 1) === 13 ? end - 1 : end;
+            this.onLine(text.slice(start, stop));
+            start = end + 1;
+        }
+        this.rest = start === 0 ? text : text.slice(start);
+    }
+    end() {
+        if (this.rest)
+            this.onLine(this.rest.endsWith("\r") ? this.rest.slice(0, -1) : this.rest);
+        this.rest = "";
+    }
+}
+/** A plain object stays as it is; any other JSON value becomes `{ value }`. */
+export function toRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : { value };
+}
+/**
+ * The records of a JSON document: an array (each element a record) or a single object (one
+ * record). Throws a `SyntaxError` for invalid JSON.
+ */
+export function jsonDocumentRecords(text) {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed.map(toRecord) : [toRecord(parsed)];
+}

package/dist/analysis/data/query-worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Query side of the data engine (spec §17.3): runs one read-only statement on a dataset file.
+ * The connection is opened `readOnly`, then `query_only=ON` and `trusted_schema=OFF`; extension
+ * loading stays disabled (the `node:sqlite` default). The host kills the process when a statement
+ * exceeds its time limit: `node:sqlite` offers no interrupt, progress handler or authorizer.
+ */
+import type { QueryRequest, QueryResult } from "./engine-types.ts";
+/** Closes one connection (or all of them): the host does this before deleting a file. */
+export declare function closeConnections(path?: string): void;
+export declare class QueryRejected extends Error {
+}
+export declare function runQuery(req: QueryRequest): QueryResult;

package/dist/analysis/data/query-worker.js

@@ -0,0 +1,75 @@
+import { guardSql } from "./sql-guard.js";
+const sqlite = process.getBuiltinModule("node:sqlite");
+const connections = new Map();
+function connect(path, heapBytes) {
+    let db = connections.get(path);
+    if (!db) {
+        db = new sqlite.DatabaseSync(path, { readOnly: true });
+        db.exec("PRAGMA query_only=ON; PRAGMA trusted_schema=OFF;");
+        if (heapBytes)
+            db.exec(`PRAGMA hard_heap_limit=${Math.floor(heapBytes)};`);
+        connections.set(path, db);
+    }
+    return db;
+}
+/** Closes one connection (or all of them): the host does this before deleting a file. */
+export function closeConnections(path) {
+    for (const [key, db] of connections) {
+        if (path && key !== path)
+            continue;
+        try {
+            db.close();
+        }
+        catch {
+            /* already closed */
+        }
+        connections.delete(key);
+    }
+}
+export class QueryRejected extends Error {
+}
+export function runQuery(req) {
+    let sql = req.sql;
+    if (req.guard) {
+        const guarded = guardSql(sql);
+        if (!guarded.ok)
+            throw new QueryRejected(guarded.reason);
+        sql = guarded.sql;
+    }
+    const db = connect(req.db, req.heapBytes);
+    const statement = db.prepare(sql);
+    statement.setReadBigInts(true);
+    statement.setReturnArrays(true);
+    const columns = statement.columns().map((c) => c.name);
+    const rows = [];
+    let truncated = false;
+    let clipped = false;
+    const cell = (value) => {
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value === "bigint") {
+            const n = Number(value);
+            return Number.isSafeInteger(n) ? n : value.toString();
+        }
+        if (typeof value === "number")
+            return value;
+        if (value instanceof Uint8Array)
+            return `<blob ${value.byteLength} bytes>`;
+        const text = String(value);
+        if (text.length > req.cellChars) {
+            clipped = true;
+            return `${text.slice(0, req.cellChars)}…`;
+        }
+        return text;
+    };
+    // JS numbers bind as REAL, which `LIMIT`/`OFFSET` reject: integral values bind as INTEGER.
+    const bound = (req.params ?? []).map((value) => typeof value === "number" && Number.isSafeInteger(value) ? BigInt(value) : value);
+    for (const row of statement.iterate(...bound)) {
+        if (rows.length >= req.maxRows) {
+            truncated = true;
+            break;
+        }
+        rows.push(row.map(cell));
+    }
+    return { columns, rows, truncated, clipped };
+}