README.md

DOM Render Scheduler

Schedules rendering of DOM updates called render shots.

Usage

import { newRenderSchedule } from '@frontmeans/render-scheduler';

// First, create a rendering schedule
const btnSchedule = newRenderSchedule();

// Schedule render shot
btnSchedule(() => (document.getElementById('button').disabled = false));

// Schedule another render shot
// Only the latest render shot within one schedule will be executed
btnSchedule(() => (document.getElementById('button').disabled = true));

// Each schedule schedules its render shots independently from others.
// Yet render shots from all schedules for the same window are executed in the same animation frame.
const popupSchedule = newRenderSchedule();

popupSchedule(execution => {
  const popup = document.getElementById('popup');

  popup.classList.remove('hidden');

  execution.postpone(() => {
    // Postponed render shot is executed after the rest of them.
    // This is useful when it needs to synchronously request a page reflow,
    // e.g. by requesting of geometry of just updated DOM element.

    const shadow = document.getElementById('popup-shadow');
    const { clientWidth, clientHeight } = popup;

    shadow.classList.remove('hidden');
    shadow.style.width = clientWidth;
    shadow.style.height = clientHeight;
  });
});

Scheduler Implementations

By default, a scheduler executes render shots within animation frame. It utilizes requestAnimationFrame() of current window for that. This implementation is called animationRenderScheduler. It helps limit the rate of DOM manipulations caused by too frequent updates, as only the latest render shot in the same schedule is executed.

There is a few more implementations:

• asyncRenderScheduler - executes render shots asynchronously,
• immediateRenderScheduler - executes render shots immediately,
• ManualRenderScheduler - executes render shots on request,
• noopRenderScheduler - neither schedules, nor executes render shots,
• queuedRenderScheduler - schedules render shots for immediate execution.

Render schedulers can be used directly, or set globally with setRenderScheduler() function. In the latter case the newRenderSchedule() function would use that scheduler.

Custom scheduler may also be created using customRenderScheduler() function.

Schedule Options

When constructing a new schedule additional options may be specified:

• window - A window for constructed schedule. animationRenderScheduler executes render shots for all schedules created for the same window simultaneously, in the same animation frame. Other implementations ignore this option. Defaults to the window of the node, or to the current one.
• node - A DOM node for constructed schedule. Used to detect missing window option.
• error(...messages: any[]) - a method that will be called when some error occurred. E.g. when render shot execution failed. Defaults to console.error().