flowx-control 1.0.0

package/README.md

@@ -0,0 +1,443 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/flowx-control?style=flat-square&color=blue" alt="npm version" />
+  <img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square" alt="coverage" />
+  <img src="https://img.shields.io/npm/l/flowx-control?style=flat-square" alt="license" />
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen?style=flat-square" alt="zero deps" />
+  <img src="https://img.shields.io/badge/TypeScript-first-blue?style=flat-square&logo=typescript&logoColor=white" alt="typescript" />
+  <img src="https://img.shields.io/npm/dm/flowx-control?style=flat-square" alt="downloads" />
+</p>
+
+# FlowX
+
+**Production-grade resilience & async flow control for TypeScript/JavaScript.**
+
+> Stop shipping fragile async code. FlowX gives you battle-tested patterns — retry, circuit breaker, rate limiter, bulkhead, queue, and 12 more — in a single, zero-dependency, tree-shakable package with **100% test coverage**.
+
+---
+
+## Why FlowX?
+
+| | FlowX | Others |
+|--|-------|--------|
+| **Dependencies** | 0 | 3–15+ |
+| **Test Coverage** | 100% statements, branches, functions, lines | Partial |
+| **TypeScript** | Native `.d.ts` + `.d.mts` | Bolted-on types |
+| **Tree-shaking** | Per-module deep imports | Monolithic bundle |
+| **Module Support** | ESM + CJS + Types | Usually one |
+| **Patterns** | 17 resilience & flow primitives | 2–5 |
+
+---
+
+## Install
+
+```bash
+npm install flowx-control
+```
+
+```bash
+yarn add flowx-control
+```
+
+```bash
+pnpm add flowx-control
+```
+
+---
+
+## Quick Start
+
+```ts
+import { retry, createCircuitBreaker, withTimeout, rateLimit } from 'flowx-control';
+
+// Retry with exponential backoff
+const data = await retry(() => fetch('/api/data'), {
+  maxAttempts: 5,
+  delay: 1000,
+  backoff: 'exponential',
+});
+
+// Circuit breaker — stop cascading failures
+const breaker = createCircuitBreaker(fetchUser, {
+  failureThreshold: 5,
+  resetTimeout: 30_000,
+});
+const user = await breaker.fire(userId);
+
+// Timeout — never wait forever
+const result = await withTimeout(() => fetch('/slow'), 5000, {
+  fallback: () => cachedResponse,
+});
+
+// Rate limiter — respect API limits
+const limiter = createRateLimiter({ limit: 10, interval: 1000 });
+await limiter.execute(() => callExternalApi());
+```
+
+---
+
+## All 17 Modules
+
+### 🛡️ Resilience
+
+<details>
+<summary><strong>retry</strong> — Retry with backoff & jitter</summary>
+
+```ts
+import { retry } from 'flowx-control/retry';
+
+const data = await retry(() => fetch('/api'), {
+  maxAttempts: 5,
+  delay: 1000,
+  backoff: 'exponential',   // 'fixed' | 'linear' | 'exponential' | custom fn
+  jitter: true,
+  retryIf: (err) => err.status !== 404,
+  onRetry: (err, attempt) => console.log(`Attempt ${attempt}`),
+  signal: abortController.signal,
+});
+```
+</details>
+
+<details>
+<summary><strong>circuitBreaker</strong> — Stop cascading failures</summary>
+
+```ts
+import { createCircuitBreaker } from 'flowx-control/circuit-breaker';
+
+const breaker = createCircuitBreaker(callApi, {
+  failureThreshold: 5,
+  resetTimeout: 30000,
+  halfOpenLimit: 1,
+  successThreshold: 2,
+  shouldTrip: (err) => err.status >= 500,
+  onStateChange: (from, to) => log(`${from} → ${to}`),
+});
+
+const result = await breaker.fire(args);
+console.log(breaker.state);       // 'closed' | 'open' | 'half-open'
+console.log(breaker.failureCount);
+breaker.reset();
+```
+</details>
+
+<details>
+<summary><strong>fallback</strong> — Graceful degradation</summary>
+
+```ts
+import { withFallback, fallbackChain } from 'flowx-control/fallback';
+
+const data = await withFallback(
+  () => fetchFromPrimary(),
+  'default-value',
+  { onFallback: (err, idx) => console.warn(err) }
+);
+
+const result = await fallbackChain([
+  () => fetchFromPrimary(),
+  () => fetchFromCache(),
+  () => fetchFromFallback(),
+]);
+```
+</details>
+
+<details>
+<summary><strong>timeout</strong> — Never wait forever</summary>
+
+```ts
+import { withTimeout } from 'flowx-control/timeout';
+
+const result = await withTimeout(() => fetch('/slow-api'), 5000, {
+  fallback: () => cachedData,
+  message: 'API took too long',
+  signal: controller.signal,
+});
+```
+</details>
+
+### 🚦 Concurrency
+
+<details>
+<summary><strong>bulkhead</strong> — Isolate concurrent operations</summary>
+
+```ts
+import { createBulkhead } from 'flowx-control/bulkhead';
+
+const bulkhead = createBulkhead({
+  maxConcurrent: 10,
+  maxQueue: 100,
+  queueTimeout: 5000,
+});
+
+const result = await bulkhead.execute(() => processRequest());
+console.log(bulkhead.activeCount, bulkhead.queueSize);
+```
+</details>
+
+<details>
+<summary><strong>queue</strong> — Priority async task queue</summary>
+
+```ts
+import { createQueue } from 'flowx-control/queue';
+
+const queue = createQueue({ concurrency: 5, timeout: 10000 });
+
+const result = await queue.add(() => processJob(), { priority: 1 });
+const results = await queue.addAll(tasks.map(t => () => process(t)));
+
+await queue.onIdle(); // wait until all done
+queue.pause();
+queue.resume();
+```
+</details>
+
+<details>
+<summary><strong>semaphore</strong> — Counting resource lock</summary>
+
+```ts
+import { createSemaphore } from 'flowx-control/semaphore';
+
+const sem = createSemaphore(3); // max 3 concurrent
+const release = await sem.acquire();
+try {
+  await doWork();
+} finally {
+  release();
+}
+```
+</details>
+
+<details>
+<summary><strong>mutex</strong> — Mutual exclusion lock</summary>
+
+```ts
+import { createMutex } from 'flowx-control/mutex';
+
+const mutex = createMutex();
+const release = await mutex.acquire();
+try {
+  await criticalSection();
+} finally {
+  release();
+}
+```
+</details>
+
+### 🎛️ Flow Control
+
+<details>
+<summary><strong>rateLimit</strong> — Token bucket rate limiting</summary>
+
+```ts
+import { createRateLimiter } from 'flowx-control/rate-limit';
+
+const limiter = createRateLimiter({
+  limit: 100,
+  interval: 60_000,
+  strategy: 'queue',   // 'queue' | 'reject'
+});
+
+await limiter.execute(() => callApi());
+console.log(limiter.remaining);
+limiter.reset();
+```
+</details>
+
+<details>
+<summary><strong>throttle</strong> — Rate-limit function calls</summary>
+
+```ts
+import { throttle } from 'flowx-control/throttle';
+
+const save = throttle(saveToDb, 1000, {
+  leading: true,
+  trailing: true,
+});
+
+await save(data);
+save.cancel();
+```
+</details>
+
+<details>
+<summary><strong>debounce</strong> — Delay until activity pauses</summary>
+
+```ts
+import { debounce } from 'flowx-control/debounce';
+
+const search = debounce(searchApi, 300, {
+  leading: false,
+  trailing: true,
+  maxWait: 1000,
+});
+
+await search(query);
+await search.flush();
+search.cancel();
+```
+</details>
+
+<details>
+<summary><strong>batch</strong> — Process collections in chunks</summary>
+
+```ts
+import { batch } from 'flowx-control/batch';
+
+const result = await batch(urls, async (url, i) => {
+  return fetch(url).then(r => r.json());
+}, {
+  batchSize: 10,
+  concurrency: 3,
+  onProgress: (done, total) => console.log(`${done}/${total}`),
+  signal: controller.signal,
+});
+
+console.log(result.succeeded, result.failed, result.errors);
+```
+</details>
+
+<details>
+<summary><strong>pipeline</strong> — Compose async operations</summary>
+
+```ts
+import { pipeline, pipe } from 'flowx-control/pipeline';
+
+const transform = pipe(
+  (input: string) => input.trim(),
+  (str) => str.toUpperCase(),
+  async (str) => await translate(str),
+);
+
+const result = await transform('  hello world  ');
+```
+</details>
+
+### 🛠️ Utilities
+
+<details>
+<summary><strong>poll</strong> — Repeated polling with backoff</summary>
+
+```ts
+import { poll } from 'flowx-control/poll';
+
+const { result, stop } = poll(() => checkJobStatus(jobId), {
+  interval: 2000,
+  until: (status) => status === 'complete',
+  maxAttempts: 30,
+  backoff: 'exponential',
+  signal: controller.signal,
+});
+
+const finalStatus = await result;
+```
+</details>
+
+<details>
+<summary><strong>hedge</strong> — Hedged/speculative requests</summary>
+
+```ts
+import { hedge } from 'flowx-control/hedge';
+
+// If primary doesn't respond in 200ms, fire a parallel request
+const data = await hedge(() => fetch('/api'), {
+  delay: 200,
+  maxHedges: 2,
+});
+```
+</details>
+
+<details>
+<summary><strong>memo</strong> — Async memoization with TTL</summary>
+
+```ts
+import { memo } from 'flowx-control/memo';
+
+const cachedFetch = memo(fetchUserById, {
+  ttl: 60_000,
+  maxSize: 1000,
+  key: (id) => `user:${id}`,
+});
+
+const user = await cachedFetch(123);
+cachedFetch.clear();
+```
+</details>
+
+<details>
+<summary><strong>deferred</strong> — Externally resolvable promise</summary>
+
+```ts
+import { deferred } from 'flowx-control/deferred';
+
+const d = deferred<string>();
+setTimeout(() => d.resolve('hello'), 1000);
+const value = await d.promise; // 'hello'
+```
+</details>
+
+---
+
+## Deep Imports (Tree-shaking)
+
+Import only what you need — zero unused code in your bundle:
+
+```ts
+// Only pulls in ~2KB instead of the full 28KB
+import { retry } from 'flowx-control/retry';
+import { createQueue } from 'flowx-control/queue';
+```
+
+---
+
+## Error Hierarchy
+
+All errors extend `FlowXError` with a machine-readable `code`:
+
+| Error | Code | Thrown by |
+|-------|------|----------|
+| `TimeoutError` | `ERR_TIMEOUT` | `withTimeout` |
+| `CircuitBreakerError` | `ERR_CIRCUIT_OPEN` | `circuitBreaker` |
+| `BulkheadError` | `ERR_BULKHEAD_FULL` | `bulkhead` |
+| `AbortError` | `ERR_ABORTED` | `poll`, `batch`, `timeout` |
+| `RateLimitError` | `ERR_RATE_LIMIT` | `rateLimit` |
+
+```ts
+import { TimeoutError, FlowXError } from 'flowx-control';
+
+try {
+  await withTimeout(fn, 1000);
+} catch (err) {
+  if (err instanceof TimeoutError) {
+    console.log(err.code); // 'ERR_TIMEOUT'
+  }
+}
+```
+
+---
+
+## Compatibility
+
+| Environment | Support |
+|-------------|---------|
+| Node.js | ≥ 16 |
+| Bun | ✅ |
+| Deno | ✅ |
+| Browsers | ✅ (ESM) |
+| TypeScript | ≥ 4.7 |
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/Avinashvelu03/FlowX.git
+cd FlowX
+npm install
+npm test          # Run tests with 100% coverage
+npm run lint      # ESLint
+npm run build     # Build ESM + CJS + DTS
+```
+
+---
+
+## License
+
+MIT © [Avinash](https://github.com/Avinashvelu03)

package/dist/batch.d.mts

@@ -0,0 +1,37 @@
+interface BatchOptions {
+    /** Maximum concurrent batch operations (default: Infinity) */
+    concurrency?: number;
+    /** Number of items per batch (default: 1) */
+    batchSize?: number;
+    /** Progress callback */
+    onProgress?: (completed: number, total: number) => void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+interface BatchResult<T> {
+    /** All results in order */
+    results: T[];
+    /** Total items processed */
+    total: number;
+    /** Number of succeeded items */
+    succeeded: number;
+    /** Number of failed items */
+    failed: number;
+    /** Errors indexed by position */
+    errors: Map<number, Error>;
+}
+/**
+ * Process an array of items in batches with concurrency control.
+ *
+ * @example
+ * ```ts
+ * const results = await batch(
+ *   urls,
+ *   async (url) => fetch(url).then(r => r.json()),
+ *   { concurrency: 5, batchSize: 10 },
+ * );
+ * ```
+ */
+declare function batch<TItem, TResult>(items: TItem[], fn: (item: TItem, index: number) => Promise<TResult>, options?: BatchOptions): Promise<BatchResult<TResult>>;
+
+export { type BatchOptions, type BatchResult, batch };

package/dist/batch.d.ts

@@ -0,0 +1,37 @@
+interface BatchOptions {
+    /** Maximum concurrent batch operations (default: Infinity) */
+    concurrency?: number;
+    /** Number of items per batch (default: 1) */
+    batchSize?: number;
+    /** Progress callback */
+    onProgress?: (completed: number, total: number) => void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+interface BatchResult<T> {
+    /** All results in order */
+    results: T[];
+    /** Total items processed */
+    total: number;
+    /** Number of succeeded items */
+    succeeded: number;
+    /** Number of failed items */
+    failed: number;
+    /** Errors indexed by position */
+    errors: Map<number, Error>;
+}
+/**
+ * Process an array of items in batches with concurrency control.
+ *
+ * @example
+ * ```ts
+ * const results = await batch(
+ *   urls,
+ *   async (url) => fetch(url).then(r => r.json()),
+ *   { concurrency: 5, batchSize: 10 },
+ * );
+ * ```
+ */
+declare function batch<TItem, TResult>(items: TItem[], fn: (item: TItem, index: number) => Promise<TResult>, options?: BatchOptions): Promise<BatchResult<TResult>>;
+
+export { type BatchOptions, type BatchResult, batch };

package/dist/batch.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// src/types.ts
+var FlowXError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "FlowXError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AbortError = class extends FlowXError {
+  constructor(message = "Operation aborted") {
+    super(message, "ERR_ABORTED");
+    this.name = "AbortError";
+  }
+};
+
+// src/batch.ts
+async function batch(items, fn, options) {
+  const { concurrency = Infinity, batchSize = 1, onProgress, signal } = options ?? {};
+  if (batchSize < 1) throw new RangeError("batchSize must be >= 1");
+  if (concurrency < 1) throw new RangeError("concurrency must be >= 1");
+  const results = new Array(items.length);
+  const errors = /* @__PURE__ */ new Map();
+  let completed = 0;
+  let succeeded = 0;
+  let failed = 0;
+  const batches = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    batches.push({
+      items: items.slice(i, i + batchSize),
+      startIndex: i
+    });
+  }
+  let batchIndex = 0;
+  async function processBatch() {
+    while (batchIndex < batches.length) {
+      if (signal?.aborted) throw new AbortError();
+      const currentBatch = batches[batchIndex++];
+      for (let i = 0; i < currentBatch.items.length; i++) {
+        if (signal?.aborted) throw new AbortError();
+        const globalIndex = currentBatch.startIndex + i;
+        try {
+          results[globalIndex] = await fn(currentBatch.items[i], globalIndex);
+          succeeded++;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          errors.set(globalIndex, err);
+          results[globalIndex] = void 0;
+          failed++;
+        }
+        completed++;
+        onProgress?.(completed, items.length);
+      }
+    }
+  }
+  const workers = [];
+  const workerCount = Math.min(concurrency, batches.length);
+  for (let i = 0; i < workerCount; i++) {
+    workers.push(processBatch());
+  }
+  await Promise.all(workers);
+  return {
+    results,
+    total: items.length,
+    succeeded,
+    failed,
+    errors
+  };
+}
+
+exports.batch = batch;
+//# sourceMappingURL=batch.js.map
+//# sourceMappingURL=batch.js.map

package/dist/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/batch.ts"],"names":[],"mappings":"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","file":"batch.js","sourcesContent":["// ============================================================================\n// FlowX — Types & Error Hierarchy\n// ============================================================================\n\n/** Generic async function signature */\nexport type AsyncFn<TArgs extends any[] = any[], TReturn = any> = (\n  ...args: TArgs\n) => Promise<TReturn>;\n\n/** Backoff strategy for retry/poll operations */\nexport type BackoffStrategy =\n  | 'fixed'\n  | 'linear'\n  | 'exponential'\n  | ((attempt: number, delay: number) => number);\n\n// ── Error Classes ───────────────────────────────────────────────────────────\n\n/** Base error class for all FlowX errors */\nexport class FlowXError extends Error {\n  public readonly code: string;\n  constructor(message: string, code: string) {\n    super(message);\n    this.name = 'FlowXError';\n    this.code = code;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a promise exceeds its timeout */\nexport class TimeoutError extends FlowXError {\n  constructor(message = 'Operation timed out') {\n    super(message, 'ERR_TIMEOUT');\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Thrown when a circuit breaker is open */\nexport class CircuitBreakerError extends FlowXError {\n  constructor(message = 'Circuit breaker is open') {\n    super(message, 'ERR_CIRCUIT_OPEN');\n    this.name = 'CircuitBreakerError';\n  }\n}\n\n/** Thrown when a bulkhead rejects due to capacity */\nexport class BulkheadError extends FlowXError {\n  constructor(message = 'Bulkhead capacity exceeded') {\n    super(message, 'ERR_BULKHEAD_FULL');\n    this.name = 'BulkheadError';\n  }\n}\n\n/** Thrown when an operation is aborted */\nexport class AbortError extends FlowXError {\n  constructor(message = 'Operation aborted') {\n    super(message, 'ERR_ABORTED');\n    this.name = 'AbortError';\n  }\n}\n\n/** Thrown when rate limit is exceeded */\nexport class RateLimitError extends FlowXError {\n  constructor(message = 'Rate limit exceeded') {\n    super(message, 'ERR_RATE_LIMIT');\n    this.name = 'RateLimitError';\n  }\n}\n\n// ── Utility Helpers ─────────────────────────────────────────────────────────\n\n/** Sleep for the specified duration, respecting AbortSignal */\nexport function sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new AbortError());\n      return;\n    }\n\n    let onAbort: (() => void) | undefined;\n\n    const timer = setTimeout(() => {\n      if (signal && onAbort) {\n        signal.removeEventListener('abort', onAbort);\n      }\n      resolve();\n    }, ms);\n\n    if (signal) {\n      onAbort = () => {\n        clearTimeout(timer);\n        reject(new AbortError());\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n  });\n}\n\n/** Calculate delay based on backoff strategy */\nexport function calculateDelay(\n  attempt: number,\n  baseDelay: number,\n  strategy: BackoffStrategy,\n  jitter: boolean | number = false,\n): number {\n  let delay: number;\n\n  if (typeof strategy === 'function') {\n    delay = strategy(attempt, baseDelay);\n  } else {\n    switch (strategy) {\n      case 'fixed':\n        delay = baseDelay;\n        break;\n      case 'linear':\n        delay = baseDelay * attempt;\n        break;\n      case 'exponential':\n        delay = baseDelay * Math.pow(2, attempt - 1);\n        break;\n    }\n  }\n\n  if (jitter) {\n    const factor = typeof jitter === 'number' ? jitter : 1;\n    delay = delay * (1 - factor * 0.5 + Math.random() * factor);\n  }\n\n  return Math.max(0, Math.floor(delay));\n}\n","// ============================================================================\n// FlowX — Batch Processing with Concurrency\n// ============================================================================\nimport { AbortError } from './types';\n\nexport interface BatchOptions {\n  /** Maximum concurrent batch operations (default: Infinity) */\n  concurrency?: number;\n  /** Number of items per batch (default: 1) */\n  batchSize?: number;\n  /** Progress callback */\n  onProgress?: (completed: number, total: number) => void;\n  /** AbortSignal for cancellation */\n  signal?: AbortSignal;\n}\n\nexport interface BatchResult<T> {\n  /** All results in order */\n  results: T[];\n  /** Total items processed */\n  total: number;\n  /** Number of succeeded items */\n  succeeded: number;\n  /** Number of failed items */\n  failed: number;\n  /** Errors indexed by position */\n  errors: Map<number, Error>;\n}\n\n/**\n * Process an array of items in batches with concurrency control.\n *\n * @example\n * ```ts\n * const results = await batch(\n *   urls,\n *   async (url) => fetch(url).then(r => r.json()),\n *   { concurrency: 5, batchSize: 10 },\n * );\n * ```\n */\nexport async function batch<TItem, TResult>(\n  items: TItem[],\n  fn: (item: TItem, index: number) => Promise<TResult>,\n  options?: BatchOptions,\n): Promise<BatchResult<TResult>> {\n  const { concurrency = Infinity, batchSize = 1, onProgress, signal } = options ?? {};\n\n  if (batchSize < 1) throw new RangeError('batchSize must be >= 1');\n  if (concurrency < 1) throw new RangeError('concurrency must be >= 1');\n\n  const results: TResult[] = new Array(items.length);\n  const errors = new Map<number, Error>();\n  let completed = 0;\n  let succeeded = 0;\n  let failed = 0;\n\n  // Split items into batches\n  const batches: Array<{ items: TItem[]; startIndex: number }> = [];\n  for (let i = 0; i < items.length; i += batchSize) {\n    batches.push({\n      items: items.slice(i, i + batchSize),\n      startIndex: i,\n    });\n  }\n\n  // Process batches with concurrency control\n  let batchIndex = 0;\n\n  async function processBatch(): Promise<void> {\n    while (batchIndex < batches.length) {\n      if (signal?.aborted) throw new AbortError();\n\n      const currentBatch = batches[batchIndex++];\n\n      for (let i = 0; i < currentBatch.items.length; i++) {\n        if (signal?.aborted) throw new AbortError();\n\n        const globalIndex = currentBatch.startIndex + i;\n        try {\n          results[globalIndex] = await fn(currentBatch.items[i], globalIndex);\n          succeeded++;\n        } catch (error) {\n          const err = error instanceof Error ? error : new Error(String(error));\n          errors.set(globalIndex, err);\n          results[globalIndex] = undefined as TResult;\n          failed++;\n        }\n        completed++;\n        onProgress?.(completed, items.length);\n      }\n    }\n  }\n\n  const workers: Promise<void>[] = [];\n  const workerCount = Math.min(concurrency, batches.length);\n\n  for (let i = 0; i < workerCount; i++) {\n    workers.push(processBatch());\n  }\n\n  await Promise.all(workers);\n\n  return {\n    results,\n    total: items.length,\n    succeeded,\n    failed,\n    errors,\n  };\n}\n"]}

package/dist/batch.mjs

@@ -0,0 +1,73 @@
+// src/types.ts
+var FlowXError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = "FlowXError";
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AbortError = class extends FlowXError {
+  constructor(message = "Operation aborted") {
+    super(message, "ERR_ABORTED");
+    this.name = "AbortError";
+  }
+};
+
+// src/batch.ts
+async function batch(items, fn, options) {
+  const { concurrency = Infinity, batchSize = 1, onProgress, signal } = options ?? {};
+  if (batchSize < 1) throw new RangeError("batchSize must be >= 1");
+  if (concurrency < 1) throw new RangeError("concurrency must be >= 1");
+  const results = new Array(items.length);
+  const errors = /* @__PURE__ */ new Map();
+  let completed = 0;
+  let succeeded = 0;
+  let failed = 0;
+  const batches = [];
+  for (let i = 0; i < items.length; i += batchSize) {
+    batches.push({
+      items: items.slice(i, i + batchSize),
+      startIndex: i
+    });
+  }
+  let batchIndex = 0;
+  async function processBatch() {
+    while (batchIndex < batches.length) {
+      if (signal?.aborted) throw new AbortError();
+      const currentBatch = batches[batchIndex++];
+      for (let i = 0; i < currentBatch.items.length; i++) {
+        if (signal?.aborted) throw new AbortError();
+        const globalIndex = currentBatch.startIndex + i;
+        try {
+          results[globalIndex] = await fn(currentBatch.items[i], globalIndex);
+          succeeded++;
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          errors.set(globalIndex, err);
+          results[globalIndex] = void 0;
+          failed++;
+        }
+        completed++;
+        onProgress?.(completed, items.length);
+      }
+    }
+  }
+  const workers = [];
+  const workerCount = Math.min(concurrency, batches.length);
+  for (let i = 0; i < workerCount; i++) {
+    workers.push(processBatch());
+  }
+  await Promise.all(workers);
+  return {
+    results,
+    total: items.length,
+    succeeded,
+    failed,
+    errors
+  };
+}
+
+export { batch };
+//# sourceMappingURL=batch.mjs.map
+//# sourceMappingURL=batch.mjs.map