Support typescript definition files

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,56 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+
+A clear and concise description of what the bug is.
+
+## Expected Behavior
+
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+
+A clear and concise description of what actually happened.
+
+## Code Sample
+
+If applicable, add a minimal code sample that reproduces the issue:
+
+```javascript
+const ping = require('ping');
+
+ping.sys.probe('google.com', function(isAlive) {
+    console.log(isAlive);
+});
+```
+
+## Environment
+
+- **OS**: [e.g. Windows 10, Ubuntu 20.04, macOS 12.0]
+- **Node.js version**: [e.g. 18.17.0]
+- **Package version**: [e.g. 0.4.4]
+- **Platform**: [e.g. linux, win32, darwin] The output from nodejs `os.platform()`
+
+## Error Output
+
+If applicable, add error messages or stack traces:
+
+```
+Error: Platform |freebsd| is not support
+    at Object.factory.createParser (/path/to/file.js:42:15)
+    ...
+```
+
+## Raw system ping output
+
+Please paste your raw system ping that causing your issue below
+
+```
+RAW OUTPUT Ping example HERE
+```

.github/workflows/build-test-coverage.yml

@@ -31,6 +31,10 @@ jobs:
         npm run lint
         npm run test
 
+    - name: DTS are up to date
+      run: |
+        npx grunt diffDts
+
     - name: Covergae
       run: |
         npm run coverage

.gitignore

@@ -16,3 +16,5 @@ node_modules
 npm-debug.log
 dist/
 .nyc_output/
+
+*.d.ts.map

CONTRIBUTING.md

@@ -3,6 +3,18 @@
 We welcome patches and features. There are however a few things that are
 required before your pull request can be merged.
 
+# Development
+
+## About TypeScript Support
+
+Currently, this is still a common js module or library. We provide typescript definitions only.
+
+Please make sure to run following for updating the typescript definition files accordingly.
+
+```shell
+npx grunt makeDts
+```
+
 # Tests
 
 ## How to write a new test case

Gruntfile.js

@@ -1,9 +1,13 @@
 'use strict';
 
+/**
+ * Grunt configuration
+ * @param {import('grunt')} grunt - The Grunt instance
+ */
 module.exports = function (grunt) {
     grunt.initConfig({
         eslint: {
-            src: ['lib/*.js', 'lib/**/*.js'],
+            src: ['Gruntfile.js', 'tasks/*.js', 'lib/*.js', 'lib/**/*.js'],
             options: {
                 overrideConfigFile: 'eslint.config.js',
             },
@@ -33,12 +37,27 @@ module.exports = function (grunt) {
             src: 'dist/coverage/*.info',
             options: {},
         },
+        makeDts: {
+            options: {
+                config: 'tsconfig.json',
+            },
+        },
+        diffDts: {
+            options: {
+                config: 'tsconfig.json',
+            },
+        },
+        runTsdTest: {
+            options: {},
+        },
     });
 
     grunt.loadNpmTasks('grunt-eslint');
     grunt.loadNpmTasks('grunt-mocha-test');
     grunt.loadNpmTasks('grunt-nyc-mocha');
     grunt.loadNpmTasks('grunt-coveralls');
-    grunt.registerTask('test', ['eslint', 'mochaTest']);
+
+    grunt.loadTasks('tasks');
+    grunt.registerTask('test', ['eslint', 'mochaTest', 'runTsdTest']);
     grunt.registerTask('coverage', ['nyc_mocha']);
 };

README.md

@@ -88,6 +88,7 @@ hosts.forEach(function (host) {
 
 
 ## Async-Await
+
 ```js
 var ping = require('ping');
 
@@ -100,6 +101,7 @@ for(let host of hosts){
 ```
 
 ## Async-Await with configurable ping options
+
 ```js
 var ping = require('ping');
 
@@ -116,62 +118,17 @@ for(let host of hosts){
 ```
 ### Support configuration
 
-Below is the possible configuration
-
-```js
-/**
- * Cross platform config representation
- * @typedef {Object} PingConfig
- * @property {boolean} numeric - Map IP address to hostname or not
- * @property {number} timeout - Timeout in seconds for each ping request.
- * Behaviour varies between platforms. Check platform ping documentation for more information.
- * @property {number} deadline - Specify a timeout, in seconds, before ping exits regardless of
-              how many packets have been sent or received. In this case ping
-              does not stop after count packet are sent, it waits either for
-              deadline expire or until count probes are answered or for some
-              error notification from network. This option is only available on linux and mac.
- * @property {number} min_reply - Exit after sending number of ECHO_REQUEST
- * @property {boolean} v6 - Ping via ipv6 or not. Default is false
- * @property {string} sourceAddr - source address for sending the ping
- * @property {number} packetSize - Specifies the number of data bytes to be sent
-                                   Default: Linux / MAC: 56 Bytes, Windows: 32 Bytes
- * @property {string[]} extra - Optional options does not provided
- */
-```
+See `PingConfig` in `types/index.d.ts`
 
 ### Output specification
 
 * For callback based implementation:
 
-```js
-/**
- * Callback after probing given host
- * @callback probeCallback
- * @param {boolean} isAlive - Whether target is alive or not
- * @param {Object} error - Null if no error occurs
- */
-```
+See `probeCallback` in `types/ping-sys.d.ts`
 
 * For promise based implementation
 
-```js
-/**
- * Parsed response
- * @typedef {object} PingResponse
- * @param {string} inputHost - The input IP address or HOST
- * @param {string} host - Parsed host from system command's output
- * @param {string} numeric_host - Target IP address
- * @param {boolean} alive - True for existed host
- * @param {string} output - Raw stdout from system ping
- * @param {number} time - Time (float) in ms for first successful ping response
- * @param {Array} times - Array of Time (float) in ms for each ping response
- * @param {string} min - Minimum time for collection records
- * @param {string} max - Maximum time for collection records
- * @param {string} avg - Average time for collection records
- * @param {string} packetLoss - Packet Losses in percent (100% -> "100.000")
- * @param {string} stddev - Standard deviation time for collected records
- */
-```
+See `PingResponse` in `types/ping-promise.d.ts`
 
 #### Note
 

eslint.config.js

@@ -1,7 +1,8 @@
 'use strict';
 
 const babelParser = require('@babel/eslint-parser');
-const jsdocPlugin = require('eslint-plugin-jsdoc');
+const jsdoc = require('eslint-plugin-jsdoc');
+const mochaPlugin = require('eslint-plugin-mocha').default;
 const {defineConfig} = require('eslint/config');
 
 const customGlobals = {
@@ -997,9 +998,15 @@ const jsdocRules = {
     'jsdoc/require-param': 0,
 };
 
+const mochaRules = {
+    'mocha/no-setup-in-describe': 'off',
+};
+
 module.exports = defineConfig([
+    jsdoc.configs['flat/recommended'],
+    mochaPlugin.configs.recommended,
     {
-        files: ['**/*.js'],
+        files: ['Gruntfile.js', '**/*.js'],
         languageOptions: {
             sourceType: 'commonjs',
             parser: babelParser,
@@ -1019,11 +1026,11 @@ module.exports = defineConfig([
             },
         },
         plugins: {
-            jsdoc: jsdocPlugin,
         },
         rules: {
             ...styleRules,
             ...jsdocRules,
+            ...mochaRules,
         },
     },
 ]);

examples/example.js

@@ -2,7 +2,7 @@
 
 'use strict';
 
-var ping = require('../index');
+var ping = require('../lib/index');
 
 var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];
 hosts.forEach(function (host) {

examples/example2.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var ping = require('../index');
+var ping = require('../lib/index');
 
 var hosts = ['192.168.1.1', 'google.com', 'yahoo.com'];
 
@@ -19,9 +19,9 @@ hosts.forEach(function (host) {
         timeout: 10,
         extra: ['-i', '2'],
     })
-    .then(function (res) {
-        console.log(res);
-    });
+        .then(function (res) {
+            console.log(res);
+        });
 });
 
 // Running ping with some default argument gone
@@ -32,7 +32,7 @@ hosts.forEach(function (host) {
         // Below extra arguments may not work in platforms other than linux
         extra: ['-i', '2'],
     })
-    .then(function (res) {
-        console.log(res);
-    });
+        .then(function (res) {
+            console.log(res);
+        });
 });

examples/example_win_de_v6.js

@@ -2,7 +2,7 @@
 
 'use strict';
 
-var ping = require('../index');
+var ping = require('../lib/index');
 
 var hosts = ['google.de']; // , '192.168.1.1', 'google.com', 'yahoo.com'];
 
@@ -14,10 +14,10 @@ hosts.forEach(function (host) {
         sourceAddr: 'your NIC\'s IPv6 address',
         // sourceAddr: false,
     })
-    .then(function (res) {
-        console.log('\n');
-        console.log(res);
-    });
+        .then(function (res) {
+            console.log('\n');
+            console.log(res);
+        });
 
     // Running ping with some default argument gone
     ping.sys.probe(host, function (isAlive) {