Scheduled

Primitives for creating scheduled — throttled or debounced — callbacks.

• debounce - Creates a callback that is debounced and cancellable.
• throttle - Creates a callback that is throttled and cancellable.
• scheduleIdle - Creates a callback throttled using window.requestIdleCallback().
• leading - Creates a scheduled and cancellable callback that will be called on leading edge.
• createScheduled - Creates a signal used for scheduling execution of solid computations by tracking.
• Scheduling explanation

#debounce

Creates a callback that is debounced and cancellable. The debounced callback is called on trailing edge.

The timeout will be automatically cleared on root dispose.

#How to use it

import { debounce } from "@solid-primitives/scheduled";

const trigger = debounce((message: string) => console.log(message), 250);
trigger("Hello!");
trigger.clear(); // clears a timeout in progress

#throttle

Creates a callback that is throttled and cancellable. The throttled callback is called on trailing edge.

The timeout will be automatically cleared on root dispose.

#How to use it

import { throttle } from "@solid-primitives/scheduled";

const trigger = throttle((message: string) => console.log(message), 250);
trigger("Hello!");
trigger.clear(); // clears a timeout in progress

#scheduleIdle

Creates a callback throttled using window.requestIdleCallback(). (MDN reference)

The throttled callback is called on trailing edge.

The timeout will be automatically cleared on root dispose.

Note: requestIdleCallback is not available in Safari. If it's not available, scheduleIdle will fallback to throttle with default timeout. (callbacks will be batched using setTimeout instead)

#How to use it

import { scheduleIdle } from "@solid-primitives/scheduled";

const trigger = scheduleIdle(
  (message: string) => console.log(message),
  // timeout passed to requestIdleCallback is a maximum timeout before the callback is called
  250,
);
trigger("Hello!");
trigger.clear(); // clears a timeout in progress

#leading

Creates a scheduled and cancellable callback that will be called on leading edge.

The timeout will be automatically cleared on root dispose.

#How to use it

// with debounce
import { leading, debounce } from "@solid-primitives/scheduled";

const trigger = leading(debounce, (message: string) => console.log(message), 250);
trigger("Hello!");
trigger.clear(); // clears a timeout in progress

// with throttle
import { leading, throttle } from "@solid-primitives/scheduled";

const trigger = leading(throttle, (message: string) => console.log(message), 250);
trigger("Hello!");
trigger.clear(); // clears a timeout in progress

#leadingAndTrailing

Creates a scheduled and cancellable callback that will be called on leading edge for the first call, and trailing edge thereafter.

The timeout will be automatically cleared on root dispose.

#How to use it

// with debounce
import { leadingAndTrailing, debounce } from "@solid-primitives/scheduled";

const trigger = leadingAndTrailing(debounce, (message: string) => console.log(message), 250);
trigger("Hello!");
trigger.clear(); // clears a timeout in progress

// with throttle
import { leadingAndTrailing, throttle } from "@solid-primitives/scheduled";

const trigger = leadingAndTrailing(throttle, (message: string) => console.log(message), 250);
trigger("Hello!");
trigger.clear(); // clears a timeout in progress

#createScheduled

Creates a signal used for scheduling execution of solid computations by tracking.

#How to use it

createScheduled takes only one parameter - a schedule function. This function is called with a callback that should be scheduled. It should return a function for triggering the timeout.

// e.g. with debounce
createScheduled(fn => debounce(fn, 1000));
// e.g. with throttle
createScheduled(fn => throttle(fn, 1000));
// e.g. with leading debounce
createScheduled(fn => leading(debounce, fn, 1000));
// e.g. with leading throttle
createScheduled(fn => leading(throttle, fn, 1000));

It returns a signal that can be used to schedule execution of a solid computation. The signal returns true if it's dirty (callback should be called) and false otherwise.

import { createScheduled, debounce } from "@solid-primitives/scheduled";

const scheduled = createScheduled(fn => debounce(fn, 1000));

const [count, setCount] = createSignal(0);

createEffect(() => {
  // track source signal
  const value = count();
  // track the debounced signal and check if it's dirty
  if (scheduled()) {
    console.log("count", value);
  }
});

// or with createMemo
const debouncedCount = createMemo((p: number = 0) => {
  // track source signal
  const value = count();
  // track the debounced signal and check if it's dirty
  return scheduled() ? value : p;
});

#Scheduling explanation

This package provides 4 different methods for scheduling a callback. Pick one that suits your application.

TOP: scheduled function triggered
BOTTOM: called user callback

1. debounce
2. throttle
3. leading debounce
4. leading throttle
5. leadingAndTrailing debounce
6. leadingAndTrailing throttle

   █   █     █
------------------------>
1.                  █
2.        █         █
3. █
4. █         █
5. █                █
6. █      █         █

Interactive DEMO of the schematic above

#Changelog

See CHANGELOG.md