rods-node-util

A collection of small utility methods.

Rod's Node.js Utilities

A small library of utility functions and classes, primarily intended for use within server-side JavaScript (CoffeeScript).

The module is published as rods-node-util on npm. It has no (runtime) external dependencies.

You can install rods-node-util directly through npm:

npm install rods-node-util -g

(omit the -g flag to install the module in a local node_modules directory rather than the global one).

or by adding it as a dependency in your package.json:

"dependencies": { "rods-node-util": "latest" }

To use the module, simply require it:

var Util = require('rods-node-util');
var hello = ' hello.  ';
console.log(hello);            // outputs: " hello.  "
console.log(Util.trim(hello)); // outputs: "hello."

See the test suite for more examples.

(Synchronously) convert the contents of the given file into to an array of lines.

var array = Util.file_to_array('MY-FILE.TXT');

An optional "options" map can be passed as a second argument to configure the behavior of the parsing.

  • When options.strip_blanks is true (the default), blank lines will be excluded from the output array.

  • When options.trim is true (the default), leading and trailing whitespace will be removed from each line

  • When options.comment_char is not null (the default is #), lines for which comment character is the first non-whitespace character will be excluded from the output array. (Note that currently a comment that appears at the end of the line isn't recognized. One can only comment out entire line at a time.) E.g.,

    # this is a comment
              # this is also a commment
    some text # this is NOT a comment
    

Removes leading and trailing whitespace from the given string.

Both vertical (\n, \r\f, etc.) and horizonal (\t, , etc.) whitespace are removed.

Util.trim("\t hello  \n");          // returns "hello"

Only the leading and trailing whitespace is removed. Whitespace that appears "within" the text of the string is left intact.

Util.trim("\t hello  \n\tworld \n") // returns "hello  \n\tworld"

Converts an object (map) into an array of name/value pairs, one for each attribute of the object.

var object = { foo: 'bar', height: 18, f: function() { return new Date(); } };
var array = Util.object_to_array(object);
console.log(array); 
// yields something like:
// [ [ 'foo', 'bar'], [ 'height', 18 ], [ 'f', [Function] ] ]

Equivalent to object_to_array.

Returns an array containing the value of each attribute in the given object. (Similiar to Object#keys, except returning values instead of keys.)

var object = { foo: 'bar', height: 18, f: function() { return new Date(); } };
var values = Util.object_values(object);
console.log(values); 
// yields something like:
// [ 'bar', 18, [Function] ]

Returns a map of all unique elements in the given array to the number of times they occur in the array.

var array = [ "two", "one", "two" ]
var freq = Util.frequency_count(array);
console.log(freq["one"]);   // yields 1
console.log(freq["two"]);   // yields 2
console.log(freq["three"]); // yields null

Returns a negative value if a < b, a postive value if a > b and 0 if a and b are equal.

Also see sort_by_value and sort_by_key.

Returns an array of name/value pairs, one for each attribute of the given object (map), ordered by value.

An optional comparator function may be provided as the second parameter. The default is Util.comparator

Returns an array of name/value pairs, one for each attribute of the given object (map), ordered by key.

An optional comparator function may be provided as the second parameter. The default is Util.comparator

Performs a generic asynchronous for loop.

Accepts five functions as parameters:

  • initialize - an initialization function that is called once (at the beginning of the loop). (Think var i = 0.)
  • condition - a predicate that is called before every iteration through the loop. When it returns true, the loop will continue. When false the loop is complete (and done will be called). (Think i < max.)
  • action - a function implementing the "inner loop". This method should accept a single argument, a callback function that should be invoked to continue executing the loop.
  • increment - called after each action but before the corresponding call to condition. (Think i++.)
  • done - called at the end of the loop (after condition returns false)

Only the action method accepts a parameter. Only the condition method returns a value.

For example, the simple loop:

for(var i=0; i<10; i++) { console.log(i); }
console.log("I'm done.");

could be implemented as:

var i = 0;
var init = function() { i = 0; };
var cond = function() { return i < 10; };
var actn = function(next) { console.log(i); next(); };
var incr = function() { i = i + 1; };
var done = function() { console.log("I'm done.");  };
Util.async_for_loop(init,cond,actn,incr,done);

Performs a generic asynchronous for-each loop.

Accepts three parameters:

  • list - the collection to iterate over
  • action - a function implementing the "inner loop" with the signature action(value,index,list,next), where:
    • value is the current value from the list
    • index is the numeric index of that value (possibly null)
    • list is the list itself (possibly null)
    • next is the callback function used to continue the iteration
  • done - a function that is called at the end of the loop

For example:

var list = [ 1, 2, 3, 4 ]
actn = function(value,index,list,next) { 
  console.log("The element #{value} is at position #{index}");
  next();
}
done = function() { }
Util.async_for_each(list,actn,done)

For a given synchronous function f, with the signature:

f(a,b,c,...)

returns a new function g, with the signature:

g(a,b,c,...,callback)

that is equivalent to:

callback(f(a,b,c,...));

The resulting method isn't asynchronous, but approximates the method signature and control flow used by asynchronous methods. This makes it easy to use a synchronous method where an asynchronous one is expected.

The Stopwatch provides a simple timer.

The Stopwatch can be used directly:

var timer = Util.Stopwatch.start();
doSomething();
timer.stop();
console.log("doSomething():");
console.log(" started at ",timer.start_time);   // start_time is a Date
console.log(" finished at ",timer.finish_time); // finish_time is a Date
console.log(" took ",timer.elapsed_time," milliseconds."); // elapsed_time is a number (finish_time - start_time)

It can also "wrap" a synchronous method call:

var timer = Util.Stopwatch.time_sync(doSomething);
console.log("doSomething():");
console.log(" started at ",timer.start_time);
console.log(" finished at ",timer.finish_time);
console.log(" took ",timer.elapsed_time," milliseconds.");

or an asynchronous method call:

var report = function (timer) {
  console.log("doSomething():");
  console.log(" started at ",timer.start_time);
  console.log(" finished at ",timer.finish_time);
  console.log(" took ",timer.elapsed_time," milliseconds.");
}
Util.Stopwatch.time_async(doSomething,report);

This software and associated materials are made available under the terms of the Apache License, Version 2.0, an OSD-compliant, non-viral, open source license. Use it in good health.

See the license.txt file for details.