option-t

option-t

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

Installation

npm install --save option-t

Usage

const { Some, None, } = require('option-t');

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

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

API

• Wrapper objects
  • Option<T>
  • Result<T, E>
• 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; })

JSON Representation

Some types defines JSON representations if you serialize them by JSON.stringify().

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 essense is just same.

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

Semantics

See the document.

FAQ

How to represent same things without this library?

Of course, there some alternative approaches. We introduce them.

Use an object with destructuring assignment.

From ECMA262 6th, we can use destructuring assignment. It provides a convinient way to handle/unwrap a value in an object.

type Option<T> = {
  ok: boolean;
  value: T;
};

const { ok, value, } = getSomeValue();
if (ok) {
    // handle some value case
}
else {
    // handle none case.
}

This does same thing which is like a return value of iterator.next(). But this approach cannot call instance methods on their returned values. If you would like to handle a result more seemless, we recommend to use option-t.

On the other hand, this way (and option-t) need to allocate an object. This allocation cost would be a cost.

In the future, a JavaScript runtime may make it more cheap, but we don't recommend to use this approach if you requires a high performance computing extremely.

Runtime Checking

This would be most popular way to handle a returned value in JavaScript.

const value = getSome(); // this returns the actual value, otherwise `undefined`.
if (value !== undefined) {
    // handle some value
}
else {
    // handle none value
}

These approach don't need an extra object allocation like the above approach (and option-t).

And you need to think about "what is null type? including undefined or not?". At least in ECMA262, There are some ways to represent "there're no value".

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

Use static type checker

Some static type checking tools provides a way to check nullability.

• Flowtype's semantics has a built-in "Maybe" types,
• TypeScript has a non-nullable type check,
  • From TypeScript compiler 1.8, you can represent type Maybe<T> = T | void.
• Google Closure Compiler also can check a non-nullable type via JSDoc style annotations in some compilation mode.

Flowtype and TypeScript checks with thier control flow analysis (Sorry, I don't know the details of Google Closure Compiler's behavior). Thus you can leave a runtime nullability checking in your code.

License

MIT License

Contribution

• Use yarn to install dev-dependency toolchains.