Make ping() Public

API.md

@@ -2,7 +2,7 @@
 
 <dl>
 <dt><a href="#NodeClam">NodeClam</a></dt>
-<dd><p>NodeClam class definition. To cf</p>
+<dd><p>NodeClam class definition.</p>
 </dd>
 <dt><a href="#NodeClamError">NodeClamError</a></dt>
 <dd><p>Clamscan-specific extension of the Javascript Error object</p>
@@ -14,6 +14,15 @@ chunks into the correct format for a ClamAV socket.</p>
 </dd>
 </dl>
 
+## Members
+
+<dl>
+<dt><a href="#ping">ping</a> ⇒ <code>Promise.&lt;object&gt;</code></dt>
+<dd><p>Quick check to see if the remote/local socket is working. Callback/Resolve
+response is an instance to a ClamAV socket client.</p>
+</dd>
+</dl>
+
 ## Functions
 
 <dl>
@@ -26,7 +35,7 @@ By default, it will retrieve files recursively.</p>
 <a name="NodeClam"></a>
 
 ## NodeClam
-NodeClam class definition. To cf
+NodeClam class definition.
 
 **Kind**: global class  
 
@@ -55,6 +64,7 @@ Initialization method.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;object&gt;</code> - An initated instance of NodeClam  
+**Access**: public  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -125,6 +135,7 @@ Allows one to create a new instances of clamscan with new options.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;object&gt;</code> - A reset instance of NodeClam  
+**Access**: public  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -138,6 +149,7 @@ Establish the clamav version of a local or remote clamav daemon.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;string&gt;</code> - - The version of ClamAV that is being interfaced with  
+**Access**: public  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -165,6 +177,7 @@ be the most common use-case for this module.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;object&gt;</code> - Object like: `{ file: String, isInfected: Boolean, viruses: Array }`  
+**Access**: public  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -208,6 +221,7 @@ destination (ex. delete a file or S3 object).
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Transform</code> - A Transform stream for piping a Readable stream into  
+**Access**: public  
 **Example**  
 ```js
 const NodeClam = require('clamscan');
@@ -257,6 +271,7 @@ Just an alias to `isInfected`. See docs for that for usage examples.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;object&gt;</code> - Object like: `{ file: String, isInfected: Boolean, viruses: Array }`  
+**Access**: public  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -276,6 +291,7 @@ of scanning many files or directories.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;object&gt;</code> - Object like: `{ goodFiles: Array, badFiles: Array, errors: Object, viruses: Array }`  
+**Access**: public  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -333,6 +349,7 @@ method also allows for non-recursive scanning with the clamdscan binary.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;object&gt;</code> - Object like: `{ path: String, isInfected: Boolean, goodFiles: Array, badFiles: Array, viruses: Array }`  
+**Access**: public  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -368,6 +385,7 @@ have access to a local ClamAV binary.
 
 **Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
 **Returns**: <code>Promise.&lt;object&gt;</code> - Object like: `{ file: String, isInfected: Boolean, viruses: Array } `  
+**Access**: public  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -470,6 +488,20 @@ This will flush out the stream when all data has been received.
 | --- | --- | --- |
 | cb | <code>function</code> | What to do when done |
 
+<a name="ping"></a>
+
+## ping ⇒ <code>Promise.&lt;object&gt;</code>
+Quick check to see if the remote/local socket is working. Callback/Resolve
+response is an instance to a ClamAV socket client.
+
+**Kind**: global variable  
+**Returns**: <code>Promise.&lt;object&gt;</code> - A copy of the Socket/TCP client  
+**Access**: public  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [cb] | <code>function</code> | What to do after the ping |
+
 <a name="getFiles"></a>
 
 ## getFiles(dir, [recursive]) ⇒ <code>Array</code>

README.md

@@ -31,6 +31,7 @@ If you are migrating from v0.8.5 or less to v1.0.0 or greater, please read the [
   - [scanFiles](#scanFiles)
   - [scanStream](#scanStream)
   - [passthrough](#passthrough)
+  - [ping](#ping)
 - [Contribute](#contribute)
 - [Resources used to help develop this module](#resources-used-to-help-develop-this-module)
 
@@ -652,6 +653,66 @@ output.on('finish', () => {
 // NOTE: no errors (or other events) are being handled in this example but standard errors will be emitted according to NodeJS's Stream specifications
 ```
 
+<a name="ping"></a>
+
+## .ping()
+
+This method checks to see if the remote/local socket is working. It supports a callback and Promise API. If no callback is supplied, a Promise will be returned. This method can be used for healthcheck purposes and is already implicitly used during scan.
+
+### Parameters
+
+- `callback` (function) (optional) Will be called after the ping:
+
+  - `err` (object or null) A standard JavaScript Error object (null if no error)
+  - `client` (object) A copy of the Socket/TCP client
+
+### Returns
+
+- Promise
+
+  - Promise resolution returns: `client` (object): A copy of the Socket/TCP client
+
+### Examples
+
+**Callback Example:**
+
+```javascript
+const NodeClam = require('clamscan');
+
+// You'll need to specify your socket or TCP connection info
+const clamscan = new NodeClam().init({
+    clamdscan: {
+        socket: '/var/run/clamd.scan/clamd.sock',
+        host: '127.0.0.1',
+        port: 3310,
+    }
+});
+
+clamscan.ping((err, client) => {
+    if (err) return console.error(err);
+    console.log('ClamAV is still working!');
+    client.end();
+});
+```
+
+**Promise Example:**
+
+```javascript
+clamscan.ping().then((client) => {
+    console.log('ClamAV is still working!');
+    client.end();
+}).catch(err => {
+    console.error(err);
+};
+```
+
+**Promise Example:**
+
+```javascript
+const client = await clamscan.ping();
+client.end();
+```
+
 # Contribute
 
 Got a missing feature you'd like to use? Found a bug? Go ahead and fork this repo, build the feature and issue a pull request.