Funfix


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.

$3

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:

$3

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

$3

`
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| elated units of measurement |
| Duration | inspired by Scala's own type, as a type safe representation for durations |

$3

Defines monadic data types for controlling laziness, asynchrony and side effects.
Exposes the most advanced IO implementation for JavaScript.

See JSDoc documentation.

#### Quick Overview & Usage

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

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.