@nshiab/simple-data-analysis-core 2.0.5 → 2.0.7

package/esm/helpers/printTable.js

@@ -1,15 +1,17 @@
+import LogValue from "./LogValue.js";
 import wrapString from "./wrapString.js";
 /**
  * Prints a formatted table to the console with support for word wrapping
- * within cells. Unlike `console.table()`, this function properly handles
- * multi-line content within cells, making it ideal for displaying data with
- * long text values.
+ * within headers and cells. Unlike `console.table()`, this function properly
+ * handles multi-line content, making it ideal for displaying data with long
+ * column names and text values.
  *
  * @param data - An array of objects representing the rows of the table. Each
  *   object should have string keys.
  * @param options - Optional configuration for table rendering.
  * @param options.maxColumnWidth - The maximum width for any column (default:
- *   `75`). Values exceeding this width will be wrapped at word boundaries.
+ *   `75`). Headers and values exceeding this width will be wrapped at word
+ *   boundaries.
  * @param options.minColumnWidth - The minimum width for any column (default:
  *   `3`).
  * @param options.typesRowIndex - The index of a row that contains type
@@ -47,8 +49,12 @@ export default function printTable(data, options) {
     const minColumnWidth = options?.minColumnWidth ?? 3;
     // Helper function to format values for display
     const formatValue = (value) => {
+        if (value instanceof LogValue)
+            return value.text;
         if (value instanceof Date) {
-            return value.toISOString();
+            return Number.isNaN(value.getTime())
+                ? "Invalid Date"
+                : value.toISOString();
         }
         return String(value);
     };
@@ -62,7 +68,7 @@ export default function printTable(data, options) {
     // First, seed widths from header names.
     const columnWidths = {};
     for (const col of columns) {
-        columnWidths[col] = col.length;
+        columnWidths[col] = Math.max(...col.split("\n").map((line) => line.length));
     }
     // Format every cell, track the longest raw line per column, and
     // store the formatted strings for the wrapping step that follows.
@@ -90,31 +96,16 @@ export default function printTable(data, options) {
     for (const col of columns) {
         columnWidths[col] = Math.min(Math.max(columnWidths[col], minColumnWidth), maxColumnWidth);
     }
-    // Wrap pre-formatted strings into multi-line cells
-    const wrappedData = [];
-    for (let r = 0; r < formattedData.length; r++) {
-        const wrappedRow = {};
-        for (let c = 0; c < columns.length; c++) {
-            const col = columns[c];
-            const value = formattedData[r][c];
-            const width = columnWidths[col];
-            // Split by existing newlines, then wrap each part
-            const lines = value.split("\n");
-            const allWrappedLines = [];
-            for (const line of lines) {
-                if (line.length <= width) {
-                    allWrappedLines.push(line);
-                }
-                else {
-                    // Wrap long lines at word boundaries
-                    const wrapped = wrapString(line, width);
-                    allWrappedLines.push(...wrapped.split("\n"));
-                }
-            }
-            wrappedRow[col] = allWrappedLines.length > 0 ? allWrappedLines : [""];
-        }
-        wrappedData.push(wrappedRow);
-    }
+    // Use the same newline and word wrapping rules for headers and cells.
+    const wrapCell = (value, width) => {
+        const lines = value.split("\n").flatMap((line) => line.length <= width ? [line] : wrapString(line, width).split("\n"));
+        return lines.length > 0 ? lines : [""];
+    };
+    const wrappedHeaders = columns.map((col) => wrapCell(col, columnWidths[col]));
+    const wrappedData = formattedData.map((row) => Object.fromEntries(columns.map((col, c) => [
+        col,
+        wrapCell(row[c], columnWidths[col]),
+    ])));
     // ANSI color codes (matching Deno's console colors)
     const colors = {
         reset: "\x1b[0m",
@@ -130,6 +121,8 @@ export default function printTable(data, options) {
     const getColorForValue = (value, isTypeRow) => {
         if (isTypeRow)
             return colors.grey;
+        if (value instanceof LogValue)
+            return colors[value.category];
         if (value === null || value === undefined)
             return colors.null;
         if (value instanceof Date)
@@ -157,11 +150,14 @@ export default function printTable(data, options) {
     };
     // Print top border
     console.log(createTopBorder());
-    // Print header row (bold)
-    const headerParts = columns.map((col) => ` ${colors.bold}${pad(col, columnWidths[col])}${colors.reset} `);
-    console.log(colors.grey + "│" + colors.reset +
-        headerParts.join(colors.grey + "│" + colors.reset) + colors.grey + "│" +
-        colors.reset);
+    // Print each header line in bold, padding shorter headers to the same height.
+    const headerHeight = Math.max(...wrappedHeaders.map((lines) => lines.length));
+    for (let lineIdx = 0; lineIdx < headerHeight; lineIdx++) {
+        const headerParts = columns.map((col, c) => ` ${colors.bold}${pad(wrappedHeaders[c][lineIdx] ?? "", columnWidths[col])}${colors.reset} `);
+        console.log(colors.grey + "│" + colors.reset +
+            headerParts.join(colors.grey + "│" + colors.reset) + colors.grey + "│" +
+            colors.reset);
+    }
     // Detect if any row has word wrapping (spans multiple lines)
     let hasWordWrapping = false;
     for (const wrappedRow of wrappedData) {

package/esm/helpers/queryDB.js

@@ -60,7 +60,7 @@ export default async function queryDB(simple, query, options) {
     // operations queued by sync builder methods, preserving program order.
     await flushAllTables(simple instanceof SimpleTable ? simple.sdb : simple);
     if (options.noClean !== true) {
-        query = cleanSQL(query);
+        query = cleanSQL(query, sdb.expressionSyntax);
     }
     const executionOptions = {
         ...options,

package/esm/helpers/queueAsyncBarrier.d.ts

@@ -11,6 +11,10 @@ import type SimpleTable from "../class/SimpleTable.js";
  * drained are discarded. Operations drained by an observer inside `execute`
  * remain applied; an asynchronous barrier does not provide database rollback.
  *
+ * This differs from a failure while executing queued builders: during replay,
+ * the failing table's remaining chain is aborted, but unexecuted work for other
+ * tables is requeued for their next observation.
+ *
  * @param simpleTable - The table whose chain owns the asynchronous work.
  * @param operation - The asynchronous extension operation to queue.
  * @param operation.method - The public method name used for diagnostics.

package/esm/helpers/queueAsyncBarrier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queueAsyncBarrier.d.ts","sourceRoot":"","sources":["../../src/helpers/queueAsyncBarrier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE;IACT,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,GACA,IAAI,CAKN"}
+{"version":3,"file":"queueAsyncBarrier.d.ts","sourceRoot":"","sources":["../../src/helpers/queueAsyncBarrier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACvC,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE;IACT,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,GACA,IAAI,CAKN"}

package/esm/helpers/queueAsyncBarrier.js

@@ -11,6 +11,10 @@ import queueOp from "./queueOp.js";
  * drained are discarded. Operations drained by an observer inside `execute`
  * remain applied; an asynchronous barrier does not provide database rollback.
  *
+ * This differs from a failure while executing queued builders: during replay,
+ * the failing table's remaining chain is aborted, but unexecuted work for other
+ * tables is requeued for their next observation.
+ *
  * @param simpleTable - The table whose chain owns the asynchronous work.
  * @param operation - The asynchronous extension operation to queue.
  * @param operation.method - The public method name used for diagnostics.

package/esm/helpers/queueOp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queueOp.d.ts","sourceRoot":"","sources":["../../src/helpers/queueOp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMtD;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,WAAW,EAAE,WAAW,EACxB,EAAE,EAAE,cAAc,GACjB,IAAI,CA8CN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,QAAQ,GACZ;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAa7C"}
+{"version":3,"file":"queueOp.d.ts","sourceRoot":"","sources":["../../src/helpers/queueOp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAWtD;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,WAAW,EAAE,WAAW,EACxB,EAAE,EAAE,cAAc,GACjB,IAAI,CAgDN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,QAAQ,GACZ;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAa7C"}

package/esm/helpers/queueOp.js

@@ -1,6 +1,6 @@
 import { ensureTableRegistered, getRegisteredTables } from "./tableRegistry.js";
 import { markTableChanged } from "./tableGeneration.js";
-import { recordCacheTableReferences } from "./cacheTableDependencies.js";
+import { assertCacheTableMutation, captureCacheTableOperation, recordCacheTableOperation, recordCacheTableReferences, } from "./cacheTableDependencies.js";
 import { captureAsyncOperation } from "./asyncOperationContext.js";
 /**
  * Queues an internal relational operation, barrier, or asynchronous barrier.
@@ -8,14 +8,15 @@ import { captureAsyncOperation } from "./asyncOperationContext.js";
  * @internal
  */
 export default function queueOp(simpleTable, op) {
+    assertCacheTableMutation(simpleTable);
     const sdb = simpleTable.sdb;
     if (sdb.lifecycleState !== "open") {
         throw new Error(`${op.method} cannot queue work because its SimpleDB is ${sdb.lifecycleState}.`);
     }
-    let capturedOp = {
+    let capturedOp = captureCacheTableOperation({
         ...op,
         parameters: op.parameters === null ? null : structuredClone(op.parameters),
-    };
+    });
     if (capturedOp.kind === "fusable" || capturedOp.kind === "source") {
         capturedOp = {
             ...capturedOp,
@@ -44,6 +45,7 @@ export default function queueOp(simpleTable, op) {
         ...capturedOp,
         sequence: sdb.opSequence++,
     };
+    recordCacheTableOperation(simpleTable, queuedOp);
     if (captureAsyncOperation(sdb, { table: simpleTable, op: queuedOp })) {
         return;
     }

package/esm/helpers/readMutationRows.d.ts

@@ -0,0 +1,9 @@
+import { type DuckDBConnection, type DuckDBType, type DuckDBValue } from "@duckdb/node-api";
+/** Reads mutation values, optionally keeping a pagination cursor out of rows. */
+export default function readMutationRows(connection: DuckDBConnection, query: string, cursorColumn?: string): Promise<{
+    rows: Record<string, unknown>[];
+    types: Map<string, DuckDBType>;
+    lastCursorValue: DuckDBValue | undefined;
+    toNative: (value: unknown, type: DuckDBType) => DuckDBValue;
+}>;
+//# sourceMappingURL=readMutationRows.d.ts.map

package/esm/helpers/readMutationRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readMutationRows.d.ts","sourceRoot":"","sources":["../../src/helpers/readMutationRows.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EAKrB,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAE1B,iFAAiF;AACjF,wBAA8B,gBAAgB,CAC5C,UAAU,EAAE,gBAAgB,EAC5B,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM;;;;sBAwDI,OAAO,QAAQ,UAAU,KAAG,WAAW;GA0DjE"}

package/esm/helpers/readMutationRows.js

@@ -0,0 +1,94 @@
+import { DuckDBArrayValue, DuckDBDateValue, DuckDBListValue, DuckDBStructValue, DuckDBTimestampValue, } from "@duckdb/node-api";
+/** Reads mutation values, optionally keeping a pagination cursor out of rows. */
+export default async function readMutationRows(connection, query, cursorColumn) {
+    const result = await connection.run(query);
+    const names = result.deduplicatedColumnNames();
+    const types = result.columnTypes();
+    const cursorIndex = cursorColumn === undefined
+        ? -1
+        : names.indexOf(cursorColumn);
+    let lastCursorValue;
+    const dates = new WeakMap();
+    const convert = (value) => {
+        if (value instanceof DuckDBDateValue || value instanceof DuckDBTimestampValue) {
+            const millis = value instanceof DuckDBDateValue
+                ? value.days * 86400000
+                : Number(value.micros >= 0n
+                    ? value.micros / 1000n
+                    : (value.micros - 999n) / 1000n);
+            const date = new Date(millis);
+            // Infinite/out-of-range dates retain their native representation.
+            if (!Number.isFinite(date.getTime()))
+                return value;
+            dates.set(date, { millis, value });
+            return date;
+        }
+        if (value instanceof DuckDBArrayValue || value instanceof DuckDBListValue) {
+            return value.items.map(convert);
+        }
+        if (value instanceof DuckDBStructValue) {
+            return Object.fromEntries(Object.entries(value.entries).map(([key, item]) => [key, convert(item)]));
+        }
+        // In particular, decimals and high-resolution temporal values stay native.
+        return value;
+    };
+    const rows = [];
+    while (true) {
+        const chunk = await result.fetchChunk();
+        if (!chunk || chunk.rowCount === 0)
+            break;
+        const offset = rows.length;
+        for (let i = 0; i < chunk.rowCount; i++)
+            rows.push({});
+        for (let i = 0; i < names.length; i++) {
+            if (i === cursorIndex) {
+                lastCursorValue = chunk.getColumnVector(i).getItem(chunk.rowCount - 1);
+                continue;
+            }
+            chunk.visitColumnValues(i, (value, row) => {
+                rows[offset + row][names[i]] = convert(value);
+            });
+        }
+    }
+    const toNative = (value, type) => {
+        if (value === null || value === undefined)
+            return null;
+        if (value instanceof Date) {
+            const original = dates.get(value);
+            if (original && value.getTime() === original.millis &&
+                type.toString() ===
+                    (original.value instanceof DuckDBDateValue ? "DATE" : "TIMESTAMP")) {
+                return original.value;
+            }
+            if (type.toString() === "DATE") {
+                if (value.getTime() % 86400000 !== 0) {
+                    throw new Error("DATE values must represent midnight UTC.");
+                }
+                return new DuckDBDateValue(value.getTime() / 86400000);
+            }
+            return new DuckDBTimestampValue(BigInt(value.getTime()) * 1000n);
+        }
+        if (Array.isArray(value) && "valueType" in type) {
+            if ("length" in type && value.length !== type.length) {
+                throw new Error(`Expected ${type.length} array elements for ${type}.`);
+            }
+            const items = value.map((item) => toNative(item, type.valueType));
+            return "length" in type
+                ? new DuckDBArrayValue(items)
+                : new DuckDBListValue(items);
+        }
+        if (typeof value === "object" && "entryNames" in type && "entryTypes" in type) {
+            return new DuckDBStructValue(Object.fromEntries(type.entryNames.map((name, i) => [
+                name,
+                toNative(value[name], type.entryTypes[i]),
+            ])));
+        }
+        return value;
+    };
+    return {
+        rows,
+        types: new Map(names.flatMap((name, i) => i === cursorIndex ? [] : [[name, types[i]]])),
+        lastCursorValue,
+        toNative,
+    };
+}

package/esm/helpers/referencedTables.d.ts

@@ -0,0 +1,9 @@
+import type SimpleDB from "../class/SimpleDB.js";
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Finds registered table identifiers in SQL, excluding literals and comments.
+ * Matching is conservative: column names and aliases also count as references.
+ * DuckDB folds ASCII letters in both quoted and unquoted identifiers.
+ */
+export default function referencedTables(sql: readonly string[], sdb: SimpleDB): SimpleTable[];
+//# sourceMappingURL=referencedTables.d.ts.map

package/esm/helpers/referencedTables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referencedTables.d.ts","sourceRoot":"","sources":["../../src/helpers/referencedTables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAKvD;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CACtC,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,GAAG,EAAE,QAAQ,GACZ,WAAW,EAAE,CAkBf"}

package/esm/helpers/referencedTables.js

@@ -0,0 +1,22 @@
+import scanSQL from "./scanSQL.js";
+import foldIdentifier from "./foldIdentifier.js";
+import { getRegisteredTables } from "./tableRegistry.js";
+/**
+ * Finds registered table identifiers in SQL, excluding literals and comments.
+ * Matching is conservative: column names and aliases also count as references.
+ * DuckDB folds ASCII letters in both quoted and unquoted identifiers.
+ */
+export default function referencedTables(sql, sdb) {
+    const identifiers = new Set();
+    for (const fragment of sql) {
+        for (const token of scanSQL(fragment)) {
+            if (token.kind === "quoted" && token.text.startsWith('"')) {
+                identifiers.add(foldIdentifier(token.text.slice(1, -1).replaceAll('""', '"')));
+            }
+            else if (token.kind === "sql" && /^[\p{L}_][\p{L}\p{N}_$]*$/u.test(token.text)) {
+                identifiers.add(foldIdentifier(token.text));
+            }
+        }
+    }
+    return getRegisteredTables(sdb).filter((table) => identifiers.has(foldIdentifier(table.name)));
+}

package/esm/helpers/runQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,gBAAgB,EAIrB,KAAK,UAAU,EAEf,KAAK,WAAW,EAIjB,MAAM,kBAAkB,CAAC;AAI1B,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAqDF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAsCjC;AAED,wBAA8B,QAAQ,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,CACP,CA6DA"}
+{"version":3,"file":"runQuery.d.ts","sourceRoot":"","sources":["../../src/helpers/runQuery.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EAIrB,KAAK,UAAU,EAEf,KAAK,WAAW,EAIjB,MAAM,kBAAkB,CAAC;AAI1B,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AA8CF,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAoCjC;AAED,wBAA8B,QAAQ,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CACN;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,CACP,CAoEA"}

package/esm/helpers/runQuery.js

@@ -1,3 +1,4 @@
+import makeLogConverter from "./makeLogConverter.js";
 import quoteIdentifier from "./quoteIdentifier.js";
 import { DuckDBTimestampValue, DuckDBTypeId, JsonDuckDBValueConverter, } from "@duckdb/node-api";
 import SDAError from "../class/SDAError.js";
@@ -5,20 +6,14 @@ import observeQuery from "./observeQuery.js";
 const msPerDay = 24 * 60 * 60 * 1000;
 const maxSafeInteger = BigInt(Number.MAX_SAFE_INTEGER);
 const minSafeInteger = BigInt(Number.MIN_SAFE_INTEGER);
-// Columns already warned about for precision loss (keyed by table and
-// column), so each column warns only once.
-const warnedUnsafeIntegerColumns = new Set();
 function makeIntegerConverter(columnName, tableName) {
-    const warnKey = `${tableName ?? ""}\0${columnName}`;
     return (value) => {
         if (value === null) {
             return null;
         }
         const bigintValue = value;
-        if ((bigintValue > maxSafeInteger || bigintValue < minSafeInteger) &&
-            !warnedUnsafeIntegerColumns.has(warnKey)) {
-            warnedUnsafeIntegerColumns.add(warnKey);
-            console.warn(`SDA: Column ${quoteIdentifier(columnName)}${tableName === null ? "" : ` of table ${quoteIdentifier(tableName)}`} has at least one value exceeding Number.MAX_SAFE_INTEGER. Converted numbers may lose precision.`);
+        if (bigintValue > maxSafeInteger || bigintValue < minSafeInteger) {
+            throw new RangeError(`SDA: Column ${quoteIdentifier(columnName)}${tableName === null ? "" : ` of table ${quoteIdentifier(tableName)}`} contains ${bigintValue} outside JavaScript's safe integer range (Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER). Cast the column to VARCHAR to retrieve exact digits.`);
         }
         return Number(bigintValue);
     };
@@ -41,10 +36,6 @@ export function makeConverter(type, columnName, tableName = null) {
         const placeholder = `GEOM(${typeString.replace("GEOMETRY('", "").replace("')", "")})`;
         return (value) => (value === null ? null : placeholder);
     }
-    if (typeString.includes("FLOAT[")) {
-        const placeholder = `<${typeString}>`;
-        return (value) => (value === null ? null : placeholder);
-    }
     switch (type.typeId) {
         case DuckDBTypeId.DATE:
             return (value) => value === null
@@ -65,6 +56,8 @@ export function makeConverter(type, columnName, tableName = null) {
             return utcTimestampTzValue;
         case DuckDBTypeId.BIGINT:
         case DuckDBTypeId.HUGEINT:
+        case DuckDBTypeId.UBIGINT:
+        case DuckDBTypeId.UHUGEINT:
             return makeIntegerConverter(columnName, tableName);
         default:
             return (value) => utcJsonValueConverter(value, type, utcJsonValueConverter);
@@ -84,7 +77,12 @@ export default async function runQuery(query, connection, returnData, options) {
                 columnTypes.some((type) => type.toString().toLowerCase().includes("geometry"))) {
                 throw new Error("The query returns geometry columns. Use getGeoData() instead.");
             }
-            const converters = columnTypes.map((type, i) => makeConverter(type, columnNames[i], options.table ?? null));
+            const logging = options.method === "log()" ||
+                options.method === "logBottom()";
+            const converters = columnTypes.map((type, i) => {
+                const converter = makeConverter(type, columnNames[i], options.table ?? null);
+                return logging ? makeLogConverter(type, converter) : converter;
+            });
             const columnCount = columnNames.length;
             // The result is converted chunk by chunk, so no intermediate row-major
             // copy of the whole result is materialized.

package/esm/helpers/scanSQL.d.ts

@@ -0,0 +1,7 @@
+type Token = {
+    text: string;
+    kind: "sql" | "quoted" | "trivia";
+};
+export default function scanSQL(query: string): Token[];
+export {};
+//# sourceMappingURL=scanSQL.d.ts.map

package/esm/helpers/scanSQL.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanSQL.d.ts","sourceRoot":"","sources":["../../src/helpers/scanSQL.ts"],"names":[],"mappings":"AAAA,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;CAAE,CAAC;AAIjE,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,CA0DtD"}

package/esm/helpers/scanSQL.js

@@ -0,0 +1,71 @@
+// Keep opaque SQL regions byte-for-byte intact. Only SQL tokens participate in
+// normalization; parameter values never enter this module.
+export default function scanSQL(query) {
+    const tokens = [];
+    let i = 0;
+    while (i < query.length) {
+        const start = i;
+        let kind = "sql";
+        const rest = query.slice(i);
+        if (/\s/.test(query[i])) {
+            kind = "trivia";
+            while (i < query.length && /\s/.test(query[i]))
+                i++;
+        }
+        else if (rest.startsWith("--")) {
+            kind = "trivia";
+            while (i < query.length && !/[\r\n]/.test(query[i]))
+                i++;
+        }
+        else if (rest.startsWith("/*")) {
+            kind = "trivia";
+            i += 2;
+            let depth = 1;
+            while (i < query.length && depth > 0) {
+                if (query.startsWith("/*", i)) {
+                    depth++;
+                    i += 2;
+                }
+                else if (query.startsWith("*/", i)) {
+                    depth--;
+                    i += 2;
+                }
+                else
+                    i++;
+            }
+        }
+        else if (/^[eE]'/.test(rest) || query[i] === "'" || query[i] === '"') {
+            kind = "quoted";
+            const escaped = /^[eE]'/.test(rest);
+            if (escaped)
+                i++;
+            const quote = query[i++];
+            while (i < query.length) {
+                if (escaped && query[i] === "\\")
+                    i = Math.min(i + 2, query.length);
+                else if (query[i++] === quote) {
+                    if (query[i] === quote)
+                        i++;
+                    else
+                        break;
+                }
+            }
+        }
+        else {
+            // DuckDB permits non-ASCII characters in dollar tags, including
+            // combining marks and characters outside the Unicode letter categories.
+            const dollar = rest.match(/^\$(?:[A-Za-z_\u0080-\uFFFF][A-Za-z_0-9\u0080-\uFFFF]*)?\$/)?.[0];
+            if (dollar) {
+                kind = "quoted";
+                const end = query.indexOf(dollar, i + dollar.length);
+                i = end === -1 ? query.length : end + dollar.length;
+            }
+            else {
+                const token = rest.match(/^(?:[\p{L}_][\p{L}\p{N}_$]*|\$(?:[0-9]+|[\p{L}_][\p{L}\p{N}_]*)|!==|===|==|!=|<>|<=|>=|&&|\|\||::)/u)?.[0];
+                i += token?.length ?? 1;
+            }
+        }
+        tokens.push({ text: query.slice(start, i), kind });
+    }
+    return tokens;
+}

package/esm/helpers/tableRegistry.d.ts

@@ -5,5 +5,7 @@ export declare function getRegisteredTables<Table extends SimpleTable>(simpleDB:
 export declare function listRegisteredTables<Table extends SimpleTable>(simpleDB: SimpleDB<Table>): readonly Table[];
 export declare function registerTable<Table extends SimpleTable>(simpleDB: SimpleDB<Table>, table: Table): void;
 export declare function ensureTableRegistered<Table extends SimpleTable>(simpleDB: SimpleDB<Table>, table: Table): void;
+/** Prevents distinct handles from owning the same DuckDB table name. */
+export declare function assertTableNameAvailable(simpleDB: SimpleDB, name: string, renamedTable?: SimpleTable): void;
 export declare function retainRegisteredTables<Table extends SimpleTable>(simpleDB: SimpleDB<Table>, predicate: (table: Table) => boolean): void;
 //# sourceMappingURL=tableRegistry.d.ts.map

package/esm/helpers/tableRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tableRegistry.d.ts","sourceRoot":"","sources":["../../src/helpers/tableRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAevD,wBAAgB,uBAAuB,CAAC,KAAK,SAAS,WAAW,EAC/D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,IAAI,CAEN;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,WAAW,EAC3D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,SAAS,KAAK,EAAE,CAElB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,WAAW,EAC5D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,SAAS,KAAK,EAAE,CAElB;AAED,wBAAgB,aAAa,CAAC,KAAK,SAAS,WAAW,EACrD,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,KAAK,EAAE,KAAK,GACX,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CAAC,KAAK,SAAS,WAAW,EAC7D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,KAAK,EAAE,KAAK,GACX,IAAI,CAKN;AAED,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,WAAW,EAC9D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,GACnC,IAAI,CAUN"}
+{"version":3,"file":"tableRegistry.d.ts","sourceRoot":"","sources":["../../src/helpers/tableRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAiBvD,wBAAgB,uBAAuB,CAAC,KAAK,SAAS,WAAW,EAC/D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,IAAI,CAEN;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,WAAW,EAC3D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,SAAS,KAAK,EAAE,CAElB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,WAAW,EAC5D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxB,SAAS,KAAK,EAAE,CAElB;AAED,wBAAgB,aAAa,CAAC,KAAK,SAAS,WAAW,EACrD,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,KAAK,EAAE,KAAK,GACX,IAAI,CAYN;AAED,wBAAgB,qBAAqB,CAAC,KAAK,SAAS,WAAW,EAC7D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,KAAK,EAAE,KAAK,GACX,IAAI,CAKN;AAED,wEAAwE;AACxE,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,WAAW,GACzB,IAAI,CASN;AAED,wBAAgB,sBAAsB,CAAC,KAAK,SAAS,WAAW,EAC9D,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,GACnC,IAAI,CAUN"}

package/esm/helpers/tableRegistry.js

@@ -1,4 +1,6 @@
 import { markTableChanged } from "./tableGeneration.js";
+import { recordCacheTableCreation } from "./cacheTableDependencies.js";
+import foldIdentifier from "./foldIdentifier.js";
 const registries = new WeakMap();
 function getMutableTables(simpleDB) {
     const tables = registries.get(simpleDB);
@@ -22,15 +24,21 @@ export function registerTable(simpleDB, table) {
         throw new Error(`The table must be an instance of ${TableClass.name}.`);
     }
     const tables = getMutableTables(simpleDB);
-    if (tables.some((registeredTable) => registeredTable.name === table.name)) {
-        throw new Error(`Table ${table.name} already exists.`);
-    }
+    assertTableNameAvailable(simpleDB, table.name);
     tables.push(table);
+    recordCacheTableCreation(table);
 }
 export function ensureTableRegistered(simpleDB, table) {
     const tables = getMutableTables(simpleDB);
     if (!tables.includes(table)) {
-        tables.push(table);
+        registerTable(simpleDB, table);
+    }
+}
+/** Prevents distinct handles from owning the same DuckDB table name. */
+export function assertTableNameAvailable(simpleDB, name, renamedTable) {
+    const normalizedName = foldIdentifier(name);
+    if (getRegisteredTables(simpleDB).some((table) => table !== renamedTable && foldIdentifier(table.name) === normalizedName)) {
+        throw new Error(`Table ${name} already exists.`);
     }
 }
 export function retainRegisteredTables(simpleDB, predicate) {

package/esm/helpers/updateColumnsWithJS.d.ts

@@ -0,0 +1,52 @@
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Generates columns from selected input columns, keeping other SQL values in
+ * DuckDB. Call from an asynchronous extension barrier. The callback must return
+ * one row per input row in the same order; only the declared output columns are
+ * stored. Existing output columns are replaced, with types inferred from the
+ * generated values. Generation runs sequentially in bounded batches (1,000 rows
+ * by default); callbacks must not depend on receiving the whole table. Non-null
+ * output types must agree across batches. All-null batches defer type inference.
+ * Only one batch of inputs and outputs is retained by this helper in JavaScript;
+ * callers must also bound their own buffering. Reads finish before callbacks or
+ * writes use the shared connection. The original table is replaced only after
+ * staging succeeds. Empty tables are unchanged and do not invoke the callback;
+ * outputs that remain null in every batch use VARCHAR.
+ *
+ * Untouched geometry columns remain in DuckDB, preserving their values, types
+ * and CRS without GeoJSON conversion. Geometry columns cannot be selected as
+ * inputs or overwritten as outputs; use updateWithJS() for editable GeoJSON.
+ * This SQL-only preservation path accepts any source CRS.
+ *
+ * @param table - Table to enrich.
+ * @param inputColumns - Columns available to the callback.
+ * @param outputColumns - Generated columns to add or replace.
+ * @param generate - Produces one result per input row, in input order.
+ * @param options - Controls the maximum rows read, generated, and staged at once.
+ * @returns Resolves after merging the generated columns into the table.
+ * @example
+ * ```ts
+ * queueAsyncBarrier(table, {
+ *   method: "label()",
+ *   parameters: null,
+ *   execute: () => updateColumnsWithJS(table, ["name"], ["label"], async (rows) =>
+ *     rows.map((row) => ({ label: String(row.name).toUpperCase() })),
+ *     { batchSize: 500 }),
+ * });
+ * await table.log();
+ * ```
+ */
+export default function updateColumnsWithJS(table: SimpleTable, inputColumns: string[], outputColumns: string[], generate: (rows: {
+    [key: string]: unknown;
+}[]) => Promise<{
+    [key: string]: unknown;
+}[]>, options?: {
+    /** Maximum rows per callback and transfer batch. Defaults to 1,000.
+     * @example
+     * ```ts
+     * { batchSize: 500 }
+     * ```
+     */
+    batchSize?: number;
+}): Promise<void>;
+//# sourceMappingURL=updateColumnsWithJS.d.ts.map

package/esm/helpers/updateColumnsWithJS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateColumnsWithJS.d.ts","sourceRoot":"","sources":["../../src/helpers/updateColumnsWithJS.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAMvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAA8B,mBAAmB,CAC/C,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,aAAa,EAAE,MAAM,EAAE,EACvB,QAAQ,EAAE,CACR,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,KAC/B,OAAO,CAAC;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,CAAC,EAC1C,OAAO,GAAE;IACP;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,IAAI,CAAC,CAoJf"}