@vielzeug/arsenal 1.1.1 → 2.0.0

package/dist/_common/_secureRandomIndex.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"_secureRandomIndex.js","names":[],"sources":["../../src/_common/_secureRandomIndex.ts"],"sourcesContent":["/**\n * Returns a cryptographically random integer in `[0, exclusiveMax)` via `crypto.getRandomValues`.\n * Shared by `random()`, `shuffle()`, and `drawMany()` — the single source of truth for converting\n * a random `Uint32` into a bounded index.\n *\n * Module-private: underscore-prefixed file is excluded from barrel exports.\n * @internal\n */\nexport function secureRandomIndex(exclusiveMax: number): number {\n  // Divide by 0x100000000 (not 0xffffffff) to produce [0, 1) instead of [0, 1]\n  const randomValue = crypto.getRandomValues(new Uint32Array(1))[0]! / 0x100000000;\n\n  return Math.floor(randomValue * exclusiveMax);\n}\n"],"mappings":";AAQA,SAAgB,EAAkB,GAA8B;CAE9D,IAAM,IAAc,OAAO,gCAAgB,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,KAAM;CAErE,OAAO,KAAK,MAAM,IAAc,CAAY;AAC9C"}

package/dist/async/queue.cjs

@@ -1,2 +0,0 @@
-const e=require("../errors.cjs");function t(t={}){let{concurrency:n=1}=t;if(n<1)throw new e.ArsenalValidationError(`Concurrency must be at least 1`);let r=0,i=!1,a=null,o=null,s=[],c=new Set,l=()=>{r===0&&s.length===0&&o&&(o(),a=null,o=null)},u=e=>{for(let t of c)t(e)},d=()=>{if(!i){for(i=!0;r<n&&s.length>0;){let e=s.shift();r++,Promise.resolve().then(()=>e.fn()).then(t=>{u({ok:!0,value:t}),e.resolve(t)}).catch(t=>{u({error:t,ok:!1}),e.reject(t)}).finally(()=>{r--,d(),l()})}i=!1,l()}};return{get active(){return r},add:(e,t)=>{let{promise:n,reject:r,resolve:i}=Promise.withResolvers(),a=t?.priority??0,o={fn:e,priority:a,reject:r,resolve:i},c=s.length;for(;c>0&&s[c-1].priority<a;)c--;return s.splice(c,0,o),d(),n},clear:e=>{let t=e??Error(`Queue cleared`);for(let e of s.splice(0))e.reject(t);l()},onIdle:()=>{if(r===0&&s.length===0)return Promise.resolve();if(!a){let e=Promise.withResolvers();a=e.promise,o=e.resolve}return a},onSettled:e=>(c.add(e),()=>{c.delete(e)}),get pending(){return s.length},get size(){return r+s.length}}}exports.queue=t;
-//# sourceMappingURL=queue.cjs.map

package/dist/async/queue.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"queue.cjs","names":[],"sources":["../../src/async/queue.ts"],"sourcesContent":["import type { AttemptResult } from './attempt';\n\nimport { ArsenalValidationError } from '../errors';\n\n/**\n * Creates a promise queue that processes promises sequentially with optional concurrency limit.\n *\n * @example\n * ```ts\n * const requestQueue = queue({ concurrency: 2 });\n *\n * requestQueue.add(() => fetch('/api/1'));\n * requestQueue.add(() => fetch('/api/2'));\n * requestQueue.add(() => fetch('/api/3'));\n *\n * await requestQueue.onIdle(); // Wait for all tasks to complete\n * ```\n *\n * @param options - Queue configuration\n * @param options.concurrency - Maximum number of concurrent promises (default: 1)\n * @returns Queue instance with add, onIdle, clear, and onSettled methods\n */\nexport type QueueSettledCallback<T = unknown> = (result: AttemptResult<T>) => void;\n\nexport interface Queue {\n  /** Adds a task to the queue. Returns a promise that resolves/rejects with the task result. */\n  add<T>(fn: () => Promise<T>, options?: { priority?: number }): Promise<T>;\n  /** Clears all pending tasks, rejecting them with the given reason. Running tasks are unaffected. */\n  clear(reason?: unknown): void;\n  /** Returns a promise that resolves when the queue becomes idle (no active or pending tasks). */\n  onIdle(): Promise<void>;\n  /** Subscribes to settled results (both resolved and rejected). Returns an unsubscribe function. */\n  onSettled<T>(cb: QueueSettledCallback<T>): () => void;\n  /** Number of currently running tasks. */\n  readonly active: number;\n  /** Number of tasks waiting to run. */\n  readonly pending: number;\n  /** Total tasks (active + pending). */\n  readonly size: number;\n}\n\nexport function queue(options: { concurrency?: number } = {}): Queue {\n  const { concurrency = 1 } = options;\n\n  if (concurrency < 1) throw new ArsenalValidationError('Concurrency must be at least 1');\n\n  let activeCount = 0;\n  let isDraining = false;\n  let idlePromise: Promise<void> | null = null;\n  let idleResolve: (() => void) | null = null;\n\n  const tasks: Array<{\n    fn: () => Promise<unknown>;\n    priority: number;\n    reject: (error: unknown) => void;\n    resolve: (value: unknown) => void;\n  }> = [];\n\n  const settledListeners = new Set<QueueSettledCallback>();\n\n  const resolveIdle = (): void => {\n    if (activeCount === 0 && tasks.length === 0 && idleResolve) {\n      idleResolve();\n      idlePromise = null;\n      idleResolve = null;\n    }\n  };\n\n  const notifySettled = (result: AttemptResult<unknown>): void => {\n    for (const cb of settledListeners) {\n      cb(result);\n    }\n  };\n\n  const drain = (): void => {\n    if (isDraining) {\n      return;\n    }\n\n    isDraining = true;\n\n    while (activeCount < concurrency && tasks.length > 0) {\n      const task = tasks.shift()!;\n\n      activeCount++;\n\n      void Promise.resolve()\n        .then(() => task.fn())\n        .then((v) => {\n          notifySettled({ ok: true, value: v });\n          task.resolve(v);\n        })\n        .catch((e: unknown) => {\n          notifySettled({ error: e, ok: false });\n          task.reject(e);\n        })\n        .finally(() => {\n          activeCount--;\n          drain();\n          resolveIdle();\n        });\n    }\n\n    isDraining = false;\n    resolveIdle();\n  };\n\n  return {\n    /**\n     * Returns the number of currently running tasks.\n     */\n    get active(): number {\n      return activeCount;\n    },\n\n    /**\n     * Adds a promise-returning function to the queue.\n     * Tasks with a higher `priority` number run before lower-priority tasks.\n     * Tasks with equal priority run in insertion order (FIFO).\n     *\n     * @param fn - The async function to queue.\n     * @param options.priority - Task priority. Higher numbers run first. Default: 0.\n     */\n    add: <T>(fn: () => Promise<T>, options?: { priority?: number }): Promise<T> => {\n      const { promise, reject, resolve } = Promise.withResolvers<T>();\n      const priority = options?.priority ?? 0;\n\n      const task = {\n        fn: fn as () => Promise<unknown>,\n        priority,\n        reject,\n        resolve: resolve as (value: unknown) => void,\n      };\n\n      let i = tasks.length;\n\n      while (i > 0 && tasks[i - 1]!.priority < priority) {\n        i--;\n      }\n\n      tasks.splice(i, 0, task);\n      drain();\n\n      return promise;\n    },\n\n    /**\n     * Clears all pending tasks from the queue and rejects them.\n     * Running tasks are not affected.\n     * @param reason - The error reason for the rejection (defaults to 'Queue cleared')\n     */\n    clear: (reason?: unknown): void => {\n      const clearReason = reason ?? new Error('Queue cleared');\n\n      for (const task of tasks.splice(0)) {\n        task.reject(clearReason);\n      }\n\n      resolveIdle();\n    },\n\n    /**\n     * Returns a promise that resolves when the queue becomes idle.\n     */\n    onIdle: (): Promise<void> => {\n      if (activeCount === 0 && tasks.length === 0) {\n        return Promise.resolve();\n      }\n\n      if (!idlePromise) {\n        const deferred = Promise.withResolvers<void>();\n\n        idlePromise = deferred.promise;\n        idleResolve = deferred.resolve;\n      }\n\n      return idlePromise;\n    },\n\n    /**\n     * Subscribes to settled task results (both resolved and rejected).\n     * The callback fires once per task, in completion order.\n     * Returns an unsubscribe function.\n     *\n     * Unlike a `for await` loop, multiple subscribers are supported and\n     * no results are accumulated in memory.\n     *\n     * @example\n     * ```ts\n     * const q = queue({ concurrency: 2 });\n     * const unsub = q.onSettled((result) => {\n     *   if (result.ok) console.log(result.value);\n     *   else console.error(result.error);\n     * });\n     *\n     * q.add(() => fetchUser(1));\n     * q.add(() => fetchUser(2));\n     *\n     * await q.onIdle();\n     * unsub(); // stop listening\n     * ```\n     */\n    onSettled: <T = unknown>(cb: QueueSettledCallback<T>): (() => void) => {\n      settledListeners.add(cb as QueueSettledCallback);\n\n      return () => {\n        settledListeners.delete(cb as QueueSettledCallback);\n      };\n    },\n\n    /**\n     * Returns the number of tasks waiting to run (queued but not yet started).\n     */\n    get pending(): number {\n      return tasks.length;\n    },\n\n    /**\n     * Returns the total number of tasks (active + pending).\n     */\n    get size(): number {\n      return activeCount + tasks.length;\n    },\n  };\n}\n"],"mappings":"iCAyCA,SAAgB,EAAM,EAAoC,CAAC,EAAU,CACnE,GAAM,CAAE,cAAc,GAAM,EAE5B,GAAI,EAAc,EAAG,MAAM,IAAI,EAAA,uBAAuB,gCAAgC,EAEtF,IAAI,EAAc,EACd,EAAa,GACb,EAAoC,KACpC,EAAmC,KAEjC,EAKD,CAAC,EAEA,EAAmB,IAAI,IAEvB,MAA0B,CAC1B,IAAgB,GAAK,EAAM,SAAW,GAAK,IAC7C,EAAY,EACZ,EAAc,KACd,EAAc,KAElB,EAEM,EAAiB,GAAyC,CAC9D,IAAK,IAAM,KAAM,EACf,EAAG,CAAM,CAEb,EAEM,MAAoB,CACpB,MAMJ,KAFA,EAAa,GAEN,EAAc,GAAe,EAAM,OAAS,GAAG,CACpD,IAAM,EAAO,EAAM,MAAM,EAEzB,IAEA,QAAa,QAAQ,CAAC,CACnB,SAAW,EAAK,GAAG,CAAC,CAAC,CACrB,KAAM,GAAM,CACX,EAAc,CAAE,GAAI,GAAM,MAAO,CAAE,CAAC,EACpC,EAAK,QAAQ,CAAC,CAChB,CAAC,CAAC,CACD,MAAO,GAAe,CACrB,EAAc,CAAE,MAAO,EAAG,GAAI,EAAM,CAAC,EACrC,EAAK,OAAO,CAAC,CACf,CAAC,CAAC,CACD,YAAc,CACb,IACA,EAAM,EACN,EAAY,CACd,CAAC,CACL,CAEA,EAAa,GACb,EAAY,CAHZ,CAIF,EAEA,MAAO,CAIL,IAAI,QAAiB,CACnB,OAAO,CACT,EAUA,KAAS,EAAsB,IAAgD,CAC7E,GAAM,CAAE,UAAS,SAAQ,WAAY,QAAQ,cAAiB,EACxD,EAAW,GAAS,UAAY,EAEhC,EAAO,CACP,KACJ,WACA,SACS,SACX,EAEI,EAAI,EAAM,OAEd,KAAO,EAAI,GAAK,EAAM,EAAI,EAAE,CAAE,SAAW,GACvC,IAMF,OAHA,EAAM,OAAO,EAAG,EAAG,CAAI,EACvB,EAAM,EAEC,CACT,EAOA,MAAQ,GAA2B,CACjC,IAAM,EAAc,GAAc,MAAM,eAAe,EAEvD,IAAK,IAAM,KAAQ,EAAM,OAAO,CAAC,EAC/B,EAAK,OAAO,CAAW,EAGzB,EAAY,CACd,EAKA,WAA6B,CAC3B,GAAI,IAAgB,GAAK,EAAM,SAAW,EACxC,OAAO,QAAQ,QAAQ,EAGzB,GAAI,CAAC,EAAa,CAChB,IAAM,EAAW,QAAQ,cAAoB,EAE7C,EAAc,EAAS,QACvB,EAAc,EAAS,OACzB,CAEA,OAAO,CACT,EAyBA,UAAyB,IACvB,EAAiB,IAAI,CAA0B,MAElC,CACX,EAAiB,OAAO,CAA0B,CACpD,GAMF,IAAI,SAAkB,CACpB,OAAO,EAAM,MACf,EAKA,IAAI,MAAe,CACjB,OAAO,EAAc,EAAM,MAC7B,CACF,CACF"}

package/dist/async/queue.d.ts

@@ -1,42 +0,0 @@
-import type { AttemptResult } from './attempt';
-/**
- * Creates a promise queue that processes promises sequentially with optional concurrency limit.
- *
- * @example
- * ```ts
- * const requestQueue = queue({ concurrency: 2 });
- *
- * requestQueue.add(() => fetch('/api/1'));
- * requestQueue.add(() => fetch('/api/2'));
- * requestQueue.add(() => fetch('/api/3'));
- *
- * await requestQueue.onIdle(); // Wait for all tasks to complete
- * ```
- *
- * @param options - Queue configuration
- * @param options.concurrency - Maximum number of concurrent promises (default: 1)
- * @returns Queue instance with add, onIdle, clear, and onSettled methods
- */
-export type QueueSettledCallback<T = unknown> = (result: AttemptResult<T>) => void;
-export interface Queue {
-    /** Adds a task to the queue. Returns a promise that resolves/rejects with the task result. */
-    add<T>(fn: () => Promise<T>, options?: {
-        priority?: number;
-    }): Promise<T>;
-    /** Clears all pending tasks, rejecting them with the given reason. Running tasks are unaffected. */
-    clear(reason?: unknown): void;
-    /** Returns a promise that resolves when the queue becomes idle (no active or pending tasks). */
-    onIdle(): Promise<void>;
-    /** Subscribes to settled results (both resolved and rejected). Returns an unsubscribe function. */
-    onSettled<T>(cb: QueueSettledCallback<T>): () => void;
-    /** Number of currently running tasks. */
-    readonly active: number;
-    /** Number of tasks waiting to run. */
-    readonly pending: number;
-    /** Total tasks (active + pending). */
-    readonly size: number;
-}
-export declare function queue(options?: {
-    concurrency?: number;
-}): Queue;
-//# sourceMappingURL=queue.d.ts.map

package/dist/async/queue.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/async/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAI/C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEnF,MAAM,WAAW,KAAK;IACpB,8FAA8F;IAC9F,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1E,oGAAoG;IACpG,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,gGAAgG;IAChG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,mGAAmG;IACnG,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IACtD,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,KAAK,CAAC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,KAAK,CAuLnE"}

package/dist/async/queue.js

@@ -1,72 +0,0 @@
-import { ArsenalValidationError as e } from "../errors.js";
-//#region src/async/queue.ts
-function t(t = {}) {
-	let { concurrency: n = 1 } = t;
-	if (n < 1) throw new e("Concurrency must be at least 1");
-	let r = 0, i = !1, a = null, o = null, s = [], c = /* @__PURE__ */ new Set(), l = () => {
-		r === 0 && s.length === 0 && o && (o(), a = null, o = null);
-	}, u = (e) => {
-		for (let t of c) t(e);
-	}, d = () => {
-		if (!i) {
-			for (i = !0; r < n && s.length > 0;) {
-				let e = s.shift();
-				r++, Promise.resolve().then(() => e.fn()).then((t) => {
-					u({
-						ok: !0,
-						value: t
-					}), e.resolve(t);
-				}).catch((t) => {
-					u({
-						error: t,
-						ok: !1
-					}), e.reject(t);
-				}).finally(() => {
-					r--, d(), l();
-				});
-			}
-			i = !1, l();
-		}
-	};
-	return {
-		get active() {
-			return r;
-		},
-		add: (e, t) => {
-			let { promise: n, reject: r, resolve: i } = Promise.withResolvers(), a = t?.priority ?? 0, o = {
-				fn: e,
-				priority: a,
-				reject: r,
-				resolve: i
-			}, c = s.length;
-			for (; c > 0 && s[c - 1].priority < a;) c--;
-			return s.splice(c, 0, o), d(), n;
-		},
-		clear: (e) => {
-			let t = e ?? /* @__PURE__ */ Error("Queue cleared");
-			for (let e of s.splice(0)) e.reject(t);
-			l();
-		},
-		onIdle: () => {
-			if (r === 0 && s.length === 0) return Promise.resolve();
-			if (!a) {
-				let e = Promise.withResolvers();
-				a = e.promise, o = e.resolve;
-			}
-			return a;
-		},
-		onSettled: (e) => (c.add(e), () => {
-			c.delete(e);
-		}),
-		get pending() {
-			return s.length;
-		},
-		get size() {
-			return r + s.length;
-		}
-	};
-}
-//#endregion
-export { t as queue };
-
-//# sourceMappingURL=queue.js.map

package/dist/async/queue.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"queue.js","names":[],"sources":["../../src/async/queue.ts"],"sourcesContent":["import type { AttemptResult } from './attempt';\n\nimport { ArsenalValidationError } from '../errors';\n\n/**\n * Creates a promise queue that processes promises sequentially with optional concurrency limit.\n *\n * @example\n * ```ts\n * const requestQueue = queue({ concurrency: 2 });\n *\n * requestQueue.add(() => fetch('/api/1'));\n * requestQueue.add(() => fetch('/api/2'));\n * requestQueue.add(() => fetch('/api/3'));\n *\n * await requestQueue.onIdle(); // Wait for all tasks to complete\n * ```\n *\n * @param options - Queue configuration\n * @param options.concurrency - Maximum number of concurrent promises (default: 1)\n * @returns Queue instance with add, onIdle, clear, and onSettled methods\n */\nexport type QueueSettledCallback<T = unknown> = (result: AttemptResult<T>) => void;\n\nexport interface Queue {\n  /** Adds a task to the queue. Returns a promise that resolves/rejects with the task result. */\n  add<T>(fn: () => Promise<T>, options?: { priority?: number }): Promise<T>;\n  /** Clears all pending tasks, rejecting them with the given reason. Running tasks are unaffected. */\n  clear(reason?: unknown): void;\n  /** Returns a promise that resolves when the queue becomes idle (no active or pending tasks). */\n  onIdle(): Promise<void>;\n  /** Subscribes to settled results (both resolved and rejected). Returns an unsubscribe function. */\n  onSettled<T>(cb: QueueSettledCallback<T>): () => void;\n  /** Number of currently running tasks. */\n  readonly active: number;\n  /** Number of tasks waiting to run. */\n  readonly pending: number;\n  /** Total tasks (active + pending). */\n  readonly size: number;\n}\n\nexport function queue(options: { concurrency?: number } = {}): Queue {\n  const { concurrency = 1 } = options;\n\n  if (concurrency < 1) throw new ArsenalValidationError('Concurrency must be at least 1');\n\n  let activeCount = 0;\n  let isDraining = false;\n  let idlePromise: Promise<void> | null = null;\n  let idleResolve: (() => void) | null = null;\n\n  const tasks: Array<{\n    fn: () => Promise<unknown>;\n    priority: number;\n    reject: (error: unknown) => void;\n    resolve: (value: unknown) => void;\n  }> = [];\n\n  const settledListeners = new Set<QueueSettledCallback>();\n\n  const resolveIdle = (): void => {\n    if (activeCount === 0 && tasks.length === 0 && idleResolve) {\n      idleResolve();\n      idlePromise = null;\n      idleResolve = null;\n    }\n  };\n\n  const notifySettled = (result: AttemptResult<unknown>): void => {\n    for (const cb of settledListeners) {\n      cb(result);\n    }\n  };\n\n  const drain = (): void => {\n    if (isDraining) {\n      return;\n    }\n\n    isDraining = true;\n\n    while (activeCount < concurrency && tasks.length > 0) {\n      const task = tasks.shift()!;\n\n      activeCount++;\n\n      void Promise.resolve()\n        .then(() => task.fn())\n        .then((v) => {\n          notifySettled({ ok: true, value: v });\n          task.resolve(v);\n        })\n        .catch((e: unknown) => {\n          notifySettled({ error: e, ok: false });\n          task.reject(e);\n        })\n        .finally(() => {\n          activeCount--;\n          drain();\n          resolveIdle();\n        });\n    }\n\n    isDraining = false;\n    resolveIdle();\n  };\n\n  return {\n    /**\n     * Returns the number of currently running tasks.\n     */\n    get active(): number {\n      return activeCount;\n    },\n\n    /**\n     * Adds a promise-returning function to the queue.\n     * Tasks with a higher `priority` number run before lower-priority tasks.\n     * Tasks with equal priority run in insertion order (FIFO).\n     *\n     * @param fn - The async function to queue.\n     * @param options.priority - Task priority. Higher numbers run first. Default: 0.\n     */\n    add: <T>(fn: () => Promise<T>, options?: { priority?: number }): Promise<T> => {\n      const { promise, reject, resolve } = Promise.withResolvers<T>();\n      const priority = options?.priority ?? 0;\n\n      const task = {\n        fn: fn as () => Promise<unknown>,\n        priority,\n        reject,\n        resolve: resolve as (value: unknown) => void,\n      };\n\n      let i = tasks.length;\n\n      while (i > 0 && tasks[i - 1]!.priority < priority) {\n        i--;\n      }\n\n      tasks.splice(i, 0, task);\n      drain();\n\n      return promise;\n    },\n\n    /**\n     * Clears all pending tasks from the queue and rejects them.\n     * Running tasks are not affected.\n     * @param reason - The error reason for the rejection (defaults to 'Queue cleared')\n     */\n    clear: (reason?: unknown): void => {\n      const clearReason = reason ?? new Error('Queue cleared');\n\n      for (const task of tasks.splice(0)) {\n        task.reject(clearReason);\n      }\n\n      resolveIdle();\n    },\n\n    /**\n     * Returns a promise that resolves when the queue becomes idle.\n     */\n    onIdle: (): Promise<void> => {\n      if (activeCount === 0 && tasks.length === 0) {\n        return Promise.resolve();\n      }\n\n      if (!idlePromise) {\n        const deferred = Promise.withResolvers<void>();\n\n        idlePromise = deferred.promise;\n        idleResolve = deferred.resolve;\n      }\n\n      return idlePromise;\n    },\n\n    /**\n     * Subscribes to settled task results (both resolved and rejected).\n     * The callback fires once per task, in completion order.\n     * Returns an unsubscribe function.\n     *\n     * Unlike a `for await` loop, multiple subscribers are supported and\n     * no results are accumulated in memory.\n     *\n     * @example\n     * ```ts\n     * const q = queue({ concurrency: 2 });\n     * const unsub = q.onSettled((result) => {\n     *   if (result.ok) console.log(result.value);\n     *   else console.error(result.error);\n     * });\n     *\n     * q.add(() => fetchUser(1));\n     * q.add(() => fetchUser(2));\n     *\n     * await q.onIdle();\n     * unsub(); // stop listening\n     * ```\n     */\n    onSettled: <T = unknown>(cb: QueueSettledCallback<T>): (() => void) => {\n      settledListeners.add(cb as QueueSettledCallback);\n\n      return () => {\n        settledListeners.delete(cb as QueueSettledCallback);\n      };\n    },\n\n    /**\n     * Returns the number of tasks waiting to run (queued but not yet started).\n     */\n    get pending(): number {\n      return tasks.length;\n    },\n\n    /**\n     * Returns the total number of tasks (active + pending).\n     */\n    get size(): number {\n      return activeCount + tasks.length;\n    },\n  };\n}\n"],"mappings":";;AAyCA,SAAgB,EAAM,IAAoC,CAAC,GAAU;CACnE,IAAM,EAAE,iBAAc,MAAM;CAE5B,IAAI,IAAc,GAAG,MAAM,IAAI,EAAuB,gCAAgC;CAEtF,IAAI,IAAc,GACd,IAAa,IACb,IAAoC,MACpC,IAAmC,MAEjC,IAKD,CAAC,GAEA,oBAAmB,IAAI,IAA0B,GAEjD,UAA0B;EAC9B,AAAI,MAAgB,KAAK,EAAM,WAAW,KAAK,MAC7C,EAAY,GACZ,IAAc,MACd,IAAc;CAElB,GAEM,KAAiB,MAAyC;EAC9D,KAAK,IAAM,KAAM,GACf,EAAG,CAAM;CAEb,GAEM,UAAoB;EACpB,QAMJ;QAFA,IAAa,IAEN,IAAc,KAAe,EAAM,SAAS,IAAG;IACpD,IAAM,IAAO,EAAM,MAAM;IAIzB,AAFA,KAEA,QAAa,QAAQ,CAAC,CACnB,WAAW,EAAK,GAAG,CAAC,CAAC,CACrB,MAAM,MAAM;KAEX,AADA,EAAc;MAAE,IAAI;MAAM,OAAO;KAAE,CAAC,GACpC,EAAK,QAAQ,CAAC;IAChB,CAAC,CAAC,CACD,OAAO,MAAe;KAErB,AADA,EAAc;MAAE,OAAO;MAAG,IAAI;KAAM,CAAC,GACrC,EAAK,OAAO,CAAC;IACf,CAAC,CAAC,CACD,cAAc;KAGb,AAFA,KACA,EAAM,GACN,EAAY;IACd,CAAC;GACL;GAGA,AADA,IAAa,IACb,EAAY;EAHZ;CAIF;CAEA,OAAO;EAIL,IAAI,SAAiB;GACnB,OAAO;EACT;EAUA,MAAS,GAAsB,MAAgD;GAC7E,IAAM,EAAE,YAAS,WAAQ,eAAY,QAAQ,cAAiB,GACxD,IAAW,GAAS,YAAY,GAEhC,IAAO;IACP;IACJ;IACA;IACS;GACX,GAEI,IAAI,EAAM;GAEd,OAAO,IAAI,KAAK,EAAM,IAAI,EAAE,CAAE,WAAW,IACvC;GAMF,OAHA,EAAM,OAAO,GAAG,GAAG,CAAI,GACvB,EAAM,GAEC;EACT;EAOA,QAAQ,MAA2B;GACjC,IAAM,IAAc,KAAU,gBAAI,MAAM,eAAe;GAEvD,KAAK,IAAM,KAAQ,EAAM,OAAO,CAAC,GAC/B,EAAK,OAAO,CAAW;GAGzB,EAAY;EACd;EAKA,cAA6B;GAC3B,IAAI,MAAgB,KAAK,EAAM,WAAW,GACxC,OAAO,QAAQ,QAAQ;GAGzB,IAAI,CAAC,GAAa;IAChB,IAAM,IAAW,QAAQ,cAAoB;IAG7C,AADA,IAAc,EAAS,SACvB,IAAc,EAAS;GACzB;GAEA,OAAO;EACT;EAyBA,YAAyB,OACvB,EAAiB,IAAI,CAA0B,SAElC;GACX,EAAiB,OAAO,CAA0B;EACpD;EAMF,IAAI,UAAkB;GACpB,OAAO,EAAM;EACf;EAKA,IAAI,OAAe;GACjB,OAAO,IAAc,EAAM;EAC7B;CACF;AACF"}

package/dist/cache/stash.cjs

@@ -1,2 +0,0 @@
-const e=require("../errors.cjs"),t=require("../guards/isPromise.cjs");function n(n={}){let r=n.maxSize??1/0;if(r!==1/0&&(!Number.isInteger(r)||r<1))throw new e.ArsenalValidationError(`stash: maxSize must be a positive integer or Infinity, got ${r}`);let i=new Map,a=new Map,o=new Map,s=n.hash??(e=>String(e)),c=n.onEvict,l=n.ttlMs,u=n.persistence,d=0,f=new Set;function p(){if(i.size>r){let[e]=i.keys();e!==void 0&&h(e)}}function m(e){let t=a.get(e);t!==void 0&&(clearTimeout(t),a.delete(e))}function h(e){let t=i.get(e);return m(e),t&&(c?.(t.key,t.value),i.delete(e)),o.has(e)&&f.add(e),t!==void 0}function g(t,n){if(m(t),n===1/0)return;if(!Number.isFinite(n))throw new e.ArsenalValidationError(`stash: ttlMs must be a finite number or Infinity`);if(n<=0){h(t);return}if(!i.has(t))return;let r=setTimeout(()=>{a.delete(t),h(t)},n);a.set(t,r)}function _(e){return u&&typeof e==`string`?u.deserialize(e):e}function v(e){let t=i.get(s(e));return t?_(t.value):void 0}function y(e,t,n){let r=s(e),a=u?u.serialize(t):t;m(r),i.set(r,{key:e,value:a}),p();let o=n?.ttlMs??l;o!==void 0&&g(r,o)}function b(e,n,r){let a=s(e);if(i.has(a)&&!r?.forceRefresh)return v(e);let c=o.get(a);if(c&&!r?.forceRefresh)return c;let l=n();if(t.isPromise(l)){let t=d,n=l.then(i=>(o.get(a)===n&&o.delete(a),d===t&&!f.has(a)&&y(e,i,r),f.delete(a),i)).catch(e=>{throw o.get(a)===n&&o.delete(a),f.delete(a),e});return o.set(a,n),n}return y(e,l,r),l}function x(e){return h(s(e))}function S(){d++;for(let e of a.values())clearTimeout(e);if(c)for(let e of i.values())c(e.key,e.value);i.clear(),a.clear(),o.clear(),f.clear()}function*C(){for(let e of i.values())yield[e.key,_(e.value)]}return{clear:S,delete:x,entries:C,get:v,getOrSet:b,set:y,get size(){return i.size}}}exports.stash=n;
-//# sourceMappingURL=stash.cjs.map

package/dist/cache/stash.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"stash.cjs","names":[],"sources":["../../src/cache/stash.ts"],"sourcesContent":["import { ArsenalValidationError } from '../errors';\nimport { isPromise } from '../guards/isPromise';\n\ntype CacheRecord<K, T> = {\n  key: K;\n  value: T;\n};\n\nexport type CachePersistence<T> = {\n  /** Deserializes a stored string back into a value of type `T`. */\n  deserialize: (raw: string) => T;\n  /** Serializes a value to a string for internal storage. */\n  serialize: (value: T) => string;\n};\n\nexport type CacheOptions<K = string, T = unknown> = {\n  /**\n   * Converts a key to its canonical string representation for internal storage.\n   * Defaults to `String(key)` — suitable for all string, number, and symbol keys.\n   * Provide a custom function for object keys or composite keys.\n   */\n  hash?: (key: K) => string;\n  /**\n   * Maximum number of entries to hold. When the store reaches capacity, the oldest\n   * entry is evicted (FIFO) before inserting the new one. `onEvict` is called on\n   * capacity evictions just like TTL evictions.\n   *\n   * Default: `Infinity` (unbounded).\n   */\n  maxSize?: number;\n  onEvict?: (key: K, value: T) => void;\n  /**\n   * Optional serialization pair for persistent caches (e.g. localStorage, cross-process IPC).\n   * Both `serialize` and `deserialize` must be provided together.\n   *\n   * @example\n   * ```ts\n   * const cache = stash<User>({\n   *   persistence: {\n   *     serialize: (u) => JSON.stringify(u),\n   *     deserialize: (raw) => JSON.parse(raw) as User,\n   *   },\n   * });\n   * ```\n   */\n  persistence?: CachePersistence<T>;\n  /**\n   * Default time-to-live for all entries in milliseconds.\n   * Applied automatically to every `set()` and `getOrSet()` call unless\n   * overridden per-entry via `CacheSetOptions.ttlMs`.\n   *\n   * Default: `undefined` (entries do not expire).\n   */\n  ttlMs?: number;\n};\n\nexport type CacheSetOptions = {\n  /**\n   * When `true`, bypasses both the cache and any in-flight promise for this key,\n   * and always calls the factory. The new value replaces the old cache entry.\n   * **Note:** if a prior in-flight is still pending when `forceRefresh` resolves,\n   * whichever `.then` runs last will write the cache slot — ensure prior in-flight\n   * tasks have settled if ordering matters.\n   */\n  forceRefresh?: boolean;\n  ttlMs?: number;\n};\n\nexport type Stash<T, K = string> = {\n  clear: () => void;\n  delete: (key: K) => boolean;\n  entries: () => IterableIterator<[K, T]>;\n  get: (key: K) => T | undefined;\n  /**\n   * Returns the cached value for `key`, or invokes `factory` to produce and cache it.\n   * Pass `{ forceRefresh: true }` to skip the cache and always call `factory`.\n   */\n  getOrSet(key: K, factory: () => T, options?: CacheSetOptions): T;\n  getOrSet(key: K, factory: () => Promise<T>, options?: CacheSetOptions): Promise<T>;\n  set: (key: K, value: T, options?: CacheSetOptions) => void;\n  readonly size: number;\n};\n\n/**\n * Creates a generic key-value cache with TTL-based garbage collection, optional capacity\n * limit (FIFO eviction), async stampede prevention, and optional eviction callback.\n *\n * This is the single caching primitive in arsenal — use it for simple bounded caches,\n * TTL caches, or async deduplication/stampede prevention.\n *\n * @example\n * ```ts\n * // Simple string cache — no options needed for string keys\n * const myCache = stash<string>();\n * myCache.set('user:1', 'John Doe');\n * const value = myCache.get('user:1'); // 'John Doe'\n *\n * // Global TTL — all entries expire after 60 seconds unless overridden\n * const apiCache = stash<Response>({ ttlMs: 60_000 });\n * apiCache.set('data', response);             // expires in 60s\n * apiCache.set('data', response, { ttlMs: 5_000 }); // override: expires in 5s\n *\n * // Async getOrSet prevents stampedes — concurrent callers share one in-flight promise\n * const user = await myCache.getOrSet('user:1', () => fetchUser(1));\n *\n * // Bounded FIFO cache\n * const fmtCache = stash<Intl.NumberFormat>({ maxSize: 64 });\n * const fmt = fmtCache.getOrSet('en-US', () => new Intl.NumberFormat('en-US'));\n *\n * // Custom key type — provide a hash function\n * const objCache = stash<Result, { id: number }>({ hash: (k) => String(k.id) });\n *\n * // Note: `undefined` is a valid cached value — if a key is set to `undefined`,\n * // `getOrSet` returns it without invoking the factory again.\n * ```\n *\n * @template T - The type of values stored in the cache.\n * @template K - The key type. Defaults to `string`.\n *\n * @throws {ArsenalValidationError} If `options.maxSize` is provided and is not a positive integer or `Infinity`.\n */\nexport function stash<T, K = string>(options: CacheOptions<K, T> = {}): Stash<T, K> {\n  const maxSize = options.maxSize ?? Infinity;\n\n  if (maxSize !== Infinity && (!Number.isInteger(maxSize) || maxSize < 1)) {\n    throw new ArsenalValidationError(`stash: maxSize must be a positive integer or Infinity, got ${maxSize}`);\n  }\n\n  const store = new Map<string, CacheRecord<K, T>>();\n  const gcTimers = new Map<string, ReturnType<typeof setTimeout>>();\n  const inFlight = new Map<string, Promise<T>>();\n  const hash = options.hash ?? ((key: K) => String(key));\n  const onEvict = options.onEvict;\n  const defaultTtlMs = options.ttlMs;\n  const persistence = options.persistence;\n  let generation = 0;\n  const deletedWhileInFlight = new Set<string>();\n\n  function evictOldestIfOverCapacity(): void {\n    if (store.size > maxSize) {\n      const [firstHash] = store.keys();\n\n      if (firstHash !== undefined) {\n        deleteByHash(firstHash);\n      }\n    }\n  }\n\n  function cancelGcByHash(keyHash: string): void {\n    const id = gcTimers.get(keyHash);\n\n    if (id !== undefined) {\n      clearTimeout(id);\n      gcTimers.delete(keyHash);\n    }\n  }\n\n  function deleteByHash(keyHash: string): boolean {\n    const record = store.get(keyHash);\n\n    cancelGcByHash(keyHash);\n\n    if (record) {\n      onEvict?.(record.key, record.value);\n      store.delete(keyHash);\n    }\n\n    if (inFlight.has(keyHash)) deletedWhileInFlight.add(keyHash);\n\n    return record !== undefined;\n  }\n\n  function scheduleGcByHash(keyHash: string, delayMs: number): void {\n    cancelGcByHash(keyHash);\n\n    if (delayMs === Number.POSITIVE_INFINITY) return;\n\n    if (!Number.isFinite(delayMs)) {\n      throw new ArsenalValidationError('stash: ttlMs must be a finite number or Infinity');\n    }\n\n    if (delayMs <= 0) {\n      deleteByHash(keyHash);\n\n      return;\n    }\n\n    if (!store.has(keyHash)) return;\n\n    const id = setTimeout(() => {\n      gcTimers.delete(keyHash);\n      deleteByHash(keyHash);\n    }, delayMs);\n\n    gcTimers.set(keyHash, id);\n  }\n\n  function deserializeValue(raw: T): T {\n    if (persistence && typeof raw === 'string') return persistence.deserialize(raw);\n\n    return raw;\n  }\n\n  function get(key: K): T | undefined {\n    const record = store.get(hash(key));\n\n    return record ? deserializeValue(record.value) : undefined;\n  }\n\n  function set(key: K, value: T, opts?: CacheSetOptions): void {\n    const keyHash = hash(key);\n    const stored = persistence ? (persistence.serialize(value) as unknown as T) : value;\n\n    cancelGcByHash(keyHash);\n    store.set(keyHash, { key, value: stored });\n    evictOldestIfOverCapacity();\n\n    const ttl = opts?.ttlMs ?? defaultTtlMs;\n\n    if (ttl !== undefined) {\n      scheduleGcByHash(keyHash, ttl);\n    }\n  }\n\n  function getOrSet(key: K, factory: () => T | Promise<T>, opts?: CacheSetOptions): T | Promise<T> {\n    const keyHash = hash(key);\n\n    if (store.has(keyHash) && !opts?.forceRefresh) return get(key) as T;\n\n    const pending = inFlight.get(keyHash);\n\n    if (pending && !opts?.forceRefresh) return pending;\n\n    const value = factory();\n\n    if (isPromise(value)) {\n      const capturedGeneration = generation;\n      const promise: Promise<T> = value\n        .then((resolved) => {\n          // Only clear the in-flight slot if it's still *this* promise — an overlapping\n          // `forceRefresh` call may have already replaced it with a newer in-flight promise.\n          if (inFlight.get(keyHash) === promise) inFlight.delete(keyHash);\n\n          if (generation === capturedGeneration && !deletedWhileInFlight.has(keyHash)) {\n            set(key, resolved, opts);\n          }\n\n          deletedWhileInFlight.delete(keyHash);\n\n          return resolved;\n        })\n        .catch((err: unknown) => {\n          if (inFlight.get(keyHash) === promise) inFlight.delete(keyHash);\n\n          deletedWhileInFlight.delete(keyHash);\n          throw err;\n        });\n\n      inFlight.set(keyHash, promise);\n\n      return promise;\n    }\n\n    set(key, value, opts);\n\n    return value;\n  }\n\n  function del(key: K): boolean {\n    return deleteByHash(hash(key));\n  }\n\n  function clear(): void {\n    generation++;\n    for (const id of gcTimers.values()) clearTimeout(id);\n\n    if (onEvict) {\n      for (const record of store.values()) {\n        onEvict(record.key, record.value);\n      }\n    }\n\n    store.clear();\n    gcTimers.clear();\n    inFlight.clear();\n    deletedWhileInFlight.clear();\n  }\n\n  function* entries(): IterableIterator<[K, T]> {\n    for (const record of store.values()) {\n      yield [record.key, deserializeValue(record.value)];\n    }\n  }\n\n  return {\n    clear,\n    delete: del,\n    entries,\n    get,\n    getOrSet: getOrSet as Stash<T, K>['getOrSet'],\n    set,\n    get size() {\n      return store.size;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/cache/stash.d.ts

@@ -1,111 +0,0 @@
-export type CachePersistence<T> = {
-    /** Deserializes a stored string back into a value of type `T`. */
-    deserialize: (raw: string) => T;
-    /** Serializes a value to a string for internal storage. */
-    serialize: (value: T) => string;
-};
-export type CacheOptions<K = string, T = unknown> = {
-    /**
-     * Converts a key to its canonical string representation for internal storage.
-     * Defaults to `String(key)` — suitable for all string, number, and symbol keys.
-     * Provide a custom function for object keys or composite keys.
-     */
-    hash?: (key: K) => string;
-    /**
-     * Maximum number of entries to hold. When the store reaches capacity, the oldest
-     * entry is evicted (FIFO) before inserting the new one. `onEvict` is called on
-     * capacity evictions just like TTL evictions.
-     *
-     * Default: `Infinity` (unbounded).
-     */
-    maxSize?: number;
-    onEvict?: (key: K, value: T) => void;
-    /**
-     * Optional serialization pair for persistent caches (e.g. localStorage, cross-process IPC).
-     * Both `serialize` and `deserialize` must be provided together.
-     *
-     * @example
-     * ```ts
-     * const cache = stash<User>({
-     *   persistence: {
-     *     serialize: (u) => JSON.stringify(u),
-     *     deserialize: (raw) => JSON.parse(raw) as User,
-     *   },
-     * });
-     * ```
-     */
-    persistence?: CachePersistence<T>;
-    /**
-     * Default time-to-live for all entries in milliseconds.
-     * Applied automatically to every `set()` and `getOrSet()` call unless
-     * overridden per-entry via `CacheSetOptions.ttlMs`.
-     *
-     * Default: `undefined` (entries do not expire).
-     */
-    ttlMs?: number;
-};
-export type CacheSetOptions = {
-    /**
-     * When `true`, bypasses both the cache and any in-flight promise for this key,
-     * and always calls the factory. The new value replaces the old cache entry.
-     * **Note:** if a prior in-flight is still pending when `forceRefresh` resolves,
-     * whichever `.then` runs last will write the cache slot — ensure prior in-flight
-     * tasks have settled if ordering matters.
-     */
-    forceRefresh?: boolean;
-    ttlMs?: number;
-};
-export type Stash<T, K = string> = {
-    clear: () => void;
-    delete: (key: K) => boolean;
-    entries: () => IterableIterator<[K, T]>;
-    get: (key: K) => T | undefined;
-    /**
-     * Returns the cached value for `key`, or invokes `factory` to produce and cache it.
-     * Pass `{ forceRefresh: true }` to skip the cache and always call `factory`.
-     */
-    getOrSet(key: K, factory: () => T, options?: CacheSetOptions): T;
-    getOrSet(key: K, factory: () => Promise<T>, options?: CacheSetOptions): Promise<T>;
-    set: (key: K, value: T, options?: CacheSetOptions) => void;
-    readonly size: number;
-};
-/**
- * Creates a generic key-value cache with TTL-based garbage collection, optional capacity
- * limit (FIFO eviction), async stampede prevention, and optional eviction callback.
- *
- * This is the single caching primitive in arsenal — use it for simple bounded caches,
- * TTL caches, or async deduplication/stampede prevention.
- *
- * @example
- * ```ts
- * // Simple string cache — no options needed for string keys
- * const myCache = stash<string>();
- * myCache.set('user:1', 'John Doe');
- * const value = myCache.get('user:1'); // 'John Doe'
- *
- * // Global TTL — all entries expire after 60 seconds unless overridden
- * const apiCache = stash<Response>({ ttlMs: 60_000 });
- * apiCache.set('data', response);             // expires in 60s
- * apiCache.set('data', response, { ttlMs: 5_000 }); // override: expires in 5s
- *
- * // Async getOrSet prevents stampedes — concurrent callers share one in-flight promise
- * const user = await myCache.getOrSet('user:1', () => fetchUser(1));
- *
- * // Bounded FIFO cache
- * const fmtCache = stash<Intl.NumberFormat>({ maxSize: 64 });
- * const fmt = fmtCache.getOrSet('en-US', () => new Intl.NumberFormat('en-US'));
- *
- * // Custom key type — provide a hash function
- * const objCache = stash<Result, { id: number }>({ hash: (k) => String(k.id) });
- *
- * // Note: `undefined` is a valid cached value — if a key is set to `undefined`,
- * // `getOrSet` returns it without invoking the factory again.
- * ```
- *
- * @template T - The type of values stored in the cache.
- * @template K - The key type. Defaults to `string`.
- *
- * @throws {ArsenalValidationError} If `options.maxSize` is provided and is not a positive integer or `Infinity`.
- */
-export declare function stash<T, K = string>(options?: CacheOptions<K, T>): Stash<T, K>;
-//# sourceMappingURL=stash.d.ts.map

package/dist/cache/stash.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"stash.d.ts","sourceRoot":"","sources":["../../src/cache/stash.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,kEAAkE;IAClE,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC;IAChC,2DAA2D;IAC3D,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,OAAO,IAAI;IAClD;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACrC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAClC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI;IACjC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAC5B,OAAO,EAAE,MAAM,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,CAAC,CAAC;IACjE,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnF,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,OAAO,GAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAM,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAwLlF"}

package/dist/cache/stash.js

@@ -1,92 +0,0 @@
-import { ArsenalValidationError as e } from "../errors.js";
-import { isPromise as t } from "../guards/isPromise.js";
-//#region src/cache/stash.ts
-function n(n = {}) {
-	let r = n.maxSize ?? Infinity;
-	if (r !== Infinity && (!Number.isInteger(r) || r < 1)) throw new e(`stash: maxSize must be a positive integer or Infinity, got ${r}`);
-	let i = /* @__PURE__ */ new Map(), a = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map(), s = n.hash ?? ((e) => String(e)), c = n.onEvict, l = n.ttlMs, u = n.persistence, d = 0, f = /* @__PURE__ */ new Set();
-	function p() {
-		if (i.size > r) {
-			let [e] = i.keys();
-			e !== void 0 && h(e);
-		}
-	}
-	function m(e) {
-		let t = a.get(e);
-		t !== void 0 && (clearTimeout(t), a.delete(e));
-	}
-	function h(e) {
-		let t = i.get(e);
-		return m(e), t && (c?.(t.key, t.value), i.delete(e)), o.has(e) && f.add(e), t !== void 0;
-	}
-	function g(t, n) {
-		if (m(t), n === Infinity) return;
-		if (!Number.isFinite(n)) throw new e("stash: ttlMs must be a finite number or Infinity");
-		if (n <= 0) {
-			h(t);
-			return;
-		}
-		if (!i.has(t)) return;
-		let r = setTimeout(() => {
-			a.delete(t), h(t);
-		}, n);
-		a.set(t, r);
-	}
-	function _(e) {
-		return u && typeof e == "string" ? u.deserialize(e) : e;
-	}
-	function v(e) {
-		let t = i.get(s(e));
-		return t ? _(t.value) : void 0;
-	}
-	function y(e, t, n) {
-		let r = s(e), a = u ? u.serialize(t) : t;
-		m(r), i.set(r, {
-			key: e,
-			value: a
-		}), p();
-		let o = n?.ttlMs ?? l;
-		o !== void 0 && g(r, o);
-	}
-	function b(e, n, r) {
-		let a = s(e);
-		if (i.has(a) && !r?.forceRefresh) return v(e);
-		let c = o.get(a);
-		if (c && !r?.forceRefresh) return c;
-		let l = n();
-		if (t(l)) {
-			let t = d, n = l.then((i) => (o.get(a) === n && o.delete(a), d === t && !f.has(a) && y(e, i, r), f.delete(a), i)).catch((e) => {
-				throw o.get(a) === n && o.delete(a), f.delete(a), e;
-			});
-			return o.set(a, n), n;
-		}
-		return y(e, l, r), l;
-	}
-	function x(e) {
-		return h(s(e));
-	}
-	function S() {
-		d++;
-		for (let e of a.values()) clearTimeout(e);
-		if (c) for (let e of i.values()) c(e.key, e.value);
-		i.clear(), a.clear(), o.clear(), f.clear();
-	}
-	function* C() {
-		for (let e of i.values()) yield [e.key, _(e.value)];
-	}
-	return {
-		clear: S,
-		delete: x,
-		entries: C,
-		get: v,
-		getOrSet: b,
-		set: y,
-		get size() {
-			return i.size;
-		}
-	};
-}
-//#endregion
-export { n as stash };
-
-//# sourceMappingURL=stash.js.map

package/dist/cache/stash.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"stash.js","names":[],"sources":["../../src/cache/stash.ts"],"sourcesContent":["import { ArsenalValidationError } from '../errors';\nimport { isPromise } from '../guards/isPromise';\n\ntype CacheRecord<K, T> = {\n  key: K;\n  value: T;\n};\n\nexport type CachePersistence<T> = {\n  /** Deserializes a stored string back into a value of type `T`. */\n  deserialize: (raw: string) => T;\n  /** Serializes a value to a string for internal storage. */\n  serialize: (value: T) => string;\n};\n\nexport type CacheOptions<K = string, T = unknown> = {\n  /**\n   * Converts a key to its canonical string representation for internal storage.\n   * Defaults to `String(key)` — suitable for all string, number, and symbol keys.\n   * Provide a custom function for object keys or composite keys.\n   */\n  hash?: (key: K) => string;\n  /**\n   * Maximum number of entries to hold. When the store reaches capacity, the oldest\n   * entry is evicted (FIFO) before inserting the new one. `onEvict` is called on\n   * capacity evictions just like TTL evictions.\n   *\n   * Default: `Infinity` (unbounded).\n   */\n  maxSize?: number;\n  onEvict?: (key: K, value: T) => void;\n  /**\n   * Optional serialization pair for persistent caches (e.g. localStorage, cross-process IPC).\n   * Both `serialize` and `deserialize` must be provided together.\n   *\n   * @example\n   * ```ts\n   * const cache = stash<User>({\n   *   persistence: {\n   *     serialize: (u) => JSON.stringify(u),\n   *     deserialize: (raw) => JSON.parse(raw) as User,\n   *   },\n   * });\n   * ```\n   */\n  persistence?: CachePersistence<T>;\n  /**\n   * Default time-to-live for all entries in milliseconds.\n   * Applied automatically to every `set()` and `getOrSet()` call unless\n   * overridden per-entry via `CacheSetOptions.ttlMs`.\n   *\n   * Default: `undefined` (entries do not expire).\n   */\n  ttlMs?: number;\n};\n\nexport type CacheSetOptions = {\n  /**\n   * When `true`, bypasses both the cache and any in-flight promise for this key,\n   * and always calls the factory. The new value replaces the old cache entry.\n   * **Note:** if a prior in-flight is still pending when `forceRefresh` resolves,\n   * whichever `.then` runs last will write the cache slot — ensure prior in-flight\n   * tasks have settled if ordering matters.\n   */\n  forceRefresh?: boolean;\n  ttlMs?: number;\n};\n\nexport type Stash<T, K = string> = {\n  clear: () => void;\n  delete: (key: K) => boolean;\n  entries: () => IterableIterator<[K, T]>;\n  get: (key: K) => T | undefined;\n  /**\n   * Returns the cached value for `key`, or invokes `factory` to produce and cache it.\n   * Pass `{ forceRefresh: true }` to skip the cache and always call `factory`.\n   */\n  getOrSet(key: K, factory: () => T, options?: CacheSetOptions): T;\n  getOrSet(key: K, factory: () => Promise<T>, options?: CacheSetOptions): Promise<T>;\n  set: (key: K, value: T, options?: CacheSetOptions) => void;\n  readonly size: number;\n};\n\n/**\n * Creates a generic key-value cache with TTL-based garbage collection, optional capacity\n * limit (FIFO eviction), async stampede prevention, and optional eviction callback.\n *\n * This is the single caching primitive in arsenal — use it for simple bounded caches,\n * TTL caches, or async deduplication/stampede prevention.\n *\n * @example\n * ```ts\n * // Simple string cache — no options needed for string keys\n * const myCache = stash<string>();\n * myCache.set('user:1', 'John Doe');\n * const value = myCache.get('user:1'); // 'John Doe'\n *\n * // Global TTL — all entries expire after 60 seconds unless overridden\n * const apiCache = stash<Response>({ ttlMs: 60_000 });\n * apiCache.set('data', response);             // expires in 60s\n * apiCache.set('data', response, { ttlMs: 5_000 }); // override: expires in 5s\n *\n * // Async getOrSet prevents stampedes — concurrent callers share one in-flight promise\n * const user = await myCache.getOrSet('user:1', () => fetchUser(1));\n *\n * // Bounded FIFO cache\n * const fmtCache = stash<Intl.NumberFormat>({ maxSize: 64 });\n * const fmt = fmtCache.getOrSet('en-US', () => new Intl.NumberFormat('en-US'));\n *\n * // Custom key type — provide a hash function\n * const objCache = stash<Result, { id: number }>({ hash: (k) => String(k.id) });\n *\n * // Note: `undefined` is a valid cached value — if a key is set to `undefined`,\n * // `getOrSet` returns it without invoking the factory again.\n * ```\n *\n * @template T - The type of values stored in the cache.\n * @template K - The key type. Defaults to `string`.\n *\n * @throws {ArsenalValidationError} If `options.maxSize` is provided and is not a positive integer or `Infinity`.\n */\nexport function stash<T, K = string>(options: CacheOptions<K, T> = {}): Stash<T, K> {\n  const maxSize = options.maxSize ?? Infinity;\n\n  if (maxSize !== Infinity && (!Number.isInteger(maxSize) || maxSize < 1)) {\n    throw new ArsenalValidationError(`stash: maxSize must be a positive integer or Infinity, got ${maxSize}`);\n  }\n\n  const store = new Map<string, CacheRecord<K, T>>();\n  const gcTimers = new Map<string, ReturnType<typeof setTimeout>>();\n  const inFlight = new Map<string, Promise<T>>();\n  const hash = options.hash ?? ((key: K) => String(key));\n  const onEvict = options.onEvict;\n  const defaultTtlMs = options.ttlMs;\n  const persistence = options.persistence;\n  let generation = 0;\n  const deletedWhileInFlight = new Set<string>();\n\n  function evictOldestIfOverCapacity(): void {\n    if (store.size > maxSize) {\n      const [firstHash] = store.keys();\n\n      if (firstHash !== undefined) {\n        deleteByHash(firstHash);\n      }\n    }\n  }\n\n  function cancelGcByHash(keyHash: string): void {\n    const id = gcTimers.get(keyHash);\n\n    if (id !== undefined) {\n      clearTimeout(id);\n      gcTimers.delete(keyHash);\n    }\n  }\n\n  function deleteByHash(keyHash: string): boolean {\n    const record = store.get(keyHash);\n\n    cancelGcByHash(keyHash);\n\n    if (record) {\n      onEvict?.(record.key, record.value);\n      store.delete(keyHash);\n    }\n\n    if (inFlight.has(keyHash)) deletedWhileInFlight.add(keyHash);\n\n    return record !== undefined;\n  }\n\n  function scheduleGcByHash(keyHash: string, delayMs: number): void {\n    cancelGcByHash(keyHash);\n\n    if (delayMs === Number.POSITIVE_INFINITY) return;\n\n    if (!Number.isFinite(delayMs)) {\n      throw new ArsenalValidationError('stash: ttlMs must be a finite number or Infinity');\n    }\n\n    if (delayMs <= 0) {\n      deleteByHash(keyHash);\n\n      return;\n    }\n\n    if (!store.has(keyHash)) return;\n\n    const id = setTimeout(() => {\n      gcTimers.delete(keyHash);\n      deleteByHash(keyHash);\n    }, delayMs);\n\n    gcTimers.set(keyHash, id);\n  }\n\n  function deserializeValue(raw: T): T {\n    if (persistence && typeof raw === 'string') return persistence.deserialize(raw);\n\n    return raw;\n  }\n\n  function get(key: K): T | undefined {\n    const record = store.get(hash(key));\n\n    return record ? deserializeValue(record.value) : undefined;\n  }\n\n  function set(key: K, value: T, opts?: CacheSetOptions): void {\n    const keyHash = hash(key);\n    const stored = persistence ? (persistence.serialize(value) as unknown as T) : value;\n\n    cancelGcByHash(keyHash);\n    store.set(keyHash, { key, value: stored });\n    evictOldestIfOverCapacity();\n\n    const ttl = opts?.ttlMs ?? defaultTtlMs;\n\n    if (ttl !== undefined) {\n      scheduleGcByHash(keyHash, ttl);\n    }\n  }\n\n  function getOrSet(key: K, factory: () => T | Promise<T>, opts?: CacheSetOptions): T | Promise<T> {\n    const keyHash = hash(key);\n\n    if (store.has(keyHash) && !opts?.forceRefresh) return get(key) as T;\n\n    const pending = inFlight.get(keyHash);\n\n    if (pending && !opts?.forceRefresh) return pending;\n\n    const value = factory();\n\n    if (isPromise(value)) {\n      const capturedGeneration = generation;\n      const promise: Promise<T> = value\n        .then((resolved) => {\n          // Only clear the in-flight slot if it's still *this* promise — an overlapping\n          // `forceRefresh` call may have already replaced it with a newer in-flight promise.\n          if (inFlight.get(keyHash) === promise) inFlight.delete(keyHash);\n\n          if (generation === capturedGeneration && !deletedWhileInFlight.has(keyHash)) {\n            set(key, resolved, opts);\n          }\n\n          deletedWhileInFlight.delete(keyHash);\n\n          return resolved;\n        })\n        .catch((err: unknown) => {\n          if (inFlight.get(keyHash) === promise) inFlight.delete(keyHash);\n\n          deletedWhileInFlight.delete(keyHash);\n          throw err;\n        });\n\n      inFlight.set(keyHash, promise);\n\n      return promise;\n    }\n\n    set(key, value, opts);\n\n    return value;\n  }\n\n  function del(key: K): boolean {\n    return deleteByHash(hash(key));\n  }\n\n  function clear(): void {\n    generation++;\n    for (const id of gcTimers.values()) clearTimeout(id);\n\n    if (onEvict) {\n      for (const record of store.values()) {\n        onEvict(record.key, record.value);\n      }\n    }\n\n    store.clear();\n    gcTimers.clear();\n    inFlight.clear();\n    deletedWhileInFlight.clear();\n  }\n\n  function* entries(): IterableIterator<[K, T]> {\n    for (const record of store.values()) {\n      yield [record.key, deserializeValue(record.value)];\n    }\n  }\n\n  return {\n    clear,\n    delete: del,\n    entries,\n    get,\n    getOrSet: getOrSet as Stash<T, K>['getOrSet'],\n    set,\n    get size() {\n      return store.size;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/function/constant.cjs

@@ -1,2 +0,0 @@
-function e(e){return()=>e}exports.constant=e;
-//# sourceMappingURL=constant.cjs.map

package/dist/function/constant.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"constant.cjs","names":[],"sources":["../../src/function/constant.ts"],"sourcesContent":["/**\n * Returns a function that always returns the same value.\n */\nexport function constant<T>(value: T): () => T {\n  return () => value;\n}\n"],"mappings":"AAGA,SAAgB,EAAY,EAAmB,CAC7C,UAAa,CACf"}

package/dist/function/constant.d.ts

@@ -1,5 +0,0 @@
-/**
- * Returns a function that always returns the same value.
- */
-export declare function constant<T>(value: T): () => T;
-//# sourceMappingURL=constant.d.ts.map

package/dist/function/constant.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"constant.d.ts","sourceRoot":"","sources":["../../src/function/constant.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAE7C"}

package/dist/function/constant.js

@@ -1,8 +0,0 @@
-//#region src/function/constant.ts
-function e(e) {
-	return () => e;
-}
-//#endregion
-export { e as constant };
-
-//# sourceMappingURL=constant.js.map

package/dist/function/constant.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constant.js","names":[],"sources":["../../src/function/constant.ts"],"sourcesContent":["/**\n * Returns a function that always returns the same value.\n */\nexport function constant<T>(value: T): () => T {\n  return () => value;\n}\n"],"mappings":";AAGA,SAAgB,EAAY,GAAmB;CAC7C,aAAa;AACf"}

package/dist/function/identity.cjs

@@ -1,2 +0,0 @@
-function e(e){return e}exports.identity=e;
-//# sourceMappingURL=identity.cjs.map

package/dist/function/identity.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"identity.cjs","names":[],"sources":["../../src/function/identity.ts"],"sourcesContent":["/**\n * Returns the same input value.\n */\nexport function identity<T>(value: T): T {\n  return value;\n}\n"],"mappings":"AAGA,SAAgB,EAAY,EAAa,CACvC,OAAO,CACT"}

package/dist/function/identity.d.ts

@@ -1,5 +0,0 @@
-/**
- * Returns the same input value.
- */
-export declare function identity<T>(value: T): T;
-//# sourceMappingURL=identity.d.ts.map

package/dist/function/identity.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/function/identity.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEvC"}

package/dist/function/identity.js

@@ -1,8 +0,0 @@
-//#region src/function/identity.ts
-function e(e) {
-	return e;
-}
-//#endregion
-export { e as identity };
-
-//# sourceMappingURL=identity.js.map

package/dist/function/identity.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"identity.js","names":[],"sources":["../../src/function/identity.ts"],"sourcesContent":["/**\n * Returns the same input value.\n */\nexport function identity<T>(value: T): T {\n  return value;\n}\n"],"mappings":";AAGA,SAAgB,EAAY,GAAa;CACvC,OAAO;AACT"}

package/dist/guards/isArray.cjs

@@ -1,2 +0,0 @@
-function e(e,t){return Array.isArray(e)?t?e.every(t):!0:!1}exports.isArray=e;
-//# sourceMappingURL=isArray.cjs.map

package/dist/guards/isArray.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"isArray.cjs","names":[],"sources":["../../src/guards/isArray.ts"],"sourcesContent":["/**\n * Returns `true` if `value` is an `Array`, with an optional item-type guard.\n *\n * @example\n * ```ts\n * isArray([1, 2, 3])          // true\n * isArray('hello')            // false\n * isArray([1, 2, 3], isNumber) // true  — all items pass isNumber\n * isArray([1, 'x'], isNumber)  // false — 'x' fails isNumber\n * ```\n *\n * @param value - The value to check.\n * @param itemGuard - Optional type guard applied to every element.\n */\nexport function isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[] {\n  if (!Array.isArray(value)) return false;\n\n  if (itemGuard) return value.every(itemGuard);\n\n  return true;\n}\n"],"mappings":"AAcA,SAAgB,EAAqB,EAAgB,EAAwD,CAK3G,OAJK,MAAM,QAAQ,CAAK,EAEpB,EAAkB,EAAM,MAAM,CAAS,EAEpC,GAJ2B,EAKpC"}

package/dist/guards/isArray.d.ts

@@ -1,16 +0,0 @@
-/**
- * Returns `true` if `value` is an `Array`, with an optional item-type guard.
- *
- * @example
- * ```ts
- * isArray([1, 2, 3])          // true
- * isArray('hello')            // false
- * isArray([1, 2, 3], isNumber) // true  — all items pass isNumber
- * isArray([1, 'x'], isNumber)  // false — 'x' fails isNumber
- * ```
- *
- * @param value - The value to check.
- * @param itemGuard - Optional type guard applied to every element.
- */
-export declare function isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[];
-//# sourceMappingURL=isArray.d.ts.map

package/dist/guards/isArray.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"isArray.d.ts","sourceRoot":"","sources":["../../src/guards/isArray.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,CAM3G"}

package/dist/guards/isArray.js

@@ -1,8 +0,0 @@
-//#region src/guards/isArray.ts
-function e(e, t) {
-	return Array.isArray(e) ? t ? e.every(t) : !0 : !1;
-}
-//#endregion
-export { e as isArray };
-
-//# sourceMappingURL=isArray.js.map

package/dist/guards/isArray.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"isArray.js","names":[],"sources":["../../src/guards/isArray.ts"],"sourcesContent":["/**\n * Returns `true` if `value` is an `Array`, with an optional item-type guard.\n *\n * @example\n * ```ts\n * isArray([1, 2, 3])          // true\n * isArray('hello')            // false\n * isArray([1, 2, 3], isNumber) // true  — all items pass isNumber\n * isArray([1, 'x'], isNumber)  // false — 'x' fails isNumber\n * ```\n *\n * @param value - The value to check.\n * @param itemGuard - Optional type guard applied to every element.\n */\nexport function isArray<T = unknown>(value: unknown, itemGuard?: (item: unknown) => item is T): value is T[] {\n  if (!Array.isArray(value)) return false;\n\n  if (itemGuard) return value.every(itemGuard);\n\n  return true;\n}\n"],"mappings":";AAcA,SAAgB,EAAqB,GAAgB,GAAwD;CAK3G,OAJK,MAAM,QAAQ,CAAK,IAEpB,IAAkB,EAAM,MAAM,CAAS,IAEpC,KAJ2B;AAKpC"}

package/dist/guards/isBoolean.cjs

@@ -1,2 +0,0 @@
-function e(e){return typeof e==`boolean`}exports.isBoolean=e;
-//# sourceMappingURL=isBoolean.cjs.map

package/dist/guards/isBoolean.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"isBoolean.cjs","names":[],"sources":["../../src/guards/isBoolean.ts"],"sourcesContent":["/**\n * Checks if the value is a boolean.\n *\n * @example\n * ```ts\n * isBoolean(true); // true\n * isBoolean(false); // true\n * isBoolean(123); // false\n * isBoolean('hello world'); // false\n * isBoolean({}); // false\n * isBoolean([]); // false\n * isBoolean(new Date()); // false\n * isBoolean(null); // false\n * isBoolean(undefined); // false\n * isBoolean(NaN); // false\n * ```\n *\n * @param arg - The argument to be checked.\n *\n * @returns `true` if the value is a boolean, else `false`.\n */\nexport function isBoolean(arg: unknown): arg is boolean {\n  return typeof arg === 'boolean';\n}\n"],"mappings":"AAqBA,SAAgB,EAAU,EAA8B,CACtD,OAAO,OAAO,GAAQ,SACxB"}

package/dist/guards/isBoolean.d.ts

@@ -1,23 +0,0 @@
-/**
- * Checks if the value is a boolean.
- *
- * @example
- * ```ts
- * isBoolean(true); // true
- * isBoolean(false); // true
- * isBoolean(123); // false
- * isBoolean('hello world'); // false
- * isBoolean({}); // false
- * isBoolean([]); // false
- * isBoolean(new Date()); // false
- * isBoolean(null); // false
- * isBoolean(undefined); // false
- * isBoolean(NaN); // false
- * ```
- *
- * @param arg - The argument to be checked.
- *
- * @returns `true` if the value is a boolean, else `false`.
- */
-export declare function isBoolean(arg: unknown): arg is boolean;
-//# sourceMappingURL=isBoolean.d.ts.map

package/dist/guards/isBoolean.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"isBoolean.d.ts","sourceRoot":"","sources":["../../src/guards/isBoolean.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CAEtD"}

package/dist/guards/isBoolean.js

@@ -1,8 +0,0 @@
-//#region src/guards/isBoolean.ts
-function e(e) {
-	return typeof e == "boolean";
-}
-//#endregion
-export { e as isBoolean };
-
-//# sourceMappingURL=isBoolean.js.map

package/dist/guards/isBoolean.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"isBoolean.js","names":[],"sources":["../../src/guards/isBoolean.ts"],"sourcesContent":["/**\n * Checks if the value is a boolean.\n *\n * @example\n * ```ts\n * isBoolean(true); // true\n * isBoolean(false); // true\n * isBoolean(123); // false\n * isBoolean('hello world'); // false\n * isBoolean({}); // false\n * isBoolean([]); // false\n * isBoolean(new Date()); // false\n * isBoolean(null); // false\n * isBoolean(undefined); // false\n * isBoolean(NaN); // false\n * ```\n *\n * @param arg - The argument to be checked.\n *\n * @returns `true` if the value is a boolean, else `false`.\n */\nexport function isBoolean(arg: unknown): arg is boolean {\n  return typeof arg === 'boolean';\n}\n"],"mappings":";AAqBA,SAAgB,EAAU,GAA8B;CACtD,OAAO,OAAO,KAAQ;AACxB"}

package/dist/guards/isString.cjs

@@ -1,2 +0,0 @@
-function e(e){return typeof e==`string`}exports.isString=e;
-//# sourceMappingURL=isString.cjs.map

package/dist/guards/isString.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"isString.cjs","names":[],"sources":["../../src/guards/isString.ts"],"sourcesContent":["/**\n * Determines if the passed value is a String.\n *\n * @example\n * ```ts\n * isString('Hello World'); // true\n * isString(42); // false\n * ```\n *\n * @param arg - The argument to be checked.\n *\n * @returns `true` if the value is a String, else `false`.\n */\nexport function isString(arg: unknown): arg is string {\n  return typeof arg === 'string';\n}\n"],"mappings":"AAaA,SAAgB,EAAS,EAA6B,CACpD,OAAO,OAAO,GAAQ,QACxB"}