@line-8/chauffeur v1.0.7

Chauffeur 🧑‍✈️

All-in-one frame scheduler

• 🎨 Eliminiates layout trashing
  Avoid unnecessary reflows by segregating DOM access to dramatically improve layout performance.
• ✋ Provides throttling
  Limit the rate at which a function is called by restricting it to a single execution per frame.
• ⏰ Supports timers
  Defer the execution of a task to the nearest frame after a specified delay has elapsed.

...now with 20% less sodium!

Installation

• Node.js
  Install the chauffeur package from npm

  npm i chauffeur@npm:@line-8/chauffeur

• UMD
  Load the chauffeur module from a CDN

  https://cdn.jsdelivr.net/npm/@line-8/chauffeur/lib/index.min.js

Usage

Chauffeur divides each frame into three discrete steps for performing specific actions:

1. Read
   Taking measurments, reading styles
2. Update
   Modifying state, performing calculations
3. Write
   Mutating elements, applying styles, rendering to canvases

Each task carried out with Chauffeur must be assigned to one of these three steps.

import { defer, schedule, throttle } from "chauffeur";

// Execute a task in the reading phase of the next frame
let job = schedule.read(() => {}, true);

// Cancel the previously scheduled task
job.cancel();

// Execute a task in the rendering phase of the nearest frame after a delay of 1 second
defer.render(() => {}, 1000);

// Limit a function to a single execution within the updating phase of a frame
let throttled = throttle.update(() => {});

API

Note: All time values are expressed in milliseconds. Their precision depends on the current environment, but typically lies within a few microseconds.

Warning: Timestamps are, in most cases, relative to the current environment, not the Unix epoch, and thus should never be used for date manipulation.

Functions

schedule

Parameters:
  task: Function
  keep?: boolean
  immediate?: boolean

Returns: Job

Creates a new job for the specified task, which will be processed on the given step of the next frame. To process the job on the current frame immediate can be set to true.

When the job is processed, the task function is invoked with a single argument containing the following data about the current frame:

• time
  The timestamp of the current frame, measured in milliseconds.
• delta
  The time difference between the current frame and the last frame, measured in milliseconds.

By default, a job is executed exactly once. To create a continuous job that is processed on each subsequent frame until actively canceled, keep can be set to true.

defer

Parameters:
  task: Function
  delay: number
  keep?: boolean

Returns: Job

Creates a new job for the specified task, which will be processed on the given step of the nearest frame after the specified delay has elapsed.

When the job is processed, the task function is invoked with a single argument containing the following data about the current frame:

• time
  The timestamp of the current frame, measured in milliseconds.
• elapsed
  The actual delay elapsed until the job was processed, measured in milliseconds.

By default, a job is executed exactly once. To create a continuous job that is processed on each subsequent frame until actively canceled, keep can be set to true. In this case, a consistent time interval is maintained.

throttle

Wraps the specified function, limiting it to a single execution within the given step per frame, using the latest arguments it was called with.

Parameters:
  fn: Function

Returns: Throttled

Structures

Job

It has the following methods:

• cancel

  Parameters: ✗
  Returns: boolean

  Immediately cancels the job by removing it from the step it is assigned to preventing all further executions. Subsequent method calls will have no effect.

  The return value indicates whether the state of the job was affected by the method call.

Throttled

It has the following methods:

• cancel

  Parameters: ✗
  Returns: boolean

  Immediately cancels all planned executions of the function. Subsequent executions, however, are still possible.

  The return value indicates whether the state of the function was affected by the method call.