Rod's Node.js Utilities
A small library of utility functions and classes, primarily intended for use within server-side JavaScript (CoffeeScript).
Installation
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" }
Use
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.
Documentation
Utility Methods
Util.file_to_array(filename,[options])
(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 notnull
(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
Util.trim(string)
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"
Util.object_to_array(object)
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] ] ]
Util.map_to_array(map)
Equivalent to object_to_array
.
Util.object_values(object)
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] ]
Util.frequency_count(array)
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
Util.comparator(a,b)
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
.
Util.sort_by_value(object,[comparator])
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
Util.sort_by_key(object,[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
Util.async_for_loop(init,cond,act,incr,done)
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). (Thinkvar i = 0
.)condition
- a predicate that is called before every iteration through the loop. When it returnstrue
, the loop will continue. Whenfalse
the loop is complete (anddone
will be called). (Thinki < 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 eachaction
but before the corresponding call tocondition
. (Thinki++
.)done
- called at the end of the loop (aftercondition
returnsfalse
)
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);
Util.async_for_each(list,action,,done)
Performs a generic asynchronous for-each loop.
Accepts three parameters:
list
- the collection to iterate overaction
- a function implementing the "inner loop" with the signatureaction(value,index,list,next)
, where:value
is the current value from the listindex
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)
Util.add_callback
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.
Stopwatch
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);
Legal Stuff
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.