jam 0.6.1 → 0.7.0

package/Makefile

@@ -1,67 +0,0 @@
-
-BIN := $(shell pwd)/node_modules/.bin
-
-GLOBALS := __coverage__,buffertools,SlowBuffer,events,util,task
-TEST_ENV := test
-
-# Project files definition
-TEST_FILES := $(wildcard test/**/*.js) $(wildcard test/*.js)
-LIB_FILES := $(wildcard lib/**/*.js) $(wildcard lib/*.js)
-COV_FILES := $(LIB_FILES:lib/%.js=lib-cov/%.js)
-
-INDEX_FILE = index.js
-MAIN_FILE = lib/jam.js
-
-# Test parameters so we can configure these via make
-TEST_TIMEOUT = 100
-TEST_REPORTER = list
-TDD_REPORTER = min
-COVER_REPORTER = mocha-istanbul
-
-# Command-line tools options
-MOCHA_OPTS = --bail --timeout $(TEST_TIMEOUT) --reporter $(TEST_REPORTER) --globals $(GLOBALS)
-MOCHA_TDD_OPTS = $(MOCHA_OPTS) --watch --reporter $(TDD_REPORTER)
-MOCHA_COVER_OPTS = $(MOCHA_OPTS) --reporter $(COVER_REPORTER)
-ISTANBUL_OPTS = instrument --variable global.__coverage__ --no-compact
-PLATO_OPTS = -d html-report/
-GROC_OPTS = -t lib/ -o doc/ --no-whitespace-after-token false --index $(MAIN_FILE)
-
-
-default: node_modules
-
-node_modules:
-	npm install
-
-# File transformations
-lib-cov/%.js: lib/%.js
-	@mkdir -p $(@D)
-	$(BIN)/istanbul $(ISTANBUL_OPTS) --output $@ $<
-
-
-# Testing
-test: node_modules
-	NODE_ENV=$(TEST_ENV) $(BIN)/mocha $(MOCHA_OPTS) $(TEST_FILES)
-tdd: node_modules
-	NODE_ENV=$(TEST_ENV) $(BIN)/mocha $(MOCHA_TDD_OPTS) $(TEST_FILES)
-
-
-# Code instrumentation
-instrument: node_modules $(COV_FILES)
-cover: instrument
-	NODE_ENV=$(TEST_ENV) JAM_COVER=1 $(BIN)/mocha $(MOCHA_COVER_OPTS) $(TEST_FILES)
-complex:
-	$(BIN)/plato $(PLATO_OPTS) $(LIB_FILES)
-
-doc:
-	$(BIN)/groc $(GROC_OPTS) $(LIB_FILES)
-
-
-# Cleans
-clean:
-	-rm -Rf lib-cov/
-	-rm -Rf html-report/
-	-rm -Rf doc/
-
-
-.PHONY: debug default test tdd clean doc doc-gh instrument cover complex
-

package/example/file1.txt

@@ -1 +0,0 @@
-a - First! I am the very very first file.

package/example/file2.txt

@@ -1 +0,0 @@
-b - I am the second file, residing in B. 2nd's not a bad place, ain't it?

package/example/file3.txt

@@ -1 +0,0 @@
-c - I'm the last one. I get to write the ending!

package/example/map.js

@@ -1,29 +0,0 @@
-
-var FILES = 'file1.txt,file2.txt,file3.txt'.split(',')
-  , jam = require('../lib/jam')
-  , fs = require('fs');
-
-// normal form
-var readFile = function(next, filename) { fs.readFile(filename, next); }
-  , catResult = function(next, result) {
-    process.stdout.write(result.join(''));
-    next();
-  };
-
-function normal(next) {
-  console.log("NORMAL FORM ::");
-  jam(jam.map(FILES, readFile))
-    (catResult)
-    (next);
-}
-
-function monad(next) {
-  console.log("MONAD FORM ::");
-  jam(jam.return(FILES))
-    (jam.map(readFile))
-    (catResult)
-    (next);
-}
-
-jam(normal)(monad)(function(e) { if (e) console.error(e); });
-

package/example/promise.js

@@ -1,21 +0,0 @@
-
-var FILES = 'file1.txt,file2.txt,file3.txt'.split(',')
-  , jam = require('../lib/jam')
-  , fs = require('fs');
-
-var chain = jam(jam.identity);
-
-FILES.forEach(function(filename) {
-  fs.readFile(filename, chain.promise());
-
-  chain(function(next, result) {
-    console.log("FILE: " + filename);
-    console.log(result.toString());
-    next();
-  });
-});
-
-chain(function(e) {
-  console.log("DONE.");
-});
-

package/index.js

@@ -1,6 +0,0 @@
-
-// index.js - Main application entrypoint
-module.exports = process.env.JAM_COVER ?
-  require('./lib-cov/jam') :
-  require('./lib/jam');
-

package/lib/jam.js

@@ -1,333 +0,0 @@
-
-// lib/jam.js - Main JAM entrypoint
-module.exports = (function() {
-
-  var assert = require('assert'), tick = null;
-
-  // Find out if we have setImmediate and fallback to setTimeout if necessary.
-  tick = typeof setImmediate === 'function' ?
-    setImmediate :
-    function(func) { setTimeout(func, 0); };
-
-  // # INTERNAL HELPERS
-
-  // Function and arguments helpers.
-  var toArgs = function(args) { return Array.prototype.slice.call(args); };
-
-  function replaceHead(args, newHead) {
-    args = toArgs(args);
-    if (!args.length) return [newHead];
-
-    args[0] = newHead;
-    return args;
-  }
-
-  function bind(func, context) {
-    return function() { return func.apply(context, arguments); };
-  }
-
-  // Common assertions
-  function ensureFunc(func, argName) {
-    assert(typeof func === 'function', argName + ' argument missing or not a function');
-  };
-
-  function ensureNum(num, argName) {
-    assert(typeof num === 'number', argName + ' argument missing or not a number');
-  };
-
-  function ensureArray(arr, argName) {
-    assert(arr && typeof arr === 'object' && typeof arr.length === 'number',
-      argName + ' argument missing or does not looks like an array');
-  };
-
-  // ---
-
-  // # HELPERS
-
-  // Additional functions that adds to the original jam function.
-  function includeHelpers(func) {
-
-    // ## jam.identity()
-
-    // Simple function that passes the values it receives to the next function.
-    // Useful if you need a `process.nextTick` inserted in-between your call chain.
-    func.identity = function(next) {
-      function _identity(next) {
-        var args = arguments;
-        tick(function() {
-          next.apply(this, replaceHead(args, null));
-        });
-      }
-
-      // This function can also be passed to jam verbatim.
-      return (typeof next === 'function') ?
-        _identity.apply(this, arguments) :
-        _identity;
-    };
-
-    // ## jam.nextTick()
-
-    // Alias for `.identity`. Use when you need a `process.nextTick` inserted in-between
-    // your call chain.
-    func.nextTick = func.identity
-
-    // ## jam.return( [args...] )
-
-    // Returns a set of values to the next function in the chain. Useful when you want to
-    // pass in the next function verbatim without wrapping it in a `function() { }` just
-    // to pass values into it.
-    func.return = function() {
-      var args = toArgs(arguments);
-      return function(next) {
-        args.unshift(null);
-        next.apply(this, args);
-      };
-    };
-
-    // ## jam.null()
-
-    // Similar to `.identity` but absorbs all arguments that has been passed to it and
-    // forward nothing to the next function. Effectively nullifying any arguments passed
-    // from previous jam call.
-    // 
-    // Like `jam.identity`, this function can be passed to the jam chain verbatim.
-    func.null = function(next) {
-      function _null(next) { next(); }
-
-      return (typeof next === 'function') ? _null.call(this, next) : _null;
-    };
-
-    // ## jam.call( function, [args...] )
-
-    // Convenience for calling functions that accepts arguments in standard node.js
-    // convention. Since jam insert `next` as first argument, most functions cannot be
-    // passed directly into the jam chain, thus this helper function.
-    // 
-    // If no `args` is given, this function passes arguments given to `next()` call from
-    // previous function directly to the function (with proper callback) placement).
-    // 
-    // Use this in combination with `jam.return` or `jam.null` if you want to control the
-    // arguments that are passed to the function.
-    func.call = function(func) {
-      ensureFunc(func, 'function');
-
-      var args = toArgs(arguments);
-      args.shift(); // func
-
-      if (args.length) { // use provided arguments
-        return function(next) {
-          args.push(next);
-          func.apply(this, args);
-        };
-
-      } else { // use passed-in arguments during chain resolution
-        return function(next) {
-          args = toArgs(arguments);
-          args.shift(); // move next to last position
-          args.push(next);
-
-          func.apply(this, args);
-        };
-      }
-    };
-
-    // ## jam.each( array, iterator( next, element, index ) )
-
-    // Execute the given `iterator` function for each element given in the `array`. The
-    // iterator is given a `next` function and the element to act on. The next step in the
-    // chain will receive the original array passed verbatim so you can chain multiple
-    // `.each` calls to act on the same array.
-    // 
-    // You can also pass `arguments` and `"strings"` as an array or you can omit the array
-    // entirely, in which case this method will assume that the previous chain step
-    // returns something that looks like an array as its first result.
-    // 
-    // Under the hood, a JAM step is added for each element. So the iterator will be
-    // called serially, one after another finish. A parallel version maybe added in the
-    // future.
-    func.each = function(array, iterator) {
-      if (typeof array === 'function') {
-        iterator = array;
-        array = null
-      } else {
-        ensureArray(array, 'array');
-      }
-
-      ensureFunc(iterator, 'iterator');
-
-      return function(next, array_) {
-        var arr = array || array_;
-
-        // Builds another JAM chain internally
-        var chain = jam(jam.identity)
-          , count = arr.length;
-
-        for (var i = 0; i < count; i++) (function(element, i) {
-          chain = chain(function(next) { iterator(next, element, i); });
-        })(arr[i], i);
-
-        chain = chain(function(next) { next(null, arr); });
-        return chain(next);
-      };
-    };
-
-    // ## jam.map( array, iterator( next, element, index ) )
-
-    // Works exactly like the `each` helper but if a value is passed to the iterator's
-    // `next` function, it is collected into a new array which will be passed to the next
-    // function in the JAM chain after `map`.
-    // 
-    // Like with `each`, you can omit the `array` input, in which case this method will
-    // assume that the previous chain step returns something that looks like an array as
-    // its first result.
-    func.map = function(array, iterator) {
-      if (typeof array === 'function') {
-        iterator = array;
-        array = null;
-      } else {
-        ensureArray(array, 'array');
-      }
-
-      ensureFunc(iterator, 'iterator');
-
-      return function(next, array_) {
-        var arr = array || array_;
-
-        // Builds another JAM chain internally and collect results.
-        // TODO: Dry with .each?
-        var chain = jam(jam.identity)
-          , count = arr.length
-          , result = [];
-
-        for (var i = 0; i < count; i++) (function(element, i) {
-          chain = chain(function(next, previous) {
-            result.push(previous);
-            iterator(next, element, i);
-          });
-        })(arr[i], i);
-
-        chain = chain(function(next, last) {
-          result.push(last);
-          result.shift(); // discard first undefined element
-          next(null, result);
-        });
-
-        return chain(next);
-      };
-    };
-
-    // ## jam.timeout( timeout )
-
-    // Pauses the chain for the specified `timeout` using `setTimeout`. Useful for
-    // inserting a delay in-between a long jam chain.
-    func.timeout = function(timeout) {
-      ensureNum(timeout, 'timeout');
-
-      return function(next) {
-        var args = replaceHead(arguments, null);
-        setTimeout(function() { next.apply(this, args); }, timeout);
-      };
-    };
-
-    // ## jam.promise( [chain] )
-
-    // Returns a JAM promise, useful when you are starting an asynchronous call outside of
-    // the JAM chain itself but wants the callback to call into the chain. In other words,
-    // this allow you to put a 'waiting point' (aka promise?) into existing JAM chain that
-    // waits for the initial call to finish and also pass any arguments passed to the
-    // callback to the next step in the JAM chain as well.
-    //
-    // This function will returns a callback that automatically bridges into the JAM
-    // chain. You can pass the returned callback to any asynchronous function and the JAM
-    // chain (at the point of calling .promise()) will wait for that asynchronous function
-    // to finish effectively creating a 'waiting point'.
-    //
-    // Additionally, any arguments passed to the callback are forwarded to the next call
-    // in the JAM chain as well. If errors are passed, then it is fast-forwarded to the
-    // last handler normally like normal JAM steps.
-    func.promise = function(chain) {
-      chain = typeof chain === 'function' ? chain : // chain is supplied
-        typeof this === 'function' ? this : // called from the chain variable
-        ensureFunc(chain, 'chain'); // fails
-
-      if (typeof chain === 'undefined' && typeof this === 'function') {
-        chain = this;
-      }
-
-      var args = null, next = null;
-
-      chain(function(next_) {
-        if (args) return next_.apply(this, args); // callback already called
-        next = next_; // wait for callback
-      });
-
-      return function() {
-        if (next) return next.apply(this, arguments); // chain promise already called
-        args = arguments; // wait for chain to call the promise
-      };
-    };
-
-    // TODO: noError() ? or absorbError()
-    return func;
-  };
-
-  // ---
-
-  // # JAM function
-
-  // Exported function starts the asynchronous call chain.
-  function jam(func, context) {
-    ensureFunc(func, 'function');
-
-    var steps = [];
-
-    // ##### Chain resolver.
-
-    // The resolver will execute all functions passed to the chain as soon as `nextTick`.
-    // Thus jam will not works across async context where the chain is not built all at
-    // once in a single event loop, which is not really a problem from my personal
-    // experience.
-    tick(function resolve(e) {
-      var args = Array.prototype.slice.call(arguments);
-
-      // Any errors passed to next() are (fast-)forwarded to the last function in the
-      // chain skipping any functions that's left to be executed.
-      if (e) return steps[steps.length - 1].apply(this, args);
-
-      // Any parameters given to next() are passed as arguments to the next function in
-      // the chain (except for errors, of course.)
-      var next = steps.shift()
-        , args = Array.prototype.slice.call(arguments)
-
-      if (steps.length) {
-        args.shift(); // error arg
-        args.unshift(resolve); // next() function
-      }
-
-      return next.apply(this, args);
-    });
-
-    // ##### Chain context continuation.
-
-    // Subsequent invocation of the function returned from the `jam` function simply adds
-    // the given function to the chain.
-    function continuable(func, context) {
-      ensureFunc(func, 'function');
-
-      if (context) { // TODO: Handle falsy things?
-        func = bind(func, context);
-      }
-
-      steps.push(func);
-      return continuable;
-    };
-
-    return includeHelpers(continuable(func, context));
-  };
-
-  // ---
-
-  return includeHelpers(jam);
-
-})();
-