yummies 7.11.0 → 7.13.0

package/README.md

@@ -15,94 +15,12 @@
 [bundlephobia-image]: https://badgen.net/bundlephobia/minzip/yummies
 
 
-Yummies - a set of various utilities for JavaScript projects with open source code, designed to simplify the execution of common tasks and increase performance. This project provides developers with powerful and easy-to-use functions that can be easily integrated into any JavaScript code.
-
-## [yummies/async](src/async.ts)  
-Utilities for working with asynchronous code  
-
-## [yummies/common](src/common.ts)  
-All other utilities without groupping  
-
-## [yummies/cookie](src/cookie.ts)  
-Utilities for working with cookies  
-
-## [yummies/css](src/css.ts)  
-Utilities for working with CSS  
-
-## [yummies/date-time](src/date-time.ts)  
-Utilities for working with dates and times (based on dayjs)  
-
-## [yummies/device](src/device.ts)  
-Utilities for working with devices  
-
-## [yummies/html](src/html.ts)  
-Utilities for working with HTML  
-
-## [yummies/id](src/id.ts)  
-Utilities for working with identifiers  
-
-## [yummies/imports](src/imports.ts)  
-Utilities for working with module imports  
-
-## [yummies/math](src/math.ts)  
-Utilities for working with devices  
-
-## [yummies/media](src/media.ts)  
-Utilities for working with media (image, canvas and blob)  
-
-## [yummies/ms](src/ms.ts)  
-Utilities for working with milliseconds  
-
-## [yummies/price](src/price.ts)  
-Utilities for working with monetary values (formatting)  
-
-## [yummies/sound](src/sound.ts)  
-Utilities for working with sound  
-
-## [yummies/storage](src/storage.ts)  
-Utilities for working with storage (localStorage, sessionStorage)  
-
-## [yummies/text](src/text.ts)  
-Utilities for working with text  
-
-## [yummies/type-guard](src/type-guard.ts)  
-Utility for type checks  
-
-## [yummies/vibrate](src/vibrate.ts)  
-Utilities for working with vibrate api  
-
-## [yummies/types.global](src/types.ts)  
-## [yummies/types](src/types.ts)  
-TypeScript utility types that simplify writing TypeScript code.  
-They can be imported globally using the `d.ts` file, embedding it in the environment  
-```ts
-import 'yummies/types.global';
-```  
-Or specified in `tsconfig.json` in the `"types"` field    
-```json
-{
-  "compilerOptions": {
-    "types": [
-      "yummies/types.global"
-    ],
-    "target": "...blabla",
-    ...
-  }
-  ...
-}
-```
-Alternatively, you can use the "library" approach, where you need exported types.  
-For this, you can use the `yummies` or `yummies/types` import.
-
-```ts
-import { AnyObject } from 'yummies';
-```
-
-
-## [yummies/complex](src/complex/index.ts)  
-
-Additional set of complex utilities  
+`yummies` - a set of various utilities for JavaScript projects with open source code,
+          designed to simplify the execution of common tasks and increase performance.
+          This project provides developers with powerful and easy-to-use functions
+          that can be easily integrated into any JavaScript code.  
 
+## [Read the docs →](https://js2me.github.io/yummies/)   
 
 ## Migration from 5.x to 6.x   
 

package/async.cjs

@@ -1,60 +1,191 @@
-"use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const sleep = (time = 0, signal) => new Promise((resolve, reject) => {
-  if (signal) {
-    const abortListener = () => {
-      clearTimeout(timerId);
-      reject(signal?.reason);
-    };
-    const timerId = setTimeout(() => {
-      signal.removeEventListener("abort", abortListener);
-      resolve();
-    }, time);
-    signal.addEventListener("abort", abortListener, { once: true });
-  } else {
-    setTimeout(resolve, time);
-  }
+//#region src/async.ts
+/**
+* ---header-docs-section---
+* # yummies/async
+*
+* ## Description
+*
+* Helpers for asynchronous control flow: delays, cancellable waits, scheduling on the next frame,
+* and small utilities around `requestAnimationFrame` and `queueMicrotask`. They complement native
+* `Promise`/`AbortSignal` patterns and keep timing logic easy to test and tree-shake per call site.
+* Import only what you need from `yummies/async` so bundlers can drop unused helpers.
+*
+* ## Usage
+*
+* ```ts
+* import { sleep } from "yummies/async";
+* ```
+*/
+/**
+* Returns a promise that resolves after `time` milliseconds.
+*
+* When `signal` is passed and becomes aborted before the delay elapses, the promise
+* rejects with `signal.reason` (same as native `fetch` / `AbortController` usage).
+* The timeout is cleared on abort so no resolve happens after cancellation.
+*
+* @param time - Delay in milliseconds. Defaults to `0` (next macrotask tick, same idea as `setTimeout(0)`).
+* @param signal - Optional `AbortSignal` to cancel the wait early.
+* @returns A promise that resolves with `void` when the delay completes, or rejects if aborted.
+*
+* @example
+* Basic pause in an async function:
+* ```ts
+* await sleep(250);
+* console.log('after 250ms');
+* ```
+*
+* @example
+* Cancellable delay tied to component unmount or user action:
+* ```ts
+* const ac = new AbortController();
+* try {
+*   await sleep(5000, ac.signal);
+* } catch (e) {
+*   // aborted — e is signal.reason
+* }
+* ac.abort('user cancelled');
+* ```
+*/
+var sleep = (time = 0, signal) => new Promise((resolve, reject) => {
+	if (signal) {
+		const abortListener = () => {
+			clearTimeout(timerId);
+			reject(signal?.reason);
+		};
+		const timerId = setTimeout(() => {
+			signal.removeEventListener("abort", abortListener);
+			resolve();
+		}, time);
+		signal.addEventListener("abort", abortListener, { once: true });
+	} else setTimeout(resolve, time);
 });
-const waitAsync = async (ms = 1e3) => new Promise((resolve) => setTimeout(resolve, ms));
-const endlessRAF = (quitFunction, asMicrotask) => {
-  if (quitFunction()) return;
-  const raf = () => requestAnimationFrame(() => endlessRAF(quitFunction, asMicrotask));
-  if (asMicrotask) {
-    queueMicrotask(raf);
-  } else {
-    raf();
-  }
+/**
+* Creates a promise that resolves after the specified number of milliseconds.
+*
+* @deprecated Use `sleep` instead.
+* @param ms Delay in milliseconds.
+* @returns Promise
+*/
+var waitAsync = async (ms = 1e3) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Runs a loop driven by `requestAnimationFrame`: on each frame, `quitFunction` is called first.
+* If it returns a truthy value, the loop stops and no further frames are scheduled.
+* If it returns falsy or nothing, the next frame is scheduled recursively.
+*
+* Use this for per-frame work (animations, layout reads after paint) without managing
+* `cancelAnimationFrame` manually — returning `true` from `quitFunction` is the exit condition.
+*
+* When `asMicrotask` is `true`, scheduling the next RAF is deferred with `queueMicrotask`
+* so other microtasks can run before the frame is requested (useful when you need to
+* batch DOM updates or let reactive frameworks flush first).
+*
+* @param quitFunction - Invoked each animation frame. Return `true` to stop the loop.
+* @param asMicrotask - If `true`, wrap the `requestAnimationFrame` call in `queueMicrotask`.
+*
+* @example
+* Stop after 60 frames (~1s at 60Hz):
+* ```ts
+* let frames = 0;
+* endlessRAF(() => {
+*   frames++;
+*   updateSomething(frames);
+*   return frames >= 60;
+* });
+* ```
+*
+* @example
+* Run until an element is removed or a flag is set:
+* ```ts
+* let running = true;
+* endlessRAF(() => {
+*   if (!running || !document.body.contains(el)) return true;
+*   draw(el);
+* }, true);
+* ```
+*/
+var endlessRAF = (quitFunction, asMicrotask) => {
+	if (quitFunction()) return;
+	const raf = () => requestAnimationFrame(() => endlessRAF(quitFunction, asMicrotask));
+	if (asMicrotask) queueMicrotask(raf);
+	else raf();
 };
+/**
+* Like `setTimeout`, but if `signal` aborts before the delay fires, the timer is cleared
+* and `callback` is never run. If the callback runs normally, the abort listener is removed.
+*
+* Does nothing special if `signal` is omitted — behaves like a plain timeout.
+*
+* @param callback - Function to run once after `delayInMs` (same as `setTimeout` callback).
+* @param delayInMs - Milliseconds to wait. Passed through to `setTimeout` (browser/Node semantics apply).
+* @param signal - When aborted, clears the pending timeout so `callback` is not invoked.
+*
+* @example
+* ```ts
+* const controller = new AbortController();
+* setAbortableTimeout(() => console.log('done'), 500, controller.signal);
+* // later: controller.abort(); // timeout cancelled, log never runs
+* ```
+*
+* @example
+* Zero-delay scheduling that can still be cancelled before the macrotask runs:
+* ```ts
+* const ac = new AbortController();
+* setAbortableTimeout(() => startIntro(), 0, ac.signal);
+* // e.g. on teardown: ac.abort();
+* ```
+*/
 function setAbortableTimeout(callback, delayInMs, signal) {
-  let internalTimer = null;
-  const handleAbort = () => {
-    if (internalTimer == null) {
-      return;
-    }
-    clearTimeout(internalTimer);
-    internalTimer = null;
-  };
-  signal?.addEventListener("abort", handleAbort, { once: true });
-  internalTimer = setTimeout(() => {
-    signal?.removeEventListener("abort", handleAbort);
-    callback();
-  }, delayInMs);
+	let internalTimer = null;
+	const handleAbort = () => {
+		if (internalTimer == null) return;
+		clearTimeout(internalTimer);
+		internalTimer = null;
+	};
+	signal?.addEventListener("abort", handleAbort, { once: true });
+	internalTimer = setTimeout(() => {
+		signal?.removeEventListener("abort", handleAbort);
+		callback();
+	}, delayInMs);
 }
+/**
+* Like `setInterval`, but when `signal` aborts, the interval is cleared with `clearInterval`
+* and `callback` stops being called. If `signal` is omitted, behaves like a normal interval
+* (you must clear it yourself).
+*
+* @param callback - Invoked every `delayInMs` milliseconds until aborted or cleared.
+* @param delayInMs - Interval period in milliseconds (same as `setInterval`).
+* @param signal - Aborting stops the interval and removes the abort listener path from keeping work alive.
+*
+* @example
+* ```ts
+* const controller = new AbortController();
+* setAbortableInterval(() => console.log('tick'), 1000, controller.signal);
+* // stop: controller.abort();
+* ```
+*
+* @example
+* ```ts
+* const ac = new AbortController();
+* setAbortableInterval(syncStatus, 30_000, ac.signal);
+* window.addEventListener('beforeunload', () => ac.abort());
+* ```
+*/
 function setAbortableInterval(callback, delayInMs, signal) {
-  let timer = null;
-  const handleAbort = () => {
-    if (timer == null) {
-      return;
-    }
-    clearInterval(timer);
-    timer = null;
-  };
-  signal?.addEventListener("abort", handleAbort, { once: true });
-  timer = setInterval(callback, delayInMs);
+	let timer = null;
+	const handleAbort = () => {
+		if (timer == null) return;
+		clearInterval(timer);
+		timer = null;
+	};
+	signal?.addEventListener("abort", handleAbort, { once: true });
+	timer = setInterval(callback, delayInMs);
 }
+//#endregion
 exports.endlessRAF = endlessRAF;
 exports.setAbortableInterval = setAbortableInterval;
 exports.setAbortableTimeout = setAbortableTimeout;
 exports.sleep = sleep;
 exports.waitAsync = waitAsync;
-//# sourceMappingURL=async.cjs.map
+
+//# sourceMappingURL=async.cjs.map

package/async.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"async.cjs","sources":["../src/async.ts"],"sourcesContent":["/**\n * Creates a promise that resolves after the specified number of milliseconds.\n *\n * @param time Delay in milliseconds.\n * @returns Promise\n */\nexport const sleep = (time: number = 0, signal?: AbortSignal) =>\n  new Promise<void>((resolve, reject) => {\n    if (signal) {\n      const abortListener = () => {\n        clearTimeout(timerId);\n        reject(signal?.reason);\n      };\n      const timerId = setTimeout(() => {\n        signal.removeEventListener('abort', abortListener);\n        resolve();\n      }, time);\n      signal.addEventListener('abort', abortListener, { once: true });\n    } else {\n      setTimeout(resolve, time);\n    }\n  });\n\n/**\n * Creates a promise that resolves after the specified number of milliseconds.\n *\n * @deprecated Use `sleep` instead.\n * @param ms Delay in milliseconds.\n * @returns Promise\n */\nexport const waitAsync = async (ms = 1000) =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Repeatedly schedules `requestAnimationFrame` until `quitFunction` returns `true`.\n *\n * @param quitFunction Function executed on each animation frame.\n * @param asMicrotask Additionally wraps the RAF scheduling in `queueMicrotask`.\n * @returns void\n */\nexport const endlessRAF = (\n  quitFunction: () => boolean | void,\n  asMicrotask?: boolean,\n) => {\n  if (quitFunction()) return;\n\n  const raf = () =>\n    requestAnimationFrame(() => endlessRAF(quitFunction, asMicrotask));\n\n  if (asMicrotask) {\n    queueMicrotask(raf);\n  } else {\n    raf();\n  }\n};\n\nexport function setAbortableTimeout(\n  callback: VoidFunction,\n  delayInMs?: number,\n  signal?: AbortSignal,\n) {\n  let internalTimer: number | null = null;\n\n  const handleAbort = () => {\n    if (internalTimer == null) {\n      return;\n    }\n    clearTimeout(internalTimer);\n    internalTimer = null;\n  };\n\n  signal?.addEventListener('abort', handleAbort, { once: true });\n\n  internalTimer = setTimeout(() => {\n    signal?.removeEventListener('abort', handleAbort);\n    callback();\n  }, delayInMs);\n}\n\nexport function setAbortableInterval(\n  callback: VoidFunction,\n  delayInMs?: number,\n  signal?: AbortSignal,\n) {\n  let timer: number | null = null;\n\n  const handleAbort = () => {\n    if (timer == null) {\n      return;\n    }\n    clearInterval(timer);\n    timer = null;\n  };\n\n  signal?.addEventListener('abort', handleAbort, { once: true });\n\n  timer = setInterval(callback, delayInMs);\n}\n"],"names":[],"mappings":";;AAMO,MAAM,QAAQ,CAAC,OAAe,GAAG,WACtC,IAAI,QAAc,CAAC,SAAS,WAAW;AACrC,MAAI,QAAQ;AACV,UAAM,gBAAgB,MAAM;AAC1B,mBAAa,OAAO;AACpB,aAAO,QAAQ,MAAM;AAAA,IACvB;AACA,UAAM,UAAU,WAAW,MAAM;AAC/B,aAAO,oBAAoB,SAAS,aAAa;AACjD,cAAA;AAAA,IACF,GAAG,IAAI;AACP,WAAO,iBAAiB,SAAS,eAAe,EAAE,MAAM,MAAM;AAAA,EAChE,OAAO;AACL,eAAW,SAAS,IAAI;AAAA,EAC1B;AACF,CAAC;AASI,MAAM,YAAY,OAAO,KAAK,QACnC,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AAS3C,MAAM,aAAa,CACxB,cACA,gBACG;AACH,MAAI,eAAgB;AAEpB,QAAM,MAAM,MACV,sBAAsB,MAAM,WAAW,cAAc,WAAW,CAAC;AAEnE,MAAI,aAAa;AACf,mBAAe,GAAG;AAAA,EACpB,OAAO;AACL,QAAA;AAAA,EACF;AACF;AAEO,SAAS,oBACd,UACA,WACA,QACA;AACA,MAAI,gBAA+B;AAEnC,QAAM,cAAc,MAAM;AACxB,QAAI,iBAAiB,MAAM;AACzB;AAAA,IACF;AACA,iBAAa,aAAa;AAC1B,oBAAgB;AAAA,EAClB;AAEA,UAAQ,iBAAiB,SAAS,aAAa,EAAE,MAAM,MAAM;AAE7D,kBAAgB,WAAW,MAAM;AAC/B,YAAQ,oBAAoB,SAAS,WAAW;AAChD,aAAA;AAAA,EACF,GAAG,SAAS;AACd;AAEO,SAAS,qBACd,UACA,WACA,QACA;AACA,MAAI,QAAuB;AAE3B,QAAM,cAAc,MAAM;AACxB,QAAI,SAAS,MAAM;AACjB;AAAA,IACF;AACA,kBAAc,KAAK;AACnB,YAAQ;AAAA,EACV;AAEA,UAAQ,iBAAiB,SAAS,aAAa,EAAE,MAAM,MAAM;AAE7D,UAAQ,YAAY,UAAU,SAAS;AACzC;;;;;;"}
+{"version":3,"file":"async.cjs","names":[],"sources":["../src/async.ts"],"sourcesContent":["/**\n * ---header-docs-section---\n * # yummies/async\n *\n * ## Description\n *\n * Helpers for asynchronous control flow: delays, cancellable waits, scheduling on the next frame,\n * and small utilities around `requestAnimationFrame` and `queueMicrotask`. They complement native\n * `Promise`/`AbortSignal` patterns and keep timing logic easy to test and tree-shake per call site.\n * Import only what you need from `yummies/async` so bundlers can drop unused helpers.\n *\n * ## Usage\n *\n * ```ts\n * import { sleep } from \"yummies/async\";\n * ```\n */\n\n/**\n * Returns a promise that resolves after `time` milliseconds.\n *\n * When `signal` is passed and becomes aborted before the delay elapses, the promise\n * rejects with `signal.reason` (same as native `fetch` / `AbortController` usage).\n * The timeout is cleared on abort so no resolve happens after cancellation.\n *\n * @param time - Delay in milliseconds. Defaults to `0` (next macrotask tick, same idea as `setTimeout(0)`).\n * @param signal - Optional `AbortSignal` to cancel the wait early.\n * @returns A promise that resolves with `void` when the delay completes, or rejects if aborted.\n *\n * @example\n * Basic pause in an async function:\n * ```ts\n * await sleep(250);\n * console.log('after 250ms');\n * ```\n *\n * @example\n * Cancellable delay tied to component unmount or user action:\n * ```ts\n * const ac = new AbortController();\n * try {\n *   await sleep(5000, ac.signal);\n * } catch (e) {\n *   // aborted — e is signal.reason\n * }\n * ac.abort('user cancelled');\n * ```\n */\nexport const sleep = (time: number = 0, signal?: AbortSignal) =>\n  new Promise<void>((resolve, reject) => {\n    if (signal) {\n      const abortListener = () => {\n        clearTimeout(timerId);\n        reject(signal?.reason);\n      };\n      const timerId = setTimeout(() => {\n        signal.removeEventListener('abort', abortListener);\n        resolve();\n      }, time);\n      signal.addEventListener('abort', abortListener, { once: true });\n    } else {\n      setTimeout(resolve, time);\n    }\n  });\n\n/**\n * Creates a promise that resolves after the specified number of milliseconds.\n *\n * @deprecated Use `sleep` instead.\n * @param ms Delay in milliseconds.\n * @returns Promise\n */\nexport const waitAsync = async (ms = 1000) =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/**\n * Runs a loop driven by `requestAnimationFrame`: on each frame, `quitFunction` is called first.\n * If it returns a truthy value, the loop stops and no further frames are scheduled.\n * If it returns falsy or nothing, the next frame is scheduled recursively.\n *\n * Use this for per-frame work (animations, layout reads after paint) without managing\n * `cancelAnimationFrame` manually — returning `true` from `quitFunction` is the exit condition.\n *\n * When `asMicrotask` is `true`, scheduling the next RAF is deferred with `queueMicrotask`\n * so other microtasks can run before the frame is requested (useful when you need to\n * batch DOM updates or let reactive frameworks flush first).\n *\n * @param quitFunction - Invoked each animation frame. Return `true` to stop the loop.\n * @param asMicrotask - If `true`, wrap the `requestAnimationFrame` call in `queueMicrotask`.\n *\n * @example\n * Stop after 60 frames (~1s at 60Hz):\n * ```ts\n * let frames = 0;\n * endlessRAF(() => {\n *   frames++;\n *   updateSomething(frames);\n *   return frames >= 60;\n * });\n * ```\n *\n * @example\n * Run until an element is removed or a flag is set:\n * ```ts\n * let running = true;\n * endlessRAF(() => {\n *   if (!running || !document.body.contains(el)) return true;\n *   draw(el);\n * }, true);\n * ```\n */\nexport const endlessRAF = (\n  quitFunction: () => boolean | void,\n  asMicrotask?: boolean,\n) => {\n  if (quitFunction()) return;\n\n  const raf = () =>\n    requestAnimationFrame(() => endlessRAF(quitFunction, asMicrotask));\n\n  if (asMicrotask) {\n    queueMicrotask(raf);\n  } else {\n    raf();\n  }\n};\n\n/**\n * Like `setTimeout`, but if `signal` aborts before the delay fires, the timer is cleared\n * and `callback` is never run. If the callback runs normally, the abort listener is removed.\n *\n * Does nothing special if `signal` is omitted — behaves like a plain timeout.\n *\n * @param callback - Function to run once after `delayInMs` (same as `setTimeout` callback).\n * @param delayInMs - Milliseconds to wait. Passed through to `setTimeout` (browser/Node semantics apply).\n * @param signal - When aborted, clears the pending timeout so `callback` is not invoked.\n *\n * @example\n * ```ts\n * const controller = new AbortController();\n * setAbortableTimeout(() => console.log('done'), 500, controller.signal);\n * // later: controller.abort(); // timeout cancelled, log never runs\n * ```\n *\n * @example\n * Zero-delay scheduling that can still be cancelled before the macrotask runs:\n * ```ts\n * const ac = new AbortController();\n * setAbortableTimeout(() => startIntro(), 0, ac.signal);\n * // e.g. on teardown: ac.abort();\n * ```\n */\nexport function setAbortableTimeout(\n  callback: VoidFunction,\n  delayInMs?: number,\n  signal?: AbortSignal,\n) {\n  let internalTimer: number | null = null;\n\n  const handleAbort = () => {\n    if (internalTimer == null) {\n      return;\n    }\n    clearTimeout(internalTimer);\n    internalTimer = null;\n  };\n\n  signal?.addEventListener('abort', handleAbort, { once: true });\n\n  internalTimer = setTimeout(() => {\n    signal?.removeEventListener('abort', handleAbort);\n    callback();\n  }, delayInMs);\n}\n\n/**\n * Like `setInterval`, but when `signal` aborts, the interval is cleared with `clearInterval`\n * and `callback` stops being called. If `signal` is omitted, behaves like a normal interval\n * (you must clear it yourself).\n *\n * @param callback - Invoked every `delayInMs` milliseconds until aborted or cleared.\n * @param delayInMs - Interval period in milliseconds (same as `setInterval`).\n * @param signal - Aborting stops the interval and removes the abort listener path from keeping work alive.\n *\n * @example\n * ```ts\n * const controller = new AbortController();\n * setAbortableInterval(() => console.log('tick'), 1000, controller.signal);\n * // stop: controller.abort();\n * ```\n *\n * @example\n * ```ts\n * const ac = new AbortController();\n * setAbortableInterval(syncStatus, 30_000, ac.signal);\n * window.addEventListener('beforeunload', () => ac.abort());\n * ```\n */\nexport function setAbortableInterval(\n  callback: VoidFunction,\n  delayInMs?: number,\n  signal?: AbortSignal,\n) {\n  let timer: number | null = null;\n\n  const handleAbort = () => {\n    if (timer == null) {\n      return;\n    }\n    clearInterval(timer);\n    timer = null;\n  };\n\n  signal?.addEventListener('abort', handleAbort, { once: true });\n\n  timer = setInterval(callback, delayInMs);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,SAAS,OAAe,GAAG,WACtC,IAAI,SAAe,SAAS,WAAW;AACrC,KAAI,QAAQ;EACV,MAAM,sBAAsB;AAC1B,gBAAa,QAAQ;AACrB,UAAO,QAAQ,OAAO;;EAExB,MAAM,UAAU,iBAAiB;AAC/B,UAAO,oBAAoB,SAAS,cAAc;AAClD,YAAS;KACR,KAAK;AACR,SAAO,iBAAiB,SAAS,eAAe,EAAE,MAAM,MAAM,CAAC;OAE/D,YAAW,SAAS,KAAK;EAE3B;;;;;;;;AASJ,IAAa,YAAY,OAAO,KAAK,QACnC,IAAI,SAAS,YAAY,WAAW,SAAS,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCnD,IAAa,cACX,cACA,gBACG;AACH,KAAI,cAAc,CAAE;CAEpB,MAAM,YACJ,4BAA4B,WAAW,cAAc,YAAY,CAAC;AAEpE,KAAI,YACF,gBAAe,IAAI;KAEnB,MAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BT,SAAgB,oBACd,UACA,WACA,QACA;CACA,IAAI,gBAA+B;CAEnC,MAAM,oBAAoB;AACxB,MAAI,iBAAiB,KACnB;AAEF,eAAa,cAAc;AAC3B,kBAAgB;;AAGlB,SAAQ,iBAAiB,SAAS,aAAa,EAAE,MAAM,MAAM,CAAC;AAE9D,iBAAgB,iBAAiB;AAC/B,UAAQ,oBAAoB,SAAS,YAAY;AACjD,YAAU;IACT,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;AA0Bf,SAAgB,qBACd,UACA,WACA,QACA;CACA,IAAI,QAAuB;CAE3B,MAAM,oBAAoB;AACxB,MAAI,SAAS,KACX;AAEF,gBAAc,MAAM;AACpB,UAAQ;;AAGV,SAAQ,iBAAiB,SAAS,aAAa,EAAE,MAAM,MAAM,CAAC;AAE9D,SAAQ,YAAY,UAAU,UAAU"}

package/async.d.ts

@@ -1,8 +1,49 @@
 /**
- * Creates a promise that resolves after the specified number of milliseconds.
+ * ---header-docs-section---
+ * # yummies/async
  *
- * @param time Delay in milliseconds.
- * @returns Promise
+ * ## Description
+ *
+ * Helpers for asynchronous control flow: delays, cancellable waits, scheduling on the next frame,
+ * and small utilities around `requestAnimationFrame` and `queueMicrotask`. They complement native
+ * `Promise`/`AbortSignal` patterns and keep timing logic easy to test and tree-shake per call site.
+ * Import only what you need from `yummies/async` so bundlers can drop unused helpers.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { sleep } from "yummies/async";
+ * ```
+ */
+/**
+ * Returns a promise that resolves after `time` milliseconds.
+ *
+ * When `signal` is passed and becomes aborted before the delay elapses, the promise
+ * rejects with `signal.reason` (same as native `fetch` / `AbortController` usage).
+ * The timeout is cleared on abort so no resolve happens after cancellation.
+ *
+ * @param time - Delay in milliseconds. Defaults to `0` (next macrotask tick, same idea as `setTimeout(0)`).
+ * @param signal - Optional `AbortSignal` to cancel the wait early.
+ * @returns A promise that resolves with `void` when the delay completes, or rejects if aborted.
+ *
+ * @example
+ * Basic pause in an async function:
+ * ```ts
+ * await sleep(250);
+ * console.log('after 250ms');
+ * ```
+ *
+ * @example
+ * Cancellable delay tied to component unmount or user action:
+ * ```ts
+ * const ac = new AbortController();
+ * try {
+ *   await sleep(5000, ac.signal);
+ * } catch (e) {
+ *   // aborted — e is signal.reason
+ * }
+ * ac.abort('user cancelled');
+ * ```
  */
 declare const sleep: (time?: number, signal?: AbortSignal) => Promise<void>;
 /**
@@ -14,14 +55,91 @@ declare const sleep: (time?: number, signal?: AbortSignal) => Promise<void>;
  */
 declare const waitAsync: (ms?: number) => Promise<unknown>;
 /**
- * Repeatedly schedules `requestAnimationFrame` until `quitFunction` returns `true`.
+ * Runs a loop driven by `requestAnimationFrame`: on each frame, `quitFunction` is called first.
+ * If it returns a truthy value, the loop stops and no further frames are scheduled.
+ * If it returns falsy or nothing, the next frame is scheduled recursively.
+ *
+ * Use this for per-frame work (animations, layout reads after paint) without managing
+ * `cancelAnimationFrame` manually — returning `true` from `quitFunction` is the exit condition.
+ *
+ * When `asMicrotask` is `true`, scheduling the next RAF is deferred with `queueMicrotask`
+ * so other microtasks can run before the frame is requested (useful when you need to
+ * batch DOM updates or let reactive frameworks flush first).
  *
- * @param quitFunction Function executed on each animation frame.
- * @param asMicrotask Additionally wraps the RAF scheduling in `queueMicrotask`.
- * @returns void
+ * @param quitFunction - Invoked each animation frame. Return `true` to stop the loop.
+ * @param asMicrotask - If `true`, wrap the `requestAnimationFrame` call in `queueMicrotask`.
+ *
+ * @example
+ * Stop after 60 frames (~1s at 60Hz):
+ * ```ts
+ * let frames = 0;
+ * endlessRAF(() => {
+ *   frames++;
+ *   updateSomething(frames);
+ *   return frames >= 60;
+ * });
+ * ```
+ *
+ * @example
+ * Run until an element is removed or a flag is set:
+ * ```ts
+ * let running = true;
+ * endlessRAF(() => {
+ *   if (!running || !document.body.contains(el)) return true;
+ *   draw(el);
+ * }, true);
+ * ```
  */
 declare const endlessRAF: (quitFunction: () => boolean | void, asMicrotask?: boolean) => void;
+/**
+ * Like `setTimeout`, but if `signal` aborts before the delay fires, the timer is cleared
+ * and `callback` is never run. If the callback runs normally, the abort listener is removed.
+ *
+ * Does nothing special if `signal` is omitted — behaves like a plain timeout.
+ *
+ * @param callback - Function to run once after `delayInMs` (same as `setTimeout` callback).
+ * @param delayInMs - Milliseconds to wait. Passed through to `setTimeout` (browser/Node semantics apply).
+ * @param signal - When aborted, clears the pending timeout so `callback` is not invoked.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ * setAbortableTimeout(() => console.log('done'), 500, controller.signal);
+ * // later: controller.abort(); // timeout cancelled, log never runs
+ * ```
+ *
+ * @example
+ * Zero-delay scheduling that can still be cancelled before the macrotask runs:
+ * ```ts
+ * const ac = new AbortController();
+ * setAbortableTimeout(() => startIntro(), 0, ac.signal);
+ * // e.g. on teardown: ac.abort();
+ * ```
+ */
 declare function setAbortableTimeout(callback: VoidFunction, delayInMs?: number, signal?: AbortSignal): void;
+/**
+ * Like `setInterval`, but when `signal` aborts, the interval is cleared with `clearInterval`
+ * and `callback` stops being called. If `signal` is omitted, behaves like a normal interval
+ * (you must clear it yourself).
+ *
+ * @param callback - Invoked every `delayInMs` milliseconds until aborted or cleared.
+ * @param delayInMs - Interval period in milliseconds (same as `setInterval`).
+ * @param signal - Aborting stops the interval and removes the abort listener path from keeping work alive.
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController();
+ * setAbortableInterval(() => console.log('tick'), 1000, controller.signal);
+ * // stop: controller.abort();
+ * ```
+ *
+ * @example
+ * ```ts
+ * const ac = new AbortController();
+ * setAbortableInterval(syncStatus, 30_000, ac.signal);
+ * window.addEventListener('beforeunload', () => ac.abort());
+ * ```
+ */
 declare function setAbortableInterval(callback: VoidFunction, delayInMs?: number, signal?: AbortSignal): void;
 
 export { endlessRAF, setAbortableInterval, setAbortableTimeout, sleep, waitAsync };