@medyll/idae-db 0.13.0 → 0.25.0

package/README.md

@@ -1,5 +1,170 @@
+# Idae Database Library
 
-```json
-"description": "@medyll/idae-db is a flexible and powerful library for interacting with various databases, with a particular focus on MongoDB support. It offers robust connection management, an intuitive API, and simplified CRUD operations."
+The Idae Database Library provides a flexible and extensible way to interact with various databases such as MongoDB, MySQL, and ChromaDB. It includes features like event emitters for pre/post hooks, auto-increment fields, and more.
+
+## Installation
+
+To install the library, run:
+
+```bash
+npm install idae-db
 ```
 
+## Usage
+
+### Initialization
+
+First, initialize the database connection:
+
+#### MongoDB
+
+```typescript
+import { IdaeDb } from './lib/idaeDb.js';
+import { DbType } from './lib/@types/types.js';
+
+const mongoDb = IdaeDb.init('mongodb://localhost:27017', {
+    dbType: DbType.MONGODB,
+    dbScope: 'a_idae_db_sitebase',
+    dbScopeSeparator: '_',
+    idaeModelOptions: {
+        autoIncrementFormat: (collection: string) => `id${collection}`,
+        autoIncrementDbCollection: 'auto_increment'
+    }
+});
+```
+
+#### MySQL
+
+```typescript
+import { IdaeDb } from './lib/idaeDb.js';
+import { DbType } from './lib/@types/types.js';
+
+const mysqlDb = IdaeDb.init('mysql://user:password@localhost:3306', {
+    dbType: DbType.MYSQL,
+    dbScope: 'a_idae_db_sitebase',
+    dbScopeSeparator: '_',
+    idaeModelOptions: {
+        autoIncrementFormat: (collection: string) => `id${collection}`,
+        autoIncrementDbCollection: 'auto_increment'
+    }
+});
+```
+
+### Create a Connection
+
+Create a connection to the database:
+
+```typescript
+await mongoDb.db('app');
+await mysqlDb.db('app');
+```
+
+### Define a Model
+
+Define a model interface:
+
+```typescript
+interface User {
+    iduser: number;
+    name: string;
+    email: string;
+    age: number;
+}
+```
+
+### Register Event Listeners
+
+Register event listeners for various operations:
+
+```typescript
+const usersCollection = mongoDb.collection<User>('user');
+
+usersCollection.registerEvents<any>({
+    findById: {
+        pre: (id) => console.log(`About to find document with id: ${id}`),
+        post: (result, id) => console.log(`Found document for id ${id}:`, result),
+        error: (error) => console.error('Error in findById:', error)
+    },
+    update: {
+        pre: (id, data) => console.log(`About to update document ${id} with:`, data),
+        post: (result, id, data) => console.log(`Updated document ${id}:`, result)
+    },
+    create: {
+        pre: (data) => console.log(`About to create document with:`, data),
+        post: (data, result) => console.log(`Created document `, data, result)
+    }
+});
+```
+
+### CRUD Operations
+
+Perform CRUD operations:
+
+#### MongoDB
+
+```typescript
+// Create a new user
+const newUser = await usersCollection.create({
+    name: 'John Doe',
+    email: 'john@example.com',
+    age: 30
+});
+
+// Find a user by email
+const user = await usersCollection.findOne({ query: { email: 'john@example.com' } });
+
+// Update a user's age
+const updateResult = await usersCollection.update(user.iduser, { age: 31 });
+
+// Find users with age greater than 25
+const users = await usersCollection.find({
+    query: { age: { $gt: 25 } },
+    sortBy: 'name:asc',
+    limit: 10
+});
+
+// Delete a user by ID
+const deleteResult = await usersCollection.deleteById(5);
+```
+
+#### MySQL
+
+```typescript
+const usersCollection = mysqlDb.collection<User>('user');
+
+// Create a new user
+const newUser = await usersCollection.create({
+    name: 'John Doe',
+    email: 'john@example.com',
+    age: 30
+});
+
+// Find a user by email
+const user = await usersCollection.findOne({ query: { email: 'john@example.com' } });
+
+// Update a user's age
+const updateResult = await usersCollection.update(user.iduser, { age: 31 });
+
+// Find users with age greater than 25
+const users = await usersCollection.find({
+    query: { age: { $gt: 25 } },
+    sortBy: 'name:asc',
+    limit: 10
+});
+
+// Delete a user by ID
+const deleteResult = await usersCollection.deleteById(5);
+```
+
+### Close Connections
+
+Close all connections when done:
+
+```typescript
+await mongoDb.closeAllConnections();
+await mysqlDb.closeAllConnections();
+```
+
+## License
+
+This project is licensed under the MIT License.

package/dist/IdaeDBModel.d.ts

@@ -4,6 +4,9 @@ export interface IdaeModelOptions {
     autoIncrementFormat?: (collection: string) => string;
     autoIncrementDbCollection?: string;
 }
+/**
+ * Models are attached to a connection.
+ */
 export declare class IdaeDBModel<T extends object> {
     private connection;
     private _collectionName;
@@ -11,9 +14,19 @@ export declare class IdaeDBModel<T extends object> {
     private _autoIncrementField;
     private _autoIncrementDbCollection;
     private _fieldId;
+    /**
+     * Creates an instance of IdaeDBModel.
+     * @param connection The database connection.
+     * @param _collectionName The name of the collection.
+     * @param options Optional model options.
+     */
     constructor(connection: IdaeDbConnection, _collectionName: string, options?: Partial<IdaeModelOptions>);
     get collection(): Collection<T>;
     get collectionName(): string;
     get fieldId(): string;
+    /**
+     * Gets the next auto-increment value.
+     * @returns The next increment value.
+     */
     getNextIncrement(): Promise<any>;
 }

package/dist/IdaeDBModel.js

@@ -1,6 +1,8 @@
 import { IdaeDbConnection } from './IdaeDbConnection.js';
 import { IdaeDb } from './idaeDb.js';
-// models are attached to a connection
+/**
+ * Models are attached to a connection.
+ */
 export class IdaeDBModel {
     connection;
     _collectionName;
@@ -8,6 +10,12 @@ export class IdaeDBModel {
     _autoIncrementField = undefined;
     _autoIncrementDbCollection = undefined;
     _fieldId = '_id';
+    /**
+     * Creates an instance of IdaeDBModel.
+     * @param connection The database connection.
+     * @param _collectionName The name of the collection.
+     * @param options Optional model options.
+     */
     constructor(connection, _collectionName, options) {
         this.connection = connection;
         this._collectionName = _collectionName;
@@ -25,6 +33,10 @@ export class IdaeDBModel {
     get fieldId() {
         return this._fieldId;
     }
+    /**
+     * Gets the next auto-increment value.
+     * @returns The next increment value.
+     */
     async getNextIncrement() {
         const idaeAuto = IdaeDb.init(this.connection.idaeDb.uri, this.connection.idaeDb.options);
         const increment_name = 'increment';

package/dist/IdaeDbAdapter.d.ts

@@ -8,6 +8,9 @@ export type EventListeners<T extends object> = {
         error?: ErrorEventListener;
     };
 };
+/**
+ * IdaeDbAdapter class that extends IdaeEventEmitter and implements AbstractIdaeDbAdapter.
+ */
 export declare class IdaeDbAdapter<T extends object> extends IdaeEventEmitter implements AbstractIdaeDbAdapter<T> {
     private dbType;
     private adapter;
@@ -49,5 +52,12 @@ export declare class IdaeDbAdapter<T extends object> extends IdaeEventEmitter im
         deletedCount?: number;
     }>;
     transaction<TResult>(callback: (session: unknown) => Promise<TResult>): Promise<TResult>;
+    /**
+     * Applies the appropriate adapter for the specified database type.
+     * @param collection The name of the collection or table.
+     * @param connection The database connection object.
+     * @param dbType The type of database being used.
+     * @throws {Error} If no adapter is found for the specified database type.
+     */
     private applyAdapter;
 }

package/dist/IdaeDbAdapter.js

@@ -15,6 +15,9 @@ import { MongoDBAdapter } from './adapters/MongoDBAdapter.js';
 import { MySQLAdapter } from './adapters/MySQLAdapter.js';
 import { ChromaDBAdapter } from './adapters/ChromaDBAdapter.js';
 import { IdaeEventEmitter, withEmitter } from './IdaeEventEmitter.js';
+/**
+ * IdaeDbAdapter class that extends IdaeEventEmitter and implements AbstractIdaeDbAdapter.
+ */
 export class IdaeDbAdapter extends IdaeEventEmitter {
     dbType;
     adapter;
@@ -99,6 +102,13 @@ export class IdaeDbAdapter extends IdaeEventEmitter {
     async transaction(callback) {
         return this.adapter.transaction(callback);
     }
+    /**
+     * Applies the appropriate adapter for the specified database type.
+     * @param collection The name of the collection or table.
+     * @param connection The database connection object.
+     * @param dbType The type of database being used.
+     * @throws {Error} If no adapter is found for the specified database type.
+     */
     applyAdapter(collection, connection, dbType) {
         const adapterConstructor = IdaeDbAdapter.adapters.get(dbType);
         if (!adapterConstructor) {

package/dist/IdaeDbConnection.d.ts

@@ -1,17 +1,52 @@
 import { IdaeDBModel } from './IdaeDBModel.js';
 import { IdaeDb } from './idaeDb.js';
+/**
+ * Represents a database connection.
+ */
 export declare class IdaeDbConnection {
     #private;
     private _idaeDb;
     private _dbName;
+    /**
+     * Creates an instance of IdaeDbConnection.
+     * @param _idaeDb The IdaeDb instance.
+     * @param _dbName The name of the database.
+     */
     constructor(_idaeDb: IdaeDb, _dbName: string);
+    /**
+     * Connects to the database.
+     * @returns A promise that resolves to the IdaeDbConnection instance.
+     */
     connect(): Promise<IdaeDbConnection>;
+    /**
+     * Gets the database instance.
+     * @returns The database instance.
+     * @throws Error if the database is not connected.
+     */
     getDb(): any;
+    /**
+     * Gets the model for a collection.
+     * @param collectionName The name of the collection.
+     * @returns The model for the collection.
+     */
     getModel: <T extends Document>(collectionName: string) => IdaeDBModel<T>;
+    /**
+     * Gets the client instance.
+     * @returns The client instance.
+     * @throws Error if the client is not initialized.
+     */
     getClient<T>(): T;
+    /**
+     * Closes the database connection.
+     * @returns A promise that resolves when the connection is closed.
+     */
     close(): Promise<void>;
     get dbName(): string;
     get connected(): boolean;
     get idaeDb(): IdaeDb;
+    /**
+     * Gets the full database name with scope.
+     * @returns The full database name.
+     */
     private getFullDbName;
 }

package/dist/IdaeDbConnection.js

@@ -2,6 +2,9 @@
 import { DbType } from './@types/types.js';
 import { IdaeDBModel } from './IdaeDBModel.js';
 import { IdaeDb } from './idaeDb.js';
+/**
+ * Represents a database connection.
+ */
 export class IdaeDbConnection {
     _idaeDb;
     _dbName;
@@ -12,6 +15,11 @@ export class IdaeDbConnection {
     #client;
     #adapterClass;
     #connected = false;
+    /**
+     * Creates an instance of IdaeDbConnection.
+     * @param _idaeDb The IdaeDb instance.
+     * @param _dbName The name of the database.
+     */
     constructor(_idaeDb, _dbName) {
         this._idaeDb = _idaeDb;
         this._dbName = _dbName;
@@ -21,6 +29,10 @@ export class IdaeDbConnection {
         // add prefix if requested
         this._dbName = this.getFullDbName();
     }
+    /**
+     * Connects to the database.
+     * @returns A promise that resolves to the IdaeDbConnection instance.
+     */
     async connect() {
         if (!this.#adapterClass?.connect)
             throw new Error('Adapter does not have a connect method');
@@ -36,12 +48,22 @@ export class IdaeDbConnection {
             throw error;
         }
     }
+    /**
+     * Gets the database instance.
+     * @returns The database instance.
+     * @throws Error if the database is not connected.
+     */
     getDb() {
         if (!this.#Db) {
             throw new Error('Db not connected. Call connect() first.');
         }
         return this.#Db;
     }
+    /**
+     * Gets the model for a collection.
+     * @param collectionName The name of the collection.
+     * @returns The model for the collection.
+     */
     getModel = (collectionName) => {
         if (!this.#models.has(collectionName)) {
             const model = new IdaeDBModel(this, collectionName, this._idaeDb?.options?.idaeModelOptions);
@@ -49,12 +71,21 @@ export class IdaeDbConnection {
         }
         return this.#models.get(collectionName);
     };
+    /**
+     * Gets the client instance.
+     * @returns The client instance.
+     * @throws Error if the client is not initialized.
+     */
     getClient() {
         if (!this.#client) {
             throw new Error('Client not initialized. Call connect() first.');
         }
         return this.#client;
     }
+    /**
+     * Closes the database connection.
+     * @returns A promise that resolves when the connection is closed.
+     */
     async close() {
         if (!this.#adapterClass?.close)
             throw new Error('Adapter does not have a close method');
@@ -69,5 +100,9 @@ export class IdaeDbConnection {
     get idaeDb() {
         return this._idaeDb;
     }
+    /**
+     * Gets the full database name with scope.
+     * @returns The full database name.
+     */
     getFullDbName = () => [this.idaeDb.options.dbScope, this._dbName].join('_');
 }

package/dist/IdaeEventEmitter.d.ts

@@ -24,7 +24,6 @@ export type PreEventListener<T extends unknown[]> = (...args: T) => void | Promi
  * Type for post-execution event listeners.
  */
 export type PostEventListener<T extends unknown[], R> = (result: R, ...args: T) => void | Promise<void>;
-export type EventListeners<T, R> = PreEventListener<T> & PostEventListener<T, R> & ErrorEventListener;
 /**
  * Type for error event listeners.
  */

package/dist/idaeDb.d.ts

@@ -13,9 +13,17 @@ export type IdaeDbOptions = {
     idaeModelOptions?: IdaeModelOptions;
     dbEvents?: EventListeners<object, object>;
 };
+/**
+ * Represents the IdaeDb class.
+ */
 export declare class IdaeDb {
     #private;
     private _uri;
+    /**
+     * Creates an instance of IdaeDb.
+     * @param _uri The URI of the database.
+     * @param options The options for the database.
+     */
     private constructor();
     /**
      * Initializes or retrieves an IdaeDb instance.
@@ -47,11 +55,35 @@ export declare class IdaeDb {
      * @throws Error if the connection is not found or the database type is unsupported.
      */
     collection<T extends Document>(collectionName: string): IdaeDbAdapter<T>;
+    /**
+     * Closes the current database connection.
+     * @returns A Promise that resolves when the connection is closed.
+     */
     closeConnection(): Promise<void>;
+    /**
+     * Closes all database connections.
+     * @returns A Promise that resolves when all connections are closed.
+     */
     closeAllConnections(): Promise<void>;
+    /**
+     * Gets the adapter class for the current database type.
+     * @returns The adapter class.
+     */
     get adapterClass(): import("./@types/types.js").AdapterConstructor<IdaeDbConnection> | undefined;
+    /**
+     * Gets the connection key for the current database instance.
+     * @returns The connection key.
+     */
     get connectionKey(): IdaeDbInstanceKey;
+    /**
+     * Gets the URI of the database.
+     * @returns The URI of the database.
+     */
     get uri(): string;
+    /**
+     * Gets the options for the database.
+     * @returns The options for the database.
+     */
     get options(): IdaeDbOptions;
 }
 export {};

package/dist/idaeDb.js

@@ -2,6 +2,9 @@
 import { DbType } from './@types/types.js';
 import { IdaeDbConnection } from './IdaeDbConnection.js';
 import { IdaeDbAdapter } from './IdaeDbAdapter.js';
+/**
+ * Represents the IdaeDb class.
+ */
 export class IdaeDb {
     _uri;
     #globalEvents;
@@ -15,6 +18,11 @@ export class IdaeDb {
         idaeModelOptions: {},
         dbEvents: {}
     };
+    /**
+     * Creates an instance of IdaeDb.
+     * @param _uri The URI of the database.
+     * @param options The options for the database.
+     */
     constructor(_uri, options = {}) {
         this._uri = _uri;
         this.#options = { ...this.#options, ...options };
@@ -79,6 +87,11 @@ export class IdaeDb {
         }
         return adapter;
     }
+    /**
+     * Applies event listeners to the adapter.
+     * @param adapter The adapter to apply events to.
+     * @param events The event listeners to apply.
+     */
     #applyEvents(adapter, events) {
         for (const [method, listeners] of Object.entries(events)) {
             if (listeners.pre) {
@@ -92,27 +105,51 @@ export class IdaeDb {
             }
         }
     }
+    /**
+     * Closes the current database connection.
+     * @returns A Promise that resolves when the connection is closed.
+     */
     async closeConnection() {
         if (this.#connection) {
             await this.#connection.close();
             this.#connections.delete(this.connectionKey);
         }
     }
+    /**
+     * Closes all database connections.
+     * @returns A Promise that resolves when all connections are closed.
+     */
     async closeAllConnections() {
         for (const [connectionName, connection] of this.#connections) {
             await connection.close();
         }
         this.#connections.clear();
     }
+    /**
+     * Gets the adapter class for the current database type.
+     * @returns The adapter class.
+     */
     get adapterClass() {
         return this.#adapterClass;
     }
+    /**
+     * Gets the connection key for the current database instance.
+     * @returns The connection key.
+     */
     get connectionKey() {
         return `${this.options.dbType}:${this._uri}`;
     }
+    /**
+     * Gets the URI of the database.
+     * @returns The URI of the database.
+     */
     get uri() {
         return this._uri;
     }
+    /**
+     * Gets the options for the database.
+     * @returns The options for the database.
+     */
     get options() {
         return this.#options;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medyll/idae-db",
-  "version": "0.13.0",
+  "version": "0.25.0",
   "description": "@medyll/idae-db is a flexible and powerful library for interacting with various databases, with a particular focus on MongoDB support. It offers robust connection management, an intuitive API, and simplified CRUD operations.",
   "scripts": {
     "dev": "vite dev",
@@ -45,7 +45,7 @@
     "publint": "^0.2.10",
     "svelte": "^5.0.0-next.225",
     "svelte-check": "^3.8.5",
-    "typescript": "^5.5.4",
+    "typescript": "^5.8.2",
     "typescript-eslint": "^8.1.0",
     "vite": "^5.4.1",
     "vitest": "^2.0.5"
@@ -57,4 +57,4 @@
   "dependencies": {
     "chromadb": "^1.8.1"
   }
-}
+}