@nshiab/simple-data-analysis 5.21.1 → 6.0.0

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/2.0.2/src/class/SimpleDB.js

@@ -0,0 +1,1039 @@
+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.
+     *
+     * @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 number of characters to display for text-based cells.
+     * @param options.typesToLog - A flag indicating whether to include data types when logging a table.
+     * @param options.cacheVerbose - Whether to log cache hits and misses, code and input changes, TTL status, and cache read/write timing.
+     * @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
+     *
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({
+     *   logSQL: true,
+     *   explainSQL: true,
+     * });
+     * ```
+     */
+    constructor(options = {}) {
+        super(options);
+        _SimpleDB_instances.add(this);
+        /**
+         * Whether to log each SQL statement immediately before execution.
+         *
+         * @defaultValue `false`
+         * @category Properties
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ logSQL: true });
+         * ```
+         */
+        Object.defineProperty(this, "logSQL", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Whether to log DuckDB query plans before supported statements execute.
+         *
+         * @defaultValue `false`
+         * @category Properties
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ explainSQL: true });
+         * ```
+         */
+        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.
+         *
+         * @defaultValue `false`
+         * @category Properties
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ file: "./archive.duckdb", readOnly: true });
+         * const table = await sdb.getTable("employees");
+         * await table.log();
+         * await sdb.close();
+         * ```
+         */
+        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.
+         *
+         * @defaultValue `SimpleTable`
+         * @category Properties
+         *
+         * @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"
+         * ```
+         */
+        Object.defineProperty(this, "tableClass", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: SimpleTable
+        });
+        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.
+     *
+     * @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.)
+     * 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();
+     * ```
+     */
+    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.
+     *
+     * @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();
+     * ```
+     */
+    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.
+     *
+     * @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
+     * 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");
+     * ```
+     */
+    async removeTables(tables) {
+        await removeTables(this, tables);
+        return this;
+    }
+    /**
+     * 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
+     * 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);
+     * ```
+     */
+    async selectTables(tables) {
+        await selectTables(this, tables);
+        return this;
+    }
+    /**
+     * 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"]
+     * ```
+     */
+    async getTableNames() {
+        return await getTableNames(this);
+    }
+    /**
+     * 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"]
+     * ```
+     */
+    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.
+     *
+     * @returns A read-only array of SimpleTable instances.
+     * @category Table Management
+     *
+     * @example
+     * ```ts
+     * // Get all SimpleTable instances
+     * const tables = sdb.getTables();
+     * ```
+     */
+    getTables() {
+        return listRegisteredTables(this);
+    }
+    /**
+     * 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
+     * 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
+     * ```
+     */
+    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.
+     *
+     * @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, ... }]
+     * ```
+     */
+    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.
+     * 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.
+     *
+     * @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
+     * 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);
+     * ```
+     */
+    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 and a failed copy is rolled back.
+     *
+     * 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 })`.
+     *
+     * @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
+     * 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();
+     * ```
+     */
+    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.
+     *
+     * @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
+     * 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");
+     * ```
+     */
+    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()`.
+     *
+     * @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.
+     * table1.loadData("data1.csv").convert({ price: "number" });
+     * table2.loadData("data2.csv").filter(`price > 0`);
+     * await sdb.run();
+     * ```
+     */
+    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.
+     *
+     * @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();
+     * ```
+     */
+    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 = [];
+    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 });
+        }
+        cleanCache(this);
+    }
+    catch (error) {
+        cleanupErrors.push(error);
+    }
+    this.lifecycleState = "closed";
+    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] });
+    }
+    if (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`);
+    }
+    return await this;
+};
+export default SimpleDB;