ember-poller

A polling addon for ember based on ember-concurrency

What does it offer?

• Easy and handy polling state management
• Multiple and isolated polling support
• Automatic polling destruction upon the destruction of the object that pollings live on
• Cancellable on demand
• A test helper to increase testability

Installation

ember install ember-poller

Sample Usages

You can initiate the poller using a ember-concurrency task.

import { reject } from 'rsvp';
import { task } from 'ember-concurrency';
poller: service(),
// Somewhere on the code call track method of the poller
let pollerUnit = this.get('poller').track({
  pollingInterval: 1000,
  retryLimit: 30,
  pollTask: this.get('pollTask'),
});
this.set('pollerUnit', pollerUnit);
pollTask: task(function*() {
  let response = yield this.get('someModel').reload();
  if (response.status == 'done') {
    return true; // if your task succeeds return true, so that poller service understands the task is successfully completed
  } else if (response == 'error') {
    return reject(); // if you have an error case basically reject the promise
  }
  // if polling needs to continue basically do nothing.
})

If you don’t use ember-concurrency on your project, you can also provide an async function as a polling method.

import { reject } from 'rsvp';
poller: service(),
// Somewhere on the code call track method of the poller
let pollerUnit = this.get('poller').track({
  pollingInterval: 1000,
  retryLimit: 30,
  pollingFunction: () => this.pollingFunction(),
});
this.set('pollerUnit', pollerUnit);
async pollingFunction() {
  let response = await this.get('someModel').reload();
  if (response.status == 'done') {
    return true; // if your task succeeds return true, so that poller service understands the task is successfully completed
  } else if (response == 'error') {
    return reject(); // if you have an error case basically reject the promise
  }
  // if polling needs to continue basically do nothing.
}

Arguments other than option parameter will be passed directly to your pollingTask or pollingFunction.

import { reject } from 'rsvp';
import { task } from 'ember-concurrency';
poller: service(),
// Somewhere on the code call track method of the poller
let pollerUnit = this.get('poller').track({
  pollingInterval: 1000,
  retryLimit: 30,
  pollTask: this.get('pollTask'),
}, 17, 89);
this.set('pollerUnit', pollerUnit);
pollTask: task(function*(min, max) {
  let response = yield this.get('someModel').reload();
  console.log(min); // 17
  console.log(max); // 89
  if (response == 'error') {
    return reject(); // if you have an error case basically reject the promise
  } else if (response.get('anAttribute') > min && response.get('anAttribute') < max) {
    return true; // if your task succeeds return true, so that poller service understands the task is successfully completed
  }
  // if polling needs to continue basically do nothing.
})

You can also cancel polling using the abort method.

let pollerUnit = this.get('poller').track({ pollTask: this.get('pollTask') });
pollerUnit.abort(); // cancels the polling
pollerUnit.isCancelled; // returns true.

You can track the state of the polling with the attributes of PollerUnit.

pollerUnit.get('isError'); // true if polling is failed(an exception throwed or promise rejected), false otherwise.
pollerUnit.get('isFailed'); // alias of isError
pollerUnit.get('isSuccessful'); // true if polling is succeeded(a `truthy` value is returned), false otherwise.
pollerUnit.get('isRunning'); // true if polling is running, meaning it is not failed, succeeded, canceled or timed out.
pollerUnit.get('isCanceled'); // true if polling is canceled using [abort()](#abort) method.
pollerUnit.get('isCancelled'); // alias of isCanceled
pollerUnit.get('isTimeout'); // true if polling terminates without success, failure and cancellation.
pollerUnit.get('retryCount'); // returns the number of pollings made since polling started.
`

For further reference, you may look API docs.

Testing

You can stub track method in your tests in your acceptance and integration tests.

let pollerService = this.owner.lookup('service:poller');
this.stub(pollerService, 'track').returns({ isRunning: true }); // sinon implementation

Test Helper

You can also inject a stubbed poller to your tests and set the pollingInterval to zero. To test your success, error, timeout case all you need is to arrange your data/mocks as intended. An example can be found below.

import injectPoller from 'ember-poller/test-helpers/poller-stub';
test('it supports polling methods with arguments', async function(assert) {
  assert.expect(5);
  injectPoller(this);
  // Arrange
  // Act
  // Assert
});

Optionally, you can also pass stubbedOptions to injectPoller. This will override your parameters specified in your code.

import injectPoller from 'ember-poller/test-helpers/poller-stub';
test('it supports polling methods with arguments', async function(assert) {
  assert.expect(5);
  injectPoller(this, {
    pollingInterval: 10,
    retryLimit: 5,
  });
  // Arrange
  // Act
  // Assert
});