ts-results

A typescript implementation of Rust's Result object.

Error handlingFunctional programming
vultix/ts-resultsts-results

README

ts-results


A typescript implementation of Rust's Result
and Option objects.

Brings compile-time error checking and optional values to typescript.

Installation


  1. ```bash
  2. $ npm install ts-results
  3. ```

or

  1. ```bash
  2. $ yarn add ts-results
  3. ```

Example


Result Example


Convert this:

  1. ```typescript
  2. import { existsSync, readFileSync } from 'fs';

  4. function readFile(path: string): string {
  5.     if (existsSync(path)) {
  6.         return readFileSync(path);
  7.     } else {
  8.         // Callers of readFile have no way of knowing the function can fail
  9.         throw new Error('invalid path');
  10.     }
  11. }

  13. // This line may fail unexpectedly without warnings from typescript
  14. const text = readFile('test.txt');
  15. ```

To this:

  1. ```typescript
  2. import { existsSync, readFileSync } from 'fs';
  3. import { Ok, Err, Result } from 'ts-results';

  5. function readFile(path: string): Result<string, 'invalid path'> {
  6.     if (existsSync(path)) {
  7.         return new Ok(readFileSync(path)); // new is optional here
  8.     } else {
  9.         return new Err('invalid path'); // new is optional here
  10.     }
  11. }

  13. // Typescript now forces you to check whether you have a valid result at compile time.
  14. const result = readFile('test.txt');
  15. if (result.ok) {
  16.     // text contains the file's content
  17.     const text = result.val;
  18. } else {
  19.     // err equals 'invalid path'
  20.     const err = result.val;
  21. }
  22. ```

Option Example


Convert this:

  1. ```typescript
  2. declare function getLoggedInUsername(): string | undefined;

  4. declare function getImageURLForUsername(username: string): string | undefined;

  6. function getLoggedInImageURL(): string | undefined {
  7.     const username = getLoggedInUsername();
  8.     if (!username) {
  9.         return undefined;
  10.     }

  12.     return getImageURLForUsername(username);
  13. }

  15. const stringUrl = getLoggedInImageURL();
  16. const optionalUrl = stringUrl ? new URL(stringUrl) : undefined;
  17. console.log(optionalUrl);
  18. ```

To this:

  1. ```typescript
  2. import { Option, Some, None } from 'ts-results';

  4. declare function getLoggedInUsername(): Option<string>;

  6. declare function getImageForUsername(username: string): Option<string>;

  8. function getLoggedInImage(): Option<string> {
  9.     return getLoggedInUsername().andThen(getImageForUsername);
  10. }

  12. const optionalUrl = getLoggedInImage().map((url) => new URL(stringUrl));
  13. console.log(optionalUrl); // Some(URL('...'))

  15. // To extract the value, do this:
  16. if (optionalUrl.some) {
  17.     const url: URL = optionalUrl.val;
  18. }
  19. ```

Usage


  1. ```typescript
  2. import { Result, Err, Ok } from 'ts-results';
  3. ```

Creation


  1. ```typescript
  2. let okResult: Result<number, Error> = Ok(10);
  3. let errorResult: Result<number, Error> = Err(new Error('bad number!'));
  4. ```

Type Safety

_Note: Typescript currently has a bug, making this type narrowing only work whenstrictNullChecks is turned on._
  1. ```typescript
  2. let result: Result<number, Error> = Ok(1);
  3. if (result.ok) {
  4.     // Typescript knows that result.val is a number because result.ok was true
  5.     let number = result.val + 1;
  6. } else {
  7.     // Typescript knows that result.val is an `Error` because result.ok was false
  8.     console.error(result.val.message);
  9. }

  11. if (result.err) {
  12.     // Typescript knows that result.val is an `Error` because result.err was true
  13.     console.error(result.val.message);
  14. } else {
  15.     // Typescript knows that result.val is a number because result.err was false
  16.     let number = result.val + 1;
  17. }
  18. ```

Stack Trace


A stack trace is generated when an Err is created.

  1. ```typescript
  2. let error = Err('Uh Oh');
  3. let stack = error.stack;
  4. ```

Unwrap


  1. ```typescript
  2. let goodResult = new Ok(1);
  3. let badResult = new Err(new Error('something went wrong'));

  5. goodResult.unwrap(); // 1
  6. badResult.unwrap(); // throws Error("something went wrong")
  7. ```

Expect


  1. ```typescript
  2. let goodResult = Ok(1);
  3. let badResult = Err(new Error('something went wrong'));

  5. goodResult.expect('goodResult should be a number'); // 1
  6. badResult.expect('badResult should be a number'); // throws Error("badResult should be a number - Error: something went wrong")
  7. ```

ExpectErr


  1. ```typescript
  2. let goodResult = Ok(1);
  3. let badResult = Err(new Error('something went wrong'));

  5. goodResult.expect('goodResult should not be a number'); // throws Error("goodResult should not be a number")
  6. badResult.expect('badResult should not be a number'); // new Error('something went wrong')
  7. ```


Map and MapErr


  1. ```typescript
  2. let goodResult = Ok(1);
  3. let badResult = Err(new Error('something went wrong'));

  5. goodResult.map((num) => num + 1).unwrap(); // 2
  6. badResult.map((num) => num + 1).unwrap(); // throws Error("something went wrong")

  8. goodResult
  9.     .map((num) => num + 1)
  10.     .mapErr((err) => new Error('mapped'))
  11.     .unwrap(); // 2
  12. badResult
  13.     .map((num) => num + 1)
  14.     .mapErr((err) => new Error('mapped'))
  15.     .unwrap(); // throws Error("mapped")
  16. ```

andThen


  1. ```typescript
  2. let goodResult = Ok(1);
  3. let badResult = Err(new Error('something went wrong'));

  5. goodResult.andThen((num) => new Ok(num + 1)).unwrap(); // 2
  6. badResult.andThen((num) => new Err(new Error('2nd error'))).unwrap(); // throws Error('something went wrong')
  7. goodResult.andThen((num) => new Err(new Error('2nd error'))).unwrap(); // throws Error('2nd error')

  9. goodResult
  10.     .andThen((num) => new Ok(num + 1))
  11.     .mapErr((err) => new Error('mapped'))
  12.     .unwrap(); // 2
  13. badResult
  14.     .andThen((num) => new Err(new Error('2nd error')))
  15.     .mapErr((err) => new Error('mapped'))
  16.     .unwrap(); // throws Error('mapped')
  17. goodResult
  18.     .andThen((num) => new Err(new Error('2nd error')))
  19.     .mapErr((err) => new Error('mapped'))
  20.     .unwrap(); // thros Error('mapped')
  21. ```

Else


Deprecated in favor of unwrapOr

UnwrapOr


  1. ```typescript
  2. let goodResult = Ok(1);
  3. let badResult = Err(new Error('something went wrong'));

  5. goodResult.unwrapOr(5); // 1
  6. badResult.unwrapOr(5); // 5
  7. ```

Empty


  1. ```typescript
  2. function checkIsValid(isValid: boolean): Result<void, Error> {
  3.     if (isValid) {
  4.         return Ok.EMPTY;
  5.     } else {
  6.         return new Err(new Error('Not valid'));
  7.     }
  8. }
  9. ```

Combining Results


ts-results has two helper functions for operating over n Result objects.

Result.all

Either returns all of the Ok values, or the first Err value

  1. ```typescript
  2. let pizzaResult: Result<Pizza, GetPizzaError> = getPizzaSomehow();
  3. let toppingsResult: Result<Toppings, GetToppingsError> = getToppingsSomehow();

  5. let result = Result.all(pizzaResult, toppingsResult); // Result<[Pizza, Toppings], GetPizzaError | GetToppingsError>

  7. let [pizza, toppings] = result.unwrap(); // pizza is a Pizza, toppings is a Toppings.  Could throw GetPizzaError or GetToppingsError.
  8. ```

Result.any

Either returns the first Ok value, or all Err values

  1. ```typescript
  2. let url1: Result<string, Error1> = attempt1();
  3. let url2: Result<string, Error2> = attempt2();
  4. let url3: Result<string, Error3> = attempt3();

  6. let result = Result.any(url1, url2, url3); // Result

  8. let url = result.unwrap(); // At least one attempt gave us a successful url
  9. ```

Usage with rxjs


resultMap


Allows you to do the same actions as the normal rxjs map
operator on a stream of Result objects.

  1. ```typescript
  2. import { of, Observable } from 'rxjs';
  3. import { Ok, Err, Result } from 'ts-results';
  4. import { resultMap } from 'ts-results/rxjs-operators';

  6. const obs$: Observable<Result<number, Error>> = of(Ok(5), Err('uh oh'));

  8. const greaterThanZero = obs$.pipe(
  9.     resultMap((number) => number > 0), // Doubles the value
  10. ); // Has type Observable>

  12. greaterThanZero.subscribe((result) => {
  13.     if (result.ok) {
  14.         console.log('Was greater than zero: ' + result.val);
  15.     } else {
  16.         console.log('Got Error Message: ' + result.val);
  17.     }
  18. });

  20. // Logs the following:
  21. // Got number: 10
  22. // Got Error Message: uh oh
  23. ```

resultMapErr


  1. ```typescript
  2. import { resultMapErr } from 'ts-results/rxjs-operators';
  3. ```

Behaves exactly the same as resultMap, but maps the error value.

resultMapTo


  1. ```typescript
  2. import { resultMapTo } from 'ts-results/rxjs-operators';
  3. ```

Behaves the same as resultMap, but takes a value instead of a function.

resultMapErrTo


  1. ```typescript
  2. import { resultMapErrTo } from 'ts-results/rxjs-operators';
  3. ```

Behaves the same as resultMapErr, but takes a value instead of a function.

elseMap


Allows you to turn a stream of Result objects into a stream of values, transforming any errors into a value.

Similar to calling the else function, but works on a stream of Result objects.

  1. ```typescript
  2. import { of, Observable } from 'rxjs';
  3. import { Ok, Err, Result } from 'ts-results';
  4. import { elseMap } from 'ts-results/rxjs-operators';

  6. const obs$: Observable<Result<number, Error>> = of(Ok(5), Err(new Error('uh oh')));

  8. const doubled = obs$.pipe(
  9.     elseMap((err) => {
  10.         console.log('Got error: ' + err.message);

  12.         return -1;
  13.     }),
  14. ); // Has type Observable

  16. doubled.subscribe((number) => {
  17.     console.log('Got number: ' + number);
  18. });

  20. // Logs the following:
  21. // Got number: 5
  22. // Got error: uh oh
  23. // Got number: -1
  24. ```

elseMapTo


  1. ```typescript
  2. import { elseMapTo } from 'ts-results/rxjs-operators';
  3. ```

Behaves the same as elseMap, but takes a value instead of a function.

resultSwitchMap and resultMergeMap


Allows you to do the same actions as the
normal rxjs switchMap
and rxjs switchMap operator on a stream of Result
objects.

Merging or switching from a stream of `Result` objects onto a stream of `` objects turns the stream into astream of `Result` objects.

Merging or switching from a stream of `Result` objects onto a stream of `Result` objects turn the streaminto a stream of `Result` objects.

  1. ```typescript
  2. import { of, Observable } from 'rxjs';
  3. import { Ok, Err, Result } from 'ts-results';
  4. import { resultMergeMap } from 'ts-results/rxjs-operators';

  6. const obs$: Observable<Result<number, Error>> = of(new Ok(5), new Err(new Error('uh oh')));

  8. const obs2$: Observable<Result<string, CustomError>> = of(new Ok('hi'), new Err(new CustomError('custom error')));

  10. const test$ = obs$.pipe(
  11.     resultMergeMap((number) => {
  12.         console.log('Got number: ' + number);

  14.         return obs2$;
  15.     }),
  16. ); // Has type Observable>

  18. test$.subscribe((result) => {
  19.     if (result.ok) {
  20.         console.log('Got string: ' + result.val);
  21.     } else {
  22.         console.log('Got error: ' + result.val.message);
  23.     }
  24. });

  26. // Logs the following:
  27. // Got number: 5
  28. // Got string: hi
  29. // Got error: custom error
  30. // Got error: uh oh
  31. ```

filterResultOk


Converts an `Observable>` to an `Observble` by filtering out the Errs and mapping to the Ok values.

  1. ```typescript
  2. import { of, Observable } from 'rxjs';
  3. import { Ok, Err, Result } from 'ts-results';
  4. import { filterResultOk } from 'ts-results/rxjs-operators';

  6. const obs$: Observable<Result<number, Error>> = of(new Ok(5), new Err(new Error('uh oh')));

  8. const test$ = obs$.pipe(filterResultOk()); // Has type Observable

  10. test$.subscribe((result) => {
  11.     console.log('Got number: ' + result);
  12. });

  14. // Logs the following:
  15. // Got number: 5
  16. ```

filterResultErr


Converts an `Observable>` to an `Observble` by filtering out the Oks and mapping to the error values.

  1. ```typescript
  2. import { of, Observable } from 'rxjs';
  3. import { Ok, Err, Result } from 'ts-results';
  4. import { filterResultOk } from 'ts-results/rxjs-operators';

  6. const obs$: Observable<Result<number, Error>> = of(new Ok(5), new Err(new Error('uh oh')));

  8. const test$ = obs$.pipe(filterResultOk()); // Has type Observable

  10. test$.subscribe((result) => {
  11.     console.log('Got number: ' + result);
  12. });

  14. // Logs the following:
  15. // Got number: 5
  16. ```