dash.refresh

Run a function now, then again every so many seconds. Runs pause while nobody can see the pane, so a pane that is off screen does not use up your API calls.

dash.refresh(seconds: number, fn: () => unknown): () => void

Example

Show the latest Node.js release and check for a new one every five minutes. api.github.com must be listed under network in the pane’s manifest.

const stop = dash.refresh(300, async () => {
  const res = await dash.fetch('https://api.github.com/repos/nodejs/node/releases/latest');
  if (!res.ok) return;
  const release = await res.json();
  document.querySelector('#version').textContent = release.tag_name;
});

document.querySelector('#pause').addEventListener('click', stop);

Arguments

Argument	Type	What it does
seconds	number	Time between runs. A value under 15 is raised to 15. A value that is not a finite number also means 15. Fractions above 15 are kept.
fn	() => unknown	The function to run. It can be async.

dash.refresh returns a stop() function. Calling it cancels every later run. A run that has already started is not interrupted.

Behaviour

• fn runs straight away, then every seconds.
• Runs never overlap. If an async fn has not finished when the next run is due, that run is skipped, not queued.
• A pane is hidden when it is scrolled out of view or its browser tab is in the background. Runs that fall due while it is hidden are skipped. When the pane is shown again, fn runs once straight away if a run was missed, and the interval starts again from that moment.
• If the pane is hidden when it starts, the first run waits until it is shown.
• You can call dash.refresh more than once. Each call has its own timer.
• If fn throws or its promise rejects, the error is reported like any uncaught error. In the editor it appears in the console. On a canvas the pane shows “This pane stopped” with a Reload button. Catch the errors you expect, such as a failed dash.fetch, inside fn.

Errors

dash.refresh does not return a promise, so it cannot reject. It throws a DashError straight away in one case:

Code	Why
VALIDATION_FAILED	fn is not a function.

The calls you make inside fn have their own errors. For dash.fetch, see its error codes.

Limits

• The shortest interval is 15 seconds.
• Every dash.fetch inside fn counts towards the account’s 60 calls a minute and 10 at once, and answers served from the cache count too. Twenty panes that each fetch every 15 seconds make 80 calls a minute, which is over the limit, so give each pane the longest interval it can live with.