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.