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 & APIs

• 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; })

Wrapper objects

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

Option<T>

This can express that there is some values or none.

import { createSome, createNone, } from 'option-t/esm/Option';
// 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`.

Result<T, E>

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

Utility functions for some types.

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

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.

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.

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