@nshiab/simple-data-analysis-core 1.0.0 → 2.0.0

package/llms.txt

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

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@nshiab/simple-data-analysis-core",
-  "version": "1.0.0",
-  "description": "The core functionalities of the simple-data-analysis library, with only one dependency: DuckDB.",
+  "version": "2.0.0",
+  "description": "Lightweight DuckDB-powered TypeScript library for tabular, SQL, CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun.",
+  "keywords": [
+    "data-analysis",
+    "typescript",
+    "duckdb",
+    "dataframe",
+    "tabular",
+    "sql",
+    "csv",
+    "parquet",
+    "geospatial",
+    "spatial-analysis",
+    "deno",
+    "nodejs",
+    "bun"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/nshiab/simple-data-analysis-core"
@@ -24,7 +39,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@duckdb/node-api": "1.5.3-r.2"
+    "@duckdb/node-api": "1.5.5-r.4"
   },
   "_generatedBy": "dnt@dev"
 }

package/script/_dnt.polyfills.d.ts

@@ -0,0 +1,7 @@
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};
+//# sourceMappingURL=_dnt.polyfills.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/class/SDAError.d.ts

@@ -0,0 +1,63 @@
+/**
+ * An error thrown when a SQL query fails. It carries the SDA method that
+ * triggered the query, the parameters passed to it, the SQL query itself,
+ * and the original error as `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await table.selectColumns("aColumnThatDoesNotExist").run();
+ * } catch (error) {
+ *   if (error instanceof SDAError) {
+ *     console.log(error.method); // "selectColumns()"
+ *     console.log(error.query); // The SQL query that failed
+ *     console.log(error.cause); // The original DuckDB error
+ *   }
+ * }
+ * ```
+ */
+export default class SDAError extends Error {
+    /**
+     * The SDA method that triggered the failing query.
+     */
+    method: string | null;
+    /**
+     * The parameters passed to the method.
+     */
+    parameters: {
+        [key: string]: unknown;
+    } | null;
+    /**
+     * The SQL query that failed.
+     */
+    query: string;
+    /**
+     * Creates an error that preserves the failing query and its original cause.
+     *
+     * @param options - Details of the failed query.
+     * @param options.method - The SDA method that triggered the query, or `null`.
+     * @param options.parameters - The method's arguments, or `null`.
+     * @param options.query - The SQL statement that failed.
+     * @param options.cause - The original error thrown while executing the query.
+     *
+     * @example
+     * ```ts
+     * const error = new SDAError({
+     *   method: "example()",
+     *   parameters: { column: "missing" },
+     *   query: "SELECT missing FROM data",
+     *   cause: new Error("Column not found"),
+     * });
+     * console.log(error.method, error.cause);
+     * ```
+     */
+    constructor(options: {
+        method: string | null;
+        parameters: {
+            [key: string]: unknown;
+        } | null;
+        query: string;
+        cause: unknown;
+    });
+}
+//# sourceMappingURL=SDAError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SDAError.d.ts","sourceRoot":"","sources":["../../src/class/SDAError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,KAAK;IACzC;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;OAEG;IACH,UAAU,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;;;;;;;;OAmBG;gBAED,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,UAAU,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAC9C,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,OAAO,CAAC;KAChB;CAoBJ"}

package/script/class/SDAError.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * An error thrown when a SQL query fails. It carries the SDA method that
+ * triggered the query, the parameters passed to it, the SQL query itself,
+ * and the original error as `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await table.selectColumns("aColumnThatDoesNotExist").run();
+ * } catch (error) {
+ *   if (error instanceof SDAError) {
+ *     console.log(error.method); // "selectColumns()"
+ *     console.log(error.query); // The SQL query that failed
+ *     console.log(error.cause); // The original DuckDB error
+ *   }
+ * }
+ * ```
+ */
+class SDAError extends Error {
+    /**
+     * Creates an error that preserves the failing query and its original cause.
+     *
+     * @param options - Details of the failed query.
+     * @param options.method - The SDA method that triggered the query, or `null`.
+     * @param options.parameters - The method's arguments, or `null`.
+     * @param options.query - The SQL statement that failed.
+     * @param options.cause - The original error thrown while executing the query.
+     *
+     * @example
+     * ```ts
+     * const error = new SDAError({
+     *   method: "example()",
+     *   parameters: { column: "missing" },
+     *   query: "SELECT missing FROM data",
+     *   cause: new Error("Column not found"),
+     * });
+     * console.log(error.method, error.cause);
+     * ```
+     */
+    constructor(options) {
+        let causeMessage = options.cause instanceof Error
+            ? options.cause.message
+            : String(options.cause);
+        if (causeMessage.includes("connection disconnected")) {
+            causeMessage =
+                "Database connection closed before all operations finished. Did you forget to add `await`?";
+        }
+        super(options.method === null
+            ? causeMessage
+            : `${causeMessage}\nSDA method: ${options.method}`, { cause: options.cause });
+        /**
+         * The SDA method that triggered the failing query.
+         */
+        Object.defineProperty(this, "method", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * The parameters passed to the method.
+         */
+        Object.defineProperty(this, "parameters", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * The SQL query that failed.
+         */
+        Object.defineProperty(this, "query", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "SDAError";
+        this.method = options.method;
+        this.parameters = options.parameters;
+        this.query = options.query;
+    }
+}
+exports.default = SDAError;

package/script/class/Simple.d.ts

@@ -1,32 +1,28 @@
-import type { DuckDBConnection, DuckDBInstance } from "@duckdb/node-api";
+import type { DuckDBConnection, DuckDBInstance, DuckDBValue } from "@duckdb/node-api";
 /**
- * An abstract base class providing common properties for SimpleDB and SimpleTable. This class is not intended for direct instantiation.
+ * Shared implementation of the properties used by SimpleDB and SimpleTable.
+ * This base class is not intended for direct instantiation.
+ * @internal
  */
 export default class Simple {
-    /**
-     * A flag indicating whether to log debugging information.
-     *
-     * @defaultValue `false`
-     */
-    debug: boolean;
     /**
      * The number of rows to display when logging a table.
      *
      * @defaultValue `10`
      */
-    nbRowsToLog: number;
+    rowsToLog: number;
     /**
      * A flag indicating whether to include data types when logging a table.
      *
      * @defaultValue `false`
      */
-    types: boolean;
+    typesToLog: boolean;
     /**
      * The maximum number of characters to display for text-based cells. If undefined, the entire text is shown.
      *
      * @defaultValue `undefined`
      */
-    nbCharactersToLog: number | undefined;
+    charsToLog: number | undefined;
     /**
      * A DuckDB database instance.
      */
@@ -42,25 +38,47 @@ export default class Simple {
      */
     defaultTableName: boolean;
     /**
-     * A function for running SQL queries. This is for internal use only. To run a custom SQL query, use the SimpleDB.customQuery method.
+     * A function for running SQL queries. Subclasses can wrap this seam to observe
+     * execution while forwarding every argument. To run custom SQL, use
+     * `SimpleDB.customQuery()` instead.
+     *
+     * @param query - The exact SQL statement to execute.
+     * @param connection - The DuckDB connection that executes the statement.
+     * @param returnData - Whether to convert and return result rows.
+     * @param options - Error-attribution, binding, and observability options.
+     * @param options.method - The SDA method responsible for the query, when available.
+     * @param options.parameters - The method arguments recorded for error attribution.
+     * @param options.table - The table associated with returned values and warnings.
+     * @param options.values - Data values bound to placeholders in the SQL statement.
+     * @param options.logSQL - Whether to log the SQL immediately before execution.
+     * @param options.explainSQL - Whether to log a supported DuckDB query plan before execution.
+     * @returns The converted rows when requested, otherwise `null`.
+     *
+     * @example
+     * ```ts
+     * const original = table.runQuery;
+     * table.runQuery = (query, connection, returnData, options) => {
+     *   console.log(query);
+     *   return original(query, connection, returnData, options);
+     * };
+     * ```
      */
-    runQuery: (query: string, connection: DuckDBConnection, returnDataFromQuery: boolean, options: {
-        debug: boolean;
+    runQuery: (query: string, connection: DuckDBConnection, returnData: boolean, options: {
         method: string | null;
         parameters: {
             [key: string]: unknown;
         } | null;
-        types?: {
-            [key: string]: string;
-        };
+        table?: string | null;
+        values?: DuckDBValue[];
+        logSQL: boolean;
+        explainSQL: boolean;
     }) => Promise<{
-        [key: string]: number | string | Date | boolean | null;
+        [key: string]: unknown;
     }[] | null>;
     constructor(options?: {
-        debug?: boolean;
-        nbRowsToLog?: number;
-        nbCharactersToLog?: number;
-        types?: boolean;
+        rowsToLog?: number;
+        charsToLog?: number;
+        typesToLog?: boolean;
     });
 }
 //# sourceMappingURL=Simple.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Simple.d.ts","sourceRoot":"","sources":["../../src/class/Simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;OAEG;IACH,EAAE,EAAG,cAAc,CAAC;IACpB;;OAEG;IACH,UAAU,EAAG,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAG,CACT,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,mBAAmB,EAAE,OAAO,EAC5B,OAAO,EAAE;QACP,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,UAAU,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAC9C,KAAK,CAAC,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;KACnC,KACE,OAAO,CACR;QACA,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;KACxD,EAAE,GACD,IAAI,CACP,CAAC;gBAGA,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;CAQT"}
+{"version":3,"file":"Simple.d.ts","sourceRoot":"","sources":["../../src/class/Simple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;OAEG;IACH,EAAE,EAAG,cAAc,CAAC;IACpB;;OAEG;IACH,UAAU,EAAG,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,EAAG,CACT,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,UAAU,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QAC9C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;KACrB,KACE,OAAO,CACR;QACA,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,EAAE,GACD,IAAI,CACP,CAAC;gBAGA,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,CAAC;KACjB;CAOT"}

package/script/class/Simple.js

@@ -1,27 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * An abstract base class providing common properties for SimpleDB and SimpleTable. This class is not intended for direct instantiation.
+ * Shared implementation of the properties used by SimpleDB and SimpleTable.
+ * This base class is not intended for direct instantiation.
+ * @internal
  */
 class Simple {
     constructor(options = {}) {
-        /**
-         * A flag indicating whether to log debugging information.
-         *
-         * @defaultValue `false`
-         */
-        Object.defineProperty(this, "debug", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         /**
          * The number of rows to display when logging a table.
          *
          * @defaultValue `10`
          */
-        Object.defineProperty(this, "nbRowsToLog", {
+        Object.defineProperty(this, "rowsToLog", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -32,7 +23,7 @@ class Simple {
          *
          * @defaultValue `false`
          */
-        Object.defineProperty(this, "types", {
+        Object.defineProperty(this, "typesToLog", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -43,7 +34,7 @@ class Simple {
          *
          * @defaultValue `undefined`
          */
-        Object.defineProperty(this, "nbCharactersToLog", {
+        Object.defineProperty(this, "charsToLog", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -79,7 +70,30 @@ class Simple {
             value: void 0
         });
         /**
-         * A function for running SQL queries. This is for internal use only. To run a custom SQL query, use the SimpleDB.customQuery method.
+         * A function for running SQL queries. Subclasses can wrap this seam to observe
+         * execution while forwarding every argument. To run custom SQL, use
+         * `SimpleDB.customQuery()` instead.
+         *
+         * @param query - The exact SQL statement to execute.
+         * @param connection - The DuckDB connection that executes the statement.
+         * @param returnData - Whether to convert and return result rows.
+         * @param options - Error-attribution, binding, and observability options.
+         * @param options.method - The SDA method responsible for the query, when available.
+         * @param options.parameters - The method arguments recorded for error attribution.
+         * @param options.table - The table associated with returned values and warnings.
+         * @param options.values - Data values bound to placeholders in the SQL statement.
+         * @param options.logSQL - Whether to log the SQL immediately before execution.
+         * @param options.explainSQL - Whether to log a supported DuckDB query plan before execution.
+         * @returns The converted rows when requested, otherwise `null`.
+         *
+         * @example
+         * ```ts
+         * const original = table.runQuery;
+         * table.runQuery = (query, connection, returnData, options) => {
+         *   console.log(query);
+         *   return original(query, connection, returnData, options);
+         * };
+         * ```
          */
         Object.defineProperty(this, "runQuery", {
             enumerable: true,
@@ -87,10 +101,9 @@ class Simple {
             writable: true,
             value: void 0
         });
-        this.nbRowsToLog = options.nbRowsToLog ?? 10;
-        this.nbCharactersToLog = options.nbCharactersToLog;
-        this.types = options.types ?? false;
-        this.debug = options.debug ?? false;
+        this.rowsToLog = options.rowsToLog ?? 10;
+        this.charsToLog = options.charsToLog;
+        this.typesToLog = options.typesToLog ?? false;
         this.defaultTableName = false;
     }
 }