@nshiab/simple-data-analysis-core 0.0.12

package/script/class/SimpleDB.d.ts

@@ -0,0 +1,487 @@
+import SimpleTable from "./SimpleTable.js";
+import Simple from "./Simple.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 new table named "employees"
+ * const employees = sdb.newTable("employees");
+ * // Load data from a CSV file into the "employees" table
+ * await employees.loadData("./employees.csv");
+ * // Log the first few rows of the "employees" table to the console
+ * await employees.logTable();
+ * // Close the database connection and clean up resources
+ * await sdb.done();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Create a persistent database instance, saving data to a file
+ * // To load an existing database, use the `loadDB` method instead
+ * const sdb = new SimpleDB({ file: "./my_database.db" });
+ * // Perform database operations...
+ * // Close the database connection, which saves changes to the specified file
+ * await sdb.done();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Create a database instance with custom options
+ * const sdb = new SimpleDB({
+ *   debug: true, // Enable debugging output
+ *   nbRowsToLog: 20 // Set the number of rows to log by default
+ * });
+ * ```
+ */
+export default class SimpleDB<Table extends SimpleTable = SimpleTable> extends Simple {
+    /**
+     * An array of paths to the data sources used in the cache.
+     *
+     * @defaultValue `[]`
+     * @category Properties
+     */
+    cacheSourcesUsed: string[];
+    /**
+     * A timestamp marking the start of a duration measurement.
+     *
+     * @defaultValue `undefined`
+     * @category Properties
+     */
+    durationStart: number | undefined;
+    /**
+     * A counter for incrementing default table names.
+     *
+     * @defaultValue `1`
+     * @category Properties
+     */
+    tableIncrement: number;
+    /**
+     * A flag indicating whether to log the total execution duration.
+     *
+     * @defaultValue `false`
+     * @category Properties
+     */
+    logDuration: boolean;
+    /**
+     * An array of table instances associated with this database.
+     *
+     * @defaultValue `[]`
+     * @category Properties
+     */
+    tables: Table[];
+    /**
+     * A flag indicating whether to log verbose cache-related messages.
+     *
+     * @defaultValue `false`
+     * @category Properties
+     */
+    cacheVerbose: boolean;
+    /**
+     * The total time saved by using the cache, in milliseconds.
+     *
+     * @defaultValue `0`
+     * @category Properties
+     */
+    cacheTimeSaved: number;
+    /**
+     * The total time spent writing to the cache, in milliseconds.
+     *
+     * @defaultValue `0`
+     * @category Properties
+     */
+    cacheTimeWriting: number;
+    /**
+     * A flag indicating whether to display a progress bar for long-running operations.
+     *
+     * @defaultValue `false`
+     * @category Properties
+     */
+    progressBar: boolean;
+    /**
+     * A flag indicating whether to use DuckDB's external file cache.
+     *
+     * @defaultValue `false`
+     * @category Properties
+     */
+    duckDbCache: boolean | null;
+    /**
+     * The path to the database file. If not provided, an in-memory database is used.
+     *
+     * @defaultValue `:memory:`
+     * @category Properties
+     */
+    file: string;
+    /**
+     * A flag indicating whether to overwrite the database file if it already exists.
+     *
+     * @defaultValue `false`
+     * @category Properties
+     */
+    overwrite: boolean;
+    /**
+     * The class used to create table instances. Defaults to `SimpleTable`.
+     * Override this property when subclassing to ensure all table-creating
+     * methods (e.g., `newTable()`, `cloneTable()`) 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"
+     * ```
+     */
+    tableClass: new (name: string, projections: {
+        [key: string]: string;
+    }, sdb: SimpleDB, options?: {
+        debug?: boolean;
+        nbRowsToLog?: number;
+        nbCharactersToLog?: number;
+        types?: boolean;
+    }) => Table;
+    /**
+     * Creates a new SimpleDB instance.
+     *
+     * @param options - Configuration options for the SimpleDB instance.
+     * @param options.file - The path to the database file. If not provided, an in-memory database is used.
+     * @param options.overwrite - A flag indicating whether to overwrite the database file if it already exists.
+     * @param options.logDuration - A flag indicating whether to log the total execution duration.
+     * @param options.nbRowsToLog - The number of rows to display when logging a table.
+     * @param options.nbCharactersToLog - The maximum number of characters to display for text-based cells.
+     * @param options.types - A flag indicating whether to include data types when logging a table.
+     * @param options.cacheVerbose - A flag indicating whether to log verbose cache-related messages.
+     * @param options.debug - A flag indicating whether to log debugging information.
+     * @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.
+     * @category Constructor
+     */
+    constructor(options?: {
+        file?: string;
+        overwrite?: boolean;
+        logDuration?: boolean;
+        nbRowsToLog?: number;
+        nbCharactersToLog?: number;
+        types?: boolean;
+        cacheVerbose?: boolean;
+        debug?: boolean;
+        duckDbCache?: boolean | null;
+        progressBar?: boolean;
+    });
+    /**
+     * Initializes the DuckDB database instance and connection.
+     *
+     * @returns A promise that resolves to the SimpleDB instance after initialization.
+     * @internal
+     * @category Lifecycle
+     */
+    start(): Promise<SimpleDB>;
+    /**
+     * Adds a SimpleTable instance to the internal list of tables.
+     *
+     * @param table - The SimpleTable instance to add.
+     * @internal
+     * @category Table Management
+     */
+    pushTable(table: Table): void;
+    /**
+     * 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").
+     * @param projections - An object mapping column names to their geospatial projections.
+     * @returns A new table instance.
+     * @category Table Management
+     *
+     * @example
+     * ```ts
+     * // Create a table with a default name (e.g., "table1", "table2", etc.)
+     * const dataTable = sdb.newTable();
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Create a table with a specific name
+     * const employees = sdb.newTable("employees");
+     * ```
+     */
+    newTable(name?: string, projections?: {
+        [key: string]: string;
+    }): 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");
+     * ```
+     */
+    getTable(name: string): Promise<Table>;
+    /**
+     * 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.
+     * @returns A promise that resolves when the tables have been removed.
+     * @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);
+     * ```
+     */
+    removeTables(tables: Table | string | (Table | string)[]): Promise<void>;
+    /**
+     * 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 when the tables have been selected.
+     * @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);
+     * ```
+     */
+    selectTables(tables: Table | string | (Table | string)[]): Promise<void>;
+    /**
+     * 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"]
+     * ```
+     */
+    getTableNames(): Promise<string[]>;
+    /**
+     * Logs the names of all tables in the database to the console, sorted alphabetically.
+     *
+     * @returns A promise that resolves when the table names have been logged.
+     * @category Table Management
+     *
+     * @example
+     * ```ts
+     * // Log all table names to the console
+     * await sdb.logTableNames();
+     * // Example output: SimpleDB - Tables:  ["employees","customers"]
+     * ```
+     */
+    logTableNames(): Promise<void>;
+    /**
+     * Returns an array of all SimpleTable instances in the database.
+     *
+     * @returns A promise that resolves to an array of SimpleTable instances.
+     * @category Table Management
+     *
+     * @example
+     * ```ts
+     * // Get all SimpleTable instances
+     * const tables = await sdb.getTables();
+     * ```
+     */
+    getTables(): Promise<Table[]>;
+    /**
+     * 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
+     * ```
+     */
+    hasTable(table: Table | string): Promise<boolean>;
+    /**
+     * 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, ... }]
+     * ```
+     */
+    getExtensions(): Promise<{
+        [key: string]: string | number | boolean | Date | null;
+    }[]>;
+    /**
+     * Executes a custom SQL query directly against the DuckDB instance.
+     *
+     * If you want to force the returned data to match the types of the columns, you can use the `types` option.
+     *
+     * @param query - The SQL query string to execute.
+     * @param options - Configuration options for the query.
+     * @param options.returnDataFrom - Specifies whether to return data from the query. Can be `"query"` to return data or `"none"` (default) to not return data.
+     * @param options.table - The name of the table associated with the query, primarily used for debugging and logging.
+     * @param options.types - An optional object specifying data types for the query parameters.
+     * @returns A promise that resolves to the query result as an array of objects if `returnDataFrom` is `"query"`, 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",
+     *   { returnDataFrom: "query" }
+     * );
+     * console.log(youngEmployees);
+     * ```
+     */
+    customQuery(query: string, options?: {
+        returnDataFrom?: "query" | "none";
+        table?: string;
+        types?: {
+            [key: string]: string;
+        };
+    }): Promise<{
+        [key: string]: string | number | boolean | Date | null;
+    }[] | null>;
+    /**
+     * Loads a database from a specified file into the current SimpleDB instance.
+     * Supported file types are `.db` (DuckDB) and `.sqlite` (SQLite).
+     *
+     * @param file - The absolute path to the database file (e.g., "./my_database.db").
+     * @param options - Configuration options for loading the database.
+     * @param options.name - The name to assign to the loaded database within the DuckDB instance. Defaults to the file name without extension.
+     * @param options.detach - If `true` (default), the database is detached after loading its contents into memory. If `false`, the database remains attached.
+     * @returns A promise that resolves when the database has been loaded.
+     * @category File Operations
+     *
+     * @example
+     * ```ts
+     * // Load a DuckDB database file
+     * await sdb.loadDB("./my_database.db");
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Load a SQLite database file and keep it attached
+     * await sdb.loadDB("./my_database.sqlite", { detach: false });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Load a database with a custom name
+     * await sdb.loadDB("./archive.db", { name: "archive_db" });
+     * ```
+     */
+    loadDB(file: string, options?: {
+        name?: string;
+        detach?: boolean;
+    }): Promise<void>;
+    /**
+     * Writes the current state of the database to a specified file.
+     * Supported output file types are `.db` (DuckDB) and `.sqlite` (SQLite).
+     *
+     * @param file - The absolute path to the output file (e.g., "./my_exported_database.db").
+     * @param options - Configuration options for writing the database.
+     * @param options.noMetaData - If `true`, metadata files (projections, indexes) are not created alongside the database file. Defaults to `false`.
+     * @returns A promise that resolves when the database has been written to the file.
+     * @category File Operations
+     *
+     * @example
+     * ```ts
+     * // Write the current database to a DuckDB file
+     * await sdb.writeDB("./my_exported_database.db");
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Write the current database to a SQLite file without metadata
+     * await sdb.writeDB("./my_exported_database.sqlite", { noMetaData: true });
+     * ```
+     */
+    writeDB(file: string, options?: {
+        noMetaData?: boolean;
+    }): Promise<void>;
+    /**
+     * Frees up memory by closing the database connection and instance, and cleans up the cache.
+     * If the database is file-based, it also compacts the database file to optimize storage.
+     *
+     * @returns A promise that resolves to the SimpleDB instance after cleanup.
+     * @category Lifecycle
+     *
+     * @example
+     * ```ts
+     * // Close the database and clean up resources
+     * await sdb.done();
+     * ```
+     */
+    done(): Promise<SimpleDB>;
+}
+//# sourceMappingURL=SimpleDB.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SimpleDB.d.ts","sourceRoot":"","sources":["../../src/class/SimpleDB.ts"],"names":[],"mappings":"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"}