The Result and Option utilities are designed to improve error handling and value management in TypeScript by providing a more functional approach. These utilities help you avoid common pitfalls associated with exceptions and null/undefined values.
Pickle draws inspiration from the error-handling patterns of languages like Rust, where Result and Option types enable more expressive and type-safe management of errors and uncertain values. While this implementation is not a direct 1:1 port from any specific language—given that JavaScript and TypeScript lack native support for Result and Option types—the goal is to introduce some of their advantages into your codebase. Designed to integrate seamlessly with TypeScript's type system, this library enhances the developer experience by improving the handling of errors and uncertain values.
For asynchronous tasks, Pickle provides an AsyncResult helper that wraps a Promise<Result<T, E>>, offering the same level of expressivity and control as a standard Result<T, E>.
Result
Option
A Result represents either something good (T) or something not so good (E).
If we hold a value of type Result<T, E> we know it's either Ok<T> or
Err<E>.
import { Result } from '@bmrk/pickle';
function divide(x: number, by: number): Result<number, string> {
return by === 0 ? Result.err('Division by zero') : Result.ok(x / by);
}
const okResult = divide(100, 20);
const errResult = divide(100, 0);Returns the contained Ok or Err value.
const res: number | string = okResult.unsafe();
assert.equal(res, 5);
const res: number | string = errResult.unsafe();
assert.equal(res, 'Division by zero');Returns the contained Ok value or a provided fallback.
const res: number = okResult.okOr(0);
assert.equal(res, 5);
const res: number = errResult.okOr(0);
assert.equal(res, 0);Returns the contained Ok value or computes a fallback.
const res: number = okResult.okOrElse(() => 0);
assert.equal(res, 5);
const res: number = errResult.okOrElse(() => 0);
assert.equal(res, 0);Returns the contained Ok value or throws an error.
const res: number = okResult.okOrThrow((err) => err);
assert.equal(res, 5);
const res: number = errResult.okOrThrow((err) => err); // Throws "Division by zero"Returns the contained Err value or a provided fallback.
const res: string = okResult.errorOr('Succesfully divided');
assert.equal(res, 'Succesfully divided');
const res: string = errResult.errorOr('Succesfully divided');
assert.equal(res, 'Division by zero');Returns the contained Err value or computes a fallback.
const res: string = okResult.errorOrElse(() => 'Succesfully divided');
assert.equal(res, 'Succesfully divided');
const res: string = errResult.errorOrElse(() => 'Succesfully divided');
assert.equal(res, 'Division by zero');Returns the contained Err value or throws an error.
const res: string = okResult.errorOrThrow(() => 'Expected division by zero!'); // Throws "Expected division by zero!"
const res: string = errResult.errorOrThrow(() => 'Expected division by zero!');
assert.equal(res, 'Division by zero');Converts the Result into a tuple.
const [ok, err] = okResult.tuple();
assert.equal(ok, 5);
assert.equal(err, null);
const [ok, err] = errResult.tuple();
assert.equal(ok, null);
assert.equal(err, 'Division by zero');Returns the contained Ok value or the provided Result.
const res: Result<number, string> = okResult.or(Result.ok(0));
assert.equal(res.unsafe(), 5);
const res: Result<number, string> = errResult.or(Result.ok(0));
assert.equal(res.unsafe(), 0);Maps a Result<Ok, Err> to Result<NewOk, Err> by applying a function to a contained Ok value, leaving an Err value untouched.
const res: Result<number, string> = okResult.map((num) => num * 2);
assert.equal(res.unsafe(), 10);
const res: Result<number, string> = errResult.map((num) => num * 2);
assert.equal(res.unsafe(), 'Division by zero');Maps a Result<Ok, Err> to Result<NewOk, Err> by applying a function to a contained Ok value, flattening the Err value.
const res: Result<number, string> = okResult.flatMap((num) =>
Result.ok(num * 2)
);
assert.equal(res.unsafe(), 10);
const res: Result<number, string> = errResult.flatMap((num) =>
Result.ok(num * 2)
);
assert.equal(res.unsafe(), 'Division by zero');Maps a Result<Ok, Err> to Result<Ok, NewErr> by applying a function to a contained Err value, leaving an Ok value untouched.
const res: Result<number, string> = okResult.mapErr((err) => `Error: ${err}`);
assert.equal(res.unsafe(), 5);
const res: Result<number, string> = errResult.mapErr((err) => `Error: ${err}`);
assert.equal(res.unsafe(), 'Error: Division by zero');Maps a Result<Ok, Err> to Result<Ok, NewErr> by applying a function to a contained Err value, flattening the Ok value.
const res: Result<number, string> = okResult.flatMapErr((err) =>
Result.err(`Error: ${err}`)
);
assert.equal(res.unsafe(), 5);
const res: Result<number, string> = errResult.flatMapErr((err) =>
Result.err(`Error: ${err}`)
);
assert.equal(res.unsafe(), 'Error: Division by zero');Converts the Result into an Option.
const res: Option<number> = okResult.filter((num) => num === 5);
assert.equal(res.isSome, true);
assert.equal(res.unsafe(), 5);
const res: Option<number> = okResult.filter((num) => num === 10);
assert.equal(res.isNone, true);
assert.equal(res.unsafe(), null);Converts the Result into an Option.
const res: Option<number> = okResult.toOption();
assert.equal(res.isSome, true);
assert.equal(res.unsafe(), 5);
const res: Option<number> = errResult.toOption();
assert.equal(res.isNone, true);
assert.equal(res.unsafe(), null);Perform side-effects from the Ok value without changing the result.
const res = okResult.effect((num) => nitification(num)); // Fire and forget the notification function
assert.equal(res.unsafe(), 5);
const res = errResult.effect((num) => nitification(num)); // Does execute the notification function
assert.equal(res.unsafe(), 'Division by zero');Perform side-effects from the Err value without changing the result.
const res = okResult.effectErr((err) => notification(err)); // Does not execute the notification function
assert.equal(res.unsafe(), 5);
const res = errResult.effectErr((err) => notification(err)); // Fire and forget the notification function
assert.equal(res.unsafe(), 'Division by zero');Returns true if input is a Result.
const res: boolean = Result.is(okResult);
assert.equal(res, true);Returns a Result with an Ok value.
const res: Result<number, never> = Result.ok(5);
assert.equal(res.unsafe(), 5);Returns a Result with an Err value.
const res: Result<never, string> = Result.err('Error');
assert.equal(res.unsafe(), 'Error');Returns a Result with the result of a promise.
const res: Result<number, string> = await Result.safe(() => Promise.resolve(5));
assert.equal(res.unsafe(), 5);
const res: Result<number, string> = await Result.safe(() =>
Promise.reject('Error')
);
assert.equal(res.unsafe(), 'Error');Returns a Result with an array of Ok values or the first Err value.
const res: Result<[number, number], never> = Result.all(
Result.ok(1),
Result.ok(2)
);
assert.deepEqual(res.unsafe(), [1, 2]);
const res: Result<[number, never], string> = Result.all(
Result.ok(1),
Result.err('Error')
);
assert.equal(res.unsafe(), 'Error');Returns a Result with the first Ok value or an array of Err values.
const res: Result<number, [never, string]> = Result.any(
Result.ok(1),
Result.err('Error')
);
assert.equal(res.unsafe(), 1);
const res: Result<never, [string, string]> = Result.any(
Result.err('Error 1'),
Result.err('Error 2')
);
assert.deepEqual(res.unsafe(), ['Error 1', 'Error 2']);Returns a Result with an Ok value if value is truthy, otherwise an Err value.
const res: Result<number, string> = Result.from(5);
assert.equal(res.isOk, true);
const res: Result<number, string> = Result.from(0);
assert.equal(res.isErr, true);Returns a Result with an Ok value if value is not null, otherwise an Err value.
const res: Result<number, string> = Result.fromNullable(5);
assert.equal(res.isOk, true);
const res: Result<number, string> = Result.fromNullable(null);
assert.equal(res.isErr, true);Returns AsyncResult.
const res: Result<number, string> = await Result.async(
Promise.resolve(Result.ok(5))
).map((num) => num * 2);
assert.equal(res.unsafe(), 10);An Option represents either something, or nothing. If we hold a value of type Option<T>, we know it is either Some<T> or None.
import { Option } from '@bmrk/pickle';
function divide(x: number, by: number): Option<number> {
return by === 0 ? Option.none : Option.some(x / by);
}
const someOption = divide(100, 20);
const noneOption = divide(100, 0);Returns the contained Some or None value.
const res: number = someOption.unsafe();
assert.equal(res, 5);
const res: number = noneOption.unsafe();
assert.equal(res, null);Returns the contained Some value or a provided fallback.
const res: number = someOption.someOr(0);
assert.equal(res, 5);
const res: number = noneOption.someOr(0);
assert.equal(res, 0);Returns the contained Some value or computes a fallback.
const res: number = someOption.someOrElse(() => 0);
assert.equal(res, 5);
const res: number = noneOption.someOrElse(() => 0);
assert.equal(res, 0);Returns the contained Some value or throws an error.
const res: number = someOption.someOrThrow(() => 'Division by zero!');
assert.equal(res, 5);
const res: number = noneOption.someOrThrow(() => 'Division by zero!'); // Throws "Division by zero!"Returns the contained None value or a provided fallback.
const res: number = someOption.noneOr(0);
assert.equal(res, 0);
const res: number = noneOption.noneOr(0);
assert.equal(res, 0);Returns the contained None value or computes a fallback.
const res: number = someOption.noneOrElse(() => 0);
assert.equal(res, 0);
const res: number = noneOption.noneOrElse(() => 0);
assert.equal(res, 0);Returns the contained None value or throws an error.
const res: number = someOption.noneOrThrow(() => 'Expected division by zero!'); // Throws "Expected division by zero!"
const res: number = noneOption.noneOrThrow(() => 'Expected division by zero!');
assert.equal(res, 0);Returns the contained Some value or the provided Option.
const res: Option<number> = someOption.or(Option.some(0));
assert.equal(res.unsafe(), 5);
const res: Option<number> = noneOption.or(Option.some(0));
assert.equal(res.unsafe(), 0);Maps a Option<Some, None> to Option<NewSome, None> by applying a function to a contained Some value, leaving an None value untouched.
const res: Option<number> = someOption.map((num) => num * 2);
assert.equal(res.unsafe(), 10);
const res: Option<number> = noneOption.map((num) => num * 2);
assert.equal(res.unsafe(), null);Maps a Option<Some, None> to Option<NewSome, None> by applying a function to a contained Some value, flattening the None value.
const res: Option<number> = someOption.flatMap((num) => Option.some(num * 2));
assert.equal(res.unsafe(), 10);
const res: Option<number> = noneOption.flatMap((num) => Option.some(num * 2));
assert.equal(res.unsafe(), null);Returns an Option with a Some value or an None value.
const res: Option<number> = someOption.filter((num) => num === 5);
assert.equal(res.unsafe(), 5);
const res: Option<number> = someOption.filter((num) => num === 10);
assert.equal(res.unsafe(), null);Converts the Option into a Result.
const res: Result<number, string> = someOption.toResult('No value');
assert.equal(res.unsafe(), 5);
const res: Result<number, string> = noneOption.toResult('No value');
assert.equal(res.unsafe(), 'No value');Perform side-effects from the Some value without changing the option.
const res = someOption.effect((num) => notification(num)); // Fire and forget the notification function
assert.equal(res.unsafe(), 5);
const res = noneOption.effect((num) => notification(num)); // Does not execute the notification function
assert.equal(res.unsafe(), null);Perform side-effects if the option is None without changing the option.
const res = someOption.effectNone(() => notification()); // Does not execute the notification function
assert.equal(res.unsafe(), 5);
const res = noneOption.effectNone(() => notification()); // Fire and forget the notification function
assert.equal(res.unsafe(), null);Returns true if input is an Option.
const res: boolean = Option.is(someOption);
assert.equal(res, true);Returns an Option with a Some value.
const res: Option<number> = Option.some(5);
assert.equal(res.unsafe(), 5);Returns an Option with a None value.
const res: Option<number> = Option.none;
assert.equal(res.unsafe(), null);Returns an Option with the result of a promise.
const res: Option<number> = await Option.safe(() => Promise.resolve(5));
assert.equal(res.unsafe(), 5);
const res: Option<number> = await Option.safe(() => Promise.reject('Error'));
assert.equal(res.unsafe(), null);Returns an Option with an array of Some values or the first None value.
const res: Option<number[]> = Option.all(Option.some(1), Option.some(2));
assert.deepEqual(res.unsafe(), [1, 2]);
const res: Option<number[]> = Option.all(Option.some(1), Option.none);
assert.equal(res.unsafe(), null);Returns an Option with the first Some value or an array of None values.
const res: Option<number> = Option.any(Option.some(1), Option.none);
assert.equal(res.unsafe(), 1);
const res: Option<number> = Option.any(Option.none, Option.none);
assert.equal(res.unsafe(), null);Returns an Option with a value.
const res: Option<number> = Option.from(5);
assert.equal(res.unsafe(), 5);Returns an Option with a value if it is not null.
const res: Option<number> = Option.fromNullable(5);
assert.equal(res.unsafe(), 5);
const res: Option<number> = Option.fromNullable(null);
assert.equal(res.unsafe(), null);Contributions are welcome! Please open an issue or submit a pull request on GitHub.
This project is licensed under the MIT License.
Special thanks to my friend Emric for the name suggestion. "To remove rust chemically, the workpieces can be pickled."