@nshiab/simple-data-analysis-core 2.1.12 → 2.1.13

package/esm/class/SimpleDB.js

@@ -1,1133 +0,0 @@
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var _SimpleDB_instances, _SimpleDB_closePromise, _SimpleDB_startPromise, _SimpleDB_initialized, _SimpleDB_setup, _SimpleDB_close;
-import quoteIdentifier from "../helpers/quoteIdentifier.js";
-import { DuckDBInstance } from "@duckdb/node-api";
-import runQuery from "../helpers/runQuery.js";
-import SimpleTable from "./SimpleTable.js";
-import cleanCache from "../helpers/cleanCache.js";
-import prettyDuration from "../helpers/prettyDuration.js";
-import Simple from "./Simple.js";
-import queryDB from "../helpers/queryDB.js";
-import mergeOptions from "../helpers/mergeOptions.js";
-import getTableNames from "../methods/getTableNames.js";
-import { existsSync, rmSync } from "node:fs";
-import createDirectory from "../helpers/createDirectory.js";
-import getDbFileType from "../helpers/getDbFileType.js";
-import getCurrentDatabase from "../helpers/getCurrentDatabase.js";
-import getDbIndexes from "../helpers/getDbIndexes.js";
-import readDbMetadata from "../helpers/readDbMetadata.js";
-import writeDbMetadata from "../helpers/writeDbMetadata.js";
-import prepareDbExtensions from "../helpers/prepareDbExtensions.js";
-import setDbProps from "../helpers/setDbProps.js";
-import queryDbFile from "../helpers/queryDbFile.js";
-import removeTables from "../methods/removeTables.js";
-import selectTables from "../methods/selectTables.js";
-import loadDB from "../methods/loadDB.js";
-import writeDB from "../methods/writeDB.js";
-import flushAllTables, { runExemptFromFlush, } from "../helpers/flushAllTables.js";
-import { discardAllPending } from "../helpers/queueOp.js";
-import { initializeTableRegistry, listRegisteredTables, registerTable, } from "../helpers/tableRegistry.js";
-import formatMissingTables from "../helpers/formatMissingTables.js";
-/**
- * Manages a DuckDB database instance, providing a simplified interface for database operations.
- *
- * @example
- * ```ts
- * // Create an in-memory database instance
- * const sdb = new SimpleDB();
- * // 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.close();
- * ```
- *
- * @example
- * ```ts
- * // Open or create a persistent DuckDB database. Changes persist in this file.
- * const sdb = new SimpleDB({ file: "./my_database.db" });
- * // Perform database operations...
- * // Execute pending work, save SDA metadata, and close the database connection
- * await sdb.close();
- * ```
- *
- * @example
- * ```ts
- * // Create a database instance with custom options
- * const sdb = new SimpleDB({
- *   logSQL: true, // Log SQL immediately before it runs
- *   rowsToLog: 20 // Set the number of rows to log by default
- * });
- * ```
- */
-class SimpleDB extends Simple {
-    /**
-     * Creates a new SimpleDB instance.
-     *
-     * DuckDB sessions use UTC so temporal parsing, extraction, and returned
-     * `TIMESTAMP WITH TIME ZONE` strings are consistent across environments.
-     *
-     * Existing tables and SDA index metadata are restored on first use. The
-     * `__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.
-     * @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.rowsToLog - The number of rows to display when logging a table.
-     * @param options.charsToLog - The maximum characters to display for text and stringified nested cells, including truncation markers (default: 75). Independent of column width. Use Infinity for unlimited text.
-     * @param options.typesToLog - A flag indicating whether to include data types when logging a table.
-     * @param options.cacheVerbose - Whether to log cache hits and misses, code and input changes, TTL status, and cache read/write timing.
-     * @param options.expressionSyntax - Operator syntax for expressions and custom queries: `"js"` (default) translates JavaScript-style operators in SQL expressions; `"sql"` preserves SQL unchanged.
-     * @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 (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
-     */
-    constructor(options = {}) {
-        super(options);
-        _SimpleDB_instances.add(this);
-        /**
-         * The operator syntax used by expressions and custom queries in this database.
-         * `"js"` translates JavaScript-style operators (`&&`, `||`, `==`, `===`,
-         * `!==`) and null comparisons within SQL expressions. It does not evaluate
-         * arbitrary JavaScript. `||` remains concatenation when string literals, list
-         * literals, explicit text casts, or `concat()` results make that intent clear.
-         * Otherwise `||` becomes OR; column types are not inferred. Use `concat()`
-         * when concatenation would otherwise be ambiguous, such as `first || last`.
-         * `"sql"` passes SQL through unchanged, including `||` and null comparisons.
-         * Choose the syntax when constructing the database; it applies to all tables.
-         *
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ expressionSyntax: "js" }); // The default mode
-         * // || becomes SQL OR: keep rows where at least one condition is true.
-         * await sdb.newTable().loadArray([{ active: true, admin: false }])
-         *   .filter("active || admin").log();
-         * ```
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ expressionSyntax: "js" });
-         * // && becomes SQL AND: both conditions must be true.
-         * // === becomes SQL =: compare the age with 18.
-         * await sdb.newTable().loadArray([{ active: true, age: 18 }])
-         *   .filter("active && age === 18").log();
-         * ```
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ expressionSyntax: "js" });
-         * // SQL AND and OR also work in JS mode; they pass through unchanged.
-         * // Keep active adults, or anyone who is an admin.
-         * await sdb.newTable().loadArray([{ active: true, age: 18, admin: false }])
-         *   .filter("(active AND age >= 18) OR admin").log();
-         * ```
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ expressionSyntax: "js" });
-         * // Bare column names do not establish concatenation. Use concat() explicitly.
-         * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
-         *   .addColumn("name", "string", "concat(first, ' ', last)").log();
-         * ```
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB(); // JS mode is the default
-         * // The string literal ' ' makes concatenation clear, so both || stay unchanged.
-         * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
-         *   .addColumn("name", "string", "first || ' ' || last").log();
-         * ```
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ expressionSyntax: "sql" });
-         * // SQL mode preserves || as concatenation: the name becomes "Jane Doe".
-         * await sdb.newTable().loadArray([{ first: "Jane", last: "Doe" }])
-         *   .addColumn("name", "string", "first || ' ' || last").log();
-         * ```
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ expressionSyntax: "sql" });
-         * // Use SQL AND and OR for logical conditions; && and || are not translated.
-         * // Both active and adult must be true, unless admin is true.
-         * 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,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * Whether to log each SQL statement immediately before execution.
-         *
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ logSQL: true });
-         * ```
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "logSQL", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * Whether to log DuckDB query plans before supported statements execute.
-         *
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ explainSQL: true });
-         * ```
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "explainSQL", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * An array of paths to the data sources used in the cache.
-         *
-         * @defaultValue `[]`
-         * @category Properties
-         */
-        Object.defineProperty(this, "cacheSourcesUsed", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A timestamp marking the start of a duration measurement.
-         *
-         * @defaultValue `undefined`
-         * @category Properties
-         */
-        Object.defineProperty(this, "durationStart", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A counter for incrementing default table names.
-         *
-         * @defaultValue `1`
-         * @category Properties
-         */
-        Object.defineProperty(this, "tableIncrement", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A flag indicating whether to log the total execution duration.
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "logDuration", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * Whether to log cache hits and misses, code and input changes, TTL status,
-         * and cache read/write timing.
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "cacheVerbose", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * The total time saved by using the cache, in milliseconds.
-         *
-         * @defaultValue `0`
-         * @category Properties
-         */
-        Object.defineProperty(this, "cacheTimeSaved", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * The total time spent writing to the cache, in milliseconds.
-         *
-         * @defaultValue `0`
-         * @category Properties
-         */
-        Object.defineProperty(this, "cacheTimeWriting", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A flag indicating whether to display a progress bar for long-running operations.
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "progressBar", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * The in-flight flush of the pending chains, if one is running. Concurrent
-         * observers await it instead of reading mid-flush state. This is for
-         * internal use only.
-         *
-         * @defaultValue `null`
-         * @internal
-         */
-        Object.defineProperty(this, "flushPromise", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        _SimpleDB_closePromise.set(this, null);
-        _SimpleDB_startPromise.set(this, null);
-        _SimpleDB_initialized.set(this, false);
-        /**
-         * The database lifecycle state. This is for internal use only.
-         *
-         * @internal
-         */
-        Object.defineProperty(this, "lifecycleState", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * The number of queued operations across all tables, so query execution
-         * points skip the flush entirely when nothing is pending. This is for
-         * internal use only.
-         *
-         * @defaultValue `0`
-         * @internal
-         */
-        Object.defineProperty(this, "pendingCount", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A counter stamping queued operations with their position in program
-         * order across all tables, so flushes replay them in the order they were
-         * queued. This is for internal use only.
-         *
-         * @defaultValue `0`
-         * @internal
-         */
-        Object.defineProperty(this, "opSequence", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A flag indicating that the spatial extension has been loaded on this
-         * connection, so it's only loaded once. This is for internal use only.
-         *
-         * @defaultValue `false`
-         * @internal
-         */
-        Object.defineProperty(this, "spatialLoaded", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A flag indicating whether to use DuckDB's external file cache.
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "duckDbCache", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * The maximum amount of memory DuckDB is allowed to use (e.g., `'4GB'`). Defaults to 80% of system RAM.
-         *
-         * @defaultValue `undefined`
-         * @category Properties
-         */
-        Object.defineProperty(this, "memoryLimit", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * 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. Temporary directories are automatically removed when calling `close()`.
-         *
-         * @defaultValue `undefined`
-         * @category Properties
-         */
-        Object.defineProperty(this, "tempDir", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * The path to the persistent DuckDB database, opened or created on first use.
-         * If not provided, an in-memory database is used. Imports and exports do not change this path.
-         *
-         * @defaultValue `:memory:`
-         * @category Properties
-         */
-        Object.defineProperty(this, "file", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * Whether to replace an existing DuckDB file on first use instead of opening it.
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "overwrite", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * Whether the persistent DuckDB file is opened read-only. Requires an existing
-         * file and cannot be combined with `overwrite`. DuckDB rejects writes to it.
-         *
-         * @example
-         * ```ts
-         * const sdb = new SimpleDB({ file: "./archive.duckdb", readOnly: true });
-         * const table = await sdb.getTable("employees");
-         * await table.log();
-         * await sdb.close();
-         * ```
-         *
-         * @defaultValue `false`
-         * @category Properties
-         */
-        Object.defineProperty(this, "readOnly", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * The class used to create table instances. Defaults to `SimpleTable`.
-         * Override this property when subclassing to ensure all table-creating
-         * methods (e.g., `newTable()`, `clone()`) return instances of your
-         * custom table class.
-         *
-         * @example
-         * ```ts
-         * class MyTable extends SimpleTable {
-         *   customMethod() { return "hello"; }
-         * }
-         *
-         * class MyDB extends SimpleDB {
-         *   constructor(options?: SimpleDBOptions) {
-         *     super(options);
-         *     this.tableClass = MyTable;
-         *   }
-         * }
-         *
-         * const db = new MyDB();
-         * const table = db.newTable("myTable");
-         * console.log(table.customMethod()); // "hello"
-         * ```
-         *
-         * @defaultValue `SimpleTable`
-         * @category Properties
-         */
-        Object.defineProperty(this, "tableClass", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: SimpleTable
-        });
-        if (options.expressionSyntax !== undefined &&
-            !["js", "sql"].includes(options.expressionSyntax)) {
-            throw new Error('expressionSyntax must be "js" or "sql".');
-        }
-        this.expressionSyntax = options.expressionSyntax ?? "js";
-        this.file = options.file ?? ":memory:";
-        this.logSQL = options.logSQL ?? false;
-        this.explainSQL = options.explainSQL ?? false;
-        this.overwrite = options.overwrite ?? false;
-        this.readOnly = options.readOnly ?? false;
-        this.logDuration = options.logDuration ?? false;
-        this.tableIncrement = 1;
-        initializeTableRegistry(this);
-        this.cacheSourcesUsed = [];
-        this.cacheVerbose = options.cacheVerbose ?? false;
-        this.cacheTimeSaved = 0;
-        this.cacheTimeWriting = 0;
-        this.progressBar = options.progressBar ?? false;
-        this.duckDbCache = options.duckDbCache === undefined
-            ? false
-            : options.duckDbCache;
-        this.memoryLimit = options.memoryLimit;
-        this.tempDir = options.tempDir;
-        this.flushPromise = null;
-        this.lifecycleState = "open";
-        this.pendingCount = 0;
-        this.opSequence = 0;
-        this.spatialLoaded = false;
-        this.runQuery = runQuery;
-        if (this.cacheVerbose || this.logDuration) {
-            this.durationStart = Date.now();
-        }
-    }
-    /**
-     * Initializes the DuckDB database instance and connection.
-     *
-     * @returns A promise that resolves to the SimpleDB instance after initialization.
-     * @internal
-     * @category Lifecycle
-     */
-    async start() {
-        if (this.lifecycleState === "closed") {
-            throw new Error(`start() cannot use a SimpleDB that is ${this.lifecycleState}.`);
-        }
-        if (__classPrivateFieldGet(this, _SimpleDB_startPromise, "f") === null) {
-            // The setup queries below must run before any queued operation, so
-            // they must not trigger a flush.
-            __classPrivateFieldSet(this, _SimpleDB_startPromise, runExemptFromFlush(this, async () => {
-                await __classPrivateFieldGet(this, _SimpleDB_instances, "m", _SimpleDB_setup).call(this);
-                __classPrivateFieldSet(this, _SimpleDB_initialized, true, "f");
-                return this;
-            }), "f");
-        }
-        return await __classPrivateFieldGet(this, _SimpleDB_startPromise, "f");
-    }
-    /**
-     * Creates a new SimpleTable instance within the database.
-     * The name must be unique among registered tables, ignoring ASCII letter case.
-     *
-     * @example
-     * ```ts
-     * // Create a table with a default name (e.g., "table1", "table2", etc.)
-     * const dataTable = await sdb
-     *   .newTable()
-     *   .loadArray([{ value: 1 }])
-     *   .log();
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Create a table with a specific name
-     * const employees = await sdb
-     *   .newTable("employees")
-     *   .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") {
-            throw new Error(`newTable() cannot use a SimpleDB that is ${this.lifecycleState}.`);
-        }
-        const TableClass = this.tableClass;
-        // SHOULD MATCH clone
-        let table;
-        if (typeof name === "string") {
-            table = new TableClass(name, this, {
-                rowsToLog: this.rowsToLog,
-                charsToLog: this.charsToLog,
-                typesToLog: this.typesToLog,
-            });
-            table.defaultTableName = false;
-        }
-        else {
-            while (this.getTables().some((table) => table.name.toLowerCase() === `table${this.tableIncrement}`)) {
-                this.tableIncrement++;
-            }
-            table = new TableClass(`table${this.tableIncrement}`, this, {
-                rowsToLog: this.rowsToLog,
-                charsToLog: this.charsToLog,
-                typesToLog: this.typesToLog,
-            });
-            table.defaultTableName = true;
-            this.tableIncrement += 1;
-        }
-        registerTable(this, table);
-        return table;
-    }
-    /**
-     * Retrieves an existing SimpleTable instance from the database.
-     *
-     * @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();
-        const tables = this.getTables();
-        const table = tables.find((t) => t.name === name);
-        if (table) {
-            return await table;
-        }
-        else {
-            throw new Error(formatMissingTables("getTable()", [name], tables.map((availableTable) => availableTable.name)));
-        }
-    }
-    /**
-     * Removes one or more tables from the database.
-     *
-     * @example
-     * ```ts
-     * // Remove a single table by name
-     * await sdb.removeTables("employees");
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Remove multiple tables by name
-     * await sdb.removeTables(["customers", "products"]);
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Remove a single table using a SimpleTable instance
-     * const employeesTable = sdb.newTable("employees");
-     * // ... load data ...
-     * await sdb.removeTables(employeesTable);
-     * ```
-     *
-     * @example
-     * ```ts
-     * // 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 removeTables(this, tables);
-        return this;
-    }
-    /**
-     * Selects one or more tables to keep in the database, removing all others.
-     *
-     * @example
-     * ```ts
-     * // Select a single table by name, removing all other tables
-     * await sdb.selectTables("employees");
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Select multiple tables by name, removing all other tables
-     * await sdb.selectTables(["customers", "products"]);
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Select a single table using a SimpleTable instance
-     * const employeesTable = sdb.newTable("employees");
-     * // ... 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 selectTables(this, tables);
-        return this;
-    }
-    /**
-     * Returns an array of all table names in the database, sorted alphabetically.
-     *
-     * @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 getTableNames(this);
-    }
-    /**
-     * Logs the names of all tables in the database to the console, sorted alphabetically.
-     *
-     * @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();
-        if (tables.length > 0) {
-            console.log(`\nSimpleDB - Tables:  ${JSON.stringify(tables)}`);
-        }
-        else {
-            console.log(`\nSimpleDB - No tables found.`);
-        }
-        return this;
-    }
-    /**
-     * Returns an array of all SimpleTable instances in the database.
-     *
-     * The returned array is a snapshot and cannot mutate the database's internal
-     * table registry.
-     *
-     * @example
-     * ```ts
-     * // Get all SimpleTable instances
-     * const tables = sdb.getTables();
-     * ```
-     *
-     * @returns A read-only array of SimpleTable instances.
-     * @category Table Management
-     */
-    getTables() {
-        return listRegisteredTables(this);
-    }
-    /**
-     * Checks if a table exists in the database.
-     *
-     * @example
-     * ```ts
-     * // Check if a table named "employees" exists
-     * const exists = await sdb.hasTable("employees");
-     * console.log(exists); // Output: true or false
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Check if a SimpleTable instance exists in the database
-     * const myTable = sdb.newTable("my_data");
-     * 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;
-        const result = (await this.getTableNames()).includes(tableName);
-        return result;
-    }
-    /**
-     * Returns a list of installed DuckDB extensions.
-     *
-     * @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 queryDB(this, `FROM duckdb_extensions();`, mergeOptions(this, {
-            returnData: true,
-            table: null,
-            method: "getExtensions()",
-            parameters: {},
-        })));
-    }
-    /**
-     * Executes a custom SQL query directly against the DuckDB instance.
-     * With the default `SimpleDB.expressionSyntax: "js"`, queries support JavaScript-style operators (`&&`, `||`, `===`, `!==`). Set `expressionSyntax: "sql"` for unchanged SQL.
-     * Queries run in UTC. When data is returned, temporal values use the same
-     * JavaScript representations as `SimpleTable.getData()`.
-     *
-     * `customQuery()` bypasses the dependency and table-generation tracking used
-     * by `SimpleTable.cache()`. Reading or changing a table with `customQuery()`
-     * can therefore cause `cache()` to return stale data. Include a value that
-     * identifies the custom query's dependencies in the cache's `options.inputs`
-     * (such as a table content hash), or use tracked `SimpleTable` methods.
-     *
-     * @example
-     * ```ts
-     * // Execute a query without returning data
-     * await sdb.customQuery("CREATE TABLE young_employees AS SELECT * FROM employees WHERE age > 30");
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Execute a query and return the results
-     * const youngEmployees = await sdb.customQuery(
-     *   "SELECT * FROM employees WHERE age < 30",
-     *   { returnData: true }
-     * );
-     * 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 queryDB(this, query, mergeOptions(this, {
-            returnData: options.returnData ?? false,
-            table: options.table ?? null,
-            method: "customQuery()",
-            parameters: { query, options },
-        }));
-    }
-    /**
-     * Imports a copy of a `.db` or `.duckdb` (DuckDB) or `.sqlite` (SQLite)
-     * file into the current database. The source is opened read-only and detached
-     * after importing; subsequent transformations do not modify the source file.
-     * Imports work with in-memory and writable persistent databases. Existing
-     * table-name conflicts are rejected. A failed import may leave partial changes
-     * in the destination database.
-     *
-     * DuckDB files restore embedded SDA index definitions when present. SQLite
-     * imports copy data without SDA index metadata. The `__sda` schema is reserved
-     * for SDA metadata.
-     * To edit an existing DuckDB file in place, use `new SimpleDB({ file })`.
-     *
-     * @example
-     * ```ts
-     * // Load a DuckDB database file
-     * await sdb.loadDB("./my_database.db");
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Import SQLite tables without modifying the original file
-     * await sdb.loadDB("./my_database.sqlite");
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Import a copy into a persistent DuckDB database
-     * const sdb = new SimpleDB({ file: "./analysis.duckdb" });
-     * 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 loadDB(this, file);
-        return this;
-    }
-    /**
-     * Exports a snapshot of the current database after executing pending work.
-     * Does not change the working database or where subsequent changes persist.
-     * DuckDB outputs (`.db` and `.duckdb`) preserve database objects and embed SDA
-     * index definitions in the reserved `__sda` schema.
-     *
-     * SQLite output (`.sqlite`) materializes main-schema tables and views as
-     * tables. It does not preserve DuckDB schemas, indexes, constraints, or SDA
-     * metadata, and SQLite type conversion may lose type information. Unsupported
-     * conversions fail without replacing an existing destination.
-     *
-     * Existing files require explicit overwrite permission. The completed export
-     * is published only after its connection is detached. Database files attached
-     * to this instance, directories, and symbolic links cannot be replaced.
-     *
-     * @example
-     * ```ts
-     * // Write the current database to a DuckDB file
-     * await sdb.writeDB("./my_exported_database.db");
-     * ```
-     *
-     * @example
-     * ```ts
-     * // Explicitly replace an earlier snapshot
-     * await sdb.writeDB("./my_exported_database.duckdb", { overwrite: true });
-     * ```
-     *
-     * @example
-     * ```ts
-     * // 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 writeDB(this, file, options);
-        return this;
-    }
-    /**
-     * Executes all queued methods across every table in the database. Sync
-     * builder methods (like `filter()` or `convert()`) only queue their
-     * operation; execution happens when an async observer method (like
-     * `getData()`, `log()`, or `writeData()`) is awaited. Use `run()` when
-     * your script ends in pure mutations with nothing to observe and you want
-     * the work done now.
-     *
-     * The whole database is flushed in program order, so operations on
-     * different tables execute exactly in the order they were queued. This is
-     * the database-level counterpart to `SimpleTable.run()`.
-     *
-     * @example
-     * ```ts
-     * // Nothing is observed after the mutations, so run() executes them.
-     * table1.loadData("data1.csv").convert({ price: "number" });
-     * 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") {
-            throw new Error(`run() cannot use a SimpleDB that is ${this.lifecycleState}.`);
-        }
-        await flushAllTables(this);
-        return this;
-    }
-    /**
-     * Executes pending transformations, saves SDA metadata for writable persistent
-     * databases, and closes the connection and instance. Also cleans up temporary
-     * files and the cache. Does not copy, compact, or replace the database file.
-     *
-     * @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) {
-            return await __classPrivateFieldGet(this, _SimpleDB_closePromise, "f");
-        }
-        this.lifecycleState = "closing";
-        const closePromise = __classPrivateFieldGet(this, _SimpleDB_instances, "m", _SimpleDB_close).call(this);
-        __classPrivateFieldSet(this, _SimpleDB_closePromise, closePromise, "f");
-        return await closePromise;
-    }
-}
-_SimpleDB_closePromise = new WeakMap(), _SimpleDB_startPromise = new WeakMap(), _SimpleDB_initialized = new WeakMap(), _SimpleDB_instances = new WeakSet(), _SimpleDB_setup = async function _SimpleDB_setup() {
-    if (this.readOnly && (this.file === ":memory:" || this.overwrite)) {
-        throw new Error("readOnly requires an existing database file and cannot be combined with overwrite.");
-    }
-    if (this.file !== ":memory:") {
-        if (getDbFileType(this.file) !== "duckdb") {
-            throw new Error("Persistent databases must use .db or .duckdb. Use loadDB() to import SQLite files.");
-        }
-        if (this.readOnly && !existsSync(this.file)) {
-            throw new Error(`The file ${this.file} does not exist.`);
-        }
-        if (existsSync(this.file) && this.overwrite) {
-            rmSync(this.file);
-            // A WAL belongs to the database being explicitly replaced.
-            rmSync(`${this.file}.wal`, { force: true });
-        }
-        if (!this.readOnly)
-            createDirectory(this.file);
-    }
-    this.db = await DuckDBInstance.create(this.file, this.readOnly ? { access_mode: "READ_ONLY" } : {});
-    this.connection = await this.db.connect();
-    // Keep temporal parsing, extraction, and serialization deterministic
-    // across machines. DuckDB otherwise inherits the process timezone.
-    await this.customQuery("SET TimeZone = 'UTC';");
-    // By default, DuckDB does not compress in-memory databases, so we enable it here.
-    if (this.file === ":memory:") {
-        await this.customQuery(`ATTACH OR REPLACE ':memory:' AS ${quoteIdentifier("memory")} (COMPRESS);`);
-    }
-    if (this.duckDbCache === true) {
-        await this.customQuery("SET enable_external_file_cache=true;");
-    }
-    else if (this.duckDbCache === false) {
-        await this.customQuery("SET enable_external_file_cache=false;");
-    }
-    if (this.progressBar) {
-        await this.customQuery(`SET enable_progress_bar = TRUE; SET progress_bar_time = 0;`);
-    }
-    if (this.memoryLimit !== undefined) {
-        await this.customQuery(`SET memory_limit = '${this.memoryLimit}';`);
-    }
-    if (this.tempDir !== undefined) {
-        await this.customQuery(`SET temp_directory = '${this.tempDir}';`);
-    }
-    if (this.file !== ":memory:") {
-        const database = await getCurrentDatabase(this);
-        const indexes = await readDbMetadata(this, database);
-        await prepareDbExtensions(this, database, indexes);
-        const existingNames = new Set((await this.getTableNames()).map((name) => name.toLowerCase()));
-        const conflicts = this.getTables().filter((table) => existingNames.has(table.name.toLowerCase()));
-        if (conflicts.length > 0) {
-            throw new Error(`Tables already exist in ${this.file}: ${conflicts.map((table) => table.name).join(", ")}. Use getTable() to access them.`);
-        }
-        await setDbProps(this, indexes);
-    }
-}, _SimpleDB_close = async function _SimpleDB_close() {
-    let operationError;
-    try {
-        await flushAllTables(this);
-        if (this.file !== ":memory:" && !this.readOnly && __classPrivateFieldGet(this, _SimpleDB_initialized, "f")) {
-            const database = await getCurrentDatabase(this);
-            await readDbMetadata(this, database);
-            await writeDbMetadata(this, database, getDbIndexes(this));
-            await queryDbFile(this, `CHECKPOINT ${quoteIdentifier(database)};`);
-        }
-    }
-    catch (error) {
-        operationError = error;
-        // A failed flush can requeue work belonging to other tables. The
-        // connection is about to close, so release those captured values.
-        discardAllPending(this);
-    }
-    const cleanupErrors = [];
-    const cacheCleanupMessages = [];
-    if (this.db instanceof DuckDBInstance) {
-        try {
-            this.connection.closeSync();
-        }
-        catch (error) {
-            cleanupErrors.push(error);
-        }
-        try {
-            this.db.closeSync();
-        }
-        catch (error) {
-            cleanupErrors.push(error);
-        }
-    }
-    try {
-        const tmpDir = this.tempDir ??
-            (this.file === ":memory:" ? ".tmp" : `${this.file}.tmp`);
-        if (existsSync(tmpDir)) {
-            rmSync(tmpDir, { recursive: true });
-        }
-        // Defer cache logs until after the summary, while timing cleanup too.
-        cleanCache(this, (message) => cacheCleanupMessages.push(message));
-    }
-    catch (error) {
-        cleanupErrors.push(error);
-    }
-    this.lifecycleState = "closed";
-    if (operationError === undefined && cleanupErrors.length === 0 &&
-        typeof this.durationStart === "number") {
-        let string = prettyDuration(this.durationStart, {
-            prefix: "\n\nSimpleDB ran for ",
-        });
-        if (this.cacheTimeSaved > 0) {
-            string += ` / ${prettyDuration(0, {
-                end: this.cacheTimeSaved,
-            })} saved by using the cache`;
-        }
-        if (this.cacheTimeWriting > 0) {
-            string += ` / ${prettyDuration(0, {
-                end: this.cacheTimeWriting,
-            })} spent writing the cache`;
-        }
-        console.log(`${string}\n`);
-    }
-    for (const message of cacheCleanupMessages) {
-        console.log(message);
-    }
-    if (cacheCleanupMessages.length > 0) {
-        console.log();
-    }
-    if (operationError !== undefined && cleanupErrors.length > 0) {
-        throw new AggregateError([operationError, ...cleanupErrors], "Pending execution and database cleanup both failed.", { cause: operationError });
-    }
-    if (operationError !== undefined) {
-        throw operationError;
-    }
-    if (cleanupErrors.length === 1) {
-        throw cleanupErrors[0];
-    }
-    if (cleanupErrors.length > 1) {
-        throw new AggregateError(cleanupErrors, "Multiple errors occurred while cleaning up the database.", { cause: cleanupErrors[0] });
-    }
-    return await this;
-};
-export default SimpleDB;