maybe-result - Safe function return handling in Typescript and Javascript

Deciding when a function should return undefined, throw an Error, or return some other indicator that
"something isn't right" is tough. We don't always know how users _calling_ our function
will use it, and we want to be clear, clean, and safe.

This library provides two approaches for wrapping function results:

- Maybe for when something may or may not exist. (Jump to API)
- Result for when you might have an error, but want to let the caller decide how to handle it. (Jump to API)

Jump to Learn More section - Jump to Origins and Alternatives section

Maybe

In many languages, we have concepts of exceptions and null values.
(JavaScript has both null and undefined. Ugh!)

Often a function will need to indicate when a value _maybe_ exists, or it does not.
In JavaScript, the "does not" is usually returned as undefined or null, but sometimes
a function will _throw_ an Error type instead. Thus, the developer needs to figure out
how that particular function behaves and adapt to that if they want to handle
the missing value.

Finally, throwing Errors in TypeScript can be expensive, as a stack trace must be
generated and cross-referenced to the .js.map files. These stack traces to your
TypeScript source are immensely useful for tracing actual errors, but they are wasted
processing when ignored.

The Maybe type makes this cleaner. Elm was an early language that defined this.
Rust has an Option type, which is the same concept.

A Maybe is a wrapper object that contains either "some" value, or "none".
A function can thus return a Maybe, and the client can then _choose_ how to handle
the possibly missing value. The caller can explicitly check for isValue or
isNone, or can simply unwrap the Maybe and let it throw an error if "none".
It is now the caller's choice. There are many other helper functions too, such as
to unwrap with a default value to return in place of throwing if isNone.

In JavaScript we like to throw Error types, but in other languages we call these _exceptions_.
Throwing is still good for _exceptional_ cases. Maybe is for "normal" control flows.

Maybe is not only for function return values. It may be used elsewhere where you want a type-safe
and immutable alternative to undefined and null.

Here's a nice introduction to the concept:
Implementing a Maybe Pattern using a TypeScript Type Guard

$3

You might define a data repository class (access to a data store) like this:

``ts
class WidgetRepository {
get(widgetID: string): Promise {
// implementation ...
}
}
`

If the Widget isn't found, you throw a NotFoundError. All is well until you start _expecting_
a Widget not to be found. That becomes valid flow, so you find yourself writing this a lot:

`ts
let widget: Widget | undefined;
try {
widget = await widgetRepo.get(widgetID);
} catch (error) {
if (!(error instanceof NotFoundError)) {
throw error;
}
}

if (widget) {
/ ... /
}
`

You may be willing to do that once... but not more. So you first try to change the repository:

`ts
class WidgetRepository {
get(widgetID: string): Promise {
// implementation ...
}
}
`

Now it returns undefined instead of throwing. Oh, but what a hassle - now you have to _check_ for
undefined _every time_ you call the function! So instead, you define _two_ functions:

`ts
class WidgetRepository {
getOrThrow(widgetID: string): Promise {
// implementation ...
}
getIfFound(widgetID: string): Promise {
// implementation ...
}
}
`

That makes it easier. It works. You just have to write _two_ functions every time you write a get function. 🙄

OR... use Maybe 🎉

`ts
class WidgetRepository {
async get(widgetID: string): PromiseMaybe {
// implementation ...
}
}

// One place elsewhere where you want to throw if not found
const widget = Maybe.unwrap(await widgetRepo.get(widgetID));

// Another place elsewhere where you want to handle the mising lookup
const widget = Maybe.unwrapOrNull(await widgetRepo.get(widgetID));
if (widget) {
// do work
} else {
// do other work
}

// Someplace where you have a default
const widget = (await widgetRepo.get(widgetID)).unwrapOr(defaultWidget);
`

$3

There are many functions, both on the Maybe instance and as static helper functions in
the Maybe namespace:

`ts
interface Maybe extends Iterable ? U : never> {
/* true when this has "some" value. /
readonly isValue: boolean;
/* false when this is "none". /
readonly isNone: boolean;
/**
* Helper function if you know you have a Maybe and T is iterable.
* @returns value's iterator or an iterator that is immediately done, if value is not iterable.
*/
[Symbol.iterator](): Iterator ? U : never>;
/**
* Returns the "some" value, or throw.
* Use if you want a "none" value to throw an error.
*
* @returns the "some" value
* @throws NoneError when "none".
*/
unwrap(): T;
/**
* Unwrap the "some" value and return it,
* or when "none" returns the given alternative instead.
*
* @param altValue value to return when "none"
* @returns the "some" value, or altValue when "none"
*/
unwrapOr(altValue: T2): T | T2;
/**
* Unwrap the "some" value and return it,
* or-else when "none" returns the given alternative lazy callback instead.
*
* @param altValueFn lazy callback result to return when "none"
* @returns the "some" value, or the altValueFn result when "none"
*/
unwrapOrElse(altValueFn: () => T2): T | T2;
/**
* Returns the "some" value or null instead of throwing an error if "none".
*
* @returns the "some" value, or null when "none"
*/
unwrapOrNull(): T | null;
/**
* Returns the "some" value, if exists. Throws when "none".
*
* @param altError (optional) Error, message for an Error, or callback that produces an Error to throw when "none"
* @returns the "some" value
* @throws the altError or NoneError when "none".
*/
unwrapOrThrow(altError?: string | Error | (() => E)): T;
/**
* Assert that this Maybe has "some" value.
* Throw with provided message (or a default) when not "some" value.
* Generally you should use an unwrap function instead, but this is useful for unit testing.
*
* @param message the message to throw when this is "none"
* @returns the "some" value
* @throws new NoneError(message) when is "none"
*/
assertIsValue(message?: string): T;
/**
* Assert that this Maybe is "none".
* Throw with provided message (or a default) when not "none".
* Generally, prefer to handle the "none" case explicitly or with unwrapOr or unwrapOrNull.
* This may be useful for unit testing.
*
* @param message the message to throw when "some".
* @returns the "none"
* @throws new Error(msg,value) when "some"
*/
assertIsNone(message?: string): Maybe.None;
/**
* Perform boolean "or" operation.
*
* Returns this when "some", otherwise returns other.
*
* @param other the right-hand operator
* @returns "none" or other.
*/
or(other: Maybe): Maybe | Maybe;
/**
* Perform a lazy boolean "or" operation.
*
* Returns this when "some", or-else returns the otherFn callback result.
*
* @param otherFn the right-hand operator
* @returns "none" or otherFn result.
*/
orElse(otherFn: () => Maybe): Maybe | Maybe;
/**
* Perform boolean "and" operation.
*
* Returns "none" if this is "none", otherwise returns other.
*
* @param other the right-hand operator
* @returns "none" or other.
*/
and(other: Maybe): Maybe | Maybe.None;
/**
* Perform a lazy boolean "and" operation by
* chaining a "some" value into a mapper function.
*
* Calls mapperFn when "some" value,
* otherwise returns itself as still "none" without calling mapperFn.
*
* @param mapperFn function to map this value to another Maybe. (See .map to map values instead.)
* @returns mapped "some" value, or this when "none".
*/
andThen(mapperFn: (value: T) => Maybe): Maybe | Maybe.None;
/**
* Transform "some" value, when present.
*
* Maps an Maybe to Maybe by applying a function to the "some" value,
* leaving a "none" untouched.
*
* This function can be used to compose the Maybe of two functions.
*
* @param mapperFn function to map this value to a new value.
* (See .andThen to map to a new Maybe instead.)
* @returns a new Maybe with the mapped "some" value, or this when "none"
*/
map(mapperFn: (value: T) => U): Maybe;
/**
* Transform "some" value or use an alternative, resulting in a Maybe that is always "some" value.
*
* Maps a Maybe to Maybe by either converting T to U using mapperFn (in case
* of "some") or using the altValue value (in case of "none").
*
* If altValue is a result of a function call consider using mapOrElse instead, it will
* only evaluate the function when needed.
*
* @param mapperFn function to map this "some" value to a new value.
* @param altValue value to return when "none"
* @returns a new Maybe with the mapped "okay" value or the altValue value
*/
mapOr(mapperFn: (value: T) => U, altValue: U): MaybeValue;
/**
* Transform "some" value or-else lazy call an alternative, resulting in a Maybe that is always "some" value.

* Maps a Maybe to Maybe by either converting T to U using mapperFn (in case
* of "some") or using the altValueFn callback value (in case of "none").
*
* @param mapperFn function to map this "some" value to a new value.
* @param altValueFn callback result to return when "none"
* @returns a new Maybe with the mapped "okay" value or the alternative result value
*/
mapOrElse(mapperFn: (value: T) => U, altValueFn: () => U): MaybeValue;
/**
* Filters "some" value to "none" if predicateFn returns false.
*
* When "some", calls the predicateFn and if it returns false returns "none".
* When "none", returns this unchanged and predicate not called.
*
* @param predicateFn filter function indicating whether to keep (true) the value
* @returns this Maybe or Maybe.None.
*/
filter(predicateFn: (value: T) => boolean): Maybe;
/**
* Convert a Maybe to a Result, with the provided Error value
* to use when this is "none".
*
* @param error to use when "none"; defaults to a NoneError
* @return a Result with this "some" as the "okay" value, or error as the "error".
*/
toResult(error?: E): Result;
/**
* This Maybe as a loggable string.
* @returns string describing this Maybe
*/
toString(): string;
}

/* A Promise to a Maybe /
type PromiseMaybe = Promise>;

declare namespace Maybe {
/* Generic None result of a Maybe /
const None: MaybeNone;
type None = MaybeNone;

/* A Successful Maybe result that just doesn't have any value /
const Empty: MaybeValue;
type Empty = MaybeValue;

/* Factory create a Maybe with "some" value /
const withValue: (value: T) => MaybeValue;
/**
* Factory create a Maybe of "none" with context of "what" was not found.
* @param what string(s) describing what wasn't found
*/
const notFound: (...what: string[]) => MaybeNotFound;
/**
* Factory create a Maybe with a "none" result. You can use the Maybe.None singleton directly;
* this just provides synchronicity with the other factory functions.
*/
const asNone: () => MaybeNone;
/**
* Factory create a Maybe with success but no actual value (void).
* You can use the Empty singleton directly instead;
* this just provides synchronicity with the other factory functions.
*/
const empty: () => MaybeValue;
/**
* Helper to wrap a value as a Maybe.
*
* @param value a value, undefined, or null
* @return a Maybe: "none" if undefined or null, otherwise "some" value.
*/
const wrap: (
value: T | undefined | null,
) => MaybeNone | MaybeValue>;
/**
* Returns the value contained in maybe, or throws if "none".
* Same as maybe.unwrap(), but more readable when maybe is returned from an async
* function: Maybe.unwrap(await repository.get(id))
*
* @param maybe to unwrap
* @return the "some" value
* @throws NoneError if maybe is "none".
*/
const unwrap: (maybe: Maybe) => T;
/**
* Returns the "some" value in maybe, or null if "none".
* Same as maybe.unwrapOrNull(), but more readable when maybe is returned from an
* async function: Maybe.unwrapOrNull(await repository.get(id))
*
* @param maybe to unwrap
* @return the "some" value or null
*/
const unwrapOrNull: (maybe: Maybe) => T | null;
/**
* Parse a set of maybes, returning an array of all "some" values.
* Short circuits with the first "none" found, if any
*
* @param maybes list to check
* @return array of "some" values or Maybe.None.
*/
function allOrNone[]>(
...maybes: T
): Maybe>;
/**
* Parse a set of maybes, returning an array of all "some" values,
* filtering out any "none"s found, if any.
*
* @param maybes list to check
* @return array of some" values
*/
function allValues(...maybes: Maybe[]): T[];
/**
* Parse a set of maybes, short-circuits when an input value is "some".
* If no "some" is found, returns a "none".
* @param maybes list to check
* @return the first "some" value given, or otherwise "none".
*/
function any[]>(
...maybes: T
): Maybe[number]>;
/**
* Type-guard to identify and narrow a Maybe
*/
function isMaybe(value: unknown): value is Maybe;
}

/**
* A special form of Maybe's "none" value with additional context.
*/
declare class MaybeNotFound extends MaybeNone {
private readonly what;
/**
* Construct a Maybe "none" that indicates a "what" wasn't found.
* @param what texts describing "what" wasn't found.
*/
constructor(what: string[]);
unwrap(): never;
}

/* HTTP-friendly Error that is thrown when unwrapping a MaybeNotFound /
declare class NotFoundError extends Error {
/* Property use by some HTTP servers /
readonly status: 404;
/* Property use by some HTTP servers /
readonly statusCode: 404;
constructor(msg: string);
}
`

Result

Unlike Maybe, which simply has some value or no value and doesn't want to return undefined,
Result is for when you have an error and don't want to throw.
Similar to Maybe, this is all about the function giving the caller the _choice_ of
how to handle a situation - in this case an _exceptional_ situation.

This is modeled off of the Rust Result type, but made to pair cleanly with this
implementation of Maybe.

$3

Expanding on the previous example of a WidgetRepository,
let's add a function in the repository that creates a new widget.
A create function should error out if the assumption that the
widget doesn't yet exist is false.

`ts
class WidgetRepository {
async create(
widget: CreatableWidget,
): Promise> {
try {
// implementation ...
return Result.okay(newWidget);
} catch (err) {
return Result.error(err);
}
}
}

/*
* Elsewhere in the create-widget use-case...
*/
const createResult = await widgetRepo.create(creatableWidget);

if (createResult.isOkay) {
return createResult.value;
} else {
// Throw more end-user aligned error instead of the database error
throw new HttpBadRequest("Widget already exists");
}

/*
* Or more simply...
*/
const createResult = await widgetRepo.create(creatableWidget);
return createResult.unwrapOrThrow(new HttpBadRequest("Widget already exists"));

/*
* Or if you just want the behavior of if Result wasn't used, just unwrap it
* and any contained error will throw.
*/
return (await widgetRepo.create(creatableWidget)).unwrap();
// or slightly more readable:
return Result.unwrap(await widgetRepo.create(creatableWidget));
// or convert to a Maybe, so that Maybe.None is returned in place of the error
return (await widgetRepo.create(creatableWidget)).toMaybe();
`

$3

There are many functions, both on the Result instance and as static helper functions in
the Result namespace:

`ts
interface Result
extends Iterable ? U : never> {
/* true when this contains an "okay" value /
readonly isOkay: boolean;
/* true when this contains an "error" value /
readonly isError: boolean;
/**
* Helper function if you know you have a Result and T is iterable
* @returns iterator over the okay value
*/
[Symbol.iterator](): Iterator ? U : never>;
/**
* Unwrap the result's "okay" value and return it.
* When "error", throws the value instead.
* Generally, prefer to handle the error case explicitly or with unwrapOr or unwrapOrNull.
*
* @returns the "okay" value
* @throws the "error" value
*/
unwrap(): T;
/**
* Unwrap the result's "okay" value and return it,
* or when "error", returns given alternative instead.
*
* @param altValue value or callback result to return when "error"
* @returns the "okay" value or the altValue.
*/
unwrapOr(altValue: T2): T | T2;
/**
* Unwrap the result's "okay" value and return it,
* or-else when "error" calls alternative lazy callback and returns that value.
*
* @param altValueFn value or callback result to return when "error"
* @returns the "okay" value or the altValueFn result when "error".
*/
unwrapOrElse(altValueFn: (error: E) => T2): T | T2;
/**
* Unwrap the result's "okay" value and return it.
* When "error", returns null.
*
* @returns the "okay" value or null
*/
unwrapOrNull(): T | null;
/**
* Unwrap the result's "okay" value and return it.
* otherwise if an altError is provided, it is thrown,
* otherwise the "error" value of this result is thrown.
*
* When no altError parameter is provided, this is the same as .unwrap()
* but a bit more descriptive.
*
* @param altError (optional) Error, message for an Error, or callback that produces an Error to throw when "error"
* @returns "okay" value
* @throws altError or the result "error" value
*/
unwrapOrThrow(
altError?: string | Error | ((error: E) => E2),
): T;
/**
* Assert that this Result is "okay".
* Throw with provided message (or a default) when not "okay".
* Generally you should use an unwrap function instead, but this is useful for unit testing.
*
* @param message the message to throw when this is an "error"
* @returns the value when this is "okay"
* @throws new Error(message,value) when is "error"
*/
assertIsOkay(message?: string): T;
/**
* Assert that this Result is "error".
* Throw with provided message (or a default) when not "error".
* Generally, prefer to handle the "error" case explicitly or with unwrapOr or unwrapOrNull.
* This may be useful for unit testing.
*
* @param message the message to throw when "okay".
* @returns the value when "error"
* @throws new Error(msg,value) when "okay"
*/
assertIsError(message?: string): E;
/**
* Perform boolean "or" operation.
*
* Returns this when "okay", otherwise returns other.
*
* @param other the right-hand operator
* @returns this "okay" or other.
*/
or(other: Result): OkayResult | Result;
/**
* Perform a lazy boolean "or" operation.
*
* Returns this when "okay", or-else lazy-cals otherFn and returns its result.
*
* @param otherFn the right-hand operator
* @returns this "okay" or otherFn result.
*/
orElse(otherFn: (error: E) => OkayResult): OkayResult;
orElse(otherFn: (error: E) => ErrorResult): Result;
orElse(otherFn: (error: E) => Result): Result;
/**
* Perform boolean "and" operation.
*
* When "error", returns this "error",
* otherwise returns other.
*
* @param other the right-hand operator
* @returns this "error" or other.
*/
and(other: Result): ErrorResult | Result;
/**
* Perform a lazy boolean "and" operation by
* chaining the "okay" value into a mapper function.
*
* Lazy calls mapperFn if the result "okay",
* otherwise returns this "error" Result as-is without calling mapperFn.
*
* This function can be used for control flow based on Result values.
*
* @param mapperFn function to map this value to another Result. (See .map to map values instead.)
* @returns mapped "okay" Result or this when "error"
*/
andThen(mapperFn: (value: T) => OkayResult): Result;
andThen(mapperFn: (value: T) => ErrorResult): Result;
andThen(mapperFn: (value: T) => Result): Result;
/**
* Transform "okay" value, when present.
*
* Maps a Result to Result by applying a function to the "okay" value,
* leaving an "error" value unchanged.
*
* This function can be used to compose the results of two functions.
*
* @param mapperFn function to map this value to a new value.
* (See .andThen to map to a new Result instead.)
* @returns a new Result with the mapped "okay" value, or this when "error"
*/
map(mapperFn: (value: T) => U): Result;
/**
* Transform "okay" value or use an alternative, resulting in a Result that is always "okay".
*
* Maps a Result to Result when "okay" by applying a function.
* When "error", returns given alternative instead.
*
* @param mapperFn function to map this value to a new value.
* @param altValue value to return when "error"
* @returns a new Result with the mapped "okay" value or the altValue value
*/
mapOr(mapperFn: (value: T) => U, altValue: U): OkayResult;
/**
* Transform "okay" value or-else lazy call an alternative, resulting in a Result that is always "okay".
*
* Maps a Result to Result when "okay" by applying a function.
* When "error", returns value from alternative callback instead.
*
* @param mapperFn function to map this value to a new value.
* @param altValueFn callback result to return when "error"
* @returns a new Result with the mapped "okay" value or the alternative value
*/
mapOrElse(
mapperFn: (value: T) => U,
altValueFn: (error: E) => U,
): OkayResult;
/**
* Transform "error" value, when present.
*
* Maps a Result to Result by applying a function to an "error" value,
* leaving an "okay" value unchanged.
*
* This function can be used to pass through a successful result while handling an error.
*
* @param mapperFn function to map this "error" value to a new error
* @returns a new Result with the mapped error, or this when "okay"
*/
mapError(mapperFn: (error: E) => F): Result;
/**
* Converts this Result to Maybe,
* discarding any error details in place of a simple Maybe.None.
* @returns the "okay" value as a Maybe, or Maybe.None when "error"
*/
toMaybe(): Maybe;
/**
* This Result as a loggable string.
* @returns string describing this Result
*/
toString(): string;
}

/* A Promise to a Result /
type PromiseResult = Promise>;

declare namespace Result {
/* A reusable okay result with no (undefined) value /
const OkayVoid: OkayResult;
/* Factory to create an "okay" result /
const okay: (value: T) => OkayResult;
/* Factory to create an "okay" result with no (undefined) value /
const okayVoid: () => OkayResult;
/* Factory to create an "error" result /
const error: (error: E) => ErrorResult;

/**
* Parse a set of Results, returning an array of all "okay" values.
* Short circuits to return the first "error" found, if any.
*
* @param results array of results; possibly a mix of "okay"s and "error"s
* @return a single Result with the first "error" or an "okay" value as an array of all the "okay" values.
*/
function all[]>(
...results: T
): Result, ErrorResultTypes[number]>;
/**
* Parse a set of Results and returns the first input value that "okay".
* If no "okay" is found, returns an "error" result with the error values.
*
* @param results array of results; possibly a mix of "okay"s and "error"s
* @return a single Result with the first "okay" or an "error" value as an array of all the "error" values.
*/
function any[]>(
...results: T
): Result[number], ErrorResultTypes>;
/**
* Returns the value contained in result, or throws the "error" in result.
*
* Same as result.unwrap(), but more reads nicer when Result is returned from an async
* function: Result.unwrap(await repository.create(widget))
*
* @param result to unwrap
* @throws if the result is "error"
*/
const unwrap: (result: Result) => T;
/**
* Wrap an operation that may throw and capture it into a Result.
*
* @param opFn the operation function
* @return a Result with the function output - either "okay" or a caught "error".
*/
function wrap(opFn: () => T): Result;
/**
* Wrap an operation that may throw and capture it into a Result.
*
* @param opFn the operation function
* @return a Result with the function output - either "okay" or a caught "error".
*/
function wrapAsync(
opFn: () => Promise,
): PromiseResult;
/**
* Type guard to identify and narrow a Result
*/
function isResult(val: unknown): val is Result;
}
`

Learn More

- View the Generated API Documentation
- Read full-coverage examples in the Maybe unit test suite and Result unit test suite.
- Functions are named per some foundational concepts:
- wrap wraps up a value
- unwrap means to extract the value
- or performs a boolean _or_ operation between two instances
- orElse lazily gets the second operand for an _or_ operation via a callback function _only_ if needed
- and performs a boolean _and_ operation between two instances
- andThen lazily gets the second operand for an _and_ operation via a callback function _only_ if needed
- map` functions transform the value to return a new instance (immutably)

Origin and Alternatives

This implementation is based on ts-results,
which adheres to the Rust API.
This library has more natual word choices, Promise support, additional functions, and other enhancements.

There are many other libraries that do this same thing - just
search NPM for "maybe".
It is up to you to decide which option is best for your project.

_The goal of this library is to be featureful, safe, and easy to understand without
a study of functional programming._