feat: make ping method public

API.md

@@ -37,6 +37,7 @@ NodeClam class definition. To cf
     * [.getVersion([cb])](#NodeClam+getVersion) ⇒ <code>Promise.&lt;string&gt;</code>
     * [.isInfected(file, [cb])](#NodeClam+isInfected) ⇒ <code>Promise.&lt;object&gt;</code>
     * [.passthrough()](#NodeClam+passthrough) ⇒ <code>Transform</code>
+    * [.ping([cb])](#NodeClam+ping) ⇒ <code>Promise.&lt;object&gt;</code>
     * [.scanFile(file, [cb])](#NodeClam+scanFile) ⇒ <code>Promise.&lt;object&gt;</code>
     * [.scanFiles(files, [endCb], [fileCb])](#NodeClam+scanFiles) ⇒ <code>Promise.&lt;object&gt;</code>
     * [.scanDir(path, [endCb], [fileCb])](#NodeClam+scanDir) ⇒ <code>Promise.&lt;object&gt;</code>
@@ -250,6 +251,44 @@ 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="NodeClam+ping"></a>
+
+### nodeClam.ping([cb]) ⇒ <code>Promise.&lt;object&gt;</code>
+This method allows you to ping the socket. It supports a callback and Promise API.
+If no callback is supplied, a Promise will be returned.
+
+**Kind**: instance method of [<code>NodeClam</code>](#NodeClam)  
+**Returns**: <code>Promise.&lt;object&gt;</code> - A copy of the Socket/TCP client.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [cb] | <code>function</code> | What to do after the ping |
+
+**Example**  
+```js
+// Callback Example
+clamscan.ping((err, client) => {
+    if (err) return console.error(err);
+
+    console.log("ClamAV client is working");
+    client.end();
+});
+
+// Promise Example
+clamscan.ping().then(client => {
+    console.log("ClamAV client is working");
+    client.end();
+}).then(err => {
+    console.error(err);
+});
+
+// Async/Await Example
+const client = await clamscan.ping();
+console.log("ClamAV client is working");
+client.end();
+```
+
 <a name="NodeClam+scanFile"></a>
 
 ### nodeClam.scanFile(file, [cb]) ⇒ <code>Promise.&lt;object&gt;</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.

index.js

@@ -326,7 +326,7 @@ class NodeClam {
                 if (this.settings.debugMode)
                     console.log(`${this.debugLabel}: Initially testing socket/tcp connection to clamscan server.`);
                 try {
-                    const client = await this._ping();
+                    const client = await this.ping();
                     client.end();
                     if (this.settings.debugMode)
                         console.log(`${this.debugLabel}: Established connection to clamscan server!`);
@@ -684,11 +684,10 @@ class NodeClam {
      * Quick check to see if the remote/local socket is working. Callback/Resolve
      * response is an instance to a ClamAV socket client.
      *
-     * @private
      * @param {Function} [cb] - What to do after the ping
      * @returns {Promise<object>} A copy of the Socket/TCP client
      */
-    _ping(cb) {
+    ping(cb) {
         let hasCb = false;
 
         // Verify second param, if supplied, is a function
@@ -704,7 +703,7 @@ class NodeClam {
         // eslint-disable-next-line consistent-return
         return new Promise(async (resolve, reject) => {
             try {
-                client = await this._initSocket('_ping');
+                client = await this._initSocket('ping');
 
                 if (this.settings.debugMode)
                     console.log(`${this.debugLabel}: Established connection to clamscan server!`);

tests/index.js

@@ -410,21 +410,21 @@ describe('_initSocket', () => {
     });
 });
 
-describe('_ping', () => {
+describe('ping', () => {
     let clamscan;
     beforeEach(async () => {
         clamscan = await resetClam();
     });
 
     it('should exist', () => {
-        should.exist(clamscan._ping);
+        should.exist(clamscan.ping);
     });
     it('should be a function', () => {
-        clamscan._ping.should.be.a('function');
+        clamscan.ping.should.be.a('function');
     });
 
     it('should respond with a socket client (Promise API)', async () => {
-        const client = await clamscan._ping();
+        const client = await clamscan.ping();
         expect(client).to.be.an('object');
         expect(client.readyState).to.eql('open');
         expect(client.writable).to.eql(true);
@@ -438,7 +438,7 @@ describe('_ping', () => {
     });
 
     it('should respond with a socket client (Callback API)', (done) => {
-        clamscan._ping((err, client) => {
+        clamscan.ping((err, client) => {
             check(done, () => {
                 expect(err).to.not.be.instanceof(Error);
                 expect(client).to.be.an('object');
@@ -1744,7 +1744,7 @@ if (process.env.CI) {
                     tls: true,
                 },
             });
-            (await clamscan._ping()).end();
+            (await clamscan.ping()).end();
         });
 
         it('Connects to clamd server via a TLS proxy on 127.0.0.1', async () => {
@@ -1756,7 +1756,7 @@ if (process.env.CI) {
                     tls: true,
                 },
             });
-            (await clamscan._ping()).end();
+            (await clamscan.ping()).end();
         });
 
         it('Connects to clamd server via a TLS proxy on ::1', async () => {
@@ -1768,7 +1768,7 @@ if (process.env.CI) {
                     tls: true,
                 },
             });
-            (await clamscan._ping()).end();
+            (await clamscan.ping()).end();
         });
 
         // it('Connects to clamd server via a TLS proxy on implicit localhost', async () => {