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

package/script/helpers/flushAllTables.js

@@ -7,6 +7,7 @@ exports.runExemptFromFlush = runExemptFromFlush;
 exports.default = flushAllTables;
 const node_async_hooks_1 = require("node:async_hooks");
 const cleanSQL_js_1 = __importDefault(require("./cleanSQL.js"));
+const referencedTables_js_1 = __importDefault(require("./referencedTables.js"));
 const ensureSpatial_js_1 = __importDefault(require("./ensureSpatial.js"));
 const extractTypes_js_1 = __importDefault(require("./extractTypes.js"));
 const mergeOptions_js_1 = __importDefault(require("./mergeOptions.js"));
@@ -147,8 +148,8 @@ async function replayEntries(sdb, pendingEntries) {
             }
             const reads = op.rawSQL === undefined
                 ? []
-                : referencedTables(op.rawSQL, sdb);
-            if (reads.includes(table)) {
+                : (0, referencedTables_js_1.default)(op.rawSQL, sdb);
+            if (op.kind === "fusable" && reads.includes(table)) {
                 // User-supplied SQL referencing the operation's own table must read
                 // the state produced by the previous steps, which a fused chain
                 // can't provide (the name would resolve to the pre-chain table). So
@@ -184,7 +185,8 @@ async function replayEntries(sdb, pendingEntries) {
             if (op.kind === "source") {
                 // A source replaces the target table from an external relation. It
                 // starts a new segment rather than consuming any segment already open
-                // on the same table.
+                // on the same table. A source may read that materialized table itself
+                // (for example, an in-place join) and still fuse with downstream steps.
                 await runOpenSegment();
                 open = { table, ops: [op] };
                 current = null;
@@ -263,23 +265,6 @@ async function drainAsyncOperationFrame(frame) {
         }
     }
 }
-/**
- * Returns the tables of the database whose names appear in the given SQL
- * fragments. Matching is conservative (a column sharing a table's name
- * counts as a reference): a false positive only costs fusion, never
- * correctness.
- */
-function referencedTables(rawSQL, sdb) {
-    const referenced = [];
-    for (const table of (0, tableRegistry_js_1.getRegisteredTables)(sdb)) {
-        const escaped = table.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-        const pattern = new RegExp(`(?<![\\w"])"?${escaped}"?(?![\\w"])`, "i");
-        if (rawSQL.some((sql) => pattern.test(sql))) {
-            referenced.push(table);
-        }
-    }
-    return referenced;
-}
 async function runSegment(table, ops) {
     if (ops.length === 1) {
         await runStepwise(table, ops[0]);
@@ -288,8 +273,7 @@ async function runSegment(table, ops) {
     if (ops.some(needsSpatial)) {
         await (0, ensureSpatial_js_1.default)(table);
     }
-    // Each fragment is cleaned individually: cleanSQL's WHERE handling must not
-    // cross fragment boundaries once they are composed into one statement.
+    // Normalize each fragment once using the database syntax before composition.
     const ctes = [];
     // The schema of the next fragment's input, reused while operations declare
     // they preserve it, so a run of same-shape steps costs at most one
@@ -316,11 +300,21 @@ async function runSegment(table, ops) {
     await executeFused(table, ops, ctes);
 }
 async function compileOp(table, op, ctes, schema) {
+    // Source relations can read tables named s1, s2, etc. A generated CTE must
+    // not shadow those physical inputs, including in later chain fragments.
+    const usedNames = new Set([
+        ...(0, tableRegistry_js_1.getRegisteredTables)(table.sdb).map((input) => input.name.toLowerCase()),
+        ...ctes.map((cte) => cte.alias),
+    ]);
+    let aliasIndex = ctes.length + 1;
+    while (usedNames.has(`s${aliasIndex}`))
+        aliasIndex++;
+    const alias = `s${aliasIndex}`;
     if (op.kind === "source") {
         return {
             cte: {
-                alias: `s${ctes.length + 1}`,
-                select: (0, cleanSQL_js_1.default)(op.buildSelect()),
+                alias,
+                select: (0, cleanSQL_js_1.default)(await op.buildSelect(), table.sdb.expressionSyntax),
                 values: [],
             },
             schema: op.schema ?? null,
@@ -342,15 +336,16 @@ async function compileOp(table, op, ctes, schema) {
                 : null;
     return {
         cte: {
-            alias: `s${ctes.length + 1}`,
-            select: (0, cleanSQL_js_1.default)(op.buildSelect(input, buildSchema)),
+            alias,
+            select: (0, cleanSQL_js_1.default)(op.buildSelect(input, buildSchema), table.sdb.expressionSyntax),
             values: resolveValues(op, buildSchema),
         },
         schema: outputSchema,
     };
 }
 async function executeFused(table, ops, ctes) {
-    const query = `CREATE OR REPLACE TABLE ${(0, quoteIdentifier_js_1.default)(table.name)} AS WITH ${ctes.map((c) => `${(0, quoteIdentifier_js_1.default)(c.alias)} AS (${c.select})`).join(", ")} SELECT * FROM ${(0, quoteIdentifier_js_1.default)(ctes[ctes.length - 1].alias)}`;
+    // A trailing line comment must end before the generated CTE delimiter.
+    const query = `CREATE OR REPLACE TABLE ${(0, quoteIdentifier_js_1.default)(table.name)} AS WITH ${ctes.map((c) => `${(0, quoteIdentifier_js_1.default)(c.alias)} AS (${c.select}\n)`).join(", ")} SELECT * FROM ${(0, quoteIdentifier_js_1.default)(ctes[ctes.length - 1].alias)}`;
     try {
         await (0, queryDB_js_1.default)(table, query, (0, mergeOptions_js_1.default)(table, {
             table: table.name,
@@ -388,7 +383,7 @@ async function runStepwise(table, op) {
     }));
 }
 function needsSpatial(op) {
-    return op.kind === "fusable" && op.needsSpatial === true;
+    return op.needsSpatial === true;
 }
 function resolveValues(op, schema) {
     return typeof op.values === "function" ? op.values(schema) : op.values ?? [];
@@ -401,7 +396,7 @@ function resolveValues(op, schema) {
 async function describeChain(table, ctes) {
     const select = ctes.length === 0
         ? `SELECT * FROM ${(0, quoteIdentifier_js_1.default)(table.name)}`
-        : `WITH ${ctes.map((c) => `${(0, quoteIdentifier_js_1.default)(c.alias)} AS (${c.select})`).join(", ")} SELECT * FROM ${(0, quoteIdentifier_js_1.default)(ctes[ctes.length - 1].alias)}`;
+        : `WITH ${ctes.map((c) => `${(0, quoteIdentifier_js_1.default)(c.alias)} AS (${c.select}\n)`).join(", ")} SELECT * FROM ${(0, quoteIdentifier_js_1.default)(ctes[ctes.length - 1].alias)}`;
     const query = ctes.length === 0
         ? `DESCRIBE ${(0, quoteIdentifier_js_1.default)(table.name)}`
         : `DESCRIBE ${select}`;

package/script/helpers/foldIdentifier.d.ts

@@ -0,0 +1,3 @@
+/** Matches DuckDB's ASCII case folding for quoted and unquoted identifiers. */
+export default function foldIdentifier(identifier: string): string;
+//# sourceMappingURL=foldIdentifier.d.ts.map

package/script/helpers/foldIdentifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldIdentifier.d.ts","sourceRoot":"","sources":["../../src/helpers/foldIdentifier.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/script/helpers/foldIdentifier.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = foldIdentifier;
+/** Matches DuckDB's ASCII case folding for quoted and unquoted identifiers. */
+function foldIdentifier(identifier) {
+    return identifier.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+}

package/script/helpers/geometryFromJSON.d.ts

@@ -0,0 +1,3 @@
+/** Converts validated GeoJSON SQL text to an explicitly typed WGS84 geometry. */
+export default function geometryFromJSON(expression: string): string;
+//# sourceMappingURL=geometryFromJSON.d.ts.map

package/script/helpers/geometryFromJSON.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometryFromJSON.d.ts","sourceRoot":"","sources":["../../src/helpers/geometryFromJSON.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/script/helpers/geometryFromJSON.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = geometryFromJSON;
+/** Converts validated GeoJSON SQL text to an explicitly typed WGS84 geometry. */
+function geometryFromJSON(expression) {
+    return `ST_GeomFromGeoJSON(${expression})::GEOMETRY('EPSG:4326')`;
+}

package/script/helpers/index.d.ts

@@ -20,4 +20,5 @@ export { default as queryDB } from "./queryDB.js";
 export { default as queueAsyncBarrier } from "./queueAsyncBarrier.js";
 export { default as quoteIdentifier } from "./quoteIdentifier.js";
 export { default as stringToArray } from "./stringToArray.js";
+export { default as updateColumnsWithJS } from "./updateColumnsWithJS.js";
 //# sourceMappingURL=index.d.ts.map

package/script/helpers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/script/helpers/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stringToArray = exports.quoteIdentifier = exports.queueAsyncBarrier = exports.queryDB = exports.parseValue = exports.mergeOptions = exports.createDirectory = void 0;
+exports.updateColumnsWithJS = exports.stringToArray = exports.quoteIdentifier = exports.queueAsyncBarrier = exports.queryDB = exports.parseValue = exports.mergeOptions = exports.createDirectory = void 0;
 /**
  * Helper utilities for Simple Data Analysis Core.
  *
@@ -33,3 +33,5 @@ var quoteIdentifier_js_1 = require("./quoteIdentifier.js");
 Object.defineProperty(exports, "quoteIdentifier", { enumerable: true, get: function () { return __importDefault(quoteIdentifier_js_1).default; } });
 var stringToArray_js_1 = require("./stringToArray.js");
 Object.defineProperty(exports, "stringToArray", { enumerable: true, get: function () { return __importDefault(stringToArray_js_1).default; } });
+var updateColumnsWithJS_js_1 = require("./updateColumnsWithJS.js");
+Object.defineProperty(exports, "updateColumnsWithJS", { enumerable: true, get: function () { return __importDefault(updateColumnsWithJS_js_1).default; } });

package/script/helpers/logData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logData.d.ts","sourceRoot":"","sources":["../../src/helpers/logData.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,KAAK,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,IAAI,EACvC,IAAI,EACA;IACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,EAAE,GACD,IAAI,EACR,UAAU,CAAC,EAAE,MAAM,QA4DpB"}
+{"version":3,"file":"logData.d.ts","sourceRoot":"","sources":["../../src/helpers/logData.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,OAAO,CAC7B,KAAK,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,IAAI,EACvC,IAAI,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,EAAE,GAAG,IAAI,EACzC,UAAU,CAAC,EAAE,MAAM,QAkEpB"}

package/script/helpers/logData.js

@@ -4,56 +4,57 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = logData;
+const LogValue_js_1 = __importDefault(require("./LogValue.js"));
 const printTable_js_1 = __importDefault(require("./printTable.js"));
 function logData(types, data, charsToLog) {
     if (data === null) {
         console.log("Data is null");
+        return;
     }
-    else {
-        if (data.length === 0) {
-            console.log(data);
+    if (data.length === 0) {
+        console.log(data);
+        return;
+    }
+    const formatted = data.map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => {
+        const nested = value !== null && typeof value === "object" &&
+            !(value instanceof Date) && !(value instanceof LogValue_js_1.default);
+        let text = value instanceof LogValue_js_1.default
+            ? value.text
+            : nested
+                ? JSON.stringify(value)
+                : value;
+        const truncatable = !(value instanceof LogValue_js_1.default) ||
+            value.category === "string";
+        if (truncatable && typeof text === "string" &&
+            typeof charsToLog === "number" && text.length > charsToLog) {
+            const limit = Math.max(0, Math.floor(charsToLog));
+            text = text.slice(0, Math.max(0, limit - 3)) + "...".slice(0, limit);
         }
-        else {
-            const dataToBeLogged = [];
-            const keys = Object.keys(data[0]);
-            for (let i = 0; i < data.length; i++) {
-                const newItem = {};
-                for (const key of keys) {
-                    if (typeof charsToLog === "number" &&
-                        typeof data[i][key] === "string" &&
-                        data[i][key].length > charsToLog) {
-                        newItem[key] = data[i][key].slice(0, charsToLog) + "...";
-                    }
-                    else {
-                        newItem[key] = data[i][key];
-                    }
-                }
-                dataToBeLogged.push(newItem);
-            }
-            let hasTypesRow = false;
-            if (types !== null) {
-                const columns = Object.keys(types);
-                if (columns.length > 0) {
-                    for (const col of columns) {
-                        if (data[0][col] === "<Geometry>") {
-                            continue;
-                        }
-                        else {
-                            types[col] = types[col] + "/" +
-                                (data[0][col] === null ? null : typeof data[0][col]);
-                        }
-                    }
-                    // Add types as the first row
-                    dataToBeLogged.unshift(types);
-                    hasTypesRow = true;
+        return [
+            key,
+            value instanceof LogValue_js_1.default
+                ? new LogValue_js_1.default(String(text), value.jsType, value.category)
+                : text,
+        ];
+    })));
+    const hasTypes = types !== null && Object.keys(types).length > 0;
+    if (hasTypes) {
+        formatted.unshift(Object.fromEntries(Object.entries(types).map(([key, sqlType]) => {
+            const representations = new Set(data.flatMap((row) => {
+                const value = row[key];
+                if (value instanceof LogValue_js_1.default) {
+                    return value.category === "null" ? [] : [value.jsType];
                 }
-            }
-            (0, printTable_js_1.default)(dataToBeLogged, {
-                ...(typeof charsToLog === "number"
-                    ? { maxColumnWidth: charsToLog }
-                    : {}),
-                ...(hasTypesRow ? { typesRowIndex: 0 } : {}),
-            });
-        }
+                return value === null || value === undefined ? [] : [typeof value];
+            }));
+            const first = data[0][key];
+            const representation = representations.size > 0
+                ? [...representations].join("|")
+                : first instanceof LogValue_js_1.default
+                    ? first.jsType
+                    : "null";
+            return [key, `${sqlType}/${representation}`];
+        })));
     }
+    (0, printTable_js_1.default)(formatted, hasTypes ? { typesRowIndex: 0 } : undefined);
 }

package/script/helpers/makeLogConverter.d.ts

@@ -0,0 +1,5 @@
+import { type DuckDBType, type DuckDBValue } from "@duckdb/node-api";
+import LogValue from "./LogValue.js";
+/** Formats native temporal values before extraction can discard precision. */
+export default function makeLogConverter(type: DuckDBType, convert: (value: DuckDBValue) => unknown): (value: DuckDBValue) => LogValue;
+//# sourceMappingURL=makeLogConverter.d.ts.map

package/script/helpers/makeLogConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"makeLogConverter.d.ts","sourceRoot":"","sources":["../../src/helpers/makeLogConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,QAAQ,MAAM,eAAe,CAAC;AAErC,8EAA8E;AAC9E,MAAM,CAAC,OAAO,UAAU,gBAAgB,CACtC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,GACvC,CAAC,KAAK,EAAE,WAAW,KAAK,QAAQ,CA8DlC"}

package/script/helpers/makeLogConverter.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = makeLogConverter;
+const node_api_1 = require("@duckdb/node-api");
+const LogValue_js_1 = __importDefault(require("./LogValue.js"));
+/** Formats native temporal values before extraction can discard precision. */
+function makeLogConverter(type, convert) {
+    const sqlType = type.toString();
+    const floatArray = sqlType.includes("FLOAT[");
+    const placeholder = sqlType.toLowerCase().includes("geometry") ||
+        floatArray;
+    const temporal = [
+        node_api_1.DuckDBTypeId.DATE,
+        node_api_1.DuckDBTypeId.TIME,
+        node_api_1.DuckDBTypeId.TIME_TZ,
+        node_api_1.DuckDBTypeId.TIME_NS,
+        node_api_1.DuckDBTypeId.TIMESTAMP,
+        node_api_1.DuckDBTypeId.TIMESTAMP_TZ,
+        node_api_1.DuckDBTypeId.TIMESTAMP_S,
+        node_api_1.DuckDBTypeId.TIMESTAMP_MS,
+        node_api_1.DuckDBTypeId.TIMESTAMP_NS,
+    ].includes(type.typeId);
+    const numeric = !placeholder &&
+        /^(TINYINT|SMALLINT|INTEGER|BIGINT|HUGEINT|UTINYINT|USMALLINT|UINTEGER|UBIGINT|UHUGEINT|FLOAT|DOUBLE|DECIMAL|BIGNUM)(\(|$)/
+            .test(sqlType);
+    const jsType = placeholder ? "string" : type.typeId === node_api_1.DuckDBTypeId.DATE ||
+        type.typeId === node_api_1.DuckDBTypeId.TIMESTAMP
+        ? "object"
+        : temporal
+            ? "string"
+            : type.typeId === node_api_1.DuckDBTypeId.BOOLEAN
+                ? "boolean"
+                : numeric
+                    ? (/^(DECIMAL|BIGNUM)/.test(sqlType) ? "string" : "number")
+                    : [
+                        node_api_1.DuckDBTypeId.LIST,
+                        node_api_1.DuckDBTypeId.ARRAY,
+                        node_api_1.DuckDBTypeId.STRUCT,
+                        node_api_1.DuckDBTypeId.MAP,
+                        node_api_1.DuckDBTypeId.UNION,
+                        node_api_1.DuckDBTypeId.INTERVAL,
+                    ].includes(type.typeId)
+                        ? "object"
+                        : "string";
+    return (value) => {
+        if (value === null)
+            return new LogValue_js_1.default("null", jsType, "null");
+        // TIMESTAMPTZ uses the existing UTC converter, independent of process timezone.
+        const converted = floatArray
+            ? `<${sqlType}>`
+            : temporal && type.typeId !== node_api_1.DuckDBTypeId.TIMESTAMP_TZ
+                ? String(value)
+                : convert(value);
+        const text = typeof converted === "object" && converted !== null
+            ? JSON.stringify(converted)
+            : String(converted);
+        return new LogValue_js_1.default(text, 
+        // NaN and infinities are strings in the public JSON conversion.
+        temporal ? jsType : typeof converted, temporal
+            ? "date"
+            : numeric
+                ? "number"
+                : jsType === "boolean"
+                    ? "boolean"
+                    : "string");
+    };
+}

package/script/helpers/osmFiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"osmFiles.d.ts","sourceRoot":"","sources":["../../src/helpers/osmFiles.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,CAAC;AAShD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAe1D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAmBrD;AAED,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IACP,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD,GACA,OAAO,CAAC,MAAM,CAAC,CAmHjB;AAgMD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWjD"}
+{"version":3,"file":"osmFiles.d.ts","sourceRoot":"","sources":["../../src/helpers/osmFiles.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,CAAC;AAShD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAe1D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAmBrD;AAED,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IACP,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD,GACA,OAAO,CAAC,MAAM,CAAC,CAqHjB;AAgMD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWjD"}

package/script/helpers/parseTypes.d.ts

@@ -1,2 +1,2 @@
-export default function parseType(type: "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | `geometry('${string}')` | `GEOMETRY('${string}')`): string;
+export default function parseType(type: "integer" | "float" | "number" | "string" | "date" | "time" | "datetime" | "datetimeTz" | "bigint" | "double" | "varchar" | "timestamp" | "timestamp with time zone" | "boolean" | "json" | "JSON" | `float[${number}]` | `FLOAT[${number}]` | `geometry('${string}')` | `GEOMETRY('${string}')`): string;
 //# sourceMappingURL=parseTypes.d.ts.map

package/script/helpers/parseTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseTypes.d.ts","sourceRoot":"","sources":["../../src/helpers/parseTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,IAAI,EACA,SAAS,GACT,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,0BAA0B,GAC1B,SAAS,GACT,aAAa,MAAM,IAAI,GACvB,aAAa,MAAM,IAAI,UAgC5B"}
+{"version":3,"file":"parseTypes.d.ts","sourceRoot":"","sources":["../../src/helpers/parseTypes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,SAAS,CAC/B,IAAI,EACA,SAAS,GACT,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,UAAU,GACV,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,WAAW,GACX,0BAA0B,GAC1B,SAAS,GACT,MAAM,GACN,MAAM,GACN,SAAS,MAAM,GAAG,GAClB,SAAS,MAAM,GAAG,GAClB,aAAa,MAAM,IAAI,GACvB,aAAa,MAAM,IAAI,UAmC5B"}

package/script/helpers/parseTypes.js

@@ -28,9 +28,13 @@ function parseType(type) {
         "timestamp",
         "timestamp with time zone",
         "boolean",
+        "json",
     ].includes(typeLowerCase)) {
         return type.toUpperCase();
     }
+    else if (/^float\[[1-9]\d*\]$/.test(typeLowerCase)) {
+        return type.toUpperCase();
+    }
     else if (typeLowerCase.includes("geometry")) {
         return type.toUpperCase();
     }

package/script/helpers/pendingOps.d.ts

@@ -94,8 +94,10 @@ export type SourceOp = {
     rawSQL?: string[];
     /** A schema known from explicit source options, when inference is unnecessary. */
     schema?: TableSchema;
-    /** Returns the source as a single composable SELECT statement. */
-    buildSelect: () => string;
+    /** Whether the source uses spatial functions. */
+    needsSpatial?: boolean;
+    /** Returns a composable SELECT, optionally inspecting materialized inputs. */
+    buildSelect: () => string | Promise<string>;
 };
 /** A relational operation that can participate in a fused segment. */
 export type RelationalOp = SourceOp | FusableOp;

package/script/helpers/pendingOps.d.ts.map

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

package/script/helpers/prepareGeometry.d.ts

@@ -0,0 +1,3 @@
+/** Validates and snapshots a two-dimensional WGS84 GeoJSON geometry cell. */
+export default function prepareGeometry(value: unknown, column: string, row: number): string | null;
+//# sourceMappingURL=prepareGeometry.d.ts.map

package/script/helpers/prepareGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareGeometry.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareGeometry.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CA+Gf"}

package/script/helpers/prepareGeometry.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = prepareGeometry;
+/** Validates and snapshots a two-dimensional WGS84 GeoJSON geometry cell. */
+function prepareGeometry(value, column, row) {
+    if (value === null)
+        return null;
+    const fail = (message) => {
+        throw new Error(`Column ${JSON.stringify(column)}, row ${row}: ${message}`);
+    };
+    const active = new Set();
+    let hasSignedZero = false;
+    function position(value) {
+        if (!Array.isArray(value) || value.length !== 2 ||
+            !Array.from(value).every((n) => typeof n === "number" && Number.isFinite(n))) {
+            fail("Expected a finite two-dimensional [longitude, latitude] position; Z/M coordinates are unsupported.");
+        }
+        const point = value;
+        if (Math.abs(point[0]) > 180 || Math.abs(point[1]) > 90) {
+            fail("Expected WGS84 longitude [-180, 180] and latitude [-90, 90]; reproject the input first.");
+        }
+        hasSignedZero ||= Object.is(point[0], -0) || Object.is(point[1], -0);
+        return [...point];
+    }
+    function list(value, convert) {
+        if (!Array.isArray(value))
+            fail("Expected a coordinate array.");
+        return Array.from(value, convert);
+    }
+    function line(value) {
+        const points = list(value, position);
+        if (points.length < 2) {
+            fail("A LineString must contain at least two positions.");
+        }
+        return points;
+    }
+    function ring(value) {
+        const points = list(value, position);
+        if (points.length < 4 || points[0][0] !== points.at(-1)[0] ||
+            points[0][1] !== points.at(-1)[1]) {
+            fail("A polygon ring must contain at least four positions and be closed.");
+        }
+        return points;
+    }
+    function geometry(value) {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            fail("Expected a GeoJSON geometry object or null.");
+        }
+        const object = value;
+        if (active.has(object))
+            fail("Cyclic GeometryCollections are unsupported.");
+        if (active.size >= 100) {
+            fail("GeometryCollections may nest at most 100 levels.");
+        }
+        active.add(object);
+        try {
+            const type = object.type;
+            if (type === "Feature" || type === "FeatureCollection") {
+                fail("Expected a GeoJSON geometry object, not a Feature or FeatureCollection; extract each feature's geometry first.");
+            }
+            if ("crs" in object) {
+                fail("Geometry crs members are unsupported; supply WGS84 coordinates and declare GEOMETRY('EPSG:4326').");
+            }
+            let coordinates;
+            switch (type) {
+                case "Point":
+                    coordinates = position(object.coordinates);
+                    break;
+                case "MultiPoint":
+                    coordinates = list(object.coordinates, position);
+                    break;
+                case "LineString":
+                    coordinates = line(object.coordinates);
+                    break;
+                case "MultiLineString":
+                    coordinates = list(object.coordinates, line);
+                    break;
+                case "Polygon":
+                    coordinates = list(object.coordinates, ring);
+                    break;
+                case "MultiPolygon":
+                    coordinates = list(object.coordinates, (v) => list(v, ring));
+                    break;
+                case "GeometryCollection":
+                    return { type, geometries: list(object.geometries, geometry) };
+                default:
+                    fail("Expected a supported GeoJSON geometry type.");
+            }
+            return { type, coordinates };
+        }
+        finally {
+            active.delete(object);
+        }
+    }
+    const prepared = geometry(value);
+    if (!hasSignedZero)
+        return JSON.stringify(prepared);
+    // JSON.stringify normalizes -0. Only supported geometry type names survive
+    // validation as strings, so the "-0" marker cannot collide with input text.
+    // Emit a decimal literal so DuckDB also preserves its sign when parsing JSON.
+    return JSON.stringify(prepared, (_key, cell) => Object.is(cell, -0) ? "-0" : cell).replaceAll('"-0"', "-0.0");
+}

package/script/helpers/prepareJSON.d.ts

@@ -0,0 +1,3 @@
+/** Validates and snapshots a JavaScript JSON value without dropping information. */
+export default function prepareJSON(value: unknown, column: string, row: number): string | null;
+//# sourceMappingURL=prepareJSON.d.ts.map

package/script/helpers/prepareJSON.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareJSON.d.ts","sourceRoot":"","sources":["../../src/helpers/prepareJSON.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,CAAC,OAAO,UAAU,WAAW,CACjC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAmEf"}

package/script/helpers/prepareJSON.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = prepareJSON;
+/** Validates and snapshots a JavaScript JSON value without dropping information. */
+function prepareJSON(value, column, row) {
+    if (value === null || value === undefined)
+        return null;
+    const active = new Set();
+    const fail = (path, message) => {
+        throw new Error(`Column ${JSON.stringify(column)}, row ${row}, ${path}: ${message}`);
+    };
+    function serialize(value, path) {
+        if (value === null)
+            return "null";
+        if (typeof value === "string" || typeof value === "boolean") {
+            return JSON.stringify(value);
+        }
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return Object.is(value, -0) ? "-0.0" : JSON.stringify(value);
+        }
+        if (typeof value !== "object") {
+            return fail(path, "Expected a JSON value: finite numbers, strings, booleans, null, arrays, or plain objects.");
+        }
+        if (active.has(value)) {
+            return fail(path, "Cyclic JSON values are unsupported.");
+        }
+        if (active.size >= 100) {
+            return fail(path, "JSON values may nest at most 100 levels.");
+        }
+        const array = Array.isArray(value);
+        if (!array && Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null) {
+            return fail(path, "Expected a plain JSON object; convert class instances to JSON values first.");
+        }
+        if (Object.getOwnPropertySymbols(value).length) {
+            return fail(path, "JSON cannot represent symbol keys.");
+        }
+        active.add(value);
+        try {
+            if (array) {
+                if (Object.keys(value).length !== value.length) {
+                    return fail(path, "JSON arrays must be dense and have no extra properties.");
+                }
+                return `[${Array.from(value, (item, i) => serialize(item, `${path}[${i}]`)).join(",")}]`;
+            }
+            return `{${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)}:${serialize(item, `${path}[${JSON.stringify(key)}]`)}`).join(",")}}`;
+        }
+        finally {
+            active.delete(value);
+        }
+    }
+    return serialize(value, "$");
+}

package/script/helpers/printTable.d.ts

@@ -1,14 +1,15 @@
 /**
  * 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