npm - yummies - Versions diffs - 7.12.0 → 7.14.0 - Mend

yummies 7.12.0 → 7.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (127) hide show

package/imports.cjs CHANGED Viewed

@@ -3,6 +3,22 @@ require("./chunk-CVq3Gv4J.cjs");
 let yummies_async = require("yummies/async");
 //#region src/imports.ts
 /**
+* ---header-docs-section---
+* # yummies/imports
+*
+* ## Description
+*
+* Patterns for **dynamic `import()`**: retry with backoff, unpacking `{ default }` from mixed ESM
+* shapes, and typed helpers around lazy-loaded modules. Ideal for code-split routes, optional panels,
+* and resilient loading when the network or CDN flakes without freezing the whole app.
+*
+* ## Usage
+*
+* ```ts
+* import { fetchLazyModule } from "yummies/imports";
+* ```
+*/
+/**
 * Lazily loads a module with retry support.
 *
 * @example

package/imports.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"imports.cjs","names":[],"sources":["../src/imports.ts"],"sourcesContent":["import { sleep } from 'yummies/async';\n\n/*\n Lazily loads a module with retry support.\n \n @example\n * ```ts\n * fetchLazyModule(() => import('./test.ts'), 3) // starts loading test.ts\n * // If loading test.ts fails, fetchLazyModule retries by calling fetchModule() again\n * // It retries as many times as specified by attempts (3 by default)\n * ```\n /\nexport const fetchLazyModule = async <T>(\n fetchModule: () => Promise<T>,\n attempts = 3,\n delay = 1000,\n): Promise<T> => {\n const attemptsArray = Array.from<typeof fetchModule>({\n length: attempts,\n }).fill(fetchModule);\n\n let lastError: null \| Error = null;\n\n for await (const attempt of attemptsArray) {\n try {\n if (lastError !== null) {\n await sleep(delay);\n }\n return await attempt();\n } catch (error) {\n lastError = error as Error;\n }\n }\n throw lastError;\n};\n\nexport type PackedAsyncModule<T> = Promise<T \| { default: T }>;\n\n/\n Resolves either a direct value or an asynchronously imported module and unwraps its `default` export.\n \n @example\n * ```ts\n * const component = await unpackAsyncModule(import('./Component.ts'));\n * ```\n */\nexport const unpackAsyncModule = async <T>(\n maybeModule: T \| PackedAsyncModule<T>,\n): Promise<T> => {\n if (maybeModule instanceof Promise) {\n const data = (await maybeModule) as any;\n\n if ((data as any).default) {\n return (data as any).default;\n } else {\n return data;\n }\n }\n\n return maybeModule;\n};\n"],"mappings":"~~;;;;;;;;;;;;;;AAYA~~,IAAa,kBAAkB,OAC7B,aACA,WAAW,GACX,QAAQ,QACO;CACf,MAAM,gBAAgB,MAAM,KAAyB,EACnD,QAAQ,UACT,CAAC,CAAC,KAAK,YAAY;CAEpB,IAAI,YAA0B;AAE9B,YAAW,MAAM,WAAW,cAC1B,KAAI;AACF,MAAI,cAAc,KAChB,QAAA,GAAA,cAAA,OAAY,MAAM;AAEpB,SAAO,MAAM,SAAS;UACf,OAAO;AACd,cAAY;;AAGhB,OAAM;;;;;;;;;;AAaR,IAAa,oBAAoB,OAC/B,gBACe;AACf,KAAI,uBAAuB,SAAS;EAClC,MAAM,OAAQ,MAAM;AAEpB,MAAK,KAAa,QAChB,QAAQ,KAAa;MAErB,QAAO;;AAIX,QAAO"}
1	+ {"version":3,"file":"imports.cjs","names":[],"sources":["../src/imports.ts"],"sourcesContent":["/*\n ---header-docs-section---\n * # yummies/imports\n \n ## Description\n \n Patterns for dynamic `import()`: retry with backoff, unpacking `{ default }` from mixed ESM\n * shapes, and typed helpers around lazy-loaded modules. Ideal for code-split routes, optional panels,\n * and resilient loading when the network or CDN flakes without freezing the whole app.\n \n ## Usage\n \n ```ts\n * import { fetchLazyModule } from \"yummies/imports\";\n * ```\n /\n\nimport { sleep } from 'yummies/async';\n\n/\n Lazily loads a module with retry support.\n \n @example\n * ```ts\n * fetchLazyModule(() => import('./test.ts'), 3) // starts loading test.ts\n * // If loading test.ts fails, fetchLazyModule retries by calling fetchModule() again\n * // It retries as many times as specified by attempts (3 by default)\n * ```\n /\nexport const fetchLazyModule = async <T>(\n fetchModule: () => Promise<T>,\n attempts = 3,\n delay = 1000,\n): Promise<T> => {\n const attemptsArray = Array.from<typeof fetchModule>({\n length: attempts,\n }).fill(fetchModule);\n\n let lastError: null \| Error = null;\n\n for await (const attempt of attemptsArray) {\n try {\n if (lastError !== null) {\n await sleep(delay);\n }\n return await attempt();\n } catch (error) {\n lastError = error as Error;\n }\n }\n throw lastError;\n};\n\nexport type PackedAsyncModule<T> = Promise<T \| { default: T }>;\n\n/\n Resolves either a direct value or an asynchronously imported module and unwraps its `default` export.\n \n @example\n * ```ts\n * const component = await unpackAsyncModule(import('./Component.ts'));\n * ```\n */\nexport const unpackAsyncModule = async <T>(\n maybeModule: T \| PackedAsyncModule<T>,\n): Promise<T> => {\n if (maybeModule instanceof Promise) {\n const data = (await maybeModule) as any;\n\n if ((data as any).default) {\n return (data as any).default;\n } else {\n return data;\n }\n }\n\n return maybeModule;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,kBAAkB,OAC7B,aACA,WAAW,GACX,QAAQ,QACO;CACf,MAAM,gBAAgB,MAAM,KAAyB,EACnD,QAAQ,UACT,CAAC,CAAC,KAAK,YAAY;CAEpB,IAAI,YAA0B;AAE9B,YAAW,MAAM,WAAW,cAC1B,KAAI;AACF,MAAI,cAAc,KAChB,QAAA,GAAA,cAAA,OAAY,MAAM;AAEpB,SAAO,MAAM,SAAS;UACf,OAAO;AACd,cAAY;;AAGhB,OAAM;;;;;;;;;;AAaR,IAAa,oBAAoB,OAC/B,gBACe;AACf,KAAI,uBAAuB,SAAS;EAClC,MAAM,OAAQ,MAAM;AAEpB,MAAK,KAAa,QAChB,QAAQ,KAAa;MAErB,QAAO;;AAIX,QAAO"}

package/imports.d.ts CHANGED Viewed

@@ -1,3 +1,19 @@
+/**
+ * ---header-docs-section---
+ * # yummies/imports
+ *
+ * ## Description
+ *
+ * Patterns for **dynamic `import()`**: retry with backoff, unpacking `{ default }` from mixed ESM
+ * shapes, and typed helpers around lazy-loaded modules. Ideal for code-split routes, optional panels,
+ * and resilient loading when the network or CDN flakes without freezing the whole app.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { fetchLazyModule } from "yummies/imports";
+ * ```
+ */
 /**
  * Lazily loads a module with retry support.
  *

package/imports.js CHANGED Viewed

@@ -1,6 +1,22 @@
 import { sleep } from "yummies/async";
 //#region src/imports.ts
 /**
+* ---header-docs-section---
+* # yummies/imports
+*
+* ## Description
+*
+* Patterns for **dynamic `import()`**: retry with backoff, unpacking `{ default }` from mixed ESM
+* shapes, and typed helpers around lazy-loaded modules. Ideal for code-split routes, optional panels,
+* and resilient loading when the network or CDN flakes without freezing the whole app.
+*
+* ## Usage
+*
+* ```ts
+* import { fetchLazyModule } from "yummies/imports";
+* ```
+*/
+/**
 * Lazily loads a module with retry support.
 *
 * @example

package/imports.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"imports.js","names":[],"sources":["../src/imports.ts"],"sourcesContent":["import { sleep } from 'yummies/async';\n\n/*\n Lazily loads a module with retry support.\n \n @example\n * ```ts\n * fetchLazyModule(() => import('./test.ts'), 3) // starts loading test.ts\n * // If loading test.ts fails, fetchLazyModule retries by calling fetchModule() again\n * // It retries as many times as specified by attempts (3 by default)\n * ```\n /\nexport const fetchLazyModule = async <T>(\n fetchModule: () => Promise<T>,\n attempts = 3,\n delay = 1000,\n): Promise<T> => {\n const attemptsArray = Array.from<typeof fetchModule>({\n length: attempts,\n }).fill(fetchModule);\n\n let lastError: null \| Error = null;\n\n for await (const attempt of attemptsArray) {\n try {\n if (lastError !== null) {\n await sleep(delay);\n }\n return await attempt();\n } catch (error) {\n lastError = error as Error;\n }\n }\n throw lastError;\n};\n\nexport type PackedAsyncModule<T> = Promise<T \| { default: T }>;\n\n/\n Resolves either a direct value or an asynchronously imported module and unwraps its `default` export.\n \n @example\n * ```ts\n * const component = await unpackAsyncModule(import('./Component.ts'));\n * ```\n */\nexport const unpackAsyncModule = async <T>(\n maybeModule: T \| PackedAsyncModule<T>,\n): Promise<T> => {\n if (maybeModule instanceof Promise) {\n const data = (await maybeModule) as any;\n\n if ((data as any).default) {\n return (data as any).default;\n } else {\n return data;\n }\n }\n\n return maybeModule;\n};\n"],"mappings":"~~;;;;;;;;;;;;AAYA~~,IAAa,kBAAkB,OAC7B,aACA,WAAW,GACX,QAAQ,QACO;CACf,MAAM,gBAAgB,MAAM,KAAyB,EACnD,QAAQ,UACT,CAAC,CAAC,KAAK,YAAY;CAEpB,IAAI,YAA0B;AAE9B,YAAW,MAAM,WAAW,cAC1B,KAAI;AACF,MAAI,cAAc,KAChB,OAAM,MAAM,MAAM;AAEpB,SAAO,MAAM,SAAS;UACf,OAAO;AACd,cAAY;;AAGhB,OAAM;;;;;;;;;;AAaR,IAAa,oBAAoB,OAC/B,gBACe;AACf,KAAI,uBAAuB,SAAS;EAClC,MAAM,OAAQ,MAAM;AAEpB,MAAK,KAAa,QAChB,QAAQ,KAAa;MAErB,QAAO;;AAIX,QAAO"}
1	+ {"version":3,"file":"imports.js","names":[],"sources":["../src/imports.ts"],"sourcesContent":["/*\n ---header-docs-section---\n * # yummies/imports\n \n ## Description\n \n Patterns for dynamic `import()`: retry with backoff, unpacking `{ default }` from mixed ESM\n * shapes, and typed helpers around lazy-loaded modules. Ideal for code-split routes, optional panels,\n * and resilient loading when the network or CDN flakes without freezing the whole app.\n \n ## Usage\n \n ```ts\n * import { fetchLazyModule } from \"yummies/imports\";\n * ```\n /\n\nimport { sleep } from 'yummies/async';\n\n/\n Lazily loads a module with retry support.\n \n @example\n * ```ts\n * fetchLazyModule(() => import('./test.ts'), 3) // starts loading test.ts\n * // If loading test.ts fails, fetchLazyModule retries by calling fetchModule() again\n * // It retries as many times as specified by attempts (3 by default)\n * ```\n /\nexport const fetchLazyModule = async <T>(\n fetchModule: () => Promise<T>,\n attempts = 3,\n delay = 1000,\n): Promise<T> => {\n const attemptsArray = Array.from<typeof fetchModule>({\n length: attempts,\n }).fill(fetchModule);\n\n let lastError: null \| Error = null;\n\n for await (const attempt of attemptsArray) {\n try {\n if (lastError !== null) {\n await sleep(delay);\n }\n return await attempt();\n } catch (error) {\n lastError = error as Error;\n }\n }\n throw lastError;\n};\n\nexport type PackedAsyncModule<T> = Promise<T \| { default: T }>;\n\n/\n Resolves either a direct value or an asynchronously imported module and unwraps its `default` export.\n \n @example\n * ```ts\n * const component = await unpackAsyncModule(import('./Component.ts'));\n * ```\n */\nexport const unpackAsyncModule = async <T>(\n maybeModule: T \| PackedAsyncModule<T>,\n): Promise<T> => {\n if (maybeModule instanceof Promise) {\n const data = (await maybeModule) as any;\n\n if ((data as any).default) {\n return (data as any).default;\n } else {\n return data;\n }\n }\n\n return maybeModule;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,kBAAkB,OAC7B,aACA,WAAW,GACX,QAAQ,QACO;CACf,MAAM,gBAAgB,MAAM,KAAyB,EACnD,QAAQ,UACT,CAAC,CAAC,KAAK,YAAY;CAEpB,IAAI,YAA0B;AAE9B,YAAW,MAAM,WAAW,cAC1B,KAAI;AACF,MAAI,cAAc,KAChB,OAAM,MAAM,MAAM;AAEpB,SAAO,MAAM,SAAS;UACf,OAAO;AACd,cAAY;;AAGhB,OAAM;;;;;;;;;;AAaR,IAAa,oBAAoB,OAC/B,gBACe;AACf,KAAI,uBAAuB,SAAS;EAClC,MAAM,OAAQ,MAAM;AAEpB,MAAK,KAAa,QAChB,QAAQ,KAAa;MAErB,QAAO;;AAIX,QAAO"}

package/math.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"math.cjs","names":[],"sources":["../src/math.ts"],"sourcesContent":["import type { Maybe } from 'yummies/types';\n\n/*\n Converts degrees to radians.\n \n @example\n * ```ts\n * degToRad(180); // Math.PI\n * ```\n /\nexport function degToRad(deg: number) {\n return deg (Math.PI / 180);\n}\n\n/*\n Converts radians to degrees.\n \n @example\n * ```ts\n * radToDeg(Math.PI); // 180\n * ```\n /\nexport function radToDeg(rad: number) {\n return rad (180 / Math.PI);\n}\n\n/*\n Returns what percentage `value` is of `from`.\n * @example\n * ```ts\n * percentFrom(500, 2000) // 25\n * percentFrom(1000, 2000) // 50\n * ```\n /\nexport const percentFrom = (value: Maybe<number>, from: Maybe<number>) => {\n return ((value ?? 0) / (from ?? 0)) 100 \|\| 0;\n};\n"],"mappings":";;;;;;;;;;~~AAUA~~,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,KAAK,KAAK;;;;;;;;;;AAW1B,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,MAAM,KAAK;;;;;;;;;;AAW3B,IAAa,eAAe,OAAsB,SAAwB;AACxE,SAAS,SAAS,MAAM,QAAQ,KAAM,OAAO"}
1	+ {"version":3,"file":"math.cjs","names":[],"sources":["../src/math.ts"],"sourcesContent":["/*\n ---header-docs-section---\n * # yummies/math\n \n ## Description\n \n Tiny math helpers: degree/radian conversion and nullable-safe percentage calculations. They wrap\n * common formulas so components do not repeat magic numbers or null checks when deriving layout or\n * charts from partially loaded data.\n \n ## Usage\n \n ```ts\n * import { degToRad, percentFrom } from \"yummies/math\";\n * ```\n /\n\nimport type { Maybe } from 'yummies/types';\n\n/\n Converts degrees to radians.\n \n @example\n * ```ts\n * degToRad(180); // Math.PI\n * ```\n /\nexport function degToRad(deg: number) {\n return deg (Math.PI / 180);\n}\n\n/*\n Converts radians to degrees.\n \n @example\n * ```ts\n * radToDeg(Math.PI); // 180\n * ```\n /\nexport function radToDeg(rad: number) {\n return rad (180 / Math.PI);\n}\n\n/*\n Returns what percentage `value` is of `from`.\n * @example\n * ```ts\n * percentFrom(500, 2000) // 25\n * percentFrom(1000, 2000) // 50\n * ```\n /\nexport const percentFrom = (value: Maybe<number>, from: Maybe<number>) => {\n return ((value ?? 0) / (from ?? 0)) 100 \|\| 0;\n};\n"],"mappings":";;;;;;;;;;AA2BA,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,KAAK,KAAK;;;;;;;;;;AAW1B,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,MAAM,KAAK;;;;;;;;;;AAW3B,IAAa,eAAe,OAAsB,SAAwB;AACxE,SAAS,SAAS,MAAM,QAAQ,KAAM,OAAO"}

package/math.d.ts CHANGED Viewed

@@ -1,5 +1,22 @@
 import { Maybe } from 'yummies/types';
+/**
+ * ---header-docs-section---
+ * # yummies/math
+ *
+ * ## Description
+ *
+ * Tiny math helpers: degree/radian conversion and nullable-safe percentage calculations. They wrap
+ * common formulas so components do not repeat magic numbers or null checks when deriving layout or
+ * charts from partially loaded data.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { degToRad, percentFrom } from "yummies/math";
+ * ```
+ */
 /**
  * Converts degrees to radians.
  *

package/math.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"math.js","names":[],"sources":["../src/math.ts"],"sourcesContent":["import type { Maybe } from 'yummies/types';\n\n/*\n Converts degrees to radians.\n \n @example\n * ```ts\n * degToRad(180); // Math.PI\n * ```\n /\nexport function degToRad(deg: number) {\n return deg (Math.PI / 180);\n}\n\n/*\n Converts radians to degrees.\n \n @example\n * ```ts\n * radToDeg(Math.PI); // 180\n * ```\n /\nexport function radToDeg(rad: number) {\n return rad (180 / Math.PI);\n}\n\n/*\n Returns what percentage `value` is of `from`.\n * @example\n * ```ts\n * percentFrom(500, 2000) // 25\n * percentFrom(1000, 2000) // 50\n * ```\n /\nexport const percentFrom = (value: Maybe<number>, from: Maybe<number>) => {\n return ((value ?? 0) / (from ?? 0)) 100 \|\| 0;\n};\n"],"mappings":";;;;;;;;;~~AAUA~~,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,KAAK,KAAK;;;;;;;;;;AAW1B,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,MAAM,KAAK;;;;;;;;;;AAW3B,IAAa,eAAe,OAAsB,SAAwB;AACxE,SAAS,SAAS,MAAM,QAAQ,KAAM,OAAO"}
1	+ {"version":3,"file":"math.js","names":[],"sources":["../src/math.ts"],"sourcesContent":["/*\n ---header-docs-section---\n * # yummies/math\n \n ## Description\n \n Tiny math helpers: degree/radian conversion and nullable-safe percentage calculations. They wrap\n * common formulas so components do not repeat magic numbers or null checks when deriving layout or\n * charts from partially loaded data.\n \n ## Usage\n \n ```ts\n * import { degToRad, percentFrom } from \"yummies/math\";\n * ```\n /\n\nimport type { Maybe } from 'yummies/types';\n\n/\n Converts degrees to radians.\n \n @example\n * ```ts\n * degToRad(180); // Math.PI\n * ```\n /\nexport function degToRad(deg: number) {\n return deg (Math.PI / 180);\n}\n\n/*\n Converts radians to degrees.\n \n @example\n * ```ts\n * radToDeg(Math.PI); // 180\n * ```\n /\nexport function radToDeg(rad: number) {\n return rad (180 / Math.PI);\n}\n\n/*\n Returns what percentage `value` is of `from`.\n * @example\n * ```ts\n * percentFrom(500, 2000) // 25\n * percentFrom(1000, 2000) // 50\n * ```\n /\nexport const percentFrom = (value: Maybe<number>, from: Maybe<number>) => {\n return ((value ?? 0) / (from ?? 0)) 100 \|\| 0;\n};\n"],"mappings":";;;;;;;;;AA2BA,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,KAAK,KAAK;;;;;;;;;;AAW1B,SAAgB,SAAS,KAAa;AACpC,QAAO,OAAO,MAAM,KAAK;;;;;;;;;;AAW3B,IAAa,eAAe,OAAsB,SAAwB;AACxE,SAAS,SAAS,MAAM,QAAQ,KAAM,OAAO"}

package/media.cjs CHANGED Viewed

@@ -3,6 +3,22 @@ require("./chunk-CVq3Gv4J.cjs");
 let yummies_math = require("yummies/math");
 //#region src/media.ts
 /**
+* ---header-docs-section---
+* # yummies/media
+*
+* ## Description
+*
+* Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related
+* browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image
+* pipelines and uploads stay consistent and easier to test or mock.
+*
+* ## Usage
+*
+* ```ts
+* import { blobToBase64 } from "yummies/media";
+* ```
+*/
+/**
 * Reads a {@link Blob} as a **data URL** string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.
 *
 * Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that

package/media.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"media.cjs","names":[],"sources":["../src/media.ts"],"sourcesContent":["import { degToRad } from 'yummies/math';\n\n/*\n Reads a {@link Blob} as a data URL string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.\n \n Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that\n * expect Base64-in-JSON. The result includes the MIME prefix, not raw Base64 alone — use\n * {@link decodeDataUrl} if you need the payload and type separately.\n \n @param blob - Any `Blob` or `File` (files are blobs).\n * @returns Resolves to the data URL string; rejects if reading fails.\n \n @example\n * ```ts\n * const dataUrl = await blobToBase64(file);\n * previewImg.src = dataUrl;\n * ```\n \n @example\n * ```ts\n * const fromFetch = await fetch('/api/export').then((r) => r.blob());\n * const dataUrl = await blobToBase64(fromFetch);\n * ```\n /\nexport function blobToBase64(blob: Blob): Promise<string> {\n return new Promise((resolve, reject) => {\n const reader = new FileReader();\n reader.onloadend = () => resolve(reader.result as string);\n reader.onerror = reject;\n reader.readAsDataURL(blob);\n });\n}\n\n/\n If `urlOrBlob` is already a string, returns it unchanged. If it is a {@link Blob}, returns\n * `URL.createObjectURL(blob)` — a short-lived `blob:` URL valid in this document until\n * {@link URL.revokeObjectURL} is called.\n \n Pair with {@link renderImage} or `<img src>` without re-fetching binary data. *Remember to\n `revokeObjectURL`** when the URL is no longer needed to avoid retaining blob memory.\n \n @param urlOrBlob - Remote/http(s) URL string, data URL, or a `Blob` / `File`.\n * @returns A string suitable for `HTMLImageElement.src` or similar.\n \n @example\n * ```ts\n * const src = blobToUrl(uploadedFile);\n * img.src = src;\n * // when done:\n * URL.revokeObjectURL(src);\n * ```\n \n @example\n * ```ts\n * blobToUrl('https://cdn.example.com/logo.png'); // passed through as-is\n * ```\n /\nexport const blobToUrl = (urlOrBlob: string \| Blob) =>\n urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;\n\n/\n Creates a new {@link Blob} from a {@link File}, copying the bytes and keeping `file.type` as\n * the blob’s MIME type. Handy when an API accepts `Blob` but you only have `File`, or you want a\n * plain blob without the `File` name/lastModified metadata.\n \n @param file - Source file from an `<input type=\"file\">` or drag-and-drop.\n * @returns A `Blob` with the same content and `type` as the file.\n \n @example\n * ```ts\n * const blob = fileToBlob(fileFromInput);\n * await uploadEndpoint(blob);\n * ```\n \n @example\n * ```ts\n * const blob = fileToBlob(imageFile);\n * const url = URL.createObjectURL(blob);\n * ```\n /\nexport const fileToBlob = (file: File) => {\n return new Blob([file], { type: file.type });\n};\n\n/\n Draws an {@link HTMLImageElement} onto an offscreen canvas, then builds a {@link Blob} from the\n * raster (via `canvas.toDataURL` + binary decode). Dimensions use `naturalWidth` / `naturalHeight`,\n * falling back to `300×300` if those are zero (e.g. not yet decoded).\n \n CORS: if the image is cross-origin without proper CORS headers, the canvas may be\n * tainted and `toDataURL` can throw — same browser rules as any canvas export.\n \n @param imageElement - Loaded image (`complete` / decoded recommended).\n * @param mimeType - Output MIME type, e.g. `'image/png'` (default) or `'image/jpeg'`. Encoder support is browser-dependent.\n * @returns Encoded image as a `Blob` with a matching `type` when possible.\n \n @example\n * ```ts\n * const img = await renderImage('/photo.jpg');\n * const jpegBlob = imageToBlob(img, 'image/jpeg');\n * ```\n \n @example\n * ```ts\n * const pngBlob = imageToBlob(cachedImg); // default image/png\n * ```\n /\nexport const imageToBlob = (\n imageElement: HTMLImageElement,\n mimeType: string = 'image/png',\n) => {\n const canvas = document.createElement('canvas');\n\n canvas.width = imageElement.naturalWidth \|\| 300;\n canvas.height = imageElement.naturalHeight \|\| 300;\n\n canvas.getContext('2d')!.drawImage(imageElement, 0, 0);\n\n const dataUri = canvas.toDataURL(mimeType, 1);\n const base64data = dataUri.split(',')[1];\n const base64MimeType = dataUri.split(';')[0].slice(5);\n\n const bytes = globalThis.atob(base64data);\n const buf = new ArrayBuffer(bytes.length);\n const array = new Uint8Array(buf);\n\n for (let index = 0; index < bytes.length; index++) {\n array[index] = bytes.charCodeAt(index);\n }\n\n const blob = new Blob([array], { type: base64MimeType });\n\n return blob;\n};\n\n/\n Loads a resource into a new `HTMLImageElement`: `src` is set via {@link blobToUrl} (so blobs get\n * object URLs, strings are used directly). Resolves on `load` with the same element; rejects on\n * `error` (e.g. bad URL, network failure, corrupt image) with no rejection value.\n \n Does not add the node to the DOM — use the returned element for canvas, measuring, or\n * {@link imageToBlob}.\n \n @param urlOrBlob - Remote URL, data URL, or `Blob` / `File`.\n * @returns Promise that fulfills with the loaded `HTMLImageElement`.\n \n @example\n * ```ts\n * const img = await renderImage('https://example.com/pic.png');\n * document.body.appendChild(img);\n * ```\n \n @example\n * ```ts\n * const img = await renderImage(pickedFile);\n * const blob = imageToBlob(img, 'image/webp');\n * ```\n /\nexport const renderImage = (urlOrBlob: Blob \| string) =>\n new Promise<HTMLImageElement>((resolve, reject) => {\n const image = new Image();\n image.src = blobToUrl(urlOrBlob);\n image.onload = () => resolve(image);\n image.onerror = () => reject();\n });\n\nfunction cropImageFromCanvas(context: CanvasRenderingContext2D) {\n const canvas = context.canvas;\n let w = canvas.width;\n let h = canvas.height;\n const pix: { x: number[]; y: number[] } = { x: [], y: [] };\n const imageData = context.getImageData(0, 0, canvas.width, canvas.height);\n let x: number;\n let y: number;\n let index: number;\n\n for (y = 0; y < h; y++) {\n for (x = 0; x < w; x++) {\n index = (y w + x) * 4;\n if (imageData.data[index + 3] > 0) {\n pix.x.push(x);\n pix.y.push(y);\n }\n }\n }\n pix.x.sort((a, b) => a - b);\n pix.y.sort((a, b) => a - b);\n const n = pix.x.length - 1;\n\n w = 1 + pix.x[n] - pix.x[0];\n h = 1 + pix.y[n] - pix.y[0];\n const cut = context.getImageData(pix.x[0], pix.y[0], w, h);\n\n canvas.width = w;\n canvas.height = h;\n context.putImageData(cut, 0, 0);\n return canvas;\n}\n\n// TODO: ломает iphone с огромными изображениями\n/*\n Rotates `image` around its center on a square canvas (side = max(width, height)), then crops\n * transparent margins by trimming to the bounding box of pixels with non-zero alpha.\n * Returns a new loaded `HTMLImageElement` (PNG data URL under the hood via {@link renderImage}).\n \n `angle` is in degrees; converted with {@link degToRad} from `yummies/math`.\n \n Very large sources can stress memory on some mobile browsers (known iPhone issues — see TODO in source).\n \n @param image - Source image (should be decoded; uses `width` / `height`).\n * @param angle - Rotation in degrees (e.g. `90` for quarter turn).\n * @returns Promise of a new `HTMLImageElement` showing the rotated, cropped result.\n \n @example\n * ```ts\n * const upright = await rotateImage(landscapeImg, 90);\n * ```\n \n @example\n * ```ts\n * const fixed = await rotateImage(await renderImage(file), -15);\n * ```\n /\nexport const rotateImage = (image: HTMLImageElement, angle: number) => {\n const maxSize = Math.max(image.width, image.height);\n const canvas = document.createElement('canvas');\n canvas.width = maxSize;\n canvas.height = maxSize;\n const context = canvas.getContext('2d')!;\n context.save();\n context.translate(canvas.width / 2, canvas.height / 2);\n context.rotate(degToRad(angle));\n context.drawImage(image, -image.width / 2, -image.height / 2);\n context.restore();\n cropImageFromCanvas(context);\n return renderImage(canvas.toDataURL('image/png'));\n};\n\ninterface DecodedDataUrl {\n mimeType?: string;\n data?: string;\n}\n\n/\n Parses a `data:` URL of the form `data:<mime>;base64,<payload>` into its MIME type and raw\n * Base64 body (without the `data:...;base64,` prefix). Non-matching strings yield `undefined`\n * fields in the result object.\n \n @param url - Full data URL string.\n * @returns `{ mimeType, data }` — both optional when the regex does not match.\n \n @example\n * ```ts\n * const { mimeType, data } = decodeDataUrl('data:image/png;base64,iVBORw0KGgo=');\n * // mimeType === 'image/png', data === 'iVBORw0KGgo='\n * ```\n \n @example\n * ```ts\n * decodeDataUrl('not-a-data-url'); // { mimeType: undefined, data: undefined }\n * ```\n /\nexport function decodeDataUrl(url: string): DecodedDataUrl {\n const regex = /^data:(.);base64,\\s?(.)$/;\n const matches = new RegExp(regex).exec(url);\n\n return {\n mimeType: matches?.[1],\n data: matches?.[2],\n };\n}\n\n/\n Returns `true` if `url` starts with `https://` or `http://` (case-sensitive, as in\n * `String#startsWith`). Does not validate that the rest is a well-formed URL — only the scheme\n * prefix. `blob:`, `data:`, and relative paths return `false`.\n \n @param url - String to test (often a user-provided or configured href).\n \n @example\n * ```ts\n * isHttpUrl('https://example.com/path'); // true\n * isHttpUrl('http://localhost:3000'); // true\n * ```\n \n @example\n * ```ts\n * isHttpUrl('//cdn.example.com'); // false — no explicit http(s) prefix\n * isHttpUrl('/assets/logo.png'); // false — relative path\n * ```\n /\nexport const isHttpUrl = (url: string): boolean => {\n return url.startsWith('https://') \|\| url.startsWith('http://');\n};\n\n/\n Returns `true` when `str` is a data URL that {@link decodeDataUrl} can parse and the MIME\n * type starts with `image/` (e.g. `image/png`, `image/jpeg`). Requires both a non-empty Base64\n * payload and an image MIME — arbitrary `data:text/plain;base64,...` is `false`.\n \n @param str - Candidate string (often `img.src` or API payload).\n \n @example\n * ```ts\n * isBase64Image('data:image/png;base64,iVBORw0KGgo='); // true\n * ```\n \n @example\n * ```ts\n * isBase64Image('https://example.com/x.png'); // false\n * isBase64Image('data:text/plain;base64,SGk='); // false\n * ```\n */\nexport const isBase64Image = (str: string): boolean => {\n const { mimeType, data } = decodeDataUrl(str);\n return !!(data && mimeType?.startsWith('image/'));\n};\n"],"mappings":"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"}
1	+ {"version":3,"file":"media.cjs","names":[],"sources":["../src/media.ts"],"sourcesContent":["/*\n ---header-docs-section---\n * # yummies/media\n \n ## Description\n \n Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related\n * browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image\n * pipelines and uploads stay consistent and easier to test or mock.\n \n ## Usage\n \n ```ts\n * import { blobToBase64 } from \"yummies/media\";\n * ```\n /\n\nimport { degToRad } from 'yummies/math';\n\n/\n Reads a {@link Blob} as a data URL string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.\n \n Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that\n * expect Base64-in-JSON. The result includes the MIME prefix, not raw Base64 alone — use\n * {@link decodeDataUrl} if you need the payload and type separately.\n \n @param blob - Any `Blob` or `File` (files are blobs).\n * @returns Resolves to the data URL string; rejects if reading fails.\n \n @example\n * ```ts\n * const dataUrl = await blobToBase64(file);\n * previewImg.src = dataUrl;\n * ```\n \n @example\n * ```ts\n * const fromFetch = await fetch('/api/export').then((r) => r.blob());\n * const dataUrl = await blobToBase64(fromFetch);\n * ```\n /\nexport function blobToBase64(blob: Blob): Promise<string> {\n return new Promise((resolve, reject) => {\n const reader = new FileReader();\n reader.onloadend = () => resolve(reader.result as string);\n reader.onerror = reject;\n reader.readAsDataURL(blob);\n });\n}\n\n/\n If `urlOrBlob` is already a string, returns it unchanged. If it is a {@link Blob}, returns\n * `URL.createObjectURL(blob)` — a short-lived `blob:` URL valid in this document until\n * {@link URL.revokeObjectURL} is called.\n \n Pair with {@link renderImage} or `<img src>` without re-fetching binary data. *Remember to\n `revokeObjectURL`** when the URL is no longer needed to avoid retaining blob memory.\n \n @param urlOrBlob - Remote/http(s) URL string, data URL, or a `Blob` / `File`.\n * @returns A string suitable for `HTMLImageElement.src` or similar.\n \n @example\n * ```ts\n * const src = blobToUrl(uploadedFile);\n * img.src = src;\n * // when done:\n * URL.revokeObjectURL(src);\n * ```\n \n @example\n * ```ts\n * blobToUrl('https://cdn.example.com/logo.png'); // passed through as-is\n * ```\n /\nexport const blobToUrl = (urlOrBlob: string \| Blob) =>\n urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;\n\n/\n Creates a new {@link Blob} from a {@link File}, copying the bytes and keeping `file.type` as\n * the blob’s MIME type. Handy when an API accepts `Blob` but you only have `File`, or you want a\n * plain blob without the `File` name/lastModified metadata.\n \n @param file - Source file from an `<input type=\"file\">` or drag-and-drop.\n * @returns A `Blob` with the same content and `type` as the file.\n \n @example\n * ```ts\n * const blob = fileToBlob(fileFromInput);\n * await uploadEndpoint(blob);\n * ```\n \n @example\n * ```ts\n * const blob = fileToBlob(imageFile);\n * const url = URL.createObjectURL(blob);\n * ```\n /\nexport const fileToBlob = (file: File) => {\n return new Blob([file], { type: file.type });\n};\n\n/\n Draws an {@link HTMLImageElement} onto an offscreen canvas, then builds a {@link Blob} from the\n * raster (via `canvas.toDataURL` + binary decode). Dimensions use `naturalWidth` / `naturalHeight`,\n * falling back to `300×300` if those are zero (e.g. not yet decoded).\n \n CORS: if the image is cross-origin without proper CORS headers, the canvas may be\n * tainted and `toDataURL` can throw — same browser rules as any canvas export.\n \n @param imageElement - Loaded image (`complete` / decoded recommended).\n * @param mimeType - Output MIME type, e.g. `'image/png'` (default) or `'image/jpeg'`. Encoder support is browser-dependent.\n * @returns Encoded image as a `Blob` with a matching `type` when possible.\n \n @example\n * ```ts\n * const img = await renderImage('/photo.jpg');\n * const jpegBlob = imageToBlob(img, 'image/jpeg');\n * ```\n \n @example\n * ```ts\n * const pngBlob = imageToBlob(cachedImg); // default image/png\n * ```\n /\nexport const imageToBlob = (\n imageElement: HTMLImageElement,\n mimeType: string = 'image/png',\n) => {\n const canvas = document.createElement('canvas');\n\n canvas.width = imageElement.naturalWidth \|\| 300;\n canvas.height = imageElement.naturalHeight \|\| 300;\n\n canvas.getContext('2d')!.drawImage(imageElement, 0, 0);\n\n const dataUri = canvas.toDataURL(mimeType, 1);\n const base64data = dataUri.split(',')[1];\n const base64MimeType = dataUri.split(';')[0].slice(5);\n\n const bytes = globalThis.atob(base64data);\n const buf = new ArrayBuffer(bytes.length);\n const array = new Uint8Array(buf);\n\n for (let index = 0; index < bytes.length; index++) {\n array[index] = bytes.charCodeAt(index);\n }\n\n const blob = new Blob([array], { type: base64MimeType });\n\n return blob;\n};\n\n/\n Loads a resource into a new `HTMLImageElement`: `src` is set via {@link blobToUrl} (so blobs get\n * object URLs, strings are used directly). Resolves on `load` with the same element; rejects on\n * `error` (e.g. bad URL, network failure, corrupt image) with no rejection value.\n \n Does not add the node to the DOM — use the returned element for canvas, measuring, or\n * {@link imageToBlob}.\n \n @param urlOrBlob - Remote URL, data URL, or `Blob` / `File`.\n * @returns Promise that fulfills with the loaded `HTMLImageElement`.\n \n @example\n * ```ts\n * const img = await renderImage('https://example.com/pic.png');\n * document.body.appendChild(img);\n * ```\n \n @example\n * ```ts\n * const img = await renderImage(pickedFile);\n * const blob = imageToBlob(img, 'image/webp');\n * ```\n /\nexport const renderImage = (urlOrBlob: Blob \| string) =>\n new Promise<HTMLImageElement>((resolve, reject) => {\n const image = new Image();\n image.src = blobToUrl(urlOrBlob);\n image.onload = () => resolve(image);\n image.onerror = () => reject();\n });\n\nfunction cropImageFromCanvas(context: CanvasRenderingContext2D) {\n const canvas = context.canvas;\n let w = canvas.width;\n let h = canvas.height;\n const pix: { x: number[]; y: number[] } = { x: [], y: [] };\n const imageData = context.getImageData(0, 0, canvas.width, canvas.height);\n let x: number;\n let y: number;\n let index: number;\n\n for (y = 0; y < h; y++) {\n for (x = 0; x < w; x++) {\n index = (y w + x) * 4;\n if (imageData.data[index + 3] > 0) {\n pix.x.push(x);\n pix.y.push(y);\n }\n }\n }\n pix.x.sort((a, b) => a - b);\n pix.y.sort((a, b) => a - b);\n const n = pix.x.length - 1;\n\n w = 1 + pix.x[n] - pix.x[0];\n h = 1 + pix.y[n] - pix.y[0];\n const cut = context.getImageData(pix.x[0], pix.y[0], w, h);\n\n canvas.width = w;\n canvas.height = h;\n context.putImageData(cut, 0, 0);\n return canvas;\n}\n\n// TODO: ломает iphone с огромными изображениями\n/*\n Rotates `image` around its center on a square canvas (side = max(width, height)), then crops\n * transparent margins by trimming to the bounding box of pixels with non-zero alpha.\n * Returns a new loaded `HTMLImageElement` (PNG data URL under the hood via {@link renderImage}).\n \n `angle` is in degrees; converted with {@link degToRad} from `yummies/math`.\n \n Very large sources can stress memory on some mobile browsers (known iPhone issues — see TODO in source).\n \n @param image - Source image (should be decoded; uses `width` / `height`).\n * @param angle - Rotation in degrees (e.g. `90` for quarter turn).\n * @returns Promise of a new `HTMLImageElement` showing the rotated, cropped result.\n \n @example\n * ```ts\n * const upright = await rotateImage(landscapeImg, 90);\n * ```\n \n @example\n * ```ts\n * const fixed = await rotateImage(await renderImage(file), -15);\n * ```\n /\nexport const rotateImage = (image: HTMLImageElement, angle: number) => {\n const maxSize = Math.max(image.width, image.height);\n const canvas = document.createElement('canvas');\n canvas.width = maxSize;\n canvas.height = maxSize;\n const context = canvas.getContext('2d')!;\n context.save();\n context.translate(canvas.width / 2, canvas.height / 2);\n context.rotate(degToRad(angle));\n context.drawImage(image, -image.width / 2, -image.height / 2);\n context.restore();\n cropImageFromCanvas(context);\n return renderImage(canvas.toDataURL('image/png'));\n};\n\ninterface DecodedDataUrl {\n mimeType?: string;\n data?: string;\n}\n\n/\n Parses a `data:` URL of the form `data:<mime>;base64,<payload>` into its MIME type and raw\n * Base64 body (without the `data:...;base64,` prefix). Non-matching strings yield `undefined`\n * fields in the result object.\n \n @param url - Full data URL string.\n * @returns `{ mimeType, data }` — both optional when the regex does not match.\n \n @example\n * ```ts\n * const { mimeType, data } = decodeDataUrl('data:image/png;base64,iVBORw0KGgo=');\n * // mimeType === 'image/png', data === 'iVBORw0KGgo='\n * ```\n \n @example\n * ```ts\n * decodeDataUrl('not-a-data-url'); // { mimeType: undefined, data: undefined }\n * ```\n /\nexport function decodeDataUrl(url: string): DecodedDataUrl {\n const regex = /^data:(.);base64,\\s?(.)$/;\n const matches = new RegExp(regex).exec(url);\n\n return {\n mimeType: matches?.[1],\n data: matches?.[2],\n };\n}\n\n/\n Returns `true` if `url` starts with `https://` or `http://` (case-sensitive, as in\n * `String#startsWith`). Does not validate that the rest is a well-formed URL — only the scheme\n * prefix. `blob:`, `data:`, and relative paths return `false`.\n \n @param url - String to test (often a user-provided or configured href).\n \n @example\n * ```ts\n * isHttpUrl('https://example.com/path'); // true\n * isHttpUrl('http://localhost:3000'); // true\n * ```\n \n @example\n * ```ts\n * isHttpUrl('//cdn.example.com'); // false — no explicit http(s) prefix\n * isHttpUrl('/assets/logo.png'); // false — relative path\n * ```\n /\nexport const isHttpUrl = (url: string): boolean => {\n return url.startsWith('https://') \|\| url.startsWith('http://');\n};\n\n/\n Returns `true` when `str` is a data URL that {@link decodeDataUrl} can parse and the MIME\n * type starts with `image/` (e.g. `image/png`, `image/jpeg`). Requires both a non-empty Base64\n * payload and an image MIME — arbitrary `data:text/plain;base64,...` is `false`.\n \n @param str - Candidate string (often `img.src` or API payload).\n \n @example\n * ```ts\n * isBase64Image('data:image/png;base64,iVBORw0KGgo='); // true\n * ```\n \n @example\n * ```ts\n * isBase64Image('https://example.com/x.png'); // false\n * isBase64Image('data:text/plain;base64,SGk='); // false\n * ```\n */\nexport const isBase64Image = (str: string): boolean => {\n const { mimeType, data } = decodeDataUrl(str);\n return !!(data && mimeType?.startsWith('image/'));\n};\n"],"mappings":"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"}

package/media.d.ts CHANGED Viewed

@@ -1,3 +1,19 @@
+/**
+ * ---header-docs-section---
+ * # yummies/media
+ *
+ * ## Description
+ *
+ * Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related
+ * browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image
+ * pipelines and uploads stay consistent and easier to test or mock.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { blobToBase64 } from "yummies/media";
+ * ```
+ */
 /**
  * Reads a {@link Blob} as a **data URL** string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.
  *

package/media.js CHANGED Viewed

@@ -1,6 +1,22 @@
 import { degToRad } from "yummies/math";
 //#region src/media.ts
 /**
+* ---header-docs-section---
+* # yummies/media
+*
+* ## Description
+*
+* Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related
+* browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image
+* pipelines and uploads stay consistent and easier to test or mock.
+*
+* ## Usage
+*
+* ```ts
+* import { blobToBase64 } from "yummies/media";
+* ```
+*/
+/**
 * Reads a {@link Blob} as a **data URL** string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.
 *
 * Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that

package/media.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"media.js","names":[],"sources":["../src/media.ts"],"sourcesContent":["import { degToRad } from 'yummies/math';\n\n/*\n Reads a {@link Blob} as a data URL string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.\n \n Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that\n * expect Base64-in-JSON. The result includes the MIME prefix, not raw Base64 alone — use\n * {@link decodeDataUrl} if you need the payload and type separately.\n \n @param blob - Any `Blob` or `File` (files are blobs).\n * @returns Resolves to the data URL string; rejects if reading fails.\n \n @example\n * ```ts\n * const dataUrl = await blobToBase64(file);\n * previewImg.src = dataUrl;\n * ```\n \n @example\n * ```ts\n * const fromFetch = await fetch('/api/export').then((r) => r.blob());\n * const dataUrl = await blobToBase64(fromFetch);\n * ```\n /\nexport function blobToBase64(blob: Blob): Promise<string> {\n return new Promise((resolve, reject) => {\n const reader = new FileReader();\n reader.onloadend = () => resolve(reader.result as string);\n reader.onerror = reject;\n reader.readAsDataURL(blob);\n });\n}\n\n/\n If `urlOrBlob` is already a string, returns it unchanged. If it is a {@link Blob}, returns\n * `URL.createObjectURL(blob)` — a short-lived `blob:` URL valid in this document until\n * {@link URL.revokeObjectURL} is called.\n \n Pair with {@link renderImage} or `<img src>` without re-fetching binary data. *Remember to\n `revokeObjectURL`** when the URL is no longer needed to avoid retaining blob memory.\n \n @param urlOrBlob - Remote/http(s) URL string, data URL, or a `Blob` / `File`.\n * @returns A string suitable for `HTMLImageElement.src` or similar.\n \n @example\n * ```ts\n * const src = blobToUrl(uploadedFile);\n * img.src = src;\n * // when done:\n * URL.revokeObjectURL(src);\n * ```\n \n @example\n * ```ts\n * blobToUrl('https://cdn.example.com/logo.png'); // passed through as-is\n * ```\n /\nexport const blobToUrl = (urlOrBlob: string \| Blob) =>\n urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;\n\n/\n Creates a new {@link Blob} from a {@link File}, copying the bytes and keeping `file.type` as\n * the blob’s MIME type. Handy when an API accepts `Blob` but you only have `File`, or you want a\n * plain blob without the `File` name/lastModified metadata.\n \n @param file - Source file from an `<input type=\"file\">` or drag-and-drop.\n * @returns A `Blob` with the same content and `type` as the file.\n \n @example\n * ```ts\n * const blob = fileToBlob(fileFromInput);\n * await uploadEndpoint(blob);\n * ```\n \n @example\n * ```ts\n * const blob = fileToBlob(imageFile);\n * const url = URL.createObjectURL(blob);\n * ```\n /\nexport const fileToBlob = (file: File) => {\n return new Blob([file], { type: file.type });\n};\n\n/\n Draws an {@link HTMLImageElement} onto an offscreen canvas, then builds a {@link Blob} from the\n * raster (via `canvas.toDataURL` + binary decode). Dimensions use `naturalWidth` / `naturalHeight`,\n * falling back to `300×300` if those are zero (e.g. not yet decoded).\n \n CORS: if the image is cross-origin without proper CORS headers, the canvas may be\n * tainted and `toDataURL` can throw — same browser rules as any canvas export.\n \n @param imageElement - Loaded image (`complete` / decoded recommended).\n * @param mimeType - Output MIME type, e.g. `'image/png'` (default) or `'image/jpeg'`. Encoder support is browser-dependent.\n * @returns Encoded image as a `Blob` with a matching `type` when possible.\n \n @example\n * ```ts\n * const img = await renderImage('/photo.jpg');\n * const jpegBlob = imageToBlob(img, 'image/jpeg');\n * ```\n \n @example\n * ```ts\n * const pngBlob = imageToBlob(cachedImg); // default image/png\n * ```\n /\nexport const imageToBlob = (\n imageElement: HTMLImageElement,\n mimeType: string = 'image/png',\n) => {\n const canvas = document.createElement('canvas');\n\n canvas.width = imageElement.naturalWidth \|\| 300;\n canvas.height = imageElement.naturalHeight \|\| 300;\n\n canvas.getContext('2d')!.drawImage(imageElement, 0, 0);\n\n const dataUri = canvas.toDataURL(mimeType, 1);\n const base64data = dataUri.split(',')[1];\n const base64MimeType = dataUri.split(';')[0].slice(5);\n\n const bytes = globalThis.atob(base64data);\n const buf = new ArrayBuffer(bytes.length);\n const array = new Uint8Array(buf);\n\n for (let index = 0; index < bytes.length; index++) {\n array[index] = bytes.charCodeAt(index);\n }\n\n const blob = new Blob([array], { type: base64MimeType });\n\n return blob;\n};\n\n/\n Loads a resource into a new `HTMLImageElement`: `src` is set via {@link blobToUrl} (so blobs get\n * object URLs, strings are used directly). Resolves on `load` with the same element; rejects on\n * `error` (e.g. bad URL, network failure, corrupt image) with no rejection value.\n \n Does not add the node to the DOM — use the returned element for canvas, measuring, or\n * {@link imageToBlob}.\n \n @param urlOrBlob - Remote URL, data URL, or `Blob` / `File`.\n * @returns Promise that fulfills with the loaded `HTMLImageElement`.\n \n @example\n * ```ts\n * const img = await renderImage('https://example.com/pic.png');\n * document.body.appendChild(img);\n * ```\n \n @example\n * ```ts\n * const img = await renderImage(pickedFile);\n * const blob = imageToBlob(img, 'image/webp');\n * ```\n /\nexport const renderImage = (urlOrBlob: Blob \| string) =>\n new Promise<HTMLImageElement>((resolve, reject) => {\n const image = new Image();\n image.src = blobToUrl(urlOrBlob);\n image.onload = () => resolve(image);\n image.onerror = () => reject();\n });\n\nfunction cropImageFromCanvas(context: CanvasRenderingContext2D) {\n const canvas = context.canvas;\n let w = canvas.width;\n let h = canvas.height;\n const pix: { x: number[]; y: number[] } = { x: [], y: [] };\n const imageData = context.getImageData(0, 0, canvas.width, canvas.height);\n let x: number;\n let y: number;\n let index: number;\n\n for (y = 0; y < h; y++) {\n for (x = 0; x < w; x++) {\n index = (y w + x) * 4;\n if (imageData.data[index + 3] > 0) {\n pix.x.push(x);\n pix.y.push(y);\n }\n }\n }\n pix.x.sort((a, b) => a - b);\n pix.y.sort((a, b) => a - b);\n const n = pix.x.length - 1;\n\n w = 1 + pix.x[n] - pix.x[0];\n h = 1 + pix.y[n] - pix.y[0];\n const cut = context.getImageData(pix.x[0], pix.y[0], w, h);\n\n canvas.width = w;\n canvas.height = h;\n context.putImageData(cut, 0, 0);\n return canvas;\n}\n\n// TODO: ломает iphone с огромными изображениями\n/*\n Rotates `image` around its center on a square canvas (side = max(width, height)), then crops\n * transparent margins by trimming to the bounding box of pixels with non-zero alpha.\n * Returns a new loaded `HTMLImageElement` (PNG data URL under the hood via {@link renderImage}).\n \n `angle` is in degrees; converted with {@link degToRad} from `yummies/math`.\n \n Very large sources can stress memory on some mobile browsers (known iPhone issues — see TODO in source).\n \n @param image - Source image (should be decoded; uses `width` / `height`).\n * @param angle - Rotation in degrees (e.g. `90` for quarter turn).\n * @returns Promise of a new `HTMLImageElement` showing the rotated, cropped result.\n \n @example\n * ```ts\n * const upright = await rotateImage(landscapeImg, 90);\n * ```\n \n @example\n * ```ts\n * const fixed = await rotateImage(await renderImage(file), -15);\n * ```\n /\nexport const rotateImage = (image: HTMLImageElement, angle: number) => {\n const maxSize = Math.max(image.width, image.height);\n const canvas = document.createElement('canvas');\n canvas.width = maxSize;\n canvas.height = maxSize;\n const context = canvas.getContext('2d')!;\n context.save();\n context.translate(canvas.width / 2, canvas.height / 2);\n context.rotate(degToRad(angle));\n context.drawImage(image, -image.width / 2, -image.height / 2);\n context.restore();\n cropImageFromCanvas(context);\n return renderImage(canvas.toDataURL('image/png'));\n};\n\ninterface DecodedDataUrl {\n mimeType?: string;\n data?: string;\n}\n\n/\n Parses a `data:` URL of the form `data:<mime>;base64,<payload>` into its MIME type and raw\n * Base64 body (without the `data:...;base64,` prefix). Non-matching strings yield `undefined`\n * fields in the result object.\n \n @param url - Full data URL string.\n * @returns `{ mimeType, data }` — both optional when the regex does not match.\n \n @example\n * ```ts\n * const { mimeType, data } = decodeDataUrl('data:image/png;base64,iVBORw0KGgo=');\n * // mimeType === 'image/png', data === 'iVBORw0KGgo='\n * ```\n \n @example\n * ```ts\n * decodeDataUrl('not-a-data-url'); // { mimeType: undefined, data: undefined }\n * ```\n /\nexport function decodeDataUrl(url: string): DecodedDataUrl {\n const regex = /^data:(.);base64,\\s?(.)$/;\n const matches = new RegExp(regex).exec(url);\n\n return {\n mimeType: matches?.[1],\n data: matches?.[2],\n };\n}\n\n/\n Returns `true` if `url` starts with `https://` or `http://` (case-sensitive, as in\n * `String#startsWith`). Does not validate that the rest is a well-formed URL — only the scheme\n * prefix. `blob:`, `data:`, and relative paths return `false`.\n \n @param url - String to test (often a user-provided or configured href).\n \n @example\n * ```ts\n * isHttpUrl('https://example.com/path'); // true\n * isHttpUrl('http://localhost:3000'); // true\n * ```\n \n @example\n * ```ts\n * isHttpUrl('//cdn.example.com'); // false — no explicit http(s) prefix\n * isHttpUrl('/assets/logo.png'); // false — relative path\n * ```\n /\nexport const isHttpUrl = (url: string): boolean => {\n return url.startsWith('https://') \|\| url.startsWith('http://');\n};\n\n/\n Returns `true` when `str` is a data URL that {@link decodeDataUrl} can parse and the MIME\n * type starts with `image/` (e.g. `image/png`, `image/jpeg`). Requires both a non-empty Base64\n * payload and an image MIME — arbitrary `data:text/plain;base64,...` is `false`.\n \n @param str - Candidate string (often `img.src` or API payload).\n \n @example\n * ```ts\n * isBase64Image('data:image/png;base64,iVBORw0KGgo='); // true\n * ```\n \n @example\n * ```ts\n * isBase64Image('https://example.com/x.png'); // false\n * isBase64Image('data:text/plain;base64,SGk='); // false\n * ```\n */\nexport const isBase64Image = (str: string): boolean => {\n const { mimeType, data } = decodeDataUrl(str);\n return !!(data && mimeType?.startsWith('image/'));\n};\n"],"mappings":"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"}
1	+ {"version":3,"file":"media.js","names":[],"sources":["../src/media.ts"],"sourcesContent":["/*\n ---header-docs-section---\n * # yummies/media\n \n ## Description\n \n Binary and media helpers: Base64 data URLs, object URLs, image orientation fixes, and related\n * browser APIs wrapped in promises. Centralizes `FileReader`/`URL.createObjectURL` usage so image\n * pipelines and uploads stay consistent and easier to test or mock.\n \n ## Usage\n \n ```ts\n * import { blobToBase64 } from \"yummies/media\";\n * ```\n /\n\nimport { degToRad } from 'yummies/math';\n\n/\n Reads a {@link Blob} as a data URL string (`data:<mime>;base64,...`) using {@link FileReader#readAsDataURL}.\n \n Useful for previewing uploads, embedding small assets inline, or serializing binary for APIs that\n * expect Base64-in-JSON. The result includes the MIME prefix, not raw Base64 alone — use\n * {@link decodeDataUrl} if you need the payload and type separately.\n \n @param blob - Any `Blob` or `File` (files are blobs).\n * @returns Resolves to the data URL string; rejects if reading fails.\n \n @example\n * ```ts\n * const dataUrl = await blobToBase64(file);\n * previewImg.src = dataUrl;\n * ```\n \n @example\n * ```ts\n * const fromFetch = await fetch('/api/export').then((r) => r.blob());\n * const dataUrl = await blobToBase64(fromFetch);\n * ```\n /\nexport function blobToBase64(blob: Blob): Promise<string> {\n return new Promise((resolve, reject) => {\n const reader = new FileReader();\n reader.onloadend = () => resolve(reader.result as string);\n reader.onerror = reject;\n reader.readAsDataURL(blob);\n });\n}\n\n/\n If `urlOrBlob` is already a string, returns it unchanged. If it is a {@link Blob}, returns\n * `URL.createObjectURL(blob)` — a short-lived `blob:` URL valid in this document until\n * {@link URL.revokeObjectURL} is called.\n \n Pair with {@link renderImage} or `<img src>` without re-fetching binary data. *Remember to\n `revokeObjectURL`** when the URL is no longer needed to avoid retaining blob memory.\n \n @param urlOrBlob - Remote/http(s) URL string, data URL, or a `Blob` / `File`.\n * @returns A string suitable for `HTMLImageElement.src` or similar.\n \n @example\n * ```ts\n * const src = blobToUrl(uploadedFile);\n * img.src = src;\n * // when done:\n * URL.revokeObjectURL(src);\n * ```\n \n @example\n * ```ts\n * blobToUrl('https://cdn.example.com/logo.png'); // passed through as-is\n * ```\n /\nexport const blobToUrl = (urlOrBlob: string \| Blob) =>\n urlOrBlob instanceof Blob ? URL.createObjectURL(urlOrBlob) : urlOrBlob;\n\n/\n Creates a new {@link Blob} from a {@link File}, copying the bytes and keeping `file.type` as\n * the blob’s MIME type. Handy when an API accepts `Blob` but you only have `File`, or you want a\n * plain blob without the `File` name/lastModified metadata.\n \n @param file - Source file from an `<input type=\"file\">` or drag-and-drop.\n * @returns A `Blob` with the same content and `type` as the file.\n \n @example\n * ```ts\n * const blob = fileToBlob(fileFromInput);\n * await uploadEndpoint(blob);\n * ```\n \n @example\n * ```ts\n * const blob = fileToBlob(imageFile);\n * const url = URL.createObjectURL(blob);\n * ```\n /\nexport const fileToBlob = (file: File) => {\n return new Blob([file], { type: file.type });\n};\n\n/\n Draws an {@link HTMLImageElement} onto an offscreen canvas, then builds a {@link Blob} from the\n * raster (via `canvas.toDataURL` + binary decode). Dimensions use `naturalWidth` / `naturalHeight`,\n * falling back to `300×300` if those are zero (e.g. not yet decoded).\n \n CORS: if the image is cross-origin without proper CORS headers, the canvas may be\n * tainted and `toDataURL` can throw — same browser rules as any canvas export.\n \n @param imageElement - Loaded image (`complete` / decoded recommended).\n * @param mimeType - Output MIME type, e.g. `'image/png'` (default) or `'image/jpeg'`. Encoder support is browser-dependent.\n * @returns Encoded image as a `Blob` with a matching `type` when possible.\n \n @example\n * ```ts\n * const img = await renderImage('/photo.jpg');\n * const jpegBlob = imageToBlob(img, 'image/jpeg');\n * ```\n \n @example\n * ```ts\n * const pngBlob = imageToBlob(cachedImg); // default image/png\n * ```\n /\nexport const imageToBlob = (\n imageElement: HTMLImageElement,\n mimeType: string = 'image/png',\n) => {\n const canvas = document.createElement('canvas');\n\n canvas.width = imageElement.naturalWidth \|\| 300;\n canvas.height = imageElement.naturalHeight \|\| 300;\n\n canvas.getContext('2d')!.drawImage(imageElement, 0, 0);\n\n const dataUri = canvas.toDataURL(mimeType, 1);\n const base64data = dataUri.split(',')[1];\n const base64MimeType = dataUri.split(';')[0].slice(5);\n\n const bytes = globalThis.atob(base64data);\n const buf = new ArrayBuffer(bytes.length);\n const array = new Uint8Array(buf);\n\n for (let index = 0; index < bytes.length; index++) {\n array[index] = bytes.charCodeAt(index);\n }\n\n const blob = new Blob([array], { type: base64MimeType });\n\n return blob;\n};\n\n/\n Loads a resource into a new `HTMLImageElement`: `src` is set via {@link blobToUrl} (so blobs get\n * object URLs, strings are used directly). Resolves on `load` with the same element; rejects on\n * `error` (e.g. bad URL, network failure, corrupt image) with no rejection value.\n \n Does not add the node to the DOM — use the returned element for canvas, measuring, or\n * {@link imageToBlob}.\n \n @param urlOrBlob - Remote URL, data URL, or `Blob` / `File`.\n * @returns Promise that fulfills with the loaded `HTMLImageElement`.\n \n @example\n * ```ts\n * const img = await renderImage('https://example.com/pic.png');\n * document.body.appendChild(img);\n * ```\n \n @example\n * ```ts\n * const img = await renderImage(pickedFile);\n * const blob = imageToBlob(img, 'image/webp');\n * ```\n /\nexport const renderImage = (urlOrBlob: Blob \| string) =>\n new Promise<HTMLImageElement>((resolve, reject) => {\n const image = new Image();\n image.src = blobToUrl(urlOrBlob);\n image.onload = () => resolve(image);\n image.onerror = () => reject();\n });\n\nfunction cropImageFromCanvas(context: CanvasRenderingContext2D) {\n const canvas = context.canvas;\n let w = canvas.width;\n let h = canvas.height;\n const pix: { x: number[]; y: number[] } = { x: [], y: [] };\n const imageData = context.getImageData(0, 0, canvas.width, canvas.height);\n let x: number;\n let y: number;\n let index: number;\n\n for (y = 0; y < h; y++) {\n for (x = 0; x < w; x++) {\n index = (y w + x) * 4;\n if (imageData.data[index + 3] > 0) {\n pix.x.push(x);\n pix.y.push(y);\n }\n }\n }\n pix.x.sort((a, b) => a - b);\n pix.y.sort((a, b) => a - b);\n const n = pix.x.length - 1;\n\n w = 1 + pix.x[n] - pix.x[0];\n h = 1 + pix.y[n] - pix.y[0];\n const cut = context.getImageData(pix.x[0], pix.y[0], w, h);\n\n canvas.width = w;\n canvas.height = h;\n context.putImageData(cut, 0, 0);\n return canvas;\n}\n\n// TODO: ломает iphone с огромными изображениями\n/*\n Rotates `image` around its center on a square canvas (side = max(width, height)), then crops\n * transparent margins by trimming to the bounding box of pixels with non-zero alpha.\n * Returns a new loaded `HTMLImageElement` (PNG data URL under the hood via {@link renderImage}).\n \n `angle` is in degrees; converted with {@link degToRad} from `yummies/math`.\n \n Very large sources can stress memory on some mobile browsers (known iPhone issues — see TODO in source).\n \n @param image - Source image (should be decoded; uses `width` / `height`).\n * @param angle - Rotation in degrees (e.g. `90` for quarter turn).\n * @returns Promise of a new `HTMLImageElement` showing the rotated, cropped result.\n \n @example\n * ```ts\n * const upright = await rotateImage(landscapeImg, 90);\n * ```\n \n @example\n * ```ts\n * const fixed = await rotateImage(await renderImage(file), -15);\n * ```\n /\nexport const rotateImage = (image: HTMLImageElement, angle: number) => {\n const maxSize = Math.max(image.width, image.height);\n const canvas = document.createElement('canvas');\n canvas.width = maxSize;\n canvas.height = maxSize;\n const context = canvas.getContext('2d')!;\n context.save();\n context.translate(canvas.width / 2, canvas.height / 2);\n context.rotate(degToRad(angle));\n context.drawImage(image, -image.width / 2, -image.height / 2);\n context.restore();\n cropImageFromCanvas(context);\n return renderImage(canvas.toDataURL('image/png'));\n};\n\ninterface DecodedDataUrl {\n mimeType?: string;\n data?: string;\n}\n\n/\n Parses a `data:` URL of the form `data:<mime>;base64,<payload>` into its MIME type and raw\n * Base64 body (without the `data:...;base64,` prefix). Non-matching strings yield `undefined`\n * fields in the result object.\n \n @param url - Full data URL string.\n * @returns `{ mimeType, data }` — both optional when the regex does not match.\n \n @example\n * ```ts\n * const { mimeType, data } = decodeDataUrl('data:image/png;base64,iVBORw0KGgo=');\n * // mimeType === 'image/png', data === 'iVBORw0KGgo='\n * ```\n \n @example\n * ```ts\n * decodeDataUrl('not-a-data-url'); // { mimeType: undefined, data: undefined }\n * ```\n /\nexport function decodeDataUrl(url: string): DecodedDataUrl {\n const regex = /^data:(.);base64,\\s?(.)$/;\n const matches = new RegExp(regex).exec(url);\n\n return {\n mimeType: matches?.[1],\n data: matches?.[2],\n };\n}\n\n/\n Returns `true` if `url` starts with `https://` or `http://` (case-sensitive, as in\n * `String#startsWith`). Does not validate that the rest is a well-formed URL — only the scheme\n * prefix. `blob:`, `data:`, and relative paths return `false`.\n \n @param url - String to test (often a user-provided or configured href).\n \n @example\n * ```ts\n * isHttpUrl('https://example.com/path'); // true\n * isHttpUrl('http://localhost:3000'); // true\n * ```\n \n @example\n * ```ts\n * isHttpUrl('//cdn.example.com'); // false — no explicit http(s) prefix\n * isHttpUrl('/assets/logo.png'); // false — relative path\n * ```\n /\nexport const isHttpUrl = (url: string): boolean => {\n return url.startsWith('https://') \|\| url.startsWith('http://');\n};\n\n/\n Returns `true` when `str` is a data URL that {@link decodeDataUrl} can parse and the MIME\n * type starts with `image/` (e.g. `image/png`, `image/jpeg`). Requires both a non-empty Base64\n * payload and an image MIME — arbitrary `data:text/plain;base64,...` is `false`.\n \n @param str - Candidate string (often `img.src` or API payload).\n \n @example\n * ```ts\n * isBase64Image('data:image/png;base64,iVBORw0KGgo='); // true\n * ```\n \n @example\n * ```ts\n * isBase64Image('https://example.com/x.png'); // false\n * isBase64Image('data:text/plain;base64,SGk='); // false\n * ```\n */\nexport const isBase64Image = (str: string): boolean => {\n const { mimeType, data } = decodeDataUrl(str);\n return !!(data && mimeType?.startsWith('image/'));\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,aAAa,MAA6B;AACxD,QAAO,IAAI,SAAS,SAAS,WAAW;EACtC,MAAM,SAAS,IAAI,YAAY;AAC/B,SAAO,kBAAkB,QAAQ,OAAO,OAAiB;AACzD,SAAO,UAAU;AACjB,SAAO,cAAc,KAAK;GAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BJ,IAAa,aAAa,cACxB,qBAAqB,OAAO,IAAI,gBAAgB,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;AAsB/D,IAAa,cAAc,SAAe;AACxC,QAAO,IAAI,KAAK,CAAC,KAAK,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA0B9C,IAAa,eACX,cACA,WAAmB,gBAChB;CACH,MAAM,SAAS,SAAS,cAAc,SAAS;AAE/C,QAAO,QAAQ,aAAa,gBAAgB;AAC5C,QAAO,SAAS,aAAa,iBAAiB;AAE9C,QAAO,WAAW,KAAK,CAAE,UAAU,cAAc,GAAG,EAAE;CAEtD,MAAM,UAAU,OAAO,UAAU,UAAU,EAAE;CAC7C,MAAM,aAAa,QAAQ,MAAM,IAAI,CAAC;CACtC,MAAM,iBAAiB,QAAQ,MAAM,IAAI,CAAC,GAAG,MAAM,EAAE;CAErD,MAAM,QAAQ,WAAW,KAAK,WAAW;CACzC,MAAM,MAAM,IAAI,YAAY,MAAM,OAAO;CACzC,MAAM,QAAQ,IAAI,WAAW,IAAI;AAEjC,MAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,QACxC,OAAM,SAAS,MAAM,WAAW,MAAM;AAKxC,QAFa,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,MAAM,gBAAgB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA4B1D,IAAa,eAAe,cAC1B,IAAI,SAA2B,SAAS,WAAW;CACjD,MAAM,QAAQ,IAAI,OAAO;AACzB,OAAM,MAAM,UAAU,UAAU;AAChC,OAAM,eAAe,QAAQ,MAAM;AACnC,OAAM,gBAAgB,QAAQ;EAC9B;AAEJ,SAAS,oBAAoB,SAAmC;CAC9D,MAAM,SAAS,QAAQ;CACvB,IAAI,IAAI,OAAO;CACf,IAAI,IAAI,OAAO;CACf,MAAM,MAAoC;EAAE,GAAG,EAAE;EAAE,GAAG,EAAE;EAAE;CAC1D,MAAM,YAAY,QAAQ,aAAa,GAAG,GAAG,OAAO,OAAO,OAAO,OAAO;CACzE,IAAI;CACJ,IAAI;CACJ,IAAI;AAEJ,MAAK,IAAI,GAAG,IAAI,GAAG,IACjB,MAAK,IAAI,GAAG,IAAI,GAAG,KAAK;AACtB,WAAS,IAAI,IAAI,KAAK;AACtB,MAAI,UAAU,KAAK,QAAQ,KAAK,GAAG;AACjC,OAAI,EAAE,KAAK,EAAE;AACb,OAAI,EAAE,KAAK,EAAE;;;AAInB,KAAI,EAAE,MAAM,GAAG,MAAM,IAAI,EAAE;AAC3B,KAAI,EAAE,MAAM,GAAG,MAAM,IAAI,EAAE;CAC3B,MAAM,IAAI,IAAI,EAAE,SAAS;AAEzB,KAAI,IAAI,IAAI,EAAE,KAAK,IAAI,EAAE;AACzB,KAAI,IAAI,IAAI,EAAE,KAAK,IAAI,EAAE;CACzB,MAAM,MAAM,QAAQ,aAAa,IAAI,EAAE,IAAI,IAAI,EAAE,IAAI,GAAG,EAAE;AAE1D,QAAO,QAAQ;AACf,QAAO,SAAS;AAChB,SAAQ,aAAa,KAAK,GAAG,EAAE;AAC/B,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA2BT,IAAa,eAAe,OAAyB,UAAkB;CACrE,MAAM,UAAU,KAAK,IAAI,MAAM,OAAO,MAAM,OAAO;CACnD,MAAM,SAAS,SAAS,cAAc,SAAS;AAC/C,QAAO,QAAQ;AACf,QAAO,SAAS;CAChB,MAAM,UAAU,OAAO,WAAW,KAAK;AACvC,SAAQ,MAAM;AACd,SAAQ,UAAU,OAAO,QAAQ,GAAG,OAAO,SAAS,EAAE;AACtD,SAAQ,OAAO,SAAS,MAAM,CAAC;AAC/B,SAAQ,UAAU,OAAO,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,SAAS,EAAE;AAC7D,SAAQ,SAAS;AACjB,qBAAoB,QAAQ;AAC5B,QAAO,YAAY,OAAO,UAAU,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;AA2BnD,SAAgB,cAAc,KAA6B;CAEzD,MAAM,2BAAU,IAAI,OADN,6BACmB,EAAC,KAAK,IAAI;AAE3C,QAAO;EACL,UAAU,UAAU;EACpB,MAAM,UAAU;EACjB;;;;;;;;;;;;;;;;;;;;;AAsBH,IAAa,aAAa,QAAyB;AACjD,QAAO,IAAI,WAAW,WAAW,IAAI,IAAI,WAAW,UAAU;;;;;;;;;;;;;;;;;;;;AAqBhE,IAAa,iBAAiB,QAAyB;CACrD,MAAM,EAAE,UAAU,SAAS,cAAc,IAAI;AAC7C,QAAO,CAAC,EAAE,QAAQ,UAAU,WAAW,SAAS"}

package/mobx.cjs CHANGED Viewed

@@ -4,6 +4,22 @@ let yummies_type_guard = require("yummies/type-guard");
 let mobx = require("mobx");
 //#region src/mobx/apply-observable.ts
 /**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* Compact **MobX `makeObservable`** wiring from tuple lists of annotations and keys. Reduces boilerplate
+* when many fields share `observable`, `action`, or `computed` decorators and you want one call site
+* instead of sprawling annotation maps across large stores.
+*
+* ## Usage
+*
+* ```ts
+* import { applyObservable } from "yummies/mobx";
+* ```
+*/
+/**
 * Applies a compact list of MobX annotations to an object using either
 * decorator-style invocation or the annotation map form accepted by `makeObservable`.
 *
@@ -43,6 +59,22 @@ var applyObservable = (context, annotationsArray, useDecorators) => {
 //#endregion
 //#region src/mobx/create-enhanced-atom.ts
 /**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **`createAtom` wrapper** that attaches arbitrary metadata and keeps MobX’s observed/unobserved
+* hooks in one place. Useful for custom reactive primitives, async resources, or debugging atoms
+* where the stock API is too bare.
+*
+* ## Usage
+*
+* ```ts
+* import { createEnhancedAtom } from "yummies/mobx";
+* ```
+*/
+/**
 * Creates a MobX atom extended with metadata and bound reporting methods.
 *
 * @template TMeta Metadata object stored on the atom.
@@ -74,6 +106,22 @@ var createEnhancedAtom = (name, onBecomeObservedHandler, onBecomeUnobservedHandl
 //#endregion
 //#region src/mobx/create-ref.ts
 /**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **Observable ref** pattern for MobX: boxed mutable references with change listeners, metadata,
+* and optional custom equality. Bridges React-style ref holders and MobX reactivity when a single
+* mutable cell must notify dependents without replacing the whole parent object graph.
+*
+* ## Usage
+*
+* ```ts
+* import { createRef } from "yummies/mobx";
+* ```
+*/
+/**
 * Creates a MobX-aware ref that behaves like a callback ref and exposes
 * observable `current` and `meta` fields.
 *
@@ -190,6 +238,22 @@ var toRef = (value, cfg) => {
 //#endregion
 //#region src/mobx/deep-observable-struct.ts
 /**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **Deep observable object** with structural `set` patches that reuse nested observables when keys
+* overlap. Helps store trees (forms, filters, entities) under MobX without wholesale replacement
+* and without manual `observable.map` wiring for every level.
+*
+* ## Usage
+*
+* ```ts
+* import { DeepObservableStruct } from "yummies/mobx";
+* ```
+*/
+/**
 * Wraps a plain object into a deeply observable structure and allows
 * patch-like updates while preserving nested observable references where possible.
 *
@@ -253,6 +317,22 @@ var DeepObservableStruct = class {
 //#endregion
 //#region src/mobx/get-mobx-administration.ts
 /**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* Typed access to MobX **internal administration** (`$mobx`) for advanced tooling, migration scripts,
+* or introspection. Prefer public MobX APIs in application code; reach for this when you must align
+* with library internals or patch behavior at the administration layer.
+*
+* ## Usage
+*
+* ```ts
+* import { getMobxAdministration } from "yummies/mobx";
+* ```
+*/
+/**
 * Returns the internal MobX administration object associated with an observable target.
 *
 * @param context Observable object instance.
@@ -273,6 +353,22 @@ var getMobxAdministration = (context) => context[mobx.$mobx];
 //#endregion
 //#region src/mobx/lazy-observe.ts
 /**
+* ---header-docs-section---
+* # yummies/mobx
+*
+* ## Description
+*
+* **Lazy subscriptions** tied to MobX observation: start work when the first reaction observes
+* tracked keys, stop when nothing listens anymore (optionally after a delay). Ideal for polling,
+* WebSocket feeds, or expensive caches that should idle when the UI is not mounted.
+*
+* ## Usage
+*
+* ```ts
+* import { lazyObserve } from "yummies/mobx";
+* ```
+*/
+/**
 * Starts side effects only while one or more MobX observables are being observed.
 *
 * When the first property becomes observed, `onStart` is called. When all tracked

package/mobx.cjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"mobx.cjs","names":[],"sources":["../src/mobx/apply-observable.ts","../src/mobx/create-enhanced-atom.ts","../src/mobx/create-ref.ts","../src/mobx/deep-observable-struct.ts","../src/mobx/get-mobx-administration.ts","../src/mobx/lazy-observe.ts"],"sourcesContent":["import { type AnnotationMapEntry, makeObservable } from 'mobx';\nimport type { AnyObject } from 'yummies/types';\n\nexport type ObservableAnnotationsArray<T extends AnyObject = AnyObject> = [\n AnnotationMapEntry,\n ...(keyof T \| (string & {}))[],\n][];\n\n/*\n Applies a compact list of MobX annotations to an object using either\n * decorator-style invocation or the annotation map form accepted by `makeObservable`.\n \n @template T Target object type.\n * @param context Object that should become observable.\n * @param annotationsArray Tuples of annotation followed by annotated field names.\n * @param useDecorators Enables decorator-style application before calling `makeObservable`.\n \n @example\n * ```ts\n * applyObservable(store, [[observable, 'items'], [action, 'setItems']]);\n * ```\n \n @example\n * ```ts\n * applyObservable(viewModel, [[computed, 'fullName']], true);\n * ```\n /\nexport const applyObservable = <T extends AnyObject>(\n context: T,\n annotationsArray: ObservableAnnotationsArray<T>,\n useDecorators?: boolean,\n) => {\n if (useDecorators) {\n annotationsArray.forEach(([annotation, ...fields]) => {\n fields.forEach((field) => {\n // @ts-expect-error\n annotation(context, field);\n });\n });\n\n makeObservable(context);\n } else {\n const annotationsObject: AnyObject = {};\n\n annotationsArray.forEach(([annotation, ...fields]) => {\n fields.forEach((field) => {\n annotationsObject[field] = annotation;\n });\n });\n\n makeObservable(context, annotationsObject);\n }\n};\n","import { createAtom, type IAtom } from 'mobx';\nimport type { AnyObject } from 'yummies/types';\n\nexport interface IEnhancedAtom<TMeta extends AnyObject = AnyObject>\n extends IAtom {\n meta: TMeta;\n}\n\n/\n Creates a MobX atom extended with metadata and bound reporting methods.\n \n @template TMeta Metadata object stored on the atom.\n * @param name Atom name used by MobX for debugging.\n * @param onBecomeObservedHandler Callback fired when the atom becomes observed.\n * @param onBecomeUnobservedHandler Callback fired when the atom is no longer observed.\n * @param meta Optional metadata attached to the atom.\n * @returns Atom instance with `meta`, `reportChanged` and `reportObserved`.\n \n @example\n * ```ts\n * const atom = createEnhancedAtom('user-status');\n * atom.reportChanged();\n * ```\n \n @example\n * ```ts\n * const atom = createEnhancedAtom('cache', undefined, undefined, { scope: 'users' });\n * atom.meta.scope;\n * ```\n /\nexport const createEnhancedAtom = <TMeta extends AnyObject>(\n name: string,\n onBecomeObservedHandler?: (atom: IEnhancedAtom<TMeta>) => void,\n onBecomeUnobservedHandler?: (atom: IEnhancedAtom<TMeta>) => void,\n meta?: TMeta,\n): IEnhancedAtom<TMeta> => {\n const atom = createAtom(\n name,\n onBecomeObservedHandler && (() => onBecomeObservedHandler(atom)),\n onBecomeUnobservedHandler && (() => onBecomeUnobservedHandler(atom)),\n ) as IEnhancedAtom<TMeta>;\n atom.meta = meta ?? ({} as TMeta);\n atom.reportChanged = atom.reportChanged.bind(atom);\n atom.reportObserved = atom.reportObserved.bind(atom);\n return atom;\n};\n","import {\n type IEqualsComparer,\n makeObservable,\n comparer as mobxComparer,\n observable,\n runInAction,\n} from 'mobx';\nimport type { AnyObject, Maybe } from 'yummies/types';\n\n/\n You can return `false` if you don't want to change the value in this ref\n /\nexport type RefChangeListener<T> = (\n value: T \| null,\n prevValue: T \| undefined,\n) => void \| false;\n\n/\n Alternative to React.createRef but works in MobX world.\n * Typically it the should be the same React.LegacyRef (fn style)\n /\nexport interface Ref<T = any, TMeta = AnyObject> {\n /\n Setter function\n /\n (value: Maybe<T>): void;\n\n set(value: Maybe<T>): void;\n listeners: Set<RefChangeListener<NoInfer<T>>>;\n current: NoInfer<T> \| null;\n meta: TMeta;\n}\n\nexport interface CreateRefConfig<T = any, TMeta = AnyObject> {\n onSet?: (node: T, prevValue: T \| undefined) => void;\n onUnset?: (lastValue: T \| undefined) => void;\n onChange?: RefChangeListener<T>;\n meta?: TMeta;\n initial?: Maybe<T>;\n comparer?: IEqualsComparer<T \| null>;\n}\n\n/\n Creates a MobX-aware ref that behaves like a callback ref and exposes\n * observable `current` and `meta` fields.\n \n @template T Referenced value type.\n * @template TMeta Additional observable metadata stored on the ref.\n * @param cfg Optional callbacks, initial value and comparer configuration.\n * @returns Observable ref function object.\n \n @example\n * ```ts\n * const inputRef = createRef<HTMLInputElement>();\n * inputRef.set(document.createElement('input'));\n * ```\n \n @example\n * ```ts\n * const ref = createRef<number>();\n * ref(3);\n * ref.current; // 3\n * ```\n \n @example\n * ```ts\n * const nodeRef = createRef({\n * onUnset: () => console.log('detached'),\n * meta: { mounted: false },\n * });\n * ```\n /\nexport const createRef = <T = any, TMeta = AnyObject>(\n cfg?: CreateRefConfig<T, TMeta>,\n): Ref<T, TMeta> => {\n let lastValue: T \| undefined;\n const comparer = cfg?.comparer ?? mobxComparer.default;\n\n const setValue: Ref<T, TMeta>['set'] = (value) => {\n const nextValue = value ?? null;\n\n if (comparer(ref.current, nextValue)) {\n return;\n }\n\n runInAction(() => {\n const prevLastValue = lastValue;\n lastValue = ref.current ?? undefined;\n ref.current = nextValue;\n\n let isNextValueIgnored = false;\n\n ref.listeners.forEach((listener) => {\n const listenerResult = listener(ref.current, lastValue);\n\n if (listenerResult === false) {\n isNextValueIgnored = true;\n }\n });\n\n if (isNextValueIgnored) {\n lastValue = prevLastValue;\n ref.current = lastValue ?? null;\n } else if (ref.current === null && lastValue !== undefined) {\n lastValue = undefined;\n }\n });\n };\n\n const ref = setValue as Ref<T, TMeta>;\n\n ref.set = setValue;\n\n ref.listeners = new Set(cfg?.onChange ? [cfg.onChange] : []);\n\n if (cfg?.onSet \|\| cfg?.onUnset) {\n ref.listeners.add((value, prevValue) => {\n if (value) {\n cfg.onSet?.(value, prevValue);\n } else {\n cfg.onUnset?.(prevValue);\n }\n });\n }\n\n ref.current = cfg?.initial ?? null;\n ref.meta = cfg?.meta ?? ({} as TMeta);\n\n makeObservable(ref, {\n current: observable.ref,\n meta: observable,\n });\n\n return ref;\n};\n\n/\n Checks whether the provided value is a ref created by `createRef`.\n \n @template T Referenced value type.\n * @template TMeta Ref metadata type.\n * @param value Value to inspect.\n * @returns `true` when the value is a ref-like function with `current`.\n \n @example\n * ```ts\n * const ref = createRef<number>();\n * isRef(ref); // true\n * ```\n \n @example\n * ```ts\n * isRef({ current: 1 }); // false\n * ```\n /\nexport const isRef = <T, TMeta = any>(\n value: T \| Ref<T, TMeta>,\n): value is Ref<T, TMeta> => {\n return typeof value === 'function' && 'current' in value;\n};\n\n/\n Normalizes a plain value or an existing ref into a `Ref` instance.\n \n @template T Referenced value type.\n * @template TMeta Ref metadata type.\n * @param value Existing ref or initial plain value.\n * @param cfg Optional ref configuration applied when a new ref is created.\n * @returns Existing ref or a newly created ref initialized with `value`.\n \n @example\n * ```ts\n * const ref = toRef(document.body);\n * ref.current === document.body;\n * ```\n \n @example\n * ```ts\n * const existingRef = createRef<number>();\n * const sameRef = toRef(existingRef);\n * ```\n /\nexport const toRef = <T, TMeta = any>(\n value: T \| Ref<T, TMeta>,\n cfg?: Omit<CreateRefConfig<T, TMeta>, 'initial'>,\n): Ref<T, TMeta> => {\n return isRef(value) ? value : createRef({ initial: value, ...cfg });\n};\n","import { action, makeObservable, observable } from 'mobx';\nimport { typeGuard } from 'yummies/type-guard';\nimport type { AnyObject } from 'yummies/types';\n\n/\n Wraps a plain object into a deeply observable structure and allows\n * patch-like updates while preserving nested observable references where possible.\n \n @template TData Observable object shape.\n \n @example\n * ```ts\n * const state = new DeepObservableStruct({ user: { name: 'Ann' } });\n * state.set({ user: { name: 'Bob' } });\n * ```\n \n @example\n * ```ts\n * const state = new DeepObservableStruct({ filters: { active: true } });\n * state.set({ filters: { active: false, archived: true } });\n * ```\n /\nexport class DeepObservableStruct<TData extends AnyObject> {\n data: TData;\n\n constructor(data: TData) {\n this.data = data;\n\n makeObservable(this, {\n data: observable.deep,\n set: action,\n });\n }\n\n set(newData: Partial<TData>) {\n type StackItem = [key: string, currObservable: AnyObject, new: AnyObject];\n\n const stack: StackItem[] = Object.keys(this.data).map((key) => [\n key,\n this.data,\n newData,\n ]);\n\n let currentIndex = 0;\n let stackLength = stack.length;\n\n while (currentIndex < stackLength) {\n const [key, currObservableData, newData] = stack[currentIndex];\n const newValue = newData[key];\n const currValue = currObservableData[key];\n\n currentIndex++;\n\n if (key in newData) {\n if (typeGuard.isObject(newValue) && typeGuard.isObject(currValue)) {\n const newValueKeys = Object.keys(newValue);\n\n Object.keys(currValue).forEach((childKey) => {\n if (!(childKey in newValue)) {\n delete currObservableData[key][childKey];\n }\n });\n\n newValueKeys.forEach((childKey) => {\n const length = stack.push([\n childKey,\n currObservableData[key],\n newValue,\n ]);\n stackLength = length;\n });\n } else if (newValue !== currValue) {\n currObservableData[key] = newValue;\n }\n } else {\n delete currObservableData[key];\n }\n }\n\n Object.keys(newData).forEach((newDataKey) => {\n if (!this.data[newDataKey]) {\n // @ts-expect-error\n this.data[newDataKey] = newData[newDataKey];\n }\n });\n }\n}\n","import { $mobx, type AnnotationMapEntry } from 'mobx';\nimport type { AnyObject } from 'yummies/types';\n\ntype ObservableObjectAdministration = Parameters<\n Exclude<AnnotationMapEntry, boolean>['make_']\n>[0];\n\n/\n Returns the internal MobX administration object associated with an observable target.\n \n @param context Observable object instance.\n * @returns MobX administration internals stored under `$mobx`.\n \n @example\n * ```ts\n * const admin = getMobxAdministration(store);\n * admin.name_;\n * ```\n \n @example\n * ```ts\n * const values = getMobxAdministration(formState).values_;\n * ```\n /\nexport const getMobxAdministration = (\n context: AnyObject,\n): ObservableObjectAdministration => context[$mobx];\n","import { onBecomeObserved, onBecomeUnobserved } from 'mobx';\n\n/\n Starts side effects only while one or more MobX observables are being observed.\n \n When the first property becomes observed, `onStart` is called. When all tracked\n * properties become unobserved, `onEnd` is called with the value returned by\n * `onStart`. Cleanup can be delayed via `endDelay`.\n \n It uses MobX `onBecomeObserved` and `onBecomeUnobserved` hooks to perform\n * lazy subscription management.\n \n @template TMetaData Data returned from `onStart` and forwarded to `onEnd`.\n * @param config Configuration for tracked properties and lifecycle callbacks.\n * @returns Cleanup function that clears the tracked state and runs `onEnd`.\n \n @example\n * ```ts\n * const stop = lazyObserve({\n * context: store,\n * property: 'items',\n * onStart: () => api.subscribe(),\n * onEnd: (subscription) => subscription.unsubscribe(),\n * });\n * ```\n \n @example\n * ```ts\n * lazyObserve({\n * property: [boxA, boxB],\n * onStart: () => console.log('observed'),\n * endDelay: 300,\n * });\n * ```\n */\nexport const lazyObserve = <TMetaData = void>({\n context,\n property,\n onStart,\n onEnd,\n endDelay = false,\n}: {\n context?: any;\n property: any \| any[];\n onStart?: () => TMetaData;\n onEnd?: (metaData: TMetaData, cleanupFn: VoidFunction) => void;\n endDelay?: number \| false;\n}) => {\n let timeoutId: ReturnType<typeof setTimeout> \| undefined;\n let metaData: TMetaData \| undefined;\n const observingProps = new Set<string>();\n const properties = Array.isArray(property) ? property : [property];\n\n const cleanup = () => {\n observingProps.clear();\n\n if (endDelay === false) {\n onEnd?.(metaData!, cleanup);\n metaData = undefined;\n return;\n }\n\n if (timeoutId) {\n clearTimeout(timeoutId);\n timeoutId = undefined;\n }\n\n timeoutId = setTimeout(() => {\n onEnd?.(metaData!, cleanup);\n timeoutId = undefined;\n metaData = undefined;\n }, endDelay);\n };\n\n const start = (property: string) => {\n const isAlreadyObserving = observingProps.size > 0;\n observingProps.add(property);\n\n if (isAlreadyObserving) {\n return;\n }\n\n if (timeoutId) {\n clearTimeout(timeoutId);\n timeoutId = undefined;\n }\n\n metaData = onStart?.();\n };\n\n const stop = (property: string) => {\n const isAlreadyNotObserving = !observingProps.size;\n\n observingProps.delete(property);\n\n const isObserving = observingProps.size > 0;\n\n if (isAlreadyNotObserving \|\| isObserving) {\n return;\n }\n\n cleanup();\n };\n\n properties.forEach((property) => {\n if (context) {\n onBecomeObserved(context, property, () => start(property));\n onBecomeUnobserved(context, property, () => stop(property));\n } else {\n onBecomeObserved(property, () => start(property));\n onBecomeUnobserved(property, () => stop(property));\n }\n });\n\n return cleanup;\n};\n"],"mappings":"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"}
1	+ {"version":3,"file":"mobx.cjs","names":[],"sources":["../src/mobx/apply-observable.ts","../src/mobx/create-enhanced-atom.ts","../src/mobx/create-ref.ts","../src/mobx/deep-observable-struct.ts","../src/mobx/get-mobx-administration.ts","../src/mobx/lazy-observe.ts"],"sourcesContent":["/*\n ---header-docs-section---\n * # yummies/mobx\n \n ## Description\n \n Compact MobX `makeObservable` wiring from tuple lists of annotations and keys. Reduces boilerplate\n * when many fields share `observable`, `action`, or `computed` decorators and you want one call site\n * instead of sprawling annotation maps across large stores.\n \n ## Usage\n \n ```ts\n * import { applyObservable } from \"yummies/mobx\";\n * ```\n /\n\nimport { type AnnotationMapEntry, makeObservable } from 'mobx';\nimport type { AnyObject } from 'yummies/types';\n\nexport type ObservableAnnotationsArray<T extends AnyObject = AnyObject> = [\n AnnotationMapEntry,\n ...(keyof T \| (string & {}))[],\n][];\n\n/\n Applies a compact list of MobX annotations to an object using either\n * decorator-style invocation or the annotation map form accepted by `makeObservable`.\n \n @template T Target object type.\n * @param context Object that should become observable.\n * @param annotationsArray Tuples of annotation followed by annotated field names.\n * @param useDecorators Enables decorator-style application before calling `makeObservable`.\n \n @example\n * ```ts\n * applyObservable(store, [[observable, 'items'], [action, 'setItems']]);\n * ```\n \n @example\n * ```ts\n * applyObservable(viewModel, [[computed, 'fullName']], true);\n * ```\n /\nexport const applyObservable = <T extends AnyObject>(\n context: T,\n annotationsArray: ObservableAnnotationsArray<T>,\n useDecorators?: boolean,\n) => {\n if (useDecorators) {\n annotationsArray.forEach(([annotation, ...fields]) => {\n fields.forEach((field) => {\n // @ts-expect-error\n annotation(context, field);\n });\n });\n\n makeObservable(context);\n } else {\n const annotationsObject: AnyObject = {};\n\n annotationsArray.forEach(([annotation, ...fields]) => {\n fields.forEach((field) => {\n annotationsObject[field] = annotation;\n });\n });\n\n makeObservable(context, annotationsObject);\n }\n};\n","/\n ---header-docs-section---\n * # yummies/mobx\n \n ## Description\n \n `createAtom` wrapper that attaches arbitrary metadata and keeps MobX’s observed/unobserved\n * hooks in one place. Useful for custom reactive primitives, async resources, or debugging atoms\n * where the stock API is too bare.\n \n ## Usage\n \n ```ts\n * import { createEnhancedAtom } from \"yummies/mobx\";\n * ```\n /\n\nimport { createAtom, type IAtom } from 'mobx';\nimport type { AnyObject } from 'yummies/types';\n\nexport interface IEnhancedAtom<TMeta extends AnyObject = AnyObject>\n extends IAtom {\n meta: TMeta;\n}\n\n/\n Creates a MobX atom extended with metadata and bound reporting methods.\n \n @template TMeta Metadata object stored on the atom.\n * @param name Atom name used by MobX for debugging.\n * @param onBecomeObservedHandler Callback fired when the atom becomes observed.\n * @param onBecomeUnobservedHandler Callback fired when the atom is no longer observed.\n * @param meta Optional metadata attached to the atom.\n * @returns Atom instance with `meta`, `reportChanged` and `reportObserved`.\n \n @example\n * ```ts\n * const atom = createEnhancedAtom('user-status');\n * atom.reportChanged();\n * ```\n \n @example\n * ```ts\n * const atom = createEnhancedAtom('cache', undefined, undefined, { scope: 'users' });\n * atom.meta.scope;\n * ```\n /\nexport const createEnhancedAtom = <TMeta extends AnyObject>(\n name: string,\n onBecomeObservedHandler?: (atom: IEnhancedAtom<TMeta>) => void,\n onBecomeUnobservedHandler?: (atom: IEnhancedAtom<TMeta>) => void,\n meta?: TMeta,\n): IEnhancedAtom<TMeta> => {\n const atom = createAtom(\n name,\n onBecomeObservedHandler && (() => onBecomeObservedHandler(atom)),\n onBecomeUnobservedHandler && (() => onBecomeUnobservedHandler(atom)),\n ) as IEnhancedAtom<TMeta>;\n atom.meta = meta ?? ({} as TMeta);\n atom.reportChanged = atom.reportChanged.bind(atom);\n atom.reportObserved = atom.reportObserved.bind(atom);\n return atom;\n};\n","/\n ---header-docs-section---\n * # yummies/mobx\n \n ## Description\n \n Observable ref pattern for MobX: boxed mutable references with change listeners, metadata,\n * and optional custom equality. Bridges React-style ref holders and MobX reactivity when a single\n * mutable cell must notify dependents without replacing the whole parent object graph.\n \n ## Usage\n \n ```ts\n * import { createRef } from \"yummies/mobx\";\n * ```\n /\n\nimport {\n type IEqualsComparer,\n makeObservable,\n comparer as mobxComparer,\n observable,\n runInAction,\n} from 'mobx';\nimport type { AnyObject, Maybe } from 'yummies/types';\n\n/\n You can return `false` if you don't want to change the value in this ref\n /\nexport type RefChangeListener<T> = (\n value: T \| null,\n prevValue: T \| undefined,\n) => void \| false;\n\n/\n Alternative to React.createRef but works in MobX world.\n * Typically it the should be the same React.LegacyRef (fn style)\n /\nexport interface Ref<T = any, TMeta = AnyObject> {\n /\n Setter function\n /\n (value: Maybe<T>): void;\n\n set(value: Maybe<T>): void;\n listeners: Set<RefChangeListener<NoInfer<T>>>;\n current: NoInfer<T> \| null;\n meta: TMeta;\n}\n\nexport interface CreateRefConfig<T = any, TMeta = AnyObject> {\n onSet?: (node: T, prevValue: T \| undefined) => void;\n onUnset?: (lastValue: T \| undefined) => void;\n onChange?: RefChangeListener<T>;\n meta?: TMeta;\n initial?: Maybe<T>;\n comparer?: IEqualsComparer<T \| null>;\n}\n\n/\n Creates a MobX-aware ref that behaves like a callback ref and exposes\n * observable `current` and `meta` fields.\n \n @template T Referenced value type.\n * @template TMeta Additional observable metadata stored on the ref.\n * @param cfg Optional callbacks, initial value and comparer configuration.\n * @returns Observable ref function object.\n \n @example\n * ```ts\n * const inputRef = createRef<HTMLInputElement>();\n * inputRef.set(document.createElement('input'));\n * ```\n \n @example\n * ```ts\n * const ref = createRef<number>();\n * ref(3);\n * ref.current; // 3\n * ```\n \n @example\n * ```ts\n * const nodeRef = createRef({\n * onUnset: () => console.log('detached'),\n * meta: { mounted: false },\n * });\n * ```\n /\nexport const createRef = <T = any, TMeta = AnyObject>(\n cfg?: CreateRefConfig<T, TMeta>,\n): Ref<T, TMeta> => {\n let lastValue: T \| undefined;\n const comparer = cfg?.comparer ?? mobxComparer.default;\n\n const setValue: Ref<T, TMeta>['set'] = (value) => {\n const nextValue = value ?? null;\n\n if (comparer(ref.current, nextValue)) {\n return;\n }\n\n runInAction(() => {\n const prevLastValue = lastValue;\n lastValue = ref.current ?? undefined;\n ref.current = nextValue;\n\n let isNextValueIgnored = false;\n\n ref.listeners.forEach((listener) => {\n const listenerResult = listener(ref.current, lastValue);\n\n if (listenerResult === false) {\n isNextValueIgnored = true;\n }\n });\n\n if (isNextValueIgnored) {\n lastValue = prevLastValue;\n ref.current = lastValue ?? null;\n } else if (ref.current === null && lastValue !== undefined) {\n lastValue = undefined;\n }\n });\n };\n\n const ref = setValue as Ref<T, TMeta>;\n\n ref.set = setValue;\n\n ref.listeners = new Set(cfg?.onChange ? [cfg.onChange] : []);\n\n if (cfg?.onSet \|\| cfg?.onUnset) {\n ref.listeners.add((value, prevValue) => {\n if (value) {\n cfg.onSet?.(value, prevValue);\n } else {\n cfg.onUnset?.(prevValue);\n }\n });\n }\n\n ref.current = cfg?.initial ?? null;\n ref.meta = cfg?.meta ?? ({} as TMeta);\n\n makeObservable(ref, {\n current: observable.ref,\n meta: observable,\n });\n\n return ref;\n};\n\n/\n Checks whether the provided value is a ref created by `createRef`.\n \n @template T Referenced value type.\n * @template TMeta Ref metadata type.\n * @param value Value to inspect.\n * @returns `true` when the value is a ref-like function with `current`.\n \n @example\n * ```ts\n * const ref = createRef<number>();\n * isRef(ref); // true\n * ```\n \n @example\n * ```ts\n * isRef({ current: 1 }); // false\n * ```\n /\nexport const isRef = <T, TMeta = any>(\n value: T \| Ref<T, TMeta>,\n): value is Ref<T, TMeta> => {\n return typeof value === 'function' && 'current' in value;\n};\n\n/\n Normalizes a plain value or an existing ref into a `Ref` instance.\n \n @template T Referenced value type.\n * @template TMeta Ref metadata type.\n * @param value Existing ref or initial plain value.\n * @param cfg Optional ref configuration applied when a new ref is created.\n * @returns Existing ref or a newly created ref initialized with `value`.\n \n @example\n * ```ts\n * const ref = toRef(document.body);\n * ref.current === document.body;\n * ```\n \n @example\n * ```ts\n * const existingRef = createRef<number>();\n * const sameRef = toRef(existingRef);\n * ```\n /\nexport const toRef = <T, TMeta = any>(\n value: T \| Ref<T, TMeta>,\n cfg?: Omit<CreateRefConfig<T, TMeta>, 'initial'>,\n): Ref<T, TMeta> => {\n return isRef(value) ? value : createRef({ initial: value, ...cfg });\n};\n","/\n ---header-docs-section---\n * # yummies/mobx\n \n ## Description\n \n Deep observable object with structural `set` patches that reuse nested observables when keys\n * overlap. Helps store trees (forms, filters, entities) under MobX without wholesale replacement\n * and without manual `observable.map` wiring for every level.\n \n ## Usage\n \n ```ts\n * import { DeepObservableStruct } from \"yummies/mobx\";\n * ```\n /\n\nimport { action, makeObservable, observable } from 'mobx';\nimport { typeGuard } from 'yummies/type-guard';\nimport type { AnyObject } from 'yummies/types';\n\n/\n Wraps a plain object into a deeply observable structure and allows\n * patch-like updates while preserving nested observable references where possible.\n \n @template TData Observable object shape.\n \n @example\n * ```ts\n * const state = new DeepObservableStruct({ user: { name: 'Ann' } });\n * state.set({ user: { name: 'Bob' } });\n * ```\n \n @example\n * ```ts\n * const state = new DeepObservableStruct({ filters: { active: true } });\n * state.set({ filters: { active: false, archived: true } });\n * ```\n /\nexport class DeepObservableStruct<TData extends AnyObject> {\n data: TData;\n\n constructor(data: TData) {\n this.data = data;\n\n makeObservable(this, {\n data: observable.deep,\n set: action,\n });\n }\n\n set(newData: Partial<TData>) {\n type StackItem = [key: string, currObservable: AnyObject, new: AnyObject];\n\n const stack: StackItem[] = Object.keys(this.data).map((key) => [\n key,\n this.data,\n newData,\n ]);\n\n let currentIndex = 0;\n let stackLength = stack.length;\n\n while (currentIndex < stackLength) {\n const [key, currObservableData, newData] = stack[currentIndex];\n const newValue = newData[key];\n const currValue = currObservableData[key];\n\n currentIndex++;\n\n if (key in newData) {\n if (typeGuard.isObject(newValue) && typeGuard.isObject(currValue)) {\n const newValueKeys = Object.keys(newValue);\n\n Object.keys(currValue).forEach((childKey) => {\n if (!(childKey in newValue)) {\n delete currObservableData[key][childKey];\n }\n });\n\n newValueKeys.forEach((childKey) => {\n const length = stack.push([\n childKey,\n currObservableData[key],\n newValue,\n ]);\n stackLength = length;\n });\n } else if (newValue !== currValue) {\n currObservableData[key] = newValue;\n }\n } else {\n delete currObservableData[key];\n }\n }\n\n Object.keys(newData).forEach((newDataKey) => {\n if (!this.data[newDataKey]) {\n // @ts-expect-error\n this.data[newDataKey] = newData[newDataKey];\n }\n });\n }\n}\n","/\n ---header-docs-section---\n * # yummies/mobx\n \n ## Description\n \n Typed access to MobX internal administration (`$mobx`) for advanced tooling, migration scripts,\n * or introspection. Prefer public MobX APIs in application code; reach for this when you must align\n * with library internals or patch behavior at the administration layer.\n \n ## Usage\n \n ```ts\n * import { getMobxAdministration } from \"yummies/mobx\";\n * ```\n /\n\nimport { $mobx, type AnnotationMapEntry } from 'mobx';\nimport type { AnyObject } from 'yummies/types';\n\ntype ObservableObjectAdministration = Parameters<\n Exclude<AnnotationMapEntry, boolean>['make_']\n>[0];\n\n/\n Returns the internal MobX administration object associated with an observable target.\n \n @param context Observable object instance.\n * @returns MobX administration internals stored under `$mobx`.\n \n @example\n * ```ts\n * const admin = getMobxAdministration(store);\n * admin.name_;\n * ```\n \n @example\n * ```ts\n * const values = getMobxAdministration(formState).values_;\n * ```\n /\nexport const getMobxAdministration = (\n context: AnyObject,\n): ObservableObjectAdministration => context[$mobx];\n","/\n ---header-docs-section---\n * # yummies/mobx\n \n ## Description\n \n Lazy subscriptions tied to MobX observation: start work when the first reaction observes\n * tracked keys, stop when nothing listens anymore (optionally after a delay). Ideal for polling,\n * WebSocket feeds, or expensive caches that should idle when the UI is not mounted.\n \n ## Usage\n \n ```ts\n * import { lazyObserve } from \"yummies/mobx\";\n * ```\n /\n\nimport { onBecomeObserved, onBecomeUnobserved } from 'mobx';\n\n/\n Starts side effects only while one or more MobX observables are being observed.\n \n When the first property becomes observed, `onStart` is called. When all tracked\n * properties become unobserved, `onEnd` is called with the value returned by\n * `onStart`. Cleanup can be delayed via `endDelay`.\n \n It uses MobX `onBecomeObserved` and `onBecomeUnobserved` hooks to perform\n * lazy subscription management.\n \n @template TMetaData Data returned from `onStart` and forwarded to `onEnd`.\n * @param config Configuration for tracked properties and lifecycle callbacks.\n * @returns Cleanup function that clears the tracked state and runs `onEnd`.\n \n @example\n * ```ts\n * const stop = lazyObserve({\n * context: store,\n * property: 'items',\n * onStart: () => api.subscribe(),\n * onEnd: (subscription) => subscription.unsubscribe(),\n * });\n * ```\n \n @example\n * ```ts\n * lazyObserve({\n * property: [boxA, boxB],\n * onStart: () => console.log('observed'),\n * endDelay: 300,\n * });\n * ```\n */\nexport const lazyObserve = <TMetaData = void>({\n context,\n property,\n onStart,\n onEnd,\n endDelay = false,\n}: {\n context?: any;\n property: any \| any[];\n onStart?: () => TMetaData;\n onEnd?: (metaData: TMetaData, cleanupFn: VoidFunction) => void;\n endDelay?: number \| false;\n}) => {\n let timeoutId: ReturnType<typeof setTimeout> \| undefined;\n let metaData: TMetaData \| undefined;\n const observingProps = new Set<string>();\n const properties = Array.isArray(property) ? property : [property];\n\n const cleanup = () => {\n observingProps.clear();\n\n if (endDelay === false) {\n onEnd?.(metaData!, cleanup);\n metaData = undefined;\n return;\n }\n\n if (timeoutId) {\n clearTimeout(timeoutId);\n timeoutId = undefined;\n }\n\n timeoutId = setTimeout(() => {\n onEnd?.(metaData!, cleanup);\n timeoutId = undefined;\n metaData = undefined;\n }, endDelay);\n };\n\n const start = (property: string) => {\n const isAlreadyObserving = observingProps.size > 0;\n observingProps.add(property);\n\n if (isAlreadyObserving) {\n return;\n }\n\n if (timeoutId) {\n clearTimeout(timeoutId);\n timeoutId = undefined;\n }\n\n metaData = onStart?.();\n };\n\n const stop = (property: string) => {\n const isAlreadyNotObserving = !observingProps.size;\n\n observingProps.delete(property);\n\n const isObserving = observingProps.size > 0;\n\n if (isAlreadyNotObserving \|\| isObserving) {\n return;\n }\n\n cleanup();\n };\n\n properties.forEach((property) => {\n if (context) {\n onBecomeObserved(context, property, () => start(property));\n onBecomeUnobserved(context, property, () => stop(property));\n } else {\n onBecomeObserved(property, () => start(property));\n onBecomeUnobserved(property, () => stop(property));\n }\n });\n\n return cleanup;\n};\n"],"mappings":"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"}