Merge pull request #24 from gjtorikian/make-an-async

Improved sync/async API

README.md

@@ -1,13 +1,13 @@
 # isBinaryFile
+
 Detects if a file is binary in Node.js. Similar to [Perl's `-B` switch](http://stackoverflow.com/questions/899206/how-does-perl-know-a-file-is-binary), in that:
 - it reads the first few thousand bytes of a file
 - checks for a `null` byte; if it's found, it's binary
-- flags non-ASCII characters. After a certain number of "weird" characters, the
-- file is flagged as binary
+- flags non-ASCII characters. After a certain number of "weird" characters, the file is flagged as binary
 
-All the logic is also pretty much ported from [ag](https://github.com/ggreer/the_silver_searcher).
+Much of the logic is pretty much ported from [ag](https://github.com/ggreer/the_silver_searcher).
 
-Note: if the file doesn't exist or it is empty, this function returns `false`.
+Note: if the file doesn't exist, is a directory, or is empty, the function returns `false`.
 
 ## Installation
 
@@ -16,7 +16,38 @@ npm install isbinaryfile
 ```
 
 ## Usage
-If you pass in one argument, this module assumes it's just the file path, and performs the appropriate file read and stat functionality internally, as sync options:
+
+### isBinaryFile(filepath, callback)
+
+* `filepath`, a `string` indicating the path to the file.
+* `callback`, a `function` for the callback. It has two arguments:
+  - `err`, the typical Node.js error argument
+  - `result`, a `boolean` of `true` or `false`, depending on if the file is binary
+
+
+### isBinaryFile(bytes, size, callback)
+
+* `bytes`, an `number` indicating the size of the file.
+* `size`, an optional `number` indicating the file size.
+* `callback`, a `function` for the callback. It has two arguments:
+  - `err`, the typical Node.js error argument
+  - `result`, a `boolean` of `true` or `false`, depending on if the file is binary
+
+
+### isBinaryFile.sync(filepath)
+
+* `filepath`, a `string` indicating the path to the file.
+
+
+### isBinaryFile.sync(bytes, size)
+
+* `bytes`, an `number` indicating the size of the file.
+* `size`, an `number` indicating the file size.
+
+
+Returns a `boolean` of `true` or `false`, depending on if the file is binary.
+
+### Examples
 
 ```javascript
 var isBinaryFile = require("isbinaryfile");
@@ -25,13 +56,7 @@ if (isBinaryFile(process.argv[2]))
   console.log("It is!")
 else
   console.log("No.")
-```
-
-Ta da.
-
-However, if you've already read and `stat()`-ed a file (for some other reason), you can pass in both the file's raw data and the stat's `size` info to save time:
 
-```javascript
 fs.readFile(process.argv[2], function(err, data) {
   fs.lstat(process.argv[2], function(err, stat) {
     if (isBinaryFile(data, stat.size))
@@ -40,29 +65,12 @@ fs.readFile(process.argv[2], function(err, data) {
       console.log("No.")
   });
 });
-```
-
-### Async
-Previous to version 2.0.0, this program always ran in sync mode. Now, there's an async option. Simply pass a function as your second parameter, and `isBinaryFile` will figure the rest out:
 
-```javascript
-var isBinaryFile = require("isbinaryfile");
-
-isBinaryFile(process.argv[2], function(err, result) {
-  if (err) return console.error(err);
-
-  if (result)
-    console.log("It is!")
-  else
-    console.log("No.")
-}
+isBinaryFile.sync(process.argv[2]); // true or false
+var stat = fs.lstatSync(process.argv[2]);
+isBinaryFile.sync(process.argv[2], stat.size); // true or false
 ```
 
 ## Testing
-Install mocha on your machine:
-
-```
-npm install mocha -g
-```
 
-Then run `npm test`.
+Run `npm install` to install `mocha`, then run `npm test`.

index.js

@@ -2,45 +2,30 @@ var fs = require('fs');
 var path = require("path");
 var MAX_BYTES = 512;
 
-module.exports = function(bytes, size) {
-  var file = bytes;
-  // Read the file with no encoding for raw buffer access.
-  if (size === undefined) {
-    try {
-      if(!fs.statSync(file).isFile()) return false;
-    } catch (err) {
-      // otherwise continue on
-    }
-    var descriptor = fs.openSync(file, 'r');
-    try {
-      bytes = new Buffer(MAX_BYTES);
-      size = fs.readSync(descriptor, bytes, 0, bytes.length, 0);
-    } finally {
-      fs.closeSync(descriptor);
-    }
-  }
-  // async version has a function instead of a `size`
-  else if (typeof size === "function") {
-    callback = size;
+module.exports = function(bytes, size, cb) {
+  // Only two args
+  if (cb === undefined) {
+    var file = bytes;
+    cb = size;
+
     fs.stat(file, function(err, stat) {
-      if (err || !stat.isFile()) return callback(null, false);
+      if (err || !stat.isFile()) return cb(err, false);
 
-      fs.open(file, 'r', function(err, descriptor){
-          if (err) return callback(err);
-          var bytes = new Buffer(MAX_BYTES);
+      fs.open(file, 'r', function(r_err, descriptor){
+          if (r_err) return cb(r_err);
+          bytes = new Buffer(MAX_BYTES);
           // Read the file with no encoding for raw buffer access.
           fs.read(descriptor, bytes, 0, bytes.length, 0, function(err, size, bytes){
-            fs.close(descriptor, function(err2){
-                if (err || err2)
-                    return callback(err || err2);
-                return callback(null, isBinaryCheck(bytes, size));
+            fs.close(descriptor, function(c_err){
+                if (c_err) return cb(c_err, false);
+                return cb(null, isBinaryCheck(bytes, size));
             });
           });
       });
     });
   }
-
-  return isBinaryCheck(bytes, size);
+  else
+    return cb(null, isBinaryCheck(bytes, size));
 };
 
 function isBinaryCheck(bytes, size) {
@@ -119,4 +104,25 @@ function isBinaryCheck(bytes, size) {
   return false;
 }
 
-module.exports.isBinaryCheck = isBinaryCheck;
+module.exports.sync = function(bytes, size) {
+  // Only one arg
+  if (size === undefined) {
+    var file = bytes;
+    try {
+      if(!fs.statSync(file).isFile()) return false;
+    } catch (err) {
+      // otherwise continue on
+    }
+    var descriptor = fs.openSync(file, 'r');
+    try {
+      // Read the file with no encoding for raw buffer access.
+      bytes = new Buffer(MAX_BYTES);
+      size = fs.readSync(descriptor, bytes, 0, bytes.length, 0);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+    return isBinaryCheck(bytes, size);
+  }
+  else
+    return isBinaryCheck(bytes, size);
+}