TypeScript JavaScript

README.md

Funfix

Travis Coverage Status Greenkeeper badge npm Join chat

Funfix is a library of type classes and data types for Functional Programming in JavaScript, TypeScript and Flow.

Inspired by Scala, Cats and Monix.

Usage

The code is organized in sub-projects, for à la carte dependencies, but all types, classes and functions are exported by funfix, so to import everything:

npm install --save funfix

Or you can depend on individual sub-projects, see below.

Modules: UMD and ES 2015

The library has been compiled using UMD (Universal Module Definition), so it should work with CommonJS and AMD, for standalone usage in browsers or Node.js.

But it also provides a module definition in package.json, thus providing compatibility with ECMAScript 2015 modules, for usage when used with a modern JS engine, or when bundling with a tool chain that understands ES2015 modules, like Rollup or Webpack.

Sub-projects

Funfix has been split in multiple sub-projects for à la carte dependency management. As mentioned above, you can depend on everything by depending on the funfix project.

These sub-projects are:

funfix-core

Exposes primitive interfaces and data types that need to be universally available, belonging into a standard library.

See JSDoc documentation.

For an à la carte install:

npm install --save funfix-core

Exposes types for expressing disjunctions:

Either data type for expressing results with two possible outcome types (a disjoint union)
Option data type for expressing optional values
Try data type for representing the result of computations that may result in either success or failure

Standard interfaces and tools for dealing with universal equality and hash code generation:

IEquals an interface for defining universal equality and hash code
is and equals for using IEquals in tests, or otherwise falls back to JavaScript's equality (== or valueOf())
hashCode for calculating hash codes (for usage in sets and maps data structures) using IEquals, or otherwise falls back to calculating a hash from .valueOf() or from .toString()
isValueObject for testing if a given object implements IEquals

Standard, reusable error types, that help with some common scenarios, working with error types being preferable to working with strings:

DummyError for tagging errors used for testing purposes
IllegalArgumentError for signaling that a given argument is violating the contract of the called function or constructor
IllegalInheritanceError for signaling that inheriting from a certain class is illegal
IllegalStateError for signaling that an illegal code branch was executed and thus something is wrong with the code and needs investigation (e.g. a bug)
NoSuchElementError thrown when the user expects an element to be returned from a function call, but no such element exists
NotImplementedError thrown in case an implementation is missing
TimeoutError thrown in case the execution of a procedure takes longer than expected
CompositeError for gathering multiple errors in a single reference that can expose them as a list

Misc utilities:

applyMixins for working with mixins (i.e. classes used as interfaces, with methods that have default implementations), see Mixins for an explanation
id is the "identity" function

funfix-exec

Contains low level / side-effectful utilities and data types for building higher level concurrency tools.

See JSDoc documentation.

For an à la carte install:

npm install --save funfix-exec

Scheduling tasks for asynchronous execution:

Future a lawful, fast, cancelable alternative to JavaScript's Promise
Scheduler the alternative to using setTimeout for asynchronous boundaries or delayed execution

In support of futures and schedulers, ICancelable data types are introduced for dealing with cancellation concerns:

ICancelable and Cancelable for expressing actions that can be triggered to cancel processes / dispose of resources
IBoolCancelable and BoolCancelable for cancelable references that can be queried for their isCanceled status
IAssignCancelable and AssignCancelable for cancelable references that can be assigned (behave like a box for) another reference
MultiAssignCancelable being a mutable cancelable whose underlying reference can be updated multiple times
SingleAssignCancelable for building forward references, much like MultiAssignCancelable except that it can be assigned only once, triggering an error on the second attempt
SerialCancelable being like a MultiAssignCancelable that cancels its previous underlying reference on updates

And also types for expressing durations:

TimeUnit inspired by Java's own enumeration, representing time
Duration inspired by Scala's own type, as a type safe representation for durations

funfix-effect

Defines monadic data types for controlling laziness, asynchrony and side effects.

See JSDoc documentation.

For an à la carte install:

npm install --save funfix-effect

The exposed data types:

Eval lawful, lazy, monadic data type, that can control evaluation, inspired by the Eval type in Typelevel Cats and by the Coeval type in Monix, a more simple IO-like type that can only handle immediate execution, no async boundaries, no error handling, not being meant for suspending side effects.
IO lawful, lazy, monadic data type, capable of expressing and composing side effectful actions, including asynchronous, being the most potent and capable alternative to JavaScript's Promise, inspired by Haskell's IO and by the Monix Task

funfix-types

Defines type classes inspired by Haskell's standard library and by Typelevel Cats.

See JSDoc documentation.

For an à la carte install:

npm install --save funfix-types

Type classes inspired by Haskell's standard library and by Typelevel Cats:

Eq type class for determining equality between instances of the same type and that obeys the laws defined in EqLaws
Functor type class exposing map and that obeys the laws defined in FunctorLaws
Apply type class that extends Functor, exposing ap and that obeys the laws defined in ApplyLaws
Applicative type class that extends Functor and Apply, exposing pure and that obeys the laws defined in ApplicativeLaws
ApplicativeError a type class that extends Applicative, for applicative types that can raise errors or recover from them and that obeys the laws defined in ApplicativeErrorLaws
FlatMap type class that extends Functor and Apply, exposing flatMap and tailRecM and that obeys the laws defined in FlatMapLaws
Monad type class that extends Applicative and FlatMap and that obeys the laws defined in MonadLaws
MonadError type class that extends ApplicativeError and Monad, for monads that can raise or recover from errors and that obeys the laws defined in MonadErrorLaws
CoflatMap type class that extends Functor, the dual of FlatMap, obeying the laws defined in CoflatMapLaws
Comonad type class that extends CoflatMap, the dual of Monad, for data types that providing extract, obeying the laws defined in ComonadLaws

More is coming 😉

TypeScript or Flow?

Funfix supports both TypeScript and Flow type annotations out of the box.

It also makes the best use of the capabilities of each. For example TypeScript has bivariant generics, but Flow supports variance annotations and Funfix makes use of them. Development happens in TypeScript, due to better tooling, but both are first class citizens.

Contributing

The Funfix project welcomes contributions from anybody wishing to participate. All code or documentation that is provided must be licensed with the same license that Funfix is licensed with (Apache 2.0).

Feel free to open an issue if you notice a bug, have an idea for a feature, or have a question about the code. Pull requests are also gladly accepted. For more information, check out the contributor guide.

License

All code in this repository is licensed under the Apache License, Version 2.0. See LICENCE.