https://github.com/aegisjsproject/tempo
Tempo provides advanced debouncing and throttling utilities for fine-grained execution control.
https://github.com/aegisjsproject/tempo
Last synced: about 1 year ago
JSON representation
Tempo provides advanced debouncing and throttling utilities for fine-grained execution control.
- Host: GitHub
- URL: https://github.com/aegisjsproject/tempo
- Owner: AegisJSProject
- License: mit
- Created: 2025-03-17T16:00:30.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-17T16:23:51.000Z (about 1 year ago)
- Last Synced: 2025-04-18T06:55:35.049Z (about 1 year ago)
- Language: JavaScript
- Homepage: https://npmjs.com/package/@aegisjsproject/tempo
- Size: 196 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# @aegisjsproject/tempo
Tempo provides advanced debouncing and throttling utilities for fine-grained execution control.
[](https://github.com/AegisJSProject/tempo/actions/workflows/codeql-analysis.yml)
[](https://github.com/AegisJSProject/tempo/blob/master/LICENSE)
[](https://github.com/AegisJSProject/tempo/commits/master)
[](https://github.com/AegisJSProject/tempo/releases)
[](https://github.com/sponsors/shgysk8zer0)
[](https://www.npmjs.com/package/@aegisjsproject/tempo)
[](https://www.npmjs.com/package/@aegisjsproject/tempo)
[](https://github.com/AegisJSProject)
[](https://twitter.com/shgysk8zer0)
[](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
- - -
- [Code of Conduct](./.github/CODE_OF_CONDUCT.md)
- [Contributing](./.github/CONTRIBUTING.md)
# @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:
```bash
npm install @aegisjsproject/tempo
```
---
## Usage
Import the desired functions into your project:
```js
import { debounce, throttle } from '@aegisjsproject/tempo';
```
### Usage with a CDN and ``
```html
<script type="importmap">
{
"imports": {
"@aegisjsproject/tempo": "https://unpkg.com/@aegisjsproject[:version]/tempo.js"
}
}
```
### Debounce Example
```js
const debouncedAction = debounce(() => {
// Your callback code here.
}, {
delay: 300,
priority: 'user-visible',
signal: myAbortSignal, // Optional: provide an AbortSignal for cancellation.
});
```
### Throttle Example
```js
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.