@vielzeug/arsenal 1.0.1

package/dist/async/abortError.js

@@ -0,0 +1,8 @@
+//#region src/async/abortError.ts
+function e(e) {
+	return e?.reason ?? new DOMException("Aborted", "AbortError");
+}
+//#endregion
+export { e as abortError };
+
+//# sourceMappingURL=abortError.js.map

package/dist/async/abortError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abortError.js","names":[],"sources":["../../src/async/abortError.ts"],"sourcesContent":["/**\n * Returns the abort error for the given signal.\n *\n * If the signal has a `reason`, that is returned directly (preserving the\n * original error thrown by `AbortController.abort(reason)`).\n * Otherwise, returns a `DOMException` with `name === 'AbortError'`.\n *\n * @example\n * ```ts\n * const ac = new AbortController();\n * ac.abort();\n * throw abortError(ac.signal); // DOMException { name: 'AbortError' }\n *\n * const ac2 = new AbortController();\n * ac2.abort(new TypeError('custom'));\n * throw abortError(ac2.signal); // TypeError('custom')\n * ```\n *\n * @param signal - The aborted signal to extract the error from.\n * @returns The abort reason, or a new `DOMException('Aborted', 'AbortError')`.\n */\nexport function abortError(signal?: AbortSignal): unknown {\n  return signal?.reason ?? new DOMException('Aborted', 'AbortError');\n}\n"],"mappings":";AAqBA,SAAgB,EAAW,GAA+B;CACxD,OAAO,GAAQ,UAAU,IAAI,aAAa,WAAW,YAAY;AACnE"}

package/dist/async/attempt.cjs

@@ -0,0 +1,2 @@
+function e(e){return e.ok===!0}function t(e){return e.ok===!1}function n(e){try{let t=e();return typeof t?.then==`function`?t.then(e=>({ok:!0,value:e}),e=>({error:e,ok:!1})):{ok:!0,value:t}}catch(e){return{error:e,ok:!1}}}exports.attempt=n,exports.isFail=t,exports.isOk=e;
+//# sourceMappingURL=attempt.cjs.map

package/dist/async/attempt.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.cjs","names":[],"sources":["../../src/async/attempt.ts"],"sourcesContent":["export type AttemptResult<T> =\n  | { ok: true; value: T }\n  // eslint-disable-next-line perfectionist/sort-object-types\n  | { ok: false; error: unknown };\n\n/**\n * Narrows an `AttemptResult` to the success branch.\n * @example\n * ```ts\n * const result = await attempt(() => fetch('/api').then(r => r.json()));\n * if (isOk(result)) console.log(result.value);\n * ```\n */\n\nexport function isOk<T>(result: AttemptResult<T>): result is { ok: true; value: T } {\n  return result.ok === true;\n}\n\n/**\n * Narrows an `AttemptResult` to the failure branch.\n * @example\n * ```ts\n * const result = await attempt(() => fetch('/api').then(r => r.json()));\n * if (isFail(result)) console.error(result.error);\n * ```\n */\n// eslint-disable-next-line perfectionist/sort-object-types\nexport function isFail<T>(result: AttemptResult<T>): result is { ok: false; error: unknown } {\n  return result.ok === false;\n}\n\n/**\n * Executes a function — sync or async — and returns an `AttemptResult` (or\n * `Promise<AttemptResult>` for async factories). Never throws.\n *\n * TypeScript infers the return type from the factory:\n * - sync factory → `AttemptResult<T>`\n * - async factory → `Promise<AttemptResult<T>>`\n *\n * @example\n * ```ts\n * // Sync\n * const parsed = attempt(() => JSON.parse(rawJson));\n * if (parsed.ok) console.log(parsed.value);\n * else console.error(parsed.error);\n *\n * // Async\n * const result = await attempt(() => fetch('/api').then(r => r.json()));\n * if (result.ok) console.log(result.value);\n * else console.error(result.error);\n *\n * // Combined with retry()\n * const result = await attempt(() => retry(fn, { times: 3 }));\n * ```\n */\nexport function attempt<T>(fn: () => Promise<T>): Promise<AttemptResult<T>>;\nexport function attempt<T>(fn: () => T): AttemptResult<T>;\nexport function attempt<T>(fn: () => T | Promise<T>): AttemptResult<T> | Promise<AttemptResult<T>> {\n  try {\n    const result = fn();\n\n    if (typeof (result as PromiseLike<T>)?.then === 'function') {\n      return (result as Promise<T>).then(\n        (value) => ({ ok: true as const, value }),\n        (error) => ({ error, ok: false as const }),\n      );\n    }\n\n    return { ok: true, value: result as T };\n  } catch (error) {\n    return { error, ok: false };\n  }\n}\n"],"mappings":"AAcA,SAAgB,EAAQ,EAA4D,CAClF,OAAO,EAAO,KAAO,EACvB,CAWA,SAAgB,EAAU,EAAmE,CAC3F,OAAO,EAAO,KAAO,EACvB,CA4BA,SAAgB,EAAW,EAAwE,CACjG,GAAI,CACF,IAAM,EAAS,EAAG,EASlB,OAPI,OAAQ,GAA2B,MAAS,WACtC,EAAsB,KAC3B,IAAW,CAAE,GAAI,GAAe,OAAM,GACtC,IAAW,CAAE,QAAO,GAAI,EAAe,EAC1C,EAGK,CAAE,GAAI,GAAM,MAAO,CAAY,CACxC,OAAS,EAAO,CACd,MAAO,CAAE,QAAO,GAAI,EAAM,CAC5B,CACF"}

package/dist/async/attempt.d.ts

@@ -0,0 +1,58 @@
+export type AttemptResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * Narrows an `AttemptResult` to the success branch.
+ * @example
+ * ```ts
+ * const result = await attempt(() => fetch('/api').then(r => r.json()));
+ * if (isOk(result)) console.log(result.value);
+ * ```
+ */
+export declare function isOk<T>(result: AttemptResult<T>): result is {
+    ok: true;
+    value: T;
+};
+/**
+ * Narrows an `AttemptResult` to the failure branch.
+ * @example
+ * ```ts
+ * const result = await attempt(() => fetch('/api').then(r => r.json()));
+ * if (isFail(result)) console.error(result.error);
+ * ```
+ */
+export declare function isFail<T>(result: AttemptResult<T>): result is {
+    ok: false;
+    error: unknown;
+};
+/**
+ * Executes a function — sync or async — and returns an `AttemptResult` (or
+ * `Promise<AttemptResult>` for async factories). Never throws.
+ *
+ * TypeScript infers the return type from the factory:
+ * - sync factory → `AttemptResult<T>`
+ * - async factory → `Promise<AttemptResult<T>>`
+ *
+ * @example
+ * ```ts
+ * // Sync
+ * const parsed = attempt(() => JSON.parse(rawJson));
+ * if (parsed.ok) console.log(parsed.value);
+ * else console.error(parsed.error);
+ *
+ * // Async
+ * const result = await attempt(() => fetch('/api').then(r => r.json()));
+ * if (result.ok) console.log(result.value);
+ * else console.error(result.error);
+ *
+ * // Combined with retry()
+ * const result = await attempt(() => retry(fn, { times: 3 }));
+ * ```
+ */
+export declare function attempt<T>(fn: () => Promise<T>): Promise<AttemptResult<T>>;
+export declare function attempt<T>(fn: () => T): AttemptResult<T>;
+//# sourceMappingURL=attempt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.d.ts","sourceRoot":"","sources":["../../src/async/attempt.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,CAAC,CAAC,IACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAEtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAElC;;;;;;;GAOG;AAEH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAElF;AAED;;;;;;;GAOG;AAEH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAE3F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5E,wBAAgB,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC"}

package/dist/async/attempt.js

@@ -0,0 +1,31 @@
+//#region src/async/attempt.ts
+function e(e) {
+	return e.ok === !0;
+}
+function t(e) {
+	return e.ok === !1;
+}
+function n(e) {
+	try {
+		let t = e();
+		return typeof t?.then == "function" ? t.then((e) => ({
+			ok: !0,
+			value: e
+		}), (e) => ({
+			error: e,
+			ok: !1
+		})) : {
+			ok: !0,
+			value: t
+		};
+	} catch (e) {
+		return {
+			error: e,
+			ok: !1
+		};
+	}
+}
+//#endregion
+export { n as attempt, t as isFail, e as isOk };
+
+//# sourceMappingURL=attempt.js.map

package/dist/async/attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.js","names":[],"sources":["../../src/async/attempt.ts"],"sourcesContent":["export type AttemptResult<T> =\n  | { ok: true; value: T }\n  // eslint-disable-next-line perfectionist/sort-object-types\n  | { ok: false; error: unknown };\n\n/**\n * Narrows an `AttemptResult` to the success branch.\n * @example\n * ```ts\n * const result = await attempt(() => fetch('/api').then(r => r.json()));\n * if (isOk(result)) console.log(result.value);\n * ```\n */\n\nexport function isOk<T>(result: AttemptResult<T>): result is { ok: true; value: T } {\n  return result.ok === true;\n}\n\n/**\n * Narrows an `AttemptResult` to the failure branch.\n * @example\n * ```ts\n * const result = await attempt(() => fetch('/api').then(r => r.json()));\n * if (isFail(result)) console.error(result.error);\n * ```\n */\n// eslint-disable-next-line perfectionist/sort-object-types\nexport function isFail<T>(result: AttemptResult<T>): result is { ok: false; error: unknown } {\n  return result.ok === false;\n}\n\n/**\n * Executes a function — sync or async — and returns an `AttemptResult` (or\n * `Promise<AttemptResult>` for async factories). Never throws.\n *\n * TypeScript infers the return type from the factory:\n * - sync factory → `AttemptResult<T>`\n * - async factory → `Promise<AttemptResult<T>>`\n *\n * @example\n * ```ts\n * // Sync\n * const parsed = attempt(() => JSON.parse(rawJson));\n * if (parsed.ok) console.log(parsed.value);\n * else console.error(parsed.error);\n *\n * // Async\n * const result = await attempt(() => fetch('/api').then(r => r.json()));\n * if (result.ok) console.log(result.value);\n * else console.error(result.error);\n *\n * // Combined with retry()\n * const result = await attempt(() => retry(fn, { times: 3 }));\n * ```\n */\nexport function attempt<T>(fn: () => Promise<T>): Promise<AttemptResult<T>>;\nexport function attempt<T>(fn: () => T): AttemptResult<T>;\nexport function attempt<T>(fn: () => T | Promise<T>): AttemptResult<T> | Promise<AttemptResult<T>> {\n  try {\n    const result = fn();\n\n    if (typeof (result as PromiseLike<T>)?.then === 'function') {\n      return (result as Promise<T>).then(\n        (value) => ({ ok: true as const, value }),\n        (error) => ({ error, ok: false as const }),\n      );\n    }\n\n    return { ok: true, value: result as T };\n  } catch (error) {\n    return { error, ok: false };\n  }\n}\n"],"mappings":";AAcA,SAAgB,EAAQ,GAA4D;CAClF,OAAO,EAAO,OAAO;AACvB;AAWA,SAAgB,EAAU,GAAmE;CAC3F,OAAO,EAAO,OAAO;AACvB;AA4BA,SAAgB,EAAW,GAAwE;CACjG,IAAI;EACF,IAAM,IAAS,EAAG;EASlB,OAPI,OAAQ,GAA2B,QAAS,aACtC,EAAsB,MAC3B,OAAW;GAAE,IAAI;GAAe;EAAM,KACtC,OAAW;GAAE;GAAO,IAAI;EAAe,EAC1C,IAGK;GAAE,IAAI;GAAM,OAAO;EAAY;CACxC,SAAS,GAAO;EACd,OAAO;GAAE;GAAO,IAAI;EAAM;CAC5B;AACF"}

package/dist/async/backoff.cjs

@@ -0,0 +1,2 @@
+function e(e,t=3e4){let n=Math.max(0,Number.isNaN(e)?0:Math.floor(e));return Math.min(1e3*(n<=30?1<<n:2**n),t)}exports.backoff=e;
+//# sourceMappingURL=backoff.cjs.map

package/dist/async/backoff.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.cjs","names":[],"sources":["../../src/async/backoff.ts"],"sourcesContent":["/**\n * Computes an exponential backoff delay cap for a given zero-based attempt number.\n * Returns `min(1000 × 2ⁿ, maxMs)` — the cap before optional jitter is applied.\n *\n * Multiply the result by `Math.random()` for full-jitter backoff.\n *\n * @example\n * ```ts\n * // Deterministic (sourcerer-style):\n * const delay = backoff(attempt); // 1s, 2s, 4s, … capped at 30s\n *\n * // Full-jitter (courier-style):\n * const delay = Math.random() * backoff(attempt);\n * ```\n *\n * @param attempt - Zero-based attempt index (0 = first retry wait).\n * @param maxMs   - Maximum cap in milliseconds. Defaults to 30 000.\n */\nexport function backoff(attempt: number, maxMs = 30_000): number {\n  const n = Math.max(0, Number.isNaN(attempt) ? 0 : Math.floor(attempt));\n\n  return Math.min(1000 * (n <= 30 ? 1 << n : Math.pow(2, n)), maxMs);\n}\n"],"mappings":"AAkBA,SAAgB,EAAQ,EAAiB,EAAQ,IAAgB,CAC/D,IAAM,EAAI,KAAK,IAAI,EAAG,OAAO,MAAM,CAAO,EAAI,EAAI,KAAK,MAAM,CAAO,CAAC,EAErE,OAAO,KAAK,IAAI,KAAQ,GAAK,GAAK,GAAK,EAAa,GAAG,GAAK,CAAK,CACnE"}

package/dist/async/backoff.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Computes an exponential backoff delay cap for a given zero-based attempt number.
+ * Returns `min(1000 × 2ⁿ, maxMs)` — the cap before optional jitter is applied.
+ *
+ * Multiply the result by `Math.random()` for full-jitter backoff.
+ *
+ * @example
+ * ```ts
+ * // Deterministic (sourcerer-style):
+ * const delay = backoff(attempt); // 1s, 2s, 4s, … capped at 30s
+ *
+ * // Full-jitter (courier-style):
+ * const delay = Math.random() * backoff(attempt);
+ * ```
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry wait).
+ * @param maxMs   - Maximum cap in milliseconds. Defaults to 30 000.
+ */
+export declare function backoff(attempt: number, maxMs?: number): number;
+//# sourceMappingURL=backoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/async/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,MAAM,CAI/D"}

package/dist/async/backoff.js

@@ -0,0 +1,9 @@
+//#region src/async/backoff.ts
+function e(e, t = 3e4) {
+	let n = Math.max(0, Number.isNaN(e) ? 0 : Math.floor(e));
+	return Math.min(1e3 * (n <= 30 ? 1 << n : 2 ** n), t);
+}
+//#endregion
+export { e as backoff };
+
+//# sourceMappingURL=backoff.js.map

package/dist/async/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","names":[],"sources":["../../src/async/backoff.ts"],"sourcesContent":["/**\n * Computes an exponential backoff delay cap for a given zero-based attempt number.\n * Returns `min(1000 × 2ⁿ, maxMs)` — the cap before optional jitter is applied.\n *\n * Multiply the result by `Math.random()` for full-jitter backoff.\n *\n * @example\n * ```ts\n * // Deterministic (sourcerer-style):\n * const delay = backoff(attempt); // 1s, 2s, 4s, … capped at 30s\n *\n * // Full-jitter (courier-style):\n * const delay = Math.random() * backoff(attempt);\n * ```\n *\n * @param attempt - Zero-based attempt index (0 = first retry wait).\n * @param maxMs   - Maximum cap in milliseconds. Defaults to 30 000.\n */\nexport function backoff(attempt: number, maxMs = 30_000): number {\n  const n = Math.max(0, Number.isNaN(attempt) ? 0 : Math.floor(attempt));\n\n  return Math.min(1000 * (n <= 30 ? 1 << n : Math.pow(2, n)), maxMs);\n}\n"],"mappings":";AAkBA,SAAgB,EAAQ,GAAiB,IAAQ,KAAgB;CAC/D,IAAM,IAAI,KAAK,IAAI,GAAG,OAAO,MAAM,CAAO,IAAI,IAAI,KAAK,MAAM,CAAO,CAAC;CAErE,OAAO,KAAK,IAAI,OAAQ,KAAK,KAAK,KAAK,IAAa,KAAG,IAAK,CAAK;AACnE"}

package/dist/async/index.d.ts

@@ -0,0 +1,9 @@
+export * from './abortError';
+export * from './attempt';
+export * from './backoff';
+export * from './parallel';
+export * from './queue';
+export * from './retry';
+export * from './sleep';
+export * from './waitFor';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/async/parallel.cjs

@@ -0,0 +1,2 @@
+const e=require("../errors.cjs"),t=require("./abortError.cjs");async function n(n,r,i={}){let{abortOnError:a=!1,limit:o=1/0,signal:s}=i;if(o<1)throw new e.ArsenalValidationError(`parallel: limit must be at least 1, got ${o}`);if(s?.aborted)throw t.abortError(s);if(n.length===0)return[];let c=Array(n.length),l=0,u=a?new AbortController:void 0,d=async()=>{for(;;){if(s?.aborted)throw t.abortError(s);if(u?.signal.aborted||l>=n.length)return;let e=l++;try{c[e]=await r(n[e],e,n)}catch(e){throw u?.abort(),e}}},f=Math.min(o,n.length),p=Array.from({length:f},()=>d());return await Promise.all(p),c}exports.parallel=n;
+//# sourceMappingURL=parallel.cjs.map

package/dist/async/parallel.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.cjs","names":[],"sources":["../../src/async/parallel.ts"],"sourcesContent":["import { ArsenalValidationError } from '../errors';\nimport { abortError } from './abortError';\n\n/**\n * Processes an array with an async callback with controlled parallelism.\n * Similar to Promise.all, but limits how many items are processed concurrently.\n * Returns an ordered array of results.\n *\n * @example\n * ```ts\n * // Process 3 items at a time\n * const results = await parallel([1, 2, 3, 4, 5], async (n) => {\n *   await delay(100);\n *   return n * 2;\n * }, { limit: 3 });\n * // [2, 4, 6, 8, 10]\n *\n * // With abort signal\n * const controller = new AbortController();\n * const results = await parallel(items, async (item) => {\n *   return processItem(item);\n * }, { limit: 2, signal: controller.signal });\n *\n * // Stop other workers as soon as one item fails\n * await parallel(items, riskyOperation, { abortOnError: true, limit: 3 });\n * ```\n *\n * @param array - Array of items to process\n * @param callback - Async function to process each item\n * @param options - Optional options for concurrency and cancellation\n * @param [options.limit=Infinity] - Maximum number of concurrent operations. Defaults to unbounded.\n * @param [options.signal] - Optional AbortSignal to cancel processing\n * @param [options.abortOnError=false] - When `true`, stops other in-flight workers as soon as any\n *   callback throws, instead of letting them keep running to completion unobserved. Default\n *   preserves the existing best-effort-completion behavior.\n * @returns Promise resolving to an ordered array of results\n * @throws {ArsenalValidationError} If limit is less than 1\n * @throws {DOMException} If aborted via signal\n */\nexport async function parallel<T, R>(\n  array: readonly T[],\n  callback: (item: T, index: number, array: readonly T[]) => Promise<R> | R,\n  options: { abortOnError?: boolean; limit?: number; signal?: AbortSignal } = {},\n): Promise<R[]> {\n  const { abortOnError = false, limit = Infinity, signal } = options;\n\n  if (limit < 1) {\n    throw new ArsenalValidationError(`parallel: limit must be at least 1, got ${limit}`);\n  }\n\n  if (signal?.aborted) {\n    throw abortError(signal);\n  }\n\n  if (array.length === 0) {\n    return [];\n  }\n\n  const results: R[] = new Array(array.length);\n  let currentIndex = 0;\n  const failFastController = abortOnError ? new AbortController() : undefined;\n\n  const worker = async (): Promise<void> => {\n    while (true) {\n      if (signal?.aborted) {\n        throw abortError(signal);\n      }\n\n      if (failFastController?.signal.aborted) {\n        return;\n      }\n\n      if (currentIndex >= array.length) {\n        return;\n      }\n\n      const index = currentIndex++;\n\n      try {\n        results[index] = await callback(array[index]!, index, array);\n      } catch (err) {\n        failFastController?.abort();\n        throw err;\n      }\n    }\n  };\n\n  const workerCount = Math.min(limit, array.length);\n  const workers = Array.from({ length: workerCount }, () => worker());\n\n  await Promise.all(workers);\n\n  return results;\n}\n"],"mappings":"+DAuCA,eAAsB,EACpB,EACA,EACA,EAA4E,CAAC,EAC/D,CACd,GAAM,CAAE,eAAe,GAAO,QAAQ,IAAU,UAAW,EAE3D,GAAI,EAAQ,EACV,MAAM,IAAI,EAAA,uBAAuB,2CAA2C,GAAO,EAGrF,GAAI,GAAQ,QACV,MAAM,EAAA,WAAW,CAAM,EAGzB,GAAI,EAAM,SAAW,EACnB,MAAO,CAAC,EAGV,IAAM,EAAmB,MAAM,EAAM,MAAM,EACvC,EAAe,EACb,EAAqB,EAAe,IAAI,gBAAoB,IAAA,GAE5D,EAAS,SAA2B,CACxC,OAAa,CACX,GAAI,GAAQ,QACV,MAAM,EAAA,WAAW,CAAM,EAOzB,GAJI,GAAoB,OAAO,SAI3B,GAAgB,EAAM,OACxB,OAGF,IAAM,EAAQ,IAEd,GAAI,CACF,EAAQ,GAAS,MAAM,EAAS,EAAM,GAAS,EAAO,CAAK,CAC7D,OAAS,EAAK,CAEZ,MADA,GAAoB,MAAM,EACpB,CACR,CACF,CACF,EAEM,EAAc,KAAK,IAAI,EAAO,EAAM,MAAM,EAC1C,EAAU,MAAM,KAAK,CAAE,OAAQ,CAAY,MAAS,EAAO,CAAC,EAIlE,OAFA,MAAM,QAAQ,IAAI,CAAO,EAElB,CACT"}

package/dist/async/parallel.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Processes an array with an async callback with controlled parallelism.
+ * Similar to Promise.all, but limits how many items are processed concurrently.
+ * Returns an ordered array of results.
+ *
+ * @example
+ * ```ts
+ * // Process 3 items at a time
+ * const results = await parallel([1, 2, 3, 4, 5], async (n) => {
+ *   await delay(100);
+ *   return n * 2;
+ * }, { limit: 3 });
+ * // [2, 4, 6, 8, 10]
+ *
+ * // With abort signal
+ * const controller = new AbortController();
+ * const results = await parallel(items, async (item) => {
+ *   return processItem(item);
+ * }, { limit: 2, signal: controller.signal });
+ *
+ * // Stop other workers as soon as one item fails
+ * await parallel(items, riskyOperation, { abortOnError: true, limit: 3 });
+ * ```
+ *
+ * @param array - Array of items to process
+ * @param callback - Async function to process each item
+ * @param options - Optional options for concurrency and cancellation
+ * @param [options.limit=Infinity] - Maximum number of concurrent operations. Defaults to unbounded.
+ * @param [options.signal] - Optional AbortSignal to cancel processing
+ * @param [options.abortOnError=false] - When `true`, stops other in-flight workers as soon as any
+ *   callback throws, instead of letting them keep running to completion unobserved. Default
+ *   preserves the existing best-effort-completion behavior.
+ * @returns Promise resolving to an ordered array of results
+ * @throws {ArsenalValidationError} If limit is less than 1
+ * @throws {DOMException} If aborted via signal
+ */
+export declare function parallel<T, R>(array: readonly T[], callback: (item: T, index: number, array: readonly T[]) => Promise<R> | R, options?: {
+    abortOnError?: boolean;
+    limit?: number;
+    signal?: AbortSignal;
+}): Promise<R[]>;
+//# sourceMappingURL=parallel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/async/parallel.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACzE,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC7E,OAAO,CAAC,CAAC,EAAE,CAAC,CAkDd"}

package/dist/async/parallel.js

@@ -0,0 +1,26 @@
+import { ArsenalValidationError as e } from "../errors.js";
+import { abortError as t } from "./abortError.js";
+//#region src/async/parallel.ts
+async function n(n, r, i = {}) {
+	let { abortOnError: a = !1, limit: o = Infinity, signal: s } = i;
+	if (o < 1) throw new e(`parallel: limit must be at least 1, got ${o}`);
+	if (s?.aborted) throw t(s);
+	if (n.length === 0) return [];
+	let c = Array(n.length), l = 0, u = a ? new AbortController() : void 0, d = async () => {
+		for (;;) {
+			if (s?.aborted) throw t(s);
+			if (u?.signal.aborted || l >= n.length) return;
+			let e = l++;
+			try {
+				c[e] = await r(n[e], e, n);
+			} catch (e) {
+				throw u?.abort(), e;
+			}
+		}
+	}, f = Math.min(o, n.length), p = Array.from({ length: f }, () => d());
+	return await Promise.all(p), c;
+}
+//#endregion
+export { n as parallel };
+
+//# sourceMappingURL=parallel.js.map

package/dist/async/parallel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.js","names":[],"sources":["../../src/async/parallel.ts"],"sourcesContent":["import { ArsenalValidationError } from '../errors';\nimport { abortError } from './abortError';\n\n/**\n * Processes an array with an async callback with controlled parallelism.\n * Similar to Promise.all, but limits how many items are processed concurrently.\n * Returns an ordered array of results.\n *\n * @example\n * ```ts\n * // Process 3 items at a time\n * const results = await parallel([1, 2, 3, 4, 5], async (n) => {\n *   await delay(100);\n *   return n * 2;\n * }, { limit: 3 });\n * // [2, 4, 6, 8, 10]\n *\n * // With abort signal\n * const controller = new AbortController();\n * const results = await parallel(items, async (item) => {\n *   return processItem(item);\n * }, { limit: 2, signal: controller.signal });\n *\n * // Stop other workers as soon as one item fails\n * await parallel(items, riskyOperation, { abortOnError: true, limit: 3 });\n * ```\n *\n * @param array - Array of items to process\n * @param callback - Async function to process each item\n * @param options - Optional options for concurrency and cancellation\n * @param [options.limit=Infinity] - Maximum number of concurrent operations. Defaults to unbounded.\n * @param [options.signal] - Optional AbortSignal to cancel processing\n * @param [options.abortOnError=false] - When `true`, stops other in-flight workers as soon as any\n *   callback throws, instead of letting them keep running to completion unobserved. Default\n *   preserves the existing best-effort-completion behavior.\n * @returns Promise resolving to an ordered array of results\n * @throws {ArsenalValidationError} If limit is less than 1\n * @throws {DOMException} If aborted via signal\n */\nexport async function parallel<T, R>(\n  array: readonly T[],\n  callback: (item: T, index: number, array: readonly T[]) => Promise<R> | R,\n  options: { abortOnError?: boolean; limit?: number; signal?: AbortSignal } = {},\n): Promise<R[]> {\n  const { abortOnError = false, limit = Infinity, signal } = options;\n\n  if (limit < 1) {\n    throw new ArsenalValidationError(`parallel: limit must be at least 1, got ${limit}`);\n  }\n\n  if (signal?.aborted) {\n    throw abortError(signal);\n  }\n\n  if (array.length === 0) {\n    return [];\n  }\n\n  const results: R[] = new Array(array.length);\n  let currentIndex = 0;\n  const failFastController = abortOnError ? new AbortController() : undefined;\n\n  const worker = async (): Promise<void> => {\n    while (true) {\n      if (signal?.aborted) {\n        throw abortError(signal);\n      }\n\n      if (failFastController?.signal.aborted) {\n        return;\n      }\n\n      if (currentIndex >= array.length) {\n        return;\n      }\n\n      const index = currentIndex++;\n\n      try {\n        results[index] = await callback(array[index]!, index, array);\n      } catch (err) {\n        failFastController?.abort();\n        throw err;\n      }\n    }\n  };\n\n  const workerCount = Math.min(limit, array.length);\n  const workers = Array.from({ length: workerCount }, () => worker());\n\n  await Promise.all(workers);\n\n  return results;\n}\n"],"mappings":";;;AAuCA,eAAsB,EACpB,GACA,GACA,IAA4E,CAAC,GAC/D;CACd,IAAM,EAAE,kBAAe,IAAO,WAAQ,UAAU,cAAW;CAE3D,IAAI,IAAQ,GACV,MAAM,IAAI,EAAuB,2CAA2C,GAAO;CAGrF,IAAI,GAAQ,SACV,MAAM,EAAW,CAAM;CAGzB,IAAI,EAAM,WAAW,GACnB,OAAO,CAAC;CAGV,IAAM,IAAmB,MAAM,EAAM,MAAM,GACvC,IAAe,GACb,IAAqB,IAAe,IAAI,gBAAgB,IAAI,KAAA,GAE5D,IAAS,YAA2B;EACxC,SAAa;GACX,IAAI,GAAQ,SACV,MAAM,EAAW,CAAM;GAOzB,IAJI,GAAoB,OAAO,WAI3B,KAAgB,EAAM,QACxB;GAGF,IAAM,IAAQ;GAEd,IAAI;IACF,EAAQ,KAAS,MAAM,EAAS,EAAM,IAAS,GAAO,CAAK;GAC7D,SAAS,GAAK;IAEZ,MADA,GAAoB,MAAM,GACpB;GACR;EACF;CACF,GAEM,IAAc,KAAK,IAAI,GAAO,EAAM,MAAM,GAC1C,IAAU,MAAM,KAAK,EAAE,QAAQ,EAAY,SAAS,EAAO,CAAC;CAIlE,OAFA,MAAM,QAAQ,IAAI,CAAO,GAElB;AACT"}

package/dist/async/queue.cjs

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

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

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

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

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

@@ -0,0 +1 @@
+{"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/async/retry.cjs

@@ -0,0 +1,2 @@
+const e=require("../errors.cjs"),t=require("./abortError.cjs"),n=require("./sleep.cjs");function r(e,t){let n=[e===void 0?void 0:AbortSignal.timeout(e),t].filter(e=>e!=null);if(n.length!==0)return n.length===1?n[0]:AbortSignal.any(n)}async function i(i,{delay:a=250,onError:o,shouldRetry:s,signal:c,timeout:l,times:u=3}={}){if(!Number.isInteger(u)||u<1)throw new e.ArsenalValidationError(`retry: times must be a positive integer, got ${u}`);for(let e=1;e<=u;e++){if(c?.aborted)throw t.abortError(c);let d=r(l,c);try{return await i(d)}catch(t){if(e===u||s&&!s(t,e-1))throw o?.(t),t;let r=typeof a==`function`?a(e-1):a;r>0&&await n.sleep(r,c)}}}exports.retry=i;
+//# sourceMappingURL=retry.cjs.map

package/dist/async/retry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.cjs","names":[],"sources":["../../src/async/retry.ts"],"sourcesContent":["import { ArsenalValidationError } from '../errors';\nimport { abortError } from './abortError';\nimport { sleep } from './sleep';\n\nexport type RetryOptions = {\n  delay?: number | ((attempt: number) => number);\n  onError?: (error: unknown) => void;\n  shouldRetry?: (error: unknown, attempt: number) => boolean;\n  signal?: AbortSignal;\n  timeout?: number;\n  times?: number;\n};\n\nfunction buildSignal(timeout: number | undefined, signal: AbortSignal | undefined): AbortSignal | undefined {\n  const parts = [timeout !== undefined ? AbortSignal.timeout(timeout) : undefined, signal].filter(\n    (s): s is AbortSignal => s != null,\n  );\n\n  if (parts.length === 0) return undefined;\n\n  if (parts.length === 1) return parts[0];\n\n  return AbortSignal.any(parts);\n}\n\n/**\n * Retries an async function with optional per-attempt timeout, delay strategy, and abort support.\n * The function receives a merged AbortSignal from the per-attempt timeout and any external signal.\n * On total failure, throws the last error (use `attempt()` to get an `AttemptResult` without throwing).\n *\n * @example\n * ```ts\n * // Basic retry\n * const data = await retry(() => fetch('/api').then(r => r.json()), { times: 3 });\n *\n * // With per-attempt timeout and cancellation\n * const data = await retry(\n *   async (signal) => fetch('/api', { signal }).then(r => r.json()),\n *   { times: 3, timeout: 5000 },\n * );\n *\n * // As AttemptResult (never throws) — combine with attempt()\n * const result = await attempt(() => retry(fn, { times: 3 }));\n * ```\n *\n * @param fn - Async function to retry. Receives a merged AbortSignal when timeout or signal is set.\n * @param options - Retry configuration.\n * @param [options.times=3] - Total attempts including the first.\n * @param [options.delay=250] - Delay between retries in ms, or a function of (attemptIndex).\n * @param [options.timeout] - Per-attempt timeout in milliseconds.\n * @param [options.signal] - External AbortSignal to cancel all retries.\n * @param [options.shouldRetry] - Predicate called after each non-final failure.\n *   Receives the error and the number of failures so far (0-indexed: `0` on the first failure,\n *   `1` on the second, etc.). Return `false` to abort immediately. **Not called on the final attempt**\n *   (use `onError` to observe the final error unconditionally).\n * @param [options.onError] - Called with the last error before rethrowing — both on final attempt exhaustion\n *   and when `shouldRetry` returns `false` to abort early.\n * @returns The resolved value.\n * @throws {ArsenalValidationError} If `times` is not a positive integer.\n * @throws The last error if all attempts fail.\n */\nexport async function retry<T>(\n  fn: (signal?: AbortSignal) => Promise<T>,\n  { delay = 250, onError, shouldRetry, signal, timeout, times = 3 }: RetryOptions = {},\n): Promise<T> {\n  if (!Number.isInteger(times) || times < 1) {\n    throw new ArsenalValidationError(`retry: times must be a positive integer, got ${times}`);\n  }\n\n  for (let tryCount = 1; tryCount <= times; tryCount++) {\n    if (signal?.aborted) throw abortError(signal);\n\n    const callSignal = buildSignal(timeout, signal);\n\n    try {\n      return await fn(callSignal);\n    } catch (err) {\n      if (tryCount === times) {\n        onError?.(err);\n        throw err;\n      }\n\n      if (shouldRetry && !shouldRetry(err, tryCount - 1)) {\n        onError?.(err);\n        throw err;\n      }\n\n      const ms = typeof delay === 'function' ? delay(tryCount - 1) : delay;\n\n      if (ms > 0) await sleep(ms, signal);\n    }\n  }\n\n  /* unreachable — the loop always returns or throws before exhausting all attempts */\n  return undefined as never;\n}\n"],"mappings":"wFAaA,SAAS,EAAY,EAA6B,EAA0D,CAC1G,IAAM,EAAQ,CAAC,IAAY,IAAA,GAA2C,IAAA,GAA/B,YAAY,QAAQ,CAAO,EAAe,CAAM,CAAC,CAAC,OACtF,GAAwB,GAAK,IAChC,EAEI,KAAM,SAAW,EAIrB,OAFI,EAAM,SAAW,EAAU,EAAM,GAE9B,YAAY,IAAI,CAAK,CAC9B,CAsCA,eAAsB,EACpB,EACA,CAAE,QAAQ,IAAK,UAAS,cAAa,SAAQ,UAAS,QAAQ,GAAoB,CAAC,EACvE,CACZ,GAAI,CAAC,OAAO,UAAU,CAAK,GAAK,EAAQ,EACtC,MAAM,IAAI,EAAA,uBAAuB,gDAAgD,GAAO,EAG1F,IAAK,IAAI,EAAW,EAAG,GAAY,EAAO,IAAY,CACpD,GAAI,GAAQ,QAAS,MAAM,EAAA,WAAW,CAAM,EAE5C,IAAM,EAAa,EAAY,EAAS,CAAM,EAE9C,GAAI,CACF,OAAO,MAAM,EAAG,CAAU,CAC5B,OAAS,EAAK,CAMZ,GALI,IAAa,GAKb,GAAe,CAAC,EAAY,EAAK,EAAW,CAAC,EAE/C,MADA,IAAU,CAAG,EACP,EAGR,IAAM,EAAK,OAAO,GAAU,WAAa,EAAM,EAAW,CAAC,EAAI,EAE3D,EAAK,GAAG,MAAM,EAAA,MAAM,EAAI,CAAM,CACpC,CACF,CAIF"}

package/dist/async/retry.d.ts

@@ -0,0 +1,46 @@
+export type RetryOptions = {
+    delay?: number | ((attempt: number) => number);
+    onError?: (error: unknown) => void;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    signal?: AbortSignal;
+    timeout?: number;
+    times?: number;
+};
+/**
+ * Retries an async function with optional per-attempt timeout, delay strategy, and abort support.
+ * The function receives a merged AbortSignal from the per-attempt timeout and any external signal.
+ * On total failure, throws the last error (use `attempt()` to get an `AttemptResult` without throwing).
+ *
+ * @example
+ * ```ts
+ * // Basic retry
+ * const data = await retry(() => fetch('/api').then(r => r.json()), { times: 3 });
+ *
+ * // With per-attempt timeout and cancellation
+ * const data = await retry(
+ *   async (signal) => fetch('/api', { signal }).then(r => r.json()),
+ *   { times: 3, timeout: 5000 },
+ * );
+ *
+ * // As AttemptResult (never throws) — combine with attempt()
+ * const result = await attempt(() => retry(fn, { times: 3 }));
+ * ```
+ *
+ * @param fn - Async function to retry. Receives a merged AbortSignal when timeout or signal is set.
+ * @param options - Retry configuration.
+ * @param [options.times=3] - Total attempts including the first.
+ * @param [options.delay=250] - Delay between retries in ms, or a function of (attemptIndex).
+ * @param [options.timeout] - Per-attempt timeout in milliseconds.
+ * @param [options.signal] - External AbortSignal to cancel all retries.
+ * @param [options.shouldRetry] - Predicate called after each non-final failure.
+ *   Receives the error and the number of failures so far (0-indexed: `0` on the first failure,
+ *   `1` on the second, etc.). Return `false` to abort immediately. **Not called on the final attempt**
+ *   (use `onError` to observe the final error unconditionally).
+ * @param [options.onError] - Called with the last error before rethrowing — both on final attempt exhaustion
+ *   and when `shouldRetry` returns `false` to abort early.
+ * @returns The resolved value.
+ * @throws {ArsenalValidationError} If `times` is not a positive integer.
+ * @throws The last error if all attempts fail.
+ */
+export declare function retry<T>(fn: (signal?: AbortSignal) => Promise<T>, { delay, onError, shouldRetry, signal, timeout, times }?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/async/retry.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAcF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACxC,EAAE,KAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,KAAS,EAAE,GAAE,YAAiB,GACnF,OAAO,CAAC,CAAC,CAAC,CA+BZ"}

package/dist/async/retry.js

@@ -0,0 +1,26 @@
+import { ArsenalValidationError as e } from "../errors.js";
+import { abortError as t } from "./abortError.js";
+import { sleep as n } from "./sleep.js";
+//#region src/async/retry.ts
+function r(e, t) {
+	let n = [e === void 0 ? void 0 : AbortSignal.timeout(e), t].filter((e) => e != null);
+	if (n.length !== 0) return n.length === 1 ? n[0] : AbortSignal.any(n);
+}
+async function i(i, { delay: a = 250, onError: o, shouldRetry: s, signal: c, timeout: l, times: u = 3 } = {}) {
+	if (!Number.isInteger(u) || u < 1) throw new e(`retry: times must be a positive integer, got ${u}`);
+	for (let e = 1; e <= u; e++) {
+		if (c?.aborted) throw t(c);
+		let d = r(l, c);
+		try {
+			return await i(d);
+		} catch (t) {
+			if (e === u || s && !s(t, e - 1)) throw o?.(t), t;
+			let r = typeof a == "function" ? a(e - 1) : a;
+			r > 0 && await n(r, c);
+		}
+	}
+}
+//#endregion
+export { i as retry };
+
+//# sourceMappingURL=retry.js.map

package/dist/async/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","names":[],"sources":["../../src/async/retry.ts"],"sourcesContent":["import { ArsenalValidationError } from '../errors';\nimport { abortError } from './abortError';\nimport { sleep } from './sleep';\n\nexport type RetryOptions = {\n  delay?: number | ((attempt: number) => number);\n  onError?: (error: unknown) => void;\n  shouldRetry?: (error: unknown, attempt: number) => boolean;\n  signal?: AbortSignal;\n  timeout?: number;\n  times?: number;\n};\n\nfunction buildSignal(timeout: number | undefined, signal: AbortSignal | undefined): AbortSignal | undefined {\n  const parts = [timeout !== undefined ? AbortSignal.timeout(timeout) : undefined, signal].filter(\n    (s): s is AbortSignal => s != null,\n  );\n\n  if (parts.length === 0) return undefined;\n\n  if (parts.length === 1) return parts[0];\n\n  return AbortSignal.any(parts);\n}\n\n/**\n * Retries an async function with optional per-attempt timeout, delay strategy, and abort support.\n * The function receives a merged AbortSignal from the per-attempt timeout and any external signal.\n * On total failure, throws the last error (use `attempt()` to get an `AttemptResult` without throwing).\n *\n * @example\n * ```ts\n * // Basic retry\n * const data = await retry(() => fetch('/api').then(r => r.json()), { times: 3 });\n *\n * // With per-attempt timeout and cancellation\n * const data = await retry(\n *   async (signal) => fetch('/api', { signal }).then(r => r.json()),\n *   { times: 3, timeout: 5000 },\n * );\n *\n * // As AttemptResult (never throws) — combine with attempt()\n * const result = await attempt(() => retry(fn, { times: 3 }));\n * ```\n *\n * @param fn - Async function to retry. Receives a merged AbortSignal when timeout or signal is set.\n * @param options - Retry configuration.\n * @param [options.times=3] - Total attempts including the first.\n * @param [options.delay=250] - Delay between retries in ms, or a function of (attemptIndex).\n * @param [options.timeout] - Per-attempt timeout in milliseconds.\n * @param [options.signal] - External AbortSignal to cancel all retries.\n * @param [options.shouldRetry] - Predicate called after each non-final failure.\n *   Receives the error and the number of failures so far (0-indexed: `0` on the first failure,\n *   `1` on the second, etc.). Return `false` to abort immediately. **Not called on the final attempt**\n *   (use `onError` to observe the final error unconditionally).\n * @param [options.onError] - Called with the last error before rethrowing — both on final attempt exhaustion\n *   and when `shouldRetry` returns `false` to abort early.\n * @returns The resolved value.\n * @throws {ArsenalValidationError} If `times` is not a positive integer.\n * @throws The last error if all attempts fail.\n */\nexport async function retry<T>(\n  fn: (signal?: AbortSignal) => Promise<T>,\n  { delay = 250, onError, shouldRetry, signal, timeout, times = 3 }: RetryOptions = {},\n): Promise<T> {\n  if (!Number.isInteger(times) || times < 1) {\n    throw new ArsenalValidationError(`retry: times must be a positive integer, got ${times}`);\n  }\n\n  for (let tryCount = 1; tryCount <= times; tryCount++) {\n    if (signal?.aborted) throw abortError(signal);\n\n    const callSignal = buildSignal(timeout, signal);\n\n    try {\n      return await fn(callSignal);\n    } catch (err) {\n      if (tryCount === times) {\n        onError?.(err);\n        throw err;\n      }\n\n      if (shouldRetry && !shouldRetry(err, tryCount - 1)) {\n        onError?.(err);\n        throw err;\n      }\n\n      const ms = typeof delay === 'function' ? delay(tryCount - 1) : delay;\n\n      if (ms > 0) await sleep(ms, signal);\n    }\n  }\n\n  /* unreachable — the loop always returns or throws before exhausting all attempts */\n  return undefined as never;\n}\n"],"mappings":";;;;AAaA,SAAS,EAAY,GAA6B,GAA0D;CAC1G,IAAM,IAAQ,CAAC,MAAY,KAAA,IAA2C,KAAA,IAA/B,YAAY,QAAQ,CAAO,GAAe,CAAM,CAAC,CAAC,QACtF,MAAwB,KAAK,IAChC;CAEI,MAAM,WAAW,GAIrB,OAFI,EAAM,WAAW,IAAU,EAAM,KAE9B,YAAY,IAAI,CAAK;AAC9B;AAsCA,eAAsB,EACpB,GACA,EAAE,WAAQ,KAAK,YAAS,gBAAa,WAAQ,YAAS,WAAQ,MAAoB,CAAC,GACvE;CACZ,IAAI,CAAC,OAAO,UAAU,CAAK,KAAK,IAAQ,GACtC,MAAM,IAAI,EAAuB,gDAAgD,GAAO;CAG1F,KAAK,IAAI,IAAW,GAAG,KAAY,GAAO,KAAY;EACpD,IAAI,GAAQ,SAAS,MAAM,EAAW,CAAM;EAE5C,IAAM,IAAa,EAAY,GAAS,CAAM;EAE9C,IAAI;GACF,OAAO,MAAM,EAAG,CAAU;EAC5B,SAAS,GAAK;GAMZ,IALI,MAAa,KAKb,KAAe,CAAC,EAAY,GAAK,IAAW,CAAC,GAE/C,MADA,IAAU,CAAG,GACP;GAGR,IAAM,IAAK,OAAO,KAAU,aAAa,EAAM,IAAW,CAAC,IAAI;GAE/D,AAAI,IAAK,KAAG,MAAM,EAAM,GAAI,CAAM;EACpC;CACF;AAIF"}

package/dist/async/sleep.cjs

@@ -0,0 +1,2 @@
+const e=require("./abortError.cjs");async function t(t,n){return n?n.aborted?Promise.reject(e.abortError(n)):new Promise((r,i)=>{let a=setTimeout(()=>{n.removeEventListener(`abort`,o),r()},t),o=()=>{clearTimeout(a),n.removeEventListener(`abort`,o),i(e.abortError(n))};n.addEventListener(`abort`,o)}):new Promise(e=>setTimeout(e,t))}exports.sleep=t;
+//# sourceMappingURL=sleep.cjs.map

package/dist/async/sleep.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.cjs","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":"oCAqBA,eAAsB,EAAM,EAAiB,EAAqC,CAShF,OARK,EAID,EAAO,QACF,QAAQ,OAAO,EAAA,WAAW,CAAM,CAAC,EAGnC,IAAI,SAAe,EAAS,IAAW,CAC5C,IAAM,EAAK,eAAiB,CAC1B,EAAO,oBAAoB,QAAS,CAAO,EAC3C,EAAQ,CACV,EAAG,CAAO,EAEJ,MAAgB,CACpB,aAAa,CAAE,EACf,EAAO,oBAAoB,QAAS,CAAO,EAC3C,EAAO,EAAA,WAAW,CAAM,CAAC,CAC3B,EAEA,EAAO,iBAAiB,QAAS,CAAO,CAC1C,CAAC,EApBQ,IAAI,QAAS,GAAY,WAAW,EAAS,CAAO,CAAC,CAqBhE"}

package/dist/async/sleep.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Creates a Promise that resolves after a specified amount of time.
+ * If an `AbortSignal` is provided and fires before the delay elapses, the promise rejects with
+ * the signal's reason (or a generic `DOMException('Aborted', 'AbortError')`).
+ *
+ * @example
+ * ```ts
+ * sleep(1000).then(() => console.log('Hello, world!')); // logs after 1 second
+ *
+ * // With abort support
+ * const controller = new AbortController();
+ * await sleep(5000, controller.signal); // rejects immediately when aborted
+ * ```
+ *
+ * @param timeout - The number of milliseconds to wait before resolving the Promise.
+ * @param signal  - Optional AbortSignal to cancel the sleep early.
+ *
+ * @returns A Promise that resolves after the specified time.
+ */
+export declare function sleep(timeout: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/async/sleep.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhF"}