@andrew_l/mongo-transaction 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Andrew L. <andrew.io.dev@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# Mongo Transaction Toolkit <!-- omit in toc -->
+
+![license](https://img.shields.io/npm/l/%40andrew_l%2Fmongo-transaction) <!-- omit in toc -->
+![npm version](https://img.shields.io/npm/v/%40andrew_l%2Fmongo-transaction) <!-- omit in toc -->
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40andrew_l%2Fmongo-transaction) <!-- omit in toc -->
+
+This package solves a common issue with MongoDB's `session.withTransaction`, where the provided function might be executed multiple times due to retries. This can create challenges for managing side effects that need to be rolled back consistently during transaction retries or failures.
+
+[Documentation](https://men232.github.io/toolkit/reference/@andrew_l/mongo-transaction/)
+
+<!-- install placeholder -->
+
+## ✨ Features
+
+- **Transactional Effects:** Easily register actions to be rolled back if a transaction fails.
+- **Retry-Safe Operations:** Avoid duplicating side effects during transaction retries.
+- **Cleanup Support:** Ensure that all registered effects are undone if the transaction is canceled.
+
+## ⚠️ Cautions
+
+To ensure smooth usage, please keep the following in mind:
+
+- **Error Handling:** If your effects throw an error, the transaction will roll back.
+- **Calls:** Always `await` the promises returned by `useTransactionEffect()`.
+- **Placement:** Do not use `useTransactionEffect()` inside nested blocks like conditionals or loops.
+- **Mongoose:** Ensure the connection is established before using the client: `withMongoTransaction(() => mongoose.connection.getClient())`.
+
+## 🚀 Example: Automatic Rollback of Side Effects
+
+This example demonstrates how to use the transaction context to automatically manage side effects and roll back actions if an error occurs during execution.
+
+```js
+const confirmOrder = withTransaction(async orderId => {
+  // Register Alert
+  await useTransactionEffect(async () => {
+    const alertId = await alertService.create({
+      title: 'New Order: ' + orderId,
+    });
+
+    return () => alertService.removeById(alertId);
+  });
+
+  // Update Statistics
+  await useTransactionEffect(async () => {
+    await statService.increment('orders_amount', 1);
+
+    return () => statService.decrement('orders_amount', 1);
+  });
+
+  throw new Error('Oops.');
+});
+```
+
+## 🚀 Example: Usage MongoDB
+
+Below is an example demonstrating how to use `withMongoTransaction` to manage side effects like creating and removing alerts during a transaction. If the transaction fails, the created alert is automatically removed. Additionally, the logic ensures duplicate alerts are not created during MongoDB's retry mechanism.
+
+```js
+import mongoose from 'mongoose';
+import {
+  useTransactionEffect,
+  withMongoTransaction,
+} from '@andrew_l/mongo-transaction';
+
+const confirmOrder = withMongoTransaction({
+  connection: () => mongoose.connection.getClient(),
+  async fn(session) {
+    // Register an alert as a transactional effect
+    await useTransactionEffect(async () => {
+      const alertId = await alertService.create({
+        title: `Order Confirmed: ${orderId}`,
+      });
+
+      // Define cleanup logic to remove the alert on rollback
+      return () => alertService.removeById(alertId);
+    });
+
+    // Simulate order processing (e.g., database updates)
+    await db
+      .collection('orders')
+      .updateOne({ orderId }, { $set: { status: 'confirmed' } }, { session });
+
+    // Simulate an error to test rollback
+    throw new Error('Simulated transaction failure');
+  },
+});
+
+confirmOrder('673b907dddd8ae43262aec0d').catch(console.error);
+```
+
+## 🤔 Why Use This Package?
+
+1. **Safe Retries:** MongoDB retries can cause duplicate actions if not handled properly. This package ensures all side effects are idempotent and reversible.
+2. **Streamlined Rollbacks:** Simplifies managing complex operations by integrating rollback mechanisms into your transaction workflow.
+3. **Ease of Use:** API design mimics React's hooks, making it intuitive for developers familiar with React patterns.

package/dist/index.cjs

@@ -0,0 +1,472 @@
+'use strict';
+
+const toolkit = require('@andrew_l/toolkit');
+const context = require('@andrew_l/context');
+const mongodb = require('mongodb');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const [injectMongoSession, provideMongoSession] = context.createContext("withMongoTransaction");
+function useMongoSession() {
+  return context.hasInjectionContext() ? injectMongoSession(null) : null;
+}
+
+function onMongoSessionCommitted(...args) {
+  let session;
+  let fn;
+  if (args.length === 2) {
+    [session, fn] = args;
+  } else {
+    session = injectMongoSession();
+    fn = args[0];
+  }
+  const q = toolkit.defer();
+  const onEnded = () => {
+    if (!session.transaction.isCommitted) {
+      return q.resolve(void 0);
+    }
+    try {
+      const result = fn();
+      if (toolkit.isPromise(result)) {
+        result.then((r) => q.resolve(r)).catch(q.reject);
+      } else {
+        q.resolve(result);
+      }
+    } catch (err) {
+      q.reject(err);
+    }
+  };
+  session.once("ended", onEnded);
+  const cancel = () => {
+    session.off("ended", onEnded);
+  };
+  return {
+    promise: q.promise,
+    cancel
+  };
+}
+
+const [injectTransactionScope, provideTransactionScope] = context.createContext([
+  "withTransaction",
+  "withTransactionControlled",
+  "withMongoTransaction"
+]);
+
+class TransactionScope {
+  constructor(fn) {
+    this.fn = fn;
+    const scope = this;
+    this.run = function(...args) {
+      const self = this === scope ? void 0 : this;
+      return scope._run(self, ...args);
+    };
+  }
+  /**
+   * @internal
+   */
+  log = toolkit.logger(({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)) }), "TransactionScope");
+  /**
+   * @internal
+   * Indicates currently ran scope
+   */
+  _active = false;
+  /**
+   * Last run error
+   */
+  error;
+  /**
+   * Last run result
+   */
+  result;
+  run;
+  /**
+   * @internal
+   */
+  hooks = {
+    committed: { byCursor: [], cursor: 0 },
+    effects: { byCursor: [], cursor: 0 },
+    rollbacks: { byCursor: [], cursor: 0 }
+  };
+  get active() {
+    return this._active;
+  }
+  /**
+   * @internal
+   */
+  async _run(self, ...args) {
+    toolkit.assert.ok(!this._active, "Cannot run while transaction active.");
+    this.reset();
+    this._active = true;
+    const [cbError, cbResult] = await context.withContext(() => {
+      provideTransactionScope(this);
+      return toolkit.catchError(this.fn.bind(self, ...args));
+    })();
+    if (cbError) {
+      this.error = cbError;
+    } else {
+      const applyError = await effectsApply(this, "post");
+      if (applyError) {
+        this.error = applyError;
+      }
+      this.result = cbResult;
+    }
+    this._active = false;
+  }
+  async commit() {
+    toolkit.assert.ok(!this._active, "Cannot commit while transaction active.");
+    toolkit.assert.ok(!this.error, this.error);
+    await toolkit.asyncForEach(
+      this.hooks.committed.byCursor,
+      (h) => toolkit.catchError(h.callback),
+      { concurrency: 4 }
+    );
+    this.reset();
+    this.clean();
+  }
+  async rollback() {
+    toolkit.assert.ok(!this._active, "Cannot rollback while transaction active.");
+    const error = await effectsCleanup(this);
+    if (error) {
+      return Promise.reject(error);
+    }
+    await toolkit.asyncForEach(
+      this.hooks.rollbacks.byCursor,
+      (h) => toolkit.catchError(h.callback),
+      { concurrency: 4 }
+    );
+    this.reset();
+    this.clean();
+  }
+  reset() {
+    toolkit.assert.ok(!this._active, "Cannot reset while transaction active.");
+    this.hooks.effects.cursor = 0;
+    this.hooks.committed.cursor = 0;
+    this.hooks.rollbacks.cursor = 0;
+    this.result = void 0;
+    this.error = void 0;
+  }
+  clean() {
+    toolkit.assert.ok(!this._active, "Cannot clean while transaction active.");
+    this.hooks.effects = { byCursor: [], cursor: 0 };
+    this.hooks.committed = { byCursor: [], cursor: 0 };
+    this.hooks.rollbacks = { byCursor: [], cursor: 0 };
+  }
+}
+function createTransactionScope(fn) {
+  return new TransactionScope(fn);
+}
+async function effectsApply(scope, reason = "no reason") {
+  let error;
+  const onComplete = (err) => void (error = err || error);
+  await toolkit.asyncForEach(
+    scope.hooks.effects.byCursor,
+    (effect) => applyEffect(scope, effect, reason).then(onComplete),
+    {
+      concurrency: 4
+    }
+  );
+  return error;
+}
+async function effectsCleanup(scope, reason = "no reason") {
+  let error;
+  const onComplete = (err) => void (error = err || error);
+  await toolkit.asyncForEach(
+    scope.hooks.effects.byCursor,
+    (effect) => cleanupEffect(scope, effect, reason).then(onComplete),
+    {
+      concurrency: 4
+    }
+  );
+  return error;
+}
+async function applyEffect(scope, effect, reason = "no reason") {
+  if (effect.cleanup) return;
+  scope.log.debug(
+    "Effect name = %s, flush = %s, apply by %s",
+    effect.name,
+    effect.flush,
+    reason
+  );
+  const [err, effectResult] = await toolkit.catchError(effect.setup);
+  if (err) {
+    !toolkit.env.isTest && scope.log.error(
+      "Effect name = %s, flush = %s apply error",
+      effect.name,
+      effect.flush,
+      err
+    );
+    return err;
+  }
+  effect.cleanup = toolkit.isFunction(effectResult) ? effectResult : toolkit.noop;
+  return;
+}
+async function cleanupEffect(scope, effect, reason = "no reason") {
+  if (!effect.cleanup) return;
+  scope.log.debug(
+    "Effect name = %s, flush = %s, cleanup by %s",
+    effect.name,
+    effect.flush,
+    reason
+  );
+  const [err] = await toolkit.catchError(effect.cleanup);
+  if (err) {
+    !toolkit.env.isTest && scope.log.error(
+      "Effect name = %s, flush = %s, cleanup error",
+      effect.name,
+      effect.flush,
+      err
+    );
+    return err;
+  }
+  effect.cleanup = void 0;
+}
+
+async function useTransactionEffect(setup, options = {}) {
+  const scope = injectTransactionScope();
+  const { cursor, byCursor } = scope.hooks.effects;
+  const effectConfig = byCursor[cursor] ?? {};
+  const flush = options?.flush || "pre";
+  const name = options?.name || `Effect #${cursor + 1}`;
+  const dependencies = options.dependencies ?? [];
+  const prevDependencies = effectConfig.dependencies;
+  byCursor[cursor] = {
+    ...effectConfig,
+    dependencies,
+    flush,
+    name,
+    setup
+  };
+  if (dependencies && prevDependencies) {
+    if (!toolkit.isEqual(dependencies, prevDependencies)) {
+      scope.log.debug(
+        "Effect name = %s, flush = %s, caused by dependencies",
+        name,
+        flush,
+        {
+          prevDependencies,
+          newDependencies: dependencies
+        }
+      );
+      await scheduleEffect(scope, cursor);
+    }
+  } else {
+    scope.log.debug(
+      "Effect name = %s, flush = %s, caused by missing dependencies",
+      name,
+      flush
+    );
+    await scheduleEffect(scope, cursor);
+  }
+  scope.hooks.effects.cursor++;
+}
+async function scheduleEffect(scope, cursor) {
+  const { byCursor } = scope.hooks.effects;
+  const effect = byCursor[cursor];
+  const cleanupErr = await cleanupEffect(scope, effect, "schedule pre");
+  if (cleanupErr) {
+    return Promise.reject(cleanupErr);
+  }
+  if (effect.flush === "pre") {
+    const err = await applyEffect(scope, effect, "schedule pre");
+    if (err) {
+      return Promise.reject(err);
+    }
+  }
+}
+
+function onCommitted(callback, dependencies) {
+  const scope = injectTransactionScope();
+  const { cursor, byCursor } = scope.hooks.committed;
+  const config = byCursor[cursor];
+  if (dependencies && config?.dependencies) {
+    if (!toolkit.isEqual(dependencies, config.dependencies)) {
+      scope.log.debug("OnCommitted caused by dependencies", {
+        prevDependencies: config.dependencies,
+        newDependencies: dependencies,
+        cursor
+      });
+      byCursor[cursor] = { callback, dependencies };
+    }
+  } else {
+    scope.log.debug("OnCommitted caused by missing dependencies", { cursor });
+    byCursor[cursor] = { callback, dependencies };
+  }
+  scope.hooks.committed.cursor++;
+  return () => {
+    byCursor[cursor].callback = toolkit.noop;
+  };
+}
+
+function onRollback(callback, dependencies) {
+  const scope = injectTransactionScope();
+  const { cursor, byCursor } = scope.hooks.rollbacks;
+  const config = byCursor[cursor];
+  if (dependencies && config?.dependencies) {
+    if (!toolkit.isEqual(dependencies, config.dependencies)) {
+      scope.log.debug("OnCommitted caused by dependencies", {
+        prevDependencies: config.dependencies,
+        newDependencies: dependencies,
+        cursor
+      });
+      byCursor[cursor] = { callback, dependencies };
+    }
+  } else {
+    scope.log.debug("OnCommitted caused by missing dependencies", { cursor });
+    byCursor[cursor] = { callback, dependencies };
+  }
+  scope.hooks.committed.cursor++;
+  return () => {
+    byCursor[cursor].callback = toolkit.noop;
+  };
+}
+
+function isTransactionAborted(transaction) {
+  return transaction?.state === "TRANSACTION_ABORTED";
+}
+function isTransactionCommittedEmpty(transaction) {
+  return transaction?.state === "TRANSACTION_COMMITTED_EMPTY";
+}
+function isMongoClientLike(value) {
+  return toolkit.has(value, ["startSession"]) && toolkit.isFunction(value.startSession);
+}
+
+const DEF_SESSION_OPTIONS = Object.freeze({
+  defaultTransactionOptions: {
+    readPreference: "primary",
+    readConcern: { level: "local" },
+    writeConcern: { w: "majority" }
+  }
+});
+function withMongoTransaction(connectionOrOptions, maybeFn, maybeOptions) {
+  const {
+    connection: connectionValue,
+    fn,
+    sessionOptions = {},
+    timeoutMS
+  } = prepareOptions(connectionOrOptions, maybeFn, maybeOptions);
+  return async function(...args) {
+    const connection = toolkit.isFunction(connectionValue) ? await connectionValue() : connectionValue;
+    const session = await connection.startSession(
+      sessionOptions
+    );
+    const scope = createTransactionScope(function(...args2) {
+      provideMongoSession(session);
+      return fn.call(this, session, ...args2);
+    });
+    const timeoutAt = timeoutMS ? Date.now() + timeoutMS : 0;
+    const timeoutError = new mongodb.MongoTransactionError(
+      "Transaction client-side timeout"
+    );
+    let [transactionError, transactionResult] = await toolkit.catchError(
+      () => session.withTransaction(async () => {
+        if (timeoutAt && timeoutAt < Date.now()) {
+          return Promise.reject(timeoutError);
+        }
+        await scope.run.apply(this, args);
+        if (scope.error) {
+          return Promise.reject(scope.error);
+        }
+      })
+    );
+    const { result } = scope;
+    await session.endSession().catch(toolkit.noop);
+    if (transactionResult === void 0 && isTransactionCommittedEmpty(session.transaction)) ; else if (isTransactionAborted(session.transaction) && transactionResult === void 0 && transactionError === void 0) {
+      transactionError = new mongodb.MongoTransactionError(
+        "Transaction is explicitly aborted"
+      );
+    }
+    if (transactionError) {
+      await scope.rollback();
+      return Promise.reject(transactionError);
+    }
+    await scope.commit();
+    return result;
+  };
+}
+function prepareOptions(connectionOrOptions, maybeFn, maybeOptions) {
+  let options;
+  if (toolkit.isFunction(connectionOrOptions) || isMongoClientLike(connectionOrOptions)) {
+    options = {
+      ...maybeOptions || {},
+      connection: connectionOrOptions,
+      fn: maybeFn
+    };
+  } else {
+    options = connectionOrOptions;
+  }
+  return toolkit.deepDefaults(options, {
+    sessionOptions: DEF_SESSION_OPTIONS
+  });
+}
+
+function withTransaction(fn, {
+  beforeRetryCallback,
+  shouldRetryBasedOnError = () => true,
+  maxRetriesNumber = 5,
+  delayFactor = 0,
+  delayMaxMs = 1e3,
+  delayMinMs = 100
+} = {}) {
+  return async function(...args) {
+    const scope = createTransactionScope(fn);
+    await toolkit.retryOnError(
+      {
+        beforeRetryCallback,
+        shouldRetryBasedOnError,
+        maxRetriesNumber,
+        delayFactor,
+        delayMaxMs,
+        delayMinMs
+      },
+      async () => {
+        await scope.run.apply(this, args);
+        if (scope.error) {
+          return Promise.reject(scope.error);
+        }
+      }
+    )().catch(toolkit.noop);
+    const { error, result } = scope;
+    if (error) {
+      await scope.rollback();
+      return Promise.reject(error);
+    } else {
+      await scope.commit();
+    }
+    return result;
+  };
+}
+
+function withTransactionControlled(fn) {
+  const scope = createTransactionScope(fn);
+  const controlled = {
+    run(...args) {
+      const self = this === controlled ? void 0 : this;
+      return scope.run.apply(self, args);
+    },
+    commit() {
+      return scope.commit();
+    },
+    rollback() {
+      return scope.rollback();
+    },
+    get active() {
+      return scope.active;
+    },
+    get result() {
+      return scope.result;
+    },
+    get error() {
+      return scope.error;
+    }
+  };
+  return controlled;
+}
+
+exports.onCommitted = onCommitted;
+exports.onMongoSessionCommitted = onMongoSessionCommitted;
+exports.onRollback = onRollback;
+exports.useMongoSession = useMongoSession;
+exports.useTransactionEffect = useTransactionEffect;
+exports.withMongoTransaction = withMongoTransaction;
+exports.withTransaction = withTransaction;
+exports.withTransactionControlled = withTransactionControlled;
+//# sourceMappingURL=index.cjs.map