@oscarpalmer/atoms 0.169.0 → 0.171.0

package/dist/function/index.d.mts

@@ -1,23 +1,3 @@
-import { CancelableCallback, GenericCallback } from "../models.mjs";
 import { noop } from "../internal/function/misc.mjs";
 import { Memoized, MemoizedOptions, memoize } from "./memoize.mjs";
-
-//#region src/function/index.d.ts
-/**
- * Debounce a function, ensuring it is only called after `time` milliseconds have passed
- *
- * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
- * @param callback Callback to debounce
- * @param time Time in milliseconds to wait before calling the callback _(defaults to match frame rate)_
- * @returns Debounced callback with a `cancel` method
- */
-declare function debounce<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
-/**
- * Throttle a function, ensuring it is only called once every `time` milliseconds
- * @param callback Callback to throttle
- * @param time Time in milliseconds to wait before calling the callback again _(defaults to match frame rate)_
- * @returns Throttled callback with a `cancel` method
- */
-declare function throttle<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
-//#endregion
-export { type Memoized, type MemoizedOptions, debounce, memoize, noop, throttle };
+export { type Memoized, type MemoizedOptions, memoize, noop };

package/dist/function/index.mjs

@@ -1,26 +1,3 @@
 import { noop } from "../internal/function/misc.mjs";
-import { TIMER_DEBOUNCE, TIMER_THROTTLE, getTimer } from "../internal/function/timer.mjs";
 import { memoize } from "./memoize.mjs";
-//#region src/function/index.ts
-/**
-* Debounce a function, ensuring it is only called after `time` milliseconds have passed
-*
-* On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
-* @param callback Callback to debounce
-* @param time Time in milliseconds to wait before calling the callback _(defaults to match frame rate)_
-* @returns Debounced callback with a `cancel` method
-*/
-function debounce(callback, time) {
-	return getTimer(TIMER_DEBOUNCE, callback, time);
-}
-/**
-* Throttle a function, ensuring it is only called once every `time` milliseconds
-* @param callback Callback to throttle
-* @param time Time in milliseconds to wait before calling the callback again _(defaults to match frame rate)_
-* @returns Throttled callback with a `cancel` method
-*/
-function throttle(callback, time) {
-	return getTimer(TIMER_THROTTLE, callback, time);
-}
-//#endregion
-export { debounce, memoize, noop, throttle };
+export { memoize, noop };

package/dist/function/limit.d.mts

@@ -0,0 +1,49 @@
+import { AsyncCancelableCallback, CancelableCallback, GenericAsyncCallback, GenericCallback } from "../models.mjs";
+
+//#region src/function/limit.d.ts
+/**
+ * Debounce a function, ensuring it is only called after `time` milliseconds have passed
+ *
+ * When called, successful _(finished)_ results will resolve and errors will reject.
+ *
+ * On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
+ * @param callback Callback to debounce
+ * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Debounced callback handler with a `cancel` method
+ */
+declare function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncCancelableCallback<Callback>;
+/**
+ * Throttle a function, ensuring it is only called once every `time` milliseconds
+ *
+ * When called, successful _(finished)_ results will resolve and errors will reject.
+ *
+ * On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
+ * @param callback Callback to throttle
+ * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Throttled callback handler with a `cancel` method
+ */
+declare function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncCancelableCallback<Callback>;
+/**
+ * Debounce a function, ensuring it is only called after `time` milliseconds have passed
+ *
+ * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
+ * @param callback Callback to debounce
+ * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Debounced callback handler with a `cancel` method
+ */
+declare function debounce<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
+declare namespace debounce {
+  var async: typeof asyncDebounce;
+}
+/**
+ * Throttle a function, ensuring it is only called once every `time` milliseconds
+ * @param callback Callback to throttle
+ * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Throttled callback handler with a `cancel` method
+ */
+declare function throttle<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
+declare namespace throttle {
+  var async: typeof asyncThrottle;
+}
+//#endregion
+export { debounce, throttle };

package/dist/function/limit.mjs

@@ -0,0 +1,52 @@
+import { TIMER_DEBOUNCE, TIMER_THROTTLE, getAsyncTimer, getTimer } from "../internal/function/timer.mjs";
+//#region src/function/limit.ts
+/**
+* Debounce a function, ensuring it is only called after `time` milliseconds have passed
+*
+* When called, successful _(finished)_ results will resolve and errors will reject.
+*
+* On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
+* @param callback Callback to debounce
+* @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+* @returns Debounced callback handler with a `cancel` method
+*/
+function asyncDebounce(callback, time) {
+	return getAsyncTimer(TIMER_DEBOUNCE, callback, time);
+}
+/**
+* Throttle a function, ensuring it is only called once every `time` milliseconds
+*
+* When called, successful _(finished)_ results will resolve and errors will reject.
+*
+* On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
+* @param callback Callback to throttle
+* @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+* @returns Throttled callback handler with a `cancel` method
+*/
+function asyncThrottle(callback, time) {
+	return getAsyncTimer(TIMER_THROTTLE, callback, time);
+}
+/**
+* Debounce a function, ensuring it is only called after `time` milliseconds have passed
+*
+* On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
+* @param callback Callback to debounce
+* @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+* @returns Debounced callback handler with a `cancel` method
+*/
+function debounce(callback, time) {
+	return getTimer(TIMER_DEBOUNCE, callback, time);
+}
+debounce.async = asyncDebounce;
+/**
+* Throttle a function, ensuring it is only called once every `time` milliseconds
+* @param callback Callback to throttle
+* @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+* @returns Throttled callback handler with a `cancel` method
+*/
+function throttle(callback, time) {
+	return getTimer(TIMER_THROTTLE, callback, time);
+}
+throttle.async = asyncThrottle;
+//#endregion
+export { debounce, throttle };

package/dist/index.d.mts

@@ -3,6 +3,15 @@
  * A generic array or object
  */
 type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
+/**
+ * An asynchronous callback that can be canceled
+ */
+type AsyncCancelableCallback<Callback extends GenericAsyncCallback | GenericCallback> = (ReturnType<Callback> extends Promise<any> ? (...args: Parameters<Callback>) => Promise<Awaited<ReturnType<Callback>>> : (...args: Parameters<Callback>) => Promise<ReturnType<Callback>>) & {
+  /**
+   * Cancel the callback
+   */
+  cancel: () => void;
+};
 /**
  * For mathicng any `void`, `Date`, primitive, or `RegExp` values
  *
@@ -10,7 +19,7 @@ type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
  */
 type BuiltIns = void | Date | Primitive | RegExp;
 /**
- * An extend callback that can be canceled
+ * A synchronous callback that can be canceled
  */
 type CancelableCallback<Callback extends GenericCallback> = Callback & {
   /**
@@ -1636,23 +1645,51 @@ type Options = {
  */
 declare function memoize<Callback extends GenericCallback>(callback: Callback, options?: MemoizedOptions<Callback>): Memoized<Callback>;
 //#endregion
-//#region src/function/index.d.ts
+//#region src/function/limit.d.ts
+/**
+ * Debounce a function, ensuring it is only called after `time` milliseconds have passed
+ *
+ * When called, successful _(finished)_ results will resolve and errors will reject.
+ *
+ * On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
+ * @param callback Callback to debounce
+ * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Debounced callback handler with a `cancel` method
+ */
+declare function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncCancelableCallback<Callback>;
+/**
+ * Throttle a function, ensuring it is only called once every `time` milliseconds
+ *
+ * When called, successful _(finished)_ results will resolve and errors will reject.
+ *
+ * On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
+ * @param callback Callback to throttle
+ * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Throttled callback handler with a `cancel` method
+ */
+declare function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(callback: Callback, time?: number): AsyncCancelableCallback<Callback>;
 /**
  * Debounce a function, ensuring it is only called after `time` milliseconds have passed
  *
  * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
  * @param callback Callback to debounce
- * @param time Time in milliseconds to wait before calling the callback _(defaults to match frame rate)_
- * @returns Debounced callback with a `cancel` method
+ * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Debounced callback handler with a `cancel` method
  */
 declare function debounce<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
+declare namespace debounce {
+  var async: typeof asyncDebounce;
+}
 /**
  * Throttle a function, ensuring it is only called once every `time` milliseconds
  * @param callback Callback to throttle
- * @param time Time in milliseconds to wait before calling the callback again _(defaults to match frame rate)_
- * @returns Throttled callback with a `cancel` method
+ * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Throttled callback handler with a `cancel` method
  */
 declare function throttle<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
+declare namespace throttle {
+  var async: typeof asyncThrottle;
+}
 //#endregion
 //#region src/function/once.d.ts
 /**
@@ -4351,4 +4388,4 @@ declare class SizedSet<Value = unknown> extends Set<Value> {
   get(value: Value, update?: boolean): Value | undefined;
 }
 //#endregion
-export { AnyResult, ArrayComparisonSorter, ArrayKeySorter, ArrayOrPlainObject, ArrayPosition, ArrayValueSorter, Asserter, AttemptFlow, AttemptFlowPromise, type Beacon, type BeaconOptions, BuiltIns, CancelableCallback, CancelablePromise, type Color, Constructor, DiffOptions, DiffResult, DiffValue, EqualOptions, Err, EventPosition, ExtendedErr, ExtendedResult, Flow, FlowPromise, FulfilledPromise, GenericAsyncCallback, GenericCallback, type HSLAColor, type HSLColor, HasValue, Key, KeyedValue, type Logger, type Memoized, type MemoizedOptions, MergeOptions, Merger, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, type Observable, type Observer, Ok, OnceAsyncCallback, OnceCallback, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PlainObject, Primitive, PromiseData, PromiseHandlers, PromiseOptions, PromiseParameters, PromiseStrategy, PromiseTimeoutError, PromisesItems, PromisesOptions, PromisesResult, PromisesUnwrapped, PromisesValue, PromisesValues, type Queue, QueueError, type QueueOptions, type Queued, type RGBAColor, type RGBColor, RejectedPromise, RequiredKeys, Result, ResultMatch, RetryError, RetryOptions, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, Simplify, SizedMap, SizedSet, Smushed, SortDirection, Sorter, type Subscription, TemplateOptions, type Time, ToString, TypedArray, Unsmushed, UnwrapValue, assert, attempt, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getTimedPromise, getUuid, getValue, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { AnyResult, ArrayComparisonSorter, ArrayKeySorter, ArrayOrPlainObject, ArrayPosition, ArrayValueSorter, Asserter, AsyncCancelableCallback, AttemptFlow, AttemptFlowPromise, type Beacon, type BeaconOptions, BuiltIns, CancelableCallback, CancelablePromise, type Color, Constructor, DiffOptions, DiffResult, DiffValue, EqualOptions, Err, EventPosition, ExtendedErr, ExtendedResult, Flow, FlowPromise, FulfilledPromise, GenericAsyncCallback, GenericCallback, type HSLAColor, type HSLColor, HasValue, Key, KeyedValue, type Logger, type Memoized, type MemoizedOptions, MergeOptions, Merger, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, type Observable, type Observer, Ok, OnceAsyncCallback, OnceCallback, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PlainObject, Primitive, PromiseData, PromiseHandlers, PromiseOptions, PromiseParameters, PromiseStrategy, PromiseTimeoutError, PromisesItems, PromisesOptions, PromisesResult, PromisesUnwrapped, PromisesValue, PromisesValues, type Queue, QueueError, type QueueOptions, type Queued, type RGBAColor, type RGBColor, RejectedPromise, RequiredKeys, Result, ResultMatch, RetryError, RetryOptions, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, Simplify, SizedMap, SizedSet, Smushed, SortDirection, Sorter, type Subscription, TemplateOptions, type Time, ToString, TypedArray, Unsmushed, UnwrapValue, assert, attempt, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getTimedPromise, getUuid, getValue, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/dist/index.mjs

@@ -1140,38 +1140,6 @@ function assertIs(condition, message, error) {
 }
 const MESSAGE_VALUE_DEFINED = "Expected value to be defined";
 //#endregion
-//#region src/internal/function/timer.ts
-function getInterval(value) {
-	return typeof value === "number" && value > 0 ? value : 0;
-}
-function getTimer(type, callback, time) {
-	const interval = getInterval(time);
-	function run(now) {
-		start ??= now;
-		if (interval === 0 || now - start >= interval - OFFSET) {
-			start = throttle ? now : void 0;
-			callback(...args);
-		} else frame = requestAnimationFrame(run);
-	}
-	const throttle = type === TIMER_THROTTLE;
-	let args;
-	let frame;
-	let start;
-	const timer = (...parameters) => {
-		timer.cancel();
-		args = parameters;
-		frame = requestAnimationFrame(run);
-	};
-	timer.cancel = () => {
-		cancelAnimationFrame(frame);
-	};
-	return timer;
-}
-const OFFSET = 5;
-const TIMER_DEBOUNCE = "debounce";
-const TIMER_THROTTLE = "throttle";
-const TIMER_WAIT = "wait";
-//#endregion
 //#region src/internal/function/misc.ts
 /**
 * A function that does nothing, which can be useful, I guess…
@@ -1399,27 +1367,137 @@ function memoize(callback, options) {
 const DEFAULT_CACHE_SIZE = 1024;
 const SEPARATOR = "_";
 //#endregion
-//#region src/function/index.ts
+//#region src/internal/function/timer.ts
+function getAsyncTimer(type, callback, time) {
+	async function run(item) {
+		const now = performance.now();
+		start ??= now;
+		if (interval === 0 || now - start >= interval - OFFSET) {
+			start = throttle ? now : void 0;
+			item.running = true;
+			try {
+				let result = callback(...item.parameters);
+				if (result instanceof Promise) result = await result;
+				item.resolve(result);
+			} catch (error) {
+				item.reject(error);
+			} finally {
+				item.running = false;
+			}
+		} else id = startTimer(() => run(item));
+	}
+	const interval = getInterval(time);
+	const throttle = type === TIMER_THROTTLE;
+	let id;
+	let last;
+	let start;
+	const timer = (...parameters) => {
+		timer.cancel();
+		const next = {
+			parameters,
+			running: false
+		};
+		next.promise = new Promise((resolve, reject) => {
+			next.reject = reject;
+			next.resolve = resolve;
+		});
+		last = next;
+		if (throttle) run(next);
+		else id = startTimer(() => run(next));
+		return next.promise;
+	};
+	timer.cancel = () => {
+		clearTimer(id);
+		if (last != null && !last.running) last.reject();
+	};
+	return timer;
+}
+function getInterval(value) {
+	return typeof value === "number" && value > 0 ? value : 0;
+}
+function getTimer(type, callback, time) {
+	function run() {
+		const now = performance.now();
+		start ??= now;
+		if (interval === 0 || now - start >= interval - OFFSET) {
+			start = throttle ? now : void 0;
+			callback(...args);
+		} else id = startTimer(run);
+	}
+	const interval = getInterval(time);
+	const throttle = type === TIMER_THROTTLE;
+	let args;
+	let id;
+	let start;
+	const timer = (...parameters) => {
+		timer.cancel();
+		args = parameters;
+		if (throttle) run();
+		else id = startTimer(run);
+	};
+	timer.cancel = () => {
+		clearTimer(id);
+	};
+	return timer;
+}
+const OFFSET = 5;
+const TIMER_DEBOUNCE = "debounce";
+const TIMER_THROTTLE = "throttle";
+const TIMER_WAIT = "wait";
+// istanbul ignore next
+const clearTimer = typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : clearTimeout;
+// istanbul ignore next
+const startTimer = typeof requestAnimationFrame === "function" ? requestAnimationFrame : setTimeout;
+//#endregion
+//#region src/function/limit.ts
+/**
+* Debounce a function, ensuring it is only called after `time` milliseconds have passed
+*
+* When called, successful _(finished)_ results will resolve and errors will reject.
+*
+* On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
+* @param callback Callback to debounce
+* @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+* @returns Debounced callback handler with a `cancel` method
+*/
+function asyncDebounce(callback, time) {
+	return getAsyncTimer(TIMER_DEBOUNCE, callback, time);
+}
+/**
+* Throttle a function, ensuring it is only called once every `time` milliseconds
+*
+* When called, successful _(finished)_ results will resolve and errors will reject.
+*
+* On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
+* @param callback Callback to throttle
+* @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+* @returns Throttled callback handler with a `cancel` method
+*/
+function asyncThrottle(callback, time) {
+	return getAsyncTimer(TIMER_THROTTLE, callback, time);
+}
 /**
 * Debounce a function, ensuring it is only called after `time` milliseconds have passed
 *
 * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
 * @param callback Callback to debounce
-* @param time Time in milliseconds to wait before calling the callback _(defaults to match frame rate)_
-* @returns Debounced callback with a `cancel` method
+* @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+* @returns Debounced callback handler with a `cancel` method
 */
 function debounce(callback, time) {
 	return getTimer(TIMER_DEBOUNCE, callback, time);
 }
+debounce.async = asyncDebounce;
 /**
 * Throttle a function, ensuring it is only called once every `time` milliseconds
 * @param callback Callback to throttle
-* @param time Time in milliseconds to wait before calling the callback again _(defaults to match frame rate)_
-* @returns Throttled callback with a `cancel` method
+* @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+* @returns Throttled callback handler with a `cancel` method
 */
 function throttle(callback, time) {
 	return getTimer(TIMER_THROTTLE, callback, time);
 }
+throttle.async = asyncThrottle;
 //#endregion
 //#region src/function/once.ts
 /**
@@ -2313,7 +2391,7 @@ function cloneValue(value, depth, references) {
 		case value instanceof Date: return new Date(value.getTime());
 		case value instanceof RegExp: return cloneRegularExpression(value, depth, references);
 		case value instanceof Map: return cloneMap(value, depth, references);
-		case value instanceof Node: return cloneNode(value, depth, references);
+		case typeof Node !== "undefined" && value instanceof Node: return cloneNode(value, depth, references);
 		case value instanceof Set: return cloneSet(value, depth, references);
 		case isArrayOrPlainObject(value): return clonePlainObject(value, depth, references);
 		case isTypedArray(value): return cloneTypedArray(value, depth, references);

package/dist/internal/function/timer.d.mts

@@ -1,10 +1,11 @@
-import { CancelableCallback, GenericCallback } from "../../models.mjs";
+import { AsyncCancelableCallback, CancelableCallback, GenericAsyncCallback, GenericCallback } from "../../models.mjs";
 
 //#region src/internal/function/timer.d.ts
 type TimerType = 'debounce' | 'throttle' | 'wait';
+declare function getAsyncTimer<Callback extends GenericAsyncCallback | GenericCallback>(type: TimerType, callback: Callback, time?: number): AsyncCancelableCallback<Callback>;
 declare function getTimer<Callback extends GenericCallback>(type: TimerType, callback: Callback, time?: number): CancelableCallback<Callback>;
 declare const TIMER_DEBOUNCE: TimerType;
 declare const TIMER_THROTTLE: TimerType;
 declare const TIMER_WAIT: TimerType;
 //#endregion
-export { TIMER_DEBOUNCE, TIMER_THROTTLE, TIMER_WAIT, getTimer };
+export { TIMER_DEBOUNCE, TIMER_THROTTLE, TIMER_WAIT, getAsyncTimer, getTimer };

package/dist/internal/function/timer.mjs

@@ -1,27 +1,73 @@
 //#region src/internal/function/timer.ts
+function getAsyncTimer(type, callback, time) {
+	async function run(item) {
+		const now = performance.now();
+		start ??= now;
+		if (interval === 0 || now - start >= interval - OFFSET) {
+			start = throttle ? now : void 0;
+			item.running = true;
+			try {
+				let result = callback(...item.parameters);
+				if (result instanceof Promise) result = await result;
+				item.resolve(result);
+			} catch (error) {
+				item.reject(error);
+			} finally {
+				item.running = false;
+			}
+		} else id = startTimer(() => run(item));
+	}
+	const interval = getInterval(time);
+	const throttle = type === TIMER_THROTTLE;
+	let id;
+	let last;
+	let start;
+	const timer = (...parameters) => {
+		timer.cancel();
+		const next = {
+			parameters,
+			running: false
+		};
+		next.promise = new Promise((resolve, reject) => {
+			next.reject = reject;
+			next.resolve = resolve;
+		});
+		last = next;
+		if (throttle) run(next);
+		else id = startTimer(() => run(next));
+		return next.promise;
+	};
+	timer.cancel = () => {
+		clearTimer(id);
+		if (last != null && !last.running) last.reject();
+	};
+	return timer;
+}
 function getInterval(value) {
 	return typeof value === "number" && value > 0 ? value : 0;
 }
 function getTimer(type, callback, time) {
-	const interval = getInterval(time);
-	function run(now) {
+	function run() {
+		const now = performance.now();
 		start ??= now;
 		if (interval === 0 || now - start >= interval - OFFSET) {
 			start = throttle ? now : void 0;
 			callback(...args);
-		} else frame = requestAnimationFrame(run);
+		} else id = startTimer(run);
 	}
+	const interval = getInterval(time);
 	const throttle = type === TIMER_THROTTLE;
 	let args;
-	let frame;
+	let id;
 	let start;
 	const timer = (...parameters) => {
 		timer.cancel();
 		args = parameters;
-		frame = requestAnimationFrame(run);
+		if (throttle) run();
+		else id = startTimer(run);
 	};
 	timer.cancel = () => {
-		cancelAnimationFrame(frame);
+		clearTimer(id);
 	};
 	return timer;
 }
@@ -29,5 +75,9 @@ const OFFSET = 5;
 const TIMER_DEBOUNCE = "debounce";
 const TIMER_THROTTLE = "throttle";
 const TIMER_WAIT = "wait";
+// istanbul ignore next
+const clearTimer = typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : clearTimeout;
+// istanbul ignore next
+const startTimer = typeof requestAnimationFrame === "function" ? requestAnimationFrame : setTimeout;
 //#endregion
-export { TIMER_DEBOUNCE, TIMER_THROTTLE, TIMER_WAIT, getTimer };
+export { TIMER_DEBOUNCE, TIMER_THROTTLE, TIMER_WAIT, getAsyncTimer, getTimer };

package/dist/models.d.mts

@@ -3,6 +3,15 @@
  * A generic array or object
  */
 type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
+/**
+ * An asynchronous callback that can be canceled
+ */
+type AsyncCancelableCallback<Callback extends GenericAsyncCallback | GenericCallback> = (ReturnType<Callback> extends Promise<any> ? (...args: Parameters<Callback>) => Promise<Awaited<ReturnType<Callback>>> : (...args: Parameters<Callback>) => Promise<ReturnType<Callback>>) & {
+  /**
+   * Cancel the callback
+   */
+  cancel: () => void;
+};
 /**
  * For mathicng any `void`, `Date`, primitive, or `RegExp` values
  *
@@ -10,7 +19,7 @@ type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
  */
 type BuiltIns = void | Date | Primitive | RegExp;
 /**
- * An extend callback that can be canceled
+ * A synchronous callback that can be canceled
  */
 type CancelableCallback<Callback extends GenericCallback> = Callback & {
   /**
@@ -135,4 +144,4 @@ type ToString<Value> = Value extends string | number ? `${Value}` : never;
  */
 type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
 //#endregion
-export { ArrayOrPlainObject, BuiltIns, CancelableCallback, Constructor, EventPosition, GenericAsyncCallback, GenericCallback, Key, KeyedValue, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, OnceAsyncCallback, OnceCallback, PlainObject, Primitive, RequiredKeys, Simplify, ToString, TypedArray };
+export { ArrayOrPlainObject, AsyncCancelableCallback, BuiltIns, CancelableCallback, Constructor, EventPosition, GenericAsyncCallback, GenericCallback, Key, KeyedValue, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, OnceAsyncCallback, OnceCallback, PlainObject, Primitive, RequiredKeys, Simplify, ToString, TypedArray };

package/dist/value/clone.mjs

@@ -103,7 +103,7 @@ function cloneValue(value, depth, references) {
 		case value instanceof Date: return new Date(value.getTime());
 		case value instanceof RegExp: return cloneRegularExpression(value, depth, references);
 		case value instanceof Map: return cloneMap(value, depth, references);
-		case value instanceof Node: return cloneNode(value, depth, references);
+		case typeof Node !== "undefined" && value instanceof Node: return cloneNode(value, depth, references);
 		case value instanceof Set: return cloneSet(value, depth, references);
 		case isArrayOrPlainObject(value): return clonePlainObject(value, depth, references);
 		case isTypedArray(value): return cloneTypedArray(value, depth, references);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.169.0",
+	"version": "0.171.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -76,6 +76,10 @@
 			"types": "./dist/function/assert.d.mts",
 			"default": "./dist/function/assert.mjs"
 		},
+		"./function/limit": {
+			"types": "./dist/function/limit.d.mts",
+			"default": "./dist/function/limit.mjs"
+		},
 		"./function/once": {
 			"types": "./dist/function/once.d.mts",
 			"default": "./dist/function/once.mjs"
@@ -221,7 +225,6 @@
 		"tsdown:build": "npx tsdown -c ./tsdown.config.ts",
 		"tsdown:watch": "npx tsdown -c ./tsdown.config.ts --watch",
 		"test": "npx vp test run --coverage",
-		"test:leak": "npx vp test run --detect-async-leaks --coverage",
 		"watch": "npx vite build --watch"
 	},
 	"devDependencies": {

package/src/function/index.ts

@@ -1,41 +1,2 @@
-import {getTimer, TIMER_DEBOUNCE, TIMER_THROTTLE} from '../internal/function/timer';
-import type {CancelableCallback, GenericCallback} from '../models';
-
-// #region Functions
-
-/**
- * Debounce a function, ensuring it is only called after `time` milliseconds have passed
- *
- * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
- * @param callback Callback to debounce
- * @param time Time in milliseconds to wait before calling the callback _(defaults to match frame rate)_
- * @returns Debounced callback with a `cancel` method
- */
-export function debounce<Callback extends GenericCallback>(
-	callback: Callback,
-	time?: number,
-): CancelableCallback<Callback> {
-	return getTimer(TIMER_DEBOUNCE, callback, time);
-}
-
-/**
- * Throttle a function, ensuring it is only called once every `time` milliseconds
- * @param callback Callback to throttle
- * @param time Time in milliseconds to wait before calling the callback again _(defaults to match frame rate)_
- * @returns Throttled callback with a `cancel` method
- */
-export function throttle<Callback extends GenericCallback>(
-	callback: Callback,
-	time?: number,
-): CancelableCallback<Callback> {
-	return getTimer(TIMER_THROTTLE, callback, time);
-}
-
-// #endregion
-
-// #region Exports
-
 export {noop} from '../internal/function/misc';
 export {memoize, type Memoized, type MemoizedOptions} from './memoize';
-
-// #endregion

package/src/function/limit.ts

@@ -0,0 +1,77 @@
+import {getAsyncTimer, getTimer, TIMER_DEBOUNCE, TIMER_THROTTLE} from '../internal/function/timer';
+import type {
+	AsyncCancelableCallback,
+	CancelableCallback,
+	GenericAsyncCallback,
+	GenericCallback,
+} from '../models';
+
+// #region Functions
+
+/**
+ * Debounce a function, ensuring it is only called after `time` milliseconds have passed
+ *
+ * When called, successful _(finished)_ results will resolve and errors will reject.
+ *
+ * On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
+ * @param callback Callback to debounce
+ * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Debounced callback handler with a `cancel` method
+ */
+function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(
+	callback: Callback,
+	time?: number,
+): AsyncCancelableCallback<Callback> {
+	return getAsyncTimer(TIMER_DEBOUNCE, callback, time);
+}
+
+/**
+ * Throttle a function, ensuring it is only called once every `time` milliseconds
+ *
+ * When called, successful _(finished)_ results will resolve and errors will reject.
+ *
+ * On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
+ * @param callback Callback to throttle
+ * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Throttled callback handler with a `cancel` method
+ */
+function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(
+	callback: Callback,
+	time?: number,
+): AsyncCancelableCallback<Callback> {
+	return getAsyncTimer(TIMER_THROTTLE, callback, time);
+}
+
+/**
+ * Debounce a function, ensuring it is only called after `time` milliseconds have passed
+ *
+ * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
+ * @param callback Callback to debounce
+ * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Debounced callback handler with a `cancel` method
+ */
+export function debounce<Callback extends GenericCallback>(
+	callback: Callback,
+	time?: number,
+): CancelableCallback<Callback> {
+	return getTimer(TIMER_DEBOUNCE, callback, time);
+}
+
+debounce.async = asyncDebounce;
+
+/**
+ * Throttle a function, ensuring it is only called once every `time` milliseconds
+ * @param callback Callback to throttle
+ * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
+ * @returns Throttled callback handler with a `cancel` method
+ */
+export function throttle<Callback extends GenericCallback>(
+	callback: Callback,
+	time?: number,
+): CancelableCallback<Callback> {
+	return getTimer(TIMER_THROTTLE, callback, time);
+}
+
+throttle.async = asyncThrottle;
+
+// #endregion

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './array/unique';
 
 export * from './function/assert';
 export * from './function/index';
+export * from './function/limit';
 export * from './function/once';
 export * from './function/retry';
 export * from './function/work';

package/src/internal/function/timer.ts

@@ -1,13 +1,101 @@
-import type {CancelableCallback, GenericCallback} from '../../models';
+import type {
+	AsyncCancelableCallback,
+	CancelableCallback,
+	GenericAsyncCallback,
+	GenericCallback,
+} from '../../models';
 
 // #region Types
 
+type AsyncItem = {
+	parameters: unknown[];
+	promise: Promise<unknown>;
+	reject: (reason?: unknown) => void;
+	resolve: (value?: unknown) => void;
+	running: boolean;
+};
+
 type TimerType = 'debounce' | 'throttle' | 'wait';
 
 // #endregion
 
 // #region Functions
 
+export function getAsyncTimer<Callback extends GenericAsyncCallback | GenericCallback>(
+	type: TimerType,
+	callback: Callback,
+	time?: number,
+): AsyncCancelableCallback<Callback> {
+	async function run(item: AsyncItem): Promise<void> {
+		const now = performance.now();
+
+		start ??= now;
+
+		if (interval === 0 || now - start >= interval - OFFSET) {
+			start = throttle ? now : undefined;
+
+			item.running = true;
+
+			try {
+				let result = callback(...item.parameters);
+
+				if (result instanceof Promise) {
+					result = await result;
+				}
+
+				item.resolve(result);
+			} catch (error) {
+				item.reject(error);
+			} finally {
+				item.running = false;
+			}
+		} else {
+			id = startTimer(() => run(item));
+		}
+	}
+
+	const interval = getInterval(time);
+	const throttle = type === TIMER_THROTTLE;
+
+	let id: number;
+	let last: AsyncItem;
+	let start: number | undefined;
+
+	const timer = (...parameters: Parameters<Callback>): Promise<unknown> => {
+		timer.cancel();
+
+		const next: AsyncItem = {
+			parameters,
+			running: false,
+		} as never;
+
+		next.promise = new Promise<unknown>((resolve, reject) => {
+			next.reject = reject;
+			next.resolve = resolve;
+		});
+
+		last = next;
+
+		if (throttle) {
+			run(next);
+		} else {
+			id = startTimer(() => run(next));
+		}
+
+		return next.promise;
+	};
+
+	timer.cancel = (): void => {
+		clearTimer(id);
+
+		if (last != null && !last.running) {
+			last.reject();
+		}
+	};
+
+	return timer as AsyncCancelableCallback<Callback>;
+}
+
 function getInterval(value: unknown): number {
 	return typeof value === 'number' && value > 0 ? value : 0;
 }
@@ -17,9 +105,9 @@ export function getTimer<Callback extends GenericCallback>(
 	callback: Callback,
 	time?: number,
 ): CancelableCallback<Callback> {
-	const interval = getInterval(time);
+	function run(): void {
+		const now = performance.now();
 
-	function run(now: DOMHighResTimeStamp): void {
 		start ??= now;
 
 		if (interval === 0 || now - start >= interval - OFFSET) {
@@ -27,25 +115,31 @@ export function getTimer<Callback extends GenericCallback>(
 
 			callback(...args);
 		} else {
-			frame = requestAnimationFrame(run);
+			id = startTimer(run);
 		}
 	}
 
+	const interval = getInterval(time);
 	const throttle = type === TIMER_THROTTLE;
 
 	let args: Parameters<Callback>;
-	let frame: DOMHighResTimeStamp | undefined;
-	let start: DOMHighResTimeStamp | undefined;
+	let id: number;
+	let start: number | undefined;
 
 	const timer = (...parameters: Parameters<Callback>): void => {
 		timer.cancel();
 
 		args = parameters;
-		frame = requestAnimationFrame(run);
+
+		if (throttle) {
+			run();
+		} else {
+			id = startTimer(run);
+		}
 	};
 
 	timer.cancel = (): void => {
-		cancelAnimationFrame(frame!);
+		clearTimer(id);
 	};
 
 	return timer as CancelableCallback<Callback>;
@@ -63,4 +157,10 @@ export const TIMER_THROTTLE: TimerType = 'throttle';
 
 export const TIMER_WAIT: TimerType = 'wait';
 
+// istanbul ignore next
+const clearTimer = typeof cancelAnimationFrame === 'function' ? cancelAnimationFrame : clearTimeout;
+
+// istanbul ignore next
+const startTimer = typeof requestAnimationFrame === 'function' ? requestAnimationFrame : setTimeout;
+
 // #endregion

package/src/models.ts

@@ -5,6 +5,19 @@
  */
 export type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
 
+/**
+ * An asynchronous callback that can be canceled
+ */
+export type AsyncCancelableCallback<Callback extends GenericAsyncCallback | GenericCallback> =
+	(ReturnType<Callback> extends Promise<any>
+		? (...args: Parameters<Callback>) => Promise<Awaited<ReturnType<Callback>>>
+		: (...args: Parameters<Callback>) => Promise<ReturnType<Callback>>) & {
+		/**
+		 * Cancel the callback
+		 */
+		cancel: () => void;
+	};
+
 /**
  * For mathicng any `void`, `Date`, primitive, or `RegExp` values
  *
@@ -13,7 +26,7 @@ export type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
 export type BuiltIns = void | Date | Primitive | RegExp;
 
 /**
- * An extend callback that can be canceled
+ * A synchronous callback that can be canceled
  */
 export type CancelableCallback<Callback extends GenericCallback> = Callback & {
 	/**

package/src/value/clone.ts

@@ -243,7 +243,7 @@ function cloneValue(value: unknown, depth: number, references: WeakMap<WeakKey,
 		case value instanceof Map:
 			return cloneMap(value, depth, references);
 
-		case value instanceof Node:
+		case typeof Node !== 'undefined' && value instanceof Node:
 			return cloneNode(value, depth, references);
 
 		case value instanceof Set: