option-t

• This library represents Option type in ECMAScript.
  • You can sort the "nullable" convention in your project.
• APIs are inspired by Rust Language's Option<T> and Result<T, E>.
• TypeScript friendly APIs.
  • We recommend to use this with some static type systems like TypeScript.

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.
3. Provide a utility function 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

• Utility functions for these types (TypeScript ready).
  • 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).
  • Option<T>
  • Result<T, E>

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

This is a wrapper object which have utility methods on its prototype.

We recommend to use utility types & functions if you don't have to use instanceof check and you should avoid to expose this object as a public API of your package because instanceof checking might not work correctly if a user project has multiple versions of this package in their dependencies. See (#337).

Option<T>

This can express that there are some values or none.

import { createSome, createNone, } from 'option-t/esm/Option.mjs';
// or
const { createSome, createNone, } = require('option-t/cjs/Option');

// `Some<T>`
const some = createSome(1);
console.log(some.isSome); // true
console.log(some.unwrap()); // 1

// `None`
const none = createNone();
console.log(none.isSome); // false
console.log(none.unwrap()); // this will throw `Error`.

And this type is defined JSON representations if you serialize them by JSON.stringify(). See OptionBase.prototype.toJSON().

Result<T, E>

This can express that there is some values or some error information.

import { createOk, createErr, } from 'option-t/esm/Result.mjs';
// or
const { createOk, createErr, } = require('option-t/cjs/Result');

// `Ok<T, E>`
const some = createOk(1);
console.log(some.isOk()); // true
console.log(some.unwrap()); // 1
console.log(none.unwrapErr()); // this will throw `Error`.

// `Err<T, E>`
const none = createErr('some error info');
console.log(none.isOk()); // false
console.log(none.unwrap()); // this will throw `Error`.
console.log(none.unwrapErr()); // 'some error info'

How to import

This package provides some sub directories to import various functions. Each of them includes the same directory hierarchy with under src/.

• option-t/cjs
  • This directory provides commonjs style modules with .js extension.
• option-t/esm
  • This directory privides ES modules with .mjs extension.
• option-t/lib (Deprecated)
  • This directory provides both of an ES module and a commonjs style module.
    • ES module has .mjs extension.
    • CommonJS module has .js extension.
  • This directory is provided for a bit of a tricky purpose.
    • For example, your project distributes a bundled file with some module bundlers that can handle ES module (e.g. rollup or webpack), But your project also use babel or typescript's downlevel transform to transform your code from ES module to Commonjs and your project runs unit-tests for transformed code with plain Node.js which only use require().
  • Please don't use this path if you don't have to use this.
    • After Node.js v13.2, we recommend to use ES Module supported natively.

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.