update: dbm types (#46)

* update: dbm types

* add: file manager types

* update: paths

* add: comment

Author: vpbs2

meerkat-dbm/src/dbm/dbm.spec.ts

@@ -2,13 +2,12 @@ import { AsyncDuckDB } from '@duckdb/duckdb-wasm';
 import log from 'loglevel';
 import {
   FileBufferStore,
-  FileData,
   FileManagerType,
-  Table,
 } from '../file-manager/file-manager-type';
-import { DBM, DBMConstructorOptions } from './dbm';
+import { FileData, Table, TableWiseFiles } from '../types';
+import { DBM } from './dbm';
 import { InstanceManagerType } from './instance-manager';
-
+import { DBMConstructorOptions } from './types';
 export class MockFileManager implements FileManagerType {
   private fileBufferStore: Record<string, FileBufferStore> = {};
   private tables: Record<string, Table> = {};
@@ -80,16 +79,8 @@ export class MockFileManager implements FileManagerType {
     }
   }
 
-  async getFilesNameForTables(tableNames: string[]): Promise<
-    {
-      tableName: string;
-      files: string[];
-    }[]
-  > {
-    const data: {
-      tableName: string;
-      files: string[];
-    }[] = [];
+  async getFilesNameForTables(tableNames: string[]): Promise<TableWiseFiles[]> {
+    const data: TableWiseFiles[] = [];
 
     for (const tableName of tableNames) {
       const files: string[] = [];
@@ -184,8 +175,8 @@ describe('DBM', () => {
   });
 
   describe('queryWithTableNames', () => {
-    it('should call the beforeQuery hook', async () => {
-      const beforeQuery = jest.fn();
+    it('should call the preQuery hook', async () => {
+      const preQuery = jest.fn();
 
       await fileManager.registerFileBuffer({
         fileName: 'file1',
@@ -197,13 +188,13 @@ describe('DBM', () => {
         'SELECT * FROM table1',
         ['table1'],
         {
-          beforeQuery,
+          preQuery,
         }
       );
 
-      expect(beforeQuery).toBeCalledTimes(1);
+      expect(preQuery).toBeCalledTimes(1);
 
-      expect(beforeQuery).toBeCalledWith([
+      expect(preQuery).toBeCalledWith([
         {
           tableName: 'table1',
           files: ['file1'],
@@ -271,7 +262,7 @@ describe('DBM', () => {
       // If instanceManager.terminateDB is a method
       jest.spyOn(instanceManager, 'terminateDB');
 
-      const onDuckdbShutdown = jest.fn();
+      const onDuckDBShutdown = jest.fn();
 
       // If instanceManager.terminateDB is a function
       instanceManager.terminateDB = jest.fn();
@@ -282,7 +273,7 @@ describe('DBM', () => {
         onEvent: (event) => {
           console.log(event);
         },
-        onDuckdbShutdown: onDuckdbShutdown,
+        onDuckDBShutdown: onDuckDBShutdown,
         options: {
           shutdownInactiveTime: 100,
         },
@@ -320,9 +311,9 @@ describe('DBM', () => {
       await new Promise((resolve) => setTimeout(resolve, 200));
 
       /**
-       * Expect onDuckdbShutdown to be called
+       * Expect onDuckDBShutdown to be called
        */
-      expect(onDuckdbShutdown).toBeCalled();
+      expect(onDuckDBShutdown).toBeCalled();
 
       /**
        * Expect instanceManager.terminateDB to be called

meerkat-dbm/src/dbm/dbm.ts

@@ -4,80 +4,35 @@ import { DBMEvent } from '../logger/event-types';
 import { DBMLogger } from '../logger/logger-types';
 import { InstanceManagerType } from './instance-manager';
 
-export interface DBMConstructorOptions {
-  fileManager: FileManagerType;
-  logger: DBMLogger;
-  onEvent?: (event: DBMEvent) => void;
-  onDuckdbShutdown?: () => void;
-  instanceManager: InstanceManagerType;
-  options?: {
-    /**
-     * shutdown the database after inactive of this time in milliseconds
-     */
-    shutdownInactiveTime?: number;
-  };
-}
-
-type BeforeQueryHook = (
-  data: {
-    tableName: string;
-    files: string[];
-  }[]
-) => Promise<void>;
-
-type QueryOptions = {
-  beforeQuery?: BeforeQueryHook;
-  metadata?: object;
-};
+import { DBMConstructorOptions, QueryOptions, QueryQueueItem } from './types';
 
 export class DBM {
   private fileManager: FileManagerType;
   private instanceManager: InstanceManagerType;
   private connection: AsyncDuckDBConnection | null = null;
-  private queriesQueue: {
-    query: string;
-    tableNames: string[];
-    promise: {
-      resolve: (value: any) => void;
-      reject: (reason?: any) => void;
-    };
-    /**
-     * Timestamp when the query was added to the queue
-     */
-    timestamp: number;
-    options?: QueryOptions;
-  }[] = [];
-  private beforeQuery?: ({
-    query,
-    tableByFiles,
-  }: {
-    query: string;
-    tableByFiles: {
-      tableName: string;
-      files: string[];
-    }[];
-  }) => Promise<void>;
+  private queriesQueue: QueryQueueItem[] = [];
+
   private queryQueueRunning = false;
   private logger: DBMLogger;
   private onEvent?: (event: DBMEvent) => void;
   private options: DBMConstructorOptions['options'];
   private terminateDBTimeout: NodeJS.Timeout | null = null;
-  private onDuckdbShutdown?: () => void;
+  private onDuckDBShutdown?: () => void;
 
   constructor({
     fileManager,
     logger,
     onEvent,
     options,
     instanceManager,
-    onDuckdbShutdown,
+    onDuckDBShutdown,
   }: DBMConstructorOptions) {
     this.fileManager = fileManager;
     this.logger = logger;
     this.onEvent = onEvent;
     this.options = options;
     this.instanceManager = instanceManager;
-    this.onDuckdbShutdown = onDuckdbShutdown;
+    this.onDuckDBShutdown = onDuckDBShutdown;
   }
 
   private async _shutdown() {
@@ -86,8 +41,8 @@ export class DBM {
       this.connection = null;
     }
     this.logger.debug('Shutting down the DB');
-    if (this.onDuckdbShutdown) {
-      this.onDuckdbShutdown();
+    if (this.onDuckDBShutdown) {
+      this.onDuckDBShutdown();
     }
     await this.fileManager.onDBShutdownHandler();
     await this.instanceManager.terminateDB();
@@ -159,10 +114,10 @@ export class DBM {
     );
 
     /**
-     * Execute the beforeQuery hook
+     * Execute the preQuery hook
      */
-    if (options?.beforeQuery) {
-      await options.beforeQuery(tablesFileData);
+    if (options?.preQuery) {
+      await options.preQuery(tablesFileData);
     }
 
     /**

meerkat-dbm/src/dbm/index.ts

@@ -0,0 +1,3 @@
+export * from './dbm';
+export * from './instance-manager';
+

meerkat-dbm/src/dbm/instance-manager.ts

@@ -2,10 +2,12 @@ import { AsyncDuckDB } from '@duckdb/duckdb-wasm';
 
 export interface InstanceManagerType {
   /**
+   * @description
    * Get the instance of the database after initializing it
    */
   getDB: () => Promise<AsyncDuckDB>;
   /**
+   * @description
    * Terminate the database instance, primarily used for memory cleanup
    */
   terminateDB: () => Promise<void>;

meerkat-dbm/src/dbm/types.ts

@@ -0,0 +1,84 @@
+import { FileManagerType } from '../file-manager/file-manager-type';
+import { DBMEvent } from '../logger/event-types';
+import { DBMLogger } from '../logger/logger-types';
+import { TableWiseFiles } from '../types';
+import { InstanceManagerType } from './instance-manager';
+
+export interface DBMConstructorOptions {
+  /**
+   * @description
+   * It handles all file operations such as file registration, file retrieval, file deletion
+   * including mounting and unmounting of files in DuckDB instance.
+   */
+  fileManager: FileManagerType;
+
+  /**
+   * @description
+   * It manages the lifecycle of the DuckDB database instance.
+   * It provides methods for obtaining an initialized DuckDB instance and terminating the instance.
+   */
+  instanceManager: InstanceManagerType;
+
+  /**
+   * @description
+   * Represents an logger instance, which will be used for logging messages throughout the DBM's execution.
+   */
+  logger: DBMLogger;
+
+  /**
+   * @description
+   * A callback function that handles events emitted by the DBM.
+   */
+  onEvent?: (event: DBMEvent) => void;
+
+  /**
+   * @description
+   * A callback function that handles shutdown event of DuckDB.
+   */
+  onDuckDBShutdown?: () => void;
+
+  /**
+   * @description
+   * Configuration options for the DBM.
+   */
+  options?: {
+    /**
+     * @description
+     * Denotes the shutdown time for the database after inactivity, in milliseconds.
+     * If not specified, the DB will not shutdown.
+     */
+    shutdownInactiveTime?: number;
+  };
+}
+
+/**
+ * Configuration options for query execution.
+ */
+export interface QueryOptions {
+  /**
+   * @description
+   * A callback function which will be executed before the query is executed.
+   * @param tableWiseFiles - An array of tables with associated file names.
+   */
+  preQuery?: (tableWiseFiles: TableWiseFiles[]) => Promise<void>;
+
+  /**
+   * @description
+   * Additional information for the query, which will be emitted in the DBM events.
+   */
+  metadata?: object;
+}
+
+export interface QueryQueueItem {
+  query: string;
+  tableNames: string[];
+  promise: {
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+  };
+  /**
+   * Timestamp indicating when the query was added to the queue.
+   */
+  timestamp: number;
+  options?: QueryOptions;
+}