@aegisjsproject/tempo

Tempo provides advanced debouncing and throttling utilities for fine-grained execution control.

---

• Code of Conduct
• Contributing

@aegisjsproject/tempo

A lightweight JavaScript library for debouncing and throttling functions using modern, native web APIs.

---

Overview

@aegisjsproject/tempo provides robust debouncing and throttling utilities by leveraging the browser's latest scheduling and locking APIs. Using methods like scheduler.postTask and navigator.locks.request, the library offers precise task scheduling with native priority support, efficient cancellation via AbortSignals, and streamlined resource management.

---

Features

• Debounce Function
  Debounces a callback function by scheduling it with scheduler.postTask. It supports custom delays, task priorities (user-blocking, user-visible, background), and cancellation through AbortSignals.

• Throttle Function
  Throttles a callback by combining scheduler.postTask with navigator.locks.request for controlled, queued execution. It provides options for lock naming, immediate failure or lock stealing, and built-in delay management.

---

Advantages of Modern Methods

• Native Integration:
  Leverages browser-native APIs for task scheduling and lock management, reducing dependency overhead and resulting in smaller bundle sizes.

• Improved Performance:
  Native scheduling with scheduler.postTask allows tasks to be queued based on system and user priorities, leading to smoother and more responsive applications.

• Enhanced Control:
  With built-in support for AbortSignals and fine-grained control over task priorities, developers can efficiently manage resource-intensive operations.

• Optimized Concurrency:
  The use of navigator.locks.request ensures that throttled tasks handle concurrent execution gracefully without resorting to heavy third-party libraries.

---

Installation

Install the package via npm:

npm install @aegisjsproject/tempo

---

Usage

Import the desired functions into your project:

import { debounce, throttle } from '@aegisjsproject/tempo';

Usage with a CDN and <script type="importmap">

<script type="importmap">
  {
    "imports": {
      "@aegisjsproject/tempo": "https://unpkg.com/@aegisjsproject[:version]/tempo.js"
    }
  }
</script>

Debounce Example

const debouncedAction = debounce(() => {
  // Your callback code here.
}, {
  delay: 300,
  priority: 'user-visible',
  signal: myAbortSignal, // Optional: provide an AbortSignal for cancellation.
});

Throttle Example

const throttledAction = throttle(() => {
  // Your callback code here.
}, {
  lockName: 'uniqueLockName', // Optional: defaults to a random UUID.
  delay: 200,
  priority: 'background',
  ifAvailable: true, // Immediately fail if the lock is unavailable.
  signal: myAbortSignal, // Optional: provide an AbortSignal for cancellation.
});

---

API Documentation

debounce(callback, options)

• Parameters:

  • callback (Function): The function to debounce.
  • options (Object, optional):
    • delay (number): The debounce delay in milliseconds.
    • priority ("user-blocking" | "user-visible" | "background"): The task priority.
    • signal (AbortSignal): Signal to cancel the debounced call.
    • thisArg (any, default: null): The this context for the callback.

• Returns:
  A debounced version of the input function.

• Throws:

  • TypeError if the callback is not a function.
  • Error if the provided AbortSignal is already aborted.

throttle(callback, options)

• Parameters:

  • callback (Function): The function to throttle.
  • options (Object, optional):
    • lockName (string, default: crypto.randomUUID()): Name for the lock.
    • delay (number): Delay in milliseconds after task execution.
    • priority ("user-blocking" | "user-visible" | "background"): The task priority.
    • ifAvailable (boolean, default: true): Fail immediately if the lock is not available.
    • steal (boolean, default: false): Allow stealing of the lock.
    • mode ("shared" | "exclusive", default: "exclusive"): The lock mode (only 'exclusive' is supported).
    • thisArg (any, default: null): The this context for the callback.
    • signal (AbortSignal): Signal to cancel the throttled call.

• Returns:
  A throttled version of the input function.

• Throws:

  • TypeError if the callback is not a function or if both steal and ifAvailable are set to true.
  • Error if the provided AbortSignal is already aborted.