mongodash 2.0.0 → 2.1.0

package/docs/with-lock.md

@@ -0,0 +1,45 @@
+# withLock
+
+Utility function to control concurrency.
+
+## withLock(key, callback [, options]) => Promise
+
+```typescript
+withLock(key, callback [, options]) => Promise
+```
+
+The `withLock` function ensures only one process steps into the [critical section](https://en.wikipedia.org/wiki/Critical_section) (callback).
+
+```typescript
+import { withLock } from 'mongodash';
+
+function updateUser (userId, data) {
+    return withLock(`user-update-${userId}`, async () => {
+        const user = await getUserFromDatabase(userId);
+        user.setData(data);
+        await saveUserToDatabase(user);
+        return user;
+    });
+}
+
+// all calls are triggered in parallel,
+// the withLock ensures they will be processed one by one
+updateUser(1, { name: 'Joe' });
+updateUser(1, { surname: 'Doe' });
+updateUser(1, { nick: 'J' });
+```
+
+The `withLock` function uses [busy wait](https://en.wikipedia.org/wiki/Busy_waiting) with a combination of sleep if the lock is occupied. The sleep time is determined by the [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) strategy.
+
+The key is always converted to a string internally, so `100` and `"100"` are considered as the same key.
+
+The lock is acquired for an amount of time (see expireIn option). If the callback lasts too long, the lock is prolonged automatically.
+
+## Usable even in scalable (multi-instance) applications
+
+Usable even in scalable (multi-instance) applications thanks to lock registration in MongoDB.
+Mongodash will ensure only one execution process step into the callback.
+
+## Options
+
+(Documentation for options was not fully retrievable. Common options likely include `expireIn`.)

package/docs/with-transaction.md

@@ -0,0 +1,65 @@
+# withTransaction
+
+The more perfect variant of the native driver's `withTransaction` function.
+
+## withTransaction(callback) => Promise
+
+```typescript
+withTransaction(callback) => Promise
+```
+
+```typescript
+import { withTransaction, getCollection } from 'mongodash';
+import { ClientSession } from 'mongodb';
+
+const createdDocuments = await withTransaction(async (session: ClientSession) => {
+    const collection = getCollection('myCollection');
+    const myDocument1 = { value: 1 };
+    const myDocument2 = { value: 2 };
+    
+    await collection.insertOne(myDocument1, { session });
+    await collection.insertOne(myDocument2, { session });
+    
+    return [myDocument1, myDocument2];
+});
+```
+
+## Benefits over the native driver's function
+
+Benefits over the native driver's [withTransaction](https://mongodb.github.io/node-mongodb-native/4.0/classes/clientsession.html#withtransaction) function:
+
+- automatically starts a new `clientSession`
+- automatically ends the `clientSession` (even on failure)
+- propagates the value returned from the callback
+
+It does all the necessary code described in the [official docs](https://docs.mongodb.com/realm/mongodb/transactions/) automatically.
+
+## Post Commit Hooks
+
+You can register hooks that will be executed **only after the transaction successfully commits**.
+
+### registerPostCommitHook(session, callback) => void
+
+```typescript
+registerPostCommitHook(session: ClientSession, callback: () => void | Promise<void>) => void
+```
+
+This is extremely useful for side effects that should happen effectively "outside" the transaction but only if the transaction succeeds, such as:
+- Sending emails
+- invalidating caches
+- Triggering webhooks
+
+```typescript
+import { withTransaction, registerPostCommitHook } from 'mongodash';
+
+await withTransaction(async (session) => {
+    // 1. Modify DB inside transaction
+    await db.collection('orders').insertOne({ status: 'created' }, { session });
+    
+    // 2. Register side-effect
+    registerPostCommitHook(session, async () => {
+        // This runs ONLY if transaction commits successfully
+        await emailService.sendOrderConfirmation();
+    });
+});
+```