Merge pull request #1 from inaiat/feat/async-finally

Feat/async finally

BUILD_SHA

@@ -1 +1 @@
-3eebd1d3875783ff1f972f8bfac9d810a18d479e
+422f3f1317b2cc9d0a82c587968241f846137894

README.md

@@ -49,18 +49,21 @@ For asynchronous tasks, `resultar` offers a `ResultAsync` class which wraps a `P
     - [`errAsync`](#errasync)
     - [`ResultAsync.fromPromise` (static class method)](#resultasyncfrompromise-static-class-method)
     - [`ResultAsync.fromSafePromise` (static class method)](#resultasyncfromsafepromise-static-class-method)
+    - [`ResultAsync.fromThrowable` (static class method)](#resultasyncfromthrowable-static-class-method)
     - [`ResultAsync.map` (method)](#resultasyncmap-method)
     - [`ResultAsync.mapErr` (method)](#resultasyncmaperr-method)
     - [`ResultAsync.unwrapOr` (method)](#resultasyncunwrapor-method)
     - [`ResultAsync.andThen` (method)](#resultasyncandthen-method)
     - [`ResultAsync.orElse` (method)](#resultasyncorelse-method)
-    - [`Result.tap` (method)](#resultasynctap-method)
+    - [`ResultAsync.tap` (method)](#resultasynctap-method)
+    - [`ResultAsync.finally` (method)](#resultasyncfinally-method)
     - [`ResultAsync.match` (method)](#resultasyncmatch-method)
     - [`ResultAsync.combine` (static class method)](#resultasynccombine-static-class-method)
     - [`ResultAsync.combineWithAllErrors` (static class method)](#resultasynccombinewithallerrors-static-class-method)
     - [`ResultAsync.safeUnwrap()`](#resultasyncsafeunwrap)
   + [Utilities](#utilities)
     - [`fromThrowable`](#fromthrowable)
+    - [`fromThrowableAsync`](#fromthrowableasync)
     - [`fromPromise`](#frompromise)
     - [`fromSafePromise`](#fromsafepromise)
     - [`safeTry`](#safetry)
@@ -712,6 +715,44 @@ myResult.isErr() // true
 
 ---
 
+#### `ResultAsync.fromThrowable` (static class method)
+
+Similar to [Result.fromThrowable](#resultfromthrowable-static-class-method), but for functions that return a `Promise`.
+
+**Example**:
+
+```typescript
+import { ResultAsync } from 'neverthrow'
+import { insertIntoDb } from 'imaginary-database'
+// insertIntoDb(user: User): Promise<User>
+
+const insertUser = ResultAsync.fromThrowable(insertIntoDb, () => new Error('Database error'))
+// `res` has a type of (user: User) => ResultAsync<User, Error>
+```
+
+Note that this can be safer than using [ResultAsync.fromPromise](#resultasyncfrompromise-static-class-method) with
+the result of a function call, because not all functions that return a `Promise` are `async`, and thus they can throw
+errors synchronously rather than returning a rejected `Promise`. For example:
+
+```typescript
+import { readFile } from 'node:fs/promises'
+import { fromThrowableAsync } from 'resultar'
+
+const safeFileReader = fromThrowableAsync(
+  async (file: string) => readFile(file),
+  e => new Error('Oops: '.concat(String(e))),
+)
+const value = await safeFileReader('foo.txt')
+
+if (value.isOk()) {
+  console.log(value.value.toString())
+}
+```
+
+[⬆️  Back to top](#toc)
+
+---
+
 #### `ResultAsync.fromPromise` (static class method)
 
 Transforms a `PromiseLike<T>` (that may throw) into a `ResultAsync<T, E>`.
@@ -981,7 +1022,7 @@ This method is useful for performing actions that do not modify the `Result` its
 **Signature:**
 ```typescript
 class ResultAsync<T, E> {
-  tap(f: (t: T) => void): Result<T, E> {..}
+  tap(f: (t: T) => void | Promise<void>): ResultAsync<T, E> {
 }
 ```
 
@@ -995,9 +1036,9 @@ const mapped = okVal.tap((value) => {
 // mapped.value === 'foo'
 ```
 [⬆️  Back to top](#toc)
----
 
 ---
+
 #### `Result.finally` (method)
 Executes a cleanup function wether the is ok or error. This method is usefull to cleanup resources.
 **Signature:**
@@ -1021,6 +1062,7 @@ if (resul.isOk()) {
 
 ```
 [⬆️  Back to top](#toc)
+
 ---
 
 #### `ResultAsync.orElse` (method)
@@ -1052,12 +1094,44 @@ class ResultAsync<T, E> {
 }
 ```
 
+
+
 **Example:**
 See [`Result.tap` (method)](#resulttap-method)
 
+
+[⬆️  Back to top](#toc)
+
+---
+
+#### `ResultAsync.finally` (method)
+Executes a cleanup function wether the is ok or error. This method is usefull to cleanup resources for async operations.
+**Signature:**
+```typescript
+class ResultAsync<T, E> {
+  finally(f: (value: T, error: E) => void): DisposableResultAsync<T, E> {...}
+}
+```
+
+**Example:**
+```typescript
+const fileHandle = await fs.open('foo.txt', 'w')
+
+const result
+  = await fromPromise(fileHandle.write('A new line of text'), String)
+    .finally(async () => {
+      console.info('Closing file handle')
+      await fileHandle.close()
+    })
+
+if (result.isOk()) {
+  console.log(result.value) // == 'A new line of text'
+}
+
 ```
 
 [⬆️  Back to top](#toc)
+
 ---
 
 #### `ResultAsync.match` (method)
@@ -1206,6 +1280,17 @@ Please find documentation at [Result.fromThrowable](#resultfromthrowable-static-
 
 [⬆️  Back to top](#toc)
 
+---
+
+#### `fromThrowableAsync`
+
+Top level export of `ResultAsync.fromThrowable`.
+Please find documentation at [ResultAsync.fromThrowable](#resultasyncfromthrowable-static-class-method)
+
+[⬆️  Back to top](#toc)
+
+---
+
 #### `fromPromise`
 
 Top level export of `ResultAsync.fromPromise`.

jsr.json

@@ -1,5 +1,5 @@
 {
     "name": "@inaiat/resultar",
-    "version": "0.9.0",
+    "version": "1.0.0",
     "exports": "./src/index.ts"
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "resultar",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "Result pattern for typescript",
   "type": "module",
   "packageManager": "[email protected]",
@@ -61,7 +61,7 @@
     "typedoc": "^0.25.13",
     "typedoc-github-wiki-theme": "2.0.0-next.8",
     "typedoc-plugin-markdown": "4.0.0-next.55",
-    "typescript": "5.4.4",
+    "typescript": "5.4.5",
     "xo": "0.58.0"
   },
   "tsup": {