@nshiab/simple-data-analysis-core 0.0.19 → 0.0.21

package/script/class/SimpleTable.js

@@ -52,6 +52,7 @@ const normalizeQuery_js_1 = __importDefault(require("../methods/normalizeQuery.j
 const rollingQuery_js_1 = __importDefault(require("../methods/rollingQuery.js"));
 const distanceQuery_js_1 = __importDefault(require("../methods/distanceQuery.js"));
 const getGeoData_js_1 = __importDefault(require("../methods/getGeoData.js"));
+const writeGeoData_js_1 = __importDefault(require("../helpers/writeGeoData.js"));
 const splitSpread_js_1 = __importDefault(require("../methods/splitSpread.js"));
 const node_fs_1 = require("node:fs");
 const stringToArray_js_1 = __importDefault(require("../helpers/stringToArray.js"));
@@ -59,24 +60,20 @@ const loadDataQuery_js_1 = __importDefault(require("../methods/loadDataQuery.js"
 const mergeOptions_js_1 = __importDefault(require("../helpers/mergeOptions.js"));
 const queryDB_js_1 = __importDefault(require("../helpers/queryDB.js"));
 const writeDataQuery_js_1 = __importDefault(require("../methods/writeDataQuery.js"));
-const writeGeoDataQuery_js_1 = __importDefault(require("../methods/writeGeoDataQuery.js"));
 const runQuery_js_1 = __importDefault(require("../helpers/runQuery.js"));
 const aggregateGeoQuery_js_1 = __importDefault(require("../methods/aggregateGeoQuery.js"));
 const summarize_js_1 = __importDefault(require("../methods/summarize.js"));
 const correlations_js_1 = __importDefault(require("../methods/correlations.js"));
 const linearRegressions_js_1 = __importDefault(require("../methods/linearRegressions.js"));
 const joinGeo_js_1 = __importDefault(require("../methods/joinGeo.js"));
-const shouldFlipBeforeExport_js_1 = __importDefault(require("../helpers/shouldFlipBeforeExport.js"));
 const getProjection_js_1 = __importDefault(require("../helpers/getProjection.js"));
 const cache_js_1 = __importDefault(require("../methods/cache.js"));
 const camelCase_js_1 = __importDefault(require("../helpers/camelCase.js"));
 const formatNumber_js_1 = __importDefault(require("../helpers/formatNumber.js"));
 const createDirectory_js_1 = __importDefault(require("../helpers/createDirectory.js"));
-const rewind_js_1 = __importDefault(require("../helpers/rewind.js"));
 const writeDataAsArrays_js_1 = __importDefault(require("../helpers/writeDataAsArrays.js"));
 const logData_js_1 = __importDefault(require("../helpers/logData.js"));
 const fill_js_1 = __importDefault(require("../methods/fill.js"));
-const node_fs_2 = require("node:fs");
 const loadArray_js_1 = __importDefault(require("../methods/loadArray.js"));
 const cleanPath_js_1 = __importDefault(require("../helpers/cleanPath.js"));
 const Simple_js_1 = __importDefault(require("./Simple.js"));
@@ -91,11 +88,11 @@ const getExtension_js_1 = __importDefault(require("../helpers/getExtension.js"))
 const getIdenticalColumns_js_1 = __importDefault(require("../helpers/getIdenticalColumns.js"));
 const capitalizeQuery_js_1 = __importDefault(require("../methods/capitalizeQuery.js"));
 const truncateQuery_js_1 = __importDefault(require("../methods/truncateQuery.js"));
+const padQuery_js_1 = __importDefault(require("../methods/padQuery.js"));
 const getProjectionParquet_js_1 = __importDefault(require("../helpers/getProjectionParquet.js"));
+const hasGeometryColumn_js_1 = __importDefault(require("../helpers/hasGeometryColumn.js"));
 const unifyColumns_js_1 = __importDefault(require("../helpers/unifyColumns.js"));
 const accumulateQuery_js_1 = __importDefault(require("../helpers/accumulateQuery.js"));
-const stringifyDates_js_1 = __importDefault(require("../helpers/stringifyDates.js"));
-const stringifyDatesInvert_js_1 = __importDefault(require("../helpers/stringifyDatesInvert.js"));
 const unnestQuery_js_1 = __importDefault(require("../helpers/unnestQuery.js"));
 const nestQuery_js_1 = __importDefault(require("../helpers/nestQuery.js"));
 const concatenateRowQuery_js_1 = __importDefault(require("../helpers/concatenateRowQuery.js"));
@@ -291,6 +288,7 @@ class SimpleTable extends Simple_js_1.default {
      * @param options.fileName - A boolean indicating whether to include the file name as a new column in the loaded data. Defaults to `false`.
      * @param options.unifyColumns - A boolean indicating whether to unify columns across multiple files when their structures differ. Missing columns will be filled with `NULL` values. Defaults to `false`.
      * @param options.columnTypes - An object mapping column names to their expected data types. By default, types are inferred.
+     * @param options.columns - An array of column names to load. When provided, only the specified columns are loaded, reducing memory usage and improving load times. Not supported for Excel files — combining `columns` with Excel files throws an error. If an invalid column name is provided, DuckDB will throw its native error. An empty array behaves the same as omitting the option (loads all columns). Defaults to loading all columns.
      * @param options.header - A boolean indicating whether the file has a header row. Applicable to CSV files. Defaults to `true`.
      * @param options.allText - A boolean indicating whether all columns should be treated as text. Applicable to CSV files. Defaults to `false`.
      * @param options.delim - The delimiter used in the file. Applicable to CSV and DSV files. By default, the delimiter is inferred.
@@ -337,6 +335,12 @@ class SimpleTable extends Simple_js_1.default {
      *   "https://some-website.com/some-data3.parquet"
      * ], { unifyColumns: true });
      * ```
+     *
+     * @example
+     * ```ts
+     * // Load only specific columns from a CSV file
+     * await table.loadData("./employees.csv", { columns: ["name", "salary"] });
+     * ```
      */
     async loadData(files, options = {}) {
         await (0, queryDB_js_1.default)(this, (0, loadDataQuery_js_1.default)(this.name, (0, stringToArray_js_1.default)(files), options), (0, mergeOptions_js_1.default)(this, {
@@ -357,6 +361,7 @@ class SimpleTable extends Simple_js_1.default {
      * @param options.fileName - A boolean indicating whether to include the file name as a new column in the loaded data. Defaults to `false`.
      * @param options.unifyColumns - A boolean indicating whether to unify columns across multiple files when their structures differ. Missing columns will be filled with `NULL` values. Defaults to `false`.
      * @param options.columnTypes - An object mapping column names to their expected data types. By default, types are inferred.
+     * @param options.columns - An array of column names to load. When provided, only the specified columns are loaded, reducing memory usage and improving load times. Not supported for Excel files — combining `columns` with Excel files throws an error. If an invalid column name is provided, DuckDB will throw its native error. An empty array behaves the same as omitting the option (loads all columns). Defaults to loading all columns.
      * @param options.header - A boolean indicating whether the file has a header row. Applicable to CSV files. Defaults to `true`.
      * @param options.allText - A boolean indicating whether all columns should be treated as text. Applicable to CSV files. Defaults to `false`.
      * @param options.delim - The delimiter used in the file. Applicable to CSV and DSV files. By default, the delimiter is inferred.
@@ -377,6 +382,12 @@ class SimpleTable extends Simple_js_1.default {
      * // Load all supported data files from the "./data/" directory
      * await table.loadDataFromDirectory("./data/");
      * ```
+     *
+     * @example
+     * ```ts
+     * // Load only specific columns from all CSV files in a directory
+     * await table.loadDataFromDirectory("./data/", { columns: ["name", "salary"] });
+     * ```
      */
     async loadDataFromDirectory(directory, options = {}) {
         const files = (0, node_fs_1.readdirSync)(directory).map((file) => `${directory.slice(-1) === "/" ? directory : directory + "/"}${file}`);
@@ -412,7 +423,13 @@ class SimpleTable extends Simple_js_1.default {
      *
      * @example
      * ```ts
-     * // Load geospatial data from a shapefile and reproject to WGS84
+     * // Load geospatial data from a shapefile (with relevant files in the same folder) and reproject to WGS84
+     * await table.loadGeoData("./some-data/some-data.shp", { toWGS84: true });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Load geospatial data from a zipped shapefile and reproject to WGS84
      * await table.loadGeoData("./some-data.shp.zip", { toWGS84: true });
      * ```
      */
@@ -1893,48 +1910,57 @@ class SimpleTable extends Simple_js_1.default {
      * @param rightTable - The SimpleTable instance to be joined with this table.
      * @param leftColumn - The name of the column in this (left) table containing the text to compare.
      * @param rightColumn - The name of the column in the right table containing the text to compare.
+     * @param threshold - The minimum similarity score (0–100) required for two rows to be joined. For `method: "ratio"`, a length-based pre-filter is automatically applied based on the threshold to improve performance without losing accuracy.
      * @param options - An optional object with configuration options:
      * @param options.method - The rapidfuzz similarity algorithm to use. Defaults to `"ratio"`.
      *   - `"ratio"`: Overall similarity (Levenshtein-based).
      *   - `"partial_ratio"`: Best partial/substring similarity.
      *   - `"token_sort_ratio"`: Similarity after sorting tokens (words), useful for reordered words.
      *   - `"token_set_ratio"`: Similarity based on sets of tokens, ignoring duplicates and word order.
-     * @param options.threshold - The minimum similarity score (0–100) required for two rows to be joined. Defaults to `80`.
      * @param options.similarityColumn - If provided, a column with this name is added to the result containing the similarity score (0–100). If omitted, the score is not included in the output.
      * @param options.outputTable - If `true`, the results will be stored in a new table with a generated name. If a string, it will be used as the name for the new table. If `false` or omitted, the current table will be overwritten. Defaults to `false`.
+     * @param options.preFilterPrefixLen - An optional prefix length. Only strings sharing the same first N characters are compared. Note that prefix filtering is lossy (e.g. "John" vs. "Phon" will not match despite high similarity).
      * @returns A promise that resolves to a table instance containing the fuzzy-joined data (either the modified current table or a new table).
      * @category Table Operations
      *
      * @example
      * ```ts
-     * // Fuzzy left join tableA with tableB on 'name' (left) and 'standardName' (right) (ratio >= 80)
-     * await tableA.fuzzyJoin(tableB, "name", "standardName");
+     * // Fuzzy left join tableA with tableB on 'name' (left) and 'standardName' (right) with a threshold of 80
+     * // A length-based pre-filter is automatically applied.
+     * await tableA.fuzzyJoin(tableB, "name", "standardName", 80);
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Fuzzy join with a prefix-based pre-filter and a threshold of 80
+     * await tableA.fuzzyJoin(tableB, "name", "standardName", 80, {
+     *   preFilterPrefixLen: 3, // Must share the same first 3 characters
+     * });
      * ```
      *
      * @example
      * ```ts
      * // Fuzzy join with a custom threshold and method, storing results in a new table
-     * const tableC = await tableA.fuzzyJoin(tableB, "name", "standardName", {
+     * const tableC = await tableA.fuzzyJoin(tableB, "name", "standardName", 90, {
      *   method: "token_sort_ratio",
-     *   threshold: 90,
      *   outputTable: "tableC",
      * });
      * ```
      *
      * @example
      * ```ts
-     * // Fuzzy join with a custom similarity column name
-     * await tableA.fuzzyJoin(tableB, "name", "standardName", {
+     * // Fuzzy join with a custom similarity column name and a threshold of 80
+     * await tableA.fuzzyJoin(tableB, "name", "standardName", 80, {
      *   similarityColumn: "matchScore",
      * });
      * ```
      */
-    async fuzzyJoin(rightTable, leftColumn, rightColumn, options = {}) {
+    async fuzzyJoin(rightTable, leftColumn, rightColumn, threshold, options = {}) {
         if (options.outputTable === true) {
             options.outputTable = `table${this.sdb.tableIncrement}`;
             this.sdb.tableIncrement += 1;
         }
-        return await (0, fuzzyJoin_js_1.default)(this, rightTable, leftColumn, rightColumn, options);
+        return await (0, fuzzyJoin_js_1.default)(this, rightTable, leftColumn, rightColumn, threshold, options);
     }
     /**
      * Normalizes string values in a column by detecting fuzzy duplicates and replacing them with a single canonical value.
@@ -1948,42 +1974,52 @@ class SimpleTable extends Simple_js_1.default {
      *
      * @param column - The name of the column containing the strings to normalize.
      * @param newColumn - The name of the column to write the normalized values to. Use the same name as `column` to normalize in-place.
+     * @param threshold - The minimum similarity score (0–100) for two strings to be considered duplicates. For `method: "ratio"`, a length-based pre-filter is automatically applied based on the threshold to improve performance without losing accuracy.
      * @param options - An optional object with configuration options:
      * @param options.method - The rapidfuzz similarity algorithm to use. Defaults to `"ratio"`.
      *   - `"ratio"`: Overall similarity.
      *   - `"partial_ratio"`: Best partial/substring similarity.
      *   - `"token_sort_ratio"`: Similarity after sorting tokens (words), useful for reordered words.
      *   - `"token_set_ratio"`: Similarity based on sets of tokens, ignoring duplicates and word order.
-     * @param options.threshold - The minimum similarity score (0–100) for two strings to be considered duplicates. Defaults to `80`.
      * @param options.keep - The strategy for choosing the canonical value within each cluster of similar strings. Defaults to `"mostCommon"`.
      *   - `"mostCommon"`: Keep the value that appears most frequently in the original column.
      *   - `"longestString"`: Keep the longest string in the cluster.
      *   - `"shortestString"`: Keep the shortest string in the cluster.
      *   - `"mostCentral"`: Keep the string with the highest total similarity score to all other cluster members (the most "central" string).
      *   - `"maxScore"`: Keep the string that participates in the single highest-scoring pairwise match within the cluster.
+     * @param options.preFilterPrefixLen - An optional prefix length. Only strings sharing the same first N characters are compared. Note that prefix filtering is lossy (e.g. "John" vs. "Phon" will not match despite high similarity).
      * @returns A promise that resolves when the column has been normalized.
      * @category Updating Data
      *
      * @example
      * ```ts
-     * // Normalize 'city' into a new 'cityClean' column, keeping the most common string per cluster
-     * await table.fuzzyClean("city", "cityClean");
+     * // Normalize 'city' into a new 'cityClean' column, keeping the most common string per cluster with a threshold of 80
+     * // A length-based pre-filter is automatically applied.
+     * await table.fuzzyClean("city", "cityClean", 80);
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Normalize with a prefix-based pre-filter and a threshold of 80
+     * await table.fuzzyClean("city", "cityClean", 80, {
+     *   preFilterPrefixLen: 5, // Must share the same first 5 characters
+     * });
      * ```
      *
      * @example
      * ```ts
-     * // Normalize 'companyName' into a new column using token_sort_ratio and a stricter threshold
-     * await table.fuzzyClean("companyName", "companyNameClean", { method: "token_sort_ratio", threshold: 90 });
+     * // Normalize 'companyName' into a new column using token_sort_ratio and a threshold of 90
+     * await table.fuzzyClean("companyName", "companyNameClean", 90, { method: "token_sort_ratio" });
      * ```
      *
      * @example
      * ```ts
-     * // Normalize 'category' in-place, keeping the longest string in each cluster
-     * await table.fuzzyClean("category", "category", { keep: "longestString" });
+     * // Normalize 'category' in-place, keeping the longest string in each cluster and a threshold of 80
+     * await table.fuzzyClean("category", "category", 80, { keep: "longestString" });
      * ```
      */
-    async fuzzyClean(column, newColumn, options = {}) {
-        await (0, fuzzyClean_js_1.default)(this, column, newColumn, options);
+    async fuzzyClean(column, newColumn, threshold, options = {}) {
+        await (0, fuzzyClean_js_1.default)(this, column, newColumn, threshold, options);
     }
     /**
      * Replaces specified strings in the selected columns.
@@ -2137,6 +2173,72 @@ class SimpleTable extends Simple_js_1.default {
             parameters: { column, length },
         }));
     }
+    /**
+     * Pads the strings in the specified columns to a target length.
+     *
+     * The columns must contain string (VARCHAR) values. An error is thrown if any
+     * column is of a different type. `null` values remain `null`. If any string
+     * already exceeds the target length, an error is thrown (no silent truncation).
+     *
+     * @param columns - The column name(s) containing strings to be padded.
+     * @param length - The target length of the padded strings.
+     * @param options - An optional object with configuration options:
+     * @param options.method - Which side to pad. `'left'` (default) or `'right'`.
+     * @param options.char - The character to use for padding. Defaults to `'0'`.
+     * @returns A promise that resolves when the padding operation is complete.
+     * @throws {Error} If any column is not of string (VARCHAR) type.
+     * @throws {Error} If any string value exceeds the target length.
+     * @category Updating Data
+     *
+     * @example
+     * ```ts
+     * // Left-pad 'id' column to 3 characters with zeros (default)
+     * await table.pad("id", 3);
+     * // Result: '1' -> '001', '23' -> '023', null -> null
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Right-pad 'code' column to 5 characters with spaces
+     * await table.pad("code", 5, { method: "right", char: " " });
+     * // Result: '123' -> '123  ', '45' -> '45   ', null -> null
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Left-pad multiple columns to 5 characters with dashes
+     * await table.pad(["id", "code"], 5, { method: "left", char: "-" });
+     * // Result: '1' -> '----1', '23' -> '---23'
+     * ```
+     */
+    async pad(columns, length, options = {}) {
+        const columnList = (0, stringToArray_js_1.default)(columns);
+        // Validate all columns are string type
+        const allTypes = await this.getTypes();
+        for (const column of columnList) {
+            if (allTypes[column] !== "VARCHAR") {
+                throw new Error(`The column "${column}" is of type ${allTypes[column]}. The pad() method only works with string (VARCHAR) columns. Please convert the column to string first with the .convert() method.`);
+            }
+        }
+        // Pre-validation: check for strings exceeding target length
+        for (const column of columnList) {
+            const overflowResult = await (0, queryDB_js_1.default)(this, `SELECT COUNT(*) AS cnt FROM "${this.name}" WHERE LENGTH("${column}") > ${length};`, (0, mergeOptions_js_1.default)(this, {
+                table: this.name,
+                method: "pad()",
+                parameters: { columns, length, options },
+                returnDataFrom: "query",
+            }));
+            const overflowCount = Number(overflowResult[0].cnt);
+            if (overflowCount > 0) {
+                throw new Error(`The column "${column}" has ${overflowCount} string(s) exceeding the target length of ${length}. The pad() method does not truncate. Shorten the strings first or use a larger target length.`);
+            }
+        }
+        await (0, queryDB_js_1.default)(this, (0, padQuery_js_1.default)(this.name, columnList, length, options), (0, mergeOptions_js_1.default)(this, {
+            table: this.name,
+            method: "pad()",
+            parameters: { columns, length, options },
+        }));
+    }
     /**
      * Splits strings in a specified column by a separator and extracts a substring at a given index, storing the result in a new or existing column.
      * If the index is out of bounds, an empty string will be returned for that row.
@@ -2482,9 +2584,18 @@ class SimpleTable extends Simple_js_1.default {
      * // Round 'columnA' and 'columnB' values to 1 decimal place using ceiling method
      * await table.round(["columnA", "columnB"], { decimals: 1, method: "ceiling" });
      * ```
+     *
+     * @example
+     * ```ts
+     * // Round 'column1' values to 2 decimal places using the shorthand
+     * await table.round("column1", 2);
+     * ```
      */
     async round(columns, options = {}) {
-        await (0, queryDB_js_1.default)(this, (0, roundQuery_js_1.default)(this.name, (0, stringToArray_js_1.default)(columns), options), (0, mergeOptions_js_1.default)(this, {
+        const optionsNormalized = typeof options === "number"
+            ? { decimals: options }
+            : options;
+        await (0, queryDB_js_1.default)(this, (0, roundQuery_js_1.default)(this.name, (0, stringToArray_js_1.default)(columns), optionsNormalized), (0, mergeOptions_js_1.default)(this, {
             table: this.name,
             method: "round()",
             parameters: { columns, options },
@@ -3840,6 +3951,9 @@ class SimpleTable extends Simple_js_1.default {
      * ```
      */
     async getData(options = {}) {
+        if (await (0, hasGeometryColumn_js_1.default)(this)) {
+            throw new Error("Table contains geometry columns. Use getGeoData() instead.");
+        }
         const columns = options.columns
             ? (typeof options.columns === "string"
                 ? [options.columns]
@@ -3904,8 +4018,9 @@ class SimpleTable extends Simple_js_1.default {
      * ```
      */
     async points(columnLat, columnLon, newColumn) {
-        await (0, queryDB_js_1.default)(this, `INSTALL spatial; LOAD spatial;
-            ALTER TABLE "${this.name}" ADD COLUMN "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Point2D("${columnLat}", "${columnLon}")`, (0, mergeOptions_js_1.default)(this, {
+        await (0, queryDB_js_1.default)(this, (await this.getColumns()).includes(newColumn)
+            ? `INSTALL spatial; LOAD spatial; UPDATE "${this.name}" SET "${newColumn}" = ST_Point2D("${columnLat}", "${columnLon}")`
+            : `INSTALL spatial; LOAD spatial; ALTER TABLE "${this.name}" ADD COLUMN "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Point2D("${columnLat}", "${columnLon}")`, (0, mergeOptions_js_1.default)(this, {
             table: this.name,
             method: "points()",
             parameters: { columnLat, columnLon, newColumn },
@@ -4321,7 +4436,9 @@ class SimpleTable extends Simple_js_1.default {
         const column = typeof options.column === "string"
             ? options.column
             : await (0, findGeoColumn_js_1.default)(this);
-        await (0, queryDB_js_1.default)(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" =  ST_Buffer("${column}", ${distance});`, (0, mergeOptions_js_1.default)(this, {
+        await (0, queryDB_js_1.default)(this, (await this.getColumns()).includes(newColumn)
+            ? `INSTALL spatial; LOAD spatial; UPDATE "${this.name}" SET "${newColumn}" = ST_Buffer("${column}", ${distance})`
+            : `INSTALL spatial; LOAD spatial; ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Buffer("${column}", ${distance})`, (0, mergeOptions_js_1.default)(this, {
             table: this.name,
             method: "buffer()",
             parameters: { column, newColumn, distance },
@@ -4407,7 +4524,9 @@ class SimpleTable extends Simple_js_1.default {
         if (this.projections[column1] !== this.projections[column2]) {
             throw new Error(`${column1} and ${column2} don't have the same projection.\n${column1}: ${this.projections[column1]}\n${column2}: ${this.projections[column2]}`);
         }
-        await (0, queryDB_js_1.default)(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Intersection("${column1}", "${column2}")`, (0, mergeOptions_js_1.default)(this, {
+        await (0, queryDB_js_1.default)(this, (await this.getColumns()).includes(newColumn)
+            ? `INSTALL spatial; LOAD spatial; UPDATE "${this.name}" SET "${newColumn}" = ST_Intersection("${column1}", "${column2}")`
+            : `INSTALL spatial; LOAD spatial; ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Intersection("${column1}", "${column2}")`, (0, mergeOptions_js_1.default)(this, {
             table: this.name,
             method: "intersection()",
             parameters: { column1, column2, newColumn },
@@ -4532,7 +4651,9 @@ class SimpleTable extends Simple_js_1.default {
         if (this.projections[column1] !== this.projections[column2]) {
             throw new Error(`${column1} and ${column2} don't have the same projection.\n${column1}: ${this.projections[column1]}\n${column2}: ${this.projections[column2]}`);
         }
-        await (0, queryDB_js_1.default)(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Union("${column1}", "${column2}")`, (0, mergeOptions_js_1.default)(this, {
+        await (0, queryDB_js_1.default)(this, (await this.getColumns()).includes(newColumn)
+            ? `INSTALL spatial; LOAD spatial; UPDATE "${this.name}" SET "${newColumn}" = ST_Union("${column1}", "${column2}")`
+            : `INSTALL spatial; LOAD spatial; ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Union("${column1}", "${column2}")`, (0, mergeOptions_js_1.default)(this, {
             table: this.name,
             method: "union()",
             parameters: { column1, column2, newColumn },
@@ -4623,7 +4744,9 @@ class SimpleTable extends Simple_js_1.default {
         const column = typeof options.column === "string"
             ? options.column
             : await (0, findGeoColumn_js_1.default)(this);
-        await (0, queryDB_js_1.default)(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" =  ST_Centroid("${column}");`, (0, mergeOptions_js_1.default)(this, {
+        await (0, queryDB_js_1.default)(this, (await this.getColumns()).includes(newColumn)
+            ? `INSTALL spatial; LOAD spatial; UPDATE "${this.name}" SET "${newColumn}" = ST_Centroid("${column}")`
+            : `INSTALL spatial; LOAD spatial; ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Centroid("${column}")`, (0, mergeOptions_js_1.default)(this, {
             table: this.name,
             method: "centroid()",
             parameters: { column, newColumn },
@@ -4908,6 +5031,9 @@ class SimpleTable extends Simple_js_1.default {
      * ```
      */
     async writeData(file, options = {}) {
+        if (await (0, hasGeometryColumn_js_1.default)(this)) {
+            throw new Error("Table contains geometry columns. Use writeGeoData() instead.");
+        }
         (0, createDirectory_js_1.default)(file);
         const extension = (0, getExtension_js_1.default)(file);
         if (options.dataAsArrays) {
@@ -4922,12 +5048,12 @@ class SimpleTable extends Simple_js_1.default {
         }
     }
     /**
-     * Writes the table's geospatial data to a file in GeoJSON or GeoParquet format.
+     * Writes the table's geospatial data to a file in GeoJSON, GeoParquet, or Shapefile format.
      * If the specified path does not exist, it will be created.
      *
      * For GeoJSON files (`.geojson` or `.json`), if the projection is WGS84 or EPSG:4326 (`[latitude, longitude]` axis order), the coordinates will be flipped to follow the RFC7946 standard (`[longitude, latitude]` axis order) in the output.
      *
-     * @param file - The absolute path to the output file (e.g., `"./output.geojson"`, `"./output.geoparquet"`).
+     * @param file - The absolute path to the output file (e.g., `"./output.geojson"`, `"./output.geoparquet"`, `"./shapefile-folder/output.shp"`).
      * @param options - An optional object with configuration options:
      * @param options.precision - For GeoJSON, the maximum number of figures after the decimal separator to write in coordinates. Defaults to `undefined` (full precision).
      * @param options.compression - For GeoParquet, if `true`, the output will be ZSTD compressed. Defaults to `false`.
@@ -4951,6 +5077,12 @@ class SimpleTable extends Simple_js_1.default {
      *
      * @example
      * ```ts
+     * // Write geospatial data to a Shapefile with all relevant files  in the same folder
+     * await table.writeGeoData("./shapefile-folder/output.shp");
+     * ```
+     *
+     * @example
+     * ```ts
      * // Write GeoJSON with specific precision and metadata
      * await table.writeGeoData("./output_high_precision.geojson", {
      *   precision: 6,
@@ -4959,71 +5091,7 @@ class SimpleTable extends Simple_js_1.default {
      * ```
      */
     async writeGeoData(file, options = {}) {
-        (0, createDirectory_js_1.default)(file);
-        const fileExtension = (0, getExtension_js_1.default)(file);
-        if (fileExtension === "geojson" || fileExtension === "json") {
-            let types;
-            if (options.formatDates === true) {
-                types = await this.getTypes();
-                if (Object.values(types).includes("DATE") ||
-                    Object.values(types).includes("TIMESTAMP")) {
-                    await (0, stringifyDates_js_1.default)(this, types);
-                }
-            }
-            if (typeof options.compression === "boolean") {
-                throw new Error("The compression option is not supported for writing GeoJSON files.");
-            }
-            const geoColumn = await (0, findGeoColumn_js_1.default)(this);
-            const flip = (0, shouldFlipBeforeExport_js_1.default)(this.projections[geoColumn]);
-            if (flip) {
-                await this.flipCoordinates(geoColumn);
-                await (0, queryDB_js_1.default)(this, (0, writeGeoDataQuery_js_1.default)(this.name, file, fileExtension, options), (0, mergeOptions_js_1.default)(this, {
-                    table: this.name,
-                    method: "writeGeoData()",
-                    parameters: { file, options },
-                }));
-                await this.flipCoordinates(geoColumn);
-            }
-            else {
-                await (0, queryDB_js_1.default)(this, (0, writeGeoDataQuery_js_1.default)(this.name, file, fileExtension, options), (0, mergeOptions_js_1.default)(this, {
-                    table: this.name,
-                    method: "writeGeoData()",
-                    parameters: { file, options },
-                }));
-            }
-            if (options.metadata) {
-                const fileData = JSON.parse((0, node_fs_2.readFileSync)(file, "utf-8"));
-                fileData.metadata = options.metadata;
-                (0, node_fs_2.writeFileSync)(file, JSON.stringify(fileData));
-            }
-            if (options.rewind) {
-                const fileData = JSON.parse((0, node_fs_2.readFileSync)(file, "utf-8"));
-                const fileRewinded = (0, rewind_js_1.default)(fileData);
-                (0, node_fs_2.writeFileSync)(file, JSON.stringify(fileRewinded));
-            }
-            if (types && (Object.values(types).includes("DATE") ||
-                Object.values(types).includes("TIMESTAMP"))) {
-                await (0, stringifyDatesInvert_js_1.default)(this, types);
-            }
-        }
-        else if (fileExtension === "geoparquet") {
-            if (typeof options.precision === "number") {
-                throw new Error("The precision option is not supported for writing PARQUET files. Use the .reducePrecision() method.");
-            }
-            if (typeof options.rewind === "boolean") {
-                throw new Error("The rewind option is not supported for writing PARQUET files.");
-            }
-            await (0, queryDB_js_1.default)(this, `COPY "${this.name}" TO '${(0, cleanPath_js_1.default)(file)}' WITH (FORMAT PARQUET${options.compression === true ? ", COMPRESSION 'zstd'" : ""}, KV_METADATA {
-             projections: '${JSON.stringify(this.projections)}'
-        });`, (0, mergeOptions_js_1.default)(this, {
-                table: this.name,
-                method: "writeGeoData()",
-                parameters: { file, options },
-            }));
-        }
-        else {
-            throw new Error(`Unknown extension ${fileExtension}`);
-        }
+        await (0, writeGeoData_js_1.default)(this, file, options);
     }
     /**
      * Caches the results of computations in `./.sda-cache`.
@@ -5231,10 +5299,10 @@ class SimpleTable extends Simple_js_1.default {
     async logDescription() {
         if (this.connection === undefined ||
             !(await this.sdb.hasTable(this.name))) {
-            console.log(`\ntable ${this.name}: no data`);
+            console.log(`\nTable ${this.name}: no data`);
         }
         else {
-            console.log(`\ntable ${this.name}:`);
+            console.log(`\nTable ${this.name}:`);
             console.table(await (0, getDescription_js_1.default)(this));
         }
     }
@@ -5251,7 +5319,7 @@ class SimpleTable extends Simple_js_1.default {
      * ```
      */
     async logProjections() {
-        console.log(`\ntable ${this.name} projections:`);
+        console.log(`\nTable ${this.name} projections:`);
         console.log(this.projections);
         return await this;
     }
@@ -5268,7 +5336,7 @@ class SimpleTable extends Simple_js_1.default {
      * ```
      */
     async logTypes() {
-        console.log(`\ntable ${this.name} types:`);
+        console.log(`\nTable ${this.name} types:`);
         console.log(await this.getTypes());
         return await this;
     }
@@ -5296,7 +5364,7 @@ class SimpleTable extends Simple_js_1.default {
      */
     async logUniques(column, options = {}) {
         const values = await this.getUniques(column);
-        console.log(`\nUnique values in ${column}:`);
+        console.log(`\nTable ${this.name} — unique values in ${column}:`);
         if (options.stringify) {
             console.log(JSON.stringify(values, null, 2));
         }

package/script/helpers/findGeoColumn.js

@@ -6,7 +6,7 @@ async function findGeoColumn(SimpleTable) {
     const types = await SimpleTable.getTypes();
     const geometries = Object.values(types).filter((d) => d.toLowerCase() === "geometry");
     if (geometries.length === 0) {
-        throw new Error("No column storing geometries");
+        throw new Error("Table contains no geometry columns.");
     }
     else if (geometries.length > 1) {
         throw new Error("More than one column storing geometries. If the method allows to specify one, do it. Otherwise, use the selectColumns methods beforehand.");

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

@@ -1 +1 @@
-{"version":3,"file":"getProjection.d.ts","sourceRoot":"","sources":["../../src/helpers/getProjection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAGjD,wBAA8B,aAAa,CACzC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,mBA8Bb"}
+{"version":3,"file":"getProjection.d.ts","sourceRoot":"","sources":["../../src/helpers/getProjection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAC;AAGjD,wBAA8B,aAAa,CACzC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,mBAiCb"}

package/script/helpers/getProjection.js

@@ -21,6 +21,9 @@ async function getProjection(simpleDB, file) {
         throw new Error("No queryResults");
     }
     const proj4 = queryResult[0].proj4;
+    if (proj4 === null) {
+        return "UNKNOWN";
+    }
     if (typeof proj4 !== "string") {
         throw new Error(`Expected proj4 to be a string, got ${typeof proj4}`);
     }

package/script/helpers/hasGeometryColumn.d.ts

@@ -0,0 +1,20 @@
+import type SimpleTable from "../class/SimpleTable.js";
+/**
+ * Returns `true` if the table has one or more columns of type geometry.
+ *
+ * Uses `getTypes()` to inspect column types and checks for any column
+ * whose type normalizes to `"geometry"`.
+ *
+ * @param table - The SimpleTable instance to inspect.
+ * @returns `true` if at least one geometry column exists, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * const hasGeo = await hasGeometryColumn(table);
+ * if (hasGeo) {
+ *   console.log("This table contains geometry columns");
+ * }
+ * ```
+ */
+export default function hasGeometryColumn(table: SimpleTable): Promise<boolean>;
+//# sourceMappingURL=hasGeometryColumn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hasGeometryColumn.d.ts","sourceRoot":"","sources":["../../src/helpers/hasGeometryColumn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAA8B,iBAAiB,CAC7C,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/script/helpers/hasGeometryColumn.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = hasGeometryColumn;
+/**
+ * Returns `true` if the table has one or more columns of type geometry.
+ *
+ * Uses `getTypes()` to inspect column types and checks for any column
+ * whose type normalizes to `"geometry"`.
+ *
+ * @param table - The SimpleTable instance to inspect.
+ * @returns `true` if at least one geometry column exists, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * const hasGeo = await hasGeometryColumn(table);
+ * if (hasGeo) {
+ *   console.log("This table contains geometry columns");
+ * }
+ * ```
+ */
+async function hasGeometryColumn(table) {
+    const types = await table.getTypes();
+    return Object.values(types).some((t) => t.toLowerCase() === "geometry");
+}

package/script/helpers/writeGeoData.d.ts

@@ -0,0 +1,9 @@
+import type SimpleTable from "../class/SimpleTable.js";
+export default function writeGeoData(table: SimpleTable, file: string, options?: {
+    precision?: number;
+    compression?: boolean;
+    rewind?: boolean;
+    metadata?: unknown;
+    formatDates?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=writeGeoData.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writeGeoData.d.ts","sourceRoot":"","sources":["../../src/helpers/writeGeoData.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAEvD,wBAA8B,YAAY,CACxC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CAClB,GACL,OAAO,CAAC,IAAI,CAAC,CAqIf"}