terkelg / workshy

A small (376B) lazy function scheduler for a butter smooth main thread.

workshy

A small (376B) lazy function scheduler for a butter smooth main thread

Workshy is a throttle utility that rate limit, queue, and distribute function executions over time to prevent the main thread from becoming unresponsive.

Unlike a standard throttle function, and to ensure non-blocking rendering and responsive UIs, workshy break up functions into smaller chunks executed over time if necessary.

This module is available in three formats:

• ES Module: dist/workshy.mjs
• CommonJS: dist/workshy.js
• UMD: dist/workshy.min.js

Install

$ npm install --save workshy

The script can also be directly included from unpkg.com:

<script src="https://unpkg.com/workshy"></script>

Usage

import workshy from 'workshy';

// dummy function doing heavy work
const greet = () => 'hello world';

// queue and call function
workshy(greet)();
// => 'hello world'

// tasks are only called once, but
// multiple calls increases priority
const a = workshy(x => console.log(`A: ${x}`));
const b = workshy(x => console.log(`B: ${x}`));
b(1);
a(1);
a(2);
// => A: 2
// => B: 1

// manually define priority
const func = workshy(greet, {priority: 2});

// force it to be called immediately
const func = workshy(greet, {force: true});

// workshy distribute the work over time to
// make sure the main thread runs butter smooth
for (let i = 0; i < 5000; i++) {
  workshy(greet)(); // => this won't block UI
}

API

workshy(task, [options])

Returns: function

task

Type: function

Accepts any function a returns a function (a function that wraps your original function). Call returned function to queue task.

The returned function will execute your function with the latest arguments provided to it as soon as possible based on queue length and prioroty.

Important: Task are only called once.
Calling the same task multiple times increases its priority.

options.priority

Type: Number
Default: 0

Tasks are sorted by priority. Functions with high priority are called first.

Important: Priority also increase if a task is called multiple times.

workshy(() => console.log('Hello World'), {force: false, priority: 2});
//=> 'Hello World'

options.force

Type: Boolean
Default: false

workshy(() => console.log('Hello World'), {force: false, priority: 2});
//=> 'Hello World'

Inspiration

This is inspired by the talk The Virtue of Laziness: Leveraging Incrementality for Faster Web UI

License

MIT © Terkel Gjervig

workshy's Issues

requestIdleCallback is undefined and raises issues on Safari

Heyo,

Thanks for the cool library, really interesting 👍!

In the current implementation requestIdleCallback is presumably falling back to the browser global window but it fails to do so in Safari.

workshy/src/index.js

Line 1 in 4c27557

const onIdle = requestIdleCallback || function (handler) {

I've experienced this issue before when doing feature detection checks and fixed it by explicitly setting it to window.requestIdleCallback.