es-toolkit 1.47.1 → 1.48.0

package/dist/compat/object/pick.js

@@ -24,14 +24,15 @@ const require_set = require("./set.js");
 * // each path can be passed individually as an argument
 * const obj = { a: 1, b: 2, c: 3 };
 * const result = pick(obj, 'a', 'c');
+* // result will be { a: 1, c: 3 }
 *
 * // pick a key over a path
 * const obj = { 'a.b': 1, a: { b: 2 } };
 * const result = pick(obj, 'a.b');
 * // result will be { 'a.b': 1 }
 */
-function pick(obj, ...keysArr) {
-	if (require_isNil.isNil(obj)) return {};
+function pick(object, ...keysArr) {
+	if (require_isNil.isNil(object)) return {};
 	const result = {};
 	for (let i = 0; i < keysArr.length; i++) {
 		let keys = keysArr[i];
@@ -47,9 +48,9 @@ function pick(obj, ...keysArr) {
 				break;
 		}
 		for (const key of keys) {
-			const value = require_get.get(obj, key);
-			if (value === void 0 && !require_has.has(obj, key)) continue;
-			if (typeof key === "string" && Object.hasOwn(obj, key)) result[key] = value;
+			const value = require_get.get(object, key);
+			if (value === void 0 && !require_has.has(object, key)) continue;
+			if (typeof key === "string" && Object.hasOwn(object, key)) result[key] = value;
 			else require_set.set(result, key, value);
 		}
 	}

package/dist/compat/object/pick.mjs

@@ -24,14 +24,15 @@ import { set } from "./set.mjs";
 * // each path can be passed individually as an argument
 * const obj = { a: 1, b: 2, c: 3 };
 * const result = pick(obj, 'a', 'c');
+* // result will be { a: 1, c: 3 }
 *
 * // pick a key over a path
 * const obj = { 'a.b': 1, a: { b: 2 } };
 * const result = pick(obj, 'a.b');
 * // result will be { 'a.b': 1 }
 */
-function pick(obj, ...keysArr) {
-	if (isNil(obj)) return {};
+function pick(object, ...keysArr) {
+	if (isNil(object)) return {};
 	const result = {};
 	for (let i = 0; i < keysArr.length; i++) {
 		let keys = keysArr[i];
@@ -47,9 +48,9 @@ function pick(obj, ...keysArr) {
 				break;
 		}
 		for (const key of keys) {
-			const value = get(obj, key);
-			if (value === void 0 && !has(obj, key)) continue;
-			if (typeof key === "string" && Object.hasOwn(obj, key)) result[key] = value;
+			const value = get(object, key);
+			if (value === void 0 && !has(object, key)) continue;
+			if (typeof key === "string" && Object.hasOwn(object, key)) result[key] = value;
 			else set(result, key, value);
 		}
 	}

package/dist/compat/predicate/isMatchWith.js

@@ -77,20 +77,23 @@ function isMatchWith(target, source, compare) {
 	return isMatchWithInternal(target, source, function doesMatch(objValue, srcValue, key, object, source, stack) {
 		const isEqual = compare(objValue, srcValue, key, object, source, stack);
 		if (isEqual !== void 0) return Boolean(isEqual);
-		return isMatchWithInternal(objValue, srcValue, doesMatch, stack);
-	}, /* @__PURE__ */ new Map());
+		return isMatchWithInternal(objValue, srcValue, doesMatch, stack, false);
+	}, /* @__PURE__ */ new Map(), true);
 }
-function isMatchWithInternal(target, source, compare, stack) {
+function isMatchWithInternal(target, source, compare, stack, isRoot = false) {
 	if (source === target) return true;
 	switch (typeof source) {
 		case "object": return isObjectMatch(target, source, compare, stack);
 		case "function":
-			if (Object.keys(source).length > 0) return isMatchWithInternal(target, { ...source }, compare, stack);
+			if (Object.keys(source).length > 0) return isMatchWithInternal(target, { ...source }, compare, stack, isRoot);
 			return require_isEqualsSameValueZero.isEqualsSameValueZero(target, source);
 		default:
 			if (!require_isObject.isObject(target)) return require_isEqualsSameValueZero.isEqualsSameValueZero(target, source);
-			if (typeof source === "string") return source === "";
-			return true;
+			if (isRoot) {
+				if (typeof source === "string") return source === "";
+				return true;
+			}
+			return require_isEqualsSameValueZero.isEqualsSameValueZero(target, source);
 	}
 }
 function isObjectMatch(target, source, compare, stack) {

package/dist/compat/predicate/isMatchWith.mjs

@@ -77,20 +77,23 @@ function isMatchWith(target, source, compare) {
 	return isMatchWithInternal(target, source, function doesMatch(objValue, srcValue, key, object, source, stack) {
 		const isEqual = compare(objValue, srcValue, key, object, source, stack);
 		if (isEqual !== void 0) return Boolean(isEqual);
-		return isMatchWithInternal(objValue, srcValue, doesMatch, stack);
-	}, /* @__PURE__ */ new Map());
+		return isMatchWithInternal(objValue, srcValue, doesMatch, stack, false);
+	}, /* @__PURE__ */ new Map(), true);
 }
-function isMatchWithInternal(target, source, compare, stack) {
+function isMatchWithInternal(target, source, compare, stack, isRoot = false) {
 	if (source === target) return true;
 	switch (typeof source) {
 		case "object": return isObjectMatch(target, source, compare, stack);
 		case "function":
-			if (Object.keys(source).length > 0) return isMatchWithInternal(target, { ...source }, compare, stack);
+			if (Object.keys(source).length > 0) return isMatchWithInternal(target, { ...source }, compare, stack, isRoot);
 			return isEqualsSameValueZero(target, source);
 		default:
 			if (!isObject(target)) return isEqualsSameValueZero(target, source);
-			if (typeof source === "string") return source === "";
-			return true;
+			if (isRoot) {
+				if (typeof source === "string") return source === "";
+				return true;
+			}
+			return isEqualsSameValueZero(target, source);
 	}
 }
 function isObjectMatch(target, source, compare, stack) {

package/dist/compat/predicate/isNaN.js

@@ -1,3 +1,4 @@
+const require_isNumber = require("./isNumber.js");
 //#region src/compat/predicate/isNaN.ts
 /**
 * Checks if the value is NaN.
@@ -12,7 +13,7 @@
 * isNaN(undefined); // false
 */
 function isNaN(value) {
-	return Number.isNaN(value);
+	return require_isNumber.isNumber(value) && Number.isNaN(Number(value));
 }
 //#endregion
 exports.isNaN = isNaN;

package/dist/compat/predicate/isNaN.mjs

@@ -1,3 +1,4 @@
+import { isNumber } from "./isNumber.mjs";
 //#region src/compat/predicate/isNaN.ts
 /**
 * Checks if the value is NaN.
@@ -12,7 +13,7 @@
 * isNaN(undefined); // false
 */
 function isNaN(value) {
-	return Number.isNaN(value);
+	return isNumber(value) && Number.isNaN(Number(value));
 }
 //#endregion
 export { isNaN };

package/dist/compat/predicate/isNumber.js

@@ -1,3 +1,6 @@
+const require_getTag = require("../_internal/getTag.js");
+require("../_internal/tags.js");
+const require_isObjectLike = require("./isObjectLike.js");
 //#region src/compat/predicate/isNumber.ts
 /**
 * Checks if a given value is a number.
@@ -17,7 +20,7 @@
 * console.log(isNumber(value3)); // false
 */
 function isNumber(value) {
-	return typeof value === "number" || value instanceof Number;
+	return typeof value === "number" || require_isObjectLike.isObjectLike(value) && require_getTag.getTag(value) === "[object Number]";
 }
 //#endregion
 exports.isNumber = isNumber;

package/dist/compat/predicate/isNumber.mjs

@@ -1,3 +1,6 @@
+import { getTag } from "../_internal/getTag.mjs";
+import "../_internal/tags.mjs";
+import { isObjectLike } from "./isObjectLike.mjs";
 //#region src/compat/predicate/isNumber.ts
 /**
 * Checks if a given value is a number.
@@ -17,7 +20,7 @@
 * console.log(isNumber(value3)); // false
 */
 function isNumber(value) {
-	return typeof value === "number" || value instanceof Number;
+	return typeof value === "number" || isObjectLike(value) && getTag(value) === "[object Number]";
 }
 //#endregion
 export { isNumber };

package/dist/compat/util/toPath.js

@@ -29,10 +29,7 @@ function toPath(deepKey) {
 	let key = "";
 	let quoteChar = "";
 	let bracket = false;
-	if (deepKey.charCodeAt(0) === 46) {
-		result.push("");
-		index++;
-	}
+	if (deepKey.charCodeAt(0) === 46) result.push("");
 	while (index < length) {
 		const char = deepKey[index];
 		if (quoteChar) if (char === "\\" && index + 1 < length) {
@@ -57,6 +54,8 @@ function toPath(deepKey) {
 				result.push(key);
 				key = "";
 			}
+			const next = deepKey[index + 1];
+			if (next === void 0 || next === ".") result.push("");
 		} else key += char;
 		index++;
 	}

package/dist/compat/util/toPath.mjs

@@ -29,10 +29,7 @@ function toPath(deepKey) {
 	let key = "";
 	let quoteChar = "";
 	let bracket = false;
-	if (deepKey.charCodeAt(0) === 46) {
-		result.push("");
-		index++;
-	}
+	if (deepKey.charCodeAt(0) === 46) result.push("");
 	while (index < length) {
 		const char = deepKey[index];
 		if (quoteChar) if (char === "\\" && index + 1 < length) {
@@ -57,6 +54,8 @@ function toPath(deepKey) {
 				result.push(key);
 				key = "";
 			}
+			const next = deepKey[index + 1];
+			if (next === void 0 || next === ".") result.push("");
 		} else key += char;
 		index++;
 	}

package/dist/function/debounce.d.mts

@@ -43,6 +43,7 @@ interface DebouncedFunction<F extends (...args: any[]) => void> {
  * @param debounceMs - The number of milliseconds to delay.
  * @param options - The options object
  * @param options.signal - An optional AbortSignal to cancel the debounced function.
+ * @param options.edges - An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
  * @returns A new debounced function with a `cancel` method.
  *
  * @example

package/dist/function/debounce.d.ts

@@ -43,6 +43,7 @@ interface DebouncedFunction<F extends (...args: any[]) => void> {
  * @param debounceMs - The number of milliseconds to delay.
  * @param options - The options object
  * @param options.signal - An optional AbortSignal to cancel the debounced function.
+ * @param options.edges - An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
  * @returns A new debounced function with a `cancel` method.
  *
  * @example

package/dist/function/debounce.js

@@ -9,6 +9,7 @@
 * @param debounceMs - The number of milliseconds to delay.
 * @param options - The options object
 * @param options.signal - An optional AbortSignal to cancel the debounced function.
+* @param options.edges - An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
 * @returns A new debounced function with a `cancel` method.
 *
 * @example

package/dist/function/debounce.mjs

@@ -9,6 +9,7 @@
 * @param debounceMs - The number of milliseconds to delay.
 * @param options - The options object
 * @param options.signal - An optional AbortSignal to cancel the debounced function.
+* @param options.edges - An optional array specifying whether the function should be invoked on the leading edge, trailing edge, or both.
 * @returns A new debounced function with a `cancel` method.
 *
 * @example

package/dist/object/toMerged.js

@@ -1,4 +1,5 @@
 const require_clone = require("./clone.js");
+const require_cloneDeep = require("./cloneDeep.js");
 const require_isPlainObject = require("../predicate/isPlainObject.js");
 const require_mergeWith = require("./mergeWith.js");
 //#region src/object/toMerged.ts
@@ -45,7 +46,7 @@ const require_mergeWith = require("./mergeWith.js");
 * // Output: { a: [1, 2, 3] }
 */
 function toMerged(target, source) {
-	return require_mergeWith.mergeWith(require_clone.clone(target), source, function mergeRecursively(targetValue, sourceValue) {
+	return require_mergeWith.mergeWith(require_cloneDeep.cloneDeep(target), source, function mergeRecursively(targetValue, sourceValue) {
 		if (Array.isArray(sourceValue)) if (Array.isArray(targetValue)) return require_mergeWith.mergeWith(require_clone.clone(targetValue), sourceValue, mergeRecursively);
 		else return require_mergeWith.mergeWith([], sourceValue, mergeRecursively);
 		else if (require_isPlainObject.isPlainObject(sourceValue)) if (require_isPlainObject.isPlainObject(targetValue)) return require_mergeWith.mergeWith(require_clone.clone(targetValue), sourceValue, mergeRecursively);

package/dist/object/toMerged.mjs

@@ -1,4 +1,5 @@
 import { clone } from "./clone.mjs";
+import { cloneDeep } from "./cloneDeep.mjs";
 import { isPlainObject } from "../predicate/isPlainObject.mjs";
 import { mergeWith } from "./mergeWith.mjs";
 //#region src/object/toMerged.ts
@@ -45,7 +46,7 @@ import { mergeWith } from "./mergeWith.mjs";
 * // Output: { a: [1, 2, 3] }
 */
 function toMerged(target, source) {
-	return mergeWith(clone(target), source, function mergeRecursively(targetValue, sourceValue) {
+	return mergeWith(cloneDeep(target), source, function mergeRecursively(targetValue, sourceValue) {
 		if (Array.isArray(sourceValue)) if (Array.isArray(targetValue)) return mergeWith(clone(targetValue), sourceValue, mergeRecursively);
 		else return mergeWith([], sourceValue, mergeRecursively);
 		else if (isPlainObject(sourceValue)) if (isPlainObject(targetValue)) return mergeWith(clone(targetValue), sourceValue, mergeRecursively);

package/dist/promise/timeout.d.mts

@@ -1,9 +1,20 @@
 //#region src/promise/timeout.d.ts
+interface TimeoutOptions {
+  signal?: AbortSignal;
+}
 /**
  * Returns a promise that rejects with a `TimeoutError` after a specified delay.
  *
+ * You can pass an `AbortSignal` to cancel the timeout. Unlike most `AbortSignal`-aware
+ * APIs, aborting does **not** reject the promise. A `timeout` only exists to lose a
+ * `Promise.race`, so cancelling it leaves the promise pending forever, allowing the
+ * operation it guards to settle on its own. The underlying timer and abort listener
+ * are cleared on abort, so nothing is leaked.
+ *
  * @param ms - The delay duration in milliseconds.
- * @returns A promise that rejects with a `TimeoutError` after the specified delay.
+ * @param options - The options object.
+ * @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the returned promise never settles.
+ * @returns A promise that rejects with a `TimeoutError` after the specified delay, or never settles if aborted.
  * @throws {TimeoutError} Throws a `TimeoutError` after the specified delay.
  *
  * @example
@@ -12,7 +23,19 @@
  * } catch (error) {
  *   console.error(error); // Will log 'The operation was timed out'
  * }
+ *
+ * @example
+ * // Cancelling the timeout lifts the time limit instead of throwing.
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 50);
+ *
+ * const result = await Promise.race([
+ *   doWork(),
+ *   timeout(1000, { signal: controller.signal }), // never rejects once aborted
+ * ]);
  */
-declare function timeout(ms: number): Promise<never>;
+declare function timeout(ms: number, {
+  signal
+}?: TimeoutOptions): Promise<never>;
 //#endregion
 export { timeout };

package/dist/promise/timeout.d.ts

@@ -1,9 +1,20 @@
 //#region src/promise/timeout.d.ts
+interface TimeoutOptions {
+  signal?: AbortSignal;
+}
 /**
  * Returns a promise that rejects with a `TimeoutError` after a specified delay.
  *
+ * You can pass an `AbortSignal` to cancel the timeout. Unlike most `AbortSignal`-aware
+ * APIs, aborting does **not** reject the promise. A `timeout` only exists to lose a
+ * `Promise.race`, so cancelling it leaves the promise pending forever, allowing the
+ * operation it guards to settle on its own. The underlying timer and abort listener
+ * are cleared on abort, so nothing is leaked.
+ *
  * @param ms - The delay duration in milliseconds.
- * @returns A promise that rejects with a `TimeoutError` after the specified delay.
+ * @param options - The options object.
+ * @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the returned promise never settles.
+ * @returns A promise that rejects with a `TimeoutError` after the specified delay, or never settles if aborted.
  * @throws {TimeoutError} Throws a `TimeoutError` after the specified delay.
  *
  * @example
@@ -12,7 +23,19 @@
  * } catch (error) {
  *   console.error(error); // Will log 'The operation was timed out'
  * }
+ *
+ * @example
+ * // Cancelling the timeout lifts the time limit instead of throwing.
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 50);
+ *
+ * const result = await Promise.race([
+ *   doWork(),
+ *   timeout(1000, { signal: controller.signal }), // never rejects once aborted
+ * ]);
  */
-declare function timeout(ms: number): Promise<never>;
+declare function timeout(ms: number, {
+  signal
+}?: TimeoutOptions): Promise<never>;
 //#endregion
 export { timeout };

package/dist/promise/timeout.js

@@ -1,11 +1,18 @@
 const require_TimeoutError = require("../error/TimeoutError.js");
-const require_delay = require("./delay.js");
 //#region src/promise/timeout.ts
 /**
 * Returns a promise that rejects with a `TimeoutError` after a specified delay.
 *
+* You can pass an `AbortSignal` to cancel the timeout. Unlike most `AbortSignal`-aware
+* APIs, aborting does **not** reject the promise. A `timeout` only exists to lose a
+* `Promise.race`, so cancelling it leaves the promise pending forever, allowing the
+* operation it guards to settle on its own. The underlying timer and abort listener
+* are cleared on abort, so nothing is leaked.
+*
 * @param ms - The delay duration in milliseconds.
-* @returns A promise that rejects with a `TimeoutError` after the specified delay.
+* @param options - The options object.
+* @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the returned promise never settles.
+* @returns A promise that rejects with a `TimeoutError` after the specified delay, or never settles if aborted.
 * @throws {TimeoutError} Throws a `TimeoutError` after the specified delay.
 *
 * @example
@@ -14,10 +21,29 @@ const require_delay = require("./delay.js");
 * } catch (error) {
 *   console.error(error); // Will log 'The operation was timed out'
 * }
+*
+* @example
+* // Cancelling the timeout lifts the time limit instead of throwing.
+* const controller = new AbortController();
+* setTimeout(() => controller.abort(), 50);
+*
+* const result = await Promise.race([
+*   doWork(),
+*   timeout(1000, { signal: controller.signal }), // never rejects once aborted
+* ]);
 */
-async function timeout(ms) {
-	await require_delay.delay(ms);
-	throw new require_TimeoutError.TimeoutError();
+function timeout(ms, { signal } = {}) {
+	return new Promise((_resolve, reject) => {
+		const abortHandler = () => {
+			clearTimeout(timeoutId);
+		};
+		if (signal?.aborted) return;
+		const timeoutId = setTimeout(() => {
+			signal?.removeEventListener("abort", abortHandler);
+			reject(new require_TimeoutError.TimeoutError());
+		}, ms);
+		signal?.addEventListener("abort", abortHandler, { once: true });
+	});
 }
 //#endregion
 exports.timeout = timeout;

package/dist/promise/timeout.mjs

@@ -1,11 +1,18 @@
 import { TimeoutError } from "../error/TimeoutError.mjs";
-import { delay } from "./delay.mjs";
 //#region src/promise/timeout.ts
 /**
 * Returns a promise that rejects with a `TimeoutError` after a specified delay.
 *
+* You can pass an `AbortSignal` to cancel the timeout. Unlike most `AbortSignal`-aware
+* APIs, aborting does **not** reject the promise. A `timeout` only exists to lose a
+* `Promise.race`, so cancelling it leaves the promise pending forever, allowing the
+* operation it guards to settle on its own. The underlying timer and abort listener
+* are cleared on abort, so nothing is leaked.
+*
 * @param ms - The delay duration in milliseconds.
-* @returns A promise that rejects with a `TimeoutError` after the specified delay.
+* @param options - The options object.
+* @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the returned promise never settles.
+* @returns A promise that rejects with a `TimeoutError` after the specified delay, or never settles if aborted.
 * @throws {TimeoutError} Throws a `TimeoutError` after the specified delay.
 *
 * @example
@@ -14,10 +21,29 @@ import { delay } from "./delay.mjs";
 * } catch (error) {
 *   console.error(error); // Will log 'The operation was timed out'
 * }
+*
+* @example
+* // Cancelling the timeout lifts the time limit instead of throwing.
+* const controller = new AbortController();
+* setTimeout(() => controller.abort(), 50);
+*
+* const result = await Promise.race([
+*   doWork(),
+*   timeout(1000, { signal: controller.signal }), // never rejects once aborted
+* ]);
 */
-async function timeout(ms) {
-	await delay(ms);
-	throw new TimeoutError();
+function timeout(ms, { signal } = {}) {
+	return new Promise((_resolve, reject) => {
+		const abortHandler = () => {
+			clearTimeout(timeoutId);
+		};
+		if (signal?.aborted) return;
+		const timeoutId = setTimeout(() => {
+			signal?.removeEventListener("abort", abortHandler);
+			reject(new TimeoutError());
+		}, ms);
+		signal?.addEventListener("abort", abortHandler, { once: true });
+	});
 }
 //#endregion
 export { timeout };

package/dist/promise/withTimeout.d.mts

@@ -1,14 +1,23 @@
 //#region src/promise/withTimeout.d.ts
+interface WithTimeoutOptions {
+  signal?: AbortSignal;
+}
 /**
  * Executes an async function and enforces a timeout.
  *
  * If the promise does not resolve within the specified time,
  * the timeout will trigger and the returned promise will be rejected.
  *
+ * You can pass an `AbortSignal` to cancel the timeout. Aborting the signal lifts the
+ * time limit: the timeout stops counting and `run`'s promise is awaited without a
+ * deadline. It does not reject the returned promise or abort `run` itself — pass the
+ * same signal into `run` if you also want to cancel the underlying work.
  *
  * @template T
  * @param run - A function that returns a promise to be executed.
  * @param ms - The timeout duration in milliseconds.
+ * @param options - The options object.
+ * @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the time limit is lifted.
  * @returns A promise that resolves with the result of the `run` function or rejects if the timeout is reached.
  *
  * @example
@@ -23,7 +32,16 @@
  * } catch (error) {
  *   console.error(error); // Will log 'TimeoutError' if `fetchData` is not resolved within 1 second.
  * }
+ *
+ * @example
+ * // Lift the time limit when the user opts to keep waiting.
+ * const controller = new AbortController();
+ * keepWaitingButton.onclick = () => controller.abort();
+ *
+ * const data = await withTimeout(fetchData, 1000, { signal: controller.signal });
  */
-declare function withTimeout<T>(run: () => Promise<T>, ms: number): Promise<T>;
+declare function withTimeout<T>(run: () => Promise<T>, ms: number, {
+  signal
+}?: WithTimeoutOptions): Promise<T>;
 //#endregion
 export { withTimeout };

package/dist/promise/withTimeout.d.ts

@@ -1,14 +1,23 @@
 //#region src/promise/withTimeout.d.ts
+interface WithTimeoutOptions {
+  signal?: AbortSignal;
+}
 /**
  * Executes an async function and enforces a timeout.
  *
  * If the promise does not resolve within the specified time,
  * the timeout will trigger and the returned promise will be rejected.
  *
+ * You can pass an `AbortSignal` to cancel the timeout. Aborting the signal lifts the
+ * time limit: the timeout stops counting and `run`'s promise is awaited without a
+ * deadline. It does not reject the returned promise or abort `run` itself — pass the
+ * same signal into `run` if you also want to cancel the underlying work.
  *
  * @template T
  * @param run - A function that returns a promise to be executed.
  * @param ms - The timeout duration in milliseconds.
+ * @param options - The options object.
+ * @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the time limit is lifted.
  * @returns A promise that resolves with the result of the `run` function or rejects if the timeout is reached.
  *
  * @example
@@ -23,7 +32,16 @@
  * } catch (error) {
  *   console.error(error); // Will log 'TimeoutError' if `fetchData` is not resolved within 1 second.
  * }
+ *
+ * @example
+ * // Lift the time limit when the user opts to keep waiting.
+ * const controller = new AbortController();
+ * keepWaitingButton.onclick = () => controller.abort();
+ *
+ * const data = await withTimeout(fetchData, 1000, { signal: controller.signal });
  */
-declare function withTimeout<T>(run: () => Promise<T>, ms: number): Promise<T>;
+declare function withTimeout<T>(run: () => Promise<T>, ms: number, {
+  signal
+}?: WithTimeoutOptions): Promise<T>;
 //#endregion
 export { withTimeout };

package/dist/promise/withTimeout.js

@@ -6,10 +6,16 @@ const require_timeout = require("./timeout.js");
 * If the promise does not resolve within the specified time,
 * the timeout will trigger and the returned promise will be rejected.
 *
+* You can pass an `AbortSignal` to cancel the timeout. Aborting the signal lifts the
+* time limit: the timeout stops counting and `run`'s promise is awaited without a
+* deadline. It does not reject the returned promise or abort `run` itself — pass the
+* same signal into `run` if you also want to cancel the underlying work.
 *
 * @template T
 * @param run - A function that returns a promise to be executed.
 * @param ms - The timeout duration in milliseconds.
+* @param options - The options object.
+* @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the time limit is lifted.
 * @returns A promise that resolves with the result of the `run` function or rejects if the timeout is reached.
 *
 * @example
@@ -24,9 +30,16 @@ const require_timeout = require("./timeout.js");
 * } catch (error) {
 *   console.error(error); // Will log 'TimeoutError' if `fetchData` is not resolved within 1 second.
 * }
+*
+* @example
+* // Lift the time limit when the user opts to keep waiting.
+* const controller = new AbortController();
+* keepWaitingButton.onclick = () => controller.abort();
+*
+* const data = await withTimeout(fetchData, 1000, { signal: controller.signal });
 */
-async function withTimeout(run, ms) {
-	return Promise.race([run(), require_timeout.timeout(ms)]);
+async function withTimeout(run, ms, { signal } = {}) {
+	return Promise.race([run(), require_timeout.timeout(ms, { signal })]);
 }
 //#endregion
 exports.withTimeout = withTimeout;

package/dist/promise/withTimeout.mjs

@@ -6,10 +6,16 @@ import { timeout } from "./timeout.mjs";
 * If the promise does not resolve within the specified time,
 * the timeout will trigger and the returned promise will be rejected.
 *
+* You can pass an `AbortSignal` to cancel the timeout. Aborting the signal lifts the
+* time limit: the timeout stops counting and `run`'s promise is awaited without a
+* deadline. It does not reject the returned promise or abort `run` itself — pass the
+* same signal into `run` if you also want to cancel the underlying work.
 *
 * @template T
 * @param run - A function that returns a promise to be executed.
 * @param ms - The timeout duration in milliseconds.
+* @param options - The options object.
+* @param options.signal - An optional AbortSignal to cancel the timeout. When aborted, the time limit is lifted.
 * @returns A promise that resolves with the result of the `run` function or rejects if the timeout is reached.
 *
 * @example
@@ -24,9 +30,16 @@ import { timeout } from "./timeout.mjs";
 * } catch (error) {
 *   console.error(error); // Will log 'TimeoutError' if `fetchData` is not resolved within 1 second.
 * }
+*
+* @example
+* // Lift the time limit when the user opts to keep waiting.
+* const controller = new AbortController();
+* keepWaitingButton.onclick = () => controller.abort();
+*
+* const data = await withTimeout(fetchData, 1000, { signal: controller.signal });
 */
-async function withTimeout(run, ms) {
-	return Promise.race([run(), timeout(ms)]);
+async function withTimeout(run, ms, { signal } = {}) {
+	return Promise.race([run(), timeout(ms, { signal })]);
 }
 //#endregion
 export { withTimeout };