feat: support ES6 Promise

khang-nd · khang-nd · commit 0f03988f81b6 · 2021-04-14T11:35:42.000+07:00
diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ This module is for the browser only as it depends on the brower's `Image` API.
 ```javascript
 var p = new Ping();
 
+// Using callback
 p.ping("https://github.com", function(err, data) {
   // Also display error if err is returned.
   if (err) {
@@ -28,6 +29,15 @@ p.ping("https://github.com", function(err, data) {
   }
   document.getElementById("ping-github").innerHTML = data;
 });
+
+// You may use Promise if the browser supports ES6
+p.ping("https://github.com")
+  .then(data => {
+    console.log("Successful ping: " + data);
+  })
+  .catch(data => {
+    console.error("Ping failed: " + data);
+  })
 ```
 
 or import as a module:
@@ -58,21 +68,18 @@ var p = new Ping(opt);
 
 Create Ping instance.
 
-#### options
-Type: `Object`
-
-`favicon` Override the default `favicon.ico` image location.
+#### `options`
 
-`timeout` Optional - Set a timeout in milliseconds.
+* Type: `Object`
+* `favicon`: Override the default `favicon.ico` image location.
+* `timeout`: Optional - Set a timeout in milliseconds.
 
 ### p.ping(source, callback)
 
-Creates a ping request to the `source`.
-
-`source` IP address or website URL, including protocol and port (optional). Example: `https://example.com:8080`
-
-`callback(err, ping)` Callback function which returns an error and the response time in milliseconds.
+Creates a ping request to the `source`. Returns a promise that resolves and rejects to the response time in milliseconds, or if the browser does not supports Promise, returns undefined.
 
+* `source`: IP address or website URL, including protocol and port (optional). Example: `https://example.com:8080`
+* `callback(err, ping)`: Optional - Callback function which returns an error and the response time in milliseconds.
 
 ## Development
 
diff --git a/demo/index.html b/demo/index.html
@@ -12,6 +12,7 @@
 	<body>
     <script src="../src/ping.js" type="text/javascript"></script>
 
+    <h2>Callback</h2>
     <ul>
       <li>google.com <span id="ping-google"></span></li>
       <li>guildbit.com <span id="ping-guildbit"></span></li>
@@ -20,6 +21,13 @@
       <li>am.guildbit.com <span id="ping-guildbit-am"></span></li>
     </ul>
 
+    <h2>Promise</h2>
+    <ul>
+      <li>facebook.com <span id="ping-facebook"></span></li>
+      <li>reddit.com <span id="ping-reddit"></span></li>
+      <li>linkedin.com <span id="ping-linkedin"></span></li>
+    </ul>
+
     <script src="https://gist.github.com/alfg/c44d8b061972879c9121.js"></script>
 
     <script>
@@ -70,6 +78,30 @@
         document.getElementById("ping-guildbit-am").innerHTML = data;
       });
 
+      p.ping("http://facebook.com")
+        .then(function(data) {
+          document.getElementById("ping-facebook").innerHTML = data;
+        })
+        .catch(function(data) {
+          document.getElementById("ping-facebook").innerHTML = data + " error";
+        })
+
+      p.ping("http://reddit.com")
+        .then(function(data) {
+          document.getElementById("ping-reddit").innerHTML = data;
+        })
+        .catch(function(data) {
+          document.getElementById("ping-reddit").innerHTML = data + " error";
+        })
+
+      p.ping("http://linkedin.com")
+        .then(function(data) {
+          document.getElementById("ping-linkedin").innerHTML = data;
+        })
+        .catch(function(data) {
+          document.getElementById("ping-linkedin").innerHTML = data + " error";
+        })
+
     </script>
 	</body>
 </html>
diff --git a/dist/ping.js b/dist/ping.js
@@ -1,5 +1,5 @@
 /*
- *  ping.js - v0.2.2
+ *  ping.js - v0.3.0
  *  Ping Utilities in Javascript
  *  http://github.com/alfg/ping.js
  *
@@ -20,11 +20,19 @@ var Ping = function(opt) {
 
 /**
  * Pings source and triggers a callback when completed.
- * @param source Source of the website or server, including protocol and port.
- * @param callback Callback function to trigger when completed. Returns error and ping value.
- * @param timeout Optional number of milliseconds to wait before aborting.
+ * @param {string} source Source of the website or server, including protocol and port.
+ * @param {Function} callback Callback function to trigger when completed. Returns error and ping value.
+ * @returns {Promise|undefined} A promise that both resolves and rejects to the ping value. Or undefined if the browser does not support Promise.
  */
 Ping.prototype.ping = function(source, callback) {
+    var promise, resolve, reject;
+    if (typeof Promise !== "undefined") {
+        promise = new Promise(function(_resolve, _reject) {
+            resolve = _resolve;
+            reject = _reject;
+        });
+    }
+
     var self = this;
     self.wasSuccess = false;
     self.img = new Image();
@@ -57,18 +65,29 @@ Ping.prototype.ping = function(source, callback) {
         if (timer) { clearTimeout(timer); }
         var pong = new Date() - start;
 
-        if (typeof callback === "function") {
+        if (!callback) {
+            if (promise) {
+                return this.wasSuccess ? resolve(pong) : reject(pong);
+            } else {
+                throw new Error("Promise is not supported by your browser. Use callback instead.");
+            }
+        } else if (typeof callback === "function") {
             // When operating in timeout mode, the timeout callback doesn't pass [event] as e.
             // Notice [this] instead of [self], since .call() was used with context
             if (!this.wasSuccess) {
                 if (self.logError) { console.error("error loading resource"); }
+                if (promise) { reject(pong); }
                 return callback("error", pong);
             }
+            if (promise) { resolve(pong); }
             return callback(null, pong);
+        } else {
+            throw new Error("Callback is not a function.");
         }
     }
 
     self.img.src = source + self.favicon + "?" + (+new Date()); // Trigger image load with cache buster
+    return promise;
 };
 
 if (typeof exports !== "undefined") {
diff --git a/dist/ping.min.js b/dist/ping.min.js
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "ping.js",
   "description": "Ping Utilities with Javascript",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "author": "Alf <alf.g.jr@gmail.com>",
   "main": "index.js",
   "devDependencies": {
diff --git a/pingjs.json b/pingjs.json
@@ -3,7 +3,7 @@
 	"title": "ping.js",
 	"description": "Ping Utilities in Javascript",
     "keywords": ["javascript", "ping", "utilities"],
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"author": {
 		"name": "Alfred Gutierrez",
 		"email": "alf.g.jr@gmail.com",
diff --git a/src/ping.js b/src/ping.js
@@ -12,11 +12,19 @@ var Ping = function(opt) {
 
 /**
  * Pings source and triggers a callback when completed.
- * @param source Source of the website or server, including protocol and port.
- * @param callback Callback function to trigger when completed. Returns error and ping value.
- * @param timeout Optional number of milliseconds to wait before aborting.
+ * @param {string} source Source of the website or server, including protocol and port.
+ * @param {Function} callback Callback function to trigger when completed. Returns error and ping value.
+ * @returns {Promise|undefined} A promise that both resolves and rejects to the ping value. Or undefined if the browser does not support Promise.
  */
 Ping.prototype.ping = function(source, callback) {
+    var promise, resolve, reject;
+    if (typeof Promise !== "undefined") {
+        promise = new Promise(function(_resolve, _reject) {
+            resolve = _resolve;
+            reject = _reject;
+        });
+    }
+
     var self = this;
     self.wasSuccess = false;
     self.img = new Image();
@@ -49,18 +57,29 @@ Ping.prototype.ping = function(source, callback) {
         if (timer) { clearTimeout(timer); }
         var pong = new Date() - start;
 
-        if (typeof callback === "function") {
+        if (!callback) {
+            if (promise) {
+                return this.wasSuccess ? resolve(pong) : reject(pong);
+            } else {
+                throw new Error("Promise is not supported by your browser. Use callback instead.");
+            }
+        } else if (typeof callback === "function") {
             // When operating in timeout mode, the timeout callback doesn't pass [event] as e.
             // Notice [this] instead of [self], since .call() was used with context
             if (!this.wasSuccess) {
                 if (self.logError) { console.error("error loading resource"); }
+                if (promise) { reject(pong); }
                 return callback("error", pong);
             }
+            if (promise) { resolve(pong); }
             return callback(null, pong);
+        } else {
+            throw new Error("Callback is not a function.");
         }
     }
 
     self.img.src = source + self.favicon + "?" + (+new Date()); // Trigger image load with cache buster
+    return promise;
 };
 
 if (typeof exports !== "undefined") {

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "ping.js",`
`3`	`3`	`"description": "Ping Utilities with Javascript",`
`4`		`- "version": "0.2.3",`
	`4`	`+ "version": "0.3.0",`
`5`	`5`	`"author": "Alf <[email protected]>",`
`6`	`6`	`"main": "index.js",`
`7`	`7`	`"devDependencies": {`