readme_jsdoc.md


What this is all about

The futils library is designed to allow you to incorporate various aspects of functional programming techniques into your JavaScript code. It ships basic building blocks as well as advanced data structures and also the tools to create your own ones. It allows you to use tacit programming with functional composition, partial application and other function(al) operations. Or maybe you want to express the intend of your code with custom data types and to work with powerful data structures like Either, Task and IO.

If that doesn't convince you to give it a go, here's an example that should spark your imagination. This is some code for the SCUMM engine, which Ron Gilbert has shown in 2011:

cut-scene {
    ...
    actor nurse-edna in-room edna-bedroom at 60,20
    camera-follow nurse-edna
    actor nurse-edna walk-to 30,20
    wait-for-actor nurse-edna
    say-line nurse-edna "WHATS'S YOUR POINT ED!!!"
    wait-for-talking nurse-edna
    ...
}

It's a beautiful little piece of declarative code. And it's quite easy to understand, right? The first line says it's a "cut-scene", the curly brackets denote everything inside it as part of a block (or group), and each line in the block reads like an instruction. futils tries to give you the tools at hand you need to write your day-to-day JavaScript code with equal expressive power. Get rid of those messy if statements, for loops and clutter and instead develop and use a beautiful API you've build almost alongside your application.

Further readings:

It is recommended to have a basic understanding about what functional programming in JavaScript looks like and how it is done. In case you have little experience with it, these should get you going:

• A Gentle Introduction to Functional JavaScript Style
• Professor Frisby's Mostly Adequate Guide to Functional Programming Note: chain is flatMap in futils
• Fantas, eel and specification Note: chain is flatMap in futils
• Monads in JavaScript Note: unit is the type constructor and bind is flatMap in futils

Why is flatMap chosen over bind or chain? Mostly in favor to have a unified interface with the native Array.prototype.flatMap and Array.prototype.flat methods. Read more about it: Array.prototype.flatMap, Array.prototype.flat, EcmaScript Proposal. Not only does it cause less friction when reading your code, it also makes porting function compositions easier because it frees you from having to distinguish your functions based on the fact that they either utilize chain when working with monads, or flatMap when working with arrays.

Download

The library can be loaded either by downloading it from NPM, by getting it from a CDN or by downloading it from Github.

Source	Snippet
NPM	npm i futils
CDN	<script src="https://unpkg.com/futils@latest"></script>
Github	<script src="local/path/to/futils.js"></script>

Requirements

futils requires a few things to be available to function properly. First of all, it needs to have Symbol support. In case you are unsure if the target platform provides it, use a shim from the list below. The same goes for Promise ans Object.assign. Also check out:

• ES6 compat table: Promise
• ES6 compat table: Symbols
• ES6 compat table: Object.assign

Shims:

You can use either of these shims if needed:

• core-js (recommended): Github | CDN
• es6-shim: Github | CDN

Quickstart

Start with this [quickstart tutorial]{@tutorial Quickstart-Basic} if you haven't used futils before. Otherwise, have fun exploring the other tutorials or reading the docs for interesting functionality!