istextorbinary - npm Package Compare versions

Comparing version 2.4.2 to 2.5.0

edition-browsers/index.js

@@ -0,1 +1,3 @@
+// @ts-check
+
 /* eslint no-use-before-define:0 */
@@ -10,6 +12,12 @@ 'use strict'; // Import
 /**
- * @typedef {'utf8'|'binary'} EncodingResult
+ * WIll be `null` if `buffer` was not provided. Otherwise will be either `'utf8'` or `'binary'`.
+ * @typedef {'utf8'|'binary'|null} EncodingResult
  */
 
 /**
+ * WIll be `null` if neither `filename` nor `buffer` were provided. Otherwise will be a boolean value with the detection result.
+ * @typedef {boolean|null} TextOrBinaryResult
+ */
+
+/**
  * @typedef {Object} EncodingOpts
@@ -23,3 +31,3 @@ * @property {number} [chunkLength = 24]
  * @param {Error?} error
- * @param {boolean} [result]
+ * @param {TextOrBinaryResult} [isTextResult]
  */
@@ -30,3 +38,3 @@
  * @param {Error?} error
- * @param {boolean} [result]
+ * @param {TextOrBinaryResult} [isBinaryResult]
  */
@@ -45,5 +53,6 @@
  * The extension checks are performed using the resources https://github.com/bevry/textextensions and https://github.com/bevry/binaryextensions
+ * In a later major release, this function will become {@link isText} so you should use that instead.
  * @param {string} [filename] The filename for the file/buffer if available
  * @param {Buffer} [buffer] The buffer for the file if available
- * @returns {boolean}
+ * @returns {TextOrBinaryResult}
  */
@@ -53,5 +62,3 @@
 function isTextSync(filename, buffer) {
-  // Prepare
-  var isText = null; // Test extensions
-
+  // Test extensions
   if (filename) {
@@ -69,10 +76,8 @@ // Extract filename
 
-        if (textExtensions.indexOf(extension) !== -1) {
-          isText = true;
-          break;
+        if (textExtensions.includes(extension)) {
+          return true;
         }
 
-        if (binaryExtensions.indexOf(extension) !== -1) {
-          isText = false;
-          break;
+        if (binaryExtensions.includes(extension)) {
+          return false;
         }
@@ -97,15 +102,14 @@ }
 
-  if (buffer && isText === null) {
-    isText = getEncodingSync(buffer) === 'utf8';
-  } // Return our result
+  if (buffer) {
+    return getEncodingSync(buffer) === 'utf8';
+  } // No buffer was provided
 
 
-  return isText;
+  return null;
 }
 /**
- * Determine if the filename and/or buffer is text.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string?} filename Forwarded to `isTextSync`
- * @param {Buffer?} buffer Forwarded to `isTextSync`
- * @param {IsTextCallback} next
+ * Callback wrapper for {@link isTextSync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} callback
  * @returns {void}
@@ -115,3 +119,3 @@ */
 
-function isText(filename, buffer, next) {
+function isTextCallback(filename, buffer, callback) {
   var result;
@@ -122,27 +126,56 @@
   } catch (err) {
-    next(err);
+    callback(err);
   }
 
-  next(null, result);
+  callback(null, result);
 }
 /**
- * Determine if the filename and/or buffer is binary.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string} [filename] Forwarded to `isTextSync`
- * @param {Buffer} [buffer] Forwarded to `isTextSync`
- * @returns {boolean}
+ * Promise wrapper for {@link isTextSync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @returns {Promise<TextOrBinaryResult>}
  */
 
 
+function isTextPromise(filename, buffer) {
+  try {
+    return Promise.resolve(isTextSync(filename, buffer));
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+/**
+ * Wrapper around {@link isTextSync} for sync signature and {@link isTextCallback} async signature.
+ * In a later major release, {@link isTextSync}.will become this function, so if you prefer the callback interface you should use {@link isTextCallback}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {TextOrBinaryResult|void} If no callback was provided, then the result is returned.
+ */
+
+
+function isText(filename, buffer, callback) {
+  if (callback) {
+    return isTextCallback(filename, buffer, callback);
+  } else return isTextSync(filename, buffer);
+}
+/**
+ * Inverse wrapper for {@link isTextSync}.
+ * In a later major release, this function will become {@link isBinary} so you should use that instead.
+ * @param {string} [filename]
+ * @param {Buffer} [buffer]
+ * @returns {TextOrBinaryResult}
+ */
+
+
 function isBinarySync(filename, buffer) {
-  // Handle
-  var result = isTextSync(filename, buffer);
-  return !result;
+  var text = isTextSync(filename, buffer);
+  if (text == null) return null;
+  return !text;
 }
 /**
- * Determine if the filename and/or buffer is binary.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string?} filename Forwarded to `isText`
- * @param {Buffer?} buffer Forwarded to `isText`
- * @param {IsBinaryCallback} next
+ * Callback wrapper for {@link isBinarySync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} callback
  * @returns {void}
@@ -152,17 +185,48 @@ */
 
-function isBinary(filename, buffer, next) {
+function isBinaryCallback(filename, buffer, callback) {
   var result;
 
   try {
-    result = isTextSync(filename, buffer);
+    result = isBinarySync(filename, buffer);
   } catch (err) {
-    next(err);
+    callback(err);
   }
 
-  next(null, !result);
+  callback(null, result);
 }
 /**
+ * Promise wrapper for {@link isBinarySync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @returns {Promise<TextOrBinaryResult>}
+ */
+
+
+function isBinaryPromise(filename, buffer) {
+  try {
+    return Promise.resolve(isBinarySync(filename, buffer));
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+/**
+ * Wrapper around {@link isBinarySync} for sync signature and {@link isBinaryCallback} async signature.
+ * In a later major release, {@link isBinarySync}.will become this function, so if you prefer the callback interface you should use {@link isBinaryCallback}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {TextOrBinaryResult|void} If no callback was provided, then the result is returned.
+ */
+
+
+function isBinary(filename, buffer, callback) {
+  if (callback) {
+    return isBinaryCallback(filename, buffer, callback);
+  } else return isBinarySync(filename, buffer);
+}
+/**
  * Get the encoding of a buffer.
- * We fetch a bunch chars from the start, middle and end of the buffer.
- * We check all three, as doing only start was not enough, and doing only middle was not enough, so better safe than sorry.
+ * Checks the start, middle, and end of the buffer for characters that are unrecognized within UTF8 encoding.
+ * History has shown that inspection at all three locations is necessary.
+ * In a later major release, this function will become {@link getEncoding} so you should use that instead.
  * @param {Buffer} buffer
@@ -175,3 +239,5 @@ * @param {EncodingOpts} [opts]
 function getEncodingSync(buffer, opts) {
-  // Prepare
+  // Check
+  if (!buffer) return null; // Prepare
+
   var textEncoding = 'utf8';
@@ -235,5 +301,5 @@ var binaryEncoding = 'binary'; // Discover
  * Uses {@link getEncodingSync} behind the scenes.
- * @param {Buffer} buffer Forwarded to `getEncodingSync`
- * @param {EncodingOpts} opts Forwarded to `getEncodingSync`
- * @param {GetEncodingCallback} next
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @param {GetEncodingCallback} callback
  * @returns {void}
@@ -243,4 +309,6 @@ */
 
-function getEncoding(buffer, opts, next) {
+function getEncodingCallback(buffer, opts, callback) {
+  if (typeof opts === 'function' && callback == null) return getEncodingCallback(buffer, null, opts);
   /** @type {EncodingResult?} */
+
   var result;
@@ -251,6 +319,36 @@
   } catch (err) {
-    next(err);
+    callback(err);
   }
 
-  next(null, result);
+  callback(null, result);
+}
+/**
+ * Promise wrapper for {@link getEncodingSync}.
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @returns {Promise<EncodingResult>}
+ */
+
+
+function getEncodingPromise(buffer, opts) {
+  try {
+    return Promise.resolve(getEncodingSync(buffer, opts));
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+/**
+ * Wrapper around {@link getEncodingSync} for sync signature and {@link getEncodingCallback} async signature.
+ * In a later major release, {@link getEncodingSync}.will become this function, so if you prefer the callback interface you should use {@link getEncodingCallback}.
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @param {GetEncodingCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {EncodingResult|void} If no callback was provided, then the result is returned.
+ */
+
+
+function getEncoding(buffer, opts, callback) {
+  if (callback || typeof opts === 'function') {
+    return getEncodingCallback(buffer, opts, callback);
+  } else return getEncodingSync(buffer, opts);
 } // Export
@@ -261,7 +359,13 @@
   isTextSync: isTextSync,
+  isTextCallback: isTextCallback,
+  isTextPromise: isTextPromise,
   isText: isText,
   isBinarySync: isBinarySync,
+  isBinaryCallback: isBinaryCallback,
+  isBinaryPromise: isBinaryPromise,
   isBinary: isBinary,
+  getEncoding: getEncoding,
   getEncodingSync: getEncodingSync,
-  getEncoding: getEncoding
+  getEncodingPromise: getEncodingPromise,
+  getEncodingCallback: getEncodingCallback
 };

edition-node-0.12/index.js

@@ -0,1 +1,3 @@
+// @ts-check
+
 /* eslint no-use-before-define:0 */
@@ -10,6 +12,12 @@ 'use strict'; // Import
 /**
- * @typedef {'utf8'|'binary'} EncodingResult
+ * WIll be `null` if `buffer` was not provided. Otherwise will be either `'utf8'` or `'binary'`.
+ * @typedef {'utf8'|'binary'|null} EncodingResult
  */
 
 /**
+ * WIll be `null` if neither `filename` nor `buffer` were provided. Otherwise will be a boolean value with the detection result.
+ * @typedef {boolean|null} TextOrBinaryResult
+ */
+
+/**
  * @typedef {Object} EncodingOpts
@@ -23,3 +31,3 @@ * @property {number} [chunkLength = 24]
  * @param {Error?} error
- * @param {boolean} [result]
+ * @param {TextOrBinaryResult} [isTextResult]
  */
@@ -30,3 +38,3 @@
  * @param {Error?} error
- * @param {boolean} [result]
+ * @param {TextOrBinaryResult} [isBinaryResult]
  */
@@ -45,5 +53,6 @@
  * The extension checks are performed using the resources https://github.com/bevry/textextensions and https://github.com/bevry/binaryextensions
+ * In a later major release, this function will become {@link isText} so you should use that instead.
  * @param {string} [filename] The filename for the file/buffer if available
  * @param {Buffer} [buffer] The buffer for the file if available
- * @returns {boolean}
+ * @returns {TextOrBinaryResult}
  */
@@ -53,5 +62,3 @@
 function isTextSync(filename, buffer) {
-  // Prepare
-  var isText = null; // Test extensions
-
+  // Test extensions
   if (filename) {
@@ -69,10 +76,8 @@ // Extract filename
 
-        if (textExtensions.indexOf(extension) !== -1) {
-          isText = true;
-          break;
+        if (textExtensions.includes(extension)) {
+          return true;
         }
 
-        if (binaryExtensions.indexOf(extension) !== -1) {
-          isText = false;
-          break;
+        if (binaryExtensions.includes(extension)) {
+          return false;
         }
@@ -97,15 +102,14 @@ }
 
-  if (buffer && isText === null) {
-    isText = getEncodingSync(buffer) === 'utf8';
-  } // Return our result
+  if (buffer) {
+    return getEncodingSync(buffer) === 'utf8';
+  } // No buffer was provided
 
 
-  return isText;
+  return null;
 }
 /**
- * Determine if the filename and/or buffer is text.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string?} filename Forwarded to `isTextSync`
- * @param {Buffer?} buffer Forwarded to `isTextSync`
- * @param {IsTextCallback} next
+ * Callback wrapper for {@link isTextSync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} callback
  * @returns {void}
@@ -115,3 +119,3 @@ */
 
-function isText(filename, buffer, next) {
+function isTextCallback(filename, buffer, callback) {
   var result;
@@ -122,27 +126,56 @@
   } catch (err) {
-    next(err);
+    callback(err);
   }
 
-  next(null, result);
+  callback(null, result);
 }
 /**
- * Determine if the filename and/or buffer is binary.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string} [filename] Forwarded to `isTextSync`
- * @param {Buffer} [buffer] Forwarded to `isTextSync`
- * @returns {boolean}
+ * Promise wrapper for {@link isTextSync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @returns {Promise<TextOrBinaryResult>}
  */
 
 
+function isTextPromise(filename, buffer) {
+  try {
+    return Promise.resolve(isTextSync(filename, buffer));
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+/**
+ * Wrapper around {@link isTextSync} for sync signature and {@link isTextCallback} async signature.
+ * In a later major release, {@link isTextSync}.will become this function, so if you prefer the callback interface you should use {@link isTextCallback}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {TextOrBinaryResult|void} If no callback was provided, then the result is returned.
+ */
+
+
+function isText(filename, buffer, callback) {
+  if (callback) {
+    return isTextCallback(filename, buffer, callback);
+  } else return isTextSync(filename, buffer);
+}
+/**
+ * Inverse wrapper for {@link isTextSync}.
+ * In a later major release, this function will become {@link isBinary} so you should use that instead.
+ * @param {string} [filename]
+ * @param {Buffer} [buffer]
+ * @returns {TextOrBinaryResult}
+ */
+
+
 function isBinarySync(filename, buffer) {
-  // Handle
-  var result = isTextSync(filename, buffer);
-  return !result;
+  var text = isTextSync(filename, buffer);
+  if (text == null) return null;
+  return !text;
 }
 /**
- * Determine if the filename and/or buffer is binary.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string?} filename Forwarded to `isText`
- * @param {Buffer?} buffer Forwarded to `isText`
- * @param {IsBinaryCallback} next
+ * Callback wrapper for {@link isBinarySync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} callback
  * @returns {void}
@@ -152,17 +185,48 @@ */
 
-function isBinary(filename, buffer, next) {
+function isBinaryCallback(filename, buffer, callback) {
   var result;
 
   try {
-    result = isTextSync(filename, buffer);
+    result = isBinarySync(filename, buffer);
   } catch (err) {
-    next(err);
+    callback(err);
   }
 
-  next(null, !result);
+  callback(null, result);
 }
 /**
+ * Promise wrapper for {@link isBinarySync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @returns {Promise<TextOrBinaryResult>}
+ */
+
+
+function isBinaryPromise(filename, buffer) {
+  try {
+    return Promise.resolve(isBinarySync(filename, buffer));
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+/**
+ * Wrapper around {@link isBinarySync} for sync signature and {@link isBinaryCallback} async signature.
+ * In a later major release, {@link isBinarySync}.will become this function, so if you prefer the callback interface you should use {@link isBinaryCallback}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {TextOrBinaryResult|void} If no callback was provided, then the result is returned.
+ */
+
+
+function isBinary(filename, buffer, callback) {
+  if (callback) {
+    return isBinaryCallback(filename, buffer, callback);
+  } else return isBinarySync(filename, buffer);
+}
+/**
  * Get the encoding of a buffer.
- * We fetch a bunch chars from the start, middle and end of the buffer.
- * We check all three, as doing only start was not enough, and doing only middle was not enough, so better safe than sorry.
+ * Checks the start, middle, and end of the buffer for characters that are unrecognized within UTF8 encoding.
+ * History has shown that inspection at all three locations is necessary.
+ * In a later major release, this function will become {@link getEncoding} so you should use that instead.
  * @param {Buffer} buffer
@@ -175,3 +239,5 @@ * @param {EncodingOpts} [opts]
 function getEncodingSync(buffer, opts) {
-  // Prepare
+  // Check
+  if (!buffer) return null; // Prepare
+
   var textEncoding = 'utf8';
@@ -235,5 +301,5 @@ var binaryEncoding = 'binary'; // Discover
  * Uses {@link getEncodingSync} behind the scenes.
- * @param {Buffer} buffer Forwarded to `getEncodingSync`
- * @param {EncodingOpts} opts Forwarded to `getEncodingSync`
- * @param {GetEncodingCallback} next
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @param {GetEncodingCallback} callback
  * @returns {void}
@@ -243,4 +309,6 @@ */
 
-function getEncoding(buffer, opts, next) {
+function getEncodingCallback(buffer, opts, callback) {
+  if (typeof opts === 'function' && callback == null) return getEncodingCallback(buffer, null, opts);
   /** @type {EncodingResult?} */
+
   var result;
@@ -251,6 +319,36 @@
   } catch (err) {
-    next(err);
+    callback(err);
   }
 
-  next(null, result);
+  callback(null, result);
+}
+/**
+ * Promise wrapper for {@link getEncodingSync}.
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @returns {Promise<EncodingResult>}
+ */
+
+
+function getEncodingPromise(buffer, opts) {
+  try {
+    return Promise.resolve(getEncodingSync(buffer, opts));
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+/**
+ * Wrapper around {@link getEncodingSync} for sync signature and {@link getEncodingCallback} async signature.
+ * In a later major release, {@link getEncodingSync}.will become this function, so if you prefer the callback interface you should use {@link getEncodingCallback}.
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @param {GetEncodingCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {EncodingResult|void} If no callback was provided, then the result is returned.
+ */
+
+
+function getEncoding(buffer, opts, callback) {
+  if (callback || typeof opts === 'function') {
+    return getEncodingCallback(buffer, opts, callback);
+  } else return getEncodingSync(buffer, opts);
 } // Export
@@ -261,7 +359,13 @@
   isTextSync: isTextSync,
+  isTextCallback: isTextCallback,
+  isTextPromise: isTextPromise,
   isText: isText,
   isBinarySync: isBinarySync,
+  isBinaryCallback: isBinaryCallback,
+  isBinaryPromise: isBinaryPromise,
   isBinary: isBinary,
+  getEncoding: getEncoding,
   getEncodingSync: getEncodingSync,
-  getEncoding: getEncoding
+  getEncodingPromise: getEncodingPromise,
+  getEncodingCallback: getEncodingCallback
 };

HISTORY.md

 # History
 
+## v2.5.0 2019 January 21
+
+As the detection algorithms are result returns, with the asynchronous signatures just wrappers, we have changed `isText`, `isBinary`, and `getEncoding` to return the result if no callback was provided to them, maintaining backwards compatibility, but encouraging intuitive usage of the methods with the least overhead.
+
+-   The following methods have had return signatures added to them, which should be the preferable usage:
+
+    -   `isText`, which you should use instead of `isTextSync` (a method which only lingers for backwards compatibility)
+    -   `isBinary`, which you should use instead of `isBinarySync` (a method which only lingers for backwards compatibility)
+    -   `getEncoding`, which you should use instead of `getEncoding` (a method which only lingers for backwards compatibility)
+
+-   If you require callback usage, the following callback wrapper methods have been added:
+
+    -   `isTextCallback`, which you should use instead of `isText`'s callback signature (a signature which only lingers for backwards compatibility)
+    -   `isBinaryCallback`, which you should use instead of `isBinary`'s callback signature (a signature which only lingers for backwards compatibility)
+    -   `getEncodingCallback`, which you should use instead of `getEncoding`'s callback signature (a signature which only lingers for backwards compatibility)
+
+-   If you require promise usage, the following promise wrapper methods have been added:
+
+    -   `isTextPromise` which wraps `isText` with a promise signature
+    -   `isBinaryPromise` which wraps `isBinary` with a promise signature
+    -   `getEncodingPromise` which wraps `getEncoding` with a promise signature
+
+-   `isBinary` method now correctly returns `null` instead of `true` when no inputs are provided
+
+-   Added tests for all methods
+
 ## v2.4.2 2019 January 21
@@ -4,0 +30,0 @@

package.json

 {
   "title": "Is Text or Binary?",
   "name": "istextorbinary",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Determine if a filename and/or buffer is text or binary. Smarter detection than the other solutions.",
@@ -6,0 +6,0 @@ "homepage": "https://github.com/bevry/istextorbinary",

README.md

@@ -39,11 +39,13 @@ <!-- TITLE/ -->
 
-1. If filename is available, check if its extension is a [text extension](https://github.com/bevry/textextensions) or if it is a [binary extension](https://github.com/bevry/binaryextensions), this is near instant.
-2. If no filename was provided, or the extension check was indeterminate, then check the buffer.
+1. Extension Check: If filename is available, check if any of its extensions (from right to left) are an [text extension](https://github.com/bevry/textextensions) or a [binary extension](https://github.com/bevry/binaryextensions), this is near instant.
+2. Buffer Check: If no filename was provided, or the extension check was indeterminate, then check the buffer.
 
-The buffer check (with the default options) will check 24 bytes at the start, middle, and end of the buffer. History has shown that checking all three locations is mandatory for accuracy, and that anything less is not accurate. This technique offers superior performance while still offering superior accuracy. Alternatives generally just do 1000 bytes at the start, which is slower, and inaccurate.
+The extension check will check each of the filenames extensions, from right to left. This is done, as certain applications utilise multiple extensions for transformations, such as `app.x.y` may tell a compiler to transform from `x` format to `y` format, if `x` is not a recognized extension but `y` is a recognized extension, then we can make use of that, to provide accuracy and convenience.
 
-One cannot just do the buffer check alone because UTF16 characters are indistinguishable from binary which would return an inaccurate result, hence why the combination is necessary for accuracy, with performance for known extensions a side-effect.
+The contents check (with the default options) will check 24 bytes at the start, middle, and end of the buffer. History has shown that checking all three locations is mandatory for accuracy, and that anything less is not accurate. This technique offers superior performance while still offering superior accuracy. Alternatives generally just do 1000 bytes at the start, which is slower, and inaccurate.
 
-As such, this library's combination of text check (if filename is provided), then buffer check (if buffer is provided), offers superior performance and accuracy to alternatives.
+One cannot just do the contents check alone because UTF16 characters are indistinguishable from binary which would return an inaccurate result, hence why the combination is necessary for accuracy, with performance for known extensions a side-effect.
 
+As such, this library's combination of extension check (if filename is provided), then contents check (if buffer is provided), offers superior performance and accuracy to alternatives.
+
 Ever since 2012, this module's superior accuracy and performance has been essential to the operation of [DocPad](https://docpad.org) and its other dependents.
@@ -55,2 +57,18 @@
 
+```javascript
+const { isText, isBuffer, getEncoding } = require('istextorbinary')
+
+isText(aFilename) // returns true if a text file otherwise false, checks only filename
+isText(null, aBuffer) // returns true if a text file otherwise false, checks only buffer
+isText(aFilename, aBuffer) // returns true if a text file otherwise false, checks filename then buffer
+isText(null, null) // returns null
+
+isBinary(aFilename) // returns true if a binary file otherwise false, checks only filename
+isBinary(null, aBuffer) // returns true if a binary file otherwise false, checks only buffer
+isBinary(aFilename, aBuffer) // returns true if a binary file otherwise false, checks filename then buffer
+isBinary(null, null) // returns null
+
+getEncoding(aBuffer) // returns 'binary' if it contained non-utf8 characters, otherwise returns 'utf8'
+```
+
 <!-- INSTALL/ -->
@@ -124,3 +142,3 @@
 
-<ul><li><a href="http://balupton.com">Benjamin Lupton</a> — <a href="https://github.com/bevry/istextorbinary/commits?author=balupton" title="View the GitHub contributions of Benjamin Lupton on repository bevry/istextorbinary">view contributions</a></li>
+<ul><li><a href="http://balupton.com">Benjamin Lupton</a></li>
 <li><a href="https://github.com/robloach">Rob Loach</a> — <a href="https://github.com/bevry/istextorbinary/commits?author=robloach" title="View the GitHub contributions of Rob Loach on repository bevry/istextorbinary">view contributions</a></li>
@@ -148,6 +166,6 @@ <li><a href="https://github.com/mikeumus">Michael Mooring</a> — <a href="https://github.com/bevry/istextorbinary/commits?author=mikeumus" title="View the GitHub contributions of Michael Mooring on repository bevry/istextorbinary">view contributions</a></li></ul>
 
-<ul><li><a href="http://balupton.com">Benjamin Lupton</a> — <a href="https://github.com/bevry/istextorbinary/commits?author=balupton" title="View the GitHub contributions of Benjamin Lupton on repository bevry/istextorbinary">view contributions</a></li>
-<li><a href="http://shinnn.github.io">Shinnosuke Watanabe</a> — <a href="https://github.com/bevry/istextorbinary/commits?author=shinnn" title="View the GitHub contributions of Shinnosuke Watanabe on repository bevry/istextorbinary">view contributions</a></li>
-<li><a href="http://www.sibnerian.com/">Ian Sibner</a> — <a href="https://github.com/bevry/istextorbinary/commits?author=sibnerian" title="View the GitHub contributions of Ian Sibner on repository bevry/istextorbinary">view contributions</a></li>
-<li><a href="http://albinodrought.com/">Sean</a> — <a href="https://github.com/bevry/istextorbinary/commits?author=AlbinoDrought" title="View the GitHub contributions of Sean on repository bevry/istextorbinary">view contributions</a></li></ul>
+<ul><li><a href="http://balupton.com">Benjamin Lupton</a></li>
+<li><a href="http://shinnn.github.io">Shinnosuke Watanabe</a></li>
+<li><a href="http://www.sibnerian.com/">Ian Sibner</a></li>
+<li><a href="http://albinodrought.com/">Sean</a></li></ul>
 
@@ -154,0 +172,0 @@ <a href="https://github.com/bevry/istextorbinary/blob/master/CONTRIBUTING.md#files">Discover how you can contribute by heading on over to the <code>CONTRIBUTING.md</code> file.</a>

source/index.js

@@ -0,1 +1,2 @@
+// @ts-check
 /* eslint no-use-before-define:0 */
@@ -10,6 +11,12 @@ 'use strict'
 /**
- * @typedef {'utf8'|'binary'} EncodingResult
+ * WIll be `null` if `buffer` was not provided. Otherwise will be either `'utf8'` or `'binary'`.
+ * @typedef {'utf8'|'binary'|null} EncodingResult
  */
 
 /**
+ * WIll be `null` if neither `filename` nor `buffer` were provided. Otherwise will be a boolean value with the detection result.
+ * @typedef {boolean|null} TextOrBinaryResult
+ */
+
+/**
  * @typedef {Object} EncodingOpts
@@ -23,3 +30,3 @@ * @property {number} [chunkLength = 24]
  * @param {Error?} error
- * @param {boolean} [result]
+ * @param {TextOrBinaryResult} [isTextResult]
  */
@@ -30,3 +37,3 @@
  * @param {Error?} error
- * @param {boolean} [result]
+ * @param {TextOrBinaryResult} [isBinaryResult]
  */
@@ -45,10 +52,8 @@
  * The extension checks are performed using the resources https://github.com/bevry/textextensions and https://github.com/bevry/binaryextensions
+ * In a later major release, this function will become {@link isText} so you should use that instead.
  * @param {string} [filename] The filename for the file/buffer if available
  * @param {Buffer} [buffer] The buffer for the file if available
- * @returns {boolean}
+ * @returns {TextOrBinaryResult}
  */
 function isTextSync(filename, buffer) {
-	// Prepare
-	let isText = null
-
 	// Test extensions
@@ -64,9 +69,7 @@ if (filename) {
 		for (const extension of parts) {
-			if (textExtensions.indexOf(extension) !== -1) {
-				isText = true
-				break
+			if (textExtensions.includes(extension)) {
+				return true
 			}
-			if (binaryExtensions.indexOf(extension) !== -1) {
-				isText = false
-				break
+			if (binaryExtensions.includes(extension)) {
+				return false
 			}
@@ -77,19 +80,18 @@ }
 	// Fallback to encoding if extension check was not enough
-	if (buffer && isText === null) {
-		isText = getEncodingSync(buffer) === 'utf8'
+	if (buffer) {
+		return getEncodingSync(buffer) === 'utf8'
 	}
 
-	// Return our result
-	return isText
+	// No buffer was provided
+	return null
 }
 
 /**
- * Determine if the filename and/or buffer is text.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string?} filename Forwarded to `isTextSync`
- * @param {Buffer?} buffer Forwarded to `isTextSync`
- * @param {IsTextCallback} next
+ * Callback wrapper for {@link isTextSync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} callback
  * @returns {void}
  */
-function isText(filename, buffer, next) {
+function isTextCallback(filename, buffer, callback) {
 	let result
@@ -99,42 +101,98 @@ try {
 	} catch (err) {
-		next(err)
+		callback(err)
 	}
-	next(null, result)
+	callback(null, result)
 }
 
 /**
- * Determine if the filename and/or buffer is binary.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string} [filename] Forwarded to `isTextSync`
- * @param {Buffer} [buffer] Forwarded to `isTextSync`
- * @returns {boolean}
+ * Promise wrapper for {@link isTextSync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @returns {Promise<TextOrBinaryResult>}
  */
+function isTextPromise(filename, buffer) {
+	try {
+		return Promise.resolve(isTextSync(filename, buffer))
+	} catch (err) {
+		return Promise.reject(err)
+	}
+}
+
+/**
+ * Wrapper around {@link isTextSync} for sync signature and {@link isTextCallback} async signature.
+ * In a later major release, {@link isTextSync}.will become this function, so if you prefer the callback interface you should use {@link isTextCallback}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {TextOrBinaryResult|void} If no callback was provided, then the result is returned.
+ */
+function isText(filename, buffer, callback) {
+	if (callback) {
+		return isTextCallback(filename, buffer, callback)
+	} else return isTextSync(filename, buffer)
+}
+
+/**
+ * Inverse wrapper for {@link isTextSync}.
+ * In a later major release, this function will become {@link isBinary} so you should use that instead.
+ * @param {string} [filename]
+ * @param {Buffer} [buffer]
+ * @returns {TextOrBinaryResult}
+ */
 function isBinarySync(filename, buffer) {
-	// Handle
-	const result = isTextSync(filename, buffer)
-	return !result
+	const text = isTextSync(filename, buffer)
+	if (text == null) return null
+	return !text
 }
 
 /**
- * Determine if the filename and/or buffer is binary.
- * Uses {@link isTextSync} behind the scenes.
- * @param {string?} filename Forwarded to `isText`
- * @param {Buffer?} buffer Forwarded to `isText`
- * @param {IsBinaryCallback} next
+ * Callback wrapper for {@link isBinarySync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} callback
  * @returns {void}
  */
-function isBinary(filename, buffer, next) {
+function isBinaryCallback(filename, buffer, callback) {
 	let result
 	try {
-		result = isTextSync(filename, buffer)
+		result = isBinarySync(filename, buffer)
 	} catch (err) {
-		next(err)
+		callback(err)
 	}
-	next(null, !result)
+	callback(null, result)
 }
 
 /**
+ * Promise wrapper for {@link isBinarySync}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @returns {Promise<TextOrBinaryResult>}
+ */
+function isBinaryPromise(filename, buffer) {
+	try {
+		return Promise.resolve(isBinarySync(filename, buffer))
+	} catch (err) {
+		return Promise.reject(err)
+	}
+}
+
+/**
+ * Wrapper around {@link isBinarySync} for sync signature and {@link isBinaryCallback} async signature.
+ * In a later major release, {@link isBinarySync}.will become this function, so if you prefer the callback interface you should use {@link isBinaryCallback}.
+ * @param {string?} filename
+ * @param {Buffer?} buffer
+ * @param {IsTextCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {TextOrBinaryResult|void} If no callback was provided, then the result is returned.
+ */
+function isBinary(filename, buffer, callback) {
+	if (callback) {
+		return isBinaryCallback(filename, buffer, callback)
+	} else return isBinarySync(filename, buffer)
+}
+
+/**
  * Get the encoding of a buffer.
- * We fetch a bunch chars from the start, middle and end of the buffer.
- * We check all three, as doing only start was not enough, and doing only middle was not enough, so better safe than sorry.
+ * Checks the start, middle, and end of the buffer for characters that are unrecognized within UTF8 encoding.
+ * History has shown that inspection at all three locations is necessary.
+ * In a later major release, this function will become {@link getEncoding} so you should use that instead.
  * @param {Buffer} buffer
@@ -145,2 +203,5 @@ * @param {EncodingOpts} [opts]
 function getEncodingSync(buffer, opts) {
+	// Check
+	if (!buffer) return null
+
 	// Prepare
@@ -193,8 +254,10 @@ const textEncoding = 'utf8'
  * Uses {@link getEncodingSync} behind the scenes.
- * @param {Buffer} buffer Forwarded to `getEncodingSync`
- * @param {EncodingOpts} opts Forwarded to `getEncodingSync`
- * @param {GetEncodingCallback} next
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @param {GetEncodingCallback} callback
  * @returns {void}
  */
-function getEncoding(buffer, opts, next) {
+function getEncodingCallback(buffer, opts, callback) {
+	if (typeof opts === 'function' && callback == null)
+		return getEncodingCallback(buffer, null, opts)
 	/** @type {EncodingResult?} */
@@ -205,15 +268,49 @@ let result
 	} catch (err) {
-		next(err)
+		callback(err)
 	}
-	next(null, result)
+	callback(null, result)
 }
 
+/**
+ * Promise wrapper for {@link getEncodingSync}.
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @returns {Promise<EncodingResult>}
+ */
+function getEncodingPromise(buffer, opts) {
+	try {
+		return Promise.resolve(getEncodingSync(buffer, opts))
+	} catch (err) {
+		return Promise.reject(err)
+	}
+}
+
+/**
+ * Wrapper around {@link getEncodingSync} for sync signature and {@link getEncodingCallback} async signature.
+ * In a later major release, {@link getEncodingSync}.will become this function, so if you prefer the callback interface you should use {@link getEncodingCallback}.
+ * @param {Buffer} buffer
+ * @param {EncodingOpts} [opts]
+ * @param {GetEncodingCallback} [callback] If provided, void will be returned, as the result will provided to the callback.
+ * @returns {EncodingResult|void} If no callback was provided, then the result is returned.
+ */
+function getEncoding(buffer, opts, callback) {
+	if (callback || typeof opts === 'function') {
+		return getEncodingCallback(buffer, opts, callback)
+	} else return getEncodingSync(buffer, opts)
+}
+
 // Export
 module.exports = {
 	isTextSync,
+	isTextCallback,
+	isTextPromise,
 	isText,
 	isBinarySync,
+	isBinaryCallback,
+	isBinaryPromise,
 	isBinary,
+	getEncoding,
 	getEncodingSync,
-	getEncoding
+	getEncodingPromise,
+	getEncodingCallback
 }

No alert changes

Improved metrics

Total package byte prevSize

55958

increased by31.29%

Lines of code

867

increased by44.74%

Number of lines in readme file

187

increased by10.65%

No dependency changes