Merge pull request #1 from AegisJSProject/patch/initial-release

Initial Release

Author: shgysk8zer0

.github/workflows/super-linter.yml

@@ -93,7 +93,7 @@ jobs:
           # VALIDATE_JAVASCRIPT_STANDARD: true
           # VALIDATE_JSON: true
           # VALIDATE_XML: true
-          VALIDATE_MARKDOWN: true
+          # VALIDATE_MARKDOWN: true
           VALIDATE_YAML: true
           # VALIDATE_TYPESCRIPT_ES: true
           # VALIDATE_TYPESCRIPT_STANDARD: true

.npmignore

@@ -17,3 +17,4 @@ importmap.yaml
 *.bak
 *.env
 !*.map
+locks.js

CHANGELOG.md

@@ -7,76 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Changed
-- Update node version via `.npmrc`
-- Update Node CI workflow
-- Install & use `@shgysk8zer0/eslint-config`
-- Add support for `node --test`, including ignoring tests for publishing
-- Update ESLint & super-linter
-- Switch to more basic Rollup config
-- Update `exports` and `main` accordingly
-
-### Fixed
-- Fix missed renaming in README
-
-## Removed
-- Remove old ESLint config files
-
-## [v1.1.1] - 2023-09-24
-
-### Added
-- Add `unpkg` to `package.json`
-- Add badges in README
-
-### Changed
-- Update `exports` to `package.json` to handle wider variety
-
-### Fixed
-- Fix typo in `fix:js` script
-
-### [v1.1.0] - 2023-07-03
-
-### Changed
-- Update to node 20
-- Update npm publishing GH Action
-
-## [v1.0.5] - 2023-07-02
-
-### Added
-- Add `funding`
-
-### Changed
-- Updated GitHub Actions workflows 
-- Update versioning & lock-file scripts
-- Update `.npmignore` & `.gitignore`
-
-## [v1.0.4] - 2023-06-08
-
-### Added
-- Install `@shgysk8zer0/npm-utils`
-- Add `exports` to package config
-
-### Removed
-- Uninstall `rollup`, `eslint`
-
-### Changed
-- Use `getConfig()` from `@shgysk8zer0/js-utils/rollup` for rollup config
-
-## [v1.0.3] - 2023-06-01
-
-### Fixed
-- Revert to old Release Action, now with permissions & link to changelog
-
-## [v1.0.2] - 2023-06-01
-
-### Fixed
-- Fix `changelog-entry` to match `[$version]` instead of `$version`
-
-## [v1.0.1] - 2023-05-31
-
-### Fixed
-- Update GitHub Release workflow to use [Auto Release](https://github.com/marketplace/actions/auto-release)
-
-## [v1.0.0] - 2023-05-31
+## [v1.0.0] - 2025-03-18
 
 Initial Release

README.md

@@ -1,24 +1,24 @@
-# npm-template
+# @aegisjsproject/tempo
 
-A template repo for npm packages
+Tempo provides advanced debouncing and throttling utilities for fine-grained execution control.
 
-[![CodeQL](https://github.com/shgysk8zer0/npm-template/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/shgysk8zer0/npm-template/actions/workflows/codeql-analysis.yml)
-![Node CI](https://github.com/shgysk8zer0/npm-template/workflows/Node%20CI/badge.svg)
-![Lint Code Base](https://github.com/shgysk8zer0/npm-template/workflows/Lint%20Code%20Base/badge.svg)
+[![CodeQL](https://github.com/AegisJSProject/tempo/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/AegisJSProject/tempo/actions/workflows/codeql-analysis.yml)
+![Node CI](https://github.com/AegisJSProject/tempo/workflows/Node%20CI/badge.svg)
+![Lint Code Base](https://github.com/AegisJSProject/tempo/workflows/Lint%20Code%20Base/badge.svg)
 
-[![GitHub license](https://img.shields.io/github/license/shgysk8zer0/npm-template.svg)](https://github.com/shgysk8zer0/npm-template/blob/master/LICENSE)
-[![GitHub last commit](https://img.shields.io/github/last-commit/shgysk8zer0/npm-template.svg)](https://github.com/shgysk8zer0/npm-template/commits/master)
-[![GitHub release](https://img.shields.io/github/release/shgysk8zer0/npm-template?logo=github)](https://github.com/shgysk8zer0/npm-template/releases)
+[![GitHub license](https://img.shields.io/github/license/AegisJSProject/tempo.svg)](https://github.com/AegisJSProject/tempo/blob/master/LICENSE)
+[![GitHub last commit](https://img.shields.io/github/last-commit/AegisJSProject/tempo.svg)](https://github.com/AegisJSProject/tempo/commits/master)
+[![GitHub release](https://img.shields.io/github/release/AegisJSProject/tempo?logo=github)](https://github.com/AegisJSProject/tempo/releases)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/shgysk8zer0?logo=github)](https://github.com/sponsors/shgysk8zer0)
 
-[![npm](https://img.shields.io/npm/v/@shgysk8zer0/npm-template)](https://www.npmjs.com/package/@shgysk8zer0/npm-template)
-![node-current](https://img.shields.io/node/v/@shgysk8zer0/npm-template)
-![npm bundle size gzipped](https://img.shields.io/bundlephobia/minzip/@shgysk8zer0/npm-template)
-[![npm](https://img.shields.io/npm/dw/@shgysk8zer0/npm-template?logo=npm)](https://www.npmjs.com/package/@shgysk8zer0/npm-template)
+[![npm](https://img.shields.io/npm/v/@aegisjsproject/tempo)](https://www.npmjs.com/package/@aegisjsproject/tempo)
+![node-current](https://img.shields.io/node/v/@aegisjsproject/tempo)
+![npm bundle size gzipped](https://img.shields.io/bundlephobia/minzip/@aegisjsproject/tempo)
+[![npm](https://img.shields.io/npm/dw/@aegisjsproject/tempo?logo=npm)](https://www.npmjs.com/package/@aegisjsproject/tempo)
 
-[![GitHub followers](https://img.shields.io/github/followers/shgysk8zer0.svg?style=social)](https://github.com/shgysk8zer0)
-![GitHub forks](https://img.shields.io/github/forks/shgysk8zer0/npm-template.svg?style=social)
-![GitHub stars](https://img.shields.io/github/stars/shgysk8zer0/npm-template.svg?style=social)
+[![GitHub followers](https://img.shields.io/github/followers/AegisJSProject.svg?style=social)](https://github.com/AegisJSProject)
+![GitHub forks](https://img.shields.io/github/forks/AegisJSProject/tempo.svg?style=social)
+![GitHub stars](https://img.shields.io/github/stars/AegisJSProject/tempo.svg?style=social)
 [![Twitter Follow](https://img.shields.io/twitter/follow/shgysk8zer0.svg?style=social)](https://twitter.com/shgysk8zer0)
 
 [![Donate using Liberapay](https://img.shields.io/liberapay/receives/shgysk8zer0.svg?logo=liberapay)](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
@@ -27,3 +27,138 @@ A template repo for npm packages
 - [Code of Conduct](./.github/CODE_OF_CONDUCT.md)
 - [Contributing](./.github/CONTRIBUTING.md)
 <!-- - [Security Policy](./.github/SECURITY.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 `<script type="importmap">`
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@aegisjsproject/tempo": "https://unpkg.com/@aegisjsproject[:version]/tempo.js"
+    }
+  }
+</script>
+```
+### 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.

consts.js

@@ -1,3 +1,3 @@
-import { node } from '@shgysk8zer0/eslint-config';
+import { browser } from '@shgysk8zer0/eslint-config';
 
-export default node({ files: ['**/*.js'], ignores: ['**/*.min.js', '**/*.cjs', '**/*.mjs'] });
+export default browser({ files: ['**/*.js'], ignores: ['**/*.min.js', '**/*.cjs', '**/*.mjs'] });

eslint.config.js

@@ -0,0 +1,96 @@
+import '@shgysk8zer0/polyfills';
+
+const locks = Object.freeze({
+	shared: new Map(),
+	exclusive: new Map(),
+});
+
+globalThis.Lock = class Lock {
+	#mode;
+	#name;
+
+	constructor(name, mode) {
+		this.#name = name;
+		this.#mode = mode;
+	}
+
+	get name() {
+		return this.#name;
+	}
+
+	get mode() {
+		return this.#mode;
+	}
+};
+
+globalThis.navigator = {
+	locks: {
+		query() {
+			return Object.freeze({
+				shared: Array.from(locks.shared.values()),
+				exclusive: Array.from(locks.exclusive.values()),
+			});
+		},
+		async request(name, {
+			delay = 0,
+			mode = 'exclusive',
+			signal,
+		}, callback) {
+			if (! (mode in locks)) {
+				throw new TypeError(`Invalid lock mode "${mode}".`);
+			} else if (signal instanceof AbortSignal && signal.aborted) {
+				throw signal.reason;
+			} else if (! locks[mode].has(name)) {
+				const lock = new Lock(name, mode);
+				const controller = new AbortController();
+				const { resolve, reject, promise } = Promise.withResolvers();
+				controller.signal.addEventListener('abort', ({ target }) => reject(target.reason), { once: true });
+				locks[mode].set(name, lock);
+
+				try {
+					let timeout = NaN;
+
+					const wait = typeof delay === 'number' ? new Promise(resolve => {
+						timeout = setTimeout(resolve, delay);
+					}) : Promise.resolve();
+
+					if (signal instanceof AbortSignal) {
+						signal.addEventListener('abort', ({ target }) => {
+							controller.abort(target.reason);
+
+							if (! Number.isNaN(timeout)) {
+								clearTimeout(timeout);
+							}
+						});
+					}
+
+					await Promise.race([wait, promise]).then(() => {
+						locks[mode].get(name) === lock
+							? Promise.try(() => callback(lock)).then(resolve, reject)
+							: Promise.try(callback).then(resolve, reject);
+					}).catch(err => reject(err));
+
+				} catch(err) {
+					reject(err);
+				} finally {
+					/* eslint no-unsafe-finally: off */
+					const [result, err] = await promise.then(result => [result, null]).catch(err => [null, err]);
+
+					if (locks[mode].get(name) === lock) {
+						locks[mode].delete(name);
+					}
+
+					if (! controller.signal.aborted) {
+						controller.abort(err);
+					}
+
+					if (err instanceof Error) {
+						throw err;
+					} else {
+						return result;
+					}
+				}
+			}
+		}
+	}
+};