feat: add types for Ok/Err/Result/ResultPromise

[aleclarson]

Tip

The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Summary

Added Types

• Ok
  • Ok<string> → [undefined, string]
  • Ok<Promise<string>> → [undefined, string]
• Err
  • Err → [Error, undefined]
  • Err<unknown> → [NonNullable<unknown>, undefined]
  • Err<Error | string> → [Error | string, undefined]
• Result
  • Result<string> → Ok<string> | Err
  • Result<string, TypeError> → Ok<string> | Err<TypeError>
• ResultPromise
  • ResultPromise<string> → Promise<Ok<string> | Err>
  • ResultPromise<string, TypeError> → Promise<Ok<string> | Err<TypeError>>

The goal is to keep these types as straight-forward as possible.

Etymology

The Ok<T> and Err<E> convention for representing success and error states in a type-safe manner originates from the Rust programming language. This pattern is known as the Result type in Rust.

In Rust, the Result<T, E> enum is used to return and propagate errors. It has two variants:

1. Ok(T): Represents a successful result, containing a value of type T.
2. Err(E): Represents an error, containing an error value of type E.

This pattern has been adopted by other languages and libraries due to its effectiveness in handling errors and optional values in a type-safe way. It's similar to the Either type in functional programming, where Left typically represents an error and Right represents a success value.

The Ok<T> and Err<E> convention offers several benefits:

1. Explicit error handling: Forces developers to consider both success and error cases.
2. Type safety: Provides compile-time checks for proper error handling.
3. Composability: Allows for easy chaining of operations that may fail.
4. Avoiding exceptions for control flow: Represents errors as values rather than using exceptions.

This approach to error handling and optional values has gained popularity in various programming paradigms due to its clarity and safety advantages over traditional error handling mechanisms.

Related issue, if any:

Inspired by #131

For any code change,

• Related documentation has been updated, if needed

Does this PR introduce a breaking change?

No

[github-actions]

A new beta version 12.2.0-beta.6b76988 has been published to NPM. 🚀

To install:

pnpm add [email protected]

The radashi@beta tag also includes this PR.