expose detailed queue params

Author: mtrezza

README.md

@@ -188,9 +188,15 @@ For more information see the [Expo docs](https://docs.expo.dev/push-notification
 
 ### Throttling
 
-Push providers usually throttle their APIs, so that sending too many pushes notifications within a short time may cause the API not accept any more requests. To address this, push sending can be throttled per provider by adding a `throttle` option to the respective push configuration. The option `maxPerSecond` defines the maximum number of pushes sent per second. If not throttle is configured, pushes are sent as quickly as possible.
+By default, pushes are sent as fast as possible. However, push providers usually throttle their APIs, so that sending too many pushes notifications within a short time may cause the API to reject requests. To address this, push sending can be throttled per provider by adding the `queue` option to the respective push configuration.
 
-Example throttle configuration:
+| Parameter                | Default    | Optional | Description                                                                                |
+|--------------------------|------------|----------|--------------------------------------------------------------------------------------------|
+| `queue.concurrency`      | `Infinity` | Yes      | The maximum number of pushes to process concurrently.                                      |
+| `queue.intervalCapacity` | `Infinity` | Yes      | The interval capacity, meaning the maximum number of tasks to process in a given interval. |
+| `queue.interval`         | `0`        | Yes      | The interval in milliseconds for the interval capacity.                                    |
+
+Example configuration to throttle the queue to max. 1 push every 100ms, equivalent to max. 10 pushes per second:
 
 ```js
 const parseServerOptions = {
@@ -199,14 +205,39 @@ const parseServerOptions = {
       ios: {
         // ...
         queue: {
-          throttle: { maxPerSecond: 100 }
-        }
+          concurrency: 1,
+          intervalCapacity: 1,
+          interval: 100,
+        },
       }
     })
   }
 };
 ```
 
+Keep in mind that `concurrency: 1` means that pushes are sent in serial. For example, if sending a request to the push provider takes up to 500ms to complete, then the configuration above may be limited to only 2 pushes per second if every request takes 500ms. To address this, you can send pushes in parallel by setting the concurrency to a value greater than `1`, and increasing `intervalCapacity` and `interval` to fully utilize parallelism.
+
+Example configuration sending pushes in parallel:
+
+```js
+const parseServerOptions = {
+  push: {
+    adapter: new ParsePushAdapter({
+      ios: {
+        // ...
+        queue: {
+          concurrency: 5,
+          intervalCapacity: 5,
+          interval: 500,
+        },
+      }
+    })
+  }
+};
+```
+
+In the example above, pushes will be sent in bursts of 5 at once, with max. 10 pushes within 1s. On a timeline that means at `t=0ms`, 5 pushes will be sent in parallel. If sending the pushes take less than 500ms, then `intervalCapacity` will still limit to 5 pushes within the first 500ms. At `t=500ms` the second interval begins and another max. 5 pushes are sent in parallel. That effectively means a throughput of up to 10 pushes per second.
+
 ### Push Options
 
 Each push request may specify the following options for handling in the queue.

spec/ParsePushAdapter.spec.js

@@ -650,7 +650,9 @@ describe('ParsePushAdapter', () => {
         senderId: 'id',
         apiKey: 'key',
         queue: {
-          throttle: { maxPerSecond: 1 }
+          concurrency: 1,
+          intervalCapacity: 1,
+          interval: 1_000,
         },
       },
     };
@@ -676,7 +678,9 @@ describe('ParsePushAdapter', () => {
         senderId: 'id',
         apiKey: 'key',
         queue: {
-          throttle: { maxPerSecond: 1 }
+          concurrency: 1,
+          intervalCapacity: 1,
+          interval: 1_000,
         },
       },
     };
@@ -699,7 +703,9 @@ describe('ParsePushAdapter', () => {
         senderId: 'id',
         apiKey: 'key',
         queue: {
-          throttle: { maxPerSecond: 1 }
+          concurrency: 1,
+          intervalCapacity: 1,
+          interval: 1_000,
         },
       },
     };

spec/ThrottleQueue.spec.js

@@ -3,7 +3,7 @@ import { wait } from './helper.js';
 
 describe('ThrottleQueue', () => {
   it('processes items respecting rate limit', async () => {
-    const q = new ThrottleQueue(1);
+    const q = new ThrottleQueue({ concurrency: 1, intervalCap: 1, interval: 1_000 });
     const times = [];
     const p1 = q.enqueue({ task: () => { times.push(Date.now()) } });
     const p2 = q.enqueue({ task: () => { times.push(Date.now()) } });
@@ -14,7 +14,7 @@ describe('ThrottleQueue', () => {
   });
 
   it('drops expired items', async () => {
-    const q = new ThrottleQueue(1);
+    const q = new ThrottleQueue({ concurrency: 1, intervalCap: 1, interval: 1_000 });
     const results = [];
     const p1 = q.enqueue({ task: () => wait(1_200) });
     const p2 = q.enqueue({ task: () => { throw new Error('should not run'); }, ttl: 1 });
@@ -24,7 +24,7 @@ describe('ThrottleQueue', () => {
   });
 
   it('processes higher priority tasks first', async () => {
-    const q = new ThrottleQueue(1);
+    const q = new ThrottleQueue({ concurrency: 1, intervalCap: 1, interval: 1_000 });
     const results = [];
 
     // Block queue with task so that the queue scheduler doesn't start processing enqueued items

src/ParsePushAdapter.js

@@ -57,9 +57,10 @@ export default class ParsePushAdapter {
         }
         break;
       }
-      if (pushConfig[pushType].throttle) {
-        const rate = pushConfig[pushType].throttle.maxPerSecond;
-        this.queues[pushType] = new ThrottleQueue(rate);
+      const queue = pushConfig[pushType].queue;
+      if (queue) {
+        const { concurrency, intervalCapacity, interval } = queue || {};
+        this.queues[pushType] = new ThrottleQueue({ concurrency, intervalCap: intervalCapacity, interval });
       }
     }
   }

src/ThrottleQueue.js

@@ -3,18 +3,19 @@ import PQueue from 'p-queue';
 export default class ThrottleQueue {
 
   /**
-   * Creates an instance of ThrottleQueue.
+   * Creates an instance of ThrottleQueue. If no parameters are provided, then the queue will have no
+   * throttling and will process tasks as fast as possible.
    *
-   * @param {number} [maxPerSecond=Infinity] The maximum number of tasks to process per second.
-   * Optional, defaults to Infinity (no limit).
+   * @param {Object} [options] The options.
+   * @param {number} [options.concurrency=Infinity] The maximum number of tasks to process concurrently.
+   * Optional, defaults to `Infinity`, meaning no limit on concurrency.
+   * @param {number} [options.intervalCap=Infinity] The interval capacity, meaning the maximum number of
+   * tasks to process in a given interval. Optional, defaults to `Infinity`, meaning no interval limit.
+   * @param {number} [options.interval=0] The interval in milliseconds for the interval capacity.
+   * Optional, defaults to `0`, meaning no interval limit.
    */
-  constructor(maxPerSecond = Infinity) {
-    if (maxPerSecond === Infinity) {
-      this.queue = new PQueue({ concurrency: Infinity });
-    } else {
-      const interval = Math.ceil(1000 / maxPerSecond);
-      this.queue = new PQueue({ concurrency: 1, intervalCap: 1, interval });
-    }
+  constructor({ concurrency = Infinity, intervalCap = Infinity, interval = 0 } = {}) {
+    this.queue = new PQueue({ concurrency, intervalCap, interval });
   }
 
   /**