@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/upload/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","sources":["../../src/upload/stream.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 { EncryptionSetting } from '../types/encryption.ts'\nimport type { FileVersion } from '../types/file.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\nimport { DEFAULT_CONTENT_TYPE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { toError } from '../util/to-error.ts'\nimport { cancelLargeFileBestEffort } from './cancel.ts'\nimport { Semaphore } from './concurrency.ts'\n\n/** Options for creating a streaming multipart upload sink. */\nexport interface CreateWriteStreamOptions {\n  /** Target bucket for the upload. */\n  readonly bucketId: BucketId\n  /** Destination file name in the bucket. */\n  readonly fileName: string\n  /** MIME type. Defaults to `b2/x-auto`. */\n  readonly contentType?: string\n  /** Custom file info stored with the file. */\n  readonly fileInfo?: Record<string, string>\n  /** Server-side encryption applied to each part. */\n  readonly serverSideEncryption?: EncryptionSetting\n  /**\n   * Target part size in bytes. The stream buffers writes until this many bytes\n   * are accumulated, then ships a part. Must be at least the account's\n   * absolute minimum part size; the implementation will raise it if too small.\n   */\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 events. `totalBytes` is `null` (size unknown). */\n  readonly onProgress?: ProgressListener\n  /** Aborts the upload and cancels the unfinished large file. */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Handle returned by `B2Object.createWriteStream`: the Web `WritableStream` to\n * pipe data into, plus a promise that resolves with the finished\n * {@link FileVersion} once the stream is closed and all parts have been\n * uploaded.\n */\nexport interface UploadWriteHandle {\n  /** Web `WritableStream` sink to pipe data into. */\n  readonly writable: WritableStream<Uint8Array>\n  /** Resolves with the finalized file version when the stream closes successfully. */\n  readonly done: Promise<FileVersion>\n}\n\n/**\n * Creates a {@link WritableStream} that streams data into a B2 multipart upload.\n *\n * Buffers incoming chunks until `partSize` bytes are accumulated, ships each\n * complete part through the standard multipart engine, and finalizes the file\n * once the stream is closed. Honours backpressure via the queue's bounded\n * concurrency. Streaming uploads do not support resume because the total size\n * and per-part hashes aren't known in advance; use {@link uploadLargeFile} with\n * a buffered source when resume is required.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state (tokens, URLs, part URL pool).\n * @param options - Streaming upload parameters.\n *\n * @returns A {@link UploadWriteHandle} with the writable sink and a completion promise.\n */\nexport function createWriteStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: CreateWriteStreamOptions,\n): UploadWriteHandle {\n  const minPartSize = accountInfo.getAbsoluteMinimumPartSize()\n  const recommendedPartSize = accountInfo.getRecommendedPartSize()\n  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize)\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const tracker = new ProgressTracker(options.onProgress, null, null)\n  const sem = new Semaphore(concurrency)\n\n  let largeFileId: LargeFileId | null = null\n  let startPromise: Promise<LargeFileId> | null = null\n  let nextPartNumber = 1\n  let pendingBytes = 0\n  const pending: Uint8Array[] = []\n  const partSha1s: string[] = []\n  const inflight: Promise<void>[] = []\n  let errored: Error | null = null\n\n  // ES2024 `Promise.withResolvers()` exposes the resolve/reject pair as\n  // properties of the returned object, avoiding the `let resolve!:` /\n  // `let reject!:` non-null-assertion pattern needed before this API\n  // existed. Available in Node 22 (our minimum), Bun, Deno, modern\n  // browsers, and Cloudflare Workers.\n  const {\n    promise: done,\n    resolve: resolveDone,\n    reject: rejectDone,\n  } = Promise.withResolvers<FileVersion>()\n  // Attach a no-op rejection handler so a `done` that rejects before the\n  // caller observes it never surfaces as a process-level unhandled rejection.\n  // The error is not swallowed: `close()`/`abort()` also reject the writable\n  // (so `pipeTo`/`getWriter().close()` throw), and any later `await done` /\n  // `done.then(onRejected)` the caller attaches still sees the rejection —\n  // extra handlers on the same promise all fire. Mirrors the\n  // `task.catch(() => {})` pattern used for inflight part uploads below, and\n  // keeps the engine well-behaved under Bun and Node's strict\n  // unhandled-rejection mode.\n  done.catch(() => {})\n\n  function ensureStarted(): Promise<LargeFileId> {\n    if (largeFileId !== null) return Promise.resolve(largeFileId)\n    if (startPromise !== null) return startPromise\n    startPromise = (async () => {\n      const resp = await raw.startLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n        bucketId: options.bucketId,\n        fileName: options.fileName,\n        contentType: options.contentType ?? DEFAULT_CONTENT_TYPE,\n        fileInfo: options.fileInfo ?? {},\n        ...(options.serverSideEncryption !== undefined\n          ? { serverSideEncryption: options.serverSideEncryption }\n          : {}),\n      })\n      largeFileId = resp.fileId\n      return largeFileId\n    })()\n    return startPromise\n  }\n\n  async function shipPart(data: Uint8Array, partNumber: number): Promise<void> {\n    const fileId = await ensureStarted()\n\n    const sha1 = new IncrementalSha1()\n    await sha1.update(data)\n    const sha1Hex = await sha1.digest()\n\n    let uploadEntry = accountInfo.checkoutPartUploadUrl(fileId)\n    if (!uploadEntry) {\n      const resp = await raw.getUploadPartUrl(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n        fileId,\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,\n          contentLength: data.byteLength,\n          contentSha1: sha1Hex,\n          ...(options.serverSideEncryption !== undefined\n            ? { serverSideEncryption: options.serverSideEncryption }\n            : {}),\n        },\n        data as BodyInit,\n        options.signal,\n      )\n      accountInfo.returnPartUploadUrl(fileId, uploadEntry)\n      partSha1s[partNumber - 1] = result.contentSha1\n      tracker.addBytes(data.byteLength)\n      tracker.completePart()\n    } catch (err) {\n      accountInfo.evictPartUploadUrl(fileId, uploadEntry)\n      throw err\n    }\n  }\n\n  function dispatchPart(): void {\n    if (pending.length === 0) return\n    let data: Uint8Array\n    if (pending.length === 1) {\n      const head = pending[0]\n      if (!head) return\n      data = head\n    } else {\n      const total = pending.reduce((sum, chunk) => sum + chunk.byteLength, 0)\n      data = new Uint8Array(total)\n      let offset = 0\n      for (const chunk of pending) {\n        data.set(chunk, offset)\n        offset += chunk.byteLength\n      }\n    }\n    pending.length = 0\n    pendingBytes = 0\n    const partNumber = nextPartNumber++\n    const task = (async () => {\n      await sem.acquire()\n      try {\n        await shipPart(data, partNumber)\n      } catch (err) {\n        errored = toError(err)\n        throw err\n      } finally {\n        sem.release()\n      }\n    })()\n    inflight.push(task)\n    // Swallow rejection here; we check `errored` later.\n    task.catch(() => {})\n  }\n\n  const writable = new WritableStream<Uint8Array>({\n    async write(chunk: Uint8Array): Promise<void> {\n      if (errored) throw errored\n      options.signal?.throwIfAborted()\n\n      pending.push(chunk)\n      pendingBytes += chunk.byteLength\n      while (pendingBytes >= partSize) {\n        // Pull exactly partSize bytes off the front\n        const carved = carveExact(pending, partSize)\n        const partNumber = nextPartNumber++\n        pendingBytes -= partSize\n        const task = (async () => {\n          await sem.acquire()\n          try {\n            await shipPart(carved, partNumber)\n          } catch (err) {\n            errored = toError(err)\n            throw err\n          } finally {\n            sem.release()\n          }\n        })()\n        inflight.push(task)\n        task.catch(() => {})\n      }\n    },\n\n    async close(): Promise<void> {\n      try {\n        if (errored) throw errored\n        options.signal?.throwIfAborted()\n\n        // Ship any remaining bytes as the last part. If the total fit in one\n        // single buffered batch (no parts shipped yet), we have to use the\n        // multipart path anyway since we already called startLargeFile lazily.\n        if (pendingBytes > 0) {\n          dispatchPart()\n        }\n\n        await Promise.all(inflight)\n        if (errored) throw errored\n\n        if (largeFileId === null) {\n          // Stream closed before any data was written. Start an empty large\n          // file? B2 requires at least 2 parts. Reject — callers shouldn't\n          // close an empty stream.\n          throw new Error('createWriteStream closed without any data written.')\n        }\n\n        const result = await raw.finishLargeFile(\n          accountInfo.getApiUrl(),\n          accountInfo.getAuthToken(),\n          { fileId: largeFileId, partSha1Array: partSha1s },\n        )\n        resolveDone(result)\n      } catch (err) {\n        // Capture into a const so the cancel closure sees a non-null\n        // `fileId`; closures don't observe the outer `!== null` narrowing\n        // because the variable is mutable across the lambda boundary.\n        const fileIdToCancel = largeFileId\n        if (fileIdToCancel !== null) {\n          await cancelLargeFileBestEffort(raw, accountInfo, fileIdToCancel)\n        }\n        rejectDone(err)\n        throw err\n      }\n    },\n\n    async abort(reason: unknown): Promise<void> {\n      const fileIdToCancel = largeFileId\n      if (fileIdToCancel !== null) {\n        await cancelLargeFileBestEffort(raw, accountInfo, fileIdToCancel)\n      }\n      rejectDone(toError(reason))\n    },\n  })\n\n  return { writable, done }\n}\n\n/**\n * Removes exactly `size` bytes from the front of `chunks` (mutates) and returns\n * them as a contiguous Uint8Array. Any trailing remainder of the last chunk\n * stays at the front of `chunks` for the next part.\n *\n * @param chunks - Queue of pending chunks. Modified in place.\n * @param size - Number of bytes to carve off the front.\n *\n * @returns A new Uint8Array containing exactly `size` bytes.\n */\nfunction carveExact(chunks: Uint8Array[], size: number): Uint8Array {\n  const out = new Uint8Array(size)\n  let written = 0\n  while (written < size && chunks.length > 0) {\n    const head = chunks[0]\n    if (!head) break\n    const need = size - written\n    if (head.byteLength <= need) {\n      out.set(head, written)\n      written += head.byteLength\n      chunks.shift()\n    } else {\n      out.set(head.subarray(0, need), written)\n      chunks[0] = head.subarray(need)\n      written += need\n    }\n  }\n  return out\n}\n"],"names":[],"mappings":";;;;;;AAoEO,SAAS,kBACd,KACA,aACA,SACmB;AACnB,QAAM,cAAc,YAAY,2BAAA;AAChC,QAAM,sBAAsB,YAAY,uBAAA;AACxC,QAAM,WAAW,KAAK,IAAI,QAAQ,YAAY,qBAAqB,WAAW;AAC9E,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,UAAU,IAAI,gBAAgB,QAAQ,YAAY,MAAM,IAAI;AAClE,QAAM,MAAM,IAAI,UAAU,WAAW;AAErC,MAAI,cAAkC;AACtC,MAAI,eAA4C;AAChD,MAAI,iBAAiB;AACrB,MAAI,eAAe;AACnB,QAAM,UAAwB,CAAA;AAC9B,QAAM,YAAsB,CAAA;AAC5B,QAAM,WAA4B,CAAA;AAClC,MAAI,UAAwB;AAO5B,QAAM;AAAA,IACJ,SAAS;AAAA,IACT,SAAS;AAAA,IACT,QAAQ;AAAA,EAAA,IACN,QAAQ,cAAA;AAUZ,OAAK,MAAM,MAAM;AAAA,EAAC,CAAC;AAEnB,WAAS,gBAAsC;AAC7C,QAAI,gBAAgB,KAAM,QAAO,QAAQ,QAAQ,WAAW;AAC5D,QAAI,iBAAiB,KAAM,QAAO;AAClC,oBAAgB,YAAY;AAC1B,YAAM,OAAO,MAAM,IAAI,eAAe,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,QACzF,UAAU,QAAQ;AAAA,QAClB,UAAU,QAAQ;AAAA,QAClB,aAAa,QAAQ,eAAe;AAAA,QACpC,UAAU,QAAQ,YAAY,CAAA;AAAA,QAC9B,GAAI,QAAQ,yBAAyB,SACjC,EAAE,sBAAsB,QAAQ,yBAChC,CAAA;AAAA,MAAC,CACN;AACD,oBAAc,KAAK;AACnB,aAAO;AAAA,IACT,GAAA;AACA,WAAO;AAAA,EACT;AAEA,iBAAe,SAAS,MAAkB,YAAmC;AAC3E,UAAM,SAAS,MAAM,cAAA;AAErB,UAAM,OAAO,IAAI,gBAAA;AACjB,UAAM,KAAK,OAAO,IAAI;AACtB,UAAM,UAAU,MAAM,KAAK,OAAA;AAE3B,QAAI,cAAc,YAAY,sBAAsB,MAAM;AAC1D,QAAI,CAAC,aAAa;AAChB,YAAM,OAAO,MAAM,IAAI,iBAAiB,YAAY,UAAA,GAAa,YAAY,gBAAgB;AAAA,QAC3F;AAAA,MAAA,CACD;AACD,oBAAc,EAAE,WAAW,KAAK,WAAW,oBAAoB,KAAK,mBAAA;AAAA,IACtE;AAEA,QAAI;AACF,YAAM,SAAS,MAAM,IAAI;AAAA,QACvB,YAAY;AAAA,QACZ;AAAA,UACE,eAAe,YAAY;AAAA,UAC3B;AAAA,UACA,eAAe,KAAK;AAAA,UACpB,aAAa;AAAA,UACb,GAAI,QAAQ,yBAAyB,SACjC,EAAE,sBAAsB,QAAQ,yBAChC,CAAA;AAAA,QAAC;AAAA,QAEP;AAAA,QACA,QAAQ;AAAA,MAAA;AAEV,kBAAY,oBAAoB,QAAQ,WAAW;AACnD,gBAAU,aAAa,CAAC,IAAI,OAAO;AACnC,cAAQ,SAAS,KAAK,UAAU;AAChC,cAAQ,aAAA;AAAA,IACV,SAAS,KAAK;AACZ,kBAAY,mBAAmB,QAAQ,WAAW;AAClD,YAAM;AAAA,IACR;AAAA,EACF;AAEA,WAAS,eAAqB;AAC5B,QAAI,QAAQ,WAAW,EAAG;AAC1B,QAAI;AACJ,QAAI,QAAQ,WAAW,GAAG;AACxB,YAAM,OAAO,QAAQ,CAAC;AACtB,UAAI,CAAC,KAAM;AACX,aAAO;AAAA,IACT,OAAO;AACL,YAAM,QAAQ,QAAQ,OAAO,CAAC,KAAK,UAAU,MAAM,MAAM,YAAY,CAAC;AACtE,aAAO,IAAI,WAAW,KAAK;AAC3B,UAAI,SAAS;AACb,iBAAW,SAAS,SAAS;AAC3B,aAAK,IAAI,OAAO,MAAM;AACtB,kBAAU,MAAM;AAAA,MAClB;AAAA,IACF;AACA,YAAQ,SAAS;AACjB,mBAAe;AACf,UAAM,aAAa;AACnB,UAAM,QAAQ,YAAY;AACxB,YAAM,IAAI,QAAA;AACV,UAAI;AACF,cAAM,SAAS,MAAM,UAAU;AAAA,MACjC,SAAS,KAAK;AACZ,kBAAU,QAAQ,GAAG;AACrB,cAAM;AAAA,MACR,UAAA;AACE,YAAI,QAAA;AAAA,MACN;AAAA,IACF,GAAA;AACA,aAAS,KAAK,IAAI;AAElB,SAAK,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACrB;AAEA,QAAM,WAAW,IAAI,eAA2B;AAAA,IAC9C,MAAM,MAAM,OAAkC;AAC5C,UAAI,QAAS,OAAM;AACnB,cAAQ,QAAQ,eAAA;AAEhB,cAAQ,KAAK,KAAK;AAClB,sBAAgB,MAAM;AACtB,aAAO,gBAAgB,UAAU;AAE/B,cAAM,SAAS,WAAW,SAAS,QAAQ;AAC3C,cAAM,aAAa;AACnB,wBAAgB;AAChB,cAAM,QAAQ,YAAY;AACxB,gBAAM,IAAI,QAAA;AACV,cAAI;AACF,kBAAM,SAAS,QAAQ,UAAU;AAAA,UACnC,SAAS,KAAK;AACZ,sBAAU,QAAQ,GAAG;AACrB,kBAAM;AAAA,UACR,UAAA;AACE,gBAAI,QAAA;AAAA,UACN;AAAA,QACF,GAAA;AACA,iBAAS,KAAK,IAAI;AAClB,aAAK,MAAM,MAAM;AAAA,QAAC,CAAC;AAAA,MACrB;AAAA,IACF;AAAA,IAEA,MAAM,QAAuB;AAC3B,UAAI;AACF,YAAI,QAAS,OAAM;AACnB,gBAAQ,QAAQ,eAAA;AAKhB,YAAI,eAAe,GAAG;AACpB,uBAAA;AAAA,QACF;AAEA,cAAM,QAAQ,IAAI,QAAQ;AAC1B,YAAI,QAAS,OAAM;AAEnB,YAAI,gBAAgB,MAAM;AAIxB,gBAAM,IAAI,MAAM,oDAAoD;AAAA,QACtE;AAEA,cAAM,SAAS,MAAM,IAAI;AAAA,UACvB,YAAY,UAAA;AAAA,UACZ,YAAY,aAAA;AAAA,UACZ,EAAE,QAAQ,aAAa,eAAe,UAAA;AAAA,QAAU;AAElD,oBAAY,MAAM;AAAA,MACpB,SAAS,KAAK;AAIZ,cAAM,iBAAiB;AACvB,YAAI,mBAAmB,MAAM;AAC3B,gBAAM,0BAA0B,KAAK,aAAa,cAAc;AAAA,QAClE;AACA,mBAAW,GAAG;AACd,cAAM;AAAA,MACR;AAAA,IACF;AAAA,IAEA,MAAM,MAAM,QAAgC;AAC1C,YAAM,iBAAiB;AACvB,UAAI,mBAAmB,MAAM;AAC3B,cAAM,0BAA0B,KAAK,aAAa,cAAc;AAAA,MAClE;AACA,iBAAW,QAAQ,MAAM,CAAC;AAAA,IAC5B;AAAA,EAAA,CACD;AAED,SAAO,EAAE,UAAU,KAAA;AACrB;AAYA,SAAS,WAAW,QAAsB,MAA0B;AAClE,QAAM,MAAM,IAAI,WAAW,IAAI;AAC/B,MAAI,UAAU;AACd,SAAO,UAAU,QAAQ,OAAO,SAAS,GAAG;AAC1C,UAAM,OAAO,OAAO,CAAC;AACrB,QAAI,CAAC,KAAM;AACX,UAAM,OAAO,OAAO;AACpB,QAAI,KAAK,cAAc,MAAM;AAC3B,UAAI,IAAI,MAAM,OAAO;AACrB,iBAAW,KAAK;AAChB,aAAO,MAAA;AAAA,IACT,OAAO;AACL,UAAI,IAAI,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO;AACvC,aAAO,CAAC,IAAI,KAAK,SAAS,IAAI;AAC9B,iBAAW;AAAA,IACb;AAAA,EACF;AACA,SAAO;AACT;"}
+{"version":3,"file":"stream.js","names":[],"sources":["../../src/upload/stream.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 { EncryptionSetting } from '../types/encryption.ts'\nimport type { FileVersion } from '../types/file.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\nimport { abortReason, raceWithAbort } from '../util/abort.ts'\nimport { DEFAULT_CONTENT_TYPE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { toError } from '../util/to-error.ts'\nimport { createAbortScope } from './abort-scope.ts'\nimport {\n  type CleanupFailureOptions,\n  cancelLargeFileBestEffort,\n  DEFAULT_CLEANUP_TIMEOUT_MS,\n  resolveLargeFileErrorAfterCleanup,\n} from './cancel.ts'\nimport { Semaphore } from './concurrency.ts'\nimport { finishLargeFileWithAbortReconciliation } from './finish.ts'\nimport {\n  resolveRetryResponseBodyFailures,\n  type UploadRetryOptions,\n  uploadPartWithFreshUrl,\n} from './retry.ts'\n\n/** Options for creating a streaming multipart upload sink. */\nexport interface CreateWriteStreamOptions extends UploadRetryOptions, CleanupFailureOptions {\n  /** Target bucket for the upload. */\n  readonly bucketId: BucketId\n  /** Destination file name in the bucket. */\n  readonly fileName: string\n  /** MIME type. Defaults to `b2/x-auto`. */\n  readonly contentType?: string\n  /** Custom file info stored with the file. */\n  readonly fileInfo?: Record<string, string>\n  /** Server-side encryption applied to each part. */\n  readonly serverSideEncryption?: EncryptionSetting\n  /**\n   * B2 upload timestamp override in milliseconds since epoch.\n   * Sets the file version `uploadTimestamp`; distinct from `src_last_modified_millis` metadata.\n   * Requires B2 account enablement for Custom Upload Timestamp.\n   */\n  readonly customUploadTimestamp?: number\n  /**\n   * Target part size in bytes. The stream buffers writes until this many bytes\n   * are accumulated, then ships a part. Must be at least the account's\n   * absolute minimum part size; the implementation will raise it if too small.\n   */\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 events. `totalBytes` is `null` (size unknown). */\n  readonly onProgress?: ProgressListener\n  /** Aborts the upload and cancels the unfinished large file. */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Handle returned by `B2Object.createWriteStream`: the Web `WritableStream` to\n * pipe data into, plus a promise that resolves with the finished\n * {@link FileVersion} once the stream is closed and all parts have been\n * uploaded.\n */\nexport interface UploadWriteHandle {\n  /** Web `WritableStream` sink to pipe data into. */\n  readonly writable: WritableStream<Uint8Array>\n  /** Resolves with the finalized file version when the stream closes successfully. */\n  readonly done: Promise<FileVersion>\n}\n\n/**\n * Creates a {@link WritableStream} that streams data into a B2 multipart upload.\n *\n * Buffers incoming chunks until `partSize` bytes are accumulated, ships each\n * complete part through the standard multipart engine, and finalizes the file\n * once the stream is closed. Honours backpressure via the queue's bounded\n * concurrency. Streaming uploads do not support resume because the total size\n * and per-part hashes aren't known in advance; use {@link uploadLargeFile} with\n * a buffered source when resume is required.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state (tokens, URLs, part URL pool).\n * @param options - Streaming upload parameters.\n *\n * @returns A {@link UploadWriteHandle} with the writable sink and a completion promise.\n */\nexport function createWriteStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: CreateWriteStreamOptions,\n): UploadWriteHandle {\n  const minPartSize = accountInfo.getAbsoluteMinimumPartSize()\n  const recommendedPartSize = accountInfo.getRecommendedPartSize()\n  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize)\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const tracker = new ProgressTracker(options.onProgress, null, null)\n  const sem = new Semaphore(concurrency)\n  const abortScope = createAbortScope(options.signal)\n\n  let largeFileId: LargeFileId | null = null\n  let startPromise: Promise<LargeFileId> | null = null\n  let cancelAfterStartScheduled = false\n  let nextPartNumber = 1\n  let pendingBytes = 0\n  const pending: Uint8Array[] = []\n  const partSha1s: string[] = []\n  const inflight: Promise<void>[] = []\n  let errored: Error | null = null\n\n  // ES2024 `Promise.withResolvers()` exposes the resolve/reject pair as\n  // properties of the returned object, avoiding the `let resolve!:` /\n  // `let reject!:` non-null-assertion pattern needed before this API\n  // existed. Available in Node 22 (our minimum), Bun, Deno, modern\n  // browsers, and Cloudflare Workers.\n  const {\n    promise: done,\n    resolve: resolveDone,\n    reject: rejectDone,\n  } = Promise.withResolvers<FileVersion>()\n  // Attach a no-op rejection handler so a `done` that rejects before the\n  // caller observes it never surfaces as a process-level unhandled rejection.\n  // The error is not swallowed: `close()`/`abort()` also reject the writable\n  // (so `pipeTo`/`getWriter().close()` throw), and any later `await done` /\n  // `done.then(onRejected)` the caller attaches still sees the rejection —\n  // extra handlers on the same promise all fire. Mirrors the\n  // `task.catch(() => {})` pattern used for inflight part uploads below, and\n  // keeps the engine well-behaved under Bun and Node's strict\n  // unhandled-rejection mode.\n  done.catch(() => {})\n\n  function ensureStarted(): Promise<LargeFileId> {\n    if (largeFileId !== null) return Promise.resolve(largeFileId)\n    if (startPromise === null) {\n      const rawStart = raw.startLargeFile(\n        accountInfo.getApiUrl(),\n        accountInfo.getAuthToken(),\n        {\n          bucketId: options.bucketId,\n          fileName: options.fileName,\n          contentType: options.contentType ?? DEFAULT_CONTENT_TYPE,\n          fileInfo: options.fileInfo ?? {},\n          ...(options.customUploadTimestamp !== undefined\n            ? { customUploadTimestamp: String(options.customUploadTimestamp) }\n            : {}),\n          ...(options.serverSideEncryption !== undefined\n            ? { serverSideEncryption: options.serverSideEncryption }\n            : {}),\n        },\n        {\n          signal: abortScope.signal,\n          ...(options.retry !== undefined ? { retry: options.retry } : {}),\n        },\n      )\n      startPromise = rawStart.then((resp) => {\n        largeFileId = resp.fileId\n        if (abortScope.signal.aborted || errored !== null) {\n          cancelStartedLargeFile(largeFileId)\n        }\n        return largeFileId\n      })\n    }\n    const started = startPromise\n    return raceWithAbort(started, abortScope.signal).catch((err) => {\n      if (abortScope.signal.aborted) scheduleCancelLargeFileAfterStart(started)\n      throw err\n    })\n  }\n\n  async function shipPart(data: Uint8Array, partNumber: number): Promise<void> {\n    if (errored !== null) throw errored\n    abortScope.signal.throwIfAborted()\n    const fileId = await ensureStarted()\n    if (errored !== null) throw errored\n    abortScope.signal.throwIfAborted()\n\n    const sha1 = new IncrementalSha1()\n    await sha1.update(data)\n    const sha1Hex = await sha1.digest()\n    abortScope.signal.throwIfAborted()\n\n    const result = await uploadPartWithFreshUrl(raw, accountInfo, fileId, {\n      fileName: options.fileName,\n      partNumber,\n      data: data as BodyInit,\n      contentLength: data.byteLength,\n      contentSha1: sha1Hex,\n      retry: options.retry,\n      signal: abortScope.signal,\n      onUploadRetry: options.onUploadRetry,\n      retryResponseBodyFailures: resolveRetryResponseBodyFailures(\n        options.retryResponseBodyFailures,\n      ),\n      ...(options.serverSideEncryption !== undefined\n        ? { serverSideEncryption: options.serverSideEncryption }\n        : {}),\n    })\n    partSha1s[partNumber - 1] = result.contentSha1\n    tracker.addBytes(data.byteLength)\n    tracker.completePart()\n  }\n\n  function markErrored(err: unknown): Error {\n    const error = toError(err)\n    errored = error\n    abortScope.abort(error)\n    return error\n  }\n\n  function cancelStartedLargeFile(fileId: LargeFileId): void {\n    if (cancelAfterStartScheduled) return\n    cancelAfterStartScheduled = true\n    void cancelLargeFileBestEffort(raw, accountInfo, fileId, cleanupWriteStreamOptions(options))\n  }\n\n  function scheduleCancelLargeFileAfterStart(started: Promise<LargeFileId>): void {\n    void started\n      .then((fileId) => cancelStartedLargeFile(fileId))\n      .catch(() => {\n        // If start failed, no file ID is available to cancel.\n      })\n  }\n\n  async function settleInflightForClose(): Promise<PromiseSettledResult<void>[]> {\n    const settled = Promise.allSettled(inflight)\n    if (startPromise === null || largeFileId !== null) return await settled\n\n    const abortWaiter = waitForAbort(abortScope.signal)\n    try {\n      const first = await Promise.race([\n        settled.then(() => 'settled' as const),\n        startPromise.then(\n          () => 'start-settled' as const,\n          () => 'start-settled' as const,\n        ),\n        abortWaiter.promise.then(() => 'aborted' as const),\n      ])\n      if (first === 'aborted' && largeFileId === null) {\n        throw abortReason(abortScope.signal)\n      }\n      return await settled\n    } finally {\n      abortWaiter.dispose()\n    }\n  }\n\n  function startPartWithAcquiredSlot(data: Uint8Array, partNumber: number): void {\n    const task = (async () => {\n      try {\n        await shipPart(data, partNumber)\n      } catch (err) {\n        markErrored(err)\n        throw err\n      } finally {\n        sem.release()\n      }\n    })()\n    inflight.push(task)\n    // Swallow rejection here; we check `errored` later.\n    task.catch(() => {})\n  }\n\n  async function acquirePartSlot(): Promise<void> {\n    await sem.acquire()\n    if (errored !== null) {\n      sem.release()\n      throw errored\n    }\n    try {\n      abortScope.signal.throwIfAborted()\n    } catch (err) {\n      sem.release()\n      throw err\n    }\n  }\n\n  async function waitForInflightPartsToSettle(\n    timeoutMs = DEFAULT_CLEANUP_TIMEOUT_MS,\n  ): Promise<void> {\n    if (inflight.length === 0) return\n    let timeout: ReturnType<typeof setTimeout> | undefined\n    try {\n      await Promise.race([\n        Promise.allSettled(inflight).then(() => undefined),\n        new Promise<void>((resolve) => {\n          timeout = setTimeout(resolve, timeoutMs)\n        }),\n      ])\n    } finally {\n      if (timeout !== undefined) clearTimeout(timeout)\n    }\n  }\n\n  async function dispatchPart(): Promise<void> {\n    if (pending.length === 0) return\n    await acquirePartSlot()\n    let data: Uint8Array\n    if (pending.length === 1) {\n      const head = pending[0]\n      if (!head) {\n        sem.release()\n        return\n      }\n      data = head\n    } else {\n      const total = pending.reduce((sum, chunk) => sum + chunk.byteLength, 0)\n      data = new Uint8Array(total)\n      let offset = 0\n      for (const chunk of pending) {\n        data.set(chunk, offset)\n        offset += chunk.byteLength\n      }\n    }\n    pending.length = 0\n    pendingBytes = 0\n    const partNumber = nextPartNumber++\n    startPartWithAcquiredSlot(data, partNumber)\n  }\n\n  const writable = new WritableStream<Uint8Array>({\n    async write(chunk: Uint8Array): Promise<void> {\n      if (errored) throw errored\n      abortScope.signal.throwIfAborted()\n      if (chunk.byteLength === 0) return\n\n      pending.push(chunk)\n      pendingBytes += chunk.byteLength\n      while (pendingBytes >= partSize) {\n        await acquirePartSlot()\n        if (errored) {\n          sem.release()\n          throw errored\n        }\n        // Pull exactly partSize bytes off the front\n        const carved = carveExact(pending, partSize)\n        const partNumber = nextPartNumber++\n        pendingBytes -= partSize\n        startPartWithAcquiredSlot(carved, partNumber)\n      }\n    },\n\n    async close(): Promise<void> {\n      try {\n        if (errored) throw errored\n        abortScope.signal.throwIfAborted()\n\n        // Ship any remaining bytes as the last part. If the total fit in one\n        // single buffered batch (no parts shipped yet), we have to use the\n        // multipart path anyway since we already called startLargeFile lazily.\n        if (pendingBytes > 0) {\n          await dispatchPart()\n        }\n\n        const settled = await settleInflightForClose()\n        const rejected = settled.find(\n          (result): result is PromiseRejectedResult => result.status === 'rejected',\n        )\n        if (rejected !== undefined && errored === null) {\n          markErrored(rejected.reason)\n        }\n        if (errored) throw errored\n\n        if (largeFileId === null) {\n          // Stream closed before any data was written. Start an empty large\n          // file? B2 requires at least 2 parts. Reject — callers shouldn't\n          // close an empty stream.\n          throw new Error('createWriteStream closed without any data written.')\n        }\n\n        const result = await finishLargeFileWithAbortReconciliation(raw, accountInfo, {\n          fileId: largeFileId,\n          bucketId: options.bucketId,\n          fileName: options.fileName,\n          partSha1s,\n          signal: abortScope.signal,\n          ...(options.retry !== undefined ? { retry: options.retry } : {}),\n        })\n        abortScope.dispose()\n        resolveDone(result)\n      } catch (err) {\n        const closeError = toError(err)\n        if (errored === null) errored = closeError\n        abortScope.abort(errored)\n        const observedError = errored\n        const fileIdToCancel = largeFileId\n        if (fileIdToCancel === null && startPromise !== null) {\n          // Mirror writer.abort(): close() must not wait for non-abortable\n          // b2_start_large_file. If a file ID arrives later, cancel it in the\n          // background.\n          scheduleCancelLargeFileAfterStart(startPromise)\n          abortScope.dispose()\n          rejectDone(observedError)\n          throw observedError\n        }\n        await Promise.allSettled(inflight)\n        // Capture into a const so the cancel closure sees a non-null\n        // `fileId`; closures don't observe the outer `!== null` narrowing\n        // because the variable is mutable across the lambda boundary.\n        let finalError: unknown = observedError\n        if (fileIdToCancel !== null) {\n          finalError = await resolveLargeFileErrorAfterCleanup(observedError, raw, accountInfo, {\n            fileId: fileIdToCancel,\n            bucketId: options.bucketId,\n            fileName: options.fileName,\n            signal: options.signal,\n            onCleanupFailure: options.onCleanupFailure,\n          })\n        }\n        abortScope.dispose()\n        rejectDone(finalError)\n        throw finalError\n      }\n    },\n\n    async abort(reason: unknown): Promise<void> {\n      const abortError = markErrored(reason)\n      pending.length = 0\n      pendingBytes = 0\n      const fileIdToCancel = largeFileId\n      if (fileIdToCancel === null && startPromise !== null) {\n        // Do not await an in-flight start request here. A stalled\n        // b2_start_large_file must not make writer.abort() hang; if it later\n        // returns a file ID, cancel it best-effort in the background.\n        scheduleCancelLargeFileAfterStart(startPromise)\n      }\n      if (fileIdToCancel !== null) {\n        await waitForInflightPartsToSettle()\n        await cancelLargeFileBestEffort(\n          raw,\n          accountInfo,\n          fileIdToCancel,\n          cleanupWriteStreamOptions(options),\n        )\n      }\n      abortScope.dispose()\n      rejectDone(abortError)\n    },\n  })\n\n  return { writable, done }\n}\n\nfunction cleanupWriteStreamOptions(options: CreateWriteStreamOptions): {\n  readonly signal?: AbortSignal\n} & CleanupFailureOptions {\n  return {\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n    ...(options.onCleanupFailure !== undefined\n      ? { onCleanupFailure: options.onCleanupFailure }\n      : {}),\n  }\n}\n\n/**\n * Removes exactly `size` bytes from the front of `chunks` (mutates) and returns\n * them as a contiguous Uint8Array. Any trailing remainder of the last chunk\n * stays at the front of `chunks` for the next part.\n *\n * @param chunks - Queue of pending chunks. Modified in place.\n * @param size - Number of bytes to carve off the front.\n *\n * @returns A new Uint8Array containing exactly `size` bytes.\n */\nfunction carveExact(chunks: Uint8Array[], size: number): Uint8Array {\n  const out = new Uint8Array(size)\n  let written = 0\n  while (written < size && chunks.length > 0) {\n    const head = chunks[0]\n    if (!head) break\n    const need = size - written\n    if (head.byteLength <= need) {\n      out.set(head, written)\n      written += head.byteLength\n      chunks.shift()\n    } else {\n      out.set(head.subarray(0, need), written)\n      chunks[0] = head.subarray(need)\n      written += need\n    }\n  }\n  return out\n}\n\nfunction waitForAbort(signal: AbortSignal): {\n  readonly promise: Promise<unknown>\n  dispose(): void\n} {\n  if (signal.aborted) {\n    return {\n      promise: Promise.resolve(abortReason(signal)),\n      dispose() {},\n    }\n  }\n\n  let onAbort: (() => void) | undefined\n  const promise = new Promise<unknown>((resolve) => {\n    onAbort = () => resolve(abortReason(signal))\n    signal.addEventListener('abort', onAbort, { once: true })\n  })\n\n  return {\n    promise,\n    dispose() {\n      if (onAbort !== undefined) signal.removeEventListener('abort', onAbort)\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/util/abort.cjs

@@ -0,0 +1,114 @@
+//#region src/util/abort.ts
+/**
+* Abort-signal and cancellation-error helpers shared across SDK operations.
+*
+* @packageDocumentation
+*/
+/**
+* Resolves the abort reason for a signal, defaulting to a standard `AbortError`.
+*
+* @param signal - The aborted signal whose reason should be resolved.
+*
+* @returns The signal's `reason`, or a fresh `AbortError` DOMException when unset.
+*/
+function abortReason(signal) {
+	return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+/**
+* Returns whether an error represents an abort.
+*
+* @param err - Unknown thrown value.
+*
+* @returns True for `Error` or `DOMException` instances named `AbortError`.
+*/
+function isAbortError(err) {
+	return isNamedError(err, "AbortError");
+}
+/**
+* Returns whether an error should be treated as the given signal's abort.
+*
+* @param signal - Controlling signal for the operation.
+* @param err - Unknown thrown value.
+*
+* @returns True when the signal is aborted and `err` is either the signal's
+* reason or a trusted `AbortError` instance.
+*/
+function isSignalAbortError(signal, err) {
+	if (signal?.aborted !== true) return false;
+	if (signal.reason !== void 0 && Object.is(err, signal.reason)) return true;
+	return isAbortError(err);
+}
+/**
+* Returns whether an error represents a timeout.
+*
+* @param err - Unknown thrown value.
+*
+* @returns True for `Error` or `DOMException` instances named `TimeoutError`.
+*/
+function isTimeoutError(err) {
+	return isNamedError(err, "TimeoutError");
+}
+/**
+* Throws the abort reason if the signal is already aborted; otherwise returns.
+*
+* @param signal - The signal to check, or undefined to skip the check.
+*
+* @throws The signal's abort reason when the signal is already aborted.
+*/
+function throwIfSignalAborted(signal) {
+	if (signal?.aborted === true) throw abortReason(signal);
+}
+/**
+* Races a promise against an abort signal. Rejects with the signal's abort
+* reason if the signal fires first, detaching the listener and suppressing the
+* losing promise's rejection so it never surfaces as an unhandled rejection.
+*
+* The underlying work must still receive the same signal so transports can
+* cancel their network activity. This helper only makes callers stop waiting
+* promptly even when a test double or custom transport ignores the signal.
+*
+* @param promise - The work to await.
+* @param signal - Abort signal, or undefined to await the promise directly.
+*
+* @returns The resolved value of `promise` when it settles before the signal aborts.
+*
+* @throws The abort reason if the signal aborts first, or the promise's rejection.
+*/
+async function raceWithAbort(promise, signal) {
+	if (signal === void 0) return promise;
+	if (signal.aborted) {
+		promise.catch(() => {});
+		throw abortReason(signal);
+	}
+	let removeAbortListener;
+	const aborted = new Promise((_, reject) => {
+		const onAbort = () => {
+			promise.catch(() => {});
+			reject(abortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+		if (signal.aborted) onAbort();
+	});
+	try {
+		return await Promise.race([promise, aborted]);
+	} finally {
+		removeAbortListener?.();
+	}
+}
+function isNamedError(err, name) {
+	try {
+		return (err instanceof DOMException || err instanceof Error) && err.name === name;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+exports.abortReason = abortReason;
+exports.isAbortError = isAbortError;
+exports.isSignalAbortError = isSignalAbortError;
+exports.isTimeoutError = isTimeoutError;
+exports.raceWithAbort = raceWithAbort;
+exports.throwIfSignalAborted = throwIfSignalAborted;
+
+//# sourceMappingURL=abort.cjs.map

package/dist/util/abort.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.cjs","names":[],"sources":["../../src/util/abort.ts"],"sourcesContent":["/**\n * Abort-signal and cancellation-error helpers shared across SDK operations.\n *\n * @packageDocumentation\n */\n\n/**\n * Resolves the abort reason for a signal, defaulting to a standard `AbortError`.\n *\n * @param signal - The aborted signal whose reason should be resolved.\n *\n * @returns The signal's `reason`, or a fresh `AbortError` DOMException when unset.\n */\nexport function abortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\n/**\n * Returns whether an error represents an abort.\n *\n * @param err - Unknown thrown value.\n *\n * @returns True for `Error` or `DOMException` instances named `AbortError`.\n */\nexport function isAbortError(err: unknown): boolean {\n  return isNamedError(err, 'AbortError')\n}\n\n/**\n * Returns whether an error should be treated as the given signal's abort.\n *\n * @param signal - Controlling signal for the operation.\n * @param err - Unknown thrown value.\n *\n * @returns True when the signal is aborted and `err` is either the signal's\n * reason or a trusted `AbortError` instance.\n */\nexport function isSignalAbortError(signal: AbortSignal | undefined, err: unknown): boolean {\n  if (signal?.aborted !== true) return false\n  if (signal.reason !== undefined && Object.is(err, signal.reason)) return true\n  return isAbortError(err)\n}\n\n/**\n * Returns whether an error represents a timeout.\n *\n * @param err - Unknown thrown value.\n *\n * @returns True for `Error` or `DOMException` instances named `TimeoutError`.\n */\nexport function isTimeoutError(err: unknown): boolean {\n  return isNamedError(err, 'TimeoutError')\n}\n\n/**\n * Throws the abort reason if the signal is already aborted; otherwise returns.\n *\n * @param signal - The signal to check, or undefined to skip the check.\n *\n * @throws The signal's abort reason when the signal is already aborted.\n */\nexport function throwIfSignalAborted(signal: AbortSignal | undefined): void {\n  if (signal?.aborted === true) {\n    throw abortReason(signal)\n  }\n}\n\n/**\n * Races a promise against an abort signal. Rejects with the signal's abort\n * reason if the signal fires first, detaching the listener and suppressing the\n * losing promise's rejection so it never surfaces as an unhandled rejection.\n *\n * The underlying work must still receive the same signal so transports can\n * cancel their network activity. This helper only makes callers stop waiting\n * promptly even when a test double or custom transport ignores the signal.\n *\n * @param promise - The work to await.\n * @param signal - Abort signal, or undefined to await the promise directly.\n *\n * @returns The resolved value of `promise` when it settles before the signal aborts.\n *\n * @throws The abort reason if the signal aborts first, or the promise's rejection.\n */\nexport async function raceWithAbort<T>(\n  promise: Promise<T>,\n  signal: AbortSignal | undefined,\n): Promise<T> {\n  if (signal === undefined) return promise\n  if (signal.aborted) {\n    void promise.catch(() => {})\n    throw abortReason(signal)\n  }\n\n  let removeAbortListener: (() => void) | undefined\n  const aborted = new Promise<never>((_, reject) => {\n    const onAbort = (): void => {\n      void promise.catch(() => {})\n      reject(abortReason(signal))\n    }\n    signal.addEventListener('abort', onAbort, { once: true })\n    removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n    if (signal.aborted) onAbort()\n  })\n\n  try {\n    return await Promise.race([promise, aborted])\n  } finally {\n    removeAbortListener?.()\n  }\n}\n\nfunction isNamedError(err: unknown, name: string): boolean {\n  try {\n    return (\n      (err instanceof DOMException || err instanceof Error) &&\n      (err as { readonly name: string }).name === name\n    )\n  } catch {\n    return false\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgB,YAAY,QAA8B;CACxD,OAAO,OAAO,UAAU,IAAI,aAAa,WAAW,YAAY;AAClE;;;;;;;;AASA,SAAgB,aAAa,KAAuB;CAClD,OAAO,aAAa,KAAK,YAAY;AACvC;;;;;;;;;;AAWA,SAAgB,mBAAmB,QAAiC,KAAuB;CACzF,IAAI,QAAQ,YAAY,MAAM,OAAO;CACrC,IAAI,OAAO,WAAW,KAAA,KAAa,OAAO,GAAG,KAAK,OAAO,MAAM,GAAG,OAAO;CACzE,OAAO,aAAa,GAAG;AACzB;;;;;;;;AASA,SAAgB,eAAe,KAAuB;CACpD,OAAO,aAAa,KAAK,cAAc;AACzC;;;;;;;;AASA,SAAgB,qBAAqB,QAAuC;CAC1E,IAAI,QAAQ,YAAY,MACtB,MAAM,YAAY,MAAM;AAE5B;;;;;;;;;;;;;;;;;AAkBA,eAAsB,cACpB,SACA,QACY;CACZ,IAAI,WAAW,KAAA,GAAW,OAAO;CACjC,IAAI,OAAO,SAAS;EAClB,QAAa,YAAY,CAAC,CAAC;EAC3B,MAAM,YAAY,MAAM;CAC1B;CAEA,IAAI;CACJ,MAAM,UAAU,IAAI,SAAgB,GAAG,WAAW;EAChD,MAAM,gBAAsB;GAC1B,QAAa,YAAY,CAAC,CAAC;GAC3B,OAAO,YAAY,MAAM,CAAC;EAC5B;EACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,4BAA4B,OAAO,oBAAoB,SAAS,OAAO;EACvE,IAAI,OAAO,SAAS,QAAQ;CAC9B,CAAC;CAED,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,OAAO,CAAC;CAC9C,UAAU;EACR,sBAAsB;CACxB;AACF;AAEA,SAAS,aAAa,KAAc,MAAuB;CACzD,IAAI;EACF,QACG,eAAe,gBAAgB,eAAe,UAC9C,IAAkC,SAAS;CAEhD,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/util/abort.d.cts

@@ -0,0 +1,65 @@
+/**
+ * Abort-signal and cancellation-error helpers shared across SDK operations.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Resolves the abort reason for a signal, defaulting to a standard `AbortError`.
+ *
+ * @param signal - The aborted signal whose reason should be resolved.
+ *
+ * @returns The signal's `reason`, or a fresh `AbortError` DOMException when unset.
+ */
+export declare function abortReason(signal: AbortSignal): unknown;
+/**
+ * Returns whether an error represents an abort.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns True for `Error` or `DOMException` instances named `AbortError`.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Returns whether an error should be treated as the given signal's abort.
+ *
+ * @param signal - Controlling signal for the operation.
+ * @param err - Unknown thrown value.
+ *
+ * @returns True when the signal is aborted and `err` is either the signal's
+ * reason or a trusted `AbortError` instance.
+ */
+export declare function isSignalAbortError(signal: AbortSignal | undefined, err: unknown): boolean;
+/**
+ * Returns whether an error represents a timeout.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns True for `Error` or `DOMException` instances named `TimeoutError`.
+ */
+export declare function isTimeoutError(err: unknown): boolean;
+/**
+ * Throws the abort reason if the signal is already aborted; otherwise returns.
+ *
+ * @param signal - The signal to check, or undefined to skip the check.
+ *
+ * @throws The signal's abort reason when the signal is already aborted.
+ */
+export declare function throwIfSignalAborted(signal: AbortSignal | undefined): void;
+/**
+ * Races a promise against an abort signal. Rejects with the signal's abort
+ * reason if the signal fires first, detaching the listener and suppressing the
+ * losing promise's rejection so it never surfaces as an unhandled rejection.
+ *
+ * The underlying work must still receive the same signal so transports can
+ * cancel their network activity. This helper only makes callers stop waiting
+ * promptly even when a test double or custom transport ignores the signal.
+ *
+ * @param promise - The work to await.
+ * @param signal - Abort signal, or undefined to await the promise directly.
+ *
+ * @returns The resolved value of `promise` when it settles before the signal aborts.
+ *
+ * @throws The abort reason if the signal aborts first, or the promise's rejection.
+ */
+export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+//# sourceMappingURL=abort.d.ts.map

package/dist/util/abort.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/util/abort.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAIzF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAI1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/util/abort.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Abort-signal and cancellation-error helpers shared across SDK operations.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Resolves the abort reason for a signal, defaulting to a standard `AbortError`.
+ *
+ * @param signal - The aborted signal whose reason should be resolved.
+ *
+ * @returns The signal's `reason`, or a fresh `AbortError` DOMException when unset.
+ */
+export declare function abortReason(signal: AbortSignal): unknown;
+/**
+ * Returns whether an error represents an abort.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns True for `Error` or `DOMException` instances named `AbortError`.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Returns whether an error should be treated as the given signal's abort.
+ *
+ * @param signal - Controlling signal for the operation.
+ * @param err - Unknown thrown value.
+ *
+ * @returns True when the signal is aborted and `err` is either the signal's
+ * reason or a trusted `AbortError` instance.
+ */
+export declare function isSignalAbortError(signal: AbortSignal | undefined, err: unknown): boolean;
+/**
+ * Returns whether an error represents a timeout.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns True for `Error` or `DOMException` instances named `TimeoutError`.
+ */
+export declare function isTimeoutError(err: unknown): boolean;
+/**
+ * Throws the abort reason if the signal is already aborted; otherwise returns.
+ *
+ * @param signal - The signal to check, or undefined to skip the check.
+ *
+ * @throws The signal's abort reason when the signal is already aborted.
+ */
+export declare function throwIfSignalAborted(signal: AbortSignal | undefined): void;
+/**
+ * Races a promise against an abort signal. Rejects with the signal's abort
+ * reason if the signal fires first, detaching the listener and suppressing the
+ * losing promise's rejection so it never surfaces as an unhandled rejection.
+ *
+ * The underlying work must still receive the same signal so transports can
+ * cancel their network activity. This helper only makes callers stop waiting
+ * promptly even when a test double or custom transport ignores the signal.
+ *
+ * @param promise - The work to await.
+ * @param signal - Abort signal, or undefined to await the promise directly.
+ *
+ * @returns The resolved value of `promise` when it settles before the signal aborts.
+ *
+ * @throws The abort reason if the signal aborts first, or the promise's rejection.
+ */
+export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+//# sourceMappingURL=abort.d.ts.map

package/dist/util/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/util/abort.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAIzF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAI1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/util/abort.js

@@ -0,0 +1,109 @@
+//#region src/util/abort.ts
+/**
+* Abort-signal and cancellation-error helpers shared across SDK operations.
+*
+* @packageDocumentation
+*/
+/**
+* Resolves the abort reason for a signal, defaulting to a standard `AbortError`.
+*
+* @param signal - The aborted signal whose reason should be resolved.
+*
+* @returns The signal's `reason`, or a fresh `AbortError` DOMException when unset.
+*/
+function abortReason(signal) {
+	return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+/**
+* Returns whether an error represents an abort.
+*
+* @param err - Unknown thrown value.
+*
+* @returns True for `Error` or `DOMException` instances named `AbortError`.
+*/
+function isAbortError(err) {
+	return isNamedError(err, "AbortError");
+}
+/**
+* Returns whether an error should be treated as the given signal's abort.
+*
+* @param signal - Controlling signal for the operation.
+* @param err - Unknown thrown value.
+*
+* @returns True when the signal is aborted and `err` is either the signal's
+* reason or a trusted `AbortError` instance.
+*/
+function isSignalAbortError(signal, err) {
+	if (signal?.aborted !== true) return false;
+	if (signal.reason !== void 0 && Object.is(err, signal.reason)) return true;
+	return isAbortError(err);
+}
+/**
+* Returns whether an error represents a timeout.
+*
+* @param err - Unknown thrown value.
+*
+* @returns True for `Error` or `DOMException` instances named `TimeoutError`.
+*/
+function isTimeoutError(err) {
+	return isNamedError(err, "TimeoutError");
+}
+/**
+* Throws the abort reason if the signal is already aborted; otherwise returns.
+*
+* @param signal - The signal to check, or undefined to skip the check.
+*
+* @throws The signal's abort reason when the signal is already aborted.
+*/
+function throwIfSignalAborted(signal) {
+	if (signal?.aborted === true) throw abortReason(signal);
+}
+/**
+* Races a promise against an abort signal. Rejects with the signal's abort
+* reason if the signal fires first, detaching the listener and suppressing the
+* losing promise's rejection so it never surfaces as an unhandled rejection.
+*
+* The underlying work must still receive the same signal so transports can
+* cancel their network activity. This helper only makes callers stop waiting
+* promptly even when a test double or custom transport ignores the signal.
+*
+* @param promise - The work to await.
+* @param signal - Abort signal, or undefined to await the promise directly.
+*
+* @returns The resolved value of `promise` when it settles before the signal aborts.
+*
+* @throws The abort reason if the signal aborts first, or the promise's rejection.
+*/
+async function raceWithAbort(promise, signal) {
+	if (signal === void 0) return promise;
+	if (signal.aborted) {
+		promise.catch(() => {});
+		throw abortReason(signal);
+	}
+	let removeAbortListener;
+	const aborted = new Promise((_, reject) => {
+		const onAbort = () => {
+			promise.catch(() => {});
+			reject(abortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+		if (signal.aborted) onAbort();
+	});
+	try {
+		return await Promise.race([promise, aborted]);
+	} finally {
+		removeAbortListener?.();
+	}
+}
+function isNamedError(err, name) {
+	try {
+		return (err instanceof DOMException || err instanceof Error) && err.name === name;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { abortReason, isAbortError, isSignalAbortError, isTimeoutError, raceWithAbort, throwIfSignalAborted };
+
+//# sourceMappingURL=abort.js.map

package/dist/util/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","names":[],"sources":["../../src/util/abort.ts"],"sourcesContent":["/**\n * Abort-signal and cancellation-error helpers shared across SDK operations.\n *\n * @packageDocumentation\n */\n\n/**\n * Resolves the abort reason for a signal, defaulting to a standard `AbortError`.\n *\n * @param signal - The aborted signal whose reason should be resolved.\n *\n * @returns The signal's `reason`, or a fresh `AbortError` DOMException when unset.\n */\nexport function abortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\n/**\n * Returns whether an error represents an abort.\n *\n * @param err - Unknown thrown value.\n *\n * @returns True for `Error` or `DOMException` instances named `AbortError`.\n */\nexport function isAbortError(err: unknown): boolean {\n  return isNamedError(err, 'AbortError')\n}\n\n/**\n * Returns whether an error should be treated as the given signal's abort.\n *\n * @param signal - Controlling signal for the operation.\n * @param err - Unknown thrown value.\n *\n * @returns True when the signal is aborted and `err` is either the signal's\n * reason or a trusted `AbortError` instance.\n */\nexport function isSignalAbortError(signal: AbortSignal | undefined, err: unknown): boolean {\n  if (signal?.aborted !== true) return false\n  if (signal.reason !== undefined && Object.is(err, signal.reason)) return true\n  return isAbortError(err)\n}\n\n/**\n * Returns whether an error represents a timeout.\n *\n * @param err - Unknown thrown value.\n *\n * @returns True for `Error` or `DOMException` instances named `TimeoutError`.\n */\nexport function isTimeoutError(err: unknown): boolean {\n  return isNamedError(err, 'TimeoutError')\n}\n\n/**\n * Throws the abort reason if the signal is already aborted; otherwise returns.\n *\n * @param signal - The signal to check, or undefined to skip the check.\n *\n * @throws The signal's abort reason when the signal is already aborted.\n */\nexport function throwIfSignalAborted(signal: AbortSignal | undefined): void {\n  if (signal?.aborted === true) {\n    throw abortReason(signal)\n  }\n}\n\n/**\n * Races a promise against an abort signal. Rejects with the signal's abort\n * reason if the signal fires first, detaching the listener and suppressing the\n * losing promise's rejection so it never surfaces as an unhandled rejection.\n *\n * The underlying work must still receive the same signal so transports can\n * cancel their network activity. This helper only makes callers stop waiting\n * promptly even when a test double or custom transport ignores the signal.\n *\n * @param promise - The work to await.\n * @param signal - Abort signal, or undefined to await the promise directly.\n *\n * @returns The resolved value of `promise` when it settles before the signal aborts.\n *\n * @throws The abort reason if the signal aborts first, or the promise's rejection.\n */\nexport async function raceWithAbort<T>(\n  promise: Promise<T>,\n  signal: AbortSignal | undefined,\n): Promise<T> {\n  if (signal === undefined) return promise\n  if (signal.aborted) {\n    void promise.catch(() => {})\n    throw abortReason(signal)\n  }\n\n  let removeAbortListener: (() => void) | undefined\n  const aborted = new Promise<never>((_, reject) => {\n    const onAbort = (): void => {\n      void promise.catch(() => {})\n      reject(abortReason(signal))\n    }\n    signal.addEventListener('abort', onAbort, { once: true })\n    removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n    if (signal.aborted) onAbort()\n  })\n\n  try {\n    return await Promise.race([promise, aborted])\n  } finally {\n    removeAbortListener?.()\n  }\n}\n\nfunction isNamedError(err: unknown, name: string): boolean {\n  try {\n    return (\n      (err instanceof DOMException || err instanceof Error) &&\n      (err as { readonly name: string }).name === name\n    )\n  } catch {\n    return false\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgB,YAAY,QAA8B;CACxD,OAAO,OAAO,UAAU,IAAI,aAAa,WAAW,YAAY;AAClE;;;;;;;;AASA,SAAgB,aAAa,KAAuB;CAClD,OAAO,aAAa,KAAK,YAAY;AACvC;;;;;;;;;;AAWA,SAAgB,mBAAmB,QAAiC,KAAuB;CACzF,IAAI,QAAQ,YAAY,MAAM,OAAO;CACrC,IAAI,OAAO,WAAW,KAAA,KAAa,OAAO,GAAG,KAAK,OAAO,MAAM,GAAG,OAAO;CACzE,OAAO,aAAa,GAAG;AACzB;;;;;;;;AASA,SAAgB,eAAe,KAAuB;CACpD,OAAO,aAAa,KAAK,cAAc;AACzC;;;;;;;;AASA,SAAgB,qBAAqB,QAAuC;CAC1E,IAAI,QAAQ,YAAY,MACtB,MAAM,YAAY,MAAM;AAE5B;;;;;;;;;;;;;;;;;AAkBA,eAAsB,cACpB,SACA,QACY;CACZ,IAAI,WAAW,KAAA,GAAW,OAAO;CACjC,IAAI,OAAO,SAAS;EAClB,QAAa,YAAY,CAAC,CAAC;EAC3B,MAAM,YAAY,MAAM;CAC1B;CAEA,IAAI;CACJ,MAAM,UAAU,IAAI,SAAgB,GAAG,WAAW;EAChD,MAAM,gBAAsB;GAC1B,QAAa,YAAY,CAAC,CAAC;GAC3B,OAAO,YAAY,MAAM,CAAC;EAC5B;EACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,4BAA4B,OAAO,oBAAoB,SAAS,OAAO;EACvE,IAAI,OAAO,SAAS,QAAQ;CAC9B,CAAC;CAED,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,SAAS,OAAO,CAAC;CAC9C,UAAU;EACR,sBAAsB;CACxB;AACF;AAEA,SAAS,aAAa,KAAc,MAAuB;CACzD,IAAI;EACF,QACG,eAAe,gBAAgB,eAAe,UAC9C,IAAkC,SAAS;CAEhD,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/util/best-effort.cjs

@@ -1,10 +1,44 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-async function bestEffort(fn) {
-  try {
-    await fn();
-  } catch {
-  }
+//#region src/util/best-effort.ts
+/**
+* Runs an async cleanup operation and swallows any rejection.
+*
+* Used at error-handling boundaries (e.g. after a multipart upload fails,
+* when trying to `cancelLargeFile` on the orphaned upload). The primary
+* error is what the caller wants to see; a secondary failure during
+* cleanup must not shadow it.
+*
+* Naming the pattern instead of inlining a try/catch with an empty catch
+* makes the intent explicit at the call site: this is best-effort cleanup,
+* not a silent error swallow.
+*
+* @param fn - Cleanup async function. Its return value is ignored; any
+*   thrown error or rejected promise is caught and discarded.
+* @param onError - Optional observer called with the swallowed cleanup error.
+*
+* @returns A promise that always resolves, regardless of `fn`'s outcome.
+*
+* @example
+* ```ts
+* try {
+*   await uploadParts(...)
+* } catch (err) {
+*   await bestEffort(() =>
+*     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),
+*   )
+*   throw err
+* }
+* ```
+*/
+async function bestEffort(fn, onError) {
+	try {
+		await fn();
+	} catch (error) {
+		try {
+			onError?.(error);
+		} catch {}
+	}
 }
+//#endregion
 exports.bestEffort = bestEffort;
-//# sourceMappingURL=best-effort.cjs.map
+
+//# sourceMappingURL=best-effort.cjs.map

package/dist/util/best-effort.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"best-effort.cjs","sources":["../../src/util/best-effort.ts"],"sourcesContent":["/**\n * Runs an async cleanup operation and swallows any rejection.\n *\n * Used at error-handling boundaries (e.g. after a multipart upload fails,\n * when trying to `cancelLargeFile` on the orphaned upload). The primary\n * error is what the caller wants to see; a secondary failure during\n * cleanup must not shadow it.\n *\n * Naming the pattern instead of inlining a try/catch with an empty catch\n * makes the intent explicit at the call site: this is best-effort cleanup,\n * not a silent error swallow.\n *\n * @param fn - Cleanup async function. Its return value is ignored; any\n *   thrown error or rejected promise is caught and discarded.\n *\n * @returns A promise that always resolves, regardless of `fn`'s outcome.\n *\n * @example\n * ```ts\n * try {\n *   await uploadParts(...)\n * } catch (err) {\n *   await bestEffort(() =>\n *     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),\n *   )\n *   throw err\n * }\n * ```\n */\nexport async function bestEffort(fn: () => Promise<unknown>): Promise<void> {\n  try {\n    await fn()\n  } catch {\n    // Intentional swallow: this helper exists for cleanup paths where a\n    // secondary failure must not shadow the primary error.\n  }\n}\n"],"names":[],"mappings":";;AA6BA,eAAsB,WAAW,IAA2C;AAC1E,MAAI;AACF,UAAM,GAAA;AAAA,EACR,QAAQ;AAAA,EAGR;AACF;;"}
+{"version":3,"file":"best-effort.cjs","names":[],"sources":["../../src/util/best-effort.ts"],"sourcesContent":["/**\n * Runs an async cleanup operation and swallows any rejection.\n *\n * Used at error-handling boundaries (e.g. after a multipart upload fails,\n * when trying to `cancelLargeFile` on the orphaned upload). The primary\n * error is what the caller wants to see; a secondary failure during\n * cleanup must not shadow it.\n *\n * Naming the pattern instead of inlining a try/catch with an empty catch\n * makes the intent explicit at the call site: this is best-effort cleanup,\n * not a silent error swallow.\n *\n * @param fn - Cleanup async function. Its return value is ignored; any\n *   thrown error or rejected promise is caught and discarded.\n * @param onError - Optional observer called with the swallowed cleanup error.\n *\n * @returns A promise that always resolves, regardless of `fn`'s outcome.\n *\n * @example\n * ```ts\n * try {\n *   await uploadParts(...)\n * } catch (err) {\n *   await bestEffort(() =>\n *     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),\n *   )\n *   throw err\n * }\n * ```\n */\nexport async function bestEffort(\n  fn: () => Promise<unknown>,\n  onError?: (error: unknown) => void,\n): Promise<void> {\n  try {\n    await fn()\n  } catch (error) {\n    try {\n      onError?.(error)\n    } catch {\n      // Observer failures are also secondary cleanup failures.\n    }\n    // Intentional swallow: this helper exists for cleanup paths where a\n    // secondary failure must not shadow the primary error.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,eAAsB,WACpB,IACA,SACe;CACf,IAAI;EACF,MAAM,GAAG;CACX,SAAS,OAAO;EACd,IAAI;GACF,UAAU,KAAK;EACjB,QAAQ,CAER;CAGF;AACF"}

package/dist/util/best-effort.d.cts

@@ -12,6 +12,7 @@
  *
  * @param fn - Cleanup async function. Its return value is ignored; any
  *   thrown error or rejected promise is caught and discarded.
+ * @param onError - Optional observer called with the swallowed cleanup error.
  *
  * @returns A promise that always resolves, regardless of `fn`'s outcome.
  *
@@ -27,5 +28,5 @@
  * }
  * ```
  */
-export declare function bestEffort(fn: () => Promise<unknown>): Promise<void>;
+export declare function bestEffort(fn: () => Promise<unknown>, onError?: (error: unknown) => void): Promise<void>;
 //# sourceMappingURL=best-effort.d.ts.map

package/dist/util/best-effort.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"best-effort.d.ts","sourceRoot":"","sources":["../../src/util/best-effort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E"}
+{"version":3,"file":"best-effort.d.ts","sourceRoot":"","sources":["../../src/util/best-effort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/util/best-effort.d.ts

@@ -12,6 +12,7 @@
  *
  * @param fn - Cleanup async function. Its return value is ignored; any
  *   thrown error or rejected promise is caught and discarded.
+ * @param onError - Optional observer called with the swallowed cleanup error.
  *
  * @returns A promise that always resolves, regardless of `fn`'s outcome.
  *
@@ -27,5 +28,5 @@
  * }
  * ```
  */
-export declare function bestEffort(fn: () => Promise<unknown>): Promise<void>;
+export declare function bestEffort(fn: () => Promise<unknown>, onError?: (error: unknown) => void): Promise<void>;
 //# sourceMappingURL=best-effort.d.ts.map

package/dist/util/best-effort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"best-effort.d.ts","sourceRoot":"","sources":["../../src/util/best-effort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E"}
+{"version":3,"file":"best-effort.d.ts","sourceRoot":"","sources":["../../src/util/best-effort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/util/best-effort.js

@@ -1,10 +1,44 @@
-async function bestEffort(fn) {
-  try {
-    await fn();
-  } catch {
-  }
+//#region src/util/best-effort.ts
+/**
+* Runs an async cleanup operation and swallows any rejection.
+*
+* Used at error-handling boundaries (e.g. after a multipart upload fails,
+* when trying to `cancelLargeFile` on the orphaned upload). The primary
+* error is what the caller wants to see; a secondary failure during
+* cleanup must not shadow it.
+*
+* Naming the pattern instead of inlining a try/catch with an empty catch
+* makes the intent explicit at the call site: this is best-effort cleanup,
+* not a silent error swallow.
+*
+* @param fn - Cleanup async function. Its return value is ignored; any
+*   thrown error or rejected promise is caught and discarded.
+* @param onError - Optional observer called with the swallowed cleanup error.
+*
+* @returns A promise that always resolves, regardless of `fn`'s outcome.
+*
+* @example
+* ```ts
+* try {
+*   await uploadParts(...)
+* } catch (err) {
+*   await bestEffort(() =>
+*     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),
+*   )
+*   throw err
+* }
+* ```
+*/
+async function bestEffort(fn, onError) {
+	try {
+		await fn();
+	} catch (error) {
+		try {
+			onError?.(error);
+		} catch {}
+	}
 }
-export {
-  bestEffort
-};
-//# sourceMappingURL=best-effort.js.map
+//#endregion
+export { bestEffort };
+
+//# sourceMappingURL=best-effort.js.map