Efficient polling with WebWorkers. Make existing APIs feel real time
api-poller-worker turns regular 'ol RESTful JSON APIs into realtime streaming connections (not really), using polling with web workers.
Table of contents
Hosted demo: https://api-poller-worker.netlify.com/
You can also run the demo locally. To get started:
git clone firstname.lastname@example.org:brianmcallister/api-poller-worker.gitcd api-poller-worker/demonpm inpm start
npm install api-poller-worker
How to get started
There are two ways to use this library:
truewhen creating an
ApiPollerWorker. Doing this will create an inline worker. Although this is much easier than option 2, if you need fine grained control over what's going on inside the worker (such as making other XHR requests, doing expensive calculations based on the data returned by the API that you're polling, etc.), you'll want to try...
- Provide a URL to a worker file. Within that worker file, you need to create an instance of
WorkerCore. If you do this, you now have the ability to manipulate the data from the API endpoint before you pass it back to your application. You also have the ability to pass more fine grained options to the
Option 1: Inline worker
Here's an example of how to create an inline worker:
Option 2: Create your own Worker.
There are two distinct steps to getting this working:
- Create an
ApiPollerWorkerinstance in your application, and subscribe to updates.
- Create a web worker, and create a
WorkerCoreinstance inside of it.
What this library does not help with is creating the worker files themselves. You'll have to set this up in your application's build pipeline, but there are many resources available online to guide you. You can also check out the demo application source to see how I like to set it up.
The reason for structuring the code this way is so that you can do other operations on the data from your polled API endpoint in your worker, before passing the data back to your application.
Internally, there are some assumptions being made about the API that is being polled. Specifically that the API endpoint responds with JSON, as a list of objects with a unique identifier.
Which key is used as the unique identifier is configurable (see
WorkerCore), but there does need to be one. As long as your endpoint responds with something like this, everything should work just fine:
ApiPollerWorker class is what coordinates the communcation between
your app and your worker. The constructor accepts the following:
Send a message (via
postMessage) to the worker, telling it to start polling.
Send a message (via
postMessage) to the worker, telling it to stop polling.
Subscribe to updates from the
ApiPollerWorker instance. The response is a
Msg<T>, which is structured so that your application will know exactly which resources in your polled endpoint are new, updated, or removed.
WorkerCore class is the what you need to create an instance of in your Worker. The constructor accepts the following options:
Here's an example of the simplest possible Worker file (with type safety).
Msg<T> structure, but empty. Useful for building default state for a slice of Redux state.
Keep track of a normalized set of records.
Represents the contents of the message emitted by the
Options object accepted by