@jcbkdev/result

A Result type for TypeScript. A function returns a Result<T> instead of throwing, so the possibility of failure is part of its signature.

Installation

npm install @jcbkdev/result

Usage

import { Result } from "@jcbkdev/result";

function parseAge(input: string): Result<number> {
  const age = Number(input);

  if (!Number.isInteger(age) || age < 0) {
    return Result.error(new Error(`Invalid age: ${input}`));
  }

  return Result.ok(age);
}

const result = parseAge("42");

if (result.isError()) {
  console.error(result.getError());
} else {
  console.log(result.getValue());
}

// or

if (result.isOk()) {
  console.log(result.getValue());
} else {
  console.error(result.getError());
}

Reference

Creating a result

Method	Description
Result.ok()	Creates a successful Result<void>, with no value.
Result.ok(value)	Creates a successful result, holding a value.
Result.error(error)	Creates a failed result holding an Error.

Inspecting a result

Method	Returns	Description
isOk()	boolean	true if the result is a success.
isError()	boolean	true if the result is a failure.
getValue()	T | undefined	The value of a success. undefined for a failure.
getError()	Error | undefined	The error of a failure. undefined for a success.

Notes

Checking the state of a result

A success can legitimately hold undefined, null, 0, or '', so always use isOk() / isError() to determine the state, not the value returned by getValue():

// Correct
if (result.isOk()) { /* ... */ }

// Incorrect: a success holding a falsy value is treated as a failure
if (result.getValue()) { /* ... */ }

Using try/catch

A function that returns a Result should not throw. To use code that can throw, such as the URL constructor, catch the exception and return it as a failure:

function parseUrl(input: string): Result<URL> {
  try {
    return Result.ok(new URL(input));
  } catch (error) {
    // Any value can be thrown in JavaScript, so make sure an Error is returned
    return Result.error(error instanceof Error ? error : new Error(String(error)));
  }
}

Results without a value

Result.ok() with no argument returns a Result<void>. For any other type, pass the value explicitly, even if it is undefined:

function deleteUser(id: string): Result<void> {
  db.remove(id);
  return Result.ok();
}

function findUser(id: string): Result<User | undefined> {
  try {
    return Result.ok(db.get(id)); // undefined if there is no such user
  } catch (error) {
    return Result.error(error instanceof Error ? error : new Error(String(error)));
  }
}

Contributing

1. Fork the repository.
2. Create a branch for your change:

git switch -c feature/my-change

3. Install the dependencies:

npm install

4. Make your changes, then run the following and check for errors:

npm test
npm run typecheck
npm run build

5. Commit your changes:

git commit -m "Describe your change"

6. Push to the branch:

git push origin feature/my-change

7. Open a pull request.

License

MIT