client-run-queue

This package provides a RunQueue implementation for scheduling and managing async or time-consuming functions such that client-side interactivity disruptions are minimized.

Usage Examples

Try it Out – CodeSandbox

1import { CANCELED, DEFAULT_PRIORITY, RunQueue } from 'client-run-queue';
2
3const main = async () => {
4  const q = new RunQueue('my-queue');
5
6  const doSomeWork = async () => {
7    // …do some work – just sleeping for some random time to simulate work here
8    await new Promise((resolve) => setTimeout(resolve, Math.random() * 1000));
9
10    return Math.random();
11  };
12
13  // Scheduling an entry
14
15  const entry = q.schedule(DEFAULT_PRIORITY, 'my-function', doSomeWork);
16
17  // Checking its various statuses
18
19  console.log('canceled', entry.wasCanceled());
20  console.log('completed', entry.wasCompleted());
21  console.log('started', entry.wasStarted());
22
23  // Waiting for it to complete
24
25  const result = await entry.promise;
26  if (result.ok) {
27    console.log('success', result.details);
28  } else if (result.details === CANCELED) {
29    console.log('canceled');
30  } else {
31    console.log('failure', result.details);
32  }
33
34  // Scheduling more entries using different priorities and options
35
36  q.schedule(2, 'my-function', doSomeWork, { delayMSec: 1000 });
37  q.schedule(0, 'my-function', doSomeWork, { neverCancel: true });
38  q.schedule(1, 'my-function', doSomeWork);
39
40  // Checking the queue length
41
42  console.log('queue length', q.getQueueLength());
43
44  // Canceling everything
45
46  q.cancelAll();
47};
48main();

Configuration

With RunQueue, one can specify:

• max parallelism
• max work units and/or continuous work duration per loop iteration
• priority and cancellable per entry (runnable function)

You may then:

• check the status of entries
• request cancellation of specific or all entries
• wait for the promised values of entries

In addition to configuring individual RunQueues in the ways mentioned above, you may also specify:

• a runAfterInteractions function to customize the coordinated scheduling mechanism for your environment (ex. React Native uses InteractionManager.runAfterInteractions). See setRunAfterInteractions. By default, runAfterInteractions uses a 0ms timeout.
• Stats tracking functions for debugging and analyzing usage. See setStatsHandler.

React Native

As noted above, for React Native, it's recommended to use InteractionManager for runAfterInteractions. To do that, run code like the following, early in your programs execution:

1setRunAfterInteractions((_id, func) => {
2  const handle = InteractionManager.runAfterInteractions(func);
3
4  return handle.cancel;
5})

API Docs

Thanks

Thanks for checking it out. Feel free to create issues or otherwise provide feedback.

Be sure to check out our other TypeScript OSS projects as well.