@brandup/ui-helpers 2.0.2 → 2.0.4

package/README.md

@@ -129,6 +129,9 @@ const data = await FuncHelper.minWaitAsync(() => loadData(), 1000);
 
 // Reject with TimeoutError if the request takes longer than 5000ms
 const result = await FuncHelper.timeout(fetch("/api"), 5000);
+
+// Make the wait abortable without stopping the underlying work
+const value = await FuncHelper.abortable(longRunning(), abortController.signal);
 ```
 
 Detect a timeout by checking the error type:
@@ -146,7 +149,18 @@ try {
 ```
 
 - `minWait(func, minTime?)` — wraps a callback so it runs no sooner than `minTime` ms after wrapping.
-- `minWaitAsync(func, minTime?, abort?)` — awaits an async operation, padding so it settles no sooner than `minTime` ms.
-- `delay(time, abort?)` — a promise resolved after `time` ms; rejects on abort.
-- `timeout(promise, timeout, abort?)` — races `promise` against `timeout` ms; rejects with a `TimeoutError` on timeout. Throws synchronously if `timeout ≤ 0`.
+- `minWaitAsync(func, minTime?, abort?)` — awaits an async operation, padding so it settles no sooner than `minTime` ms. An already-aborted signal rejects immediately, before `func` runs.
+- `delay(ms, abort?)` — a promise resolved after `ms` ms; rejects on abort. Throws synchronously if `ms` is negative (`0` is allowed).
+- `timeout(promise, ms, abort?)` — races `promise` against `ms` ms; rejects with a `TimeoutError` on timeout, or with the signal's reason on abort. Throws synchronously if `ms ≤ 0`. The underlying `promise` is not cancelled — only the wait ends.
+- `abortable(promise, abort?)` — makes *waiting* for `promise` abortable: rejects with the signal's reason on abort. Does not stop the underlying work; without a signal the promise is awaited as-is.
 - `TimeoutError` — error class thrown by `timeout` when the time limit is exceeded.
+
+## Polyfills
+
+An opt-in, side-effect-only entry point fills in `AbortSignal` APIs that older runtimes may lack — `AbortSignal.prototype.throwIfAborted`, `AbortSignal.timeout` and `AbortSignal.any`. Import it once, as early as possible (e.g. in your entry module):
+
+```TypeScript
+import "@brandup/ui-helpers/polyfill";
+```
+
+Each implementation installs only when missing, so native behaviour is preserved where available. Types ship with the TypeScript `ESNext` lib; this module provides just the runtime. It is excluded from tree-shaking (`sideEffects`), so a bare import is never dropped by the bundler.

package/dist/cjs/helpers/func.js

@@ -31,13 +31,17 @@ const minWait = (func, minTime) => {
  * Useful for keeping spinners/loading states visible for a minimum duration. If `minTime`
  * is omitted or falsy, `func` is awaited and its result returned without padding.
  *
+ * An already-aborted signal rejects immediately, before `func` runs; aborting later cancels
+ * the padding delay (but not `func` itself, which can't be cancelled here).
+ *
  * @typeParam TResult Result type produced by `func`.
  * @param func Factory returning the promise to await.
  * @param minTime Minimum total duration in milliseconds.
- * @param abort Optional signal used to cancel the padding delay.
+ * @param abort Optional signal used to cancel the wait.
  * @returns The result produced by `func`.
  */
 async function minWaitAsync(func, minTime, abort) {
+    abort?.throwIfAborted();
     if (!minTime)
         return func();
     const beginTime = Date.now();
@@ -51,6 +55,8 @@ async function minWaitAsync(func, minTime, abort) {
 const getRightTime = (start, minTime) => {
     const finishTime = Date.now();
     const w = minTime - (finishTime - start);
+    // Skip padding when the leftover is within 10% of `minTime`: the wait is already
+    // "close enough", and a sub-tick delay would only add jitter without a visible effect.
     return w > minTime * 0.1 ? w : 0;
 };
 /**
@@ -59,21 +65,26 @@ const getRightTime = (start, minTime) => {
  * If an already-aborted signal is supplied the promise rejects immediately; otherwise
  * aborting before the delay elapses clears the timer and rejects with the abort reason.
  *
- * @param time Delay in milliseconds.
+ * @param ms Delay in milliseconds; must not be negative. Values above 2147483647 (~24.8 days)
+ *           overflow the timer and fire on the next tick — a `setTimeout` limitation.
  * @param abort Optional signal used to cancel the delay.
  * @returns A promise that resolves when the delay elapses.
+ * @throws {Error} When `ms` is negative.
  */
-function delay(time, abort) {
+function delay(ms, abort) {
+    if (ms < 0)
+        throw new Error("Invalid delay value.");
     return new Promise((resolve, reject) => {
         abort?.throwIfAborted();
         const onAbort = () => {
             clearTimeout(timer);
-            reject(abort?.reason);
+            // `onAbort` only runs once the listener has fired, which means `abort` exists.
+            reject(abort.reason);
         };
         const timer = setTimeout(() => {
             abort?.removeEventListener("abort", onAbort);
             resolve();
-        }, time);
+        }, ms);
         abort?.addEventListener("abort", onAbort, { once: true });
     });
 }
@@ -86,32 +97,48 @@ function delay(time, abort) {
  *
  * @typeParam T Resolved value type of the wrapped promise.
  * @param promise Promise to guard with a timeout.
- * @param timeout Timeout in milliseconds; must be greater than `0`.
+ * @param ms Timeout in milliseconds; must be greater than `0`. Values above 2147483647
+ *           (~24.8 days) overflow the timer and fire on the next tick — a `setTimeout` limitation.
  * @param abort Optional signal used to cancel the wait.
  * @returns A promise mirroring `promise` unless the timeout or abort fires first.
- * @throws {Error} When `timeout` is not greater than `0`.
+ * @throws {Error} When `ms` is not greater than `0`.
  */
-function timeout(promise, timeout, abort) {
-    if (timeout <= 0)
+function timeout(promise, ms, abort) {
+    if (ms <= 0)
         throw new Error("Invalid timeout value.");
+    // Own controller so the `delay` timer can be torn down once the race is decided,
+    // independently of the caller's `abort`.
+    const timer = new AbortController();
+    // Wins the race only by timing out (rejects with TimeoutError). If the timer is cancelled
+    // instead — the guarded work settled, or the caller aborted — `delay` rejects, and we turn
+    // that into a never-settling promise so `expire` simply stands aside: the race never produces
+    // a stray rejection that nobody is listening for.
+    const expire = delay(ms, timer.signal).then(() => Promise.reject(new TimeoutError()), () => new Promise(() => { }));
+    return abortable(Promise.race([promise, expire]), abort)
+        .finally(() => timer.abort());
+}
+/**
+ * Makes *waiting* for a promise abortable: rejects with the signal's reason on abort.
+ * Does not stop the underlying work the promise performs.
+ *
+ * If no signal is supplied the promise is awaited as-is. An already-aborted signal rejects
+ * immediately; otherwise the abort listener is removed once the promise settles.
+ *
+ * @typeParam T Resolved value type of the wrapped promise.
+ * @param promise Promise (or thenable) whose wait should become abortable.
+ * @param abort Optional signal used to cancel the wait.
+ * @returns A promise mirroring `promise` unless the abort fires first.
+ */
+function abortable(promise, abort) {
+    if (!abort)
+        return Promise.resolve(promise);
+    if (abort.aborted)
+        return Promise.reject(abort.reason);
     return new Promise((resolve, reject) => {
-        abort?.throwIfAborted();
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(abort?.reason);
-        };
-        const timer = setTimeout(() => {
-            abort?.removeEventListener("abort", onAbort);
-            reject(new TimeoutError());
-        }, timeout);
-        abort?.addEventListener("abort", onAbort, { once: true });
-        promise
-            .then(result => resolve(result))
-            .catch(reason => reject(reason))
-            .finally(() => {
-            clearTimeout(timer);
-            abort?.removeEventListener("abort", onAbort);
-        });
+        const onAbort = () => reject(abort.reason);
+        abort.addEventListener("abort", onAbort, { once: true });
+        const cleanup = () => abort.removeEventListener("abort", onAbort);
+        Promise.resolve(promise).then(v => { cleanup(); resolve(v); }, e => { cleanup(); reject(e); });
     });
 }
 /** Thrown by {@link timeout} when the time limit is exceeded. */
@@ -123,6 +150,7 @@ class TimeoutError extends Error {
 }
 
 exports.TimeoutError = TimeoutError;
+exports.abortable = abortable;
 exports.delay = delay;
 exports.minWait = minWait;
 exports.minWaitAsync = minWaitAsync;

package/dist/cjs/helpers/func.js.map

@@ -1 +1 @@
-{"version":3,"file":"func.js","sources":["../../../../source/helpers/func.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"func.js","sources":["../../../../source/helpers/func.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;AAUG;AACH,MAAM,OAAO,GAAG,CAAC,IAA8B,EAAE,OAAgB,KAAI;AACpE,IAAA,IAAI,CAAC,OAAO;AACX,QAAA,OAAO,IAAI;AAEZ,IAAA,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE;AAE5B,IAAA,MAAM,GAAG,GAAG,CAAC,GAAG,IAAW,KAAI;QAC9B,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC;AAClD,QAAA,IAAI,SAAS;AACZ,YAAA,UAAU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,SAAS,CAAC;;AAE1C,YAAA,IAAI,CAAC,GAAG,IAAI,CAAC;AACf,IAAA,CAAC;AAED,IAAA,OAAO,GAAG;AACX;AAEA;;;;;;;;;;;;;;;AAeG;AACH,eAAe,YAAY,CAAoB,IAA4B,EAAE,OAAgB,EAAE,KAAmB,EAAA;IACjH,KAAK,EAAE,cAAc,EAAE;AAEvB,IAAA,IAAI,CAAC,OAAO;QACX,OAAO,IAAI,EAAE;AAEd,IAAA,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE;AAC5B,IAAA,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE;IAE3B,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC;AAClD,IAAA,IAAI,SAAS;AACZ,QAAA,MAAM,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC;AAE9B,IAAA,OAAO,MAAM;AACd;AAEA;AACA,MAAM,YAAY,GAAG,CAAC,KAAa,EAAE,OAAe,KAAI;AACvD,IAAA,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE;IAC7B,MAAM,CAAC,GAAG,OAAO,IAAI,UAAU,GAAG,KAAK,CAAC;;;AAIxC,IAAA,OAAO,CAAC,GAAG,OAAO,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;AAWG;AACH,SAAS,KAAK,CAAC,EAAU,EAAE,KAAmB,EAAA;IAC7C,IAAI,EAAE,GAAG,CAAC;AACT,QAAA,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC;IAExC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,KAAI;QAC5C,KAAK,EAAE,cAAc,EAAE;QAEvB,MAAM,OAAO,GAAG,MAAK;YACpB,YAAY,CAAC,KAAK,CAAC;;AAEnB,YAAA,MAAM,CAAC,KAAM,CAAC,MAAM,CAAC;AACtB,QAAA,CAAC;AAED,QAAA,MAAM,KAAK,GAAG,UAAU,CAAC,MAAK;AAC7B,YAAA,KAAK,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;AAC5C,YAAA,OAAO,EAAE;QACV,CAAC,EAAE,EAAE,CAAC;AAEN,QAAA,KAAK,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC1D,IAAA,CAAC,CAAC;AACH;AAEA;;;;;;;;;;;;;;AAcG;AACH,SAAS,OAAO,CAAc,OAAmB,EAAE,EAAU,EAAE,KAAmB,EAAA;IACjF,IAAI,EAAE,IAAI,CAAC;AACV,QAAA,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC;;;AAI1C,IAAA,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE;;;;;AAMnC,IAAA,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAC1C,MAAM,OAAO,CAAC,MAAM,CAAI,IAAI,YAAY,EAAE,CAAC,EAC3C,MAAM,IAAI,OAAO,CAAI,QAA0D,CAAC,CAAC,CACjF;AAED,IAAA,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK;SACrD,OAAO,CAAC,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;AAC/B;AAEA;;;;;;;;;;;AAWG;AACH,SAAS,SAAS,CAAI,OAAuB,EAAE,KAAmB,EAAA;AACjE,IAAA,IAAI,CAAC,KAAK;AACT,QAAA,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;IAEhC,IAAI,KAAK,CAAC,OAAO;QAChB,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;IAEpC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,KAAI;QACzC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;AAC1C,QAAA,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAExD,QAAA,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC;AACjE,QAAA,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAC5B,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAC/B,CAAC,IAAG,EAAG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC9B;AACF,IAAA,CAAC,CAAC;AACH;AAEA;AACM,MAAO,YAAa,SAAQ,KAAK,CAAA;AACtC,IAAA,WAAA,GAAA;QACC,KAAK,CAAC,SAAS,CAAC;AAChB,QAAA,IAAI,CAAC,IAAI,GAAG,cAAc;IAC3B;AACA;;;;;;;;;"}

package/dist/cjs/polyfill.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Runtime polyfills for `AbortSignal`, installed only when the host lacks them:
+ * `AbortSignal.prototype.throwIfAborted`, `AbortSignal.timeout` and `AbortSignal.any`.
+ *
+ * Import for its side effect — there are no exports:
+ *
+ * ```TypeScript
+ * import "@brandup/ui-helpers/polyfill";
+ * ```
+ *
+ * Types already ship with the TypeScript `ESNext` lib; this module only fills in the
+ * implementations missing in older runtimes, matching the standard behaviour.
+ */
+if (typeof AbortSignal.prototype.throwIfAborted !== "function") {
+    AbortSignal.prototype.throwIfAborted = function () {
+        if (this.aborted)
+            throw this.reason;
+    };
+}
+if (typeof AbortSignal.timeout !== "function") {
+    AbortSignal.timeout = (milliseconds) => {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(new DOMException("The operation timed out.", "TimeoutError")), milliseconds);
+        return controller.signal;
+    };
+}
+if (typeof AbortSignal.any !== "function") {
+    AbortSignal.any = (signals) => {
+        const controller = new AbortController();
+        for (const signal of signals) {
+            // If one is already aborted, the combined signal aborts immediately with its reason.
+            if (signal.aborted) {
+                controller.abort(signal.reason);
+                break;
+            }
+            // Tying each listener to the combined signal removes them all once it aborts — no leak.
+            signal.addEventListener("abort", () => controller.abort(signal.reason), { signal: controller.signal });
+        }
+        return controller.signal;
+    };
+}
+//# sourceMappingURL=polyfill.js.map

package/dist/cjs/polyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polyfill.js","sources":["../../../source/polyfill.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;AAYG;AAEH,IAAI,OAAO,WAAW,CAAC,SAAS,CAAC,cAAc,KAAK,UAAU,EAAE;AAC/D,IAAA,WAAW,CAAC,SAAS,CAAC,cAAc,GAAG,YAAA;QACtC,IAAI,IAAI,CAAC,OAAO;YACf,MAAM,IAAI,CAAC,MAAM;AACnB,IAAA,CAAC;AACF;AAEA,IAAI,OAAO,WAAW,CAAC,OAAO,KAAK,UAAU,EAAE;AAC9C,IAAA,WAAW,CAAC,OAAO,GAAG,CAAC,YAAoB,KAAiB;AAC3D,QAAA,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE;AACxC,QAAA,UAAU,CAAC,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,0BAA0B,EAAE,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC;QAC9G,OAAO,UAAU,CAAC,MAAM;AACzB,IAAA,CAAC;AACF;AAEA,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,EAAE;AAC1C,IAAA,WAAW,CAAC,GAAG,GAAG,CAAC,OAAsB,KAAiB;AACzD,QAAA,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE;AAExC,QAAA,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE;;AAE7B,YAAA,IAAI,MAAM,CAAC,OAAO,EAAE;AACnB,gBAAA,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC/B;YACD;;YAGA,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;QACvG;QAEA,OAAO,UAAU,CAAC,MAAM;AACzB,IAAA,CAAC;AACF;;"}

package/dist/mjs/helpers/func.js

@@ -29,13 +29,17 @@ const minWait = (func, minTime) => {
  * Useful for keeping spinners/loading states visible for a minimum duration. If `minTime`
  * is omitted or falsy, `func` is awaited and its result returned without padding.
  *
+ * An already-aborted signal rejects immediately, before `func` runs; aborting later cancels
+ * the padding delay (but not `func` itself, which can't be cancelled here).
+ *
  * @typeParam TResult Result type produced by `func`.
  * @param func Factory returning the promise to await.
  * @param minTime Minimum total duration in milliseconds.
- * @param abort Optional signal used to cancel the padding delay.
+ * @param abort Optional signal used to cancel the wait.
  * @returns The result produced by `func`.
  */
 async function minWaitAsync(func, minTime, abort) {
+    abort?.throwIfAborted();
     if (!minTime)
         return func();
     const beginTime = Date.now();
@@ -49,6 +53,8 @@ async function minWaitAsync(func, minTime, abort) {
 const getRightTime = (start, minTime) => {
     const finishTime = Date.now();
     const w = minTime - (finishTime - start);
+    // Skip padding when the leftover is within 10% of `minTime`: the wait is already
+    // "close enough", and a sub-tick delay would only add jitter without a visible effect.
     return w > minTime * 0.1 ? w : 0;
 };
 /**
@@ -57,21 +63,26 @@ const getRightTime = (start, minTime) => {
  * If an already-aborted signal is supplied the promise rejects immediately; otherwise
  * aborting before the delay elapses clears the timer and rejects with the abort reason.
  *
- * @param time Delay in milliseconds.
+ * @param ms Delay in milliseconds; must not be negative. Values above 2147483647 (~24.8 days)
+ *           overflow the timer and fire on the next tick — a `setTimeout` limitation.
  * @param abort Optional signal used to cancel the delay.
  * @returns A promise that resolves when the delay elapses.
+ * @throws {Error} When `ms` is negative.
  */
-function delay(time, abort) {
+function delay(ms, abort) {
+    if (ms < 0)
+        throw new Error("Invalid delay value.");
     return new Promise((resolve, reject) => {
         abort?.throwIfAborted();
         const onAbort = () => {
             clearTimeout(timer);
-            reject(abort?.reason);
+            // `onAbort` only runs once the listener has fired, which means `abort` exists.
+            reject(abort.reason);
         };
         const timer = setTimeout(() => {
             abort?.removeEventListener("abort", onAbort);
             resolve();
-        }, time);
+        }, ms);
         abort?.addEventListener("abort", onAbort, { once: true });
     });
 }
@@ -84,32 +95,48 @@ function delay(time, abort) {
  *
  * @typeParam T Resolved value type of the wrapped promise.
  * @param promise Promise to guard with a timeout.
- * @param timeout Timeout in milliseconds; must be greater than `0`.
+ * @param ms Timeout in milliseconds; must be greater than `0`. Values above 2147483647
+ *           (~24.8 days) overflow the timer and fire on the next tick — a `setTimeout` limitation.
  * @param abort Optional signal used to cancel the wait.
  * @returns A promise mirroring `promise` unless the timeout or abort fires first.
- * @throws {Error} When `timeout` is not greater than `0`.
+ * @throws {Error} When `ms` is not greater than `0`.
  */
-function timeout(promise, timeout, abort) {
-    if (timeout <= 0)
+function timeout(promise, ms, abort) {
+    if (ms <= 0)
         throw new Error("Invalid timeout value.");
+    // Own controller so the `delay` timer can be torn down once the race is decided,
+    // independently of the caller's `abort`.
+    const timer = new AbortController();
+    // Wins the race only by timing out (rejects with TimeoutError). If the timer is cancelled
+    // instead — the guarded work settled, or the caller aborted — `delay` rejects, and we turn
+    // that into a never-settling promise so `expire` simply stands aside: the race never produces
+    // a stray rejection that nobody is listening for.
+    const expire = delay(ms, timer.signal).then(() => Promise.reject(new TimeoutError()), () => new Promise(() => { }));
+    return abortable(Promise.race([promise, expire]), abort)
+        .finally(() => timer.abort());
+}
+/**
+ * Makes *waiting* for a promise abortable: rejects with the signal's reason on abort.
+ * Does not stop the underlying work the promise performs.
+ *
+ * If no signal is supplied the promise is awaited as-is. An already-aborted signal rejects
+ * immediately; otherwise the abort listener is removed once the promise settles.
+ *
+ * @typeParam T Resolved value type of the wrapped promise.
+ * @param promise Promise (or thenable) whose wait should become abortable.
+ * @param abort Optional signal used to cancel the wait.
+ * @returns A promise mirroring `promise` unless the abort fires first.
+ */
+function abortable(promise, abort) {
+    if (!abort)
+        return Promise.resolve(promise);
+    if (abort.aborted)
+        return Promise.reject(abort.reason);
     return new Promise((resolve, reject) => {
-        abort?.throwIfAborted();
-        const onAbort = () => {
-            clearTimeout(timer);
-            reject(abort?.reason);
-        };
-        const timer = setTimeout(() => {
-            abort?.removeEventListener("abort", onAbort);
-            reject(new TimeoutError());
-        }, timeout);
-        abort?.addEventListener("abort", onAbort, { once: true });
-        promise
-            .then(result => resolve(result))
-            .catch(reason => reject(reason))
-            .finally(() => {
-            clearTimeout(timer);
-            abort?.removeEventListener("abort", onAbort);
-        });
+        const onAbort = () => reject(abort.reason);
+        abort.addEventListener("abort", onAbort, { once: true });
+        const cleanup = () => abort.removeEventListener("abort", onAbort);
+        Promise.resolve(promise).then(v => { cleanup(); resolve(v); }, e => { cleanup(); reject(e); });
     });
 }
 /** Thrown by {@link timeout} when the time limit is exceeded. */
@@ -120,5 +147,5 @@ class TimeoutError extends Error {
     }
 }
 
-export { TimeoutError, delay, minWait, minWaitAsync, timeout };
+export { TimeoutError, abortable, delay, minWait, minWaitAsync, timeout };
 //# sourceMappingURL=func.js.map

package/dist/mjs/helpers/func.js.map

@@ -1 +1 @@
-{"version":3,"file":"func.js","sources":["../../../../source/helpers/func.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"func.js","sources":["../../../../source/helpers/func.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/mjs/polyfill.js

@@ -0,0 +1,42 @@
+/**
+ * Runtime polyfills for `AbortSignal`, installed only when the host lacks them:
+ * `AbortSignal.prototype.throwIfAborted`, `AbortSignal.timeout` and `AbortSignal.any`.
+ *
+ * Import for its side effect — there are no exports:
+ *
+ * ```TypeScript
+ * import "@brandup/ui-helpers/polyfill";
+ * ```
+ *
+ * Types already ship with the TypeScript `ESNext` lib; this module only fills in the
+ * implementations missing in older runtimes, matching the standard behaviour.
+ */
+if (typeof AbortSignal.prototype.throwIfAborted !== "function") {
+    AbortSignal.prototype.throwIfAborted = function () {
+        if (this.aborted)
+            throw this.reason;
+    };
+}
+if (typeof AbortSignal.timeout !== "function") {
+    AbortSignal.timeout = (milliseconds) => {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(new DOMException("The operation timed out.", "TimeoutError")), milliseconds);
+        return controller.signal;
+    };
+}
+if (typeof AbortSignal.any !== "function") {
+    AbortSignal.any = (signals) => {
+        const controller = new AbortController();
+        for (const signal of signals) {
+            // If one is already aborted, the combined signal aborts immediately with its reason.
+            if (signal.aborted) {
+                controller.abort(signal.reason);
+                break;
+            }
+            // Tying each listener to the combined signal removes them all once it aborts — no leak.
+            signal.addEventListener("abort", () => controller.abort(signal.reason), { signal: controller.signal });
+        }
+        return controller.signal;
+    };
+}
+//# sourceMappingURL=polyfill.js.map

package/dist/mjs/polyfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polyfill.js","sources":["../../../source/polyfill.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;AAYG;AAEH,IAAI,OAAO,WAAW,CAAC,SAAS,CAAC,cAAc,KAAK,UAAU,EAAE;AAC/D,IAAA,WAAW,CAAC,SAAS,CAAC,cAAc,GAAG,YAAA;QACtC,IAAI,IAAI,CAAC,OAAO;YACf,MAAM,IAAI,CAAC,MAAM;AACnB,IAAA,CAAC;AACF;AAEA,IAAI,OAAO,WAAW,CAAC,OAAO,KAAK,UAAU,EAAE;AAC9C,IAAA,WAAW,CAAC,OAAO,GAAG,CAAC,YAAoB,KAAiB;AAC3D,QAAA,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE;AACxC,QAAA,UAAU,CAAC,MAAM,UAAU,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,0BAA0B,EAAE,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC;QAC9G,OAAO,UAAU,CAAC,MAAM;AACzB,IAAA,CAAC;AACF;AAEA,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,EAAE;AAC1C,IAAA,WAAW,CAAC,GAAG,GAAG,CAAC,OAAsB,KAAiB;AACzD,QAAA,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE;AAExC,QAAA,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE;;AAE7B,YAAA,IAAI,MAAM,CAAC,OAAO,EAAE;AACnB,gBAAA,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC/B;YACD;;YAGA,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;QACvG;QAEA,OAAO,UAAU,CAAC,MAAM;AACzB,IAAA,CAAC;AACF"}

package/dist/polyfill.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/types.d.ts

@@ -74,10 +74,13 @@ declare const minWait: (func: (...args: any[]) => void, minTime?: number) => (..
  * Useful for keeping spinners/loading states visible for a minimum duration. If `minTime`
  * is omitted or falsy, `func` is awaited and its result returned without padding.
  *
+ * An already-aborted signal rejects immediately, before `func` runs; aborting later cancels
+ * the padding delay (but not `func` itself, which can't be cancelled here).
+ *
  * @typeParam TResult Result type produced by `func`.
  * @param func Factory returning the promise to await.
  * @param minTime Minimum total duration in milliseconds.
- * @param abort Optional signal used to cancel the padding delay.
+ * @param abort Optional signal used to cancel the wait.
  * @returns The result produced by `func`.
  */
 declare function minWaitAsync<TResult = unknown>(func: () => Promise<TResult>, minTime?: number, abort?: AbortSignal): Promise<TResult>;
@@ -87,11 +90,13 @@ declare function minWaitAsync<TResult = unknown>(func: () => Promise<TResult>, m
  * If an already-aborted signal is supplied the promise rejects immediately; otherwise
  * aborting before the delay elapses clears the timer and rejects with the abort reason.
  *
- * @param time Delay in milliseconds.
+ * @param ms Delay in milliseconds; must not be negative. Values above 2147483647 (~24.8 days)
+ *           overflow the timer and fire on the next tick — a `setTimeout` limitation.
  * @param abort Optional signal used to cancel the delay.
  * @returns A promise that resolves when the delay elapses.
+ * @throws {Error} When `ms` is negative.
  */
-declare function delay(time: number, abort?: AbortSignal): Promise<void>;
+declare function delay(ms: number, abort?: AbortSignal): Promise<void>;
 /**
  * Races a promise against a timeout.
  *
@@ -101,12 +106,26 @@ declare function delay(time: number, abort?: AbortSignal): Promise<void>;
  *
  * @typeParam T Resolved value type of the wrapped promise.
  * @param promise Promise to guard with a timeout.
- * @param timeout Timeout in milliseconds; must be greater than `0`.
+ * @param ms Timeout in milliseconds; must be greater than `0`. Values above 2147483647
+ *           (~24.8 days) overflow the timer and fire on the next tick — a `setTimeout` limitation.
  * @param abort Optional signal used to cancel the wait.
  * @returns A promise mirroring `promise` unless the timeout or abort fires first.
- * @throws {Error} When `timeout` is not greater than `0`.
+ * @throws {Error} When `ms` is not greater than `0`.
+ */
+declare function timeout<T = unknown>(promise: Promise<T>, ms: number, abort?: AbortSignal): Promise<T>;
+/**
+ * Makes *waiting* for a promise abortable: rejects with the signal's reason on abort.
+ * Does not stop the underlying work the promise performs.
+ *
+ * If no signal is supplied the promise is awaited as-is. An already-aborted signal rejects
+ * immediately; otherwise the abort listener is removed once the promise settles.
+ *
+ * @typeParam T Resolved value type of the wrapped promise.
+ * @param promise Promise (or thenable) whose wait should become abortable.
+ * @param abort Optional signal used to cancel the wait.
+ * @returns A promise mirroring `promise` unless the abort fires first.
  */
-declare function timeout<T = unknown>(promise: Promise<T>, timeout: number, abort?: AbortSignal): Promise<T>;
+declare function abortable<T>(promise: PromiseLike<T>, abort?: AbortSignal): Promise<T>;
 /** Thrown by {@link timeout} when the time limit is exceeded. */
 declare class TimeoutError extends Error {
     constructor();
@@ -114,6 +133,7 @@ declare class TimeoutError extends Error {
 
 type func_TimeoutError = TimeoutError;
 declare const func_TimeoutError: typeof TimeoutError;
+declare const func_abortable: typeof abortable;
 declare const func_delay: typeof delay;
 declare const func_minWait: typeof minWait;
 declare const func_minWaitAsync: typeof minWaitAsync;
@@ -121,6 +141,7 @@ declare const func_timeout: typeof timeout;
 declare namespace func {
   export {
     func_TimeoutError as TimeoutError,
+    func_abortable as abortable,
     func_delay as delay,
     func_minWait as minWait,
     func_minWaitAsync as minWaitAsync,

package/package.json

@@ -22,16 +22,24 @@
     "email": "it@brandup.online"
   },
   "license": "Apache-2.0",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "main": "dist/cjs/index.js",
   "module": "dist/mjs/index.js",
   "types": "dist/types.d.ts",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/cjs/polyfill.js",
+    "./dist/mjs/polyfill.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/types.d.ts",
       "import": "./dist/mjs/index.js",
       "require": "./dist/cjs/index.js"
+    },
+    "./polyfill": {
+      "types": "./dist/polyfill.d.ts",
+      "import": "./dist/mjs/polyfill.js",
+      "require": "./dist/cjs/polyfill.js"
     }
   },
   "files": [