reduce use of callbacks

Author: cbaker6

README.md

@@ -59,7 +59,7 @@ var options = {
   production: false
 };
 
-var apnProvider = new apn.Provider(options);
+const apnProvider = new apn.Provider(options);
 ```
 
 By default, the provider will connect to the sandbox unless the environment variable `NODE_ENV=production` is set.
@@ -68,6 +68,10 @@ For more information about configuration options consult the [provider documenta
 
 Help with preparing the key and certificate files for connection can be found in the [wiki][certificateWiki]
 
+⚠️ You should only create one `Provider` per-process for each certificate/key pair you have. You do not need to create a new `Provider` for each notification. If you are only sending notifications to one app then there is no need for more than one `Provider`.
+
+If you are constantly creating `Provider` instances in your app, make sure to call `Provider.shutdown()` when you are done with each provider to release its resources and memory.
+
 ### Connecting through an HTTP proxy
 
 If you need to connect through an HTTP proxy, you simply need to provide the `proxy: {host, port}` option when creating the provider. For example:
@@ -86,7 +90,7 @@ var options = {
   production: false
 };
 
-var apnProvider = new apn.Provider(options);
+const apnProvider = new apn.Provider(options);
 ```
 
 The provider will first send an HTTP CONNECT request to the specified proxy in order to establish an HTTP tunnel. Once established, it will create a new secure connection to the Apple Push Notification provider API through the tunnel.
@@ -111,7 +115,7 @@ var options = {
   production: false
 };
 
-var apnProvider = new apn.MultiProvider(options);
+const apnProvider = new apn.MultiProvider(options);
 ```
 
 ## Sending a notification
@@ -124,7 +128,7 @@ let deviceToken = "a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da1
 Create a notification object, configuring it with the relevant parameters (See the [notification documentation](doc/notification.markdown) for more details.)
 
 ```javascript
-var note = new apn.Notification();
+let note = new apn.Notification();
 
 note.expiry = Math.floor(Date.now() / 1000) + 3600; // Expires 1 hour from now.
 note.badge = 3;
@@ -137,9 +141,12 @@ note.topic = "<your-app-bundle-id>";
 Send the notification to the API with `send`, which returns a promise.
 
 ```javascript
-apnProvider.send(note, deviceToken).then( (result) => {
+try {
+  const result = apnProvider.send(note, deviceToken);
   // see documentation for an explanation of result
-});
+} catch(error) {
+  // Handle error...
+}
 ```
 
 This will result in the the following notification payload being sent to the device
@@ -151,7 +158,7 @@ This will result in the the following notification payload being sent to the dev
 Create a Live Activity notification object, configuring it with the relevant parameters (See the [notification documentation](doc/notification.markdown) for more details.)
 
 ```javascript
-var note = new apn.Notification();
+let note = new apn.Notification();
 
 note.expiry = Math.floor(Date.now() / 1000) + 3600; // Expires 1 hour from now.
 note.badge = 3;
@@ -170,9 +177,12 @@ note.contentState = {}
 Send the notification to the API with `send`, which returns a promise.
 
 ```javascript
-apnProvider.send(note, deviceToken).then( (result) => {
+try {
+  const result = await apnProvider.send(note, deviceToken)
   // see documentation for an explanation of result
-});
+} catch (error) {
+  // Handle error...
+}
 ```
 
 This will result in the the following notification payload being sent to the device
@@ -182,6 +192,6 @@ This will result in the the following notification payload being sent to the dev
 {"messageFrom":"John Appleseed","aps":{"badge":3,"sound":"ping.aiff","alert":"\uD83D\uDCE7 \u2709 You have a new message", "relevance-score":75,"timestamp":1683129662,"stale-date":1683216062,"event":"update","content-state":{}}}
 ```
 
-You should only create one `Provider` per-process for each certificate/key pair you have. You do not need to create a new `Provider` for each notification. If you are only sending notifications to one app then there is no need for more than one `Provider`.
+## Manage Channels
 
-If you are constantly creating `Provider` instances in your app, make sure to call `Provider.shutdown()` when you are done with each provider to release its resources and memory.
+## Sending Broadcast Notifications

doc/provider.markdown

@@ -103,7 +103,7 @@ If you wish to send notifications containing emoji or other multi-byte character
 
 Indicate to node-apn that it should close all open connections when the queue of pending notifications is fully drained. This will allow your application to terminate.
 
-**Note:** If notifications are pushed after the connection has started, an error will be thrown.
+**Note:** If notifications are pushed after the shutdown has started, an error will be thrown.
 
 [provider-api]: https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html
 [provider-auth-tokens]: https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html#//apple_ref/doc/uid/TP40008194-CH11-SW1

index.d.ts

@@ -192,7 +192,7 @@ export class Provider extends EventEmitter {
   /**
    * Indicate to node-apn that it should close all open connections when the queue of pending notifications is fully drained. This will allow your application to terminate.
    */
-  shutdown(callback?: () => void): void;
+  shutdown(callback?: () => void): Promise<void>;
 }
 
 export class MultiProvider extends EventEmitter {
@@ -238,7 +238,7 @@ export class MultiProvider extends EventEmitter {
   /**
    * Indicate to node-apn that it should close all open connections when the queue of pending notifications is fully drained. This will allow your application to terminate.
    */
-  shutdown(callback?: () => void): void;
+  shutdown(callback?: () => void): Promise<void>;
 }
 
 export type NotificationPushType = 'background' | 'alert' | 'voip' | 'pushtotalk' | 'liveactivity' | 'location' | 'complication' | 'fileprovider' | 'mdm';

lib/client.js

@@ -74,28 +74,19 @@ module.exports = function (dependencies) {
     }, this.config.heartBeat).unref();
   }
 
-  Client.prototype.destroySession = function (session, callback) {
+  Client.prototype.destroySession = function (session) {
     if (!session) {
-      if (callback) {
-        callback();
-      }
       return;
     }
     if (!session.destroyed) {
       session.destroy();
     }
     session = null;
-    if (callback) {
-      callback();
-    }
   };
 
   // Session should be passed except when destroying the client
-  Client.prototype.closeAndDestroySession = async function (session, callback) {
+  Client.prototype.closeAndDestroySession = async function (session) {
     if (!session) {
-      if (callback) {
-        callback();
-      }
       return;
     }
     if (!session.closed) {
@@ -105,7 +96,7 @@ module.exports = function (dependencies) {
         });
       });
     }
-    this.destroySession(session, callback);
+    this.destroySession(session);
   };
 
   Client.prototype.makePath = function makePath(type, subDirectory) {
@@ -667,8 +658,11 @@ module.exports = function (dependencies) {
     });
   };
 
-  Client.prototype.shutdown = async function shutdown() {
+  Client.prototype.shutdown = async function shutdown(callback) {
     if (this.isDestroyed) {
+      if (callback) {
+        callback();
+      }
       return;
     }
     if (this.errorLogger.enabled) {
@@ -685,6 +679,9 @@ module.exports = function (dependencies) {
     }
     await this.closeAndDestroySession(this.session);
     await this.closeAndDestroySession(this.manageChannelsSession);
+    if (callback) {
+      callback();
+    }
   };
 
   Client.prototype.setLogger = function (newLogger, newErrorLogger = null) {

lib/multiclient.js

@@ -30,19 +30,29 @@ module.exports = function (dependencies) {
     return client;
   };
 
-  MultiClient.prototype.write = function write(notification, device, type, method, count) {
-    return this.chooseSingleClient().write(notification, device, type, method, count);
+  MultiClient.prototype.write = async function write(
+    notification,
+    subDirectory,
+    type,
+    method,
+    count
+  ) {
+    return await this.chooseSingleClient().write(notification, subDirectory, type, method, count);
   };
 
-  MultiClient.prototype.shutdown = function shutdown(callback) {
+  MultiClient.prototype.shutdown = async function shutdown(callback) {
     let callCount = 0;
     const multiCallback = () => {
       callCount++;
       if (callCount === this.clients.length) {
-        callback();
+        if (callback) {
+          callback();
+        }
       }
     };
-    this.clients.forEach(client => client.shutdown(multiCallback));
+    for (const client of this.clients) {
+      await client.shutdown(multiCallback);
+    }
   };
 
   MultiClient.prototype.setLogger = function (newLogger, newErrorLogger = null) {

test/multiclient.js

@@ -131,8 +131,9 @@ describe('MultiClient', () => {
       }
     };
     if (client) {
-      await client.shutdown(closeServer);
-      client = null;
+      await client.shutdown(() => {
+        client = null;
+      });
     }
     await closeServer();
   });
@@ -1229,8 +1230,9 @@ describe('ManageChannelsMultiClient', () => {
       }
     };
     if (client) {
-      await client.shutdown();
-      client = null;
+      await client.shutdown(() => {
+        client = null;
+      });
     }
     await closeServer();
   });