mongodb-ops 0.11.0 → 0.11.2

package/package.json

@@ -1,28 +1,32 @@
-{
-  "name": "mongodb-ops",
-  "version": "0.11.0",
-  "description": "Read and write ops for MongoDB",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "dependencies": {
-    "mongodb": "^6.8.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/CompAndSave/mongodb-ops.git"
-  },
-  "keywords": [
-    "mongodb"
-  ],
-  "author": "Andrew Y",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/CompAndSave/mongodb-ops/issues"
-  },
-  "homepage": "https://github.com/CompAndSave/mongodb-ops#readme",
-  "directories": {
-    "lib": "lib"
-  }
-}
+{
+  "name": "mongodb-ops",
+  "version": "0.11.2",
+  "description": "Read and write ops for MongoDB",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test",
+    "lint": "node --check index.js && node --check lib/mongodb-ops.js && node --check test/mongodb-ops.test.js && node --check test/mongodb-write-errors.test.js"
+  },
+  "dependencies": {
+    "mongodb": "^6.8.0"
+  },
+  "devDependencies": {
+    "mongodb-memory-server": "^11.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CompAndSave/mongodb-ops.git"
+  },
+  "keywords": [
+    "mongodb"
+  ],
+  "author": "Andrew Y",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/CompAndSave/mongodb-ops/issues"
+  },
+  "homepage": "https://github.com/CompAndSave/mongodb-ops#readme",
+  "directories": {
+    "lib": "lib"
+  }
+}

package/readme.md

@@ -1,65 +1,130 @@
-# Read and write ops for MongoDB
-**DB client is at static level - It will keep alive and can be reused**
-
-**Updated - MongoDBToolSet class is added**
-```
-const { MongoDBToolSet } = require('mongodb-ops');
-```
-
-**Sample code to use the class**
-
-```
-const { MongoDBOps } = require('mongodb-ops');
-const connString = "mongodb+srv://YOUR_DB_USERNAME:YOUR_DB_PASSWORD@YOUR_MONGO_ATLAS_URL/YOUR_DBNAME?retryWrites=true&w=majority";
-
-class MongoDBToolSet extends MongoDBOps {
-  constructor(collectionName) {
-    super(connString);
-    this.collectionName = collectionName;
-  }
-
-  static async getDataByID(collectionName, id, projection) {
-    let queryFilter = { _id:id };
-    return Promise.resolve(await MongoDBOps.getData(collectionName, queryFilter, false, projection, undefined, undefined, undefined, connString));
-  }
-
-  async getDataByID(id, projection) { return Promise.resolve(await MongoDBToolSet.getDataByID(this.collectionName, id, projection)); }
-
-  static async getAllData(collectionName, projection, sort, pagination) {
-    let queryFilter = {};
-    return Promise.resolve(await MongoDBOps.getData(collectionName, queryFilter, false, projection, sort, pagination, false, connString));
-  }
-
-  async getAllData(site, projection, sort, pagination) { return Promise.resolve(await MongoDBToolSet.getAllData(this.collectionName, projection, sort, pagination)); }
-
-  static async insertOne(collectionName, doc) { return Promise.resolve(await MongoDBOps.writeData("insertOne", collectionName, doc, undefined, connString)); }
-  async insertOne(doc) { return Promise.resolve(await super.writeData("insertOne", this.collectionName, doc)); }
-  static async insertBulkOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("insertBulk", collectionName, docs, true, connString)); }
-  async insertBulkOrdered(docs) { return Promise.resolve(await super.writeBulkData("insertBulk", this.collectionName, docs, true)); }
-  static async insertBulkUnOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("insertBulk", collectionName, docs, false, connString)); }
-  async insertBulkUnOrdered(docs) { return Promise.resolve(await super.writeBulkData("insertBulk", this.collectionName, docs, false)); }
-
-  static async replaceOne(collectionName, doc, filter) { return Promise.resolve(await MongoDBOps.writeData("replaceOne", collectionName, doc, filter, connString)); }
-  async replaceOne(doc, filter) { return Promise.resolve(await super.writeData("replaceOne", this.collectionName, doc, filter)); }
-  static async replaceBulkOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("replaceBulk", collectionName, docs, true, connString)); }
-  async replaceBulkOrdered(docs) { return Promise.resolve(await super.writeBulkData("replaceBulk", this.collectionName, docs, true)); }
-  static async replaceBulkUnOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("replaceBulk", collectionName, docs, false, connString)); }
-  async replaceBulkUnOrdered(docs) { return Promise.resolve(await super.writeBulkData("replaceBulk", this.collectionName, docs, false)); }
-
-  static async updateOne(collectionName, doc, filter) { return Promise.resolve(await MongoDBOps.writeData("updateOne", collectionName, doc, filter, connString)); }
-  async updateOne(doc, filter) { return Promise.resolve(await super.writeData("updateOne", this.collectionName, doc, filter)); }
-  static async updateMany(collectionName, doc, filter) { return Promise.resolve(await MongoDBOps.writeData("updateMany", collectionName, doc, filter, connString)); }
-  async updateMany(doc, filter) { return Promise.resolve(await super.writeData("updateMany", this.collectionName, doc, filter)); }
-  static async updateBulkOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("updateBulk", collectionName, docs, true, connString)); }
-  async updateBulkOrdered(docs) { return Promise.resolve(await super.writeBulkData("updateBulk", this.collectionName, docs, true)); }
-  static async updateBulkUnOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("updateBulk", collectionName, docs, false, connString)); }
-  async updateBulkUnOrdered(docs) { return Promise.resolve(await super.writeBulkData("updateBulk", this.collectionName, docs, false)); }
-
-  static async allBulkOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("allBulk", collectionName, docs, true, connString)); }
-  async allBulkOrdered(docs) { return Promise.resolve(await super.writeBulkData("allBulk", this.collectionName, docs, true)); }
-  static async allBulkUnOrdered(collectionName, docs) { return Promise.resolve(await MongoDBOps.writeBulkData("allBulk", collectionName, docs, false, connString)); }
-  async allBulkUnOrdered(docs) { return Promise.resolve(await super.writeBulkData("allBulk", this.collectionName, docs, false)); }
-}
-
-module.exports = MongoDB;
-```
+# mongodb-ops
+
+Lightweight read/write helpers for MongoDB with a **shared, self-managing client**. The MongoDB client is cached at the class (process) level per connection string and reused across calls — you connect once and let the driver handle pooling, topology monitoring, and failover recovery.
+
+> `writeConcern` is not configurable through this library.
+
+## Install
+
+```bash
+npm install mongodb-ops
+```
+
+Requires Node.js 16+ and bundles the official `mongodb` driver (v6).
+
+## Exports
+
+```js
+const { MongoDBOps, MongoDBToolSet } = require('mongodb-ops');
+```
+
+- **`MongoDBOps`** — low-level static/instance operations (`getData`, `search`, `writeData`, `writeBulkData`, `getCollectionCount`, `getDbClient`, `closeDBConn`, `getObjectId`).
+- **`MongoDBToolSet`** — a higher-level, collection-scoped convenience class that extends `MongoDBOps` (get / insert / update / replace / delete + bulk variants).
+
+## Quick start
+
+### Collection-scoped (`MongoDBToolSet`)
+
+```js
+const { MongoDBToolSet } = require('mongodb-ops');
+
+const connString = "mongodb+srv://USER:PASS@your-cluster.mongodb.net/your-db?retryWrites=true&w=majority";
+
+// Instance style — bind a collection + connection once
+const orders = new MongoDBToolSet('orders', connString);
+
+await orders.insertOne({ number: 'PO-1001', status: 'open' });
+const open = await orders.getDataByFilter({ status: 'open' }, { number: 1 }, { number: -1 });
+await orders.updateOne({ $set: { status: 'closed' } }, { number: 'PO-1001' });
+```
+
+Every method also has a **static** form that takes the collection name and connection string explicitly — handy when wrapping it in your own model class:
+
+```js
+class Order extends MongoDBToolSet {
+  static collectionName = 'orders';
+  static connString = connString;
+
+  static getById(id) {
+    return MongoDBToolSet.getDataByID(this.collectionName, id, undefined, this.connString);
+  }
+}
+```
+
+### Low-level (`MongoDBOps`)
+
+```js
+const { MongoDBOps } = require('mongodb-ops');
+
+const rows = await MongoDBOps.getData(
+  'orders',
+  { status: 'open' },              // query
+  false,                           // isAggregate
+  { number: 1 },                   // projection
+  { number: -1 },                  // sort
+  { startIndex: 1, endIndex: 20 }, // pagination (1-based, inclusive)
+  false,                           // isGetCount
+  connString
+);
+```
+
+## Connection management
+
+`getDbClient(connString)` maintains **one cached `MongoClient` per connection string** for the life of the process (kept in an internal `Map`; concurrent first-connects are de-duplicated). All operations reuse it, so there is no per-call connect overhead — and the driver's topology monitoring transparently rediscovers a new primary after a replica-set failover.
+
+Clients are created with safe, failover-friendly defaults:
+
+```js
+{ serverSelectionTimeoutMS: 8000, retryWrites: true, retryReads: true }
+```
+
+**Override or extend** the driver options process-wide, before the first connection is made — your values are merged over the defaults:
+
+```js
+const { MongoDBOps } = require('mongodb-ops');
+MongoDBOps.clientOptions = { maxPoolSize: 20 };
+```
+
+**Close** every cached connection (e.g. in a CLI or test teardown; long-running servers/Lambdas normally leave them open for reuse):
+
+```js
+await MongoDBOps.closeDBConn();
+```
+
+## API
+
+### `MongoDBToolSet`
+
+Constructor: `new MongoDBToolSet(collectionName, connString)`. Instance methods use the bound collection/connection; each has a matching static method that takes them as arguments.
+
+| Read | Write | Bulk |
+|---|---|---|
+| `getDataByID` | `insertOne` | `insertBulkOrdered` / `insertBulkUnOrdered` |
+| `getDataByFilter` | `replaceOne` | `replaceBulkOrdered` / `replaceBulkUnOrdered` |
+| `getDataByAggregate` | `updateOne` / `updateMany` | `updateBulkOrdered` / `updateBulkUnOrdered` |
+| `getDataCount` | `deleteOne` / `deleteMany` | `deleteBulkOrdered` / `deleteBulkUnOrdered` |
+| `list` (rows + optional total) | | `allBulkOrdered` / `allBulkUnOrdered` |
+| `getAllData` | | |
+
+### `MongoDBOps`
+
+`getData`, `search`, `writeData(type, …)`, `writeBulkData(type, …, ordered)`, `getCollectionCount`, `getObjectId`, `getDbClient`, `closeDBConn`.
+
+## Changelog
+
+### 0.11.1
+- **Hardened connection caching.** The client cache is now keyed by connection string in a `Map` (previously matched against MongoDB driver internals), making client reuse reliable across driver versions.
+- **De-duplicated concurrent cold-start connects** by caching the connect promise; a failed connect is evicted so the next call retries instead of caching a rejected promise.
+- **Safer driver defaults:** `serverSelectionTimeoutMS: 8000`, `retryWrites: true`, `retryReads: true` — reads now recover automatically across a replica-set failover/election.
+- **New `MongoDBOps.clientOptions`** hook to override/extend the driver options process-wide.
+- `closeDBConn()` now drains the client `Map` (and any legacy cache).
+
+### 0.11.0
+- Added estimated collection count (`getCollectionCount`).
+
+### Earlier
+- `search`, collation, and aggregate options. See the git history for details.
+
+## License
+
+ISC

package/test/fixtures/README.md

@@ -0,0 +1,7 @@
+# Orders Validator
+
+`vendor-orders-validator.json` is an unmodified copy of vendor-api's
+`db/validators/orders.json` at commit `303a01b425246b588f027145db04abe53049882e`.
+The real schema is checked in so the integration tests do not depend on a
+separate vendor-api checkout. In particular, `invoice_date: null` must be
+rejected by the same strict validator used by that service.

package/test/fixtures/vendor-orders-validator.json

@@ -0,0 +1,224 @@
+{
+  "$jsonSchema": {
+    "bsonType": "object",
+    "required": [
+      "_id",
+      "ts",
+      "order_id",
+      "vendor",
+      "submitted_by",
+      "status",
+      "address"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "_id": {
+        "bsonType": "string",
+        "pattern": "^EDI-[A-Za-z0-9-]+$",
+        "description": "site EDI-<digits> or marketplace EDI-<SELLERCODE>-<rawOrderId>"
+      },
+      "ts": {
+        "bsonType": "date"
+      },
+      "order_id": {
+        "bsonType": "string",
+        "pattern": "^[A-Za-z0-9-]+$",
+        "description": "site numeric id or marketplace raw order id"
+      },
+      "vendor": {
+        "bsonType": "string",
+        "pattern": "^[a-z]+$"
+      },
+      "vendor_po_num": {
+        "bsonType": "string",
+        "pattern": "^EDI-[A-Za-z0-9-]+$"
+      },
+      "submitted_by": {
+        "bsonType": "string"
+      },
+      "status": {
+        "bsonType": "string",
+        "pattern": "^(?:new|shipped|completed|send_error)$"
+      },
+      "items": {
+        "bsonType": "array",
+        "minimum": 1,
+        "items": {
+          "bsonType": "object",
+          "required": [
+            "sku",
+            "vendor_sku",
+            "unit_price",
+            "qty"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "sku": {
+              "bsonType": "string"
+            },
+            "vendor_sku": {
+              "bsonType": "string"
+            },
+            "unit_price": {
+              "bsonType": [
+                "int",
+                "double"
+              ]
+            },
+            "qty": {
+              "bsonType": "int"
+            }
+          }
+        }
+      },
+      "total_before_shipping": {
+        "bsonType": [
+          "int",
+          "double"
+        ]
+      },
+      "address": {
+        "bsonType": "object",
+        "required": [
+          "company_name",
+          "name",
+          "address_line1",
+          "address_line2",
+          "city",
+          "state_province",
+          "postal_code",
+          "country_code"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "company_name": {
+            "bsonType": "string"
+          },
+          "name": {
+            "bsonType": "string"
+          },
+          "address_line1": {
+            "bsonType": "string"
+          },
+          "address_line2": {
+            "bsonType": "string"
+          },
+          "city": {
+            "bsonType": "string"
+          },
+          "state_province": {
+            "bsonType": "string"
+          },
+          "postal_code": {
+            "bsonType": "string"
+          },
+          "country_code": {
+            "bsonType": "string"
+          }
+        }
+      },
+      "invoice_date": {
+        "bsonType": "string",
+        "pattern": "^[\\d]{4}-[\\d]{2}-[\\d]{2}$"
+      },
+      "invoice_id": {
+        "bsonType": "string"
+      },
+      "invoice_total": {
+        "bsonType": [
+          "int",
+          "double"
+        ]
+      },
+      "tracking_num": {
+        "bsonType": "string"
+      },
+      "tracking_updated_at": {
+        "bsonType": "date",
+        "description": "when tracking was last populated on this PO"
+      },
+      "shipping_cost": {
+        "bsonType": [
+          "int",
+          "double"
+        ]
+      },
+      "carrier": {
+        "bsonType": "string"
+      },
+      "signature_requested": {
+        "bsonType": "bool"
+      },
+      "channel": {
+        "bsonType": "string"
+      },
+      "seller_account": {
+        "bsonType": [
+          "string",
+          "null"
+        ]
+      },
+      "seller_code": {
+        "bsonType": [
+          "string",
+          "null"
+        ]
+      },
+      "marketplace_id": {
+        "bsonType": [
+          "string",
+          "null"
+        ]
+      },
+      "raw_order_id": {
+        "bsonType": [
+          "string",
+          "null"
+        ]
+      },
+      "source_order_id": {
+        "bsonType": "string"
+      },
+      "send_error": {
+        "bsonType": "string"
+      },
+      "marketplace_writeback_status": {
+        "bsonType": "string"
+      },
+      "marketplace_writeback_attempt_at": {
+        "bsonType": "date"
+      },
+      "marketplace_writeback_channel": {
+        "bsonType": "string"
+      },
+      "marketplace_writeback_error": {
+        "bsonType": [
+          "string",
+          "null"
+        ]
+      },
+      "marketplace_writeback_confirmed_at": {
+        "bsonType": "date"
+      },
+      "marketplace_writeback_carrier": {
+        "bsonType": "string"
+      },
+      "marketplace_writeback_tracking_number": {
+        "bsonType": "string"
+      },
+      "marketplace_writeback_failed_at": {
+        "bsonType": "date"
+      },
+      "marketplace_writeback_http_status": {
+        "bsonType": [
+          "int",
+          "double",
+          "null"
+        ]
+      },
+      "marketplace_writeback_last_error_at": {
+        "bsonType": "date"
+      }
+    }
+  }
+}

package/test/mongodb-ops.test.js

@@ -0,0 +1,160 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const mongodb = require('mongodb');
+
+const originalConnect = mongodb.MongoClient.connect;
+
+function freshMongoDBOps(connectImpl) {
+  delete require.cache[require.resolve('../lib/mongodb-ops')];
+  mongodb.MongoClient.connect = connectImpl;
+
+  const MongoDBOps = require('../lib/mongodb-ops');
+  MongoDBOps.dbClients = undefined;
+  MongoDBOps.dbClientList = undefined;
+  MongoDBOps.clientOptions = undefined;
+
+  return MongoDBOps;
+}
+
+function createClient(name) {
+  const closeCalls = [];
+  return {
+    name,
+    closeCalls,
+    db() { return {}; },
+    async close() { closeCalls.push(name); }
+  };
+}
+
+test.afterEach(() => {
+  mongodb.MongoClient.connect = originalConnect;
+  delete require.cache[require.resolve('../lib/mongodb-ops')];
+});
+
+test('reuses one client for repeated calls with the same connection string', async () => {
+  const calls = [];
+  const client = createClient('same');
+  const MongoDBOps = freshMongoDBOps(async (connString, options) => {
+    calls.push({ connString, options });
+    return client;
+  });
+
+  const first = await MongoDBOps.getDbClient('mongodb://example-a');
+  const second = await MongoDBOps.getDbClient('mongodb://example-a');
+
+  assert.equal(first, client);
+  assert.equal(second, client);
+  assert.equal(first, second);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].options.serverSelectionTimeoutMS, 8000);
+  assert.equal(calls[0].options.retryWrites, true);
+  assert.equal(calls[0].options.retryReads, true);
+});
+
+test('uses separate clients for different connection strings', async () => {
+  const calls = [];
+  const MongoDBOps = freshMongoDBOps(async (connString, options) => {
+    calls.push({ connString, options });
+    return createClient(connString);
+  });
+
+  const first = await MongoDBOps.getDbClient('mongodb://example-a');
+  const second = await MongoDBOps.getDbClient('mongodb://example-b');
+
+  assert.notEqual(first, second);
+  assert.deepEqual(calls.map((call) => call.connString), ['mongodb://example-a', 'mongodb://example-b']);
+});
+
+test('dedupes concurrent cold-start connection attempts', async () => {
+  const calls = [];
+  const client = createClient('concurrent');
+  let releaseConnect;
+  const connectStarted = new Promise((resolve) => {
+    releaseConnect = resolve;
+  });
+  const MongoDBOps = freshMongoDBOps(async (connString, options) => {
+    calls.push({ connString, options });
+    await connectStarted;
+    return client;
+  });
+
+  const pending = Array.from({ length: 5 }, () => MongoDBOps.getDbClient('mongodb://example-a'));
+  assert.equal(calls.length, 1);
+
+  releaseConnect();
+  const clients = await Promise.all(pending);
+
+  assert.equal(calls.length, 1);
+  assert.equal(new Set(clients).size, 1);
+  assert.equal(clients[0], client);
+});
+
+test('evicts failed connection promises so a later call reconnects', async () => {
+  let attempts = 0;
+  const client = createClient('retry');
+  const MongoDBOps = freshMongoDBOps(async () => {
+    attempts += 1;
+    if (attempts === 1) { throw new Error('connect failed'); }
+    return client;
+  });
+
+  await assert.rejects(MongoDBOps.getDbClient('mongodb://example-a'), /connect failed/);
+  const recovered = await MongoDBOps.getDbClient('mongodb://example-a');
+
+  assert.equal(recovered, client);
+  assert.equal(attempts, 2);
+});
+
+test('closeDBConn closes cached clients, clears the map, and reconnects next time', async () => {
+  const calls = [];
+  const clients = [];
+  const MongoDBOps = freshMongoDBOps(async (connString, options) => {
+    calls.push({ connString, options });
+    const client = createClient(connString);
+    clients.push(client);
+    return client;
+  });
+
+  await MongoDBOps.getDbClient('mongodb://example-a');
+  await MongoDBOps.getDbClient('mongodb://example-b');
+  await MongoDBOps.closeDBConn();
+
+  assert.equal(clients[0].closeCalls.length, 1);
+  assert.equal(clients[1].closeCalls.length, 1);
+  assert.equal(MongoDBOps.dbClients.size, 0);
+
+  await MongoDBOps.getDbClient('mongodb://example-a');
+  assert.equal(calls.length, 3);
+});
+
+test('closeDBConn also drains legacy dbClientList clients', async () => {
+  const MongoDBOps = freshMongoDBOps(async () => createClient('unused'));
+  const legacyClient = createClient('legacy');
+  MongoDBOps.dbClientList = [legacyClient];
+
+  await MongoDBOps.closeDBConn();
+
+  assert.equal(legacyClient.closeCalls.length, 1);
+  assert.deepEqual(MongoDBOps.dbClientList, []);
+});
+
+test('passes safe MongoDB driver options and permits consumer overrides', async () => {
+  const calls = [];
+  const client = createClient('options');
+  const MongoDBOps = freshMongoDBOps(async (connString, options) => {
+    calls.push({ connString, options });
+    return client;
+  });
+  MongoDBOps.clientOptions = { serverSelectionTimeoutMS: 5000, maxPoolSize: 10 };
+
+  await MongoDBOps.getDbClient('mongodb://example-a');
+
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].options.serverSelectionTimeoutMS, 5000);
+  assert.equal(calls[0].options.retryWrites, true);
+  assert.equal(calls[0].options.retryReads, true);
+  assert.equal(calls[0].options.maxPoolSize, 10);
+});
+