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

package/esm/class/SimpleTable.js

@@ -47,6 +47,7 @@ import normalizeQuery from "../methods/normalizeQuery.js";
 import rollingQuery from "../methods/rollingQuery.js";
 import distanceQuery from "../methods/distanceQuery.js";
 import getGeoData from "../methods/getGeoData.js";
+import writeGeoData from "../helpers/writeGeoData.js";
 import splitSpread from "../methods/splitSpread.js";
 import { readdirSync } from "node:fs";
 import stringToArray from "../helpers/stringToArray.js";
@@ -54,24 +55,20 @@ import loadDataQuery from "../methods/loadDataQuery.js";
 import mergeOptions from "../helpers/mergeOptions.js";
 import queryDB from "../helpers/queryDB.js";
 import writeDataQuery from "../methods/writeDataQuery.js";
-import writeGeoDataQuery from "../methods/writeGeoDataQuery.js";
 import runQuery from "../helpers/runQuery.js";
 import aggregateGeoQuery from "../methods/aggregateGeoQuery.js";
 import summarize from "../methods/summarize.js";
 import correlations from "../methods/correlations.js";
 import linearRegressions from "../methods/linearRegressions.js";
 import joinGeo from "../methods/joinGeo.js";
-import shouldFlipBeforeExport from "../helpers/shouldFlipBeforeExport.js";
 import getProjection from "../helpers/getProjection.js";
 import cache from "../methods/cache.js";
 import camelCase from "../helpers/camelCase.js";
 import formatNumber from "../helpers/formatNumber.js";
 import createDirectory from "../helpers/createDirectory.js";
-import rewind from "../helpers/rewind.js";
 import writeDataAsArrays from "../helpers/writeDataAsArrays.js";
 import logData from "../helpers/logData.js";
 import fill from "../methods/fill.js";
-import { readFileSync, writeFileSync } from "node:fs";
 import loadArray from "../methods/loadArray.js";
 import cleanPath from "../helpers/cleanPath.js";
 import Simple from "./Simple.js";
@@ -86,11 +83,11 @@ import getExtension from "../helpers/getExtension.js";
 import getIdenticalColumns from "../helpers/getIdenticalColumns.js";
 import capitalizeQuery from "../methods/capitalizeQuery.js";
 import truncateQuery from "../methods/truncateQuery.js";
+import padQuery from "../methods/padQuery.js";
 import getProjectionParquet from "../helpers/getProjectionParquet.js";
+import hasGeometryColumn from "../helpers/hasGeometryColumn.js";
 import unifyColumns from "../helpers/unifyColumns.js";
 import accumulateQuery from "../helpers/accumulateQuery.js";
-import stringifyDates from "../helpers/stringifyDates.js";
-import stringifyDatesInvert from "../helpers/stringifyDatesInvert.js";
 import unnestQuery from "../helpers/unnestQuery.js";
 import nestQuery from "../helpers/nestQuery.js";
 import concatenateRowQuery from "../helpers/concatenateRowQuery.js";
@@ -286,6 +283,7 @@ export default class SimpleTable extends Simple {
      * @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.
@@ -332,6 +330,12 @@ export default class SimpleTable extends Simple {
      *   "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 queryDB(this, loadDataQuery(this.name, stringToArray(files), options), mergeOptions(this, {
@@ -352,6 +356,7 @@ export default class SimpleTable extends Simple {
      * @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.
@@ -372,6 +377,12 @@ export default class SimpleTable extends Simple {
      * // 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 = readdirSync(directory).map((file) => `${directory.slice(-1) === "/" ? directory : directory + "/"}${file}`);
@@ -407,7 +418,13 @@ export default class SimpleTable extends Simple {
      *
      * @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 });
      * ```
      */
@@ -1888,48 +1905,57 @@ export default class SimpleTable extends Simple {
      * @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 fuzzyJoin(this, rightTable, leftColumn, rightColumn, options);
+        return await fuzzyJoin(this, rightTable, leftColumn, rightColumn, threshold, options);
     }
     /**
      * Normalizes string values in a column by detecting fuzzy duplicates and replacing them with a single canonical value.
@@ -1943,42 +1969,52 @@ export default class SimpleTable extends Simple {
      *
      * @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 fuzzyClean(this, column, newColumn, options);
+    async fuzzyClean(column, newColumn, threshold, options = {}) {
+        await fuzzyClean(this, column, newColumn, threshold, options);
     }
     /**
      * Replaces specified strings in the selected columns.
@@ -2132,6 +2168,72 @@ export default class SimpleTable extends Simple {
             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 = stringToArray(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 queryDB(this, `SELECT COUNT(*) AS cnt FROM "${this.name}" WHERE LENGTH("${column}") > ${length};`, mergeOptions(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 queryDB(this, padQuery(this.name, columnList, length, options), mergeOptions(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.
@@ -2477,9 +2579,18 @@ export default class SimpleTable extends Simple {
      * // 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 queryDB(this, roundQuery(this.name, stringToArray(columns), options), mergeOptions(this, {
+        const optionsNormalized = typeof options === "number"
+            ? { decimals: options }
+            : options;
+        await queryDB(this, roundQuery(this.name, stringToArray(columns), optionsNormalized), mergeOptions(this, {
             table: this.name,
             method: "round()",
             parameters: { columns, options },
@@ -3835,6 +3946,9 @@ export default class SimpleTable extends Simple {
      * ```
      */
     async getData(options = {}) {
+        if (await hasGeometryColumn(this)) {
+            throw new Error("Table contains geometry columns. Use getGeoData() instead.");
+        }
         const columns = options.columns
             ? (typeof options.columns === "string"
                 ? [options.columns]
@@ -3899,8 +4013,9 @@ export default class SimpleTable extends Simple {
      * ```
      */
     async points(columnLat, columnLon, newColumn) {
-        await queryDB(this, `INSTALL spatial; LOAD spatial;
-            ALTER TABLE "${this.name}" ADD COLUMN "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Point2D("${columnLat}", "${columnLon}")`, mergeOptions(this, {
+        await queryDB(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}")`, mergeOptions(this, {
             table: this.name,
             method: "points()",
             parameters: { columnLat, columnLon, newColumn },
@@ -4316,7 +4431,9 @@ export default class SimpleTable extends Simple {
         const column = typeof options.column === "string"
             ? options.column
             : await findGeoColumn(this);
-        await queryDB(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" =  ST_Buffer("${column}", ${distance});`, mergeOptions(this, {
+        await queryDB(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})`, mergeOptions(this, {
             table: this.name,
             method: "buffer()",
             parameters: { column, newColumn, distance },
@@ -4402,7 +4519,9 @@ export default class SimpleTable extends Simple {
         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 queryDB(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Intersection("${column1}", "${column2}")`, mergeOptions(this, {
+        await queryDB(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}")`, mergeOptions(this, {
             table: this.name,
             method: "intersection()",
             parameters: { column1, column2, newColumn },
@@ -4527,7 +4646,9 @@ export default class SimpleTable extends Simple {
         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 queryDB(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" = ST_Union("${column1}", "${column2}")`, mergeOptions(this, {
+        await queryDB(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}")`, mergeOptions(this, {
             table: this.name,
             method: "union()",
             parameters: { column1, column2, newColumn },
@@ -4618,7 +4739,9 @@ export default class SimpleTable extends Simple {
         const column = typeof options.column === "string"
             ? options.column
             : await findGeoColumn(this);
-        await queryDB(this, `ALTER TABLE "${this.name}" ADD "${newColumn}" GEOMETRY; UPDATE "${this.name}" SET "${newColumn}" =  ST_Centroid("${column}");`, mergeOptions(this, {
+        await queryDB(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}")`, mergeOptions(this, {
             table: this.name,
             method: "centroid()",
             parameters: { column, newColumn },
@@ -4903,6 +5026,9 @@ export default class SimpleTable extends Simple {
      * ```
      */
     async writeData(file, options = {}) {
+        if (await hasGeometryColumn(this)) {
+            throw new Error("Table contains geometry columns. Use writeGeoData() instead.");
+        }
         createDirectory(file);
         const extension = getExtension(file);
         if (options.dataAsArrays) {
@@ -4917,12 +5043,12 @@ export default class SimpleTable extends Simple {
         }
     }
     /**
-     * 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`.
@@ -4946,6 +5072,12 @@ export default class SimpleTable extends Simple {
      *
      * @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,
@@ -4954,71 +5086,7 @@ export default class SimpleTable extends Simple {
      * ```
      */
     async writeGeoData(file, options = {}) {
-        createDirectory(file);
-        const fileExtension = getExtension(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 stringifyDates(this, types);
-                }
-            }
-            if (typeof options.compression === "boolean") {
-                throw new Error("The compression option is not supported for writing GeoJSON files.");
-            }
-            const geoColumn = await findGeoColumn(this);
-            const flip = shouldFlipBeforeExport(this.projections[geoColumn]);
-            if (flip) {
-                await this.flipCoordinates(geoColumn);
-                await queryDB(this, writeGeoDataQuery(this.name, file, fileExtension, options), mergeOptions(this, {
-                    table: this.name,
-                    method: "writeGeoData()",
-                    parameters: { file, options },
-                }));
-                await this.flipCoordinates(geoColumn);
-            }
-            else {
-                await queryDB(this, writeGeoDataQuery(this.name, file, fileExtension, options), mergeOptions(this, {
-                    table: this.name,
-                    method: "writeGeoData()",
-                    parameters: { file, options },
-                }));
-            }
-            if (options.metadata) {
-                const fileData = JSON.parse(readFileSync(file, "utf-8"));
-                fileData.metadata = options.metadata;
-                writeFileSync(file, JSON.stringify(fileData));
-            }
-            if (options.rewind) {
-                const fileData = JSON.parse(readFileSync(file, "utf-8"));
-                const fileRewinded = rewind(fileData);
-                writeFileSync(file, JSON.stringify(fileRewinded));
-            }
-            if (types && (Object.values(types).includes("DATE") ||
-                Object.values(types).includes("TIMESTAMP"))) {
-                await stringifyDatesInvert(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 queryDB(this, `COPY "${this.name}" TO '${cleanPath(file)}' WITH (FORMAT PARQUET${options.compression === true ? ", COMPRESSION 'zstd'" : ""}, KV_METADATA {
-             projections: '${JSON.stringify(this.projections)}'
-        });`, mergeOptions(this, {
-                table: this.name,
-                method: "writeGeoData()",
-                parameters: { file, options },
-            }));
-        }
-        else {
-            throw new Error(`Unknown extension ${fileExtension}`);
-        }
+        await writeGeoData(this, file, options);
     }
     /**
      * Caches the results of computations in `./.sda-cache`.
@@ -5226,10 +5294,10 @@ export default class SimpleTable extends Simple {
     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 getDescription(this));
         }
     }
@@ -5246,7 +5314,7 @@ export default class SimpleTable extends Simple {
      * ```
      */
     async logProjections() {
-        console.log(`\ntable ${this.name} projections:`);
+        console.log(`\nTable ${this.name} projections:`);
         console.log(this.projections);
         return await this;
     }
@@ -5263,7 +5331,7 @@ export default class SimpleTable extends Simple {
      * ```
      */
     async logTypes() {
-        console.log(`\ntable ${this.name} types:`);
+        console.log(`\nTable ${this.name} types:`);
         console.log(await this.getTypes());
         return await this;
     }
@@ -5291,7 +5359,7 @@ export default class SimpleTable extends Simple {
      */
     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/esm/helpers/findGeoColumn.js

@@ -3,7 +3,7 @@ export default 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/esm/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/esm/helpers/getProjection.js

@@ -15,6 +15,9 @@ export default 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/esm/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/esm/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/esm/helpers/hasGeometryColumn.js

@@ -0,0 +1,21 @@
+/**
+ * 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 async function hasGeometryColumn(table) {
+    const types = await table.getTypes();
+    return Object.values(types).some((t) => t.toLowerCase() === "geometry");
+}

package/esm/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/esm/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"}