@vielzeug/arsenal 1.0.1

package/dist/async/sleep.js

@@ -0,0 +1,16 @@
+import { abortError as e } from "./abortError.js";
+//#region src/async/sleep.ts
+async function t(t, n) {
+	return n ? n.aborted ? Promise.reject(e(n)) : new Promise((r, i) => {
+		let a = setTimeout(() => {
+			n.removeEventListener("abort", o), r();
+		}, t), o = () => {
+			clearTimeout(a), n.removeEventListener("abort", o), i(e(n));
+		};
+		n.addEventListener("abort", o);
+	}) : new Promise((e) => setTimeout(e, t));
+}
+//#endregion
+export { t as sleep };
+
+//# sourceMappingURL=sleep.js.map

package/dist/async/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","names":[],"sources":["../../src/async/sleep.ts"],"sourcesContent":["import { abortError } from './abortError';\n\n/**\n * Creates a Promise that resolves after a specified amount of time.\n * If an `AbortSignal` is provided and fires before the delay elapses, the promise rejects with\n * the signal's reason (or a generic `DOMException('Aborted', 'AbortError')`).\n *\n * @example\n * ```ts\n * sleep(1000).then(() => console.log('Hello, world!')); // logs after 1 second\n *\n * // With abort support\n * const controller = new AbortController();\n * await sleep(5000, controller.signal); // rejects immediately when aborted\n * ```\n *\n * @param timeout - The number of milliseconds to wait before resolving the Promise.\n * @param signal  - Optional AbortSignal to cancel the sleep early.\n *\n * @returns A Promise that resolves after the specified time.\n */\nexport async function sleep(timeout: number, signal?: AbortSignal): Promise<void> {\n  if (!signal) {\n    return new Promise((resolve) => setTimeout(resolve, timeout));\n  }\n\n  if (signal.aborted) {\n    return Promise.reject(abortError(signal));\n  }\n\n  return new Promise<void>((resolve, reject) => {\n    const id = setTimeout(() => {\n      signal.removeEventListener('abort', onAbort);\n      resolve();\n    }, timeout);\n\n    const onAbort = () => {\n      clearTimeout(id);\n      signal.removeEventListener('abort', onAbort);\n      reject(abortError(signal));\n    };\n\n    signal.addEventListener('abort', onAbort);\n  });\n}\n"],"mappings":";;AAqBA,eAAsB,EAAM,GAAiB,GAAqC;CAShF,OARK,IAID,EAAO,UACF,QAAQ,OAAO,EAAW,CAAM,CAAC,IAGnC,IAAI,SAAe,GAAS,MAAW;EAC5C,IAAM,IAAK,iBAAiB;GAE1B,AADA,EAAO,oBAAoB,SAAS,CAAO,GAC3C,EAAQ;EACV,GAAG,CAAO,GAEJ,UAAgB;GAGpB,AAFA,aAAa,CAAE,GACf,EAAO,oBAAoB,SAAS,CAAO,GAC3C,EAAO,EAAW,CAAM,CAAC;EAC3B;EAEA,EAAO,iBAAiB,SAAS,CAAO;CAC1C,CAAC,IApBQ,IAAI,SAAS,MAAY,WAAW,GAAS,CAAO,CAAC;AAqBhE"}

package/dist/async/waitFor.cjs

@@ -0,0 +1,2 @@
+const e=require("./sleep.cjs");async function t(t,{interval:n=100,signal:r,timeout:i=5e3}={}){let a=AbortSignal.timeout(i),o=r?AbortSignal.any([r,a]):a;for(o.throwIfAborted();;){if(o.throwIfAborted(),await t(o))return;await e.sleep(n,o)}}exports.waitFor=t;
+//# sourceMappingURL=waitFor.cjs.map

package/dist/async/waitFor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"waitFor.cjs","names":[],"sources":["../../src/async/waitFor.ts"],"sourcesContent":["import { sleep } from './sleep';\n\nexport type WaitForOptions = {\n  interval?: number;\n  signal?: AbortSignal;\n  timeout?: number;\n};\n\n/**\n * Waits for a condition to become true by polling.\n * Useful for waiting for DOM elements, API states, or other conditions.\n *\n * @example\n * ```ts\n * // Wait for an element to appear\n * await waitFor(() => document.querySelector('#myElement') !== null);\n *\n * // Wait for API to be ready with cancellation support\n * await waitFor(\n *   async (signal) => {\n *     const res = await fetch('/api/health', { signal });\n *     return res.ok;\n *   },\n *   { timeout: 30000, interval: 1000 },\n * );\n * ```\n *\n * @param condition - Polling function that receives the merged AbortSignal and returns true when the condition is met\n * @param options - Configuration options\n * @param [options.timeout=5000] - Maximum time to wait in ms\n * @param [options.interval=100] - Polling interval in ms\n * @param [options.signal] - AbortSignal to cancel waiting\n * @returns Promise that resolves when condition becomes true\n * @throws Rejects with the abort reason when timed out or cancelled\n */\nexport async function waitFor(\n  condition: (signal: AbortSignal) => boolean | Promise<boolean>,\n  { interval = 100, signal, timeout: ms = 5000 }: WaitForOptions = {},\n): Promise<void> {\n  const deadline = AbortSignal.timeout(ms);\n  const merged = signal ? AbortSignal.any([signal, deadline]) : deadline;\n\n  merged.throwIfAborted();\n\n  while (true) {\n    merged.throwIfAborted();\n\n    if (await condition(merged)) return;\n\n    await sleep(interval, merged);\n  }\n}\n"],"mappings":"+BAmCA,eAAsB,EACpB,EACA,CAAE,WAAW,IAAK,SAAQ,QAAS,EAAK,KAAyB,CAAC,EACnD,CACf,IAAM,EAAW,YAAY,QAAQ,CAAE,EACjC,EAAS,EAAS,YAAY,IAAI,CAAC,EAAQ,CAAQ,CAAC,EAAI,EAI9D,IAFA,EAAO,eAAe,IAET,CAGX,GAFA,EAAO,eAAe,EAElB,MAAM,EAAU,CAAM,EAAG,OAE7B,MAAM,EAAA,MAAM,EAAU,CAAM,CAC9B,CACF"}

package/dist/async/waitFor.d.ts

@@ -0,0 +1,34 @@
+export type WaitForOptions = {
+    interval?: number;
+    signal?: AbortSignal;
+    timeout?: number;
+};
+/**
+ * Waits for a condition to become true by polling.
+ * Useful for waiting for DOM elements, API states, or other conditions.
+ *
+ * @example
+ * ```ts
+ * // Wait for an element to appear
+ * await waitFor(() => document.querySelector('#myElement') !== null);
+ *
+ * // Wait for API to be ready with cancellation support
+ * await waitFor(
+ *   async (signal) => {
+ *     const res = await fetch('/api/health', { signal });
+ *     return res.ok;
+ *   },
+ *   { timeout: 30000, interval: 1000 },
+ * );
+ * ```
+ *
+ * @param condition - Polling function that receives the merged AbortSignal and returns true when the condition is met
+ * @param options - Configuration options
+ * @param [options.timeout=5000] - Maximum time to wait in ms
+ * @param [options.interval=100] - Polling interval in ms
+ * @param [options.signal] - AbortSignal to cancel waiting
+ * @returns Promise that resolves when condition becomes true
+ * @throws Rejects with the abort reason when timed out or cancelled
+ */
+export declare function waitFor(condition: (signal: AbortSignal) => boolean | Promise<boolean>, { interval, signal, timeout: ms }?: WaitForOptions): Promise<void>;
+//# sourceMappingURL=waitFor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"waitFor.d.ts","sourceRoot":"","sources":["../../src/async/waitFor.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAC9D,EAAE,QAAc,EAAE,MAAM,EAAE,OAAO,EAAE,EAAS,EAAE,GAAE,cAAmB,GAClE,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/async/waitFor.js

@@ -0,0 +1,13 @@
+import { sleep as e } from "./sleep.js";
+//#region src/async/waitFor.ts
+async function t(t, { interval: n = 100, signal: r, timeout: i = 5e3 } = {}) {
+	let a = AbortSignal.timeout(i), o = r ? AbortSignal.any([r, a]) : a;
+	for (o.throwIfAborted();;) {
+		if (o.throwIfAborted(), await t(o)) return;
+		await e(n, o);
+	}
+}
+//#endregion
+export { t as waitFor };
+
+//# sourceMappingURL=waitFor.js.map

package/dist/async/waitFor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waitFor.js","names":[],"sources":["../../src/async/waitFor.ts"],"sourcesContent":["import { sleep } from './sleep';\n\nexport type WaitForOptions = {\n  interval?: number;\n  signal?: AbortSignal;\n  timeout?: number;\n};\n\n/**\n * Waits for a condition to become true by polling.\n * Useful for waiting for DOM elements, API states, or other conditions.\n *\n * @example\n * ```ts\n * // Wait for an element to appear\n * await waitFor(() => document.querySelector('#myElement') !== null);\n *\n * // Wait for API to be ready with cancellation support\n * await waitFor(\n *   async (signal) => {\n *     const res = await fetch('/api/health', { signal });\n *     return res.ok;\n *   },\n *   { timeout: 30000, interval: 1000 },\n * );\n * ```\n *\n * @param condition - Polling function that receives the merged AbortSignal and returns true when the condition is met\n * @param options - Configuration options\n * @param [options.timeout=5000] - Maximum time to wait in ms\n * @param [options.interval=100] - Polling interval in ms\n * @param [options.signal] - AbortSignal to cancel waiting\n * @returns Promise that resolves when condition becomes true\n * @throws Rejects with the abort reason when timed out or cancelled\n */\nexport async function waitFor(\n  condition: (signal: AbortSignal) => boolean | Promise<boolean>,\n  { interval = 100, signal, timeout: ms = 5000 }: WaitForOptions = {},\n): Promise<void> {\n  const deadline = AbortSignal.timeout(ms);\n  const merged = signal ? AbortSignal.any([signal, deadline]) : deadline;\n\n  merged.throwIfAborted();\n\n  while (true) {\n    merged.throwIfAborted();\n\n    if (await condition(merged)) return;\n\n    await sleep(interval, merged);\n  }\n}\n"],"mappings":";;AAmCA,eAAsB,EACpB,GACA,EAAE,cAAW,KAAK,WAAQ,SAAS,IAAK,QAAyB,CAAC,GACnD;CACf,IAAM,IAAW,YAAY,QAAQ,CAAE,GACjC,IAAS,IAAS,YAAY,IAAI,CAAC,GAAQ,CAAQ,CAAC,IAAI;CAI9D,KAFA,EAAO,eAAe,KAET;EAGX,IAFA,EAAO,eAAe,GAElB,MAAM,EAAU,CAAM,GAAG;EAE7B,MAAM,EAAM,GAAU,CAAM;CAC9B;AACF"}

package/dist/cache/index.d.ts

@@ -0,0 +1,3 @@
+export * from './memo';
+export * from './stash';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/cache/memo.cjs

@@ -0,0 +1,2 @@
+const e=require("../errors.cjs"),t=require("../_common/_lruMap.cjs");var n=`\0undefined\0`,r=`\0NaN\0`,i=`\0+Infinity\0`,a=`\0-Infinity\0`,o=`\0function\0`,s=0,c=new WeakMap;function l(e){let t=c.get(e);return t===void 0&&(t=s++,c.set(e,t)),t}var u=t=>{try{return JSON.stringify(t,(e,t)=>t===void 0?n:typeof t==`number`&&Number.isNaN(t)?r:t===1/0?i:t===-1/0?a:typeof t==`function`?`${o}${l(t)}`:t)}catch(t){throw new e.ArsenalSerializationError(`[arsenal/memo] Failed to serialize memo arguments. Provide options.key for non-serializable arguments.${t instanceof Error&&t.message?` Reason: ${t.message}`:``}`,{cause:t})}};function d(n,{key:r,maxSize:i=1/0}={}){if(i!==1/0&&(!Number.isInteger(i)||i<1))throw new e.ArsenalValidationError(`memo: maxSize must be a positive integer or Infinity, got ${i}`);let a=new t.LruMap(i),o=(...e)=>r?r(...e):u(e),s=Object.assign((...e)=>{let t=o(...e);if(a.has(t)){let e=a.get(t);return a.set(t,e),e}let r=n(...e);return a.set(t,r),r},{clear:()=>a.clear(),invalidate:(...e)=>{a.delete(o(...e))}});return Object.defineProperty(s,"size",{get:()=>a.size}),s}exports.memo=d;
+//# sourceMappingURL=memo.cjs.map

package/dist/cache/memo.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memo.cjs","names":[],"sources":["../../src/cache/memo.ts"],"sourcesContent":["import type { Fn } from '../types';\n\nimport { LruMap } from '../_common/_lruMap';\nimport { ArsenalSerializationError, ArsenalValidationError } from '../errors';\n\nexport type MemoOptions<T extends Fn> = {\n  key?: (...args: Parameters<T>) => PropertyKey;\n  maxSize?: number;\n};\n\nexport type Memoized<T extends Fn> = ((...args: Parameters<T>) => ReturnType<T>) & {\n  clear(): void;\n  invalidate(...args: Parameters<T>): void;\n  readonly size: number;\n};\n\nconst UNDEFINED_SENTINEL = '\\x00undefined\\x00';\nconst NAN_SENTINEL = '\\x00NaN\\x00';\nconst POSITIVE_INFINITY_SENTINEL = '\\x00+Infinity\\x00';\nconst NEGATIVE_INFINITY_SENTINEL = '\\x00-Infinity\\x00';\nconst FUNCTION_SENTINEL = '\\x00function\\x00';\n\nlet functionIdCounter = 0;\nconst functionIds = new WeakMap<Fn, number>();\n\n/** Returns a stable per-identity id for a function so distinct functions never collide as cache keys. */\nfunction idForFunction(fn: Fn): number {\n  let id = functionIds.get(fn);\n\n  if (id === undefined) {\n    id = functionIdCounter++;\n    functionIds.set(fn, id);\n  }\n\n  return id;\n}\n\nconst defaultKey = (args: unknown[]): string => {\n  try {\n    return JSON.stringify(args, (_, value) => {\n      if (value === undefined) return UNDEFINED_SENTINEL;\n\n      if (typeof value === 'number' && Number.isNaN(value)) return NAN_SENTINEL;\n\n      if (value === Number.POSITIVE_INFINITY) return POSITIVE_INFINITY_SENTINEL;\n\n      if (value === Number.NEGATIVE_INFINITY) return NEGATIVE_INFINITY_SENTINEL;\n\n      if (typeof value === 'function') return `${FUNCTION_SENTINEL}${idForFunction(value as Fn)}`;\n\n      return value;\n    });\n  } catch (error) {\n    const reason = error instanceof Error && error.message ? ` Reason: ${error.message}` : '';\n\n    throw new ArsenalSerializationError(\n      `[arsenal/memo] Failed to serialize memo arguments. Provide options.key for non-serializable arguments.${reason}`,\n      { cause: error },\n    );\n  }\n};\n\n/** Excludes async functions at the type level so callers cannot accidentally memoize a Promise. */\ntype SyncFn<T extends Fn> = ReturnType<T> extends Promise<unknown> ? never : T;\n\n/**\n * Memoizes a **sync** function with optional LRU eviction by cache size.\n * The returned function exposes `.clear()` and `.invalidate(...args)` methods.\n *\n * **Do not pass async functions.** `memo` caches the raw `Promise` object, not\n * the resolved value — subsequent calls return the same stale Promise. Use\n * `stash.getOrSet` for async caching with TTL and stampede prevention.\n *\n * @example\n * ```ts\n * const add = (x: number, y: number) => x + y;\n * const memoAdd = memo(add, { maxSize: 100 });\n *\n * memoAdd(1, 2); // 3 (computed)\n * memoAdd(1, 2); // 3 (from cache)\n * memoAdd.invalidate(1, 2); // remove specific entry\n * memoAdd.clear(); // wipe entire cache\n * ```\n *\n * @param fn - The sync function to memoize. Must not return a Promise.\n * @param [options.maxSize] - Maximum cache size. Oldest entries evicted when exceeded (LRU). Default: `Infinity`.\n * @param [options.key] - Custom cache key function. Defaults to `JSON.stringify(args)`.\n *\n * @throws {ArsenalValidationError} If `maxSize` is not a positive integer or `Infinity`.\n */\nexport function memo<T extends Fn>(fn: SyncFn<T>, { key, maxSize = Infinity }: MemoOptions<T> = {}): Memoized<T> {\n  if (maxSize !== Infinity && (!Number.isInteger(maxSize) || maxSize < 1)) {\n    throw new ArsenalValidationError(`memo: maxSize must be a positive integer or Infinity, got ${maxSize}`);\n  }\n\n  const cache = new LruMap<PropertyKey, ReturnType<T>>(maxSize);\n\n  const resolveKey = (...args: Parameters<T>): PropertyKey => (key ? key(...args) : defaultKey(args));\n\n  const memoized = (...args: Parameters<T>): ReturnType<T> => {\n    const cacheKey = resolveKey(...args);\n\n    if (cache.has(cacheKey)) {\n      const cached = cache.get(cacheKey)!;\n\n      cache.set(cacheKey, cached);\n\n      return cached;\n    }\n\n    const value = fn(...args) as ReturnType<T>;\n\n    cache.set(cacheKey, value);\n\n    return value;\n  };\n\n  const result = Object.assign(memoized, {\n    clear: () => cache.clear(),\n    invalidate: (...args: Parameters<T>): void => {\n      cache.delete(resolveKey(...args));\n    },\n  });\n\n  Object.defineProperty(result, 'size', { get: () => cache.size });\n\n  return result as Memoized<T>;\n}\n"],"mappings":"qEAgBA,IAAM,EAAqB,gBACrB,EAAe,UACf,EAA6B,gBAC7B,EAA6B,gBAC7B,EAAoB,eAEtB,EAAoB,EAClB,EAAc,IAAI,QAGxB,SAAS,EAAc,EAAgB,CACrC,IAAI,EAAK,EAAY,IAAI,CAAE,EAO3B,OALI,IAAO,IAAA,KACT,EAAK,IACL,EAAY,IAAI,EAAI,CAAE,GAGjB,CACT,CAEA,IAAM,EAAc,GAA4B,CAC9C,GAAI,CACF,OAAO,KAAK,UAAU,GAAO,EAAG,IAC1B,IAAU,IAAA,GAAkB,EAE5B,OAAO,GAAU,UAAY,OAAO,MAAM,CAAK,EAAU,EAEzD,IAAU,IAAiC,EAE3C,IAAU,KAAiC,EAE3C,OAAO,GAAU,WAAmB,GAAG,IAAoB,EAAc,CAAW,IAEjF,CACR,CACH,OAAS,EAAO,CAGd,MAAM,IAAI,EAAA,0BACR,yGAHa,aAAiB,OAAS,EAAM,QAAU,YAAY,EAAM,UAAY,KAIrF,CAAE,MAAO,CAAM,CACjB,CACF,CACF,EA8BA,SAAgB,EAAmB,EAAe,CAAE,MAAK,UAAU,KAA6B,CAAC,EAAgB,CAC/G,GAAI,IAAY,MAAa,CAAC,OAAO,UAAU,CAAO,GAAK,EAAU,GACnE,MAAM,IAAI,EAAA,uBAAuB,6DAA6D,GAAS,EAGzG,IAAM,EAAQ,IAAI,EAAA,OAAmC,CAAO,EAEtD,GAAc,GAAG,IAAsC,EAAM,EAAI,GAAG,CAAI,EAAI,EAAW,CAAI,EAoB3F,EAAS,OAAO,QAlBJ,GAAG,IAAuC,CAC1D,IAAM,EAAW,EAAW,GAAG,CAAI,EAEnC,GAAI,EAAM,IAAI,CAAQ,EAAG,CACvB,IAAM,EAAS,EAAM,IAAI,CAAQ,EAIjC,OAFA,EAAM,IAAI,EAAU,CAAM,EAEnB,CACT,CAEA,IAAM,EAAQ,EAAG,GAAG,CAAI,EAIxB,OAFA,EAAM,IAAI,EAAU,CAAK,EAElB,CACT,EAEuC,CACrC,UAAa,EAAM,MAAM,EACzB,YAAa,GAAG,IAA8B,CAC5C,EAAM,OAAO,EAAW,GAAG,CAAI,CAAC,CAClC,CACF,CAAC,EAID,OAFA,OAAO,eAAe,EAAQ,OAAQ,CAAE,QAAW,EAAM,IAAK,CAAC,EAExD,CACT"}

package/dist/cache/memo.d.ts

@@ -0,0 +1,40 @@
+import type { Fn } from '../types';
+export type MemoOptions<T extends Fn> = {
+    key?: (...args: Parameters<T>) => PropertyKey;
+    maxSize?: number;
+};
+export type Memoized<T extends Fn> = ((...args: Parameters<T>) => ReturnType<T>) & {
+    clear(): void;
+    invalidate(...args: Parameters<T>): void;
+    readonly size: number;
+};
+/** Excludes async functions at the type level so callers cannot accidentally memoize a Promise. */
+type SyncFn<T extends Fn> = ReturnType<T> extends Promise<unknown> ? never : T;
+/**
+ * Memoizes a **sync** function with optional LRU eviction by cache size.
+ * The returned function exposes `.clear()` and `.invalidate(...args)` methods.
+ *
+ * **Do not pass async functions.** `memo` caches the raw `Promise` object, not
+ * the resolved value — subsequent calls return the same stale Promise. Use
+ * `stash.getOrSet` for async caching with TTL and stampede prevention.
+ *
+ * @example
+ * ```ts
+ * const add = (x: number, y: number) => x + y;
+ * const memoAdd = memo(add, { maxSize: 100 });
+ *
+ * memoAdd(1, 2); // 3 (computed)
+ * memoAdd(1, 2); // 3 (from cache)
+ * memoAdd.invalidate(1, 2); // remove specific entry
+ * memoAdd.clear(); // wipe entire cache
+ * ```
+ *
+ * @param fn - The sync function to memoize. Must not return a Promise.
+ * @param [options.maxSize] - Maximum cache size. Oldest entries evicted when exceeded (LRU). Default: `Infinity`.
+ * @param [options.key] - Custom cache key function. Defaults to `JSON.stringify(args)`.
+ *
+ * @throws {ArsenalValidationError} If `maxSize` is not a positive integer or `Infinity`.
+ */
+export declare function memo<T extends Fn>(fn: SyncFn<T>, { key, maxSize }?: MemoOptions<T>): Memoized<T>;
+export {};
+//# sourceMappingURL=memo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../../src/cache/memo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAKnC,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,EAAE,IAAI;IACtC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG;IACjF,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAgDF,mGAAmG;AACnG,KAAK,MAAM,CAAC,CAAC,SAAS,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,OAAkB,EAAE,GAAE,WAAW,CAAC,CAAC,CAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAqC/G"}

package/dist/cache/memo.js

@@ -0,0 +1,37 @@
+import { ArsenalSerializationError as e, ArsenalValidationError as t } from "../errors.js";
+import { LruMap as n } from "../_common/_lruMap.js";
+//#region src/cache/memo.ts
+var r = "\0undefined\0", i = "\0NaN\0", a = "\0+Infinity\0", o = "\0-Infinity\0", s = "\0function\0", c = 0, l = /* @__PURE__ */ new WeakMap();
+function u(e) {
+	let t = l.get(e);
+	return t === void 0 && (t = c++, l.set(e, t)), t;
+}
+var d = (t) => {
+	try {
+		return JSON.stringify(t, (e, t) => t === void 0 ? r : typeof t == "number" && Number.isNaN(t) ? i : t === Infinity ? a : t === -Infinity ? o : typeof t == "function" ? `${s}${u(t)}` : t);
+	} catch (t) {
+		throw new e(`[arsenal/memo] Failed to serialize memo arguments. Provide options.key for non-serializable arguments.${t instanceof Error && t.message ? ` Reason: ${t.message}` : ""}`, { cause: t });
+	}
+};
+function f(e, { key: r, maxSize: i = Infinity } = {}) {
+	if (i !== Infinity && (!Number.isInteger(i) || i < 1)) throw new t(`memo: maxSize must be a positive integer or Infinity, got ${i}`);
+	let a = new n(i), o = (...e) => r ? r(...e) : d(e), s = Object.assign((...t) => {
+		let n = o(...t);
+		if (a.has(n)) {
+			let e = a.get(n);
+			return a.set(n, e), e;
+		}
+		let r = e(...t);
+		return a.set(n, r), r;
+	}, {
+		clear: () => a.clear(),
+		invalidate: (...e) => {
+			a.delete(o(...e));
+		}
+	});
+	return Object.defineProperty(s, "size", { get: () => a.size }), s;
+}
+//#endregion
+export { f as memo };
+
+//# sourceMappingURL=memo.js.map

package/dist/cache/memo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memo.js","names":[],"sources":["../../src/cache/memo.ts"],"sourcesContent":["import type { Fn } from '../types';\n\nimport { LruMap } from '../_common/_lruMap';\nimport { ArsenalSerializationError, ArsenalValidationError } from '../errors';\n\nexport type MemoOptions<T extends Fn> = {\n  key?: (...args: Parameters<T>) => PropertyKey;\n  maxSize?: number;\n};\n\nexport type Memoized<T extends Fn> = ((...args: Parameters<T>) => ReturnType<T>) & {\n  clear(): void;\n  invalidate(...args: Parameters<T>): void;\n  readonly size: number;\n};\n\nconst UNDEFINED_SENTINEL = '\\x00undefined\\x00';\nconst NAN_SENTINEL = '\\x00NaN\\x00';\nconst POSITIVE_INFINITY_SENTINEL = '\\x00+Infinity\\x00';\nconst NEGATIVE_INFINITY_SENTINEL = '\\x00-Infinity\\x00';\nconst FUNCTION_SENTINEL = '\\x00function\\x00';\n\nlet functionIdCounter = 0;\nconst functionIds = new WeakMap<Fn, number>();\n\n/** Returns a stable per-identity id for a function so distinct functions never collide as cache keys. */\nfunction idForFunction(fn: Fn): number {\n  let id = functionIds.get(fn);\n\n  if (id === undefined) {\n    id = functionIdCounter++;\n    functionIds.set(fn, id);\n  }\n\n  return id;\n}\n\nconst defaultKey = (args: unknown[]): string => {\n  try {\n    return JSON.stringify(args, (_, value) => {\n      if (value === undefined) return UNDEFINED_SENTINEL;\n\n      if (typeof value === 'number' && Number.isNaN(value)) return NAN_SENTINEL;\n\n      if (value === Number.POSITIVE_INFINITY) return POSITIVE_INFINITY_SENTINEL;\n\n      if (value === Number.NEGATIVE_INFINITY) return NEGATIVE_INFINITY_SENTINEL;\n\n      if (typeof value === 'function') return `${FUNCTION_SENTINEL}${idForFunction(value as Fn)}`;\n\n      return value;\n    });\n  } catch (error) {\n    const reason = error instanceof Error && error.message ? ` Reason: ${error.message}` : '';\n\n    throw new ArsenalSerializationError(\n      `[arsenal/memo] Failed to serialize memo arguments. Provide options.key for non-serializable arguments.${reason}`,\n      { cause: error },\n    );\n  }\n};\n\n/** Excludes async functions at the type level so callers cannot accidentally memoize a Promise. */\ntype SyncFn<T extends Fn> = ReturnType<T> extends Promise<unknown> ? never : T;\n\n/**\n * Memoizes a **sync** function with optional LRU eviction by cache size.\n * The returned function exposes `.clear()` and `.invalidate(...args)` methods.\n *\n * **Do not pass async functions.** `memo` caches the raw `Promise` object, not\n * the resolved value — subsequent calls return the same stale Promise. Use\n * `stash.getOrSet` for async caching with TTL and stampede prevention.\n *\n * @example\n * ```ts\n * const add = (x: number, y: number) => x + y;\n * const memoAdd = memo(add, { maxSize: 100 });\n *\n * memoAdd(1, 2); // 3 (computed)\n * memoAdd(1, 2); // 3 (from cache)\n * memoAdd.invalidate(1, 2); // remove specific entry\n * memoAdd.clear(); // wipe entire cache\n * ```\n *\n * @param fn - The sync function to memoize. Must not return a Promise.\n * @param [options.maxSize] - Maximum cache size. Oldest entries evicted when exceeded (LRU). Default: `Infinity`.\n * @param [options.key] - Custom cache key function. Defaults to `JSON.stringify(args)`.\n *\n * @throws {ArsenalValidationError} If `maxSize` is not a positive integer or `Infinity`.\n */\nexport function memo<T extends Fn>(fn: SyncFn<T>, { key, maxSize = Infinity }: MemoOptions<T> = {}): Memoized<T> {\n  if (maxSize !== Infinity && (!Number.isInteger(maxSize) || maxSize < 1)) {\n    throw new ArsenalValidationError(`memo: maxSize must be a positive integer or Infinity, got ${maxSize}`);\n  }\n\n  const cache = new LruMap<PropertyKey, ReturnType<T>>(maxSize);\n\n  const resolveKey = (...args: Parameters<T>): PropertyKey => (key ? key(...args) : defaultKey(args));\n\n  const memoized = (...args: Parameters<T>): ReturnType<T> => {\n    const cacheKey = resolveKey(...args);\n\n    if (cache.has(cacheKey)) {\n      const cached = cache.get(cacheKey)!;\n\n      cache.set(cacheKey, cached);\n\n      return cached;\n    }\n\n    const value = fn(...args) as ReturnType<T>;\n\n    cache.set(cacheKey, value);\n\n    return value;\n  };\n\n  const result = Object.assign(memoized, {\n    clear: () => cache.clear(),\n    invalidate: (...args: Parameters<T>): void => {\n      cache.delete(resolveKey(...args));\n    },\n  });\n\n  Object.defineProperty(result, 'size', { get: () => cache.size });\n\n  return result as Memoized<T>;\n}\n"],"mappings":";;;AAgBA,IAAM,IAAqB,iBACrB,IAAe,WACf,IAA6B,iBAC7B,IAA6B,iBAC7B,IAAoB,gBAEtB,IAAoB,GAClB,oBAAc,IAAI,QAAoB;AAG5C,SAAS,EAAc,GAAgB;CACrC,IAAI,IAAK,EAAY,IAAI,CAAE;CAO3B,OALI,MAAO,KAAA,MACT,IAAK,KACL,EAAY,IAAI,GAAI,CAAE,IAGjB;AACT;AAEA,IAAM,KAAc,MAA4B;CAC9C,IAAI;EACF,OAAO,KAAK,UAAU,IAAO,GAAG,MAC1B,MAAU,KAAA,IAAkB,IAE5B,OAAO,KAAU,YAAY,OAAO,MAAM,CAAK,IAAU,IAEzD,MAAU,WAAiC,IAE3C,MAAU,YAAiC,IAE3C,OAAO,KAAU,aAAmB,GAAG,IAAoB,EAAc,CAAW,MAEjF,CACR;CACH,SAAS,GAAO;EAGd,MAAM,IAAI,EACR,yGAHa,aAAiB,SAAS,EAAM,UAAU,YAAY,EAAM,YAAY,MAIrF,EAAE,OAAO,EAAM,CACjB;CACF;AACF;AA8BA,SAAgB,EAAmB,GAAe,EAAE,QAAK,aAAU,aAA6B,CAAC,GAAgB;CAC/G,IAAI,MAAY,aAAa,CAAC,OAAO,UAAU,CAAO,KAAK,IAAU,IACnE,MAAM,IAAI,EAAuB,6DAA6D,GAAS;CAGzG,IAAM,IAAQ,IAAI,EAAmC,CAAO,GAEtD,KAAc,GAAG,MAAsC,IAAM,EAAI,GAAG,CAAI,IAAI,EAAW,CAAI,GAoB3F,IAAS,OAAO,QAlBJ,GAAG,MAAuC;EAC1D,IAAM,IAAW,EAAW,GAAG,CAAI;EAEnC,IAAI,EAAM,IAAI,CAAQ,GAAG;GACvB,IAAM,IAAS,EAAM,IAAI,CAAQ;GAIjC,OAFA,EAAM,IAAI,GAAU,CAAM,GAEnB;EACT;EAEA,IAAM,IAAQ,EAAG,GAAG,CAAI;EAIxB,OAFA,EAAM,IAAI,GAAU,CAAK,GAElB;CACT,GAEuC;EACrC,aAAa,EAAM,MAAM;EACzB,aAAa,GAAG,MAA8B;GAC5C,EAAM,OAAO,EAAW,GAAG,CAAI,CAAC;EAClC;CACF,CAAC;CAID,OAFA,OAAO,eAAe,GAAQ,QAAQ,EAAE,WAAW,EAAM,KAAK,CAAC,GAExD;AACT"}

package/dist/cache/stash.cjs

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,111 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,92 @@
+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

@@ -0,0 +1 @@
+{"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":";;;AAyHA,SAAgB,EAAqB,IAA8B,CAAC,GAAgB;CAClF,IAAM,IAAU,EAAQ,WAAW;CAEnC,IAAI,MAAY,aAAa,CAAC,OAAO,UAAU,CAAO,KAAK,IAAU,IACnE,MAAM,IAAI,EAAuB,8DAA8D,GAAS;CAG1G,IAAM,oBAAQ,IAAI,IAA+B,GAC3C,oBAAW,IAAI,IAA2C,GAC1D,oBAAW,IAAI,IAAwB,GACvC,IAAO,EAAQ,UAAU,MAAW,OAAO,CAAG,IAC9C,IAAU,EAAQ,SAClB,IAAe,EAAQ,OACvB,IAAc,EAAQ,aACxB,IAAa,GACX,oBAAuB,IAAI,IAAY;CAE7C,SAAS,IAAkC;EACzC,IAAI,EAAM,OAAO,GAAS;GACxB,IAAM,CAAC,KAAa,EAAM,KAAK;GAE/B,AAAI,MAAc,KAAA,KAChB,EAAa,CAAS;EAE1B;CACF;CAEA,SAAS,EAAe,GAAuB;EAC7C,IAAM,IAAK,EAAS,IAAI,CAAO;EAE/B,AAAI,MAAO,KAAA,MACT,aAAa,CAAE,GACf,EAAS,OAAO,CAAO;CAE3B;CAEA,SAAS,EAAa,GAA0B;EAC9C,IAAM,IAAS,EAAM,IAAI,CAAO;EAWhC,OATA,EAAe,CAAO,GAElB,MACF,IAAU,EAAO,KAAK,EAAO,KAAK,GAClC,EAAM,OAAO,CAAO,IAGlB,EAAS,IAAI,CAAO,KAAG,EAAqB,IAAI,CAAO,GAEpD,MAAW,KAAA;CACpB;CAEA,SAAS,EAAiB,GAAiB,GAAuB;EAGhE,IAFA,EAAe,CAAO,GAElB,MAAY,UAA0B;EAE1C,IAAI,CAAC,OAAO,SAAS,CAAO,GAC1B,MAAM,IAAI,EAAuB,kDAAkD;EAGrF,IAAI,KAAW,GAAG;GAChB,EAAa,CAAO;GAEpB;EACF;EAEA,IAAI,CAAC,EAAM,IAAI,CAAO,GAAG;EAEzB,IAAM,IAAK,iBAAiB;GAE1B,AADA,EAAS,OAAO,CAAO,GACvB,EAAa,CAAO;EACtB,GAAG,CAAO;EAEV,EAAS,IAAI,GAAS,CAAE;CAC1B;CAEA,SAAS,EAAiB,GAAW;EAGnC,OAFI,KAAe,OAAO,KAAQ,WAAiB,EAAY,YAAY,CAAG,IAEvE;CACT;CAEA,SAAS,EAAI,GAAuB;EAClC,IAAM,IAAS,EAAM,IAAI,EAAK,CAAG,CAAC;EAElC,OAAO,IAAS,EAAiB,EAAO,KAAK,IAAI,KAAA;CACnD;CAEA,SAAS,EAAI,GAAQ,GAAU,GAA8B;EAC3D,IAAM,IAAU,EAAK,CAAG,GAClB,IAAS,IAAe,EAAY,UAAU,CAAK,IAAqB;EAI9E,AAFA,EAAe,CAAO,GACtB,EAAM,IAAI,GAAS;GAAE;GAAK,OAAO;EAAO,CAAC,GACzC,EAA0B;EAE1B,IAAM,IAAM,GAAM,SAAS;EAE3B,AAAI,MAAQ,KAAA,KACV,EAAiB,GAAS,CAAG;CAEjC;CAEA,SAAS,EAAS,GAAQ,GAA+B,GAAwC;EAC/F,IAAM,IAAU,EAAK,CAAG;EAExB,IAAI,EAAM,IAAI,CAAO,KAAK,CAAC,GAAM,cAAc,OAAO,EAAI,CAAG;EAE7D,IAAM,IAAU,EAAS,IAAI,CAAO;EAEpC,IAAI,KAAW,CAAC,GAAM,cAAc,OAAO;EAE3C,IAAM,IAAQ,EAAQ;EAEtB,IAAI,EAAU,CAAK,GAAG;GACpB,IAAM,IAAqB,GACrB,IAAsB,EACzB,MAAM,OAGD,EAAS,IAAI,CAAO,MAAM,KAAS,EAAS,OAAO,CAAO,GAE1D,MAAe,KAAsB,CAAC,EAAqB,IAAI,CAAO,KACxE,EAAI,GAAK,GAAU,CAAI,GAGzB,EAAqB,OAAO,CAAO,GAE5B,EACR,CAAC,CACD,OAAO,MAAiB;IAIvB,MAHI,EAAS,IAAI,CAAO,MAAM,KAAS,EAAS,OAAO,CAAO,GAE9D,EAAqB,OAAO,CAAO,GAC7B;GACR,CAAC;GAIH,OAFA,EAAS,IAAI,GAAS,CAAO,GAEtB;EACT;EAIA,OAFA,EAAI,GAAK,GAAO,CAAI,GAEb;CACT;CAEA,SAAS,EAAI,GAAiB;EAC5B,OAAO,EAAa,EAAK,CAAG,CAAC;CAC/B;CAEA,SAAS,IAAc;EACrB;EACA,KAAK,IAAM,KAAM,EAAS,OAAO,GAAG,aAAa,CAAE;EAEnD,IAAI,GACF,KAAK,IAAM,KAAU,EAAM,OAAO,GAChC,EAAQ,EAAO,KAAK,EAAO,KAAK;EAOpC,AAHA,EAAM,MAAM,GACZ,EAAS,MAAM,GACf,EAAS,MAAM,GACf,EAAqB,MAAM;CAC7B;CAEA,UAAU,IAAoC;EAC5C,KAAK,IAAM,KAAU,EAAM,OAAO,GAChC,MAAM,CAAC,EAAO,KAAK,EAAiB,EAAO,KAAK,CAAC;CAErD;CAEA,OAAO;EACL;EACA,QAAQ;EACR;EACA;EACU;EACV;EACA,IAAI,OAAO;GACT,OAAO,EAAM;EACf;CACF;AACF"}

package/dist/errors.cjs

@@ -0,0 +1,2 @@
+var e=class e extends Error{constructor(e,t){super(e,t),this.name=new.target.name,Object.setPrototypeOf(this,new.target.prototype)}static is(t){return t instanceof e}},t=class extends e{},n=class extends e{};exports.ArsenalError=e,exports.ArsenalSerializationError=n,exports.ArsenalValidationError=t;
+//# sourceMappingURL=errors.cjs.map

package/dist/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.cjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all arsenal errors. Use `instanceof ArsenalError` to catch any arsenal-originated error. */\nexport class ArsenalError extends Error {\n  constructor(message: string, opts?: ErrorOptions) {\n    super(message, opts);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  static is(err: unknown): err is ArsenalError {\n    return err instanceof ArsenalError;\n  }\n}\n\n/**\n * Thrown when a function argument or option is invalid — wrong type, out of range, or an\n * otherwise-unusable value (e.g. a negative `concurrency`, a non-finite `range` bound, an\n * oversized `similarity` input).\n */\nexport class ArsenalValidationError extends ArsenalError {}\n\n/**\n * Thrown when converting a value to or from its serialized form fails — e.g. `memo`'s default\n * cache key (`JSON.stringify`) encountering a circular reference, or `hash` encountering an\n * unsupported class instance with `{ onClassInstance: 'throw' }`.\n */\nexport class ArsenalSerializationError extends ArsenalError {}\n"],"mappings":"AACA,IAAa,EAAb,MAAa,UAAqB,KAAM,CACtC,YAAY,EAAiB,EAAqB,CAChD,MAAM,EAAS,CAAI,EACnB,KAAK,KAAO,IAAI,OAAO,KACvB,OAAO,eAAe,KAAM,IAAI,OAAO,SAAS,CAClD,CAEA,OAAO,GAAG,EAAmC,CAC3C,OAAO,aAAe,CACxB,CACF,EAOa,EAAb,cAA4C,CAAa,CAAC,EAO7C,EAAb,cAA+C,CAAa,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/** Base class for all arsenal errors. Use `instanceof ArsenalError` to catch any arsenal-originated error. */
+export declare class ArsenalError extends Error {
+    constructor(message: string, opts?: ErrorOptions);
+    static is(err: unknown): err is ArsenalError;
+}
+/**
+ * Thrown when a function argument or option is invalid — wrong type, out of range, or an
+ * otherwise-unusable value (e.g. a negative `concurrency`, a non-finite `range` bound, an
+ * oversized `similarity` input).
+ */
+export declare class ArsenalValidationError extends ArsenalError {
+}
+/**
+ * Thrown when converting a value to or from its serialized form fails — e.g. `memo`'s default
+ * cache key (`JSON.stringify`) encountering a circular reference, or `hash` encountering an
+ * unsupported class instance with `{ onClassInstance: 'throw' }`.
+ */
+export declare class ArsenalSerializationError extends ArsenalError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY;IAMhD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,YAAY;CAG7C;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,YAAY;CAAG;AAE3D;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;CAAG"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+//#region src/errors.ts
+var e = class e extends Error {
+	constructor(e, t) {
+		super(e, t), this.name = new.target.name, Object.setPrototypeOf(this, new.target.prototype);
+	}
+	static is(t) {
+		return t instanceof e;
+	}
+}, t = class extends e {}, n = class extends e {};
+//#endregion
+export { e as ArsenalError, n as ArsenalSerializationError, t as ArsenalValidationError };
+
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all arsenal errors. Use `instanceof ArsenalError` to catch any arsenal-originated error. */\nexport class ArsenalError extends Error {\n  constructor(message: string, opts?: ErrorOptions) {\n    super(message, opts);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  static is(err: unknown): err is ArsenalError {\n    return err instanceof ArsenalError;\n  }\n}\n\n/**\n * Thrown when a function argument or option is invalid — wrong type, out of range, or an\n * otherwise-unusable value (e.g. a negative `concurrency`, a non-finite `range` bound, an\n * oversized `similarity` input).\n */\nexport class ArsenalValidationError extends ArsenalError {}\n\n/**\n * Thrown when converting a value to or from its serialized form fails — e.g. `memo`'s default\n * cache key (`JSON.stringify`) encountering a circular reference, or `hash` encountering an\n * unsupported class instance with `{ onClassInstance: 'throw' }`.\n */\nexport class ArsenalSerializationError extends ArsenalError {}\n"],"mappings":";AACA,IAAa,IAAb,MAAa,UAAqB,MAAM;CACtC,YAAY,GAAiB,GAAqB;EAGhD,AAFA,MAAM,GAAS,CAAI,GACnB,KAAK,OAAO,IAAI,OAAO,MACvB,OAAO,eAAe,MAAM,IAAI,OAAO,SAAS;CAClD;CAEA,OAAO,GAAG,GAAmC;EAC3C,OAAO,aAAe;CACxB;AACF,GAOa,IAAb,cAA4C,EAAa,CAAC,GAO7C,IAAb,cAA+C,EAAa,CAAC"}

package/dist/function/assert.cjs

@@ -0,0 +1,2 @@
+function e(e,t,n){if(!e)throw new((n?.type)??Error)(t??`Assertion failed`)}exports.assert=e;
+//# sourceMappingURL=assert.cjs.map

package/dist/function/assert.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.cjs","names":[],"sources":["../../src/function/assert.ts"],"sourcesContent":["/**\n * Asserts that a condition is true. Throws with `message` if false.\n *\n * @example\n * ```ts\n * assert(Array.isArray(x));\n * assert(x > 0, 'x must be positive');\n * assert(n >= 1, 'must be at least 1', { type: RangeError });\n * ```\n *\n * @param condition - The boolean condition to assert.\n * @param [message] - Error message (default: `'Assertion failed'`).\n * @param [options.type] - Error class to throw (default: `Error`).\n * @throws {Error} If `condition` is false.\n */\nexport function assert(condition: boolean, message?: string, options?: { type?: ErrorConstructor }): asserts condition {\n  if (!condition) throw new (options?.type ?? Error)(message ?? 'Assertion failed');\n}\n"],"mappings":"AAeA,SAAgB,EAAO,EAAoB,EAAkB,EAA0D,CACrH,GAAI,CAAC,EAAW,MAAM,KAAK,GAAS,OAAQ,OAAO,GAAW,kBAAkB,CAClF"}

package/dist/function/assert.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Asserts that a condition is true. Throws with `message` if false.
+ *
+ * @example
+ * ```ts
+ * assert(Array.isArray(x));
+ * assert(x > 0, 'x must be positive');
+ * assert(n >= 1, 'must be at least 1', { type: RangeError });
+ * ```
+ *
+ * @param condition - The boolean condition to assert.
+ * @param [message] - Error message (default: `'Assertion failed'`).
+ * @param [options.type] - Error class to throw (default: `Error`).
+ * @throws {Error} If `condition` is false.
+ */
+export declare function assert(condition: boolean, message?: string, options?: {
+    type?: ErrorConstructor;
+}): asserts condition;
+//# sourceMappingURL=assert.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/function/assert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,gBAAgB,CAAA;CAAE,GAAG,OAAO,CAAC,SAAS,CAErH"}

package/dist/function/assert.js

@@ -0,0 +1,8 @@
+//#region src/function/assert.ts
+function e(e, t, n) {
+	if (!e) throw new ((n?.type) ?? Error)(t ?? "Assertion failed");
+}
+//#endregion
+export { e as assert };
+
+//# sourceMappingURL=assert.js.map

package/dist/function/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","names":[],"sources":["../../src/function/assert.ts"],"sourcesContent":["/**\n * Asserts that a condition is true. Throws with `message` if false.\n *\n * @example\n * ```ts\n * assert(Array.isArray(x));\n * assert(x > 0, 'x must be positive');\n * assert(n >= 1, 'must be at least 1', { type: RangeError });\n * ```\n *\n * @param condition - The boolean condition to assert.\n * @param [message] - Error message (default: `'Assertion failed'`).\n * @param [options.type] - Error class to throw (default: `Error`).\n * @throws {Error} If `condition` is false.\n */\nexport function assert(condition: boolean, message?: string, options?: { type?: ErrorConstructor }): asserts condition {\n  if (!condition) throw new (options?.type ?? Error)(message ?? 'Assertion failed');\n}\n"],"mappings":";AAeA,SAAgB,EAAO,GAAoB,GAAkB,GAA0D;CACrH,IAAI,CAAC,GAAW,MAAM,MAAK,GAAS,SAAQ,OAAO,KAAW,kBAAkB;AAClF"}

package/dist/function/constant.cjs

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

package/dist/function/constant.cjs.map

@@ -0,0 +1 @@
+{"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"}