sn-core

sn-core
=======

Project Tin Functional Programming and Utility Functions

This module provides some basic functional programming and cross-environment
utilities.

Functional Programming Support
------------------------------

This is module adds a few functional programming primitives. They're no better
than ones provided by other packages, they're just in a format I like to use.

This module adds:

Function.prototype._$partial( args ) - this function returns a function
which pre-applies some number of arguments. Here's an example cribbed from
http://dailyjs.com/2012/09/14/functional-programming/ :

function add(x,y) { return x+y; };
var add_three = add.$_partial(3);
console.log( add_three(4) ); // this should print the number 7

Function.prototype._$compose( function ) - this function returns a function
which executes the base function (the thing you do the _$compose() on) on the
output of the function you pass as a parameter to _$compose(). Example:

function add2( x ) { return 2+x; }
function mult2( x ) { return 2*x; };
var add_then_mult = mult2._$compose( add2 );
console.log( add_then_mult( 7 ) ); // should print the number 18

Function.prototype._$flip() - returns a function whose arguments are
reversed.

function div(x,y) { return x/y; }
var recip = div._$flip();
console.log( div( 10, 5 ) ); // should print the number 2
console.log( recip( 10, 5 ) ); // should print the number 0.5

Function.prototype._$negate() returns a function whose value is
the logical negation of the original.

function isTwo( x ) { return 2 == x; }
var isNotTwo = isTwo._$negate();
console.log( isTwo( 1 ) ); // should print false
console.log( isTwo( 2 ) ); // should print true
console.log( isNotTwo( 1 ) ); // should print true
console.log( IsNotTwo( 2 ) ); // should print false

Array.prototype._$each(function) and Object.prototype._$each(function)
Iterates through array calling the function passed for each value passing
the element and the index as parameters. 'this' is set as the array
(or object).

Array.prototype._$map(function) and Object.prototype._$map(function)
Iterates through each element of the array (or object), creating a new array
(or object) whose elements are the contents of the original array passed
through the function provided.

Object.prototype._$fold( function, base ) Iterates through the object's members
combining the output of the value returned from the function provided with the
base value specified.

Array.prototype._$reverse() Returns a shallow copy of the reciever with it's
elements reversed. (Unlike Object.reverse(), it doesn't modify the receiver.)

Object.prototype._$all( function ) Returns true if the function provided returns
true when each of the members of the collection are passed as a parameter.

Object.prototype._$any( function ) Returns true if the function provided returns
true when at least one of the members of the collection are passed as a parameter.

Object.prototype._$none( function ) Returns true if the function provided returns
a false value when each of the members of the collection are passed as a parameter.

Object.prototype._$pluck( property ) Assumes the receiver is a collection of objects
and that each of those objects contains the property named as an argument to the pluck
call. The function returns an array of those properties plucked from the objects in
the collection.

var example = [
  { status: 200, body: "whatever" },
  { status: 201, body: "yeah. you're supposed to return a 201 when you create a new resource" },
  { status: 404, body: "not exactly found" }
];
// this will return the array [200, 201, 404]
example._$pluck( 'status' );

Function.prototype._$f() This is a dummy function for when you need something that's
definitely a function, but you don't want to really do anything. I sometimes use this
function to represent default null behaviors so i don't have to check if a function is
defined.

function _do_something( callback ) {
  var _callback = ('function'==typeof callback)?callback:_$f; // but look at _$g() below
  
  // do a whole bunch of stuff here
  return _callback();
}

Function.prototype._$g( function ) If the parameter passed is a function, that function
is returned. If it's not a function, _$f is returned. Useful for guaranteeing callbacks
are functions (instead of undefineds or objects).

function _do_something_else( callback ) {
  // do a whole bunch of stuff here
  return _$g( callback )();
}

Utility Functions
-----------------

Function.prototype._$punch( target, name ) Duck-punches a function into an existing
object, and makes it non-enumerable, non-configurable and non-writable.

( function( _f ) {
  for( var i in this ) {
    _f.apply( this, this[ i ] );
  }
} )._$punch( Object.prototype, '_$sortOfLikeTheEachFunction' );
{ a: "1", b: "2" }._$sortOfLikeTheEachFunction( function( e ) {
  console.log( "wubba! " + e );
} );

Object.prototype._$shallow( source ) (shallow) copies properties
from the source object into the receiver. This is a "shallow" copy of the first
level of properties. This doesn't create a new object, so properties
that are in the receiver, but aren't in the source are left alone.

var a = { a: { whatever: "dingo" }, b: 2, c: 3 };
a._$shallow( { a: { larb: "foo" }, z:26 } );
// a now looks like: {a: { larb: "foo" }, b: 2, c:3, z: 26}

Object.prototype._$merge( source ) Performs a recursive copy from
the source into the receiver. This is more like a "deep" copy. But like _$shallow,
it doesn't create a new object, so properties that are in the receiver, but aren't
in the source are left alone.

var a = { a: { whatever: "dingo" }, b: 2, c: 3 };
a._$shallow( { a: { larb: "foo" }, z:26 } );
// a now looks like: {a: { whatever: "dingo", larb: "foo" }, b: 2, c:3, z: 26}

Object.prototype._$get( path ) Traverses nested objects to return the value specified
by the path. If an element in the path doesn't exist, an empty object is used.

var a = { one: 1, two: { a: 2, b: 3 } };
console.log( a._$get( "one" ) ); // prints 1
console.log( a._$get( "two/a" ) ); // prints 2
console.log( a._$get( "three" ) ); // prints undefined
console.log( a._$get( "three/alpha" ) ); // prints undefined

Object.prototype._$put( path, value ) Traverses nested objects using the specified path,
setting the value given to the last element in the list.

var a = { one: 1, two: { a: 2, b: 3 } };
a._$put( "three/alpha", "dingo" );
console.log( a ); // prints out { one: 1, two: { a: 2, b: 3 }, three: { alpha: "dingo" } }

Callback Support
----------------

Number.prototype._$counter Returns a function that calls another function after N invocations.
This is useful when you want to process all items in a list with async calls, and then do something
else after they've all completed.

function _process( item, callback ) {
  setTimeout( function () {
    console.log( "processed: " + item );
    _$g( callback ) ();
  }, Math.random() * 10000 );
}
var a = [ 'one', 'two', 'three', 'four', 'five', 'six' ];
var begin = Date.now(), end;
var _post = a.length._$counter( function() {
  end = Date.now();
  console.log( "finished processing items at " + (new Date(end)).toString() );
  console.log( "took " + ( end - begin ) + " milliseconds." );
} );
console.log( "starting processing items at " + (new Date(begin)).toString() );
a._$each( function( e ) { _process( e, _post ); } );

Array.prototype._$sim( each_function, after_function ) Calls the first function on each
element in an array. After each function has called back, it calls the second function.

function _process( element, index, callback ) {
  setTimeout( function () {
    console.log( "processed: " + element + "(" + index + ")" );
    _$g( callback ) ();
  }, Math.random() * 10000 );
}
var a = [ 'zero', 'one', 'two', 'three', 'four', 'five', 'six' ];
var begin = Date.now(), end;
a._$sim( _process, function () {
  end = Date.now();
  console.log( "finished processing items at " + (new Date(end)).toString() );
  console.log( "took " + ( end - begin ) + " milliseconds." );
} );

Function.prototype._$capture Returns a version of a function that captures exceptions,
returning them as the first parameter to an error handling callback. This is useful if you're
using a function or library that throws exceptions, but you want to use it in an async
manner.

For example, consider the situation in node where you need to parse a JSON file read with
the async fs.readFile() function. The _$capture function lets you separate the logic for
processing processing the file from the logic of handling exceptions so the caller can
decide what action to take when there's an exception.

var fs = require( 'fs' );
var filepath = process.argv[2];
console.log( "processing file " + filepath );
fs.readFile( filepath, function( err, data ) {
  if( err ) { return console.log( "error reading file " + filepath + ": " + err.toString() ); }
  var parsed = JSON.parse( data.toString() );
  console.log( "oh look! parsed data:" );
  console.log( parsed );
  // continue processing
}._$capture( function( err ) {
  console.log( "error processing file " + filepath + ": " + err.toString() );
  // do whatever you need to do to recover from an error in the JSON file
} ) );

Cross-Environment Support
-------------------------

Object.prototype._$keys() It turns out that some JavaScript environments
don't provide Object.keys(). Who knew? This function is punched into Object's
prototype and calls Object.keys() if it's available or calls a local
implementation.

// this will return the array [ 'a', 'b', 'c' ]
{ a: "1", b: "2", c: "3" }._$keys();

_$construct( name, defaults, global ) constructs a constructor that takes an
object containing properties to initialize object instances with. If items in
the defaults objects are specified, they'll be copied from the defaults.

If you define the functions _$init or _$initAsync in the constructor's prototype,
the _$construct() constructor will call them immediately or via _$nextTick.

_$construct( 'SampleObject', { location: [ 0, 0 ], log: '/var/log/sample.log' } );
SampleObject.prototype._$init = function() {
  console.log( "SampleObject's _$init function" );
};
SampleObject.prototype._$initAsync = function( callback ) {
  callback = callback?callback:_$f;
  console.log( "SampleObject's _$initAsync function" );
  callback.call( this );
};
// This will create an object with the properties { location: [ 0, 0 ], log: '/var/log/sample.log' }
var foo = new SampleObject();
// This will create an object with properties { location: [ 0, 0 ], log: '/var/log/sample.log', title: 'whatever' }
var bar = new SampleObject( { title: 'whatever' } );
// This will create an object with properties { location: [ -10, 12 ], log: '/var/log/sample.log' }
var baz = new SampleObject( { location: [-10, 12] } );

A pattern I use frequently in node.js modules is something like this:

( function () {
  require( 'sn-core' );
  _$construct( 'exports', { / instance defaults go here / }, module };
  module.exports.prototype._$init = function () {
    // This function is called after defaults are applied.
  };
} ) ();

And I would use the module like any other:

var example = require( 'example' );
var whatever = new example( {a: 1, b:2} );

Function.prototype._$nextTick() Calls the recieving function after after the current run through the event loop.

var items = [];
function _log_this( param, value ) {
  console.log( "logging: " + ((param)?param.toString():"undefined") );
  items.push( value );
}
_log_this( "line 1", 33 );
_log_this._$nextTick( "line 3", 77 );
_log_this( "line 2", 44 );
// items will now contain [33, 44, 77]. 77 is at the end because _log_this( "line 3", 77 )
// is executed after _log_this( "line 2", 44 )