fluture - npm Package Compare versions

Comparing version 0.6.1 to 0.6.2

fluture.js

@@ -28,6 +28,6 @@ /*global define FantasyLand inspectf*/
   function isForkable(m){
-    return m && typeof m.fork === 'function' && m.fork.length >= 2;
+    return Boolean(m) && typeof m.fork === 'function' && m.fork.length >= 2;
   }
 
-  function isFluture(m){
+  function isFuture(m){
     return m instanceof FutureClass;
@@ -94,3 +94,3 @@ }
   function check$fork(it, rej, res){
-    if(!isFluture(it)) error$invalidContext('Future#fork', it);
+    if(!isFuture(it)) error$invalidContext('Future#fork', it);
     if(!isFunction(rej)) error$invalidArgument('Future#fork', 0, 'be a function', rej);
@@ -101,3 +101,3 @@ if(!isFunction(res)) error$invalidArgument('Future#fork', 1, 'be a function', res);
   function check$chain(it, f){
-    if(!isFluture(it)) error$invalidContext('Future#chain', it);
+    if(!isFuture(it)) error$invalidContext('Future#chain', it);
     if(!isFunction(f)) error$invalidArgument('Future#chain', 0, 'be a function', f);
@@ -107,3 +107,3 @@ }
   function check$chain$f(m, f, x){
-    if(!isFluture(m)) throw new TypeError(
+    if(!isFuture(m)) throw new TypeError(
       'Future#chain expects the function its given to return a Future'
@@ -115,3 +115,3 @@ + `\n  Actual: ${show(m)}\n  From calling: ${showf(f)}\n  With: ${show(x)}`
   function check$chainRej(it, f){
-    if(!isFluture(it)) error$invalidContext('Future.chainRej', it);
+    if(!isFuture(it)) error$invalidContext('Future.chainRej', it);
     if(!isFunction(f)) error$invalidArgument('Future.chainRej', 0, 'a function', f);
@@ -121,3 +121,3 @@ }
   function check$chainRej$f(m, f, x){
-    if(!isFluture(m)) throw new TypeError(
+    if(!isFuture(m)) throw new TypeError(
       'Future.chainRej expects the function its given to return a Future'
@@ -129,3 +129,3 @@ + `\n  Actual: ${show(m)}\n  From calling: ${showf(f)}\n  With: ${show(x)}`
   function check$map(it, f){
-    if(!isFluture(it)) error$invalidContext('Future#map', it);
+    if(!isFuture(it)) error$invalidContext('Future#map', it);
     if(!isFunction(f)) error$invalidArgument('Future#map', 0, 'be a function', f);
@@ -135,4 +135,4 @@ }
   function check$ap(it, m){
-    if(!isFluture(it)) error$invalidContext('Future#ap', it);
-    if(!isFluture(m)) error$invalidArgument('Future#ap', 0, 'be a Future', m);
+    if(!isFuture(it)) error$invalidContext('Future#ap', it);
+    if(!isFuture(m)) error$invalidArgument('Future#ap', 0, 'be a Future', m);
   }
@@ -148,13 +148,13 @@
   function check$race(it, m){
-    if(!isFluture(it)) error$invalidContext('Future#race', it);
-    if(!isFluture(m)) error$invalidArgument('Future#race', 0, 'be a Future', m);
+    if(!isFuture(it)) error$invalidContext('Future#race', it);
+    if(!isFuture(m)) error$invalidArgument('Future#race', 0, 'be a Future', m);
   }
 
   function check$or(it, m){
-    if(!isFluture(it)) error$invalidContext('Future#or', it);
-    if(!isFluture(m)) error$invalidArgument('Future#or', 0, 'be a Future', m);
+    if(!isFuture(it)) error$invalidContext('Future#or', it);
+    if(!isFuture(m)) error$invalidArgument('Future#or', 0, 'be a Future', m);
   }
 
   function check$fold(it, f, g){
-    if(!isFluture(it)) error$invalidContext('Future#fold', it);
+    if(!isFuture(it)) error$invalidContext('Future#fold', it);
     if(!isFunction(f)) error$invalidArgument('Future#fold', 0, 'be a function', f);
@@ -165,3 +165,3 @@ if(!isFunction(g)) error$invalidArgument('Future#fold', 1, 'be a function', g);
   function check$value(it, f){
-    if(!isFluture(it)) error$invalidContext('Future#value', it);
+    if(!isFuture(it)) error$invalidContext('Future#value', it);
     if(!isFunction(f)) error$invalidArgument('Future#value', 0, 'be a function', f);
@@ -171,7 +171,7 @@ }
   function check$promise(it){
-    if(!isFluture(it)) error$invalidContext('Future#promise', it);
+    if(!isFuture(it)) error$invalidContext('Future#promise', it);
   }
 
   function check$cache(it){
-    if(!isFluture(it)) error$invalidContext('Future#cache', it);
+    if(!isFuture(it)) error$invalidContext('Future#cache', it);
   }
@@ -211,3 +211,3 @@
   function check$parallel$m(m, i){
-    if(!isFluture(m)) throw new TypeError(
+    if(!isFuture(m)) throw new TypeError(
       'Future.parallel expects argument 1 to be an array of Futures.'
@@ -481,6 +481,10 @@ + ` The value at position ${i} in the array was not a Future.\n  Actual: ${show(m)}`
 
-  //////////////////
-  // Constructors //
-  //////////////////
+  /////////////////////
+  // Other functions //
+  /////////////////////
 
+  //Type checks.
+  Future.isFuture = isFuture;
+  Future.isForkable = isForkable;
+
   //Create a Future which rejects witth the given value.
@@ -487,0 +491,0 @@ Future.reject = function Future$reject(x){

package.json

 {
   "name": "fluture",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "A mathematically correct alternative to Promises for asynchronous control flow",
@@ -28,2 +28,3 @@ "main": "fluture.js",
   },
+  "files": ["fluture.js"],
   "keywords": [
@@ -30,0 +31,0 @@ "async",

README.md

@@ -8,3 +8,3 @@ # Fluture
 [![Build Status](https://travis-ci.org/Avaq/Fluture.svg?branch=master)](https://travis-ci.org/Avaq/Fluture)
-[![Code Coverage](https://codecov.io/github/Avaq/Fluture/coverage.svg?branch=develop)](https://codecov.io/github/Avaq/Fluture/fluture.js?branch=develop)
+[![Code Coverage](https://codecov.io/github/Avaq/Fluture/coverage.svg?branch=master)](https://codecov.io/github/Avaq/Fluture/fluture.js?branch=master)
 
@@ -19,3 +19,16 @@ Futures are containers which represent some eventual value as a result of an
 
+## Table of contents
 
+- [Usage](#usage)
+- [Motivation and Features](#motivation-and-features)
+- [Documentation](#documentation)
+  - [Type signatures](#type-signatures)
+  - [Creation](#creation)
+  - [Method API](#method-api)
+  - [Dispatcher API](#dispatcher-api)
+  - [Utility functions](#utility-functions)
+  - [Futurization](#futurization)
+- [Benchmarks](#benchmarks)
+- [The name](#the-name)
+
 ## Usage
@@ -78,13 +91,16 @@
 
-### Constructors
+### Creation
 
 #### `Future :: ((a -> Void), (b -> Void) -> Void) -> Future a b`
 
-A (monadic) container which represents an eventual value. A lot like Promise but
-more principled in that it follows the [Fantasy Land][1] algebraic JavaScript
-specification.
+The Future constructor. Creates a new instance of Future by taking a single
+parameter `fork`: A function which takes two callbacks. Both are continuations
+for an asynchronous computation. The first is `reject`, commonly abreviated to
+`rej`. The second `resolve`, which abreviates to `res`. The `fork` function is
+expected to call `rej` once an error occurs, or `res` with the result of the
+asynchronous computation.
 
 ```js
-const eventualThing = Future((reject, resolve) => {
-  setTimeout(resolve, 500, 'world');
+const eventualThing = Future((rej, res) => {
+  setTimeout(res, 500, 'world');
 });
@@ -99,5 +115,7 @@
 
-#### `of :: b -> Future a b`
+#### `of :: a -> Future _ a`
 
-A constructor that creates a Future containing the given value.
+Creates a Future which immediately resolves with the given value. This function
+is compliant with the [Fantasy Land Applicative specification][16] and is
+also available on the prototype.
 
@@ -113,5 +131,10 @@ ```js
 
+#### `reject :: a -> Future a _`
+
+Creates a Future which immediately rejects with the given value. Just like `of`
+but for the rejection branch.
+
 #### `after :: Number -> b -> Future a b`
 
-A constructor that creates a Future containing the given value after n milliseconds.
+Creates a Future which resolves with the given value after n milliseconds.
 
@@ -126,3 +149,3 @@ ```js
 
-Cast any [Forkable](#forkable) to a [Future](#future).
+Cast any [Forkable](#type-signatures) to a [Future](#type-signatures).
 
@@ -148,4 +171,4 @@ ```js
 
-A constructor that creates a Future which resolves with the result of calling
-the given function, or rejects with the error thrown by the given function.
+Creates a Future which resolves with the result of calling the given function,
+or rejects with the error thrown by the given function.
 
@@ -163,7 +186,8 @@ Sugar for `Future.encase(f, undefined)`.
 
-A constructor that creates a Future which rejects with the first argument given
-to the function, or resolves with the second if the first is not present.
+Creates a Future which rejects with the first argument given to the function,
+or resolves with the second if the first is not present.
 
 This is a convenience for NodeJS users who wish to easily obtain a Future from
-a node style callback API.
+a node style callback API. To permanently turn a function into one that returns
+a Future, check out [futurization](#futurization).
 
@@ -220,24 +244,2 @@ ```js
 
-#### `cache :: Future a b -> Future a b`
-
-Returns a Future which caches the resolution value of the given Future so that
-whenever it's forked, it can load the value from cache rather than reexecuting
-the chain.
-
-```js
-const eventualPackage = Future.cache(
-  Future.node(done => {
-    console.log('Reading some big data');
-    fs.readFile('package.json', 'utf8', done)
-  })
-);
-
-eventualPackage.fork(console.error, console.log);
-//> "Reading some big data"
-//> "{...}"
-
-eventualPackage.fork(console.error, console.log);
-//> "{...}"
-```
-
 ### Method API
@@ -247,8 +249,7 @@
 
-Execute the Future (which up until now was merely a container for its
-computation), and get at the result or error.
+Execute the Future by calling the `fork` function that was passed to it at
+[construction](#creation) with the `reject` and `resolve` callbacks. Futures are
+*lazy*, which means even if you've `map`ped or `chain`ed over them, they'll do
+*nothing* if you don't eventually fork them.
 
-It is the return from Fantasy Land to the real world. This function best shows
-the fundamental difference between Promises and Futures.
-
 ```js
@@ -270,4 +271,8 @@ Future.of('world').fork(
 
-Map over the value inside the Future. If the Future is rejected, mapping is not
-performed.
+Transforms the resolution value inside the Future, and returns a new Future with
+the transformed value. This is like doing `promise.then(x => x + 1)`, except
+that it's lazy, so the transformation will not be applied before the Future is
+forked. The transformation is only applied to the resolution branch. So if the
+Future is rejected, the transformation is ignored. To learn more about the exact
+behaviour of `map`, check out its [spec][12].
 
@@ -283,4 +288,7 @@ ```js
 
-FlatMap over the value inside the Future. If the Future is rejected, chaining is
-not performed.
+Allows the creation of a new Future based on the resolution value. This is like
+doing `promise.then(x => Promise.resolve(x + 1))`, except that it's lazy, so the
+new Future will not be created until the other one is forked. The function is
+only ever applied to the resolution value, so is ignored when the Future was
+rejected. To learn more about the exact behaviour of `chain`, check out its [spec][13].
 
@@ -296,4 +304,4 @@ ```js
 
-FlatMap over the **rejection** value inside the Future. If the Future is
-resolved, chaining is not performed.
+Chain over the **rejection** reason of the Future. This is like `chain`, but for
+the rejection branch.
 
@@ -311,4 +319,7 @@ ```js
 
-Apply the value in the Future to the value in the given Future. If the Future is
-rejected, applying is not performed.
+Apply the resolution value, which is expected to be a function (as in
+`Future.of(a_function)`), to the resolution value in the given Future. Both
+Futures involved will run in parallel, and if one rejects the resulting Future
+will also be rejected. To learn more about the exact behaviour of `ap`, check
+out its [spec][14].
 
@@ -378,2 +389,24 @@ ```js
 
+#### `cache :: Future a b -> Future a b`
+
+Returns a Future which caches the resolution value of the given Future so that
+whenever it's forked, it can load the value from cache rather than reexecuting
+the chain.
+
+```js
+const eventualPackage = Future.cache(
+  Future.node(done => {
+    console.log('Reading some big data');
+    fs.readFile('package.json', 'utf8', done)
+  })
+);
+
+eventualPackage.fork(console.error, console.log);
+//> "Reading some big data"
+//> "{...}"
+
+eventualPackage.fork(console.error, console.log);
+//> "{...}"
+```
+
 #### `value :: Future a b ~> (b -> Void) -> Void`
@@ -474,2 +507,21 @@
 
+#### `promise :: Future a b -> Promise b a`
+
+Dispatches to the `promise` method.
+
+```js
+Future.promise(Future.after(300, 'Hello')).then(console.log);
+//> "Hello"
+```
+
+### Utility functions
+
+#### `isFuture :: a -> Boolean`
+
+Returns true for [Futures](#type-signatures) and false for everything else.
+
+#### `isForkable :: a -> Boolean`
+
+Returns true for [Forkables](#type-signatures) and false for everything else.
+
 ### Futurization
@@ -525,1 +577,2 @@
 [15]: https://github.com/Avaq/Fluture/wiki/Comparison-of-Future-Implementations
+[16]: https://github.com/fantasyland/fantasy-land#applicative

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

37088

increased by6.77%

Lines of code

470

increased by0.64%

Number of lines in readme file

562

increased by10.41%

Worsened metrics

Number of package files

4

decreased by-20%

No dependency changes