@stacksjs/error-handling

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

bun install -d @stacksjs/error-handling

You can now use it in your project:

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

// ...

Example #1

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

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

Example #2

const command = 'bunx --bun rimraf ./bun.lockb ./node_modules ./core/**/dist'
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

bun 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.

📈 Changelog

Please see our releases page for more information on what has changed recently.

🚜 Contributing

Please review the Contributing Guide for details.

🏝 Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

📄 License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙