option-t

• This library provides a toolkit for nullable types in ECMAScript.
  • T | null
  • T | undefined
  • T | null | undefined
  • Result type
  • Tagged Option type
• APIs are inspired by Rust Language's Option<T> and Result<T, E>.
• This library helps to sort the "nullable" convention in your project.
• TypeScript friendly APIs.
  • We recommend to use this with some static type systems like TypeScript.
• Zero dependency.
• Tree shakable completely.
• ES Module fully compatbile.
  • Support Node.js' ES Module.
  • Of course, we provides CommonJS too.

Motivation

This library provides these conventions for your project:

1. Uniform an expression of "none" value in JavaScript.
2. Uniform a way to carry error information instead of throwing an error by result type.
3. Provide various utility functions to handle 1 and 2 easily.

And Rust's std::option and std::result are suggestive to achieve these conventions in practice. Thus this package is inspired by their design.

Uniform the expression of "none" value.

In JavaScript world, there are many ways to express "there is no value". At least in ECMA262, There are some ways to represent them:

• undefined (e.g. Map.prototype.get())
• null (e.g. RegExp.prototype.exec())
• -1 (e.g. String.prototype.indexOf())

In addition, ECMA262 interacts with DOM binding, Node.js standard modules, and others. There are additional various ways to represent "none" value.

In practice, we write some glue code to tame their various ways in our project to uniform their expression style. This library contributes to uniform the convention to write it.

Uniform the way to carry error information instead of throwing an error.

Exception is useful but it has some terrible aspects. It's easy that try-catch statement be a jump instruction by large scoped try-catch statement. It's hard to find where to throw an error, it's also hard to handle a penetrated exception from a lower layer. Especially, exception mechanism mis-matches with an async programming model. ECMA262 7th' async-await relaxes the problem about an exception with async programming, but there is still the problem about exceptions in traditional synchronous programming. Furthermore, if you interact with setTimeout() and other async APIs built with callback style on event loop, this problem faces you.

And some async-push based paradigm like Rx.Observable<T> does not allow throw any exceptions in their Observable stream. If you throw an error in it, only catch() operator can catch the error. But a programmer would sometimes forget to use its operator. This means that throwing an Error in Rx's Observable is pretty mis-matched action. Promise also has a similar problem.

And exception in ECMA262 is not friendly with static typing model because ECMA262's throw can throw not only Error but also other object types.

In Rust which is a programming language designed for parallel and seftiness, it treats errors in two category:

Rust groups errors into two major categories: recoverable and unrecoverable errors. For a recoverable error, such as a file not found error, it’s reasonable to report the problem to the user and retry the operation. Unrecoverable errors are always symptoms of bugs, like trying to access a location beyond the end of an array.

This categorization is pretty useful to relax the problem about exception in ECMA262 which this section described.

Thus this library provides a way to express recoverable error and also recommends to use throwing an error only if you intend to throw an unrecoverable error. This categorization introduces a convenient convention for you:

• If the code uses throw, you should be careful about unrecoverable error.
• If the code returns Result<T, E> provided this library, then you should handle it correctly.

This convention is clear as error handling style and it's static typing friendly by generics.

Provide a utility function to handle these uniformed expression easily.

Some static type checking tools also provide a way to check nullability and provide these conventions.

• Flowtype's semantics has a built-in "Maybe" types,
• TypeScript has a non-nullable type check,
• Google Closure Compiler also can check a non-nullable type via JSDoc style annotations in some compilation mode.

Flowtype and TypeScript checks with their control flow analysis (Sorry, I'm not sure about the details of Google Closure Compiler's behavior).

However, these compilers do not provide a way to handle their value easily like map or flatMap operations.

Rust's std::option and std::result have some utilities operation method to handle them easily. This library also provides a convenient way to handle them and its way is inspired by Rust's ones.

Installation

npm install --save option-t
// or
yarn add option-t --save

Usage & APIs

All APIs are TypeScript ready.

• Utility functions for these types.
  • Nullable<T> (T | null)
  • Undefinable<T> (T | undefined)
  • Maybe<T> (T | null | undefined)
  • plain objects
    • Option<T> ({ ok: true; val: T } | { ok: false; })
    • Result<T, E> ({ ok: true; val: T } | { ok: false; err: E; })
• Wrapper objects (deprecated).

Utility functions for some types.

These are designed for more tree shaking friendly and more usable for JavaScript common world.

We recommend to use these in almost case.

Nullable<T> (T | null)

This can express a value of T type or null.

Undefinable<T> (T | undefined)

This can express a value of T type or undefined.

Maybe<T> (T | null | undefined)

This can express a value of T type, null, or undefined.

Option<T> ({ ok: true; val: T } | { ok: false; })

This can express that there is some values or none as a plain object. This does not have any property method on its prototype. But this allows no including unused methods of them.

Result<T, E> ({ ok: true; val: T } | { ok: false; err: E; })

This can express that there is some values or some error information as a plain object. This does not have any property method on its prototype. But this allows no including unused methods of them.

Wrapper objects (deprecated)

See this guide.

How to import

You can use these paths in both of CommonJS style and ES Module style.

This package provides some sub directories to import various functions (e.g. option-t/PlainResult). Each of them includes the same directory hierarchy with under src/.

If your toolchain does not support exports field in package.json...

We provides some backward compatible styles. They are deprecated but we're no plan to drop them.

These styles are kept for backward compatibility. You should switch to option-t/BarFoo style path.

Case: Your project is still use TypeScript compiler which lacks to support moduleResolution=node16.

Use option-t/lib/**.

This directory provides both of an ES Module and a CommonJS style module by conditional exports and host an actual d.ts file for legacy TypeScript compiler.

This is a most easy path for migrations (e.g. switch to option-t/BarFoo style, or switch to ES Module from CommonJS).

Case: Your project uses a classic bundler which does not support exports field.

you can use these paths:

• option-t/cjs/** (Deprecated)
  • This directory provides only commonjs style modules.
• option-t/esm/** (Deprecated)
  • This directory privides only ES Modules.

Idioms

• You can see some idioms of this library for the interoperability to JavaScript world.

See also

These documents would provide more information about Option<T> and Result<T, E>. These are written for Rust, but the essence is just same.

• Error Handling - Rust by Example
• Error Handling - The Rust Programming Language
• std::option - Rust
• std::result - Rust

License

MIT License

Contribution

• Use yarn to install dev-dependency toolchains.