api-poller-worker
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
- Demo
- Installation
- Usage
- API
- Classes
- Utils
- Types
Demo
Hosted demo: https://api-poller-worker.netlify.com/
You can also run the demo locally. To get started:
git clone git@github.com:brianmcallister/api-poller-worker.gitcd api-poller-worker/demonpm inpm start
⇡ Top
Installation
npm install api-poller-worker
⇡ Top
Usage
How to get started
There are two ways to use this library:
- Set
inline
totrue
when creating anApiPollerWorker
. 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 theWorkerCore
class.
Option 1: Inline worker
Here's an example of how to create an inline worker:
; worker.onMessageconsole.logdata;
Option 2: Create your own Worker.
There are two distinct steps to getting this working:
- Create an
ApiPollerWorker
instance in your application, and subscribe to updates. - Create a web worker, and create a
WorkerCore
instance 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.
In short, you need to tell your ApiPollerWorker
where your worker is, and then in your worker, you need to tell WorkerCore
where the API endpoint you'd like to poll is.
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.
Assumptions
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:
⇡ Top
API
Classes
ApiPollerWorker
;
The ApiPollerWorker
class is what coordinates the communcation between
your app and your worker. The constructor accepts the following:
ApiPollerWorker#start
Send a message (via postMessage
) to the worker, telling it to start polling.
start: this;
; pollerWorker.start;
ApiPollerWorker#stop
Send a message (via postMessage
) to the worker, telling it to stop polling.
stop: this;
; pollerWorker.stop;
ApiPollerWorker#onMessage
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.
onMessagecallback:void: this;
; pollerWorker.onMessage;
⇡ Top
WorkerCore
;
The 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).
worker.ts
; ; new WorkerCore;
⇡ Top
Utils
createEmptyMsg
Create the Msg<T>
structure, but empty. Useful for building default state for a slice of Redux state.
;
createEmptyMsg: Msg<T>
⇡ Top
Types
Records<T>
Keep track of a normalized set of records.
;
⇡ Top
Msg<T>
Represents the contents of the message emitted by the WorkerCore
.
;
⇡ Top
ApiPollerWorkerOptions
Options object accepted by ApiPollerWorker
.
;