1 | The Future monad
|
2 | ================
|
3 |
|
4 | [![Build Status](https://secure.travis-ci.org/folktale/data.future.png?branch=master)](https://travis-ci.org/folktale/data.future)
|
5 | [![NPM version](https://badge.fury.io/js/data.future.png)](http://badge.fury.io/js/data.future)
|
6 | [![Dependencies Status](https://david-dm.org/folktale/data.future.png)](https://david-dm.org/folktale/data.future)
|
7 | [![stable](http://hughsk.github.io/stability-badges/dist/stable.svg)](http://github.com/hughsk/stability-badges)
|
8 |
|
9 |
|
10 | The `Future(a, b)` monad represents values that depend on time. This allows one
|
11 | to model time-based effects explicitly, such that one can have full knowledge
|
12 | of when they're dealing with delayed computations, latency, or anything that
|
13 | can not be computed immediately.
|
14 |
|
15 | A common use for this monad is to replace the usual
|
16 | [Continuation-Passing Style][CPS] form of programming, in order to be able to
|
17 | compose and sequence time-dependent effects using the generic and powerful
|
18 | monadic operations.
|
19 |
|
20 |
|
21 | ## Example
|
22 |
|
23 | ```js
|
24 | var Future = require('data.future')
|
25 |
|
26 | function get(url) {
|
27 | return new Future(function(resolve, reject) {
|
28 | var request = new XMLHttpRequest()
|
29 | request.onload = function() {
|
30 | if (!/2\d\d/.test(this.status)) reject(this.responseText)
|
31 | else resolve(this.responseText)
|
32 | }
|
33 | request.open("get", url, true)
|
34 | request.send()
|
35 | })
|
36 | }
|
37 |
|
38 | var t1 = get('/something')
|
39 | var t2 = get('/other')
|
40 |
|
41 | var t3 = t1.map(function(a) {
|
42 | t2.map(function(b) {
|
43 | return a + b
|
44 | })
|
45 | })
|
46 |
|
47 | t3.chain(function(a) {
|
48 | console.log(a)
|
49 | })
|
50 | ```
|
51 |
|
52 |
|
53 | ## Installing
|
54 |
|
55 | The easiest way is to grab it from NPM. If you're running in a Browser
|
56 | environment, you can use [Browserify][]
|
57 |
|
58 | $ npm install data.future
|
59 |
|
60 |
|
61 | ### Using with CommonJS
|
62 |
|
63 | If you're not using NPM, [Download the latest release][release], and require
|
64 | the `data.future.umd.js` file:
|
65 |
|
66 | ```js
|
67 | var Future = require('data.future')
|
68 | ```
|
69 |
|
70 |
|
71 | ### Using with AMD
|
72 |
|
73 | [Download the latest release][release], and require the `data.future.umd.js`
|
74 | file:
|
75 |
|
76 | ```js
|
77 | require(['data.future'], function(Future) {
|
78 | ( ... )
|
79 | })
|
80 | ```
|
81 |
|
82 |
|
83 | ### Using without modules
|
84 |
|
85 | [Download the latest release][release], and load the `data.future.umd.js`
|
86 | file. The properties are exposed in the global `Future` object:
|
87 |
|
88 | ```html
|
89 | <script src="/path/to/data.future.umd.js"></script>
|
90 | ```
|
91 |
|
92 |
|
93 | ### Compiling from source
|
94 |
|
95 | If you want to compile this library from the source, you'll need [Git][],
|
96 | [Make][], [Node.js][], and run the following commands:
|
97 |
|
98 | $ git clone git://github.com/folktale/data.future.git
|
99 | $ cd data.future
|
100 | $ npm install
|
101 | $ make bundle
|
102 |
|
103 | This will generate the `dist/data.future.umd.js` file, which you can load in
|
104 | any JavaScript environment.
|
105 |
|
106 |
|
107 | ## Documentation
|
108 |
|
109 | You can [read the documentation online][docs] or build it yourself:
|
110 |
|
111 | $ git clone git://github.com/folktale/monads.maybe.git
|
112 | $ cd monads.maybe
|
113 | $ npm install
|
114 | $ make documentation
|
115 |
|
116 | Then open the file `docs/literate/index.html` in your browser.
|
117 |
|
118 |
|
119 | ## Platform support
|
120 |
|
121 | This library assumes an ES5 environment, but can be easily supported in ES3
|
122 | platforms by the use of shims. Just include [es5-shim][] :)
|
123 |
|
124 |
|
125 | ## Licence
|
126 |
|
127 | Copyright (c) 2013 Quildreen Motta.
|
128 |
|
129 | Released under the [MIT licence](https://github.com/folktale/data.future/blob/master/LICENCE).
|
130 |
|
131 |
|
132 | [Fantasy Land]: https://github.com/fantasyland/fantasy-land
|
133 | [Browserify]: http://browserify.org/
|
134 | [Git]: http://git-scm.com/
|
135 | [Make]: http://www.gnu.org/software/make/
|
136 | [Node.js]: http://nodejs.org/
|
137 | [es5-shim]: https://github.com/kriskowal/es5-shim
|
138 | [docs]: http://folktale.github.io/data.future
|
139 | [CPS]: http://matt.might.net/articles/by-example-continuation-passing-style/
|
140 |
|
141 | [release]: https://github.com/folktale/data.future/releases/download/v1.0.0/data.future-1.0.0.tar.gz
|
142 |
|
143 |
|