@backblaze-labs/b2-sdk 0.1.0

package/dist/upload/concurrency.d.cts

@@ -0,0 +1,46 @@
+/**
+ * Bounded concurrency primitive.
+ *
+ * Limits the number of concurrent operations to a fixed maximum. Callers
+ * {@link acquire} a slot before starting work and {@link release} it when done.
+ * If all slots are taken, `acquire` returns a promise that resolves when a slot
+ * becomes available.
+ */
+export declare class Semaphore {
+    private readonly limit;
+    private current;
+    private readonly queue;
+    /**
+     * @param limit - Maximum number of concurrent acquisitions. Must be a
+     *   positive integer; values `<= 0` would create a semaphore that
+     *   never lets anything through (all `acquire()` calls would queue
+     *   forever), so the constructor throws fast instead.
+     *
+     * @throws `RangeError` when `limit` is not a positive integer.
+     */
+    constructor(limit: number);
+    /**
+     * Acquires a slot, waiting if the limit has been reached.
+     * @returns A promise that resolves when a slot is available.
+     */
+    acquire(): Promise<void>;
+    /** Releases a slot, unblocking the next queued caller if any. */
+    release(): void;
+    /**
+     * Number of slots currently available.
+     *
+     * @returns The count of free concurrency slots.
+     */
+    get available(): number;
+}
+/**
+ * Maps over an array with bounded concurrency.
+ *
+ * @param items - Input items to process.
+ * @param concurrency - Maximum number of items processed in parallel.
+ * @param fn - Async function applied to each item.
+ *
+ * @returns Results in the same order as the input items.
+ */
+export declare function mapConcurrent<T, R>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/upload/concurrency.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/upload/concurrency.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,SAAS;IAYR,OAAO,CAAC,QAAQ,CAAC,KAAK;IAXlC,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C;;;;;;;OAOG;gBAC0B,KAAK,EAAE,MAAM;IAQ1C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,iEAAiE;IACjE,OAAO,IAAI,IAAI;IASf;;;;OAIG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,EACtC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAad"}

package/dist/upload/concurrency.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Bounded concurrency primitive.
+ *
+ * Limits the number of concurrent operations to a fixed maximum. Callers
+ * {@link acquire} a slot before starting work and {@link release} it when done.
+ * If all slots are taken, `acquire` returns a promise that resolves when a slot
+ * becomes available.
+ */
+export declare class Semaphore {
+    private readonly limit;
+    private current;
+    private readonly queue;
+    /**
+     * @param limit - Maximum number of concurrent acquisitions. Must be a
+     *   positive integer; values `<= 0` would create a semaphore that
+     *   never lets anything through (all `acquire()` calls would queue
+     *   forever), so the constructor throws fast instead.
+     *
+     * @throws `RangeError` when `limit` is not a positive integer.
+     */
+    constructor(limit: number);
+    /**
+     * Acquires a slot, waiting if the limit has been reached.
+     * @returns A promise that resolves when a slot is available.
+     */
+    acquire(): Promise<void>;
+    /** Releases a slot, unblocking the next queued caller if any. */
+    release(): void;
+    /**
+     * Number of slots currently available.
+     *
+     * @returns The count of free concurrency slots.
+     */
+    get available(): number;
+}
+/**
+ * Maps over an array with bounded concurrency.
+ *
+ * @param items - Input items to process.
+ * @param concurrency - Maximum number of items processed in parallel.
+ * @param fn - Async function applied to each item.
+ *
+ * @returns Results in the same order as the input items.
+ */
+export declare function mapConcurrent<T, R>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/upload/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/upload/concurrency.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,SAAS;IAYR,OAAO,CAAC,QAAQ,CAAC,KAAK;IAXlC,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C;;;;;;;OAOG;gBAC0B,KAAK,EAAE,MAAM;IAQ1C;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,iEAAiE;IACjE,OAAO,IAAI,IAAI;IASf;;;;OAIG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,EACtC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAad"}

package/dist/upload/concurrency.js

@@ -0,0 +1,54 @@
+class Semaphore {
+  /**
+   * @param limit - Maximum number of concurrent acquisitions. Must be a
+   *   positive integer; values `<= 0` would create a semaphore that
+   *   never lets anything through (all `acquire()` calls would queue
+   *   forever), so the constructor throws fast instead.
+   *
+   * @throws `RangeError` when `limit` is not a positive integer.
+   */
+  constructor(limit) {
+    this.limit = limit;
+    if (!Number.isInteger(limit) || limit <= 0) {
+      throw new RangeError(
+        `Semaphore limit must be a positive integer; received ${limit}. A non-positive limit produces a deadlocked semaphore — fail fast at construction instead.`
+      );
+    }
+  }
+  current = 0;
+  queue = [];
+  /**
+   * Acquires a slot, waiting if the limit has been reached.
+   * @returns A promise that resolves when a slot is available.
+   */
+  async acquire() {
+    if (this.current < this.limit) {
+      this.current++;
+      return;
+    }
+    return new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+  /** Releases a slot, unblocking the next queued caller if any. */
+  release() {
+    const next = this.queue.shift();
+    if (next) {
+      next();
+    } else {
+      this.current--;
+    }
+  }
+  /**
+   * Number of slots currently available.
+   *
+   * @returns The count of free concurrency slots.
+   */
+  get available() {
+    return this.limit - this.current;
+  }
+}
+export {
+  Semaphore
+};
+//# sourceMappingURL=concurrency.js.map

package/dist/upload/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sources":["../../src/upload/concurrency.ts"],"sourcesContent":["/**\n * Bounded concurrency primitive.\n *\n * Limits the number of concurrent operations to a fixed maximum. Callers\n * {@link acquire} a slot before starting work and {@link release} it when done.\n * If all slots are taken, `acquire` returns a promise that resolves when a slot\n * becomes available.\n */\nexport class Semaphore {\n  private current = 0\n  private readonly queue: (() => void)[] = []\n\n  /**\n   * @param limit - Maximum number of concurrent acquisitions. Must be a\n   *   positive integer; values `<= 0` would create a semaphore that\n   *   never lets anything through (all `acquire()` calls would queue\n   *   forever), so the constructor throws fast instead.\n   *\n   * @throws `RangeError` when `limit` is not a positive integer.\n   */\n  constructor(private readonly limit: number) {\n    if (!Number.isInteger(limit) || limit <= 0) {\n      throw new RangeError(\n        `Semaphore limit must be a positive integer; received ${limit}. A non-positive limit produces a deadlocked semaphore — fail fast at construction instead.`,\n      )\n    }\n  }\n\n  /**\n   * Acquires a slot, waiting if the limit has been reached.\n   * @returns A promise that resolves when a slot is available.\n   */\n  async acquire(): Promise<void> {\n    if (this.current < this.limit) {\n      this.current++\n      return\n    }\n    return new Promise<void>((resolve) => {\n      this.queue.push(resolve)\n    })\n  }\n\n  /** Releases a slot, unblocking the next queued caller if any. */\n  release(): void {\n    const next = this.queue.shift()\n    if (next) {\n      next()\n    } else {\n      this.current--\n    }\n  }\n\n  /**\n   * Number of slots currently available.\n   *\n   * @returns The count of free concurrency slots.\n   */\n  get available(): number {\n    return this.limit - this.current\n  }\n}\n\n/**\n * Maps over an array with bounded concurrency.\n *\n * @param items - Input items to process.\n * @param concurrency - Maximum number of items processed in parallel.\n * @param fn - Async function applied to each item.\n *\n * @returns Results in the same order as the input items.\n */\nexport async function mapConcurrent<T, R>(\n  items: readonly T[],\n  concurrency: number,\n  fn: (item: T, index: number) => Promise<R>,\n): Promise<R[]> {\n  const sem = new Semaphore(concurrency)\n  const results: R[] = new Array(items.length)\n  const tasks = items.map(async (item, i) => {\n    await sem.acquire()\n    try {\n      results[i] = await fn(item, i)\n    } finally {\n      sem.release()\n    }\n  })\n  await Promise.all(tasks)\n  return results\n}\n"],"names":[],"mappings":"AAQO,MAAM,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYrB,YAA6B,OAAe;AAAf,SAAA,QAAA;AAC3B,QAAI,CAAC,OAAO,UAAU,KAAK,KAAK,SAAS,GAAG;AAC1C,YAAM,IAAI;AAAA,QACR,wDAAwD,KAAK;AAAA,MAAA;AAAA,IAEjE;AAAA,EACF;AAAA,EAjBQ,UAAU;AAAA,EACD,QAAwB,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBzC,MAAM,UAAyB;AAC7B,QAAI,KAAK,UAAU,KAAK,OAAO;AAC7B,WAAK;AACL;AAAA,IACF;AACA,WAAO,IAAI,QAAc,CAAC,YAAY;AACpC,WAAK,MAAM,KAAK,OAAO;AAAA,IACzB,CAAC;AAAA,EACH;AAAA;AAAA,EAGA,UAAgB;AACd,UAAM,OAAO,KAAK,MAAM,MAAA;AACxB,QAAI,MAAM;AACR,WAAA;AAAA,IACF,OAAO;AACL,WAAK;AAAA,IACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,YAAoB;AACtB,WAAO,KAAK,QAAQ,KAAK;AAAA,EAC3B;AACF;"}

package/dist/upload/large.cjs

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const hash = require("../streams/hash.cjs");
+const progress = require("../streams/progress.cjs");
+const defaults = require("../util/defaults.cjs");
+const planRanges = require("../util/plan-ranges.cjs");
+const cancel = require("./cancel.cjs");
+const concurrency = require("./concurrency.cjs");
+const resume = require("./resume.cjs");
+async function uploadLargeFile(raw, accountInfo, options) {
+  const recommendedPartSize = accountInfo.getRecommendedPartSize();
+  const minPartSize = accountInfo.getAbsoluteMinimumPartSize();
+  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize);
+  const concurrency$1 = options.concurrency ?? defaults.DEFAULT_TRANSFER_CONCURRENCY;
+  const totalSize = options.source.size;
+  const parts = planRanges.planRanges(totalSize, partSize);
+  const fileInfo = { ...options.fileInfo };
+  const startLargeFileRequest = {
+    bucketId: options.bucketId,
+    fileName: options.fileName,
+    contentType: options.contentType ?? defaults.DEFAULT_CONTENT_TYPE,
+    fileInfo,
+    ...options.serverSideEncryption !== void 0 ? { serverSideEncryption: options.serverSideEncryption } : {},
+    ...options.fileRetention !== void 0 ? { fileRetention: options.fileRetention } : {},
+    ...options.legalHold !== void 0 ? { legalHold: options.legalHold } : {}
+  };
+  let largeFileId;
+  let preUploaded;
+  if (options.resumeFileId !== void 0) {
+    largeFileId = options.resumeFileId;
+    preUploaded = await resume.collectPartSha1s(raw, accountInfo, largeFileId);
+  } else if (options.resume === true) {
+    const candidate = await resume.findResumeCandidate(
+      raw,
+      accountInfo,
+      options.bucketId,
+      options.fileName
+    );
+    if (candidate) {
+      largeFileId = candidate.fileId;
+      preUploaded = candidate.uploadedPartSha1s;
+    } else {
+      const startResp = await raw.startLargeFile(
+        accountInfo.getApiUrl(),
+        accountInfo.getAuthToken(),
+        startLargeFileRequest
+      );
+      largeFileId = startResp.fileId;
+      preUploaded = /* @__PURE__ */ new Map();
+    }
+  } else {
+    const startResp = await raw.startLargeFile(
+      accountInfo.getApiUrl(),
+      accountInfo.getAuthToken(),
+      startLargeFileRequest
+    );
+    largeFileId = startResp.fileId;
+    preUploaded = /* @__PURE__ */ new Map();
+  }
+  const partSha1s = new Array(parts.length);
+  const tracker = new progress.ProgressTracker(options.onProgress, totalSize, parts.length);
+  const sem = new concurrency.Semaphore(concurrency$1);
+  if (!options.source.canSlice) {
+    if (options.resume === true || options.resumeFileId !== void 0) {
+      await cancel.cancelLargeFileBestEffort(raw, accountInfo, largeFileId);
+      throw new Error(
+        "uploadLargeFile: resume is not supported on non-sliceable sources (e.g. StreamSource)."
+      );
+    }
+    try {
+      await uploadPartsSequentially(
+        raw,
+        accountInfo,
+        options,
+        largeFileId,
+        parts,
+        partSha1s,
+        tracker
+      );
+      return await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+        fileId: largeFileId,
+        partSha1Array: partSha1s
+      });
+    } catch (err) {
+      await cancel.cancelLargeFileBestEffort(raw, accountInfo, largeFileId);
+      throw err;
+    }
+  }
+  try {
+    const tasks = parts.map(async (part) => {
+      await sem.acquire();
+      try {
+        options.signal?.throwIfAborted();
+        const partSource = options.source.slice(part.offset, part.offset + part.length);
+        const data = new Uint8Array(await partSource.toArrayBuffer());
+        const partSha1 = new hash.IncrementalSha1();
+        await partSha1.update(data);
+        const sha1Hex = await partSha1.digest();
+        const serverSha1 = preUploaded.get(part.partNumber);
+        if (serverSha1 !== void 0 && serverSha1 === sha1Hex) {
+          partSha1s[part.partNumber - 1] = serverSha1;
+          tracker.addBytes(data.byteLength);
+          tracker.completePart();
+          return;
+        }
+        let uploadEntry = accountInfo.checkoutPartUploadUrl(largeFileId);
+        if (!uploadEntry) {
+          const resp = await raw.getUploadPartUrl(
+            accountInfo.getApiUrl(),
+            accountInfo.getAuthToken(),
+            { fileId: largeFileId }
+          );
+          uploadEntry = { uploadUrl: resp.uploadUrl, authorizationToken: resp.authorizationToken };
+        }
+        try {
+          const result2 = await raw.uploadPart(
+            uploadEntry.uploadUrl,
+            {
+              authorization: uploadEntry.authorizationToken,
+              partNumber: part.partNumber,
+              contentLength: data.byteLength,
+              contentSha1: sha1Hex,
+              ...options.serverSideEncryption !== void 0 ? { serverSideEncryption: options.serverSideEncryption } : {}
+            },
+            data,
+            options.signal
+          );
+          accountInfo.returnPartUploadUrl(largeFileId, uploadEntry);
+          partSha1s[part.partNumber - 1] = result2.contentSha1;
+          tracker.addBytes(data.byteLength);
+          tracker.completePart();
+        } catch (err) {
+          accountInfo.evictPartUploadUrl(largeFileId, uploadEntry);
+          throw err;
+        }
+      } finally {
+        sem.release();
+      }
+    });
+    await Promise.all(tasks);
+    const result = await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+      fileId: largeFileId,
+      partSha1Array: partSha1s
+    });
+    return result;
+  } catch (err) {
+    await cancel.cancelLargeFileBestEffort(raw, accountInfo, largeFileId);
+    throw err;
+  }
+}
+async function uploadPartsSequentially(raw, accountInfo, options, largeFileId, parts, partSha1s, tracker) {
+  const reader = options.source.stream().getReader();
+  let partNumber = 1;
+  let carry = null;
+  try {
+    for (const planned of parts) {
+      options.signal?.throwIfAborted();
+      const buf = new Uint8Array(planned.length);
+      let filled = 0;
+      if (carry !== null) {
+        const take = Math.min(carry.byteLength, buf.byteLength - filled);
+        buf.set(carry.subarray(0, take), filled);
+        filled += take;
+        carry = take < carry.byteLength ? carry.subarray(take) : null;
+      }
+      while (filled < buf.byteLength) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const take = Math.min(value.byteLength, buf.byteLength - filled);
+        buf.set(value.subarray(0, take), filled);
+        filled += take;
+        if (take < value.byteLength) {
+          carry = value.subarray(take);
+        }
+      }
+      const data = filled === buf.byteLength ? buf : buf.subarray(0, filled);
+      if (data.byteLength === 0) {
+        throw new Error(
+          `uploadLargeFile: source stream ended before part ${partNumber}; advertised size does not match emitted bytes.`
+        );
+      }
+      const partSha1 = new hash.IncrementalSha1();
+      await partSha1.update(data);
+      const sha1Hex = await partSha1.digest();
+      let uploadEntry = accountInfo.checkoutPartUploadUrl(largeFileId);
+      if (!uploadEntry) {
+        const resp = await raw.getUploadPartUrl(
+          accountInfo.getApiUrl(),
+          accountInfo.getAuthToken(),
+          { fileId: largeFileId }
+        );
+        uploadEntry = { uploadUrl: resp.uploadUrl, authorizationToken: resp.authorizationToken };
+      }
+      try {
+        const result = await raw.uploadPart(
+          uploadEntry.uploadUrl,
+          {
+            authorization: uploadEntry.authorizationToken,
+            partNumber: planned.partNumber,
+            contentLength: data.byteLength,
+            contentSha1: sha1Hex,
+            ...options.serverSideEncryption !== void 0 ? { serverSideEncryption: options.serverSideEncryption } : {}
+          },
+          data,
+          options.signal
+        );
+        accountInfo.returnPartUploadUrl(largeFileId, uploadEntry);
+        partSha1s[planned.partNumber - 1] = result.contentSha1;
+        tracker.addBytes(data.byteLength);
+        tracker.completePart();
+      } catch (err) {
+        accountInfo.evictPartUploadUrl(largeFileId, uploadEntry);
+        throw err;
+      }
+      partNumber++;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+exports.uploadLargeFile = uploadLargeFile;
+//# sourceMappingURL=large.cjs.map

package/dist/upload/large.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"large.cjs","sources":["../../src/upload/large.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport type { ProgressListener } from '../streams/progress.ts'\nimport { ProgressTracker } from '../streams/progress.ts'\nimport type { ContentSource } from '../streams/source.ts'\nimport type { EncryptionSetting } from '../types/encryption.ts'\nimport type { FileVersion } from '../types/file.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\nimport type { FileRetentionValue, LegalHoldValue } from '../types/lock.ts'\nimport { DEFAULT_CONTENT_TYPE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { type RangePlan, planRanges } from '../util/plan-ranges.ts'\nimport { cancelLargeFileBestEffort } from './cancel.ts'\nimport { Semaphore } from './concurrency.ts'\nimport { collectPartSha1s, findResumeCandidate } from './resume.ts'\n\n/** Options for uploading a large file via the multipart protocol. */\nexport interface UploadLargeFileOptions {\n  /** Target bucket for the upload. */\n  readonly bucketId: BucketId\n  /** Full B2 file name including any path prefix. */\n  readonly fileName: string\n  /**\n   * Content to upload. Sliceable sources ({@link BufferSource},\n   * {@link BlobSource}) use the parallel-parts path. Non-sliceable\n   * sources ({@link StreamSource}) fall back to a sequential read path\n   * — one part at a time, concurrency forced to 1 — so callers can\n   * stream a multi-GB file without buffering the whole payload in\n   * memory. The `resume` / `resumeFileId` options require a sliceable\n   * source; they throw on a `StreamSource`.\n   */\n  readonly source: ContentSource\n  /** MIME type. Defaults to `b2/x-auto` for server-side detection. */\n  readonly contentType?: string\n  /** Custom file info key/value pairs stored with the file. */\n  readonly fileInfo?: Record<string, string>\n  /** Server-side encryption settings applied to each part. */\n  readonly serverSideEncryption?: EncryptionSetting\n  /** File retention policy applied at upload time. */\n  readonly fileRetention?: FileRetentionValue\n  /** Legal hold status applied at upload time. */\n  readonly legalHold?: LegalHoldValue\n  /** Size of each part in bytes. Defaults to the account's recommended part size. */\n  readonly partSize?: number\n  /** Maximum number of parts uploaded in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /** Callback invoked with upload progress updates. */\n  readonly onProgress?: ProgressListener\n  /** Signal to abort the upload. Triggers cancellation of the large file. */\n  readonly signal?: AbortSignal\n  /**\n   * If true, look for an unfinished large file with the same bucket and file name\n   * and skip parts whose locally-recomputed SHA-1 matches the server's.\n   */\n  readonly resume?: boolean\n  /**\n   * Explicit large file ID to resume into. Overrides {@link resume} discovery\n   * but the local `partSize` must still match the server's plan.\n   */\n  readonly resumeFileId?: LargeFileId\n}\n\n/**\n * Uploads a file using the B2 multipart (large file) protocol.\n *\n * The source is sliced into parts and uploaded concurrently via\n * `b2_upload_part`. This is appropriate for files larger than the recommended\n * part size. For smaller files, use {@link uploadSmallFile} which sends the\n * entire payload in a single request.\n *\n * On failure, the in-progress large file is cancelled on a best-effort basis.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state (tokens, URLs, upload URL pool).\n * @param options - Upload parameters including part size and concurrency.\n *\n * @returns The resulting {@link FileVersion} metadata.\n */\nexport async function uploadLargeFile(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: UploadLargeFileOptions,\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  const totalSize = options.source.size\n\n  const parts = planRanges(totalSize, partSize)\n  const fileInfo: Record<string, string> = { ...options.fileInfo }\n\n  // Construct the `b2_start_large_file` request body once so the two\n  // non-resume branches below (no `resume`, resume-but-no-candidate)\n  // can dispatch without re-spelling the conditional spreads.\n  const startLargeFileRequest = {\n    bucketId: options.bucketId,\n    fileName: options.fileName,\n    contentType: options.contentType ?? DEFAULT_CONTENT_TYPE,\n    fileInfo,\n    ...(options.serverSideEncryption !== undefined\n      ? { serverSideEncryption: options.serverSideEncryption }\n      : {}),\n    ...(options.fileRetention !== undefined ? { fileRetention: options.fileRetention } : {}),\n    ...(options.legalHold !== undefined ? { legalHold: options.legalHold } : {}),\n  }\n\n  // --- Resume discovery (M11.1) ---\n  let largeFileId: LargeFileId\n  let preUploaded: ReadonlyMap<number, string>\n\n  if (options.resumeFileId !== undefined) {\n    largeFileId = options.resumeFileId\n    preUploaded = await collectPartSha1s(raw, accountInfo, largeFileId)\n  } else if (options.resume === true) {\n    const candidate = await findResumeCandidate(\n      raw,\n      accountInfo,\n      options.bucketId,\n      options.fileName,\n    )\n    if (candidate) {\n      largeFileId = candidate.fileId\n      preUploaded = candidate.uploadedPartSha1s\n    } else {\n      const startResp = await raw.startLargeFile(\n        accountInfo.getApiUrl(),\n        accountInfo.getAuthToken(),\n        startLargeFileRequest,\n      )\n      largeFileId = startResp.fileId\n      preUploaded = new Map<number, string>()\n    }\n  } else {\n    const startResp = await raw.startLargeFile(\n      accountInfo.getApiUrl(),\n      accountInfo.getAuthToken(),\n      startLargeFileRequest,\n    )\n    largeFileId = startResp.fileId\n    preUploaded = new Map<number, string>()\n  }\n\n  const partSha1s: string[] = new Array(parts.length)\n  const tracker = new ProgressTracker(options.onProgress, totalSize, parts.length)\n  const sem = new Semaphore(concurrency)\n\n  // Non-sliceable sources (e.g. `StreamSource` wrapping a Node\n  // `Readable.toWeb`) can't be read in parallel — there's only one\n  // forward-only cursor. Resume is also impossible (no seek). Bail to a\n  // sequential read loop instead. Each part is buffered, hashed,\n  // shipped, then dropped before the next read starts, so the peak\n  // memory footprint is ~partSize bytes regardless of total file size.\n  if (!options.source.canSlice) {\n    if (options.resume === true || options.resumeFileId !== undefined) {\n      // Cancel the unfinished large file before throwing so the caller\n      // doesn't have to clean it up themselves.\n      await cancelLargeFileBestEffort(raw, accountInfo, largeFileId)\n      throw new Error(\n        'uploadLargeFile: resume is not supported on non-sliceable sources (e.g. StreamSource).',\n      )\n    }\n    try {\n      await uploadPartsSequentially(\n        raw,\n        accountInfo,\n        options,\n        largeFileId,\n        parts,\n        partSha1s,\n        tracker,\n      )\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\n  try {\n    const tasks = parts.map(async (part) => {\n      await sem.acquire()\n      try {\n        options.signal?.throwIfAborted()\n\n        const partSource = options.source.slice(part.offset, part.offset + part.length)\n        const data = new Uint8Array(await partSource.toArrayBuffer())\n\n        const partSha1 = new IncrementalSha1()\n        await partSha1.update(data)\n        const sha1Hex = await partSha1.digest()\n\n        // Resume short-circuit: server already has this part with matching SHA-1\n        const serverSha1 = preUploaded.get(part.partNumber)\n        if (serverSha1 !== undefined && serverSha1 === sha1Hex) {\n          partSha1s[part.partNumber - 1] = serverSha1\n          tracker.addBytes(data.byteLength)\n          tracker.completePart()\n          return\n        }\n\n        let uploadEntry = accountInfo.checkoutPartUploadUrl(largeFileId)\n        if (!uploadEntry) {\n          const resp = await raw.getUploadPartUrl(\n            accountInfo.getApiUrl(),\n            accountInfo.getAuthToken(),\n            { fileId: largeFileId },\n          )\n          uploadEntry = { uploadUrl: resp.uploadUrl, authorizationToken: resp.authorizationToken }\n        }\n\n        try {\n          const result = await raw.uploadPart(\n            uploadEntry.uploadUrl,\n            {\n              authorization: uploadEntry.authorizationToken,\n              partNumber: part.partNumber,\n              contentLength: data.byteLength,\n              contentSha1: sha1Hex,\n              ...(options.serverSideEncryption !== undefined\n                ? { serverSideEncryption: options.serverSideEncryption }\n                : {}),\n            },\n            data,\n            options.signal,\n          )\n\n          accountInfo.returnPartUploadUrl(largeFileId, uploadEntry)\n          partSha1s[part.partNumber - 1] = result.contentSha1\n          tracker.addBytes(data.byteLength)\n          tracker.completePart()\n        } catch (err) {\n          accountInfo.evictPartUploadUrl(largeFileId, uploadEntry)\n          throw err\n        }\n      } finally {\n        sem.release()\n      }\n    })\n\n    await Promise.all(tasks)\n\n    const result = await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n      fileId: largeFileId,\n      partSha1Array: partSha1s,\n    })\n\n    return result\n  } catch (err) {\n    await cancelLargeFileBestEffort(raw, accountInfo, largeFileId)\n    throw err\n  }\n}\n\n/**\n * Sequential upload path for non-sliceable sources (`StreamSource`).\n *\n * Reads the source's `stream()` once and accumulates exactly `partSize`\n * bytes into an in-memory buffer per iteration. Each filled buffer is\n * hashed, dispatched to `b2_upload_part`, then released before the next\n * part starts — so peak memory is ~partSize regardless of file size.\n *\n * Concurrency is forced to 1 here because the stream is a single\n * forward-only cursor; the engine can't read part N+1 until part N is\n * fully consumed.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param options - The original `uploadLargeFile` options.\n * @param largeFileId - ID of the in-progress large file (already started).\n * @param parts - Pre-planned part layout (used for part numbers + count).\n * @param partSha1s - Output array, written in-place at index `partNumber - 1`.\n * @param tracker - Progress tracker; bytes added per chunk, part completed\n *   each time a part finishes.\n */\nasync function uploadPartsSequentially(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: UploadLargeFileOptions,\n  largeFileId: LargeFileId,\n  parts: readonly RangePlan[],\n  partSha1s: string[],\n  tracker: ProgressTracker,\n): Promise<void> {\n  const reader = options.source.stream().getReader()\n  let partNumber = 1\n  // Carry-over bytes from a previous read when the read returned more\n  // than we needed to fill one part. Kept as an array to avoid an\n  // allocation per loop iteration on a typical multi-part upload.\n  let carry: Uint8Array | null = null\n\n  try {\n    for (const planned of parts) {\n      options.signal?.throwIfAborted()\n\n      const buf = new Uint8Array(planned.length)\n      let filled = 0\n\n      if (carry !== null) {\n        const take = Math.min(carry.byteLength, buf.byteLength - filled)\n        buf.set(carry.subarray(0, take), filled)\n        filled += take\n        carry = take < carry.byteLength ? carry.subarray(take) : null\n      }\n\n      while (filled < buf.byteLength) {\n        const { done, value } = await reader.read()\n        if (done) break\n        const take = Math.min(value.byteLength, buf.byteLength - filled)\n        buf.set(value.subarray(0, take), filled)\n        filled += take\n        if (take < value.byteLength) {\n          carry = value.subarray(take)\n        }\n      }\n\n      // For the LAST part the stream may run dry mid-buffer, leaving a\n      // shorter chunk. B2 accepts a final part smaller than `partSize`.\n      const data = filled === buf.byteLength ? buf : buf.subarray(0, filled)\n      /* v8 ignore start -- defensive: only fires when the source's advertised\n         size over-reports the actual emitted byte count, which a well-behaved\n         ContentSource implementation cannot do. Kept so callers feeding the\n         engine a buggy custom stream get an actionable error rather than a\n         B2 wire-level failure. */\n      if (data.byteLength === 0) {\n        throw new Error(\n          `uploadLargeFile: source stream ended before part ${partNumber}; advertised size does not match emitted bytes.`,\n        )\n      }\n      /* v8 ignore stop */\n\n      const partSha1 = new IncrementalSha1()\n      await partSha1.update(data)\n      const sha1Hex = await partSha1.digest()\n\n      let uploadEntry = accountInfo.checkoutPartUploadUrl(largeFileId)\n      if (!uploadEntry) {\n        const resp = await raw.getUploadPartUrl(\n          accountInfo.getApiUrl(),\n          accountInfo.getAuthToken(),\n          { fileId: largeFileId },\n        )\n        uploadEntry = { uploadUrl: resp.uploadUrl, authorizationToken: resp.authorizationToken }\n      }\n\n      try {\n        const result = await raw.uploadPart(\n          uploadEntry.uploadUrl,\n          {\n            authorization: uploadEntry.authorizationToken,\n            partNumber: planned.partNumber,\n            contentLength: data.byteLength,\n            contentSha1: sha1Hex,\n            ...(options.serverSideEncryption !== undefined\n              ? { serverSideEncryption: options.serverSideEncryption }\n              : {}),\n          },\n          data,\n          options.signal,\n        )\n\n        accountInfo.returnPartUploadUrl(largeFileId, uploadEntry)\n        partSha1s[planned.partNumber - 1] = result.contentSha1\n        tracker.addBytes(data.byteLength)\n        tracker.completePart()\n      } catch (err) {\n        accountInfo.evictPartUploadUrl(largeFileId, uploadEntry)\n        throw err\n      }\n\n      partNumber++\n    }\n  } finally {\n    // Releasing the lock lets the underlying stream propagate close /\n    // error events to any upstream producer (e.g. a Node `Readable`).\n    reader.releaseLock()\n  }\n}\n"],"names":["concurrency","DEFAULT_TRANSFER_CONCURRENCY","planRanges","DEFAULT_CONTENT_TYPE","collectPartSha1s","findResumeCandidate","ProgressTracker","Semaphore","cancelLargeFileBestEffort","IncrementalSha1","result"],"mappings":"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"}

package/dist/upload/large.d.cts

@@ -0,0 +1,71 @@
+import { AccountInfo } from '../auth/account-info.js';
+import { RawClient } from '../raw/index.js';
+import { ProgressListener } from '../streams/progress.js';
+import { ContentSource } from '../streams/source.js';
+import { EncryptionSetting } from '../types/encryption.js';
+import { FileVersion } from '../types/file.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+import { FileRetentionValue, LegalHoldValue } from '../types/lock.js';
+/** Options for uploading a large file via the multipart protocol. */
+export interface UploadLargeFileOptions {
+    /** Target bucket for the upload. */
+    readonly bucketId: BucketId;
+    /** Full B2 file name including any path prefix. */
+    readonly fileName: string;
+    /**
+     * Content to upload. Sliceable sources ({@link BufferSource},
+     * {@link BlobSource}) use the parallel-parts path. Non-sliceable
+     * sources ({@link StreamSource}) fall back to a sequential read path
+     * — one part at a time, concurrency forced to 1 — so callers can
+     * stream a multi-GB file without buffering the whole payload in
+     * memory. The `resume` / `resumeFileId` options require a sliceable
+     * source; they throw on a `StreamSource`.
+     */
+    readonly source: ContentSource;
+    /** MIME type. Defaults to `b2/x-auto` for server-side detection. */
+    readonly contentType?: string;
+    /** Custom file info key/value pairs stored with the file. */
+    readonly fileInfo?: Record<string, string>;
+    /** Server-side encryption settings applied to each part. */
+    readonly serverSideEncryption?: EncryptionSetting;
+    /** File retention policy applied at upload time. */
+    readonly fileRetention?: FileRetentionValue;
+    /** Legal hold status applied at upload time. */
+    readonly legalHold?: LegalHoldValue;
+    /** Size of each part in bytes. Defaults to the account's recommended part size. */
+    readonly partSize?: number;
+    /** Maximum number of parts uploaded in parallel. Defaults to 4. */
+    readonly concurrency?: number;
+    /** Callback invoked with upload progress updates. */
+    readonly onProgress?: ProgressListener;
+    /** Signal to abort the upload. Triggers cancellation of the large file. */
+    readonly signal?: AbortSignal;
+    /**
+     * If true, look for an unfinished large file with the same bucket and file name
+     * and skip parts whose locally-recomputed SHA-1 matches the server's.
+     */
+    readonly resume?: boolean;
+    /**
+     * Explicit large file ID to resume into. Overrides {@link resume} discovery
+     * but the local `partSize` must still match the server's plan.
+     */
+    readonly resumeFileId?: LargeFileId;
+}
+/**
+ * Uploads a file using the B2 multipart (large file) protocol.
+ *
+ * The source is sliced into parts and uploaded concurrently via
+ * `b2_upload_part`. This is appropriate for files larger than the recommended
+ * part size. For smaller files, use {@link uploadSmallFile} which sends the
+ * entire payload in a single request.
+ *
+ * On failure, the in-progress large file is cancelled on a best-effort basis.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state (tokens, URLs, upload URL pool).
+ * @param options - Upload parameters including part size and concurrency.
+ *
+ * @returns The resulting {@link FileVersion} metadata.
+ */
+export declare function uploadLargeFile(raw: RawClient, accountInfo: AccountInfo, options: UploadLargeFileOptions): Promise<FileVersion>;
+//# sourceMappingURL=large.d.ts.map

package/dist/upload/large.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"large.d.ts","sourceRoot":"","sources":["../../src/upload/large.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAO1E,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,iBAAiB,CAAA;IACjD,oDAAoD;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAA;IAC3C,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;IACnC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAA;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAA;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,WAAW,CAAC,CA6KtB"}

package/dist/upload/large.d.ts

@@ -0,0 +1,71 @@
+import { AccountInfo } from '../auth/account-info.js';
+import { RawClient } from '../raw/index.js';
+import { ProgressListener } from '../streams/progress.js';
+import { ContentSource } from '../streams/source.js';
+import { EncryptionSetting } from '../types/encryption.js';
+import { FileVersion } from '../types/file.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+import { FileRetentionValue, LegalHoldValue } from '../types/lock.js';
+/** Options for uploading a large file via the multipart protocol. */
+export interface UploadLargeFileOptions {
+    /** Target bucket for the upload. */
+    readonly bucketId: BucketId;
+    /** Full B2 file name including any path prefix. */
+    readonly fileName: string;
+    /**
+     * Content to upload. Sliceable sources ({@link BufferSource},
+     * {@link BlobSource}) use the parallel-parts path. Non-sliceable
+     * sources ({@link StreamSource}) fall back to a sequential read path
+     * — one part at a time, concurrency forced to 1 — so callers can
+     * stream a multi-GB file without buffering the whole payload in
+     * memory. The `resume` / `resumeFileId` options require a sliceable
+     * source; they throw on a `StreamSource`.
+     */
+    readonly source: ContentSource;
+    /** MIME type. Defaults to `b2/x-auto` for server-side detection. */
+    readonly contentType?: string;
+    /** Custom file info key/value pairs stored with the file. */
+    readonly fileInfo?: Record<string, string>;
+    /** Server-side encryption settings applied to each part. */
+    readonly serverSideEncryption?: EncryptionSetting;
+    /** File retention policy applied at upload time. */
+    readonly fileRetention?: FileRetentionValue;
+    /** Legal hold status applied at upload time. */
+    readonly legalHold?: LegalHoldValue;
+    /** Size of each part in bytes. Defaults to the account's recommended part size. */
+    readonly partSize?: number;
+    /** Maximum number of parts uploaded in parallel. Defaults to 4. */
+    readonly concurrency?: number;
+    /** Callback invoked with upload progress updates. */
+    readonly onProgress?: ProgressListener;
+    /** Signal to abort the upload. Triggers cancellation of the large file. */
+    readonly signal?: AbortSignal;
+    /**
+     * If true, look for an unfinished large file with the same bucket and file name
+     * and skip parts whose locally-recomputed SHA-1 matches the server's.
+     */
+    readonly resume?: boolean;
+    /**
+     * Explicit large file ID to resume into. Overrides {@link resume} discovery
+     * but the local `partSize` must still match the server's plan.
+     */
+    readonly resumeFileId?: LargeFileId;
+}
+/**
+ * Uploads a file using the B2 multipart (large file) protocol.
+ *
+ * The source is sliced into parts and uploaded concurrently via
+ * `b2_upload_part`. This is appropriate for files larger than the recommended
+ * part size. For smaller files, use {@link uploadSmallFile} which sends the
+ * entire payload in a single request.
+ *
+ * On failure, the in-progress large file is cancelled on a best-effort basis.
+ *
+ * @param raw - Low-level B2 API client.
+ * @param accountInfo - Authorized account state (tokens, URLs, upload URL pool).
+ * @param options - Upload parameters including part size and concurrency.
+ *
+ * @returns The resulting {@link FileVersion} metadata.
+ */
+export declare function uploadLargeFile(raw: RawClient, accountInfo: AccountInfo, options: UploadLargeFileOptions): Promise<FileVersion>;
+//# sourceMappingURL=large.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"large.d.ts","sourceRoot":"","sources":["../../src/upload/large.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAO1E,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,iBAAiB,CAAA;IACjD,oDAAoD;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,kBAAkB,CAAA;IAC3C,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;IACnC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAA;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAA;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,WAAW,CAAC,CA6KtB"}