@nshiab/simple-data-analysis-core 2.0.9 → 2.1.0

package/script/class/SimpleDB.js

@@ -121,6 +121,14 @@ class SimpleDB extends Simple_js_1.default {
      * `__sda` schema is reserved for versioned SDA metadata. SQLite files can be
      * imported with `loadDB()` but cannot be used as the persistent database.
      *
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({
+     *   logSQL: true,
+     *   explainSQL: true,
+     * });
+     * ```
+     *
      * @param options - Configuration options for the SimpleDB instance.
      * @param options.file - A `.db` or `.duckdb` file to open or create. Defaults to an in-memory database.
      * @param options.overwrite - If true, replaces an existing file on first use. Defaults to false, which opens the existing file.
@@ -138,14 +146,6 @@ class SimpleDB extends Simple_js_1.default {
      * @param options.memoryLimit - The maximum amount of memory DuckDB is allowed to use (e.g., `'4GB'`). Defaults to 80% of system RAM.
      * @param options.tempDir - The path to the directory used for temporary files when data exceeds the memory limit (e.g., `'/tmp/duckdb_swap'`). Defaults to `.tmp` for in-memory databases or `<file>.tmp` for file-based databases. Automatically removed when calling `close()`.
      * @category Constructor
-     *
-     * @example
-     * ```ts
-     * const sdb = new SimpleDB({
-     *   logSQL: true,
-     *   explainSQL: true,
-     * });
-     * ```
      */
     constructor(options = {}) {
         super(options);
@@ -161,8 +161,6 @@ class SimpleDB extends Simple_js_1.default {
          * `"sql"` passes SQL through unchanged, including `||` and null comparisons.
          * Choose the syntax when constructing the database; it applies to all tables.
          *
-         * @defaultValue `"js"`
-         * @category Properties
          * @example
          * ```ts
          * const sdb = new SimpleDB({ expressionSyntax: "js" }); // The default mode
@@ -215,6 +213,9 @@ class SimpleDB extends Simple_js_1.default {
          * await sdb.newTable().loadArray([{ active: true, age: 18, admin: false }])
          *   .filter("(active AND age >= 18) OR admin").log();
          * ```
+         *
+         * @defaultValue `"js"`
+         * @category Properties
          */
         Object.defineProperty(this, "expressionSyntax", {
             enumerable: true,
@@ -225,12 +226,13 @@ class SimpleDB extends Simple_js_1.default {
         /**
          * Whether to log each SQL statement immediately before execution.
          *
-         * @defaultValue `false`
-         * @category Properties
          * @example
          * ```ts
          * const sdb = new SimpleDB({ logSQL: true });
          * ```
+         *
+         * @defaultValue `false`
+         * @category Properties
          */
         Object.defineProperty(this, "logSQL", {
             enumerable: true,
@@ -241,12 +243,13 @@ class SimpleDB extends Simple_js_1.default {
         /**
          * Whether to log DuckDB query plans before supported statements execute.
          *
-         * @defaultValue `false`
-         * @category Properties
          * @example
          * ```ts
          * const sdb = new SimpleDB({ explainSQL: true });
          * ```
+         *
+         * @defaultValue `false`
+         * @category Properties
          */
         Object.defineProperty(this, "explainSQL", {
             enumerable: true,
@@ -485,8 +488,6 @@ class SimpleDB extends Simple_js_1.default {
          * Whether the persistent DuckDB file is opened read-only. Requires an existing
          * file and cannot be combined with `overwrite`. DuckDB rejects writes to it.
          *
-         * @defaultValue `false`
-         * @category Properties
          * @example
          * ```ts
          * const sdb = new SimpleDB({ file: "./archive.duckdb", readOnly: true });
@@ -494,6 +495,9 @@ class SimpleDB extends Simple_js_1.default {
          * await table.log();
          * await sdb.close();
          * ```
+         *
+         * @defaultValue `false`
+         * @category Properties
          */
         Object.defineProperty(this, "readOnly", {
             enumerable: true,
@@ -507,9 +511,6 @@ class SimpleDB extends Simple_js_1.default {
          * methods (e.g., `newTable()`, `clone()`) return instances of your
          * custom table class.
          *
-         * @defaultValue `SimpleTable`
-         * @category Properties
-         *
          * @example
          * ```ts
          * class MyTable extends SimpleTable {
@@ -527,6 +528,9 @@ class SimpleDB extends Simple_js_1.default {
          * const table = db.newTable("myTable");
          * console.log(table.customMethod()); // "hello"
          * ```
+         *
+         * @defaultValue `SimpleTable`
+         * @category Properties
          */
         Object.defineProperty(this, "tableClass", {
             enumerable: true,
@@ -593,10 +597,6 @@ class SimpleDB extends Simple_js_1.default {
      * Creates a new SimpleTable instance within the database.
      * The name must be unique among registered tables, ignoring ASCII letter case.
      *
-     * @param name - The name of the new table. If not provided, a default name is generated (e.g., "table1").
-     * @returns A new table instance.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Create a table with a default name (e.g., "table1", "table2", etc.)
@@ -614,6 +614,10 @@ class SimpleDB extends Simple_js_1.default {
      *   .loadData("employees.csv")
      *   .log();
      * ```
+     *
+     * @param name - The name of the new table. If not provided, a default name is generated (e.g., "table1").
+     * @returns A new table instance.
+     * @category Table Management
      */
     newTable(name) {
         if (this.lifecycleState !== "open") {
@@ -648,16 +652,16 @@ class SimpleDB extends Simple_js_1.default {
     /**
      * Retrieves an existing SimpleTable instance from the database.
      *
-     * @param name - The name of the table to retrieve.
-     * @returns A promise that resolves to the SimpleTable instance if found.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Retrieve the "employees" table
      * const employees = await sdb.getTable("employees");
      * await employees.log();
      * ```
+     *
+     * @param name - The name of the table to retrieve.
+     * @returns A promise that resolves to the SimpleTable instance if found.
+     * @category Table Management
      */
     async getTable(name) {
         await this.start();
@@ -673,10 +677,6 @@ class SimpleDB extends Simple_js_1.default {
     /**
      * Removes one or more tables from the database.
      *
-     * @param tables - A single table or an array of tables to remove, specified by name or as SimpleTable instances. Pass `"all"` to remove all tables.
-     * @returns A promise that resolves to the database, so methods can be chained.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Remove a single table by name
@@ -702,6 +702,10 @@ class SimpleDB extends Simple_js_1.default {
      * // Remove all tables
      * await sdb.removeTables("all");
      * ```
+     *
+     * @param tables - A single table or an array of tables to remove, specified by name or as SimpleTable instances. Pass `"all"` to remove all tables.
+     * @returns A promise that resolves to the database, so methods can be chained.
+     * @category Table Management
      */
     async removeTables(tables) {
         await (0, removeTables_js_1.default)(this, tables);
@@ -710,10 +714,6 @@ class SimpleDB extends Simple_js_1.default {
     /**
      * Selects one or more tables to keep in the database, removing all others.
      *
-     * @param tables - A single table or an array of tables to select, specified by name or as SimpleTable instances.
-     * @returns A promise that resolves to the database, so methods can be chained.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Select a single table by name, removing all other tables
@@ -733,6 +733,10 @@ class SimpleDB extends Simple_js_1.default {
      * // ... load data ...
      * await sdb.selectTables(employeesTable);
      * ```
+     *
+     * @param tables - A single table or an array of tables to select, specified by name or as SimpleTable instances.
+     * @returns A promise that resolves to the database, so methods can be chained.
+     * @category Table Management
      */
     async selectTables(tables) {
         await (0, selectTables_js_1.default)(this, tables);
@@ -741,15 +745,15 @@ class SimpleDB extends Simple_js_1.default {
     /**
      * Returns an array of all table names in the database, sorted alphabetically.
      *
-     * @returns A promise that resolves to an array of table names.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Get all table names
      * const tableNames = await sdb.getTableNames();
      * console.log(tableNames); // Output: ["employees", "customers"]
      * ```
+     *
+     * @returns A promise that resolves to an array of table names.
+     * @category Table Management
      */
     async getTableNames() {
         return await (0, getTableNames_js_1.default)(this);
@@ -757,15 +761,15 @@ class SimpleDB extends Simple_js_1.default {
     /**
      * Logs the names of all tables in the database to the console, sorted alphabetically.
      *
-     * @returns A promise that resolves to the database, so methods can be chained.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Log all table names to the console
      * await sdb.logTableNames();
      * // Example output: SimpleDB - Tables:  ["employees","customers"]
      * ```
+     *
+     * @returns A promise that resolves to the database, so methods can be chained.
+     * @category Table Management
      */
     async logTableNames() {
         const tables = await this.getTableNames();
@@ -783,14 +787,14 @@ class SimpleDB extends Simple_js_1.default {
      * The returned array is a snapshot and cannot mutate the database's internal
      * table registry.
      *
-     * @returns A read-only array of SimpleTable instances.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Get all SimpleTable instances
      * const tables = sdb.getTables();
      * ```
+     *
+     * @returns A read-only array of SimpleTable instances.
+     * @category Table Management
      */
     getTables() {
         return (0, tableRegistry_js_1.listRegisteredTables)(this);
@@ -798,10 +802,6 @@ class SimpleDB extends Simple_js_1.default {
     /**
      * Checks if a table exists in the database.
      *
-     * @param table - The name of the table or a SimpleTable instance.
-     * @returns A promise that resolves to `true` if the table exists, `false` otherwise.
-     * @category Table Management
-     *
      * @example
      * ```ts
      * // Check if a table named "employees" exists
@@ -816,6 +816,10 @@ class SimpleDB extends Simple_js_1.default {
      * const existsInstance = await sdb.hasTable(myTable);
      * console.log(existsInstance); // Output: true or false
      * ```
+     *
+     * @param table - The name of the table or a SimpleTable instance.
+     * @returns A promise that resolves to `true` if the table exists, `false` otherwise.
+     * @category Table Management
      */
     async hasTable(table) {
         const tableName = typeof table === "string" ? table : table.name;
@@ -825,15 +829,15 @@ class SimpleDB extends Simple_js_1.default {
     /**
      * Returns a list of installed DuckDB extensions.
      *
-     * @returns A promise that resolves to an array of objects, each representing an installed extension.
-     * @category DuckDB
-     *
      * @example
      * ```ts
      * // Get a list of all installed extensions
      * const extensions = await sdb.getExtensions();
      * console.log(extensions); // Output: [{ extension_name: "spatial", loaded: true, ... }]
      * ```
+     *
+     * @returns A promise that resolves to an array of objects, each representing an installed extension.
+     * @category DuckDB
      */
     async getExtensions() {
         return (await (0, queryDB_js_1.default)(this, `FROM duckdb_extensions();`, (0, mergeOptions_js_1.default)(this, {
@@ -855,13 +859,6 @@ class SimpleDB extends Simple_js_1.default {
      * identifies the custom query's dependencies in the cache's `options.inputs`
      * (such as a table content hash), or use tracked `SimpleTable` methods.
      *
-     * @param query - The SQL query string to execute.
-     * @param options - Configuration options for the query.
-     * @param options.returnData - If `true`, the query result is returned. Defaults to `false`.
-     * @param options.table - The name of the table associated with the query, primarily used for debugging and logging.
-     * @returns A promise that resolves to the query result as an array of objects if `returnData` is `true`, otherwise `null`.
-     * @category DuckDB
-     *
      * @example
      * ```ts
      * // Execute a query without returning data
@@ -877,6 +874,13 @@ class SimpleDB extends Simple_js_1.default {
      * );
      * console.log(youngEmployees);
      * ```
+     *
+     * @param query - The SQL query string to execute.
+     * @param options - Configuration options for the query.
+     * @param options.returnData - If `true`, the query result is returned. Defaults to `false`.
+     * @param options.table - The name of the table associated with the query, primarily used for debugging and logging.
+     * @returns A promise that resolves to the query result as an array of objects if `returnData` is `true`, otherwise `null`.
+     * @category DuckDB
      */
     async customQuery(query, options = {}) {
         return await (0, queryDB_js_1.default)(this, query, (0, mergeOptions_js_1.default)(this, {
@@ -898,10 +902,6 @@ class SimpleDB extends Simple_js_1.default {
      * for SDA metadata.
      * To edit an existing DuckDB file in place, use `new SimpleDB({ file })`.
      *
-     * @param file - The relative or absolute path to the database file.
-     * @returns A promise that resolves to the database, so methods can be chained.
-     * @category File Operations
-     *
      * @example
      * ```ts
      * // Load a DuckDB database file
@@ -921,6 +921,10 @@ class SimpleDB extends Simple_js_1.default {
      * await sdb.loadDB("./archive.db");
      * await sdb.close();
      * ```
+     *
+     * @param file - The relative or absolute path to the database file.
+     * @returns A promise that resolves to the database, so methods can be chained.
+     * @category File Operations
      */
     async loadDB(file) {
         await (0, loadDB_js_1.default)(this, file);
@@ -941,13 +945,6 @@ class SimpleDB extends Simple_js_1.default {
      * is published only after its connection is detached. Database files attached
      * to this instance, directories, and symbolic links cannot be replaced.
      *
-     * @param file - The relative or absolute path to the output file.
-     * @param options - Configuration options for writing the database.
-     * @param options.overwrite - If true, permits atomic replacement of an existing output file. Defaults to false.
-     * @param options.metadata - If false, omits logical SDA index definitions from DuckDB exports. Defaults to true. Does not control physical indexes; SQLite exports never include SDA metadata.
-     * @returns A promise that resolves to the database, so methods can be chained.
-     * @category File Operations
-     *
      * @example
      * ```ts
      * // Write the current database to a DuckDB file
@@ -965,6 +962,13 @@ class SimpleDB extends Simple_js_1.default {
      * // Export table data for use with SQLite
      * await sdb.writeDB("./my_exported_database.sqlite");
      * ```
+     *
+     * @param file - The relative or absolute path to the output file.
+     * @param options - Configuration options for writing the database.
+     * @param options.overwrite - If true, permits atomic replacement of an existing output file. Defaults to false.
+     * @param options.metadata - If false, omits logical SDA index definitions from DuckDB exports. Defaults to true. Does not control physical indexes; SQLite exports never include SDA metadata.
+     * @returns A promise that resolves to the database, so methods can be chained.
+     * @category File Operations
      */
     async writeDB(file, options = {}) {
         await (0, writeDB_js_1.default)(this, file, options);
@@ -982,9 +986,6 @@ class SimpleDB extends Simple_js_1.default {
      * different tables execute exactly in the order they were queued. This is
      * the database-level counterpart to `SimpleTable.run()`.
      *
-     * @returns A promise that resolves to the SimpleDB instance once the queued methods have been executed.
-     * @category Lifecycle
-     *
      * @example
      * ```ts
      * // Nothing is observed after the mutations, so run() executes them.
@@ -992,6 +993,9 @@ class SimpleDB extends Simple_js_1.default {
      * table2.loadData("data2.csv").filter(`price > 0`);
      * await sdb.run();
      * ```
+     *
+     * @returns A promise that resolves to the SimpleDB instance once the queued methods have been executed.
+     * @category Lifecycle
      */
     async run() {
         if (this.lifecycleState !== "open") {
@@ -1005,16 +1009,16 @@ class SimpleDB extends Simple_js_1.default {
      * databases, and closes the connection and instance. Also cleans up temporary
      * files and the cache. Does not copy, compact, or replace the database file.
      *
-     * @returns A promise that resolves to the SimpleDB instance after cleanup.
-     * @throws An error after cleanup when pending execution or cleanup fails.
-     * @category Lifecycle
-     *
      * @example
      * ```ts
      * // close() executes queued transformations before cleaning up resources.
      * table.loadData("data.csv").convert({ price: "number" });
      * await sdb.close();
      * ```
+     *
+     * @returns A promise that resolves to the SimpleDB instance after cleanup.
+     * @throws An error after cleanup when pending execution or cleanup fails.
+     * @category Lifecycle
      */
     async close() {
         if (__classPrivateFieldGet(this, _SimpleDB_closePromise, "f") !== null) {