TagVal (tagval.js)

Tagged union, discriminated union, variant or sum type.. for JavaScript.

Example

JavaScript

var T = require('tagval');

// with underscore.js
var nums = [3, 5, 6];
function is_even(x){ return x%2 === 0; }
function is_gt_10(x){ return (x > 10); }

var optional_x = T.Option.fromValue(_.find(nums, is_even));
var optional_y = T.Option.fromValue(_.find(nums, is_gt_10));

optional_x.match({
  Some: function(x){ console.log("I got "+x); },
  None: function(){ console.log("nothing"); }
});  // output: I got 6

var y = optional_y.getOrElse(10);
console.log(y); // 10

Coffee Script

T = require 'tagval'

# with underscore.js
nums = [3, 5, 6]
is_even = (x)-> x%2 is 0
is_gt_10 = (x)-> (x > 10)

optional_x = T.Option.fromValue _.find(nums, is_even)
optional_y = T.Option.fromValue _.find(nums, is_gt_10)

optional_x.match
  Some: (x)-> console.log "I got #{x}"
  None:    -> console.log "nothing"
# output: I got 6

y = optional_y.getOrElse 10
console.log y # 10

TagVal.Option class

Option is a class which expresses "something x"(Some) or "nothing"(None).

Example

// Finding a number from collection.
var optionalX = find_num(); // assume it returns `Option`
var DEFAULT_X = 30;

// Try to set the found number or 30 by default.
var x = optionalX.getOrElse(DEFAULT_X);

API

| method | detail | |----|----| | TagVal.Some(v) | creates a new Option object tagged Some with v in the value. | | TagVal.None() | creates a new Option object tagged None. | | TagVal.Option.fromValue(v) | creates Some(v) if v is neither undefined nor null. | | TagVal.optionFrom(v) | alias of TagVal.Option.fromValue(v) | | TagVal.fromBool(v) | If v is truthy, it returns Some(true) | | opt.map(f) | Some(x) to Some(f(x)) / nothing to None() | | opt.getOrElse(x) | Some(y) to y / None() to x | | opt.getOrElseF(f) | Some(y) to y / None() to f() | | opt.toArray() | Some(y) to [y] / None() to [] | | opt.toStatus(msg) | Some(v) to Success(v) / None() to Failure(msg) | | opt.toValue() | Some(v) to v / None() to undefined | | opt.equal(y) | If opt=Some(x) and y=Some(y) then x === y, and true if both are None(), otherwise false. | | opt.mapEqual(y, f) | If opt=Some(x) and y=Some(y) then f(x, y), and true if both are None(), otherwise false. | | opt.match | see Matchable | | opt.when | see Matchable | | opt.toString | see Matchable |

TagVal.Status class

Status object is a class that express "success with result"(Success) or "failure with message"(Failure).

API

| method | detail | |----|----| | TagVal.Status.trying(f) | Success(f()) or Failure(e) if caught an exception e. | | TagVal.withTry | alias of TagVal.Status.trying| | stat.getOrThrow() | Success(v) to v / throw msg if Failure(msg)| | stat.toOption() | Success(v) to Some(v) / Failure(msg) to None() | | stat.match | see Matchable | | stat.when | see Matchable | | stat.toString | see Matchable | | stat.equal | see Matchable |

TagVal.Matchable class

TagVal's basic concept is regarding {tag: String, val: Value} as minimum tagged-value interface. Matchable has actually only this two fields, and they are initialized simply:

var value = "some value"
var tv = new TagVal.Matchable("Tag", value); // I often express as "Tag(value)"

console.log(tv.tag); // Tag
console.log(tv.val); // value

In addition, Matchable has a few, generic methods below. You can inherit it. Option and Status are subclasses of Matchable.

API

| method | detail | |----|----| | tv.match(table[, default_fun]) | table[T](v) if table[T] exists. Next, default_fun(v) if default_fun exists. Otherwise undefined. | | tv.when(table) | table[T](v) if table[T] exists, otherwise returns object itself. | | tv.toString() | Tag( value.toString() ) | | tv.equal(y) | tv.valEqual(y) if same tag, otherwise false | | tv.valEqual(y) | tv.val === y.val | | TagVal.match(tv)(table) | match method for arbitrary { tag: Tag, value: Value } |

Matchable#when example:

In JavaScript:

x_stat = try_something1()
  .when({ Failure: function(){ return try_something2(); } })
  .when({ Failure: function(){ return try_something3(); } })
  .when({
    Failure: function(){ returns TagVal.Failure("All tries failed."); }
  });

In CoffeeScript:

x_stat = try_something1()
  .when Failure: -> try_something2()
  .when Failure: -> try_something3()
  .when Failure: -> TagVal.Failure "All tries failed."