utils-fs-exists v1.0.1

Exists

Tests whether a path exists on the filesystem.

Installation

$ npm install utils-fs-exists

Usage

var exists = require( 'utils-fs-exists' );

exists( path, clbk )

Tests whether a path exists on the filesystem.

exists( __dirname, done );

function done( bool ) {
	if ( bool ) {
		console.log( '...path exists.' );
	} else {
		console.log( '...path does not exist.' );
	}
}

The above callback signature matches the now deprecated fs.exists() API. The function also accepts the more conventional error-first style callback signature found in most asynchronous Node APIs.

exists( __dirname, done );

function done( error, bool ) {
	if ( error ) {
		console.error( error );
	}
	if ( bool ) {
		console.log( '...path exists.' );
	} else {
		console.log( '...path does not exist.' );
	}
}

exists.sync( path )

Synchronously tests whether a path exists on the fileystem.

var bool = exists.sync( __dirname );
// returns <boolean>

Notes

• The following is considered an anti-pattern:

  var fs = require( 'fs' ),
  	path = require( 'path' );
  
  var file = path.join( __dirname, 'foo.js' );
  if ( exists.sync( __dirname ) ) {
  	file = fs.readFileSync( file );
  }

  Because time elapses between checking for existence and performing IO, at the time IO is performed, the path can no longer be guaranteed to exist. In other words, here, a race condition exists between the process attempting to read and another process attempting to delete.

  Instead, the following pattern is preferred, where errors are handled explicitly:

  var fs = require( 'fs' ),
  	path = require( 'path' );
  
  var file = path.join( __dirname, 'foo.js' );
  try {
  	file = fs.readFileSync( file );
  } catch ( error ) {
  	console.log( 'unable to read file.' );
  	console.error( error );
  }

• Nevertheless, use cases exist where one desires to check existence without performing IO. For example,

  var fs = require( 'fs' ),
  	path = require( 'path' );
  
  var file = path.join( __dirname, 'foo.js' );
  if ( exists.sync( file ) ) {
  	console.log( 'Don\'t overwrite the file!' );
  } else {
  	fs.writeFileSync( file, 'beep', {
  		'encoding': 'utf8'
  	});
  }

Examples

var exists = require( 'utils-fs-exists' );

// Sync:
console.log( exists.sync( __dirname ) );
// returns true

console.log( exists.sync( 'beepboop' ) );
// returns false


// Async:
exists( __dirname, done );
exists( 'beepboop', done );

function done( error, bool ) {
	if ( error ) {
		console.error( error.message );
	} else {
		console.log( bool );
	}
}

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. Athan Reines.