ruby-wisp-source 0.7.0

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/Readme.md

@@ -0,0 +1,253 @@
+# reducers
+
+[![Build Status](https://secure.travis-ci.org/Gozala/reducers.png)](http://travis-ci.org/Gozala/reducers)
+
+Library for higher-order manipulation of collections, based upon [reduce][].
+
+## Rationale
+
+Most functional languages (including beloved JS) typically come with some
+collection transformation functions like [filter][] and [map][] that take a
+logical collections and return transformed version of it. Unfortunately they
+tend to [complect][], by implying mechanism, order, laziness and
+representation. This library is an attempt to provide simple solution for
+some of the hard problems by decomplecting and building upon simple premise -
+minimum definition of collection is something that is reducible.
+
+More specifically library defines super-generalized and minimal abstraction for
+collections - a collection is some set of things that, when given a function to
+apply to its contents, can do so and give you the result, i.e. a collection is
+(at minimum) **reducible**. In other words, you can call `reduce` on it.
+
+A very minimal abstraction for collection is more powerful than it may seem at
+first!
+
+## Basics
+
+Demonstration of features of this library requires some basic understanding of
+the abstraction above. So let's take a more practical look at the idea. Let's
+say we have a `reduce` function with *(very familiar)* API:
+
+```js
+reduce(source, f, initial) // => accumulated result
+```
+
+It takes reducing function, a reducible `source` and `initial` value to
+accumulate reductions upon. In return it outputs an accumulated result.
+Reducing functions performing accumulation have a following shape:
+
+```js
+f(result, value) // => new result
+```
+
+A reducing function is simply a binary function, akin to the one you might pass
+to reduce. While the two arguments might be treated symmetrically by the
+function, there is an implied semantic that distinguishes the arguments:
+the first argument is a `result` or accumulator that is being built up by the
+reduction, while the second is some new input `value` from the source being
+reduced.
+
+## Transformations
+
+All of the collection operations can be expressed in terms of transformations.
+By the definition all transformations will produce **reducible** collections
+that can be reduced via `reduce` function defined above:
+
+```js
+map(source, JSON.parse) // => reducible collection
+filter(numbers, isEven) // => reducible collection
+```
+
+In order to explain transformations we'll need a primitive API for producing
+**reducible** collections. Let's define one in form of `reducible` function
+that takes `accumulator` function and returns something that can be reduced
+via `reduce` function:
+
+
+```js
+reducible(accumulator) // => reducible
+```
+
+Argument it takes, `accumulator` is a function that performs has following shape:
+
+```js
+accumulate(next, initial) // => accumulated result
+```
+
+And when invoked it performs reductions via `next` reducing function starting
+from `initial` result.
+
+
+Now consider following implementation of `map` & `filter` transformation
+functions:
+
+```js
+function map(f, source) {
+  return reducible(function accumulator(next, initial) {
+    return reduce(source, function reducer(result, input) {
+      return next(result, f(input))
+    }, initial)
+  })
+}
+
+function filter(predicate, source) {
+  return reducible(function accumulator(next, initial) {
+    return reduce(source, function reducer(result, input) {
+      return predicate(input) ? next(result, input) : result
+    }, initial)
+  })
+}
+```
+
+There are a few things to note here:
+
+  - Type of the source is irrelevant as long as it is reducible and there for
+    can be reduced via `reduce` function.
+  - Transformations do not traverse collections, instead they compose results
+    that can be reduced by a receiver of the result later.
+  - Transformations do not imply timing in which `reducer` in invoked with an
+    each `input` of the `source`, there for `source` can be asynchronous.
+  - Filtering can *skip* inputs by simply returning the incoming result.
+
+
+## Features
+
+### Laziness
+
+Library consists of transformation functions which, as seen above, when called
+do nothing except the creation of a recipe for a new collection, a recipe that
+is itself reducible. No work is done yet to the contained elements and no
+concrete collection is produced. All the transformations defer actual work
+to a point where result of transformations pipeline is being reduced.
+
+The beautiful thing is that this mechanism also works for all other traditional
+transformations `take`, `drop`, `merge` etc. Note the fact that `filter` is
+(potentially) contractive, and flatten is (potentially) expansive per step -
+the mechanism is general and not limited to 1:1 transformations.
+
+### Uniformity
+
+Transformation functions are absolutely agnostic of the actual type of the
+`source`, as they just describe transformations and leave it up to `source`
+to do a reduction when result is consumed.
+
+Library takes a advantage of this feature and takes it even step further by
+treating every possible value as a reducible collection. Non collection values
+like numbers, booleans, objects etc. are treated as collection of single item,
+item being a value. Also `null` and `undefined` are considered as empty
+collections.
+
+This means that library can be used on any data type and more importantly
+transformations between different data types & compose naturally, which is
+great, let's you define logic in terms of abstractions instead of specific
+types.
+
+### Composability
+
+All the transformations are fully composable as a matter of fact transformation
+pipelines produce compositions equivalent of a function compositions created by
+a [compose][]. Also type agnostic nature of the transformation functions enables
+compositions between different types of data.
+
+### Performance
+
+Since transformations doesn't do the work, but merely create a recipe, there is
+no per-step allocation overhead, so it's faster. Also note that transformations
+are composed by curring transformation functions and all the actual work happens
+in a pipe line at the end when result is consumed, which means that no
+intermediate collections are produced, unlike it's a case with arrays etc..
+
+Think [monad][] & [category theory][] if you fancy that.
+
+It can even [outperform arrays][benchmarks] when used wisely, although it's not
+the point & arrays are not the primary use case.
+
+### Asynchronicity
+
+As it was already pointed out transformation functions do not imply any timing
+of individual value delivery, which means they can be used on asynchronous
+data structures like [node streams][stream-reduce] or [FRP][] events & signals.
+
+This feature is extremely powerful as it allows structuring complex asynchronous
+programs in simple intuitive code without a [callback hell][] and manual error
+propagation. _See [lstree][] for examples_.
+
+Even better actually exact same code can be used with both synchronous and
+asynchronous data structures. For example exact same code in [fs-reduce][]
+can be forced to do blocking IO by via `options.sync` option.
+
+### Extensibility
+
+Since transformations are `source` type agnostic it's highly extensible. In
+fact implementation is based of polymorphic [method][] dispatch library and
+enables one to add support for new data types without any changes to this
+library or data types / classes them self. This feature is used by
+[stream-reduce][] library to add support for node streams. There are more
+examples of this feature in [callback-reduce][], [dom-reduce][],
+[http-reduce][]...
+
+Very likely all data types like `signal` provided by this library will be move
+out into own libraries too.
+
+### Automatic disposal
+
+Reducible data structures feature auto cleanup of the resources at the end of
+consumption. For example [dom-reduce][] and [fs-reduce][] use this feature to
+remove event listeners / close file descriptors once input is consumed and to
+set you free from clean up constraints. This means you spend more time on
+actual problems rather and less on plumbing.
+
+### Infinity
+
+Infinite data structures can be trivially represented via reducibles since
+nothing implies the end. In fact [dom-reduce][] uses this feature to represent
+user events in form of reducibles that pretty much can be infinite.
+
+That being said reducibles are not the best abstraction for the some types of
+infinite data structures specially ones that rather better be polled instead.
+
+## F.A.Q.
+
+
+##### 1. Q: Can this handle "back pressure" ?  
+   
+**A:** Short answer is **Yes**.
+
+See [IO Coordination] for more detailed answer
+
+
+
+
+## Install
+
+    npm install reducers
+
+## Prior art
+
+- [Clojure reducers][]
+- [Haskell Enumerator/Iteratee][]
+
+[Clojure reducers]:http://clojure.com/blog/2012/05/15/anatomy-of-reducer.html
+[Haskell Enumerator/Iteratee]:http://www.haskell.org/haskellwiki/Enumerator_and_iteratee
+
+[reduce]:http://en.wikipedia.org/wiki/Reduce_%28higher-order_function%29
+[map reduce]:http://en.wikipedia.org/wiki/MapReduce
+[map]:https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/map
+[filter]:https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/filter
+[Uniformity]:http://en.wikipedia.org/wiki/Uniformity_%28complexity%29#Uniformity
+[complect]:http://www.infoq.com/presentations/Simple-Made-Easy
+[compose]:http://underscorejs.org/#compose
+[monad]:http://en.wikipedia.org/wiki/Monad_%28category_theory%29
+[Category theory]:http://en.wikipedia.org/wiki/Category_theory]
+[benchmarks]:http://jsperf.com/reducibles/4
+[stream-reduce]:https://github.com/Gozala/stream-reduce
+[FRP]:http://en.wikipedia.org/wiki/Functional_reactive_programming
+[method]:https://github.com/Gozala/method
+[callback-reduce]:https://github.com/Gozala/callback-reduce
+[dom-reduce]:https://github.com/Gozala/dom-reduce
+[http-reduce]:https://github.com/Gozala/http-reduce
+[callback hell]:http://callbackhell.com/
+[fs-reduce]:https://github.com/Gozala/fs-reduce
+[lstree]:https://github.com/Gozala/callback-reduce
+
+[IO Coordination]:https://github.com/Gozala/reducers/wiki/IO-Coordination

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/capture.js

@@ -0,0 +1,34 @@
+"use strict";
+
+var reducible = require("reducible/reducible")
+var reduce = require("reducible/reduce")
+var reduced = require("reducible/reduced")
+var isError = require("reducible/is-error")
+
+function capture(source, recover) {
+  /**
+  Creates and returns safe version of given `source` sequence, by using
+  `recover` function to recover from errors that may occur while reducing
+  a `source`. This is a mechanism for error handling and recovery for streams
+  that representing IO operations like (XHR / WebSockets etc...) where errors
+  may occur.
+  **/
+  return reducible(function reduceCapture(next, initial) {
+    var failure = void(0)
+    reduce(source, function reduceCaptureSource(value, result) {
+      // If error has already being captured then return
+      if (failure) return failure
+      // If value is an error then continue accumulation of recovered
+      // sequence.
+      else if (isError(value)) {
+        failure = reduced(result)
+        reduce(recover(value, result), next, result)
+        return failure
+      }
+      // Otherwise just forward messages.
+      else return next(value, result)
+    }, initial)
+  })
+}
+
+module.exports = capture

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/concat.js

@@ -0,0 +1,37 @@
+"use strict";
+
+var reducible = require("reducible/reducible")
+var reduce = require("reducible/reduce")
+var end = require("reducible/end")
+
+var slicer = Array.prototype.slice
+
+function append(left, right) {
+  /**
+  Returns sequences of items in the `left` sequence followed by the
+  items in the `right` sequence.
+  **/
+  return reducible(function reduceConcatination(next, initial) {
+    reduce(left, function reduceLeft(value, result) {
+      return value === end ? reduce(right, next, result) :
+             next(value, result)
+    }, initial)
+  })
+}
+
+function concat(left, right /*, ...rest*/) {
+  /**
+  Returns a sequence representing the concatenation of the elements in the
+  supplied arguments, in the given order.
+
+  print(concat([ 1 ], [ 2, 3 ], [ 4, 5, 6 ])) // => <stream 1 2 3 4 5 6 />
+
+  **/
+  switch (arguments.length) {
+    case 1: return left
+    case 2: return append(left, right)
+    default: return slicer.call(arguments).reduce(append)
+  }
+}
+
+module.exports = concat

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/debug/print.js

@@ -0,0 +1,45 @@
+"use strict";
+
+var reduce = require("reducible/reduce")
+var reducible = require("reducible/reducible")
+var end = require("reducible/end")
+var isError = require("reducible/is-error")
+
+var PREFIX = "\u200B"
+var OPEN = PREFIX + "< "
+var CLOSE = PREFIX + ">\n"
+var ERROR = PREFIX + "\u26A1 "
+var DELIMITER = PREFIX + " "
+
+var SPECIALS = [ OPEN, CLOSE, ERROR, DELIMITER ]
+
+var write = (function() {
+  if (typeof(process) !== "undefined" &&
+      typeof(process.stdout) !== "undefined" &&
+      typeof(process.stdout.write) === "function") {
+    var inspect = require("util").inspect
+    var slicer = Array.prototype.slice
+    return function write() {
+      var message = slicer.call(arguments).map(function($) {
+        return SPECIALS.indexOf($) >= 0 ? $ : inspect($)
+      }).join("")
+      process.stdout.write(message)
+    }
+  } else {
+    return console.log.bind(console)
+  }
+})()
+
+function print(source) {
+  var open = false
+  reduce(source, function reducePrintSource(value) {
+    if (!open) write(OPEN)
+    open = true
+
+    if (value === end) write(CLOSE)
+    else if (isError(value)) write(ERROR, value, DELIMITER, CLOSE)
+    else write(value, DELIMITER)
+  })
+}
+
+module.exports = print

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/delay.js

@@ -0,0 +1,29 @@
+"use strict";
+
+var reducible = require("reducible/reducible")
+var reduce = require("reducible/reduce")
+var isReduced = require("reducible/is-reduced")
+var end = require("reducible/end")
+
+function delay(source, ms) {
+  ms = ms || 6 // Minimum 6ms, as on less dispatch order becomes unreliable
+  return reducible(function reduceDelayed(next, result) {
+    var timeout = 0
+    var ended = false
+    reduce(source, function reduceDelaySource(value) {
+      setTimeout(function delayed() {
+        if (!ended) {
+          timeout = timeout - ms
+          result = next(value, result)
+          if (isReduced(result)) {
+            ended = true
+            next(end)
+          }
+        }
+      }, timeout = timeout + ms)
+      return result
+    })
+  })
+}
+
+module.exports = delay

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/drop-while.js

@@ -0,0 +1,39 @@
+"use strict";
+
+var reducible = require("reducible/reducible")
+var reduce = require("reducible/reduce")
+var isError = require("reducible/is-error")
+var end = require("reducible/end")
+
+function dropWhile(source, predicate) {
+  /**
+  Returns a sequence of the items in `source` starting from the first
+  item for which `predicate(item)` returns `false`.
+
+  ## Example
+
+  var numbers = dropWhile([ 2, 7, 10, 23 ], function(value) {
+    return value < 10
+  })
+  print(numbers)   // => < 10 23 >
+  **/
+  return reducible(function reduceDropWhile(next, initial) {
+    var dropped = false
+    reduce(source, function reduceDropWhileSource(value, result) {
+      // If value is end of collection or is an error (which also includes
+      // end of collection) just pass it through, `reducible` will take care
+      // of everything.
+      if (value === end) return next(value, result)
+      if (isError(value)) return next(value, result)
+
+      // If already dropped all the intended items (if `dropped` is already
+      // being set to `true` or if current predicate returns `false`). Then
+      // just keep on passing values.
+      if (dropped || (dropped = !predicate(value))) return next(value, result)
+
+      return result
+    }, initial)
+  })
+}
+
+module.exports = dropWhile

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/drop.js

@@ -0,0 +1,40 @@
+"use strict";
+
+var reducible = require("reducible/reducible")
+var reduce = require("reducible/reduce")
+var isError = require("reducible/is-error")
+var end = require("reducible/end")
+
+function drop(source, n) {
+  /**
+  Returns sequence of all `source`'s items after `n`-th one. If source contains
+  less then `n` items empty sequence is returned.
+
+  ## Example
+
+  print(drop([ 1, 2, 3, 4 ], 2))  // => <stream 3 4 />
+  print(drop([ 1, 2, 3 ], 5))     // => <stream />
+  **/
+
+  // If drop `<= 0` then optimize by returning source itself. If `Infinity`
+  // return empty.
+  if (n <= 0) return source
+  if (n === Infinity) return void(0)
+  return reducible(function reduceDrop(next, initial) {
+    var count = n
+    reduce(source, function reduceDropSource(value, result) {
+      // If value is end of collection or is an error (which also includes
+      // end of collection) just pass it through, `reducible` will take care
+      // of everything.
+      if (value === end) return next(value, result)
+      if (isError(value)) return next(value, result)
+      // If count of items has reached `0` just keep on passing values.
+      if (count === 0) return next(value, result)
+      // Otherwise just decrement count and return `result`.
+      count = count - 1
+      return result
+    }, initial)
+  })
+}
+
+module.exports = drop

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/expand.js

@@ -0,0 +1,25 @@
+"use strict";
+
+var merge = require("./merge")
+var map = require("./map")
+
+function expand(source, f) {
+  /**
+  Takes `source` sequence maps each item via `f` to a new sequence
+  and then flattens them down into single form sequence. Note that
+  returned sequence will have items ordered by time and not by index,
+  if you wish opposite you need to force sequential order by wrapping
+  `source` into `sequential` before passing it.
+
+  ## Example
+
+  var sequence = expand([ 1, 2, 3 ], function(x) {
+    return [ x, x * x ]
+  })
+  print(sequence)   // => < 1 1 2 4 3 9 >
+
+  **/
+  return merge(map(source, f))
+}
+
+module.exports = expand

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/filter.js

@@ -0,0 +1,21 @@
+"use strict";
+
+var reducer = require("./reducer")
+
+var filter = reducer(function filter(predicate, next, value, result) {
+  /**
+  Composes filtered version of given `source`, such that only items contained
+  will be once on which `f(item)` was `true`.
+
+  ## Example
+
+  var digits = filter([ 10, 23, 2, 7, 17 ], function(value) {
+    return value >= 0 && value <= 9
+  })
+  print(digits) // => < 2 7 >
+  **/
+  return predicate(value) ? next(value, result) :
+         result
+})
+
+module.exports = filter

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/fold.js

@@ -0,0 +1,55 @@
+"use strict";
+
+var reduce = require("reducible/reduce")
+var isError = require("reducible/is-error")
+var isReduced = require("reducible/is-reduced")
+var end = require("reducible/end")
+var hub = require("./hub")
+
+function Promise() {
+  this.delivered = false
+  this.next = void(0)
+  this.initial = void(0)
+}
+reduce.define(Promise, function reducePromise(promise, next, initial) {
+  if (promise.delivered) return reduce(promise.value, next, initial)
+  promise.next = next
+  promise.initial = initial
+})
+
+function deliver(promise, value) {
+  promise.delivered = true
+  promise.value = value
+  if (promise.next) reduce(value, promise.next, promise.initial)
+}
+
+
+function fold(source, next, initial) {
+  /**
+  Fold is just like `reduce` with a difference that `next` reducer / folder
+  function it takes has it's parameters reversed. One always needs `value`,
+  but not always accumulated one. To avoid conflict with array `reduce` we
+  have a `fold`.
+  **/
+  var promise = new Promise()
+  reduce(source, function fold(value, state) {
+    // If source is `end`-ed deliver accumulated `state`.
+    // If is source has an error, deliver that.
+    if (isError(value)) {
+      deliver(promise, value)
+      throw value
+    }
+    if (value === end) return deliver(promise, state)
+
+    // Accumulate new `state`
+    state = next(value, state)
+    // If already reduced, then deliver.
+    if (isReduced(state)) deliver(promise, state.value)
+
+    return state
+  }, initial)
+
+  return promise.delivered ? promise.value : hub(promise)
+}
+
+module.exports = fold

data/vendor/node_modules/wisp/interactivate/node_modules/interactivate/node_modules/reducers/hub.js

@@ -0,0 +1,102 @@
+"use strict";
+
+var reduce = require("reducible/reduce")
+var reduced = require("reducible/reduced")
+var isReduced = require("reducible/is-reduced")
+var end = require("reducible/end")
+
+var input = "input@" + module.id
+var consumers = "consumers@" + module.id
+
+
+var isArray = Array.isArray
+
+function Hub(source) {
+  this[input] = source
+  this[consumers] = []
+}
+
+reduce.define(Hub, function reduceHub(hub, next, initial) {
+  // Enqueue new consumer into consumers array so that new
+  // values will be delegated to it.
+  hub[consumers].push({ next: next, state: initial })
+  // If source is not in the process of consumption than
+  // start it up.
+  if (!isOpen(hub)) open(hub)
+})
+
+function drain(consumers) {
+  while (consumers.length) {
+    var count = consumers.length
+    var index = 0
+    while (index < count) {
+      var consumer = consumers[index]
+      consumer.next(end, consumer.state)
+      index = index + 1
+    }
+    consumers.splice(0, count)
+  }
+}
+
+function dispatch(consumers, value) {
+  var count = consumers.length
+  var index = 0
+  while (index < count) {
+    var consumer = consumers[index]
+    var state = consumer.next(value, consumer.state)
+    // If consumer has finished accumulation remove it from the consumers
+    // list. And dispatch end of stream on it (maybe that should not be
+    // necessary).
+    if (isReduced(state)) {
+      consumers.splice(index, 1)
+      consumer.next(end, state.value)
+      // If consumer is removed than we decrease count as consumers array
+      // will contain less elements (unless of course more elements were
+      // added but we would like to ignore those).
+      count = count - 1
+    } else {
+      consumer.state = state
+      index = index + 1
+    }
+  }
+}
+
+function open(hub) {
+  var source = hub[input]
+  var reducers = hub[consumers]
+  hub[input] = null         // mark hub as open
+  reduce(source, function distribute(value) {
+    // If it's end of the source we close all the reducers including
+    // ones that subscribe as side effect.
+    if (value === end) drain(reducers)
+    // otherwise we dispatch value to all the registered reducers.
+    else dispatch(reducers, value)
+
+    // reducers will be empty if either source is drained or if all the
+    // reducers finished reductions. Either way we reset input back to
+    // source and return `reduced` marker to stop the reduction of
+    // source.
+    if (reducers.length === 0) {
+      hub[input] = source
+      return reduced()
+    }
+  })
+}
+
+function isOpen(hub) {
+  return hub[input] === null
+}
+
+function hub(source) {
+  /**
+  Take a reducible `source`, such as a `signal` and return a reducible that can
+  be consumed by many reducers.
+  **/
+  if (source === null) return null
+  if (source === void(0)) return null
+  return new Hub(source)
+}
+hub.isOpen = isOpen
+hub.type = Hub
+
+module.exports = hub