arlib

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'), or each component is loadable separately with eg require('arlib/tempnam').

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

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.

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

Tempnam() generates random filenames and retries on collision. The more files in the temp directory, the more chance of name collisions. Although up to 16 million (2^24) files are possible, the retry approach breaks down when close to the 16m limit (at 14 million it would take an average of 4 retries to find an unused name, still ok, but at 15 million 11, not ok). Note that 16 million files in a single directory is unmanageable; ls and echo * do not work, and it takes days to just delete them all off an ext3 filesystem with an opendir/readdir/unlink loop written in C.

getopt( argv, optspec )

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 )

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 )

return a formatted date string like PHP's date() does. Supports most of the conversions (but not the ISO-8601), though timezone and localization support is rather lacking. North America timezones should work.

See php's date for the list of supported conversions. Of the conversions as of 2014-09-15 (php 5.1.0), W and o are not yet implemented.

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

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

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

http_build_query( objectOrArray, options )

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

    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"

    var params = {d: {a: 1, b: 2, c: {a: 1, b: 2}}};
    var queryString = http_build_query(params, {leave_brackets: true});
    // => "d[a]=1&d[b]=2&d[c][a]=1&d[c][b]=2"

    var params = [1, 2, 3];
    var queryString = http_build_query(params, {numeric_prefix: 'idx'});
    // => "idx0=1&idx1=2&idx2=3"

options:

    arg_separator   '&'
    eq_sign         '='
    numeric_prefix  string to prepend to numeric keys
    encoding        'PHP_QUERY_RFC1738' (default) - encode spaces as '+'
                    'PHP_QUERY_RFC3986' - encode spaces as '%20'
    leave_brackets  encode {a:[3]} as "a[0]=3" and not "a%5B0%5D=3"