node package manager
It’s your turn. Help us improve JavaScript. Take the 2017 JavaScript Ecosystem Survey »

option-t

option-t

npm version Build Status

  • 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

How to import

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

  • option-t/cjs
    • This directory privides commonjs style modules with .js extension.
  • option-t/esm
    • This directory privides ES modules with .mjs extension.
    • Currently, we provides them with .js extension for compatibility. However, we may only release .mjs for the future release. If you uses some module bundler (e.g. webpack or rollup), please add the config to prefer .mjs file.
  • option-t/lib
    • This directory privides 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 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 trasnform 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.

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.

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