@nshiab/simple-data-analysis 5.20.8 → 5.21.0

package/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/1.0.0/src/class/SimpleDB.d.ts

@@ -1,482 +0,0 @@
-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, 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").
-     * @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): 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 (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/esm/deps/jsr.io/@nshiab/simple-data-analysis-core/1.0.0/src/class/SimpleDB.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SimpleDB.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/simple-data-analysis-core/1.0.0/src/class/SimpleDB.ts"],"names":[],"mappings":"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"}