add finally (#14)

* ✨ add finally callback to Try class

- Implemented `finally` method to allow users to register a callback that runs after the wrapped function finishes, regardless of success or failure.
- Updated README to include usage example for the new feature.
- Added tests to verify the execution of the `finally` callback on both successful and erroneous function executions.

Signed-off-by: w01fgang <sumin@unix-center.ru>

* 🔖 bump version to 0.0.7

Signed-off-by: w01fgang <sumin@unix-center.ru>

* Remove unused `finallyExecuted` property from Try class to streamline error handling logic.

Signed-off-by: w01fgang <sumin@unix-center.ru>

* Refactor test for Try class to use `unwrap` method and validate error handling

- Updated the test case to utilize the `unwrap` method instead of `value`.
- Adjusted the expectation to check for rejection with the correct error message.

Signed-off-by: w01fgang <sumin@unix-center.ru>

---------

Signed-off-by: w01fgang <sumin@unix-center.ru>

Author: w01fgang

README.md

@@ -110,6 +110,9 @@ const user = await new Try(fetchUser, userId)
   .report('Failed to fetch user')
   .breadcrumbs(['userId'])
   .default(null)
+  .finally(() => {
+    console.log('Completed fetching user')
+  })
   .value();
 
 // Pattern 2: Check errors explicitly

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@power-rent/try-catch",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "A TypeScript utility for simplified async error handling with Sentry integration",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",

src/__tests__/Try.test.ts

@@ -228,4 +228,26 @@ describe('Try', () => {
     expect(() => result.ok).not.toThrow(TypeError);
     expect(Sentry.captureException).not.toHaveBeenCalled();
   });
+
+  it('should execute finally callback on success', async () => {
+    const params = { parameterKey: 'alpha' };
+    const finallySpy = vi.fn();
+
+    await new Try(successfulFunction, params)
+      .finally(finallySpy)
+      .unwrap();
+
+    expect(finallySpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('should execute finally callback on error', async () => {
+    const params = { parameterKey: 'alpha' };
+    const finallySpy = vi.fn();
+
+    const exec = new Try(throwingFunction, params)
+      .finally(finallySpy)
+      .unwrap();
+    await expect(exec).rejects.toThrow('boom');
+    expect(finallySpy).toHaveBeenCalledTimes(1);
+  });
 });

src/nextjs/index.ts

@@ -8,6 +8,11 @@ interface TryConfig<TArg extends Record<string, any>> {
   readonly breadcrumbKeys?: readonly (keyof TArg)[];
   readonly tags: Readonly<Record<string, string>>;
   readonly defaultValue?: unknown;
+  /**
+   * Callback that will always run after the wrapped function finishes
+   * executing, regardless of success or failure. Similar to `Promise.prototype.finally`.
+   */
+  readonly finallyCallback?: () => void;
 }
 
 /**
@@ -180,6 +185,23 @@ export class Try<T, TArgs extends readonly Record<string, any>[] = Record<string
     });
   }
 
+  /**
+   * Register a callback that will run after the wrapped function finishes
+   * executing (successfully or with an error). The callback runs exactly once
+   * per {@link Try} instance, mirroring the behaviour of
+   * `Promise.prototype.finally`.
+   *
+   * The callback is executed **after** the underlying function settles but
+   * before any error is re-thrown from {@link unwrap}. It is always executed
+   * asynchronously in the same tick as the function resolution.
+   *
+   * @param callback A function to invoke once the wrapped operation settles.
+   * @returns The `Try` instance for method chaining.
+   */
+  finally(callback: () => void): Try<T, TArgs> {
+    return this.setConfig({ finallyCallback: callback });
+  }
+
   /**
    * Configure a default value to return when an error occurs.
    * This default value will be returned by `.value()` method if the function execution fails.
@@ -352,14 +374,21 @@ export class Try<T, TArgs extends readonly Record<string, any>[] = Record<string
 
     try {
       const value = await this.fn(...this.args);
-      return { success: true, value };
+      this.result = { success: true, value };
     } catch (e) {
       console.error(e);
       const error = e as Error;
-      return { success: false, error };
+      this.result = { success: false, error };
     } finally {
       this.state = 'executed';
+      try {
+        this.config.finallyCallback?.();
+      } catch (err) {
+        console.error('Error in finally callback', err);
+      }
     }
+
+    return this.result;
   }
 
   /**