@nshiab/simple-data-analysis 5.21.1 → 6.0.1

package/llms.txt

@@ -0,0 +1,19 @@
+# The Simple Data Analysis Library
+
+> Fast DuckDB-powered TypeScript library for tabular, geospatial, vector, AI, Google Sheets, and data visualization workflows on Deno, Node.js, and Bun.
+
+Install with Deno: `deno add jsr:@nshiab/simple-data-analysis`
+
+Install with Node.js: `npm i @nshiab/simple-data-analysis`
+
+Install with Bun: `bun add @nshiab/simple-data-analysis`
+
+## Documentation
+
+- [README](https://raw.githubusercontent.com/nshiab/simple-data-analysis/main/README.md): Installation, quick start, concepts, and examples.
+- [Complete API reference](https://raw.githubusercontent.com/nshiab/simple-data-analysis/main/llm.md): Generated documentation for public classes, methods, parameters, and examples.
+- [JSR API reference](https://jsr.io/@nshiab/simple-data-analysis/doc): Searchable documentation for the published package.
+
+## Optional
+
+- [Source repository](https://github.com/nshiab/simple-data-analysis): Source code, issues, releases, and contribution guidance.

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@nshiab/simple-data-analysis",
-  "version": "5.21.1",
-  "description": "Easy-to-use and high-performance TypeScript library for data analysis. Works with tabular, geospatial and vector data.",
+  "version": "6.0.1",
+  "description": "Fast DuckDB-powered TypeScript library for tabular, geospatial, vector, AI, Google Sheets, and data visualization workflows on Deno, Node.js, and Bun.",
+  "keywords": [
+    "data-analysis",
+    "typescript",
+    "duckdb",
+    "dataframe",
+    "tabular",
+    "csv",
+    "parquet",
+    "geospatial",
+    "spatial-analysis",
+    "vector-search",
+    "rag",
+    "data-visualization",
+    "google-sheets",
+    "deno",
+    "nodejs",
+    "bun"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/nshiab/simple-data-analysis"
@@ -20,20 +38,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@duckdb/node-api": "1.5.3-r.2",
-    "@google-cloud/storage": "^7.19.0",
-    "@google/genai": "^2.0.1",
-    "@napi-rs/canvas": "^1.0.0",
+    "@duckdb/node-api": "1.5.5-r.4",
+    "@google-cloud/storage": "^8.0.1",
+    "@google/genai": "^2.19.0",
+    "@napi-rs/canvas": "^1.0.8",
     "@observablehq/plot": "^0.6.17",
     "@resvg/resvg-js": "^2.6.2",
-    "@types/d3-geo": "^3.1.0",
-    "d3-array": "^3.2.4",
     "d3-dsv": "^3.0.1",
-    "d3-geo": "^3.1.1",
-    "date-fns-tz": "^3.2.0",
-    "google-auth-library": "^10.6.2",
-    "google-spreadsheet": "^5.2.0",
-    "linkedom": "^0.18.12",
+    "google-auth-library": "^11.0.2",
+    "google-spreadsheet": "^5.3.0",
+    "linkedom": "^0.18.13",
     "ollama": "^0.6.3",
     "zod": "^4.4.3"
   },

package/script/_dnt.polyfills.d.ts

@@ -1,11 +1,6 @@
 declare global {
-    interface Object {
-        /**
-         * Determines whether an object has a property with the specified name.
-         * @param o An object.
-         * @param v A property name.
-         */
-        hasOwn(o: object, v: PropertyKey): boolean;
+    interface Error {
+        cause?: unknown;
     }
 }
 export {};

package/script/_dnt.polyfills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAeA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd;;;;WAIG;QACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;KAC5C;CACF;AAED,OAAO,EAAE,CAAC"}
+{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC"}

package/script/_dnt.polyfills.js

@@ -1,16 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-// https://github.com/tc39/proposal-accessible-object-hasownproperty/blob/main/polyfill.js
-if (!Object.hasOwn) {
-    Object.defineProperty(Object, "hasOwn", {
-        value: function (object, property) {
-            if (object == null) {
-                throw new TypeError("Cannot convert undefined or null to object");
-            }
-            return Object.prototype.hasOwnProperty.call(Object(object), property);
-        },
-        configurable: true,
-        enumerable: false,
-        writable: true,
-    });
-}

package/script/class/SimpleDB.d.ts

@@ -1,41 +1,45 @@
-import { SimpleDB as SimpleDBCore } from "../deps/jsr.io/@nshiab/simple-data-analysis-core/1.0.1/src/index.js";
+import { SimpleDB as SimpleDBCore } from "../deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/index.js";
 import SimpleTable from "./SimpleTable.js";
 /**
  * Manages a DuckDB database instance, providing a simplified interface for database operations.
- * Extends the core [`SimpleDB`](https://github.com/nshiab/simple-data-analysis-core) class
+ * Extends the core [`SimpleDB`](https://jsr.io/@nshiab/simple-data-analysis-core/doc/~/SimpleDB) class
  * from [`simple-data-analysis-core`](https://github.com/nshiab/simple-data-analysis-core) to use
  * our extended SimpleTable class which includes additional AI, Google Sheets, and charting methods.
  *
+ * All core methods are available on this class. JSR currently omits inherited methods
+ * from subclass reference pages because of an [upstream limitation](https://github.com/jsr-io/jsr/issues/747).
+ * See the [core SimpleDB reference](https://jsr.io/@nshiab/simple-data-analysis-core/doc/~/SimpleDB)
+ * for inherited methods such as `newTable()` and `close()`.
+ *
  * @example
  * ```ts
  * // Create an in-memory database instance
  * const sdb = new SimpleDB();
- * // Create a new table named "employees"
- * const employees = sdb.newTable("employees");
- * // Load data from a CSV file into the "employees" table
- * await employees.loadData("./employees.csv");
- * // Log the first few rows of the "employees" table to the console
- * await employees.logTable();
+ * // Create a table, load a CSV file, and log its first few rows
+ * const employees = await sdb
+ *   .newTable("employees")
+ *   .loadData("./employees.csv")
+ *   .log();
+ *
  * // Close the database connection and clean up resources
- * await sdb.done();
+ * await sdb.close();
  * ```
  *
  * @example
  * ```ts
- * // Create a persistent database instance, saving data to a file
- * // To load an existing database, use the `loadDB` method instead
+ * // Open an existing DuckDB file, or create it on first use
  * const sdb = new SimpleDB({ file: "./my_database.db" });
  * // Perform database operations...
- * // Close the database connection, which saves changes to the specified file
- * await sdb.done();
+ * // Execute pending work, save metadata, and close the database connection
+ * await sdb.close();
  * ```
  *
  * @example
  * ```ts
  * // Create a database instance with custom options
  * const sdb = new SimpleDB({
- *   debug: true, // Enable debugging output
- *   nbRowsToLog: 20 // Set the number of rows to log by default
+ *   logSQL: true, // Log SQL immediately before execution
+ *   rowsToLog: 20 // Set the number of rows to log by default
  * });
  * ```
  */
@@ -50,29 +54,44 @@ export default class SimpleDB extends SimpleDBCore<SimpleTable> {
      * Creates a new SimpleDB instance.
      *
      * @param options - Configuration options for the SimpleDB instance.
-     * @param options.file - The path to the database file. If not provided, an in-memory database is used.
-     * @param options.overwrite - A flag indicating whether to overwrite the database file if it already exists.
+     * @param options.file - The path to a persistent DuckDB file, opened or created on first use. If not provided, an in-memory database is used.
+     * @param options.overwrite - Whether to replace an existing DuckDB file on first use instead of opening it. Defaults to false.
+     * @param options.readOnly - Opens an existing DuckDB file read-only. Defaults to false. Requires a file and cannot be combined with overwrite.
      * @param options.logDuration - A flag indicating whether to log the total execution duration.
-     * @param options.nbRowsToLog - The number of rows to display when logging a table.
-     * @param options.nbCharactersToLog - The maximum number of characters to display for text-based cells.
-     * @param options.types - A flag indicating whether to include data types when logging a table.
+     * @param options.rowsToLog - The number of rows to display when logging a table.
+     * @param options.charsToLog - The maximum number of characters to display for text-based cells.
+     * @param options.typesToLog - A flag indicating whether to include data types when logging a table.
      * @param options.cacheVerbose - A flag indicating whether to log verbose cache-related messages.
-     * @param options.debug - A flag indicating whether to log debugging information.
+     * @param options.logSQL - A flag indicating whether to log SQL immediately before execution.
+     * @param options.explainSQL - A flag indicating whether to log DuckDB query plans for supported statements.
      * @param options.duckDbCache - A flag indicating whether to use DuckDB's external file cache.
      * @param options.progressBar - A flag indicating whether to display a progress bar for long-running operations.
+     * @param options.memoryLimit - The maximum amount of memory DuckDB is allowed to use (for example, `"4GB"`).
+     * @param options.tempDir - The path to the directory used for temporary files.
      * @category Constructor
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ file: "./archive.duckdb", readOnly: true });
+     * const table = await sdb.getTable("employees");
+     * await table.log();
+     * await sdb.close();
+     * ```
      */
     constructor(options?: {
         file?: string;
         overwrite?: boolean;
+        readOnly?: boolean;
         logDuration?: boolean;
-        nbRowsToLog?: number;
-        nbCharactersToLog?: number;
-        types?: boolean;
+        rowsToLog?: number;
+        charsToLog?: number;
+        typesToLog?: boolean;
         cacheVerbose?: boolean;
-        debug?: boolean;
+        logSQL?: boolean;
+        explainSQL?: boolean;
         duckDbCache?: boolean | null;
         progressBar?: boolean;
+        memoryLimit?: string;
+        tempDir?: string;
     });
 }
 //# sourceMappingURL=SimpleDB.d.ts.map

package/script/class/SimpleDB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SimpleDB.d.ts","sourceRoot":"","sources":["../../src/class/SimpleDB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,qEAAqE,CAAC;AAC/G,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,YAAY,CAAC,WAAW,CAAC;IAC7D;;;;OAIG;IACM,UAAU,EAAE,OAAO,WAAW,CAAC;IAExC;;;;;;;;;;;;;;;OAeG;gBAED,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;KAClB;CAMT"}
+{"version":3,"file":"SimpleDB.d.ts","sourceRoot":"","sources":["../../src/class/SimpleDB.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,qEAAqE,CAAC;AAC/G,OAAO,WAAW,MAAM,kBAAkB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,YAAY,CAAC,WAAW,CAAC;IAC7D;;;;OAIG;IACM,UAAU,EAAE,OAAO,WAAW,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;gBAED,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb;CAMT"}

package/script/class/SimpleDB.js

@@ -3,44 +3,48 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const index_js_1 = require("../deps/jsr.io/@nshiab/simple-data-analysis-core/1.0.1/src/index.js");
+const index_js_1 = require("../deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/index.js");
 const SimpleTable_js_1 = __importDefault(require("./SimpleTable.js"));
 /**
  * Manages a DuckDB database instance, providing a simplified interface for database operations.
- * Extends the core [`SimpleDB`](https://github.com/nshiab/simple-data-analysis-core) class
+ * Extends the core [`SimpleDB`](https://jsr.io/@nshiab/simple-data-analysis-core/doc/~/SimpleDB) class
  * from [`simple-data-analysis-core`](https://github.com/nshiab/simple-data-analysis-core) to use
  * our extended SimpleTable class which includes additional AI, Google Sheets, and charting methods.
  *
+ * All core methods are available on this class. JSR currently omits inherited methods
+ * from subclass reference pages because of an [upstream limitation](https://github.com/jsr-io/jsr/issues/747).
+ * See the [core SimpleDB reference](https://jsr.io/@nshiab/simple-data-analysis-core/doc/~/SimpleDB)
+ * for inherited methods such as `newTable()` and `close()`.
+ *
  * @example
  * ```ts
  * // Create an in-memory database instance
  * const sdb = new SimpleDB();
- * // Create a new table named "employees"
- * const employees = sdb.newTable("employees");
- * // Load data from a CSV file into the "employees" table
- * await employees.loadData("./employees.csv");
- * // Log the first few rows of the "employees" table to the console
- * await employees.logTable();
+ * // Create a table, load a CSV file, and log its first few rows
+ * const employees = await sdb
+ *   .newTable("employees")
+ *   .loadData("./employees.csv")
+ *   .log();
+ *
  * // Close the database connection and clean up resources
- * await sdb.done();
+ * await sdb.close();
  * ```
  *
  * @example
  * ```ts
- * // Create a persistent database instance, saving data to a file
- * // To load an existing database, use the `loadDB` method instead
+ * // Open an existing DuckDB file, or create it on first use
  * const sdb = new SimpleDB({ file: "./my_database.db" });
  * // Perform database operations...
- * // Close the database connection, which saves changes to the specified file
- * await sdb.done();
+ * // Execute pending work, save metadata, and close the database connection
+ * await sdb.close();
  * ```
  *
  * @example
  * ```ts
  * // Create a database instance with custom options
  * const sdb = new SimpleDB({
- *   debug: true, // Enable debugging output
- *   nbRowsToLog: 20 // Set the number of rows to log by default
+ *   logSQL: true, // Log SQL immediately before execution
+ *   rowsToLog: 20 // Set the number of rows to log by default
  * });
  * ```
  */
@@ -49,17 +53,28 @@ class SimpleDB extends index_js_1.SimpleDB {
      * Creates a new SimpleDB instance.
      *
      * @param options - Configuration options for the SimpleDB instance.
-     * @param options.file - The path to the database file. If not provided, an in-memory database is used.
-     * @param options.overwrite - A flag indicating whether to overwrite the database file if it already exists.
+     * @param options.file - The path to a persistent DuckDB file, opened or created on first use. If not provided, an in-memory database is used.
+     * @param options.overwrite - Whether to replace an existing DuckDB file on first use instead of opening it. Defaults to false.
+     * @param options.readOnly - Opens an existing DuckDB file read-only. Defaults to false. Requires a file and cannot be combined with overwrite.
      * @param options.logDuration - A flag indicating whether to log the total execution duration.
-     * @param options.nbRowsToLog - The number of rows to display when logging a table.
-     * @param options.nbCharactersToLog - The maximum number of characters to display for text-based cells.
-     * @param options.types - A flag indicating whether to include data types when logging a table.
+     * @param options.rowsToLog - The number of rows to display when logging a table.
+     * @param options.charsToLog - The maximum number of characters to display for text-based cells.
+     * @param options.typesToLog - A flag indicating whether to include data types when logging a table.
      * @param options.cacheVerbose - A flag indicating whether to log verbose cache-related messages.
-     * @param options.debug - A flag indicating whether to log debugging information.
+     * @param options.logSQL - A flag indicating whether to log SQL immediately before execution.
+     * @param options.explainSQL - A flag indicating whether to log DuckDB query plans for supported statements.
      * @param options.duckDbCache - A flag indicating whether to use DuckDB's external file cache.
      * @param options.progressBar - A flag indicating whether to display a progress bar for long-running operations.
+     * @param options.memoryLimit - The maximum amount of memory DuckDB is allowed to use (for example, `"4GB"`).
+     * @param options.tempDir - The path to the directory used for temporary files.
      * @category Constructor
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({ file: "./archive.duckdb", readOnly: true });
+     * const table = await sdb.getTable("employees");
+     * await table.log();
+     * await sdb.close();
+     * ```
      */
     constructor(options = {}) {
         super(options);