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.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.prototype._$flip() - returns a function whose arguments are reversed.

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

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.

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.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).

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.

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.

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.

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.

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

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.

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.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.

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.

_$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.

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

And I would use the module like any other:

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