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

package/README.md

@@ -1,29 +1,26 @@
 # Simple data analysis core (SDA-core)
 
-This repository contains the core functionalities of the
-[simple-data-analysis library](https://github.com/nshiab/simple-data-analysis),
-an easy-to-use and high-performance TypeScript library for data analysis that
-you can use with tabular, geospatial and vector data.
+SDA-core is a lightweight DuckDB-powered TypeScript library for tabular, SQL,
+CSV, Parquet, and geospatial data analysis on Deno, Node.js, and Bun. It has one
+runtime dependency: DuckDB.
 
-You'll find here a stripped-out version with only one dependency (DuckDB) that
-is aimed to be light-weight and to be used in constrained environment.
+Choose this package for core data loading, cleaning, joining, statistics, and
+geospatial operations. For AI, vector search, Google Sheets, and data
+visualization features, use the full
+[simple-data-analysis library](https://github.com/nshiab/simple-data-analysis).
 
 The library is available on
 [JSR](https://jsr.io/@nshiab/simple-data-analysis-core) with its
 [documentation](https://jsr.io/@nshiab/simple-data-analysis-core/doc).
 
-The documentation is also available as the markdown file
-[llm.md](https://github.com/nshiab/simple-data-analysis-core/blob/main/llm.md),
-which can be passed as context to improve the use of the library by AI coding
-assistants or agents.
+AI coding assistants and agents can start with the concise
+[llms.txt](https://github.com/nshiab/simple-data-analysis-core/blob/main/llms.txt)
+index. The complete generated API reference is available in
+[llm.md](https://github.com/nshiab/simple-data-analysis-core/blob/main/llm.md).
 
 The library is maintained by [Nael Shiab](http://naelshiab.com/), computational
 journalist and senior data producer for [CBC News](https://www.cbc.ca/news).
 
-For the full-fledged library (with AI, dataviz, google sheet methods and more),
-check the
-[simple-data-analysis repository](https://github.com/nshiab/simple-data-analysis).
-
 > [!TIP]
 > To learn how to use SDA, check out
 > [Code Like a Journalist](https://www.code-like-a-journalist.com/), a free and
@@ -62,3 +59,158 @@ npx @nshiab/setup-data-project
 # Bun
 bunx @nshiab/setup-data-project
 ```
+
+## Database files in version 2
+
+`new SimpleDB()` works in memory. To work directly in a DuckDB file, pass
+`{ file: "./analysis.duckdb" }`: SDA opens an existing file or creates a new one
+on first use. Await `getTable()` to access a saved table, or `start()` to
+restore all saved table handles before using the synchronous `getTables()`
+method. `{ readOnly: true }` opens an existing file without allowing changes.
+
+```ts
+const sdb = new SimpleDB({ file: "./analysis.duckdb" });
+const observations = await sdb.getTable("observations");
+await observations.filter("value IS NOT NULL").log();
+await sdb.close();
+```
+
+`loadDB(file)` imports a copy into the current database, including into a
+persistent database. It opens the source read-only, rejects existing table-name
+conflicts, and rolls back failed copies. `writeDB(file)` exports a snapshot
+after executing pending work; subsequent changes still affect the working
+database.
+
+When migrating from the previous interface:
+
+- Replace `loadDB(file, { detach: false })` with `new SimpleDB({ file })` for
+  DuckDB files. The `detach` and `name` import options have been removed. SQLite
+  files are supported for import/export, not as the persistent working database.
+- The constructor now opens existing files by default. Explicit
+  `overwrite: true` still replaces a file on first use.
+- Existing export destinations require `writeDB(file, { overwrite: true })`.
+  Exports finish in a temporary file before publishing the output. Open database
+  files attached to that instance, symbolic links, and directories cannot be
+  replaced.
+- DuckDB files support both `.db` and `.duckdb` extensions. SDA index
+  definitions are stored inside the reserved `__sda` schema. Writable persistent
+  databases save metadata on `close()`.
+- SQLite exports contain main-schema tables and views materialized as tables.
+  They do not preserve DuckDB schemas, indexes, constraints, or SDA metadata.
+  SQLite conversion may lose type information; unsupported conversions fail
+  without replacing the destination.
+- `close()` executes pending work, saves metadata, and releases resources. It no
+  longer compacts or replaces persistent database files.
+
+## Performance benchmarks
+
+These benchmarks compare SDA-core with raw DuckDB and popular Python and R
+libraries, measuring duration and peak memory.
+
+They were run on a MacBook Pro with an Apple M4 Max and 64 GB of memory.
+
+<!-- benchmark-results:start -->
+
+### Tabular workload
+
+Using 22,051,025 temperature records (`ahccd.csv`, 1.77 GB, in
+`benchmarks/data/`), we remove missing temperatures, convert dates and numbers,
+save the cleaned data, then calculate average temperatures by station and decade
+and export the sorted results.
+
+| Library version                           | Runtime       |  Mean duration | Duration difference | Mean peak memory | Memory difference |
+| ----------------------------------------- | ------------- | -------------: | ------------------: | ---------------: | ----------------: |
+| @duckdb/node-api 1.5.5-r.4; DuckDB v1.5.5 | Deno 2.9.6    |  1.14 ± 0.01 s |               -8.2% |         2,372 MB |             -7.1% |
+| SDA-core 2.0.0                            | Deno 2.9.6    |  1.24 ± 0.03 s |            baseline |         2,554 MB |          baseline |
+| pandas 3.0.5                              | Python 3.14.7 | 28.21 ± 0.01 s |            +2168.6% |         4,699 MB |            +84.0% |
+| tidyverse 2.0.0                           | R 4.6.1       | 78.81 ± 0.17 s |            +6236.7% |         8,178 MB |           +220.2% |
+
+### Spatial workload
+
+Using 335,024 Montreal public trees (`arbres-publics.csv`, 135.5 MB) and 91
+neighbourhood boundaries (`quartierreferencehabitation.geojson`, 1.14 MB), both
+in `benchmarks/data/`, we remove missing coordinates, create points, join trees
+to neighbourhoods, then count trees per neighbourhood and export the sorted
+results.
+
+| Library version                           | Runtime       | Mean duration | Duration difference | Mean peak memory | Memory difference |
+| ----------------------------------------- | ------------- | ------------: | ------------------: | ---------------: | ----------------: |
+| @duckdb/node-api 1.5.5-r.4; DuckDB v1.5.5 | Deno 2.9.6    | 0.72 ± 0.01 s |               -3.4% |           255 MB |             -7.2% |
+| SDA-core 2.0.0                            | Deno 2.9.6    | 0.75 ± 0.01 s |            baseline |           275 MB |          baseline |
+| GeoPandas 1.1.4                           | Python 3.14.7 | 1.11 ± 0.00 s |              +48.7% |           292 MB |             +6.0% |
+| sf 1.1.2                                  | R 4.6.1       | 1.58 ± 0.00 s |             +111.2% |           489 MB |            +78.0% |
+
+<!-- benchmark-results:end -->
+
+## Building extensions
+
+The full
+[simple-data-analysis library](https://github.com/nshiab/simple-data-analysis)
+is itself an extension of SDA-core. It subclasses `SimpleTable` to add AI,
+Google Sheets and charting methods, then subclasses `SimpleDB` so every table
+created by the database uses that extended table class.
+
+Follow the same pattern when building an extension. To make new table methods
+chainable, define them on a `SimpleTable` subclass, give them a return type of
+`this` and return `this` after queuing their work. Then extend
+`SimpleDB<YourTable>` and set its `tableClass` to your subclass. Methods that
+create tables should always use `this.sdb.newTable()` so they also return your
+extended table type.
+
+```ts
+import {
+  SimpleDB as CoreDB,
+  SimpleTable as CoreTable,
+} from "@nshiab/simple-data-analysis-core";
+
+class MyTable extends CoreTable {
+  selectForPublication(columns: string[]): this {
+    this.selectColumns(columns);
+    return this;
+  }
+}
+
+class MyDB extends CoreDB<MyTable> {
+  constructor() {
+    super();
+    this.tableClass = MyTable;
+  }
+}
+
+const sdb = new MyDB();
+await sdb
+  .newTable("articles")
+  .loadData("articles.csv")
+  .selectForPublication(["title", "author"])
+  .log();
+```
+
+If an extension must perform asynchronous work before queuing table builders,
+use `queueAsyncBarrier()`. The callback runs at the barrier's position in
+database-wide program order, and builders it queues run before later chained
+operations:
+
+```ts
+import { queueAsyncBarrier } from "@nshiab/simple-data-analysis-core/helpers";
+
+class RemoteTable extends CoreTable {
+  loadRemote(url: string): this {
+    queueAsyncBarrier(this, {
+      method: "loadRemote()",
+      parameters: { url },
+      execute: async () => {
+        const rows = await fetch(url).then((response) => response.json()) as {
+          [key: string]: unknown;
+        }[];
+        this.loadArray(rows);
+      },
+    });
+    return this;
+  }
+}
+```
+
+The callback must await all asynchronous work that can queue builders. If it
+rejects, captured builders that have not already run are discarded. Builders
+already drained by an observer inside the callback remain applied;
+`queueAsyncBarrier()` does not provide database rollback.

package/esm/_dnt.polyfills.d.ts

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

package/esm/_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/esm/_dnt.polyfills.js

@@ -0,0 +1 @@
+export {};

package/esm/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/esm/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/esm/class/SDAError.js

@@ -0,0 +1,83 @@
+/**
+ * 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 {
+    /**
+     * 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;
+    }
+}

package/esm/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/esm/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/esm/class/Simple.js

@@ -1,25 +1,16 @@
 /**
- * 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 {
     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,
@@ -30,7 +21,7 @@ export default class Simple {
          *
          * @defaultValue `false`
          */
-        Object.defineProperty(this, "types", {
+        Object.defineProperty(this, "typesToLog", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -41,7 +32,7 @@ export default class Simple {
          *
          * @defaultValue `undefined`
          */
-        Object.defineProperty(this, "nbCharactersToLog", {
+        Object.defineProperty(this, "charsToLog", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -77,7 +68,30 @@ export default 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,
@@ -85,10 +99,9 @@ export default 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;
     }
 }