mongoplusplus 1.0.4 → 1.0.6

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,226 @@
+import * as mongoose from 'mongoose';
+
+/**
+ * Mongoplus manages multiple mongoose connections and builds distributed models.
+ *
+ * Example:
+ * ```ts
+ * import Mongoplus from 'mongoplusplus';
+ * const mp = new Mongoplus(['mongodb://a/db','readonly:mongodb://b/db']);
+ * await mp.connectToAll();
+ * ```
+ */
+declare class Mongoplus {
+    /** Array of connection URIs. Use `readonly:` prefix to mark read-only URIs. */
+    mongoURI: string[];
+    /** All mongoose connections created by `connectToAll`. */
+    allConnections: mongoose.Connection[];
+    /** Internal rotation index. */
+    currentIndex: number;
+    /** Connections created from `readonly:` URIs. */
+    static readonlydbs: mongoose.Connection[];
+    /** Models corresponding to readonly connections. */
+    static readonlymodels: any[];
+
+    /**
+     * Create manager with list of URIs.
+     * @example
+     * const mp = new Mongoplus(['mongodb://a/db','readonly:mongodb://b/db']);
+     */
+    constructor(mongoURI: string[]);
+
+    /**
+     * Create a mongoose Schema.
+     * @example
+     * const schema = mp.Schema({ name: String, dbIndex: { type: Number, required: true } });
+     */
+    Schema(schema: mongoose.SchemaDefinition | mongoose.Schema): mongoose.Schema;
+
+    /**
+     * Add an index to a schema.
+     * @example
+     * mp.addIndex(schema, { email: 1 });
+     */
+    addIndex(schema: mongoose.Schema, indextype: any): void;
+
+    /**
+     * Return next MongoDB URI in rotation.
+     */
+    getNextMongoURI(): string;
+
+    /**
+     * Establish all connections. Call before `buildModel`.
+     * @returns array of `mongoose.Connection`.
+     */
+    connectToAll(): mongoose.Connection[];
+
+    /**
+     * Build a distributed model across all connections. Schema must include `dbIndex`.
+     * @example
+     * const User = mp.buildModel('User', schema);
+     */
+    buildModel(name: string, schema: mongoose.Schema): MongoModel;
+}
+
+/**
+ * MongoModel wraps per-connection models and exposes multi-DB helpers.
+ */
+declare class MongoModel {
+    /** Per-connection mongoose Model instances. */
+    model: any[];
+    /** Read-only model references. */
+    readonlydbs: any[];
+    /** Original schema. */
+    s: mongoose.Schema;
+    /** Rotation index for `write`. */
+    static currentIndex: number;
+
+    /**
+     * Construct a MongoModel.
+     * @example
+     * const mm = new MongoModel([M1,M2], schema, [M2]);
+     */
+    constructor(model: any[], s: mongoose.Schema, readonlydbs: any[]);
+
+    /**
+     * Run `find` on every DB and return aggregated results with timing.
+     * @example
+     * const { results, totalTime } = await User.findInAllDatabase({ active: true });
+     */
+    findInAllDatabase(filter: any, chain?: any): Promise<any>;
+
+    /**
+     * Run aggregation pipeline on every DB and return aggregated results.
+     * @example
+     * await User.aggregateInAllDatabase([{ $match: { age: { $gt: 18 } } }]);
+     */
+    aggregateInAllDatabase(filter: any, chain?: any): Promise<any>;
+
+    /**
+     * Write the same document to all writable DBs. Returns saved docs array.
+     * @example
+     * await User.writeInAllDatabase({ name: 'Alice' });
+     */
+    writeInAllDatabase(data: any): Promise<any[]>;
+
+    /**
+     * Update one matching document across all DBs.
+     * @example
+     * await User.UpdateOneInAllDatabase({ active: false }, { active: true });
+     */
+    UpdateOneInAllDatabase(filter: any, update: any): Promise<any>;
+
+    /**
+     * Update by id across all DBs.
+     * @example
+     * await User.UpdateByIdInAllDatabase(id, { name: 'Bob' });
+     */
+    UpdateByIdInAllDatabase(id: any, update: any): Promise<any>;
+
+    /**
+     * Find by id in all DBs and delete.
+     * @example
+     * await User.findByIdInAllDatabaseAndDelete(id);
+     */
+    findByIdInAllDatabaseAndDelete(id: any): Promise<any>;
+
+    /**
+     * Find one in all DBs and delete.
+     * @example
+     * await User.findOneInAllDatabaseAndDelete({ email: 'x@example.com' });
+     */
+    findOneInAllDatabaseAndDelete(filter: any): Promise<any>;
+
+    /**
+     * Delete many documents matching `filter` in all databases and return aggregated results.
+     * @example
+     * await User.finManyInAllDatabaseAndDelete({ expired: true });
+     */
+    findManyInAllDatabaseAndDelete(filter: any): Promise<any>;
+
+    /**
+     * Write a single document using round-robin balancing across writable DBs.
+     * @example
+     * const saved = await User.write({ name: 'Charlie' });
+     */
+    write(data: any): Promise<any>;
+
+    /**
+     * Perform efficient bulk upserts across writable DBs.
+     * @example
+     * await User.bulkWrite([{ id: '1', name: 'A' }], { batchSize: 500 });
+     */
+    bulkWrite(data: any[], options?: { batchSize?: number; concurrentBatches?: boolean }): Promise<any[]>;
+
+    /**
+     * Find a single document on a specific DB index.
+     * @example
+     * await User.findOne(0, { email: 'x' });
+     */
+    findOne(dbIndex: number, filter: any, chain?: any): Promise<any>;
+
+    /**
+     * Find documents on a specific DB index.
+     * @example
+     * await User.find(1, { active: true }, { limit: 10 });
+     */
+    find(dbIndex: number, filter: any, chain?: any): Promise<any>;
+
+    /**
+     * Find by id on a specific DB index.
+     * @example
+     * await User.findById(0, id);
+     */
+    findById(dbIndex: number, filter: any, chain?: any): Promise<any>;
+
+    /**
+     * Find by id and update on a specific DB index.
+     * @example
+     * await User.findByIdAndUpdate(0, id, { name: 'New' });
+     */
+    findByIdAndUpdate(dbIndex: number, id: any, update: any): Promise<any>;
+
+    /**
+     * Find by id and delete on a specific DB index.
+     * @example
+     * await User.findByIdAndDelete(1, id);
+     */
+    findByIdAndDelete(dbIndex: number, id: any, update?: any): Promise<any>;
+
+    /**
+     * Find one and update on a specific DB index.
+     * @example
+     * await User.findOneAndUpdate(0, { email: 'x' }, { active: false });
+     */
+    findOneAndUpdate(dbIndex: number, filter: any, update: any): Promise<any>;
+
+    /**
+     * Run aggregation on a specific DB index.
+     * @example
+     * await User.aggregate(0, [{ $group: { _id: '$country', count: { $sum: 1 } } }]);
+     */
+    aggregate(dbIndex: number, filter: any): Promise<any>;
+
+    /**
+     * Watch change stream on a specific DB index.
+     * @example
+     * const stream = User.watch(0);
+     */
+    watch(dbIndex: number): any;
+
+    /**
+     * Return the next model and its index for round-robin writes.
+     * @example
+     * const [model, idx] = User.getNextModel();
+     */
+    getNextModel(): [any, number];
+
+    /**
+     * Internal runner to execute many queries concurrently and return results with timing.
+     */
+    runLargeComputations(computationPairs: any[]): Promise<{ results: any[]; totalTime: number }>;
+}
+
+export default Mongoplus;
+export { MongoModel };
+