arlib

Andras' Library of Handy Utilities

This is a placeholder for some of the code I've been working on that I want easy access to. Feel free to browse and use!

Note: qfgets which first appeared here was moved into its own package.

Installation

    npm install arlib
    npm test arlib

Contents

The components are all available with require('arlib') as eg require('arlib').tempnam, or separately with eg require('arlib/tempnam').

tempnam( [directory], [prefix], [callback(err, filename)] )

tempnam from the tempnam package.

php tempnam equivalent, creates a filename that does not exist on the system. Like php, it also creates the file to prevent the name from being reused. The default directory is process.env.TMPDIR (else /tmp), and the default prefix is the empty string.

If the callback is omitted, tempnam returns a filename or an Error object.

    var tempnam = require('arlib/tempnam');
    tempnam("/tmp", "my-prefix-", function(err, filename) {
        // => /tmp/my-prefix-a7259b
    });

For full details, please see the package. Tempnam was originally published here, but was split out into its own package in arlib version 0.2.5.

getopt( argv, optspec )

getopt from the qgetopt package.

traditional unix command option extractor, returns an object with the options set as properties. Like traditional unix, getopt only checks for option switches at the beginning of the argument list, before non-switch arguments. It recognizes '-' as a filename and '--' as the special marker that stops further argument scanning.

    var getopt = require('arlib/getopt').getopt;
    var options = getopt(process.argv, "f:h");
    // { f: 'filename', h: true }
    var options = getopt(process.argv, "(-file):(-help)");
    // {file: 'filename', help: true}

mongoid( ), new MongoId().fetch( )

MongoId.getTimestamp( idString )

MongoId.parse( idString )

mongoid from the mongoid-js package.

very fast, light-weight mongodb compatible timestamped unique id generator. Can be used as a convenience function to return unique-ish (random) ids, or as an id factory configured with a unique system id to return locale-specific guaranteed unique ids.

The mongoid functionality of arlib was made into separate package, arlib now includes it as a dependency. See mongoid-js for details.

phpdate( format, [timestamp] )

phpdate from the phpdate-js package.

return a formatted date string like PHP's date() does. Supports all the php conversions, though timezone and localization support is very basic. North America timezones should work.

See php's date for the list of supported conversions. As of phpdate-js 1.0.0, all documented conversions are supported and work identically to php.

Format is the conversion specification. Each character is a time element spec or a literal. Backslash escaping inserts a literal instead of the converted time element. The timestamp is either a JavaScript millisecond timestamp or a Date object. If omitted, the current time Date.now() is used.

    var phpdate = require('arlib/phpdate');
    phpdate('Y-m-d H:i:s.u T');     // 2014-10-18 04:56:53.437000 EDT

    var gmdate = require('arlib/phpdate').gmdate;
    gmdate('Y-m-d H:i:s.u T');      // 2014-10-18 08:56:53.438000 GMT

Phpdate, originally included as part of arlib, was made into a separate package. Arlib now includes it as a dependency.

str_repeat( string, count )

return the string concatenated with itself count times. See php's str_repeat

    var str_repeat = require('arlib/str_repeat');
    str_repeat("x", 5);             // "xxxxx"

timeit( count, function, [message], [callback] )

qtimeit from the qtimeit package.

run the function count + 1 times, and print the run timings to the console. If function is a string it will be eval-d. The function under test is run twice to compile it (and not include the cost of compilation in the timings) and prime the node optimizer, then count times back-to-back for the benchmark.

    var timeit = require('arlib/timeit');
    var fs = require('fs');

    function opencloseSync() {
        var fd = fs.openSync('/etc/motd', 'r');
        fs.closeSync(fd);
    }
    timeit(10000, function(){ opencloseSync(); });
    // AR: "function (){ opencloseSync(); }": 10000 loops in 0.0210 sec:  475221.68 / sec, 0.00210 ms each

    function opencloseAsync(cb) {
        fs.open('/etc/motd', 'r', function(err, fd) {
            if (err) throw err;
            fs.close(fd, function(err) { cb(fd); });
        });
    }
    timeit(10000, function(cb){ opencloseAsync(function(){ cb(); }); }, "async open/close:", function(){ });
    // async open/close: "function (cb){ opencloseAsync(function(){ cb(); }); }": 10000 loops in 0.2890 sec:  34598.11 / sec, 0.02890 ms each

timeit.fptime( )

nanosecond-resolution floating-point timestamp from process.hrtime(). The timestamp returned does not have an absolute meaning (on Linux, it's uptime(1), the number of seconds since the last boot), but differeces between timestamp are accurate -- a difference of 1.00 is 1 elapsed second. The overhead is as low as .6 microseconds per call, about 3x slower than Date.now().

    var fptime = require('arlib/timeit').fptime
    var t1 = fptime();      // 1809688.215437152
    var t2 = fptime();      // 1809688.215462518
    var t3 = fptime();      // 1809688.215466353
    // 25.4 usec for the first call, 3.84 for the second
    // uptime of 20 days, 22:40 hours

timeit.bench( benchSuite [,callback] )

Run each of the functions in the suite and report timings and relative throughput. The suite can be an array of functions, or an object where the properties are test functions and the property names are the test names to report on.

http_build_query( queryParams, [options] )

http_build_query from the qhttp package.

format a query string like PHP's http_build_query. In particular, it handles nested objects and nested arrays.

This function was moved and is now republished from the qhttp package. Please see qhttp for details.

    var http_build_query = require('arlib/http_build_query');
    var params = {a: 1, b: 2, c: [3, 4, [5, 6]]};
    var queryString = http_build_query(params, {leave_brackets: true});
    // => "a=1&b=2&c[0]=3&c[1]=4&c[2][0]=5&c[2][1]=6"

http_parse_query( string )

http_parse_query from the qhttp package.

build up the parameters hash from the PHP-style query string. Parses name-value pairs as expected, a=1&b=2 is {a:1, b:2}. names value-less names as if set to one, i.e. a&b becomes {a:1, b:1}. Unlike PHP, gathers repeated parameters into arrays (e.g., a=1&a=2 is {a: [1, 2]} and not a=2. Like PHP, parses hierarchical values like a[i][j]=1 into {a: {i: {j:1}}}.

This function was moved and is now replushed from the qhttp package. Please see qhttp for details.

    var http_parse_query = require('arlib/http_parse_query');
    var params = http_parse_query("a=1&b=2&c[0]=3&c[1]=4&c[2][0]=5");
    // => {a:1, b:2, c:{'0':3, '1':4, '2':{'0':5}}}

getrusage

the unix getrusage(2) system call, from the qrusage package. See the package for details. The fields names have the ru_ stripped, and the struct timevals are combined into floating-point time values.

    var getrusage = require('arlib/getrusage');
    var usage = getrusage();

fptime

fptime from the qrusage package

the current microsecond precision timestamp as a floating point number. Analogous to the time(2) system call (implemented with gettimeofday(2)). Also from the qrusage package.

    var fptime = require('arlib/fptime');
    var timestamp = fptime();

Todo