@stacksjs/errors NPM

Stacks Error Handling

Similar to the way Rust handles errors and other functional programming languages.

Encode failure into your program. This package contains a Result type that represents either success (Ok) or failure (Err).
For asynchronous tasks, this package offers a ResultAsync class which wraps a Promise<Result<T, E>> and gives you the same level of expressivity and control as a regular Result<T, E>.
ResultAsync is "thenable" meaning it behaves exactly like a native Promise<Result>, except you have access to the same methods that Result provides without having to await or .then the promise. - neverthrow

Read more about the API in the documentation here.

☘️ Features

Currently, a wrapper of the neverthrow API.

Type-Safe Errors
Encode failure into your program

🤖 Usage

pnpm i -D @stacksjs/errors

You can now use it in your project:

import {
  Err,
  Ok,
  Result,
  ResultAsync,
  err,
  errAsync,
  fromPromise,
  fromSafePromise,
  fromThrowable,
  ok,
  okAsync,
} from '@stacksjs/errors'

// ...

Example #1

const result = ok({ myData: 'test' }) // instance of `Ok`

result.isOk() // true
result.isErr() // false

Example #2

const command = 'rimraf ./pnpm-lock.yaml ./node_modules/ ./.stacks/**/node_modules'
const result = await runCommand(command, options)

if (result.isOk()) {
  log.success('Cleaned up.')
  process.exit(ExitCode.Success)
}

log.error(result.error)
process.exit(ExitCode.FatalError)

Learn more in the docs.

🧪 Testing

pnpm test

🤗 Motivation

As from the HackerNews thread relating to "Where Everything Went Wrong: Error Handling and Error Messages in Rust (2020)":

Error handling has been wrong since the beginning, and has continued to be wrong ever since.

First, we had error codes. Except these were wrong because people forget all the time to check them.

Then we had exceptions, which solved the problem of people forgetting to check by crashing the app.

Then the Java team got the bright idea to have checked exceptions, which at first helped to mitigate crashes
from uncaught exception, but caused an explosion in thrown exception signatures, culminating in "catch Throwable".

Back to square one.

Then we got multi-return error objects, maybes, panics, and all sorts of bright ideas that fail to understand the basic premises of errors:

  Any error system that relies upon developer discipline will fail because errors will be missed.

  Any error system that handles all errors the same way will fail because there are some errors we can ignore,
  and some errors we must not ignore. And what's ignorable/retriable to one project is not ignorable/retriable to another.

Attempting to get the complete set of error types that any given call may raise is a fool's errand because of the halting
problem it eventually invokes. Forcing people to provide such a list results in the Java problem for the same reason.

It's a hard problem, which is why no one has solved it yet.

Quote from user kstenerud.