yummies 7.12.0 → 7.14.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/assert.cjs

@@ -0,0 +1,146 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_chunk = require("./chunk-CVq3Gv4J.cjs");
+let yummies_common = require("yummies/common");
+//#region src/assert/_exports.ts
+/**
+* ---header-docs-section---
+* # yummies/assert
+*
+* ## Description
+*
+* Runtime **assertions** for invariants, narrowing, and exhaustiveness. Helpers throw
+* {@link AssertionError} with an optional message (`string` or {@link MaybeFn}) so failing fast stays
+* explicit without a heavy assertion library. Use `assert.ok`, `assert.defined`, `assert.fail`, and
+* the rest on the namespace export from the package entry.
+*
+* ## Usage
+*
+* ```ts
+* import { assert } from "yummies/assert";
+*
+* assert.ok(user.id, "user id is required");
+* assert.defined(maybeName);
+* ```
+*/
+var _exports_exports = /* @__PURE__ */ require_chunk.__exportAll({
+	AssertionError: () => AssertionError,
+	defined: () => defined,
+	fail: () => fail,
+	instanceOf: () => instanceOf,
+	invariant: () => invariant,
+	never: () => unreachable,
+	notNull: () => notNull,
+	notUndefined: () => notUndefined,
+	ok: () => ok,
+	unreachable: () => unreachable
+});
+/**
+* Error thrown by assertion helpers in this module.
+*/
+var AssertionError = class extends Error {
+	name = "AssertionError";
+};
+function resolveAssertMessage(message, fallback) {
+	if (message === void 0) return fallback;
+	return (0, yummies_common.callFunction)(message);
+}
+/**
+* Throws when `condition` is falsy; narrows the type when it is truthy.
+*
+* @param condition Value treated as a boolean guard.
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* assert.ok(user.id, "user id is required");
+* ```
+*/
+function ok(condition, message) {
+	if (!condition) throw new AssertionError(resolveAssertMessage(message, "Assertion failed"));
+}
+/**
+* Same as {@link ok}; common alias for internal invariants (e.g. after optional checks).
+*/
+var invariant = ok;
+/**
+* Throws when the value is `null` or `undefined`; otherwise narrows away nullish.
+*
+* @param value Possibly nullish value.
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* assert.defined(maybeName, "name must be present");
+* ```
+*/
+function defined(value, message) {
+	if (value == null) throw new AssertionError(resolveAssertMessage(message, "Expected a defined value"));
+}
+/**
+* Throws when the value is `null`; allows `undefined` unless combined with other checks.
+*
+* @param value Value that may be `null`.
+* @param message Optional message or lazy message factory.
+*/
+function notNull(value, message) {
+	if (value === null) throw new AssertionError(resolveAssertMessage(message, "Expected a non-null value"));
+}
+/**
+* Throws when the value is `undefined`.
+*
+* @param value Value that may be `undefined`.
+* @param message Optional message or lazy message factory.
+*/
+function notUndefined(value, message) {
+	if (value === void 0) throw new AssertionError(resolveAssertMessage(message, "Expected a defined value"));
+}
+/**
+* Always throws; use for branches that must be impossible or as a typed “abort”.
+*
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* function parse(kind: "a" | "b") {
+*   if (kind === "a") return 1;
+*   if (kind === "b") return 2;
+*   assert.fail("unreachable");
+* }
+* ```
+*/
+function fail(message) {
+	throw new AssertionError(resolveAssertMessage(message, "Unreachable"));
+}
+/**
+* Exhaustiveness helper: call with a `never` value when all union cases are handled.
+*
+* @param value Should be `never` when the type checker is satisfied.
+* @param message Optional message (this path always throws, so a lazy factory is unnecessary).
+*/
+function unreachable(value, message) {
+	throw new AssertionError(resolveAssertMessage(message, `Unexpected value: ${String(value)}`));
+}
+/**
+* Throws when `value` is not an instance of `ctor`.
+*
+* @param value Value to check.
+* @param ctor Constructor used with `instanceof`.
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* assert.instanceOf(el, HTMLElement, "expected a DOM element");
+* ```
+*/
+function instanceOf(value, ctor, message) {
+	if (!(value instanceof ctor)) throw new AssertionError(resolveAssertMessage(message, `Expected instance of ${ctor.name}`));
+}
+//#endregion
+Object.defineProperty(exports, "assert", {
+	enumerable: true,
+	get: function() {
+		return _exports_exports;
+	}
+});
+
+//# sourceMappingURL=assert.cjs.map

package/assert.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.cjs","names":[],"sources":["../src/assert/_exports.ts"],"sourcesContent":["/**\n * ---header-docs-section---\n * # yummies/assert\n *\n * ## Description\n *\n * Runtime **assertions** for invariants, narrowing, and exhaustiveness. Helpers throw\n * {@link AssertionError} with an optional message (`string` or {@link MaybeFn}) so failing fast stays\n * explicit without a heavy assertion library. Use `assert.ok`, `assert.defined`, `assert.fail`, and\n * the rest on the namespace export from the package entry.\n *\n * ## Usage\n *\n * ```ts\n * import { assert } from \"yummies/assert\";\n *\n * assert.ok(user.id, \"user id is required\");\n * assert.defined(maybeName);\n * ```\n */\n\nimport { callFunction } from 'yummies/common';\nimport type { Maybe, MaybeFn } from 'yummies/types';\n\n/**\n * Error thrown by assertion helpers in this module.\n */\nexport class AssertionError extends Error {\n  override name = 'AssertionError';\n}\n\nfunction resolveAssertMessage(\n  message: MaybeFn<string> | undefined,\n  fallback: string,\n): string {\n  if (message === undefined) {\n    return fallback;\n  }\n  return callFunction(message);\n}\n\n/**\n * Throws when `condition` is falsy; narrows the type when it is truthy.\n *\n * @param condition Value treated as a boolean guard.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.ok(user.id, \"user id is required\");\n * ```\n */\nexport function ok(\n  condition: unknown,\n  message?: MaybeFn<string>,\n): asserts condition {\n  if (!condition) {\n    throw new AssertionError(resolveAssertMessage(message, 'Assertion failed'));\n  }\n}\n\n/**\n * Same as {@link ok}; common alias for internal invariants (e.g. after optional checks).\n */\nexport const invariant: typeof ok = ok;\n\n/**\n * Throws when the value is `null` or `undefined`; otherwise narrows away nullish.\n *\n * @param value Possibly nullish value.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.defined(maybeName, \"name must be present\");\n * ```\n */\nexport function defined<T>(\n  value: Maybe<T>,\n  message?: MaybeFn<string>,\n): asserts value is NonNullable<T> {\n  if (value == null) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a defined value'),\n    );\n  }\n}\n\n/**\n * Throws when the value is `null`; allows `undefined` unless combined with other checks.\n *\n * @param value Value that may be `null`.\n * @param message Optional message or lazy message factory.\n */\nexport function notNull<T>(\n  value: T | null,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (value === null) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a non-null value'),\n    );\n  }\n}\n\n/**\n * Throws when the value is `undefined`.\n *\n * @param value Value that may be `undefined`.\n * @param message Optional message or lazy message factory.\n */\nexport function notUndefined<T>(\n  value: T | undefined,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (value === undefined) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a defined value'),\n    );\n  }\n}\n\n/**\n * Always throws; use for branches that must be impossible or as a typed “abort”.\n *\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * function parse(kind: \"a\" | \"b\") {\n *   if (kind === \"a\") return 1;\n *   if (kind === \"b\") return 2;\n *   assert.fail(\"unreachable\");\n * }\n * ```\n */\nexport function fail(message?: MaybeFn<string>): never {\n  throw new AssertionError(resolveAssertMessage(message, 'Unreachable'));\n}\n\n/**\n * Exhaustiveness helper: call with a `never` value when all union cases are handled.\n *\n * @param value Should be `never` when the type checker is satisfied.\n * @param message Optional message (this path always throws, so a lazy factory is unnecessary).\n */\nexport function unreachable(value: never, message?: string): never {\n  throw new AssertionError(\n    resolveAssertMessage(message, `Unexpected value: ${String(value)}`),\n  );\n}\n\n/**\n * Alias for {@link unreachable} (common name in switch exhaustiveness snippets).\n */\nexport { unreachable as never };\n\n/**\n * Throws when `value` is not an instance of `ctor`.\n *\n * @param value Value to check.\n * @param ctor Constructor used with `instanceof`.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.instanceOf(el, HTMLElement, \"expected a DOM element\");\n * ```\n */\nexport function instanceOf<T>(\n  value: unknown,\n  ctor: abstract new (...args: never[]) => T,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (!(value instanceof ctor)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, `Expected instance of ${ctor.name}`),\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,IAAa,iBAAb,cAAoC,MAAM;CACxC,OAAgB;;AAGlB,SAAS,qBACP,SACA,UACQ;AACR,KAAI,YAAY,KAAA,EACd,QAAO;AAET,SAAA,GAAA,eAAA,cAAoB,QAAQ;;;;;;;;;;;;;AAc9B,SAAgB,GACd,WACA,SACmB;AACnB,KAAI,CAAC,UACH,OAAM,IAAI,eAAe,qBAAqB,SAAS,mBAAmB,CAAC;;;;;AAO/E,IAAa,YAAuB;;;;;;;;;;;;AAapC,SAAgB,QACd,OACA,SACiC;AACjC,KAAI,SAAS,KACX,OAAM,IAAI,eACR,qBAAqB,SAAS,2BAA2B,CAC1D;;;;;;;;AAUL,SAAgB,QACd,OACA,SACoB;AACpB,KAAI,UAAU,KACZ,OAAM,IAAI,eACR,qBAAqB,SAAS,4BAA4B,CAC3D;;;;;;;;AAUL,SAAgB,aACd,OACA,SACoB;AACpB,KAAI,UAAU,KAAA,EACZ,OAAM,IAAI,eACR,qBAAqB,SAAS,2BAA2B,CAC1D;;;;;;;;;;;;;;;;AAkBL,SAAgB,KAAK,SAAkC;AACrD,OAAM,IAAI,eAAe,qBAAqB,SAAS,cAAc,CAAC;;;;;;;;AASxE,SAAgB,YAAY,OAAc,SAAyB;AACjE,OAAM,IAAI,eACR,qBAAqB,SAAS,qBAAqB,OAAO,MAAM,GAAG,CACpE;;;;;;;;;;;;;;AAoBH,SAAgB,WACd,OACA,MACA,SACoB;AACpB,KAAI,EAAE,iBAAiB,MACrB,OAAM,IAAI,eACR,qBAAqB,SAAS,wBAAwB,KAAK,OAAO,CACnE"}

package/assert.d.ts

@@ -0,0 +1,134 @@
+import { Maybe, MaybeFn } from 'yummies/types';
+
+/**
+ * ---header-docs-section---
+ * # yummies/assert
+ *
+ * ## Description
+ *
+ * Runtime **assertions** for invariants, narrowing, and exhaustiveness. Helpers throw
+ * {@link AssertionError} with an optional message (`string` or {@link MaybeFn}) so failing fast stays
+ * explicit without a heavy assertion library. Use `assert.ok`, `assert.defined`, `assert.fail`, and
+ * the rest on the namespace export from the package entry.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { assert } from "yummies/assert";
+ *
+ * assert.ok(user.id, "user id is required");
+ * assert.defined(maybeName);
+ * ```
+ */
+
+/**
+ * Error thrown by assertion helpers in this module.
+ */
+declare class AssertionError extends Error {
+    name: string;
+}
+/**
+ * Throws when `condition` is falsy; narrows the type when it is truthy.
+ *
+ * @param condition Value treated as a boolean guard.
+ * @param message Optional message or lazy message factory.
+ *
+ * @example
+ * ```ts
+ * assert.ok(user.id, "user id is required");
+ * ```
+ */
+declare function ok(condition: unknown, message?: MaybeFn<string>): asserts condition;
+/**
+ * Same as {@link ok}; common alias for internal invariants (e.g. after optional checks).
+ */
+declare const invariant: typeof ok;
+/**
+ * Throws when the value is `null` or `undefined`; otherwise narrows away nullish.
+ *
+ * @param value Possibly nullish value.
+ * @param message Optional message or lazy message factory.
+ *
+ * @example
+ * ```ts
+ * assert.defined(maybeName, "name must be present");
+ * ```
+ */
+declare function defined<T>(value: Maybe<T>, message?: MaybeFn<string>): asserts value is NonNullable<T>;
+/**
+ * Throws when the value is `null`; allows `undefined` unless combined with other checks.
+ *
+ * @param value Value that may be `null`.
+ * @param message Optional message or lazy message factory.
+ */
+declare function notNull<T>(value: T | null, message?: MaybeFn<string>): asserts value is T;
+/**
+ * Throws when the value is `undefined`.
+ *
+ * @param value Value that may be `undefined`.
+ * @param message Optional message or lazy message factory.
+ */
+declare function notUndefined<T>(value: T | undefined, message?: MaybeFn<string>): asserts value is T;
+/**
+ * Always throws; use for branches that must be impossible or as a typed “abort”.
+ *
+ * @param message Optional message or lazy message factory.
+ *
+ * @example
+ * ```ts
+ * function parse(kind: "a" | "b") {
+ *   if (kind === "a") return 1;
+ *   if (kind === "b") return 2;
+ *   assert.fail("unreachable");
+ * }
+ * ```
+ */
+declare function fail(message?: MaybeFn<string>): never;
+/**
+ * Exhaustiveness helper: call with a `never` value when all union cases are handled.
+ *
+ * @param value Should be `never` when the type checker is satisfied.
+ * @param message Optional message (this path always throws, so a lazy factory is unnecessary).
+ */
+declare function unreachable(value: never, message?: string): never;
+
+/**
+ * Throws when `value` is not an instance of `ctor`.
+ *
+ * @param value Value to check.
+ * @param ctor Constructor used with `instanceof`.
+ * @param message Optional message or lazy message factory.
+ *
+ * @example
+ * ```ts
+ * assert.instanceOf(el, HTMLElement, "expected a DOM element");
+ * ```
+ */
+declare function instanceOf<T>(value: unknown, ctor: abstract new (...args: never[]) => T, message?: MaybeFn<string>): asserts value is T;
+
+type _exports_AssertionError = AssertionError;
+declare const _exports_AssertionError: typeof AssertionError;
+declare const _exports_defined: typeof defined;
+declare const _exports_fail: typeof fail;
+declare const _exports_instanceOf: typeof instanceOf;
+declare const _exports_invariant: typeof invariant;
+declare const _exports_notNull: typeof notNull;
+declare const _exports_notUndefined: typeof notUndefined;
+declare const _exports_ok: typeof ok;
+declare const _exports_unreachable: typeof unreachable;
+declare namespace _exports {
+  export {
+    _exports_AssertionError as AssertionError,
+    _exports_defined as defined,
+    _exports_fail as fail,
+    _exports_instanceOf as instanceOf,
+    _exports_invariant as invariant,
+    unreachable as never,
+    _exports_notNull as notNull,
+    _exports_notUndefined as notUndefined,
+    _exports_ok as ok,
+    _exports_unreachable as unreachable,
+  };
+}
+
+export { _exports as assert };

package/assert.js

@@ -0,0 +1,140 @@
+import { n as __exportAll } from "./chunk-YKewjYmz.js";
+import { callFunction } from "yummies/common";
+//#region src/assert/_exports.ts
+/**
+* ---header-docs-section---
+* # yummies/assert
+*
+* ## Description
+*
+* Runtime **assertions** for invariants, narrowing, and exhaustiveness. Helpers throw
+* {@link AssertionError} with an optional message (`string` or {@link MaybeFn}) so failing fast stays
+* explicit without a heavy assertion library. Use `assert.ok`, `assert.defined`, `assert.fail`, and
+* the rest on the namespace export from the package entry.
+*
+* ## Usage
+*
+* ```ts
+* import { assert } from "yummies/assert";
+*
+* assert.ok(user.id, "user id is required");
+* assert.defined(maybeName);
+* ```
+*/
+var _exports_exports = /* @__PURE__ */ __exportAll({
+	AssertionError: () => AssertionError,
+	defined: () => defined,
+	fail: () => fail,
+	instanceOf: () => instanceOf,
+	invariant: () => invariant,
+	never: () => unreachable,
+	notNull: () => notNull,
+	notUndefined: () => notUndefined,
+	ok: () => ok,
+	unreachable: () => unreachable
+});
+/**
+* Error thrown by assertion helpers in this module.
+*/
+var AssertionError = class extends Error {
+	name = "AssertionError";
+};
+function resolveAssertMessage(message, fallback) {
+	if (message === void 0) return fallback;
+	return callFunction(message);
+}
+/**
+* Throws when `condition` is falsy; narrows the type when it is truthy.
+*
+* @param condition Value treated as a boolean guard.
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* assert.ok(user.id, "user id is required");
+* ```
+*/
+function ok(condition, message) {
+	if (!condition) throw new AssertionError(resolveAssertMessage(message, "Assertion failed"));
+}
+/**
+* Same as {@link ok}; common alias for internal invariants (e.g. after optional checks).
+*/
+var invariant = ok;
+/**
+* Throws when the value is `null` or `undefined`; otherwise narrows away nullish.
+*
+* @param value Possibly nullish value.
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* assert.defined(maybeName, "name must be present");
+* ```
+*/
+function defined(value, message) {
+	if (value == null) throw new AssertionError(resolveAssertMessage(message, "Expected a defined value"));
+}
+/**
+* Throws when the value is `null`; allows `undefined` unless combined with other checks.
+*
+* @param value Value that may be `null`.
+* @param message Optional message or lazy message factory.
+*/
+function notNull(value, message) {
+	if (value === null) throw new AssertionError(resolveAssertMessage(message, "Expected a non-null value"));
+}
+/**
+* Throws when the value is `undefined`.
+*
+* @param value Value that may be `undefined`.
+* @param message Optional message or lazy message factory.
+*/
+function notUndefined(value, message) {
+	if (value === void 0) throw new AssertionError(resolveAssertMessage(message, "Expected a defined value"));
+}
+/**
+* Always throws; use for branches that must be impossible or as a typed “abort”.
+*
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* function parse(kind: "a" | "b") {
+*   if (kind === "a") return 1;
+*   if (kind === "b") return 2;
+*   assert.fail("unreachable");
+* }
+* ```
+*/
+function fail(message) {
+	throw new AssertionError(resolveAssertMessage(message, "Unreachable"));
+}
+/**
+* Exhaustiveness helper: call with a `never` value when all union cases are handled.
+*
+* @param value Should be `never` when the type checker is satisfied.
+* @param message Optional message (this path always throws, so a lazy factory is unnecessary).
+*/
+function unreachable(value, message) {
+	throw new AssertionError(resolveAssertMessage(message, `Unexpected value: ${String(value)}`));
+}
+/**
+* Throws when `value` is not an instance of `ctor`.
+*
+* @param value Value to check.
+* @param ctor Constructor used with `instanceof`.
+* @param message Optional message or lazy message factory.
+*
+* @example
+* ```ts
+* assert.instanceOf(el, HTMLElement, "expected a DOM element");
+* ```
+*/
+function instanceOf(value, ctor, message) {
+	if (!(value instanceof ctor)) throw new AssertionError(resolveAssertMessage(message, `Expected instance of ${ctor.name}`));
+}
+//#endregion
+export { _exports_exports as assert };
+
+//# sourceMappingURL=assert.js.map

package/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","names":[],"sources":["../src/assert/_exports.ts"],"sourcesContent":["/**\n * ---header-docs-section---\n * # yummies/assert\n *\n * ## Description\n *\n * Runtime **assertions** for invariants, narrowing, and exhaustiveness. Helpers throw\n * {@link AssertionError} with an optional message (`string` or {@link MaybeFn}) so failing fast stays\n * explicit without a heavy assertion library. Use `assert.ok`, `assert.defined`, `assert.fail`, and\n * the rest on the namespace export from the package entry.\n *\n * ## Usage\n *\n * ```ts\n * import { assert } from \"yummies/assert\";\n *\n * assert.ok(user.id, \"user id is required\");\n * assert.defined(maybeName);\n * ```\n */\n\nimport { callFunction } from 'yummies/common';\nimport type { Maybe, MaybeFn } from 'yummies/types';\n\n/**\n * Error thrown by assertion helpers in this module.\n */\nexport class AssertionError extends Error {\n  override name = 'AssertionError';\n}\n\nfunction resolveAssertMessage(\n  message: MaybeFn<string> | undefined,\n  fallback: string,\n): string {\n  if (message === undefined) {\n    return fallback;\n  }\n  return callFunction(message);\n}\n\n/**\n * Throws when `condition` is falsy; narrows the type when it is truthy.\n *\n * @param condition Value treated as a boolean guard.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.ok(user.id, \"user id is required\");\n * ```\n */\nexport function ok(\n  condition: unknown,\n  message?: MaybeFn<string>,\n): asserts condition {\n  if (!condition) {\n    throw new AssertionError(resolveAssertMessage(message, 'Assertion failed'));\n  }\n}\n\n/**\n * Same as {@link ok}; common alias for internal invariants (e.g. after optional checks).\n */\nexport const invariant: typeof ok = ok;\n\n/**\n * Throws when the value is `null` or `undefined`; otherwise narrows away nullish.\n *\n * @param value Possibly nullish value.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.defined(maybeName, \"name must be present\");\n * ```\n */\nexport function defined<T>(\n  value: Maybe<T>,\n  message?: MaybeFn<string>,\n): asserts value is NonNullable<T> {\n  if (value == null) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a defined value'),\n    );\n  }\n}\n\n/**\n * Throws when the value is `null`; allows `undefined` unless combined with other checks.\n *\n * @param value Value that may be `null`.\n * @param message Optional message or lazy message factory.\n */\nexport function notNull<T>(\n  value: T | null,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (value === null) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a non-null value'),\n    );\n  }\n}\n\n/**\n * Throws when the value is `undefined`.\n *\n * @param value Value that may be `undefined`.\n * @param message Optional message or lazy message factory.\n */\nexport function notUndefined<T>(\n  value: T | undefined,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (value === undefined) {\n    throw new AssertionError(\n      resolveAssertMessage(message, 'Expected a defined value'),\n    );\n  }\n}\n\n/**\n * Always throws; use for branches that must be impossible or as a typed “abort”.\n *\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * function parse(kind: \"a\" | \"b\") {\n *   if (kind === \"a\") return 1;\n *   if (kind === \"b\") return 2;\n *   assert.fail(\"unreachable\");\n * }\n * ```\n */\nexport function fail(message?: MaybeFn<string>): never {\n  throw new AssertionError(resolveAssertMessage(message, 'Unreachable'));\n}\n\n/**\n * Exhaustiveness helper: call with a `never` value when all union cases are handled.\n *\n * @param value Should be `never` when the type checker is satisfied.\n * @param message Optional message (this path always throws, so a lazy factory is unnecessary).\n */\nexport function unreachable(value: never, message?: string): never {\n  throw new AssertionError(\n    resolveAssertMessage(message, `Unexpected value: ${String(value)}`),\n  );\n}\n\n/**\n * Alias for {@link unreachable} (common name in switch exhaustiveness snippets).\n */\nexport { unreachable as never };\n\n/**\n * Throws when `value` is not an instance of `ctor`.\n *\n * @param value Value to check.\n * @param ctor Constructor used with `instanceof`.\n * @param message Optional message or lazy message factory.\n *\n * @example\n * ```ts\n * assert.instanceOf(el, HTMLElement, \"expected a DOM element\");\n * ```\n */\nexport function instanceOf<T>(\n  value: unknown,\n  ctor: abstract new (...args: never[]) => T,\n  message?: MaybeFn<string>,\n): asserts value is T {\n  if (!(value instanceof ctor)) {\n    throw new AssertionError(\n      resolveAssertMessage(message, `Expected instance of ${ctor.name}`),\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,IAAa,iBAAb,cAAoC,MAAM;CACxC,OAAgB;;AAGlB,SAAS,qBACP,SACA,UACQ;AACR,KAAI,YAAY,KAAA,EACd,QAAO;AAET,QAAO,aAAa,QAAQ;;;;;;;;;;;;;AAc9B,SAAgB,GACd,WACA,SACmB;AACnB,KAAI,CAAC,UACH,OAAM,IAAI,eAAe,qBAAqB,SAAS,mBAAmB,CAAC;;;;;AAO/E,IAAa,YAAuB;;;;;;;;;;;;AAapC,SAAgB,QACd,OACA,SACiC;AACjC,KAAI,SAAS,KACX,OAAM,IAAI,eACR,qBAAqB,SAAS,2BAA2B,CAC1D;;;;;;;;AAUL,SAAgB,QACd,OACA,SACoB;AACpB,KAAI,UAAU,KACZ,OAAM,IAAI,eACR,qBAAqB,SAAS,4BAA4B,CAC3D;;;;;;;;AAUL,SAAgB,aACd,OACA,SACoB;AACpB,KAAI,UAAU,KAAA,EACZ,OAAM,IAAI,eACR,qBAAqB,SAAS,2BAA2B,CAC1D;;;;;;;;;;;;;;;;AAkBL,SAAgB,KAAK,SAAkC;AACrD,OAAM,IAAI,eAAe,qBAAqB,SAAS,cAAc,CAAC;;;;;;;;AASxE,SAAgB,YAAY,OAAc,SAAyB;AACjE,OAAM,IAAI,eACR,qBAAqB,SAAS,qBAAqB,OAAO,MAAM,GAAG,CACpE;;;;;;;;;;;;;;AAoBH,SAAgB,WACd,OACA,MACA,SACoB;AACpB,KAAI,EAAE,iBAAiB,MACrB,OAAM,IAAI,eACR,qBAAqB,SAAS,wBAAwB,KAAK,OAAO,CACnE"}

package/async.cjs

@@ -1,6 +1,23 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#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

package/async.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"async.cjs","names":[],"sources":["../src/async.ts"],"sourcesContent":["/**\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,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"}
+{"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,3 +1,20 @@
+/**
+ * ---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.
  *

package/async.js

@@ -1,5 +1,22 @@
 //#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