mongoplusplus 1.0.4 → 1.0.5

package/README.md

@@ -1,170 +1,188 @@
-# mongoplusplus
-
-## Overview
-
-`mongoplusplus` is a Node.js package designed to facilitate load balancing of read and write operations across multiple MongoDB databases. It simplifies database connection management, schema definition, model building, and CRUD operations execution.
-
-## Installation
-
-Install mongoplusplus via npm:
-
-```bash
-npm install mongoplusplus
-```
-
-importing
-```node
-const mongoplusplus = require('mongoplusplus');
-```
-##Initialing
-```node
-const dbname = 'testforUP';
-
-const mongoURI1 = `mongodb+srv://xxxxx:xxxxxx@cluster0.xxxxx.mongodb.net/${dbname}?retryWrites=true&w=majority`;
-const mongoURI2 = `readonly:mongodb+srv://xxxxxxx:xxxxxx@cluster0.xxxxxx.mongodb.net/${dbname}?retryWrites=true&w=majority`;
-const mongodb = new mongoplusplus([mongoURI1, mongoURI2]);
-
-```
-##connecting database
-this is the top level thing in your main page (in this test code, under mongodb variable declaration  )
-```node
-(async () => {
-  await mongodb.connectToAll();
-})();
-```
-##Schema defining 
-it is very  similar to Mongoose schema definition.but only one mandatory field must be there in the schema which will act as a db identifier for that document
-```node
-const likeSH = mongodb.Schema({
-  user_id: { type: mongoose.Schema.Types.ObjectId, required: true, ref: "users" },
-  postId: { type: mongoose.Schema.Types.ObjectId, required: true  },
-  dbIndex: { type: Number, required: true },
-
-  like_time: { type: Date, default: Date.now }
-}
-)
-```
-### model building
-```node
-const likes = mongodb.buildModel("likes", likeSH)
-```
-
-
-##### Note that `dbIndex` is used to indicate which MongoDB server it belongs to.
-###### it is a must otherwise it will throw an error.
-```node
-     throw new Error(`[!]Error :  < dbIndex > must be present in your schema like dbIndex:{
-            type: Number,
-            required: true
-          } `)
-```
-
-
-### usage methods
-```node 
-findInAllDatabase(filter, chain = {})
-```
-Usage: Finds documents matching the filter in all MongoDB databases.
-
-```node 
-const result = await likes.findInAllDatabase({ name: 'John' }, { limit: 10, skip: 0 });
-Returns: An array of documents matching the filter from all databases.
-```
-```node
-writeInAllDatabase(data)
-
-Usage: Writes data to all MongoDB databases.
-
-const result = await likes.writeInAllDatabase({ name: 'John', age: 30 });
-Returns: An array of written documents from all databases.
-```
-```node
-UpdateOneInAllDatabase(filter, update)
-Usage: Updates a single document matching the filter in all MongoDB databases.
-const updatedDocument = await likes.UpdateOneInAllDatabase({ name: 'John' }, { age: 35 });
-Returns: The updated document.
-```
-```node 
-UpdateByIdInAllDatabase(id, update)
-Usage: Updates a document by ID in all MongoDB databases.
-const updatedDocument = await likes.UpdateByIdInAllDatabase('123456', { age: 35 });
-Returns: The updated document.
-```
-```node 
-findByIdInAllDatabaseAndDelete(id)
-Usage: Finds a document by ID in all MongoDB databases and deletes it.
-const deletedDocument = await likes.findByIdInAllDatabaseAndDelete('123456');
-Returns: The deleted document.
-```
-
-```node 
-findOneInAllDatabaseAndDelete(filter)
-Usage: Finds a single document matching the filter in all MongoDB databases and deletes it.
-const deletedDocument = await likes.findOneInAllDatabaseAndDelete({ name: 'John' });
-Returns: The deleted document.
-```
-```node 
-write(data)
-Usage: Writes data to a MongoDB database.
-const result = await likes.write({ name: 'John', age: 30 });
-Returns: The written document.
-```
-
-```node 
-findOne(dbIndex, filter, chain = {})
-Usage: Finds a single document matching the filter in a specific MongoDB database.
-const document = await likes.findOne(0, { name: 'John' }, { limit: 1 });
-Returns: The found document.
-```
-```node
-find(dbIndex, filter, chain = {})
-Usage: Finds documents matching the filter in a specific MongoDB database.
-const documents = await likes.find(0, { age: { $gt: 18 } }, { limit: 10 });
-Returns: An array of found documents.
-```
-
-```node 
-findById(dbIndex, id, chain = {})
-Usage: Finds a document by ID in a specific MongoDB database.
-const document = await likes.findById(0, '123456');
-Returns: The found document.
-```
-```node
-findByIdAndUpdate(dbIndex, id, update)
-Usage: Finds a document by ID in a specific MongoDB database and updates it.
-const updatedDocument = await likes.findByIdAndUpdate(0, '123456', { age: 35 });
-Returns: The updated document.
-```
-```node
-findByIdAndDelete(dbIndex, id)
-Usage: Finds a document by ID in a specific MongoDB database and deletes it.
-const deletedDocument = await likes.findByIdAndDelete(0, '123456');
-Returns: The deleted document.
-```
-```node
-findOneAndUpdate(dbIndex, filter, update)
-Usage: Finds a single document matching the filter in a specific MongoDB database and updates it.
-
-const updatedDocument = await likes.findOneAndUpdate(0, { name: 'John' }, { age: 35 });
-Returns: The updated document.
-```
-```node
-aggregate(dbIndex, filter)
-Usage: Aggregates documents in a specific MongoDB database based on the filter.
-const aggregationResult = await likes.aggregate(0, [{ $group: { _id: '$name', total: { $sum: '$age' } } }]);
-Returns: The aggregation result.
-```
-```node
-watch(dbIndex)
-Usage: Starts watching for changes in a specific MongoDB database.
-const watcher = await likes.watch(0);
-Returns: A watcher object for the database.
-```
-
-> now most of the functionality is as same as mongoose  so you can use them directly like indexing a schema 
-```node
-likeSH.index({ user_id: 1, postId: 1 }, { unique: true });
-```
-# Contributing
-there are many things that are not ported. feel free to contribute!
+# mongoplusplus
+
+## Overview
+
+`mongoplusplus` is a Node.js package designed to facilitate load balancing of read and write operations across multiple MongoDB databases. It simplifies database connection management, schema definition, model building, and CRUD operations execution.
+
+## Installation
+
+Install mongoplusplus via npm:
+
+```bash
+npm install mongoplusplus
+```
+
+importing
+```node
+const mongoplusplus = require('mongoplusplus');
+```
+##Initialing
+```node
+const dbname = 'testforUP';
+
+const mongoURI1 = `mongodb+srv://xxxxx:xxxxxx@cluster0.xxxxx.mongodb.net/${dbname}?retryWrites=true&w=majority`;
+const mongoURI2 = `readonly:mongodb+srv://xxxxxxx:xxxxxx@cluster0.xxxxxx.mongodb.net/${dbname}?retryWrites=true&w=majority`;
+const mongodb = new mongoplusplus([mongoURI1, mongoURI2]);
+
+```
+##connecting database
+this is the top level thing in your main page (in this test code, under mongodb variable declaration  )
+```node
+(async () => {
+  await mongodb.connectToAll();
+})();
+```
+##Schema defining 
+it is very  similar to Mongoose schema definition.but only one mandatory field must be there in the schema which will act as a db identifier for that document
+```node
+const likeSH = mongodb.Schema({
+  user_id: { type: mongoose.Schema.Types.ObjectId, required: true, ref: "users" },
+  postId: { type: mongoose.Schema.Types.ObjectId, required: true  },
+  dbIndex: { type: Number, required: true },
+
+  like_time: { type: Date, default: Date.now }
+}
+)
+```
+### model building
+```node
+const likes = mongodb.buildModel("likes", likeSH)
+```
+
+
+##### Note that `dbIndex` is used to indicate which MongoDB server it belongs to.
+###### it is a must otherwise it will throw an error.
+```node
+     throw new Error(`[!]Error :  < dbIndex > must be present in your schema like dbIndex:{
+            type: Number,
+            required: true
+          } `)
+```
+
+
+### usage methods
+```node 
+findInAllDatabase(filter, chain = {})
+```
+Usage: Finds documents matching the filter in all MongoDB databases.
+
+```node 
+const result = await likes.findInAllDatabase({ name: 'John' }, { limit: 10, skip: 0 });
+Returns: An array of documents matching the filter from all databases.
+```
+```node
+writeInAllDatabase(data)
+
+Usage: Writes data to all MongoDB databases.
+
+const result = await likes.writeInAllDatabase({ name: 'John', age: 30 });
+Returns: An array of written documents from all databases.
+```
+```node
+UpdateOneInAllDatabase(filter, update)
+Usage: Updates a single document matching the filter in all MongoDB databases.
+const updatedDocument = await likes.UpdateOneInAllDatabase({ name: 'John' }, { age: 35 });
+Returns: The updated document.
+```
+```node 
+UpdateByIdInAllDatabase(id, update)
+Usage: Updates a document by ID in all MongoDB databases.
+const updatedDocument = await likes.UpdateByIdInAllDatabase('123456', { age: 35 });
+Returns: The updated document.
+```
+```node 
+findByIdInAllDatabaseAndDelete(id)
+Usage: Finds a document by ID in all MongoDB databases and deletes it.
+const deletedDocument = await likes.findByIdInAllDatabaseAndDelete('123456');
+Returns: The deleted document.
+```
+
+```node 
+findOneInAllDatabaseAndDelete(filter)
+Usage: Finds a single document matching the filter in all MongoDB databases and deletes it.
+const deletedDocument = await likes.findOneInAllDatabaseAndDelete({ name: 'John' });
+Returns: The deleted document.
+```
+```node 
+write(data)
+Usage: Writes data to a MongoDB database.
+const result = await likes.write({ name: 'John', age: 30 });
+Returns: The written document.
+```
+
+```node 
+bulkWrite(data)
+Usage: Bulk writes data to a MongoDB database with transaction inbuilt.
+
+ const testData = Array.from({ length: 10000 }, (_, i) => ({
+        name: `User ${i}`,
+        email: `user${i}@example.com`,
+        age: 20 + (i % 50)
+    }));
+
+    // Test 1: Large batch, concurrent
+    console.time('Large batch concurrent');
+    await UserModel.bulkWrite(testData, {
+        batchSize: 5000,
+        concurrentBatches: true
+    });
+```
+
+```node 
+findOne(dbIndex, filter, chain = {})
+Usage: Finds a single document matching the filter in a specific MongoDB database.
+const document = await likes.findOne(0, { name: 'John' }, { limit: 1 });
+Returns: The found document.
+```
+```node
+find(dbIndex, filter, chain = {})
+Usage: Finds documents matching the filter in a specific MongoDB database.
+const documents = await likes.find(0, { age: { $gt: 18 } }, { limit: 10 });
+Returns: An array of found documents.
+```
+
+```node 
+findById(dbIndex, id, chain = {})
+Usage: Finds a document by ID in a specific MongoDB database.
+const document = await likes.findById(0, '123456');
+Returns: The found document.
+```
+```node
+findByIdAndUpdate(dbIndex, id, update)
+Usage: Finds a document by ID in a specific MongoDB database and updates it.
+const updatedDocument = await likes.findByIdAndUpdate(0, '123456', { age: 35 });
+Returns: The updated document.
+```
+```node
+findByIdAndDelete(dbIndex, id)
+Usage: Finds a document by ID in a specific MongoDB database and deletes it.
+const deletedDocument = await likes.findByIdAndDelete(0, '123456');
+Returns: The deleted document.
+```
+```node
+findOneAndUpdate(dbIndex, filter, update)
+Usage: Finds a single document matching the filter in a specific MongoDB database and updates it.
+
+const updatedDocument = await likes.findOneAndUpdate(0, { name: 'John' }, { age: 35 });
+Returns: The updated document.
+```
+```node
+aggregate(dbIndex, filter)
+Usage: Aggregates documents in a specific MongoDB database based on the filter.
+const aggregationResult = await likes.aggregate(0, [{ $group: { _id: '$name', total: { $sum: '$age' } } }]);
+Returns: The aggregation result.
+```
+```node
+watch(dbIndex)
+Usage: Starts watching for changes in a specific MongoDB database.
+const watcher = await likes.watch(0);
+Returns: A watcher object for the database.
+```
+
+> now most of the functionality is as same as mongoose  so you can use them directly like indexing a schema 
+```node
+likeSH.index({ user_id: 1, postId: 1 }, { unique: true });
+```
+# Contributing
+there are many things that are not ported. feel free to contribute!
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update.and also 

package/index.d.ts

@@ -0,0 +1,144 @@
+import mongoose = require('mongoose');
+
+/**
+ * Mongoplus manages multiple mongoose connections and builds distributed models.
+ *
+ * Usage example:
+ * ```js
+ * const Mongoplus = require('mongoplus');
+ * const mp = new Mongoplus(['mongodb://host1/db', 'readonly:mongodb://host2/db']);
+ * await mp.connectToAll();
+ * const User = mp.buildModel('User', new mp.Schema({ name: String, dbIndex: { type: Number, required: true } }));
+ * await User.write({ name: 'Alice' });
+ * ```
+ */
+declare class Mongoplus {
+    /** Array of connection URIs. Prefix a URI with `readonly:` to mark it read-only. */
+    mongoURI: string[];
+    /** All mongoose connections created by `connectToAll`. */
+    allConnections: mongoose.Connection[];
+    /** Internal rotation index used by `getNextMongoURI`. */
+    currentIndex: number;
+    /** Connections that were created from `readonly:` URIs. */
+    static readonlydbs: mongoose.Connection[];
+    /** Models corresponding to readonly connections. */
+    static readonlymodels: any[];
+
+    /**
+     * Create a Mongoplus manager.
+     * @param mongoURI - Array of MongoDB URIs. Use `readonly:` prefix for read-only replicas.
+     */
+    constructor(mongoURI: string[]);
+
+    /** Create a mongoose Schema from a plain definition. */
+    Schema(schema: mongoose.SchemaDefinition | mongoose.Schema): mongoose.Schema;
+
+    /** Add an index to a schema. Delegates to `schema.index(...)`. */
+    addIndex(schema: mongoose.Schema, indextype: any): any;
+
+    /** Return next MongoDB URI in rotation (without `readonly:` prefix). */
+    getNextMongoURI(): string;
+
+    /**
+     * Establish all connections from `mongoURI`. Returns an array of mongoose.Connection.
+     * Call this before `buildModel`.
+     */
+    connectToAll(): mongoose.Connection[];
+
+    /**
+     * Build a distributed model across all connections.
+     * The provided `schema` must include a required numeric `dbIndex` field.
+     */
+    buildModel(name: string, schema: mongoose.Schema): MongoModel;
+}
+
+/**
+ * MongoModel represents the model instances distributed across multiple databases.
+ * Methods with `InAllDatabase` perform the operation on every connection and return aggregated results.
+ */
+declare class MongoModel {
+    /** Array of mongoose models (one per connection). */
+    model: any[];
+    /** Read-only model references. */
+    readonlydbs: any[];
+    /** Original schema used to create the models. */
+    s: mongoose.Schema;
+    /** Rotation index for `write` balancing. */
+    static currentIndex: number;
+
+    /**
+     * @param model - array of mongoose Model instances (one per connection)
+     * @param s - mongoose Schema used to create models
+     * @param readonlydbs - list of models that are read-only
+     */
+    constructor(model: any[], s: mongoose.Schema, readonlydbs: any[]);
+
+    /** Find matching documents in all databases.
+     * @param filter - mongoose filter
+     * @param chain - optional chaining options (skip, limit, sort)
+     */
+    findInAllDatabase(filter: any, chain?: any): Promise<any>;
+
+    /** Run aggregation pipeline on all databases. */
+    aggregateInAllDatabase(filter: any, chain?: any): Promise<any>;
+
+    /** Write the same document to all writable databases. Returns an array of saved docs. */
+    writeInAllDatabase(data: any): Promise<any[]>;
+
+    /** Update one matching document across all databases. */
+    UpdateOneInAllDatabase(filter: any, update: any): Promise<any>;
+
+    /** Update by id across all databases. */
+    UpdateByIdInAllDatabase(id: any, update: any): Promise<any>;
+
+    /** Find by id in all DBs and delete. */
+    findByIdInAllDatabaseAndDelete(id: any): Promise<any>;
+
+    /** Find one in all DBs and delete. */
+    findOneInAllDatabaseAndDelete(filter: any): Promise<any>;
+
+    /** Write a single document using round-robin balancing across writable DBs. */
+    write(data: any): Promise<any>;
+
+    /**
+     * Perform efficient bulk upserts across writable DBs.
+     * @param data - array of objects to upsert
+     * @param options - optional settings: `batchSize` and `concurrentBatches`
+     */
+    bulkWrite(data: any[], options?: { batchSize?: number; concurrentBatches?: boolean }): Promise<any[]>;
+
+    /** Find a single document on a specific DB index. */
+    findOne(dbIndex: number, filter: any, chain?: any): Promise<any>;
+
+    /** Find documents on a specific DB index. */
+    find(dbIndex: number, filter: any, chain?: any): Promise<any>;
+
+    /** Find by id on a specific DB index. */
+    findById(dbIndex: number, filter: any, chain?: any): Promise<any>;
+
+    /** Find by id and update on a specific DB index. */
+    findByIdAndUpdate(dbIndex: number, id: any, update: any): Promise<any>;
+
+    /** Find by id and delete on a specific DB index. */
+    findByIdAndDelete(dbIndex: number, id: any, update?: any): Promise<any>;
+
+    /** Find one and update on a specific DB index. */
+    findOneAndUpdate(dbIndex: number, filter: any, update: any): Promise<any>;
+
+    /** Run aggregation on a specific DB index. */
+    aggregate(dbIndex: number, filter: any): Promise<any>;
+
+    /** Watch change stream on a specific DB index. */
+    watch(dbIndex: number): any;
+
+    /** Return the next model and its index for round-robin writes. */
+    getNextModel(): [any, number];
+
+    /** Internal runner to execute many queries concurrently and return results with timing. */
+    runLargeComputations(computationPairs: any[]): Promise<{ results: any[]; totalTime: number }>;
+}
+
+declare namespace Mongoplus { }
+
+export = Mongoplus;
+