utils-upsearch

Upsearch

Attempts to resolve a path by walking up from a specified directory.

Installation

$ npm install utils-upsearch

Usage

var upsearch = require( 'utils-upsearch' );

upsearch( path, [ options,] clbk )

Attempts to resolve a (file or directory) path by walking up from a specified directory.

upsearch( '.npmrc', done );
 
function done( error, path ) {
    if ( error ) {
        return console.error( error );
    }
    if ( path === null ) {
        return console.log( 'Unable to resolve path.' );
    }
    console.log( path );
    // returns /path/to/.npmrc
}

By default, the function begins searching in the current working directory. To begin searching from a different directory, set the dir option.

var opts = {
    'dir': '/path/to/a/directory'
};
 
upsearch( '.npmrc', opts, done );

upsearch.sync( path[, options] )

Synchronously attempts to resolve a (file or directory) path by walking up from a specified directory.

var path = upsearch.sync( '.npmrc' );
// returns /path/to/.npmrc

To begin searching from a particular directory, set the dir option.

var opts = {
    'dir': '/path/to/a/directory'
};
 
var path = upsearch.sync( '.npmrc', opts );
// returns /path/to/.npmrc

If unable to resolve a path, the method returns null.

var path = upsearch.sync( './../../non/existent/dir/or/file/path' );
// returns null

Examples

var readFile = require( 'utils-upsearch' );
 
// Sync:
var path = upsearch.sync( 'utils-upsearch', {
    'dir': __dirname
});
console.log( path );
// returns /path/to/utils-upsearch
 
path = upsearch.sync( 'non_existent_basename' );
console.log( path );
// returns null
 
 
// Async:
upsearch( '.npmrc', { 'dir': process.cwd() }, onPath );
upsearch( './../non_existent_path', onPath );
 
function onPath( error, path ) {
    if ( error ) {
        throw error;
    }
    console.log( path );
}

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

---

License

MIT license.

Copyright

Copyright © 2015-2016. Athan Reines.