Skip to content
Powerful and practical functional abstractions for JavaScript and TypeScript. Functors, Monads, Traversables and all that jazz.
TypeScript JavaScript
Branch: master
Clone or download

Latest commit

Latest commit 11f0a7d Jun 6, 2018

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmark Add lazyFoldr benchmark Dec 2, 2016
docs Use Prettier Nov 25, 2017
src Fix types in Either#ap Jun 6, 2018
test Monoid does not re-export combine Jun 2, 2018
.gitignore Prepare for release May 19, 2017
.npmignore Prepare for release May 19, 2017
.travis.yml Add CI Sep 28, 2016
README.md Tweak readme, use tslib May 19, 2017
metalsmith.js The commit in which YAML introduced Dec 20, 2016
package-lock.json Update dependencies May 31, 2018
package.json Version 0.0.24 Jun 2, 2018
tsconfig-release.json Smaller npm package Jun 2, 2018
tsconfig.json Use Prettier Nov 25, 2017
tslint.json Use Prettier Nov 25, 2017
typings.json Update name Jul 27, 2016

README.md

Jabz

Powerful and practical abstractions for JavaScript. Functors, monads, foldables, traversables, and all that jazz.

Build Status codecov Gitter chat

Goals and features

  • Be as simple and convenient as possible in usage
  • Allow for performant implementations
  • TypeScript support
  • Batteries included. Provide implementations of often used instances and commonly used utility functions.
  • Do-notation
  • Seamless instances
  • Comes with files in ES2015 module format for tree-shaking

For a more detailed introduction to the design of the specification and a comparison to Fantasy Land please see this blog post.

Install

npm install @funkia/jabz

Documentation

See the API documentation and the example below.

Note that the specification for the abstractions is not written down formally yet. But the source code contain TypeScript interfaces that documents the different required methods. The laws associated with the abstractions are as expected if one is familiar with them.

Example

This example demonstrates some of what Jabz can do by implementing a simple singly linked list aka. a cons list.

@monad @traversable
class Cons {
  constructor(v, t) {
    this.val = v;
    this.tail = t;
  }
  concat(c) {
    return this === nil ? c : cons(this.val, this.tail.concat(c));
  }
  of(b: B) {
    return cons(b, nil);
  }
  chain<B>(f) {
    return this === nil ? nil : f(this.val).concat(this.tail.chain(f));
  }
  traverse<B>(a, f) {
    return this === nil ? a.of(nil) : lift(cons, f(this.val), this.tail.traverse(a, f));
  }
}
const nil = new Cons(undefined, undefined);
function cons(a: A, as) {
  return new Cons(a, as);
}
function fromArray(as) {
  return as.length === 0 ? nil : cons(as[0], fromArray(as.slice(1)));
}

Since Cons contains the methods of and chain it can implement monad. This is done with the @monad decorator. JavaScript decorators are just plain old functions so they can also be used without the decorator syntax

monad(Cons);

The function allows implementations flexibility in what methods they choose to provide. For instance monad can also be implemented by defining a of, a map and a chain method.

Similar to Monad, Traversable is implemented by defining the traverse method and using the traversable decorator.

When we implement Monad Jabz automatically derives implementations for Functor and Applicative. Likewise when we implement Traversable it derives Foldable. Thus, Jabz can give us a lot of things for free just from the few methods the Cons class defines.

Map functions over elements in the list.

mapTo((n) => n * n, fromArray([1, 2, 3, 4])); //=> [1, 4, 9, 16]

Change each element in the list to a constant.

mapTo(8, fromArray([1, 2, 3, 4])); //=> [8, 8, 8, 8]

Apply a list of functions to a list of values.

ap(fromArray([(n) => n * 2, (n) => n * n]), fromArray(1, 2, 3)); //=> [2, 4, 6, 1, 4, 9]

Folding.

foldr((n, m) => n + m, 3, fromArray([1, 2, 3, 4, 5])); //=> 18

Find an element satisfying a predicate.

find((n) => n > 6, fromArray([1, 8, 3, 7, 5])); //=> just(8)
findLast((n) => n > 6, fromArray([1, 8, 3, 7, 5])); //=> just(7)

We can convert a cons-list to an array

toArray(fromArray([1, 2, 3, 4])); //=> [1, 2, 3, 4]

We can flatten nested cons-lists.

flatten(fromArray([fromArray([1, 2]), fromArray([3, 4, 5])])); //=> [1, 2, 3, 4, 5]

Seamless instances

Seamless instances means that certain native JavaScript types can be used as if they implemented the abstractions relevant for them.

  • string, implements setoid and monoid.
  • array, implements setoid, monoid, functor, foldable and traversable.
You can’t perform that action at this time.