Inline function docs

This release adds in-line docs for the Result variants. Now, when using a LSP-supported editor, you'll have docs as you hover a Result method.

Thanks to @Liam-Tait for the contribution!

✨ New `combineWithAllErrors` utility function ✨

neverthrow now exposes a combineWithAllErrors function that is the "lazy" (for lack of a better word) equivalent of combine.

This means that rather than short-circuiting upon finding the first Err value, combineWithAllErrors will continue consuming the Result / ResultAsync list until the end and return a list containing all the Err values that it found.

Thanks to @tobloef for the contribution 🚀

Bugfix: Do not unwrap / destructure array contents into combine list.

This release patches a bug where calling combine on a Result<T, E>[] or ResultAsync<T, E>[] and the T values were lists, then those lists would get concatenated into a single output list:

Example:

import { combine, ok } from 'neverthrow'

combine([
  ok([ 1, 2, 3 ]),
  ok([ 'hello', 'world ])
])

// before v4.1.1, the above would incorrectly return [ 1, 2, 3, 'hello', 'world' ]
// 
// actual output should be [ [ 1,2,3 ], [ 'hello', 'world' ] ] 

The fix of the bug can be found here:

a5e66a8

I decided to continue using Array.prototype.concat in spite of this subtlety because it does not mutate references (unlike Array.prototype.push).

All `andThen` variations now allow you to return distinct error types! 🔥 (now out of beta)

This release:

• Releases https://github.com/supermacro/neverthrow/releases/tag/v4.1.0-beta.0 out of beta

  • This functionality is now part of the @default npm tag, meaning you can just run npm install neverthrow to get this functionality

• Re-exporting fromThrowable, fromPromise and fromSafePromise (PR here)

  • Thanks to @mariosant for the contribution

All `andThen` variations now allow you to return distinct error types! 🔥

I finally caved and have gone ahead and "loosened" the restriction that all andThen variations (Result.andThen, Result.asyncAndThen, and ResultAsync.andThen) had before. The restriction prevented the callback inside all andThen variations from returning a distinct / different error type.

See #30 for more context on the "problem" that this addresses.

This release is downloadable behind a beta tag on npm.

> npm install neverthrow@beta

Docs have been updated to reflect this change.

Here's an example diff.

-   andThen<U>(f: (t: T) => Result<U, E>): Result<U, E> {
+   andThen<U, F>(f: (t: T) => Result<U, F>): Result<U, E | F> {

And here is the full diff:

8f87ef0

Fix invalid overload type for combine

The combine overload for ResultAsync lists was incorrect. Previously the overload stated that the return type of a combine invocation with a list of ResultAsyncs was a Result.

This patch fixes this error and now combine's type on ResultAsyncs correctly specifies that the return value will be a ResultAsync.

✨ New `fromSafePromise` method on ResultAsync✨

Breaking Change: This release changes the API of the original ResultAsync.fromPromise method to require a error handler callback.

In addition, there is now a new static class method called ResultAsync.fromSafePromise that does not take a error handler callback under the assumption that you are calling this method with a promise that does not ever throw.

✨ `combine` now works on heterogeneous lists ✨ + new `orElse` method! ✨

Combine v2

The combine utility function now lets you combine lists containing different kinds of results! The recommended way that you use combine when calling it with a heterogeneous list is to either declare a tuple type that describes each element in the list, or declare the list as const.

New orElse method

The orElse method (implemented on both Result and ResultAsync) allows for error-recovery where you want to potentially convert an E into T.

Improved error messages during tests & optional stack trace generation

This release swaps out the usage of a native Error with a custom JS Object for the _unsafeUnwrap and _unsafeUnwrapErr methods. This means that stack traces will not be generated by default.

The aforementioned methods will not generate a stack trace because Jest's error messages become less helpful.

If for some reason you want to log stack traces (because you're using these methods in a non-test environment ... which would be considered .... unsafe) for thrown exceptions, you can call the above methods with the following config object as an argument:

_unsafeUnwrapErr({
  withStackTrace: true,
})

Make Result instances comparable

#214 changes the match method from being implemented as a instance property to being implemented as a method on the prototype chain.

Therefore all instances of Result share the same reference in their match method. This allows testing libraries like Jest to make appropriate object comparisons / diffs.

Thanks to @bluenote10 for the submission!