@andrew_l/mongo-transaction 0.3.22 → 0.4.0

package/dist/index.d.ts

@@ -1,391 +0,0 @@
-import { Awaitable, Fn, AnyFunction, RetryOnErrorConfig } from '@andrew_l/toolkit';
-import { ClientSession, ClientSessionOptions } from 'mongodb';
-
-type OnMongoSessionCommittedResult<T> = {
-    /**
-     * Executes the provided function upon transaction commit.
-     *
-     * Returns `T` if the transaction is committed and the function completes successfully.
-     *
-     * Returns `undefined` if the transaction is explicitly aborted or ends without committing.
-     *
-     * Rejects if the function throws an error.
-     */
-    promise: Promise<T | undefined>;
-    cancel: () => void;
-};
-/**
- * Executes the provided function upon transaction commit.
- *
- * Returns `T` if the transaction is committed and the function completes successfully.
- *
- * Returns `false` if the transaction ends without committing.
- *
- * Rejects if the function throws an error.
- *
- * @example
- * const { promise } = onTransactionCommitted(async () => {
- *   console.info('Transaction committed successfully!');
- *   return Math.random(); // Random value generated after commit
- * });
- *
- * promise.then(result => {
- *   if (result !== false) {
- *     console.info('Handler result:', result); // e.g., Handler result: 0.07576196837476501
- *   }
- * });
- *
- * @group Hooks
- */
-declare function onMongoSessionCommitted<T>(fn: () => Awaitable<T>): OnMongoSessionCommittedResult<T>;
-declare function onMongoSessionCommitted<T>(session: ClientSession, fn: () => Awaitable<T>): OnMongoSessionCommittedResult<T>;
-
-/**
- * Returns the current transaction session if executed within `withMongoTransaction()` otherwise returns `null`
- *
- * @example
- * async function createAlert() {
- *   const session = useMongoSession();
- *
- *   await db.alerts.insertOne(
- *     { title: 'Order Created' },
- *     { session: session ?? undefined }
- *   );
- * }
- *
- * @group Hooks
- */
-declare function useMongoSession(): ClientSession | null;
-
-interface TransactionEffect {
-    /**
-     * Specifies when the transaction effect should run:
-     *
-     * `pre` -  execute immediately
-     *
-     *  `post` - execute before transaction commit
-     *
-     * @default: "pre"
-     */
-    flush: 'pre' | 'post';
-    /**
-     * Setup effect function. You can return a cleanup callback to be used as a rollback.
-     */
-    setup: EffectCallback;
-    /**
-     * Cleanup function.
-     */
-    cleanup?: EffectCleanup;
-    /**
-     * Useful for debugging execution logs.
-     */
-    name?: string;
-    dependencies?: readonly any[];
-}
-type EffectCallback = () => Awaitable<EffectCleanup | void>;
-type EffectCleanup = () => Awaitable<void>;
-type OnCommittedCallback = () => Awaitable<void>;
-type OnRollbackCallback = () => Awaitable<void>;
-
-type UseTransactionEffectOptions = Partial<Pick<TransactionEffect, 'name' | 'flush' | 'dependencies'>>;
-/**
- * Executes a transactional effect with cleanup on error or rollback.
- *
- * Ensures the `callback` function is executed only once per transaction, even during retries.
- * On errors or dependency changes, the cleanup logic is invoked before re-execution to maintain consistency.
- *
- * @param setup A function defining the transactional effect. It is guaranteed to run once per transaction
- *              and may be re-executed after cleanup if dependencies change.
- *
- * @example
- * 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');
- *   },
- * });
- *
- * @group Hooks
- */
-declare function useTransactionEffect(setup: TransactionEffect['setup'], options?: UseTransactionEffectOptions): Promise<void>;
-
-/**
- * Registers a callback to be executed upon transaction commitment, with support
- * for dependency-based updates.
- *
- * This function is used within a transaction scope to perform specific actions
- * when a transaction is committed. If dependencies are provided, the callback
- * is re-registered only if the dependencies have changed. Otherwise, the
- * callback is registered unconditionally.
- *
- * @param {OnCommittedCallback} callback - The function to be executed upon
- *   transaction commitment.
- * @param {readonly any[]} [dependencies=[]] - An optional array of dependencies
- *   to determine if the callback should be re-registered. If the dependencies
- *   differ from the previously registered ones, the callback is updated.
- * @returns {Fn} A cleanup function to cancel event listener.
- *
- * @example
- * // Basic usage without dependencies
- * onCommitted(() => {
- *   console.log('Transaction committed!');
- * });
- *
- * @example
- * // Using dependencies
- * count++;
- * onCommitted(() => {
- *   console.log(`Commit #${count}`);
- * }, [count]);
- *
- * @example
- * //  Cancel by request
- * const cancel = onCommitted(() => {
- *   console.log('This will run only once!');
- * });
- *
- * if (orderReceived) {
- *   cancel(); // Prevents onCommitted from running
- * }
- *
- * @group Hooks
- */
-declare function onCommitted(callback: OnCommittedCallback, dependencies?: readonly any[]): Fn;
-
-/**
- * Registers a callback to be executed upon transaction rollback, with support
- * for dependency-based updates.
- *
- * This function is used within a transaction scope to perform specific actions
- * when a transaction is rolled back. If dependencies are provided, the callback
- * is re-registered only if the dependencies have changed. Otherwise, the
- * callback is registered unconditionally.
- *
- * @param {OnRollbackCallback} callback - The function to be executed upon
- *   transaction rollback.
- * @param {readonly any[]} [dependencies=[]] - An optional array of dependencies
- *   to determine if the callback should be re-registered. If the dependencies
- *   differ from the previously registered ones, the callback is updated.
- * @returns {Fn} A cleanup function to cancel event listener.
- *
- * @example
- * // Basic usage without dependencies
- * onRollback(() => {
- *   console.log('Transaction rolled back!');
- * });
- *
- * @example
- * // Using dependencies
- * count++;
- * onRollback(() => {
- *   console.log(`Rollback detected, flag is ${flag}`);
- * }, [count]);
- *
- * @example
- * // Cancel by request
- * const cancel = onRollback(() => {
- *   console.log('This will run only once on rollback!');
- * });
- *
- * if (orderReceived) {
- *   cancel(); // Prevents onRollback from running
- * }
- *
- * @group Hooks
- */
-declare function onRollback(callback: OnRollbackCallback, dependencies?: readonly any[]): Fn;
-
-interface MongoClientLike {
-    startSession(options: Record<string, any>): ClientSessionLike;
-}
-interface ClientSessionLike {
-    withTransaction(fn: AnyFunction): Promise<any>;
-    endSession(): Promise<void>;
-}
-type ConnectionValue = MongoClientLike | (() => Awaitable<MongoClientLike>);
-type Callback<T, K = any, Args extends Array<any> = any[]> = (this: K, session: ClientSession, ...args: Args) => Awaitable<T>;
-interface WithMongoTransactionOptions<T, K = any, Args extends Array<any> = any[]> {
-    /**
-     * Mongodb connection getter
-     */
-    connection: ConnectionValue;
-    /**
-     * Transaction session options
-     *
-     * @default: {
-     *   defaultTransactionOptions: {
-     *     readPreference: 'primary',
-     *     readConcern: { level: 'local' },
-     *     writeConcern: { w: 'majority' },
-     *   }
-     * }
-     */
-    sessionOptions?: ClientSessionOptions;
-    /**
-     * Configures a timeoutMS expiry for the entire withTransactionCallback.
-     *
-     * @remarks
-     * - The remaining timeout will not be applied to callback operations that do not use the ClientSession.
-     * - Overriding timeoutMS for operations executed using the explicit session inside the provided callback will result in a client-side error.
-     */
-    timeoutMS?: number;
-    /**
-     * Transaction function that will be executed
-     *
-     * ⚠️ Possible several times!
-     */
-    fn: Callback<T, K, Args>;
-}
-type WithMongoTransactionWrapped<T, K = any, Args extends Array<any> = any[]> = (this: K, ...args: Args) => Promise<T>;
-/**
- * Runs a provided callback within a transaction, retrying either the commitTransaction operation or entire transaction as needed (and when the error permits) to better ensure that the transaction can complete successfully.
- *
- * Passes the session as the function's first argument or via `useMongoSession()` hook
- *
- * @example
- * const executeTransaction = withMongoTransaction({
- *   connection: () => mongoose.connection.getClient(),
- *   async fn() {
- *     const session = useMongoSession();
- *     const orders = mongoose.connection.collection('orders');
- *
- *     const { modifiedCount } = await orders.updateMany(
- *       { status: 'pending' },
- *       { $set: { status: 'confirmed' } },
- *       { session },
- *     );
- *   },
- * });
- *
- * @group Main
- */
-declare function withMongoTransaction<T, K = any, Args extends Array<any> = any[]>(options: WithMongoTransactionOptions<T, K, Args>): WithMongoTransactionWrapped<T, K, Args>;
-/**
- * Runs a provided callback within a transaction, retrying either the commitTransaction operation or entire transaction as needed (and when the error permits) to better ensure that the transaction can complete successfully.
- *
- * Passes the session as the function's first argument or via `useMongoSession()` hook
- *
- * @example
- * const executeTransaction = withMongoTransaction(mongoose.connection.getClient(), async () => {
- *   const session = useMongoSession();
- *   const orders = mongoose.connection.collection('orders');
- *
- *   const { modifiedCount } = await orders.updateMany(
- *     { status: 'pending' },
- *     { $set: { status: 'confirmed' } },
- *     { session },
- *   );
- * });
- */
-declare function withMongoTransaction<T, K = any, Args extends Array<any> = any[]>(connection: ConnectionValue, fn: Callback<T, K, Args>, options?: Omit<WithMongoTransactionOptions<any>, 'fn' | 'connection'>): WithMongoTransactionWrapped<T, K, Args>;
-
-interface WithTransactionOptions extends Partial<RetryOnErrorConfig> {
-}
-/**
- * Wraps a function with transaction context, enabling retry logic and transactional effects.
- *
- * The wrapped function may be executed multiple times (up to `maxRetriesNumber`) to ensure
- * all side effects complete successfully. If the retries are exhausted without success,
- * registered cleanup functions will be executed to undo any applied effects.
- *
- * This utility is useful for managing transactional side effects, such as
- * updates to external systems, and ensures proper cleanup in case of failure.
- *
- * Additionally, this enables hooks like `useTransactionEffect()`, which allows
- * defining effects with automatic rollback mechanisms.
- *
- * @param fn - The target function to wrap with transaction handling.
- * @param [options] - Configuration options for the transaction handling.
- * @param [options.beforeRetryCallback] - An optional callback to execute before each retry attempt.
- * @param [options.shouldRetryBasedOnError] - A predicate to determine if a retry should occur based on the thrown error. Defaults to always retry.
- * @param [options.maxRetriesNumber=5] - The maximum number of retries before failing the transaction. Defaults to 5.
- * @param [options.delayFactor=0] - A multiplier for the delay between retries. Default is 0 (no exponential backoff).
- * @param [options.delayMaxMs=1000] - The maximum delay between retries, in milliseconds. Defaults to 1000 ms.
- * @param [options.delayMinMs=100] - The minimum delay between retries, in milliseconds. Defaults to 100 ms.
- *
- * @example
- * const confirmOrder = withTransaction(async (orderId) => {
- *   // Register Alert
- *   await useTransactionEffect(async () => {
- *     const alertId = await alertService.create({
- *       title: 'New Order: ' + orderId,
- *     });
- *
- *     return () => alertService.removeById(alertId); // Cleanup in case of failure
- *   });
- *
- *   // Update Statistics
- *   await useTransactionEffect(async () => {
- *     await statService.increment('orders_amount', 1);
- *
- *     return () => statService.decrement('orders_amount', 1); // Cleanup in case of failure
- *   });
- *
- *   // Simulate failure to trigger rollback
- *   throw new Error('Cancel transaction.');
- * });
- *
- * @group Main
- */
-declare function withTransaction<T, K = any, Args extends Array<any> = any[]>(fn: (this: K, ...args: Args) => T, { beforeRetryCallback, shouldRetryBasedOnError, maxAttempts, maxRetriesNumber, delayFactor, delayMaxMs, delayMinMs, }?: WithTransactionOptions): (this: K, ...args: Args) => Promise<Awaited<T>>;
-
-interface TransactionControlled<T, K = any, Args extends Array<any> = any[]> {
-    run: (this: K, ...args: Args) => Promise<void>;
-    commit: () => Promise<void>;
-    rollback: () => Promise<void>;
-    result: Readonly<T | undefined>;
-    error: Readonly<Error | undefined>;
-    active: boolean;
-}
-/**
- * Wraps a function and returns a `TransactionControlled` interface, allowing manual control
- * over transaction commit and rollback operations.
- *
- * This provides finer-grained control over the transaction lifecycle, enabling users to
- * explicitly commit or rollback a transaction based on custom logic. It's especially useful
- * in scenarios where transactional state or conditions need to be externally determined.
- *
- * @example
- * const t = withTransactionControlled(async (userId) => {
- *   await useTransactionEffect(async () => {
- *     await db.users.updateById(userId, { premium: true });
- *
- *     return () => db.users.updateById(userId, { premium: false })
- *   });
- *
- *   const user = await db.users.findById(userId);
- *
- *   return user;
- * });
- *
- *
- * await t.run();
- *
- * // Remove premium when no subscriptions
- * if (t.result.activeSubscriptions > 0) {
- *   await t.commit();
- * } else {
- *   await t.rollback();
- * }
- *
- * @group Main
- */
-declare function withTransactionControlled<T, K = any, Args extends Array<any> = any[]>(fn: (this: K, ...args: Args) => T): TransactionControlled<Awaited<T>, K, Args>;
-
-export { type OnMongoSessionCommittedResult, type TransactionControlled, type UseTransactionEffectOptions, type WithMongoTransactionOptions, type WithTransactionOptions, onCommitted, onMongoSessionCommitted, onRollback, useMongoSession, useTransactionEffect, withMongoTransaction, withTransaction, withTransactionControlled };