@backblaze-labs/b2-sdk 0.1.0

package/dist/copy/large.d.ts

@@ -0,0 +1,53 @@
+import { AccountInfo } from '../auth/account-info.js';
+import { RawClient } from '../raw/index.js';
+import { EncryptionSetting } from '../types/encryption.js';
+import { FileVersion } from '../types/file.js';
+import { BucketId, FileId } from '../types/ids.js';
+/** Options for a server-side multipart copy. */
+export interface CopyLargeFileOptions {
+    /** ID of the source file version to copy. */
+    readonly sourceFileId: FileId;
+    /** Destination file name in the target bucket. */
+    readonly fileName: string;
+    /** Target bucket. Defaults to the source's bucket. */
+    readonly destinationBucketId?: BucketId;
+    /** Size of each part in bytes. Defaults to the account's recommended part size. */
+    readonly partSize?: number;
+    /**
+     * Maximum number of parts copied in parallel. Defaults to
+     * {@link DEFAULT_TRANSFER_CONCURRENCY}.
+     */
+    readonly concurrency?: number;
+    /** MIME type for the destination file. Defaults to `b2/x-auto`. */
+    readonly contentType?: string;
+    /** Custom file info merged into the destination. */
+    readonly fileInfo?: Record<string, string>;
+    /** Server-side encryption applied to the destination. */
+    readonly destinationServerSideEncryption?: EncryptionSetting;
+    /** SSE-C settings used to read the source if it was uploaded with SSE-C. */
+    readonly sourceServerSideEncryption?: EncryptionSetting;
+    /**
+     * Optional abort signal. Checked before dispatching each part and
+     * between parts; an aborted signal cancels remaining parts and rolls
+     * back the unfinished large file via best-effort `cancelLargeFile`.
+     *
+     * Aborting does NOT roll back parts already accepted by B2; those
+     * exist on the unfinished large file until the cancel call completes
+     * or B2's lifecycle expires the in-progress upload (24 hours).
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Performs a server-side copy of a file using the multipart `b2_copy_part` protocol.
+ * The source bytes never traverse the client; B2 copies each range internally.
+ *
+ * Falls back to a single `copyFile` call when the source fits in one part.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state (used to resolve API URL, recommended part size).
+ * @param options - Copy parameters including source, destination, and concurrency.
+ *
+ * @returns The resulting destination {@link FileVersion}.
+ */
+export declare function copyLargeFile(raw: RawClient, accountInfo: AccountInfo, options: CopyLargeFileOptions): Promise<FileVersion>;
+//# sourceMappingURL=large.d.ts.map

package/dist/copy/large.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"large.d.ts","sourceRoot":"","sources":["../../src/copy/large.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAsB,MAAM,iBAAiB,CAAA;AAMhF,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sDAAsD;IACtD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,QAAQ,CAAA;IACvC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,yDAAyD;IACzD,QAAQ,CAAC,+BAA+B,CAAC,EAAE,iBAAiB,CAAA;IAC5D,4EAA4E;IAC5E,QAAQ,CAAC,0BAA0B,CAAC,EAAE,iBAAiB,CAAA;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,CA0FtB"}

package/dist/copy/large.js

@@ -0,0 +1,74 @@
+import { fileId } from "../types/ids.js";
+import { cancelLargeFileBestEffort } from "../upload/cancel.js";
+import { Semaphore } from "../upload/concurrency.js";
+import { DEFAULT_CONTENT_TYPE, DEFAULT_TRANSFER_CONCURRENCY } from "../util/defaults.js";
+import { byteRangeHeader, planRanges } from "../util/plan-ranges.js";
+async function copyLargeFile(raw, accountInfo, options) {
+  const recommendedPartSize = accountInfo.getRecommendedPartSize();
+  const minPartSize = accountInfo.getAbsoluteMinimumPartSize();
+  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize);
+  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY;
+  const sourceInfo = await raw.getFileInfo(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+    fileId: options.sourceFileId
+  });
+  const totalSize = sourceInfo.contentLength;
+  if (totalSize <= partSize) {
+    return raw.copyFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+      sourceFileId: options.sourceFileId,
+      fileName: options.fileName,
+      ...options.destinationBucketId !== void 0 ? { destinationBucketId: options.destinationBucketId } : {},
+      ...options.contentType !== void 0 ? { contentType: options.contentType } : {},
+      ...options.fileInfo !== void 0 ? { fileInfo: options.fileInfo } : {},
+      ...options.destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption: options.destinationServerSideEncryption } : {},
+      ...options.sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption: options.sourceServerSideEncryption } : {}
+    });
+  }
+  const destBucketId = options.destinationBucketId ?? sourceInfo.bucketId;
+  const startResp = await raw.startLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+    bucketId: destBucketId,
+    fileName: options.fileName,
+    contentType: options.contentType ?? sourceInfo.contentType ?? DEFAULT_CONTENT_TYPE,
+    fileInfo: options.fileInfo ?? {},
+    ...options.destinationServerSideEncryption !== void 0 ? { serverSideEncryption: options.destinationServerSideEncryption } : {}
+  });
+  const largeFileId = startResp.fileId;
+  const ranges = planRanges(totalSize, partSize);
+  const partSha1s = new Array(ranges.length);
+  const sem = new Semaphore(concurrency);
+  try {
+    options.signal?.throwIfAborted();
+    await Promise.all(
+      ranges.map(async (range) => {
+        await sem.acquire();
+        try {
+          options.signal?.throwIfAborted();
+          const resp = await raw.copyPart(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+            sourceFileId: options.sourceFileId,
+            // `startLargeFile` returns `LargeFileId`; `copyPart` takes the
+            // same value typed as `FileId`. Re-brand via the factory.
+            largeFileId: fileId(largeFileId),
+            partNumber: range.partNumber,
+            range: byteRangeHeader(range.start, range.end),
+            ...options.sourceServerSideEncryption !== void 0 ? { sourceServerSideEncryption: options.sourceServerSideEncryption } : {},
+            ...options.destinationServerSideEncryption !== void 0 ? { destinationServerSideEncryption: options.destinationServerSideEncryption } : {}
+          });
+          partSha1s[range.partNumber - 1] = resp.contentSha1;
+        } finally {
+          sem.release();
+        }
+      })
+    );
+    options.signal?.throwIfAborted();
+    return await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+      fileId: largeFileId,
+      partSha1Array: partSha1s
+    });
+  } catch (err) {
+    await cancelLargeFileBestEffort(raw, accountInfo, largeFileId);
+    throw err;
+  }
+}
+export {
+  copyLargeFile
+};
+//# sourceMappingURL=large.js.map

package/dist/copy/large.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"large.js","sources":["../../src/copy/large.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { EncryptionSetting } from '../types/encryption.ts'\nimport type { FileVersion } from '../types/file.ts'\nimport { type BucketId, type FileId, fileId as fileIdOf } from '../types/ids.ts'\nimport { cancelLargeFileBestEffort } from '../upload/cancel.ts'\nimport { Semaphore } from '../upload/concurrency.ts'\nimport { DEFAULT_CONTENT_TYPE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\n\n/** Options for a server-side multipart copy. */\nexport interface CopyLargeFileOptions {\n  /** ID of the source file version to copy. */\n  readonly sourceFileId: FileId\n  /** Destination file name in the target bucket. */\n  readonly fileName: string\n  /** Target bucket. Defaults to the source's bucket. */\n  readonly destinationBucketId?: BucketId\n  /** Size of each part in bytes. Defaults to the account's recommended part size. */\n  readonly partSize?: number\n  /**\n   * Maximum number of parts copied in parallel. Defaults to\n   * {@link DEFAULT_TRANSFER_CONCURRENCY}.\n   */\n  readonly concurrency?: number\n  /** MIME type for the destination file. Defaults to `b2/x-auto`. */\n  readonly contentType?: string\n  /** Custom file info merged into the destination. */\n  readonly fileInfo?: Record<string, string>\n  /** Server-side encryption applied to the destination. */\n  readonly destinationServerSideEncryption?: EncryptionSetting\n  /** SSE-C settings used to read the source if it was uploaded with SSE-C. */\n  readonly sourceServerSideEncryption?: EncryptionSetting\n  /**\n   * Optional abort signal. Checked before dispatching each part and\n   * between parts; an aborted signal cancels remaining parts and rolls\n   * back the unfinished large file via best-effort `cancelLargeFile`.\n   *\n   * Aborting does NOT roll back parts already accepted by B2; those\n   * exist on the unfinished large file until the cancel call completes\n   * or B2's lifecycle expires the in-progress upload (24 hours).\n   */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Performs a server-side copy of a file using the multipart `b2_copy_part` protocol.\n * The source bytes never traverse the client; B2 copies each range internally.\n *\n * Falls back to a single `copyFile` call when the source fits in one part.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state (used to resolve API URL, recommended part size).\n * @param options - Copy parameters including source, destination, and concurrency.\n *\n * @returns The resulting destination {@link FileVersion}.\n */\nexport async function copyLargeFile(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: CopyLargeFileOptions,\n): Promise<FileVersion> {\n  const recommendedPartSize = accountInfo.getRecommendedPartSize()\n  const minPartSize = accountInfo.getAbsoluteMinimumPartSize()\n  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize)\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n\n  // Discover the source size via getFileInfo.\n  const sourceInfo = await raw.getFileInfo(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n    fileId: options.sourceFileId,\n  })\n  const totalSize = sourceInfo.contentLength\n\n  // Below the part threshold, take the single-call fast path.\n  if (totalSize <= partSize) {\n    return raw.copyFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n      sourceFileId: options.sourceFileId,\n      fileName: options.fileName,\n      ...(options.destinationBucketId !== undefined\n        ? { destinationBucketId: options.destinationBucketId }\n        : {}),\n      ...(options.contentType !== undefined ? { contentType: options.contentType } : {}),\n      ...(options.fileInfo !== undefined ? { fileInfo: options.fileInfo } : {}),\n      ...(options.destinationServerSideEncryption !== undefined\n        ? { destinationServerSideEncryption: options.destinationServerSideEncryption }\n        : {}),\n      ...(options.sourceServerSideEncryption !== undefined\n        ? { sourceServerSideEncryption: options.sourceServerSideEncryption }\n        : {}),\n    })\n  }\n\n  // Resolve destination bucket (defaults to source's bucket). Both operands\n  // are already typed `BucketId`, so no cast is needed.\n  const destBucketId = options.destinationBucketId ?? sourceInfo.bucketId\n\n  // Start the multipart file.\n  const startResp = await raw.startLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n    bucketId: destBucketId,\n    fileName: options.fileName,\n    contentType: options.contentType ?? sourceInfo.contentType ?? DEFAULT_CONTENT_TYPE,\n    fileInfo: options.fileInfo ?? {},\n    ...(options.destinationServerSideEncryption !== undefined\n      ? { serverSideEncryption: options.destinationServerSideEncryption }\n      : {}),\n  })\n  const largeFileId = startResp.fileId\n\n  const ranges = planRanges(totalSize, partSize)\n  const partSha1s: string[] = new Array(ranges.length)\n  const sem = new Semaphore(concurrency)\n\n  try {\n    options.signal?.throwIfAborted()\n    await Promise.all(\n      ranges.map(async (range) => {\n        await sem.acquire()\n        try {\n          // Re-check the abort flag after every queue handoff so the\n          // first cancelled task short-circuits the remaining parts.\n          options.signal?.throwIfAborted()\n          const resp = await raw.copyPart(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n            sourceFileId: options.sourceFileId,\n            // `startLargeFile` returns `LargeFileId`; `copyPart` takes the\n            // same value typed as `FileId`. Re-brand via the factory.\n            largeFileId: fileIdOf(largeFileId),\n            partNumber: range.partNumber,\n            range: byteRangeHeader(range.start, range.end),\n            ...(options.sourceServerSideEncryption !== undefined\n              ? { sourceServerSideEncryption: options.sourceServerSideEncryption }\n              : {}),\n            ...(options.destinationServerSideEncryption !== undefined\n              ? { destinationServerSideEncryption: options.destinationServerSideEncryption }\n              : {}),\n          })\n          partSha1s[range.partNumber - 1] = resp.contentSha1\n        } finally {\n          sem.release()\n        }\n      }),\n    )\n\n    options.signal?.throwIfAborted()\n    return await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n      fileId: largeFileId,\n      partSha1Array: partSha1s,\n    })\n  } catch (err) {\n    await cancelLargeFileBestEffort(raw, accountInfo, largeFileId)\n    throw err\n  }\n}\n"],"names":["fileIdOf"],"mappings":";;;;;AAyDA,eAAsB,cACpB,KACA,aACA,SACsB;AACtB,QAAM,sBAAsB,YAAY,uBAAA;AACxC,QAAM,cAAc,YAAY,2BAAA;AAChC,QAAM,WAAW,KAAK,IAAI,QAAQ,YAAY,qBAAqB,WAAW;AAC9E,QAAM,cAAc,QAAQ,eAAe;AAG3C,QAAM,aAAa,MAAM,IAAI,YAAY,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,IAC5F,QAAQ,QAAQ;AAAA,EAAA,CACjB;AACD,QAAM,YAAY,WAAW;AAG7B,MAAI,aAAa,UAAU;AACzB,WAAO,IAAI,SAAS,YAAY,aAAa,YAAY,gBAAgB;AAAA,MACvE,cAAc,QAAQ;AAAA,MACtB,UAAU,QAAQ;AAAA,MAClB,GAAI,QAAQ,wBAAwB,SAChC,EAAE,qBAAqB,QAAQ,oBAAA,IAC/B,CAAA;AAAA,MACJ,GAAI,QAAQ,gBAAgB,SAAY,EAAE,aAAa,QAAQ,YAAA,IAAgB,CAAA;AAAA,MAC/E,GAAI,QAAQ,aAAa,SAAY,EAAE,UAAU,QAAQ,SAAA,IAAa,CAAA;AAAA,MACtE,GAAI,QAAQ,oCAAoC,SAC5C,EAAE,iCAAiC,QAAQ,gCAAA,IAC3C,CAAA;AAAA,MACJ,GAAI,QAAQ,+BAA+B,SACvC,EAAE,4BAA4B,QAAQ,+BACtC,CAAA;AAAA,IAAC,CACN;AAAA,EACH;AAIA,QAAM,eAAe,QAAQ,uBAAuB,WAAW;AAG/D,QAAM,YAAY,MAAM,IAAI,eAAe,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,IAC9F,UAAU;AAAA,IACV,UAAU,QAAQ;AAAA,IAClB,aAAa,QAAQ,eAAe,WAAW,eAAe;AAAA,IAC9D,UAAU,QAAQ,YAAY,CAAA;AAAA,IAC9B,GAAI,QAAQ,oCAAoC,SAC5C,EAAE,sBAAsB,QAAQ,oCAChC,CAAA;AAAA,EAAC,CACN;AACD,QAAM,cAAc,UAAU;AAE9B,QAAM,SAAS,WAAW,WAAW,QAAQ;AAC7C,QAAM,YAAsB,IAAI,MAAM,OAAO,MAAM;AACnD,QAAM,MAAM,IAAI,UAAU,WAAW;AAErC,MAAI;AACF,YAAQ,QAAQ,eAAA;AAChB,UAAM,QAAQ;AAAA,MACZ,OAAO,IAAI,OAAO,UAAU;AAC1B,cAAM,IAAI,QAAA;AACV,YAAI;AAGF,kBAAQ,QAAQ,eAAA;AAChB,gBAAM,OAAO,MAAM,IAAI,SAAS,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,YACnF,cAAc,QAAQ;AAAA;AAAA;AAAA,YAGtB,aAAaA,OAAS,WAAW;AAAA,YACjC,YAAY,MAAM;AAAA,YAClB,OAAO,gBAAgB,MAAM,OAAO,MAAM,GAAG;AAAA,YAC7C,GAAI,QAAQ,+BAA+B,SACvC,EAAE,4BAA4B,QAAQ,2BAAA,IACtC,CAAA;AAAA,YACJ,GAAI,QAAQ,oCAAoC,SAC5C,EAAE,iCAAiC,QAAQ,oCAC3C,CAAA;AAAA,UAAC,CACN;AACD,oBAAU,MAAM,aAAa,CAAC,IAAI,KAAK;AAAA,QACzC,UAAA;AACE,cAAI,QAAA;AAAA,QACN;AAAA,MACF,CAAC;AAAA,IAAA;AAGH,YAAQ,QAAQ,eAAA;AAChB,WAAO,MAAM,IAAI,gBAAgB,YAAY,aAAa,YAAY,gBAAgB;AAAA,MACpF,QAAQ;AAAA,MACR,eAAe;AAAA,IAAA,CAChB;AAAA,EACH,SAAS,KAAK;AACZ,UAAM,0BAA0B,KAAK,aAAa,WAAW;AAC7D,UAAM;AAAA,EACR;AACF;"}

package/dist/download/parallel.cjs

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const retry = require("../http/retry.cjs");
+const collect = require("../streams/collect.cjs");
+const defaults = require("../util/defaults.cjs");
+const planRanges = require("../util/plan-ranges.cjs");
+function createParallelDownloadStream(raw, accountInfo, options) {
+  const rangeSize = options.rangeSize ?? 10 * 1024 * 1024;
+  const concurrency = options.concurrency ?? defaults.DEFAULT_TRANSFER_CONCURRENCY;
+  const totalSize = options.totalSize;
+  const retryOptions = {
+    ...retry.DEFAULT_RETRY_OPTIONS,
+    ...options.maxRetries !== void 0 ? { maxRetries: options.maxRetries } : {}
+  };
+  const abort = options.signal;
+  const ranges = planRanges.planRanges(totalSize, rangeSize);
+  const windowSize = concurrency * 2;
+  const inflight = /* @__PURE__ */ new Map();
+  const buffer = /* @__PURE__ */ new Map();
+  let nextToSchedule = 0;
+  let nextToEmit = 0;
+  let firstError = null;
+  function scheduleNext() {
+    while (firstError === null && // Honour abort here so a completed range that triggers a top-up
+    // doesn't queue one final fetch after the caller aborted. Without
+    // this gate, one extra range request fires post-abort before the
+    // `pull()` loop notices.
+    abort?.aborted !== true && nextToSchedule < ranges.length && inflight.size + buffer.size < windowSize) {
+      const range = ranges[nextToSchedule];
+      if (range === void 0) break;
+      const idx = nextToSchedule;
+      nextToSchedule++;
+      const task = (async () => {
+        try {
+          const data = await fetchRangeWithRetry(
+            raw,
+            accountInfo,
+            options.fileId,
+            range.start,
+            range.end,
+            retryOptions,
+            abort
+          );
+          buffer.set(idx, data);
+        } catch (err) {
+          if (firstError === null) firstError = err;
+        } finally {
+          inflight.delete(idx);
+        }
+      })();
+      inflight.set(idx, task);
+    }
+  }
+  return new ReadableStream({
+    start(controller) {
+      try {
+        abort?.throwIfAborted();
+        scheduleNext();
+      } catch (err) {
+        controller.error(err);
+      }
+    },
+    async pull(controller) {
+      try {
+        while (!buffer.has(nextToEmit)) {
+          abort?.throwIfAborted();
+          if (firstError !== null) throw firstError;
+          if (inflight.size === 0) {
+            controller.close();
+            return;
+          }
+          await Promise.race(inflight.values());
+        }
+        const data = buffer.get(nextToEmit);
+        if (data !== void 0) {
+          buffer.delete(nextToEmit);
+          nextToEmit++;
+          controller.enqueue(data);
+        }
+        scheduleNext();
+        if (nextToEmit >= ranges.length && buffer.size === 0 && inflight.size === 0 && firstError === null) {
+          controller.close();
+        }
+      } catch (err) {
+        controller.error(err);
+      }
+    },
+    cancel() {
+      buffer.clear();
+    }
+  });
+}
+async function fetchRangeWithRetry(raw, accountInfo, fileId, start, end, retryOptions, signal) {
+  let lastError;
+  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
+    if (attempt > 0) {
+      const delay = retry.computeBackoff(attempt - 1, retryOptions);
+      await retry.sleep(delay, signal);
+    }
+    try {
+      signal?.throwIfAborted();
+      const resp = await raw.downloadFileById(
+        accountInfo.getDownloadUrl(),
+        accountInfo.getAuthToken(),
+        fileId,
+        {
+          range: planRanges.byteRangeHeader(start, end),
+          ...signal !== void 0 ? { signal } : {}
+        }
+      );
+      if (!resp.body) throw new Error("Download chunk has no body");
+      return await collect.collectStream(resp.body);
+    } catch (err) {
+      lastError = err;
+      if (signal?.aborted) throw err;
+      if (err instanceof DOMException && err.name === "AbortError") throw err;
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Range download failed after retries");
+}
+exports.createParallelDownloadStream = createParallelDownloadStream;
+//# sourceMappingURL=parallel.cjs.map

package/dist/download/parallel.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.cjs","sources":["../../src/download/parallel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { DEFAULT_RETRY_OPTIONS, computeBackoff, sleep } from '../http/retry.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport { collectStream } from '../streams/collect.ts'\nimport type { FileId } from '../types/ids.ts'\nimport { DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\n\n/** Options for downloading a file using concurrent byte-range requests. */\nexport interface ParallelDownloadOptions {\n  /** ID of the file to download. */\n  readonly fileId: FileId\n  /** Total file size in bytes (must be known in advance). */\n  readonly totalSize: number\n  /** Size of each ranged chunk in bytes. Defaults to 10 MB. */\n  readonly rangeSize?: number\n  /** Maximum number of chunks fetched in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /** Maximum retry attempts per range on transient failures. Defaults to 5. */\n  readonly maxRetries?: number\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Creates a readable stream that downloads a file using parallel byte-range requests.\n *\n * The file is split into fixed-size ranges fetched in a **sliding\n * window** keyed off the consumer's read pace. The window size is\n * `concurrency * 2`: up to `concurrency` ranges are in flight at once,\n * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered\n * ahead of the read head. New fetches kick off only when the consumer\n * reads a chunk, so a slow downstream pipe (e.g. a saturated network\n * sink or a `pipeTo` consumer that drains slowly) backpressures into\n * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.\n *\n * The previous eager implementation scheduled every range into\n * `Promise.all` up front; a slow head-of-line range could hold the\n * entire file in memory while later ranges finished and waited.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param options - Parallel download parameters (file ID, size, concurrency).\n *\n * @returns A `ReadableStream` that yields file bytes in order.\n */\nexport function createParallelDownloadStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: ParallelDownloadOptions,\n): ReadableStream<Uint8Array> {\n  const rangeSize = options.rangeSize ?? 10 * 1024 * 1024\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const totalSize = options.totalSize\n  // `maxRetries` is part of `DEFAULT_RETRY_OPTIONS`; only override when\n  // the caller supplied an explicit value so the shared default stays\n  // the single source of truth.\n  const retryOptions = {\n    ...DEFAULT_RETRY_OPTIONS,\n    ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),\n  }\n  const abort = options.signal\n\n  const ranges = planRanges(totalSize, rangeSize)\n\n  // `inflight` holds currently-fetching range promises; `buffer` holds\n  // completed ranges waiting for their slot in the emit order. Total\n  // scheduled-but-not-emitted = inflight.size + buffer.size is capped\n  // at `windowSize`, so peak memory is bounded regardless of any\n  // single range's latency.\n  const windowSize = concurrency * 2\n  const inflight = new Map<number, Promise<void>>()\n  const buffer = new Map<number, Uint8Array>()\n  let nextToSchedule = 0\n  let nextToEmit = 0\n  let firstError: unknown = null\n\n  function scheduleNext(): void {\n    while (\n      firstError === null &&\n      // Honour abort here so a completed range that triggers a top-up\n      // doesn't queue one final fetch after the caller aborted. Without\n      // this gate, one extra range request fires post-abort before the\n      // `pull()` loop notices.\n      abort?.aborted !== true &&\n      nextToSchedule < ranges.length &&\n      inflight.size + buffer.size < windowSize\n    ) {\n      const range = ranges[nextToSchedule]\n      if (range === undefined) break\n      const idx = nextToSchedule\n      nextToSchedule++\n      const task = (async () => {\n        try {\n          const data = await fetchRangeWithRetry(\n            raw,\n            accountInfo,\n            options.fileId,\n            range.start,\n            range.end,\n            retryOptions,\n            abort,\n          )\n          buffer.set(idx, data)\n        } catch (err) {\n          if (firstError === null) firstError = err\n        } finally {\n          inflight.delete(idx)\n        }\n      })()\n      inflight.set(idx, task)\n    }\n  }\n\n  return new ReadableStream<Uint8Array>({\n    start(controller) {\n      // Pre-warm: kick off the initial window so the first `pull` has\n      // something to await. An already-aborted signal surfaces as a\n      // stream error rather than a synchronous throw, matching the\n      // contract callers had with the previous eager implementation.\n      try {\n        abort?.throwIfAborted()\n        scheduleNext()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    async pull(controller) {\n      try {\n        // Wait until the next in-order chunk is available.\n        while (!buffer.has(nextToEmit)) {\n          abort?.throwIfAborted()\n          if (firstError !== null) throw firstError\n          /* v8 ignore start -- defensive close: every code path that\n             populates `nextToEmit < ranges.length` also schedules into\n             `inflight`. The pre-warm in `start()` plus `scheduleNext()`\n             after each enqueue guarantee that whenever there are\n             pending ranges, at least one is in flight. This guard\n             exists only so a future refactor can't accidentally stall\n             the stream by leaving both maps empty mid-stream. */\n          if (inflight.size === 0) {\n            controller.close()\n            return\n          }\n          /* v8 ignore stop */\n          await Promise.race(inflight.values())\n        }\n\n        const data = buffer.get(nextToEmit)\n        if (data !== undefined) {\n          buffer.delete(nextToEmit)\n          nextToEmit++\n          controller.enqueue(data)\n        }\n\n        // Top up the window now that we freed a slot by emitting.\n        scheduleNext()\n\n        if (\n          nextToEmit >= ranges.length &&\n          buffer.size === 0 &&\n          inflight.size === 0 &&\n          firstError === null\n        ) {\n          controller.close()\n        }\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel() {\n      // Abort propagation handles in-flight requests; just drop buffered\n      // data so it can be GC'd promptly.\n      buffer.clear()\n    },\n  })\n}\n\n/**\n * Fetches a single byte range with bounded retry on transient failures.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param fileId - ID of the file being downloaded.\n * @param start - Inclusive byte offset where the range begins.\n * @param end - Inclusive byte offset where the range ends.\n * @param retryOptions - Retry settings controlling attempts and backoff.\n * @param signal - Optional abort signal that cancels the range and any pending retry.\n *\n * @returns The range's bytes, or throws after exhausting all retry attempts.\n */\nasync function fetchRangeWithRetry(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: FileId,\n  start: number,\n  end: number,\n  retryOptions: typeof DEFAULT_RETRY_OPTIONS,\n  signal: AbortSignal | undefined,\n): Promise<Uint8Array> {\n  let lastError: unknown\n  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {\n    if (attempt > 0) {\n      const delay = computeBackoff(attempt - 1, retryOptions)\n      await sleep(delay, signal)\n    }\n    try {\n      signal?.throwIfAborted()\n      const resp = await raw.downloadFileById(\n        accountInfo.getDownloadUrl(),\n        accountInfo.getAuthToken(),\n        fileId,\n        {\n          range: byteRangeHeader(start, end),\n          ...(signal !== undefined ? { signal } : {}),\n        },\n      )\n      if (!resp.body) throw new Error('Download chunk has no body')\n      return await collectStream(resp.body)\n    } catch (err) {\n      lastError = err\n      // Honour AbortSignal cancellation: don't retry past an abort.\n      if (signal?.aborted) throw err\n      if (err instanceof DOMException && err.name === 'AbortError') throw err\n    }\n  }\n  throw lastError instanceof Error ? lastError : new Error('Range download failed after retries')\n}\n"],"names":["DEFAULT_TRANSFER_CONCURRENCY","DEFAULT_RETRY_OPTIONS","planRanges","computeBackoff","sleep","byteRangeHeader","collectStream"],"mappings":"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"}

package/dist/download/parallel.d.cts

@@ -0,0 +1,42 @@
+import { AccountInfo } from '../auth/account-info.js';
+import { RawClient } from '../raw/index.js';
+import { FileId } from '../types/ids.js';
+/** Options for downloading a file using concurrent byte-range requests. */
+export interface ParallelDownloadOptions {
+    /** ID of the file to download. */
+    readonly fileId: FileId;
+    /** Total file size in bytes (must be known in advance). */
+    readonly totalSize: number;
+    /** Size of each ranged chunk in bytes. Defaults to 10 MB. */
+    readonly rangeSize?: number;
+    /** Maximum number of chunks fetched in parallel. Defaults to 4. */
+    readonly concurrency?: number;
+    /** Maximum retry attempts per range on transient failures. Defaults to 5. */
+    readonly maxRetries?: number;
+    /** Signal to abort the download. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Creates a readable stream that downloads a file using parallel byte-range requests.
+ *
+ * The file is split into fixed-size ranges fetched in a **sliding
+ * window** keyed off the consumer's read pace. The window size is
+ * `concurrency * 2`: up to `concurrency` ranges are in flight at once,
+ * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered
+ * ahead of the read head. New fetches kick off only when the consumer
+ * reads a chunk, so a slow downstream pipe (e.g. a saturated network
+ * sink or a `pipeTo` consumer that drains slowly) backpressures into
+ * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.
+ *
+ * The previous eager implementation scheduled every range into
+ * `Promise.all` up front; a slow head-of-line range could hold the
+ * entire file in memory while later ranges finished and waited.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param options - Parallel download parameters (file ID, size, concurrency).
+ *
+ * @returns A `ReadableStream` that yields file bytes in order.
+ */
+export declare function createParallelDownloadStream(raw: RawClient, accountInfo: AccountInfo, options: ParallelDownloadOptions): ReadableStream<Uint8Array>;
+//# sourceMappingURL=parallel.d.ts.map

package/dist/download/parallel.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/download/parallel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAI7C,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CAAC,UAAU,CAAC,CA8H5B"}

package/dist/download/parallel.d.ts

@@ -0,0 +1,42 @@
+import { AccountInfo } from '../auth/account-info.js';
+import { RawClient } from '../raw/index.js';
+import { FileId } from '../types/ids.js';
+/** Options for downloading a file using concurrent byte-range requests. */
+export interface ParallelDownloadOptions {
+    /** ID of the file to download. */
+    readonly fileId: FileId;
+    /** Total file size in bytes (must be known in advance). */
+    readonly totalSize: number;
+    /** Size of each ranged chunk in bytes. Defaults to 10 MB. */
+    readonly rangeSize?: number;
+    /** Maximum number of chunks fetched in parallel. Defaults to 4. */
+    readonly concurrency?: number;
+    /** Maximum retry attempts per range on transient failures. Defaults to 5. */
+    readonly maxRetries?: number;
+    /** Signal to abort the download. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Creates a readable stream that downloads a file using parallel byte-range requests.
+ *
+ * The file is split into fixed-size ranges fetched in a **sliding
+ * window** keyed off the consumer's read pace. The window size is
+ * `concurrency * 2`: up to `concurrency` ranges are in flight at once,
+ * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered
+ * ahead of the read head. New fetches kick off only when the consumer
+ * reads a chunk, so a slow downstream pipe (e.g. a saturated network
+ * sink or a `pipeTo` consumer that drains slowly) backpressures into
+ * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.
+ *
+ * The previous eager implementation scheduled every range into
+ * `Promise.all` up front; a slow head-of-line range could hold the
+ * entire file in memory while later ranges finished and waited.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state.
+ * @param options - Parallel download parameters (file ID, size, concurrency).
+ *
+ * @returns A `ReadableStream` that yields file bytes in order.
+ */
+export declare function createParallelDownloadStream(raw: RawClient, accountInfo: AccountInfo, options: ParallelDownloadOptions): ReadableStream<Uint8Array>;
+//# sourceMappingURL=parallel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../../src/download/parallel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAI7C,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CAAC,UAAU,CAAC,CA8H5B"}

package/dist/download/parallel.js

@@ -0,0 +1,122 @@
+import { DEFAULT_RETRY_OPTIONS, computeBackoff, sleep } from "../http/retry.js";
+import { collectStream } from "../streams/collect.js";
+import { DEFAULT_TRANSFER_CONCURRENCY } from "../util/defaults.js";
+import { planRanges, byteRangeHeader } from "../util/plan-ranges.js";
+function createParallelDownloadStream(raw, accountInfo, options) {
+  const rangeSize = options.rangeSize ?? 10 * 1024 * 1024;
+  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY;
+  const totalSize = options.totalSize;
+  const retryOptions = {
+    ...DEFAULT_RETRY_OPTIONS,
+    ...options.maxRetries !== void 0 ? { maxRetries: options.maxRetries } : {}
+  };
+  const abort = options.signal;
+  const ranges = planRanges(totalSize, rangeSize);
+  const windowSize = concurrency * 2;
+  const inflight = /* @__PURE__ */ new Map();
+  const buffer = /* @__PURE__ */ new Map();
+  let nextToSchedule = 0;
+  let nextToEmit = 0;
+  let firstError = null;
+  function scheduleNext() {
+    while (firstError === null && // Honour abort here so a completed range that triggers a top-up
+    // doesn't queue one final fetch after the caller aborted. Without
+    // this gate, one extra range request fires post-abort before the
+    // `pull()` loop notices.
+    abort?.aborted !== true && nextToSchedule < ranges.length && inflight.size + buffer.size < windowSize) {
+      const range = ranges[nextToSchedule];
+      if (range === void 0) break;
+      const idx = nextToSchedule;
+      nextToSchedule++;
+      const task = (async () => {
+        try {
+          const data = await fetchRangeWithRetry(
+            raw,
+            accountInfo,
+            options.fileId,
+            range.start,
+            range.end,
+            retryOptions,
+            abort
+          );
+          buffer.set(idx, data);
+        } catch (err) {
+          if (firstError === null) firstError = err;
+        } finally {
+          inflight.delete(idx);
+        }
+      })();
+      inflight.set(idx, task);
+    }
+  }
+  return new ReadableStream({
+    start(controller) {
+      try {
+        abort?.throwIfAborted();
+        scheduleNext();
+      } catch (err) {
+        controller.error(err);
+      }
+    },
+    async pull(controller) {
+      try {
+        while (!buffer.has(nextToEmit)) {
+          abort?.throwIfAborted();
+          if (firstError !== null) throw firstError;
+          if (inflight.size === 0) {
+            controller.close();
+            return;
+          }
+          await Promise.race(inflight.values());
+        }
+        const data = buffer.get(nextToEmit);
+        if (data !== void 0) {
+          buffer.delete(nextToEmit);
+          nextToEmit++;
+          controller.enqueue(data);
+        }
+        scheduleNext();
+        if (nextToEmit >= ranges.length && buffer.size === 0 && inflight.size === 0 && firstError === null) {
+          controller.close();
+        }
+      } catch (err) {
+        controller.error(err);
+      }
+    },
+    cancel() {
+      buffer.clear();
+    }
+  });
+}
+async function fetchRangeWithRetry(raw, accountInfo, fileId, start, end, retryOptions, signal) {
+  let lastError;
+  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {
+    if (attempt > 0) {
+      const delay = computeBackoff(attempt - 1, retryOptions);
+      await sleep(delay, signal);
+    }
+    try {
+      signal?.throwIfAborted();
+      const resp = await raw.downloadFileById(
+        accountInfo.getDownloadUrl(),
+        accountInfo.getAuthToken(),
+        fileId,
+        {
+          range: byteRangeHeader(start, end),
+          ...signal !== void 0 ? { signal } : {}
+        }
+      );
+      if (!resp.body) throw new Error("Download chunk has no body");
+      return await collectStream(resp.body);
+    } catch (err) {
+      lastError = err;
+      if (signal?.aborted) throw err;
+      if (err instanceof DOMException && err.name === "AbortError") throw err;
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Range download failed after retries");
+}
+export {
+  createParallelDownloadStream
+};
+//# sourceMappingURL=parallel.js.map

package/dist/download/parallel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.js","sources":["../../src/download/parallel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { DEFAULT_RETRY_OPTIONS, computeBackoff, sleep } from '../http/retry.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport { collectStream } from '../streams/collect.ts'\nimport type { FileId } from '../types/ids.ts'\nimport { DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { byteRangeHeader, planRanges } from '../util/plan-ranges.ts'\n\n/** Options for downloading a file using concurrent byte-range requests. */\nexport interface ParallelDownloadOptions {\n  /** ID of the file to download. */\n  readonly fileId: FileId\n  /** Total file size in bytes (must be known in advance). */\n  readonly totalSize: number\n  /** Size of each ranged chunk in bytes. Defaults to 10 MB. */\n  readonly rangeSize?: number\n  /** Maximum number of chunks fetched in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /** Maximum retry attempts per range on transient failures. Defaults to 5. */\n  readonly maxRetries?: number\n  /** Signal to abort the download. */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Creates a readable stream that downloads a file using parallel byte-range requests.\n *\n * The file is split into fixed-size ranges fetched in a **sliding\n * window** keyed off the consumer's read pace. The window size is\n * `concurrency * 2`: up to `concurrency` ranges are in flight at once,\n * plus up to `concurrency` completed-but-not-yet-emitted ranges buffered\n * ahead of the read head. New fetches kick off only when the consumer\n * reads a chunk, so a slow downstream pipe (e.g. a saturated network\n * sink or a `pipeTo` consumer that drains slowly) backpressures into\n * the SDK and bounds peak memory to `(concurrency * 2) * rangeSize`.\n *\n * The previous eager implementation scheduled every range into\n * `Promise.all` up front; a slow head-of-line range could hold the\n * entire file in memory while later ranges finished and waited.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param options - Parallel download parameters (file ID, size, concurrency).\n *\n * @returns A `ReadableStream` that yields file bytes in order.\n */\nexport function createParallelDownloadStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: ParallelDownloadOptions,\n): ReadableStream<Uint8Array> {\n  const rangeSize = options.rangeSize ?? 10 * 1024 * 1024\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const totalSize = options.totalSize\n  // `maxRetries` is part of `DEFAULT_RETRY_OPTIONS`; only override when\n  // the caller supplied an explicit value so the shared default stays\n  // the single source of truth.\n  const retryOptions = {\n    ...DEFAULT_RETRY_OPTIONS,\n    ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),\n  }\n  const abort = options.signal\n\n  const ranges = planRanges(totalSize, rangeSize)\n\n  // `inflight` holds currently-fetching range promises; `buffer` holds\n  // completed ranges waiting for their slot in the emit order. Total\n  // scheduled-but-not-emitted = inflight.size + buffer.size is capped\n  // at `windowSize`, so peak memory is bounded regardless of any\n  // single range's latency.\n  const windowSize = concurrency * 2\n  const inflight = new Map<number, Promise<void>>()\n  const buffer = new Map<number, Uint8Array>()\n  let nextToSchedule = 0\n  let nextToEmit = 0\n  let firstError: unknown = null\n\n  function scheduleNext(): void {\n    while (\n      firstError === null &&\n      // Honour abort here so a completed range that triggers a top-up\n      // doesn't queue one final fetch after the caller aborted. Without\n      // this gate, one extra range request fires post-abort before the\n      // `pull()` loop notices.\n      abort?.aborted !== true &&\n      nextToSchedule < ranges.length &&\n      inflight.size + buffer.size < windowSize\n    ) {\n      const range = ranges[nextToSchedule]\n      if (range === undefined) break\n      const idx = nextToSchedule\n      nextToSchedule++\n      const task = (async () => {\n        try {\n          const data = await fetchRangeWithRetry(\n            raw,\n            accountInfo,\n            options.fileId,\n            range.start,\n            range.end,\n            retryOptions,\n            abort,\n          )\n          buffer.set(idx, data)\n        } catch (err) {\n          if (firstError === null) firstError = err\n        } finally {\n          inflight.delete(idx)\n        }\n      })()\n      inflight.set(idx, task)\n    }\n  }\n\n  return new ReadableStream<Uint8Array>({\n    start(controller) {\n      // Pre-warm: kick off the initial window so the first `pull` has\n      // something to await. An already-aborted signal surfaces as a\n      // stream error rather than a synchronous throw, matching the\n      // contract callers had with the previous eager implementation.\n      try {\n        abort?.throwIfAborted()\n        scheduleNext()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    async pull(controller) {\n      try {\n        // Wait until the next in-order chunk is available.\n        while (!buffer.has(nextToEmit)) {\n          abort?.throwIfAborted()\n          if (firstError !== null) throw firstError\n          /* v8 ignore start -- defensive close: every code path that\n             populates `nextToEmit < ranges.length` also schedules into\n             `inflight`. The pre-warm in `start()` plus `scheduleNext()`\n             after each enqueue guarantee that whenever there are\n             pending ranges, at least one is in flight. This guard\n             exists only so a future refactor can't accidentally stall\n             the stream by leaving both maps empty mid-stream. */\n          if (inflight.size === 0) {\n            controller.close()\n            return\n          }\n          /* v8 ignore stop */\n          await Promise.race(inflight.values())\n        }\n\n        const data = buffer.get(nextToEmit)\n        if (data !== undefined) {\n          buffer.delete(nextToEmit)\n          nextToEmit++\n          controller.enqueue(data)\n        }\n\n        // Top up the window now that we freed a slot by emitting.\n        scheduleNext()\n\n        if (\n          nextToEmit >= ranges.length &&\n          buffer.size === 0 &&\n          inflight.size === 0 &&\n          firstError === null\n        ) {\n          controller.close()\n        }\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel() {\n      // Abort propagation handles in-flight requests; just drop buffered\n      // data so it can be GC'd promptly.\n      buffer.clear()\n    },\n  })\n}\n\n/**\n * Fetches a single byte range with bounded retry on transient failures.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param fileId - ID of the file being downloaded.\n * @param start - Inclusive byte offset where the range begins.\n * @param end - Inclusive byte offset where the range ends.\n * @param retryOptions - Retry settings controlling attempts and backoff.\n * @param signal - Optional abort signal that cancels the range and any pending retry.\n *\n * @returns The range's bytes, or throws after exhausting all retry attempts.\n */\nasync function fetchRangeWithRetry(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: FileId,\n  start: number,\n  end: number,\n  retryOptions: typeof DEFAULT_RETRY_OPTIONS,\n  signal: AbortSignal | undefined,\n): Promise<Uint8Array> {\n  let lastError: unknown\n  for (let attempt = 0; attempt <= retryOptions.maxRetries; attempt++) {\n    if (attempt > 0) {\n      const delay = computeBackoff(attempt - 1, retryOptions)\n      await sleep(delay, signal)\n    }\n    try {\n      signal?.throwIfAborted()\n      const resp = await raw.downloadFileById(\n        accountInfo.getDownloadUrl(),\n        accountInfo.getAuthToken(),\n        fileId,\n        {\n          range: byteRangeHeader(start, end),\n          ...(signal !== undefined ? { signal } : {}),\n        },\n      )\n      if (!resp.body) throw new Error('Download chunk has no body')\n      return await collectStream(resp.body)\n    } catch (err) {\n      lastError = err\n      // Honour AbortSignal cancellation: don't retry past an abort.\n      if (signal?.aborted) throw err\n      if (err instanceof DOMException && err.name === 'AbortError') throw err\n    }\n  }\n  throw lastError instanceof Error ? lastError : new Error('Range download failed after retries')\n}\n"],"names":[],"mappings":"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"}