@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

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

@@ -1 +1 @@
-{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/upload/cancel.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAGlD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,SAAS,EACd,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAIf"}
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../../src/upload/cancel.js"],"names":[],"mappings":"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"}

package/dist/upload/cancel.js

@@ -1,10 +1,179 @@
+import { FinishLargeFileResponseBodyError } from "../errors/index.js";
 import { bestEffort } from "../util/best-effort.js";
-async function cancelLargeFileBestEffort(raw, accountInfo, fileId) {
-  await bestEffort(
-    () => raw.cancelLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId })
-  );
-}
-export {
-  cancelLargeFileBestEffort
-};
-//# sourceMappingURL=cancel.js.map
+//#region src/upload/cancel.ts
+/** Default wall-clock bound for best-effort cleanup calls after upload failure. */
+var DEFAULT_CLEANUP_TIMEOUT_MS = 3e4;
+var fallbackCleanupDisposers = /* @__PURE__ */ new WeakMap();
+/**
+* Cancels an unfinished large file on a best-effort basis. Used at every
+* error-handling boundary in the multipart upload, write-stream, and
+* server-side copy paths to roll back in-progress uploads without
+* letting a cancellation failure mask the underlying error the caller
+* is about to see.
+*
+* Centralising the call removes a five-line `bestEffort` block that
+* recurred at six sites with identical shape — the only thing that
+* changed was the captured `fileId` and the surrounding error trail.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state for the API URL + token.
+* @param fileId - The in-progress large file ID to cancel.
+* @param options - Optional request controls and cleanup-failure observer.
+*
+* @returns A promise that always resolves, regardless of the cancel
+*   call's outcome.
+*/
+async function cancelLargeFileBestEffort(raw, accountInfo, fileId, options) {
+	await bestEffort(async () => {
+		const requestOptions = cleanupRequestOptions(options?.signal);
+		await waitForCleanup(raw.cancelLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId }, requestOptions), requestOptions.signal);
+	}, (error) => options?.onCleanupFailure?.({
+		fileId,
+		error,
+		reason: "cancel-failed"
+	}));
+}
+/**
+* Returns cleanup request controls with a live timeout signal.
+*
+* @param signal - Caller-provided abort signal, if any.
+* @param timeoutMs - Maximum time to spend waiting for cleanup.
+*
+* @returns Request controls with a signal independent of an already-aborted caller signal.
+*/
+function cleanupRequestOptions(signal, timeoutMs = DEFAULT_CLEANUP_TIMEOUT_MS) {
+	return { signal: createCleanupSignal(signal, timeoutMs) };
+}
+function createCleanupSignal(signal, timeoutMs) {
+	if (typeof AbortSignal.timeout === "function") {
+		if (signal === void 0 || signal.aborted) return AbortSignal.timeout(timeoutMs);
+		if (typeof AbortSignal.any === "function") return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+	}
+	return createFallbackCleanupSignal(signal, timeoutMs);
+}
+function createFallbackCleanupSignal(signal, timeoutMs) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => {
+		abortFallbackCleanup(controller, cleanupTimeoutReason(), cleanup);
+	}, timeoutMs);
+	const onAbort = () => {
+		const reason = signal === void 0 ? cleanupDomException("Cleanup aborted", "AbortError") : cleanupAbortReason(signal);
+		abortFallbackCleanup(controller, reason, cleanup);
+	};
+	const cleanup = () => {
+		clearTimeout(timeout);
+		signal?.removeEventListener("abort", onAbort);
+		fallbackCleanupDisposers.delete(controller.signal);
+	};
+	fallbackCleanupDisposers.set(controller.signal, cleanup);
+	if (signal === void 0 || signal.aborted) return controller.signal;
+	signal.addEventListener("abort", onAbort, { once: true });
+	controller.signal.addEventListener("abort", cleanup, { once: true });
+	return controller.signal;
+}
+function abortFallbackCleanup(controller, reason, cleanup) {
+	if (!controller.signal.aborted) controller.abort(reason);
+	cleanup();
+}
+async function waitForCleanup(request, signal) {
+	if (signal.aborted) throw cleanupAbortReason(signal);
+	let removeAbortListener;
+	const aborted = new Promise((_resolve, reject) => {
+		const onAbort = () => reject(cleanupAbortReason(signal));
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+	});
+	try {
+		await Promise.race([request, aborted]);
+	} finally {
+		removeAbortListener?.();
+		fallbackCleanupDisposers.get(signal)?.();
+		request.catch(() => {});
+	}
+}
+function cleanupAbortReason(signal) {
+	return signal.reason ?? cleanupDomException("Cleanup aborted", "AbortError");
+}
+function cleanupTimeoutReason() {
+	return cleanupDomException("Cleanup timed out", "TimeoutError");
+}
+function cleanupDomException(message, name) {
+	if (typeof DOMException === "function") return new DOMException(message, name);
+	const error = new Error(message);
+	error.name = name;
+	return error;
+}
+/**
+* Emits an observable cleanup event when cancellation is deliberately skipped
+* because `b2_finish_large_file` may already have committed the file.
+* @param fileId - Large file whose final state is ambiguous.
+* @param error - Ambiguous finish error that will be thrown to the caller.
+* @param onCleanupFailure - Optional observer for cleanup-related events.
+*/
+function notifyAmbiguousLargeFileCleanupSkipped(fileId, error, onCleanupFailure) {
+	try {
+		onCleanupFailure?.({
+			fileId,
+			error,
+			reason: "finish-ambiguous"
+		});
+	} catch {}
+}
+/**
+* Adds high-level reconciliation metadata to an ambiguous finish response-body
+* error and notifies the cleanup observer that cancellation was skipped.
+*
+* @param err - Raw finish response-body error from the low-level client.
+* @param options - Large-file context used for reconciliation.
+*
+* @returns The enriched {@link FinishLargeFileResponseBodyError}.
+*/
+function handleAmbiguousFinishLargeFileResponseBodyError(err, options) {
+	const enriched = err.fileId === options.fileId && err.bucketId === options.bucketId && err.fileName === options.fileName ? err : new FinishLargeFileResponseBodyError(err.message, {
+		cause: err.cause ?? err,
+		fileId: options.fileId,
+		bucketId: options.bucketId,
+		fileName: options.fileName
+	});
+	notifyAmbiguousLargeFileCleanupSkipped(options.fileId, enriched, options.onCleanupFailure);
+	return enriched;
+}
+/**
+* Performs the shared large-file failure policy: ambiguous finish-body errors
+* are enriched and left uncancelled, while all pre-finish errors trigger
+* best-effort cancellation.
+*
+* @param err - Error from a multipart upload/copy/write-stream path.
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param context - Large file metadata used for cleanup and diagnostics.
+* @param options - Cleanup policy controls.
+*
+* @returns The error that should be surfaced to the caller.
+*/
+async function resolveLargeFileErrorAfterCleanup(err, raw, accountInfo, context, options = {}) {
+	if (err instanceof FinishLargeFileResponseBodyError) return handleAmbiguousFinishLargeFileResponseBodyError(err, context);
+	if (options.cancelOnError ?? true) await cancelLargeFileBestEffort(raw, accountInfo, context.fileId, {
+		...context.signal !== void 0 ? { signal: context.signal } : {},
+		...context.onCleanupFailure !== void 0 ? { onCleanupFailure: context.onCleanupFailure } : {}
+	});
+	return err;
+}
+/**
+* Throwing wrapper around {@link resolveLargeFileErrorAfterCleanup} for paths
+* that can surface the error directly.
+* @param err - Error from a multipart upload/copy/write-stream path.
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param context - Large file metadata used for cleanup and diagnostics.
+* @param options - Cleanup policy controls.
+*
+* @throws The resolved large-file error after cleanup policy is applied.
+*/
+async function cleanupAfterLargeFileError(err, raw, accountInfo, context, options) {
+	throw await resolveLargeFileErrorAfterCleanup(err, raw, accountInfo, context, options);
+}
+//#endregion
+export { DEFAULT_CLEANUP_TIMEOUT_MS, cancelLargeFileBestEffort, cleanupAfterLargeFileError, cleanupRequestOptions, handleAmbiguousFinishLargeFileResponseBodyError, notifyAmbiguousLargeFileCleanupSkipped, resolveLargeFileErrorAfterCleanup };
+
+//# sourceMappingURL=cancel.js.map

package/dist/upload/cancel.js.map

@@ -1 +1 @@
-{"version":3,"file":"cancel.js","sources":["../../src/upload/cancel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { LargeFileId } from '../types/ids.ts'\nimport { bestEffort } from '../util/best-effort.ts'\n\n/**\n * Cancels an unfinished large file on a best-effort basis. Used at every\n * error-handling boundary in the multipart upload, write-stream, and\n * server-side copy paths to roll back in-progress uploads without\n * letting a cancellation failure mask the underlying error the caller\n * is about to see.\n *\n * Centralising the call removes a five-line `bestEffort` block that\n * recurred at six sites with identical shape — the only thing that\n * changed was the captured `fileId` and the surrounding error trail.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state for the API URL + token.\n * @param fileId - The in-progress large file ID to cancel.\n *\n * @returns A promise that always resolves, regardless of the cancel\n *   call's outcome.\n */\nexport async function cancelLargeFileBestEffort(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: LargeFileId,\n): Promise<void> {\n  await bestEffort(() =>\n    raw.cancelLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), { fileId }),\n  )\n}\n"],"names":[],"mappings":";AAuBA,eAAsB,0BACpB,KACA,aACA,QACe;AACf,QAAM;AAAA,IAAW,MACf,IAAI,gBAAgB,YAAY,UAAA,GAAa,YAAY,gBAAgB,EAAE,OAAA,CAAQ;AAAA,EAAA;AAEvF;"}
+{"version":3,"file":"cancel.js","names":[],"sources":["../../src/upload/cancel.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { FinishLargeFileResponseBodyError } from '../errors/index.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\nimport { bestEffort } from '../util/best-effort.ts'\n\n/** Event emitted when best-effort `b2_cancel_large_file` cleanup fails. */\nexport interface CancelLargeFileCleanupFailureEvent {\n  /** Unfinished large file that may remain orphaned. */\n  readonly fileId: LargeFileId\n  /** Error thrown by `b2_cancel_large_file`. */\n  readonly error: unknown\n  /** Cleanup phase that produced the observable event. */\n  readonly reason: 'cancel-failed'\n}\n\n/** Event emitted when cleanup is skipped because finish may have committed. */\nexport interface AmbiguousFinishCleanupFailureEvent {\n  /** Large file whose final server-side state is ambiguous. */\n  readonly fileId: LargeFileId\n  /** Error thrown to the caller with reconciliation metadata. */\n  readonly error: FinishLargeFileResponseBodyError\n  /** Cleanup phase that produced the observable event. */\n  readonly reason: 'finish-ambiguous'\n}\n\n/** Event emitted when large-file cleanup fails or is deliberately skipped. */\nexport type CleanupFailureEvent =\n  | CancelLargeFileCleanupFailureEvent\n  | AmbiguousFinishCleanupFailureEvent\n\n/** Callback invoked when best-effort cancellation fails or finish cleanup is skipped. */\nexport type CleanupFailureListener = (event: CleanupFailureEvent) => void\n\n/** Shared option for observing large-file cleanup failures or skipped cleanup. */\nexport interface CleanupFailureOptions {\n  /**\n   * Callback invoked if best-effort cancellation fails, or if cancellation is\n   * skipped because `b2_finish_large_file` may already have committed.\n   */\n  readonly onCleanupFailure?: CleanupFailureListener\n}\n\n/** Default wall-clock bound for best-effort cleanup calls after upload failure. */\nexport const DEFAULT_CLEANUP_TIMEOUT_MS = 30_000\n\nconst fallbackCleanupDisposers = new WeakMap<AbortSignal, () => void>()\n\n/** Context needed to reconcile or cancel an unfinished large file after an error. */\nexport interface LargeFileCleanupContext {\n  readonly fileId: LargeFileId\n  readonly bucketId: BucketId\n  readonly fileName: string\n  readonly signal?: AbortSignal | undefined\n  readonly onCleanupFailure?: CleanupFailureListener | undefined\n}\n\n/** Options for applying the shared large-file cleanup policy. */\nexport interface LargeFileCleanupPolicyOptions {\n  /**\n   * Whether non-ambiguous failures should cancel the unfinished large file.\n   * Defaults to true. Explicit resume callers can disable this so the SDK does\n   * not cancel a large file that it did not create.\n   */\n  readonly cancelOnError?: boolean\n}\n\n/**\n * Cancels an unfinished large file on a best-effort basis. Used at every\n * error-handling boundary in the multipart upload, write-stream, and\n * server-side copy paths to roll back in-progress uploads without\n * letting a cancellation failure mask the underlying error the caller\n * is about to see.\n *\n * Centralising the call removes a five-line `bestEffort` block that\n * recurred at six sites with identical shape — the only thing that\n * changed was the captured `fileId` and the surrounding error trail.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state for the API URL + token.\n * @param fileId - The in-progress large file ID to cancel.\n * @param options - Optional request controls and cleanup-failure observer.\n *\n * @returns A promise that always resolves, regardless of the cancel\n *   call's outcome.\n */\nexport async function cancelLargeFileBestEffort(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  fileId: LargeFileId,\n  options?: { readonly signal?: AbortSignal } & CleanupFailureOptions,\n): Promise<void> {\n  await bestEffort(\n    async () => {\n      const requestOptions = cleanupRequestOptions(options?.signal)\n      const request = raw.cancelLargeFile(\n        accountInfo.getApiUrl(),\n        accountInfo.getAuthToken(),\n        { fileId },\n        requestOptions,\n      )\n      await waitForCleanup(request, requestOptions.signal)\n    },\n    (error) => options?.onCleanupFailure?.({ fileId, error, reason: 'cancel-failed' }),\n  )\n}\n\n/**\n * Returns cleanup request controls with a live timeout signal.\n *\n * @param signal - Caller-provided abort signal, if any.\n * @param timeoutMs - Maximum time to spend waiting for cleanup.\n *\n * @returns Request controls with a signal independent of an already-aborted caller signal.\n */\nexport function cleanupRequestOptions(\n  signal: AbortSignal | undefined,\n  timeoutMs = DEFAULT_CLEANUP_TIMEOUT_MS,\n): { readonly signal: AbortSignal } {\n  return { signal: createCleanupSignal(signal, timeoutMs) }\n}\n\nfunction createCleanupSignal(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {\n  if (typeof AbortSignal.timeout === 'function') {\n    if (signal === undefined || signal.aborted) return AbortSignal.timeout(timeoutMs)\n    if (typeof AbortSignal.any === 'function') {\n      return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])\n    }\n  }\n\n  return createFallbackCleanupSignal(signal, timeoutMs)\n}\n\nfunction createFallbackCleanupSignal(\n  signal: AbortSignal | undefined,\n  timeoutMs: number,\n): AbortSignal {\n  const controller = new AbortController()\n  const timeout = setTimeout(() => {\n    abortFallbackCleanup(controller, cleanupTimeoutReason(), cleanup)\n  }, timeoutMs)\n\n  const onAbort = () => {\n    const reason =\n      signal === undefined\n        ? cleanupDomException('Cleanup aborted', 'AbortError')\n        : cleanupAbortReason(signal)\n    abortFallbackCleanup(controller, reason, cleanup)\n  }\n  const cleanup = () => {\n    clearTimeout(timeout)\n    signal?.removeEventListener('abort', onAbort)\n    fallbackCleanupDisposers.delete(controller.signal)\n  }\n  fallbackCleanupDisposers.set(controller.signal, cleanup)\n\n  if (signal === undefined || signal.aborted) {\n    return controller.signal\n  }\n\n  signal.addEventListener('abort', onAbort, { once: true })\n  controller.signal.addEventListener('abort', cleanup, { once: true })\n  return controller.signal\n}\n\nfunction abortFallbackCleanup(\n  controller: AbortController,\n  reason: unknown,\n  cleanup: () => void,\n): void {\n  if (!controller.signal.aborted) controller.abort(reason)\n  cleanup()\n}\n\nasync function waitForCleanup(request: Promise<unknown>, signal: AbortSignal): Promise<void> {\n  if (signal.aborted) throw cleanupAbortReason(signal)\n\n  let removeAbortListener: (() => void) | undefined\n  const aborted = new Promise<never>((_resolve, reject) => {\n    const onAbort = () => reject(cleanupAbortReason(signal))\n    signal.addEventListener('abort', onAbort, { once: true })\n    removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n  })\n\n  try {\n    await Promise.race([request, aborted])\n  } finally {\n    removeAbortListener?.()\n    fallbackCleanupDisposers.get(signal)?.()\n    void request.catch(() => {})\n  }\n}\n\nfunction cleanupAbortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? cleanupDomException('Cleanup aborted', 'AbortError')\n}\n\nfunction cleanupTimeoutReason(): unknown {\n  return cleanupDomException('Cleanup timed out', 'TimeoutError')\n}\n\nfunction cleanupDomException(message: string, name: string): Error {\n  if (typeof DOMException === 'function') return new DOMException(message, name)\n  const error = new Error(message)\n  error.name = name\n  return error\n}\n\n/**\n * Emits an observable cleanup event when cancellation is deliberately skipped\n * because `b2_finish_large_file` may already have committed the file.\n * @param fileId - Large file whose final state is ambiguous.\n * @param error - Ambiguous finish error that will be thrown to the caller.\n * @param onCleanupFailure - Optional observer for cleanup-related events.\n */\nexport function notifyAmbiguousLargeFileCleanupSkipped(\n  fileId: LargeFileId,\n  error: FinishLargeFileResponseBodyError,\n  onCleanupFailure?: CleanupFailureListener,\n): void {\n  try {\n    onCleanupFailure?.({ fileId, error, reason: 'finish-ambiguous' })\n  } catch {\n    // Observer failures are secondary and must not hide the finish ambiguity.\n  }\n}\n\n/**\n * Adds high-level reconciliation metadata to an ambiguous finish response-body\n * error and notifies the cleanup observer that cancellation was skipped.\n *\n * @param err - Raw finish response-body error from the low-level client.\n * @param options - Large-file context used for reconciliation.\n *\n * @returns The enriched {@link FinishLargeFileResponseBodyError}.\n */\nexport function handleAmbiguousFinishLargeFileResponseBodyError(\n  err: FinishLargeFileResponseBodyError,\n  options: LargeFileCleanupContext,\n): FinishLargeFileResponseBodyError {\n  const enriched =\n    err.fileId === options.fileId &&\n    err.bucketId === options.bucketId &&\n    err.fileName === options.fileName\n      ? err\n      : new FinishLargeFileResponseBodyError(err.message, {\n          cause: err.cause ?? err,\n          fileId: options.fileId,\n          bucketId: options.bucketId,\n          fileName: options.fileName,\n        })\n  notifyAmbiguousLargeFileCleanupSkipped(options.fileId, enriched, options.onCleanupFailure)\n  return enriched\n}\n\n/**\n * Performs the shared large-file failure policy: ambiguous finish-body errors\n * are enriched and left uncancelled, while all pre-finish errors trigger\n * best-effort cancellation.\n *\n * @param err - Error from a multipart upload/copy/write-stream path.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param context - Large file metadata used for cleanup and diagnostics.\n * @param options - Cleanup policy controls.\n *\n * @returns The error that should be surfaced to the caller.\n */\nexport async function resolveLargeFileErrorAfterCleanup(\n  err: unknown,\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  context: LargeFileCleanupContext,\n  options: LargeFileCleanupPolicyOptions = {},\n): Promise<unknown> {\n  if (err instanceof FinishLargeFileResponseBodyError) {\n    return handleAmbiguousFinishLargeFileResponseBodyError(err, context)\n  }\n  if (options.cancelOnError ?? true) {\n    await cancelLargeFileBestEffort(raw, accountInfo, context.fileId, {\n      ...(context.signal !== undefined ? { signal: context.signal } : {}),\n      ...(context.onCleanupFailure !== undefined\n        ? { onCleanupFailure: context.onCleanupFailure }\n        : {}),\n    })\n  }\n  return err\n}\n\n/**\n * Throwing wrapper around {@link resolveLargeFileErrorAfterCleanup} for paths\n * that can surface the error directly.\n * @param err - Error from a multipart upload/copy/write-stream path.\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param context - Large file metadata used for cleanup and diagnostics.\n * @param options - Cleanup policy controls.\n *\n * @throws The resolved large-file error after cleanup policy is applied.\n */\nexport async function cleanupAfterLargeFileError(\n  err: unknown,\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  context: LargeFileCleanupContext,\n  options?: LargeFileCleanupPolicyOptions,\n): Promise<never> {\n  throw await resolveLargeFileErrorAfterCleanup(err, raw, accountInfo, context, options)\n}\n"],"mappings":"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"}

package/dist/upload/concurrency.cjs

@@ -1,54 +1,81 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-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;
-  }
+//#region src/upload/concurrency.ts
+/**
+* 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.
+*/
+var Semaphore = class {
+	limit;
+	current = 0;
+	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) {
+		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.`);
+	}
+	/**
+	* 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;
+	}
+};
+/**
+* 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.
+*/
+async function mapConcurrent(items, concurrency, fn) {
+	const sem = new Semaphore(concurrency);
+	const results = new Array(items.length);
+	const tasks = items.map(async (item, i) => {
+		await sem.acquire();
+		try {
+			results[i] = await fn(item, i);
+		} finally {
+			sem.release();
+		}
+	});
+	await Promise.all(tasks);
+	return results;
 }
+//#endregion
 exports.Semaphore = Semaphore;
-//# sourceMappingURL=concurrency.cjs.map
+exports.mapConcurrent = mapConcurrent;
+
+//# sourceMappingURL=concurrency.cjs.map

package/dist/upload/concurrency.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"concurrency.cjs","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;;"}
+{"version":3,"file":"concurrency.cjs","names":[],"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"],"mappings":";;;;;;;;;AAQA,IAAa,YAAb,MAAuB;CAYQ;CAX7B,UAAkB;CAClB,QAAyC,CAAC;;;;;;;;;CAU1C,YAAY,OAAgC;EAAf,KAAA,QAAA;EAC3B,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,SAAS,GACvC,MAAM,IAAI,WACR,wDAAwD,MAAM,4FAChE;CAEJ;;;;;CAMA,MAAM,UAAyB;EAC7B,IAAI,KAAK,UAAU,KAAK,OAAO;GAC7B,KAAK;GACL;EACF;EACA,OAAO,IAAI,SAAe,YAAY;GACpC,KAAK,MAAM,KAAK,OAAO;EACzB,CAAC;CACH;;CAGA,UAAgB;EACd,MAAM,OAAO,KAAK,MAAM,MAAM;EAC9B,IAAI,MACF,KAAK;OAEL,KAAK;CAET;;;;;;CAOA,IAAI,YAAoB;EACtB,OAAO,KAAK,QAAQ,KAAK;CAC3B;AACF;;;;;;;;;;AAWA,eAAsB,cACpB,OACA,aACA,IACc;CACd,MAAM,MAAM,IAAI,UAAU,WAAW;CACrC,MAAM,UAAe,IAAI,MAAM,MAAM,MAAM;CAC3C,MAAM,QAAQ,MAAM,IAAI,OAAO,MAAM,MAAM;EACzC,MAAM,IAAI,QAAQ;EAClB,IAAI;GACF,QAAQ,KAAK,MAAM,GAAG,MAAM,CAAC;EAC/B,UAAU;GACR,IAAI,QAAQ;EACd;CACF,CAAC;CACD,MAAM,QAAQ,IAAI,KAAK;CACvB,OAAO;AACT"}

package/dist/upload/concurrency.js

@@ -1,54 +1,80 @@
-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
+//#region src/upload/concurrency.ts
+/**
+* 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.
+*/
+var Semaphore = class {
+	limit;
+	current = 0;
+	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) {
+		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.`);
+	}
+	/**
+	* 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;
+	}
 };
-//# sourceMappingURL=concurrency.js.map
+/**
+* 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.
+*/
+async function mapConcurrent(items, concurrency, fn) {
+	const sem = new Semaphore(concurrency);
+	const results = new Array(items.length);
+	const tasks = items.map(async (item, i) => {
+		await sem.acquire();
+		try {
+			results[i] = await fn(item, i);
+		} finally {
+			sem.release();
+		}
+	});
+	await Promise.all(tasks);
+	return results;
+}
+//#endregion
+export { Semaphore, mapConcurrent };
+
+//# sourceMappingURL=concurrency.js.map

package/dist/upload/concurrency.js.map

@@ -1 +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;"}
+{"version":3,"file":"concurrency.js","names":[],"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"],"mappings":";;;;;;;;;AAQA,IAAa,YAAb,MAAuB;CAYQ;CAX7B,UAAkB;CAClB,QAAyC,CAAC;;;;;;;;;CAU1C,YAAY,OAAgC;EAAf,KAAA,QAAA;EAC3B,IAAI,CAAC,OAAO,UAAU,KAAK,KAAK,SAAS,GACvC,MAAM,IAAI,WACR,wDAAwD,MAAM,4FAChE;CAEJ;;;;;CAMA,MAAM,UAAyB;EAC7B,IAAI,KAAK,UAAU,KAAK,OAAO;GAC7B,KAAK;GACL;EACF;EACA,OAAO,IAAI,SAAe,YAAY;GACpC,KAAK,MAAM,KAAK,OAAO;EACzB,CAAC;CACH;;CAGA,UAAgB;EACd,MAAM,OAAO,KAAK,MAAM,MAAM;EAC9B,IAAI,MACF,KAAK;OAEL,KAAK;CAET;;;;;;CAOA,IAAI,YAAoB;EACtB,OAAO,KAAK,QAAQ,KAAK;CAC3B;AACF;;;;;;;;;;AAWA,eAAsB,cACpB,OACA,aACA,IACc;CACd,MAAM,MAAM,IAAI,UAAU,WAAW;CACrC,MAAM,UAAe,IAAI,MAAM,MAAM,MAAM;CAC3C,MAAM,QAAQ,MAAM,IAAI,OAAO,MAAM,MAAM;EACzC,MAAM,IAAI,QAAQ;EAClB,IAAI;GACF,QAAQ,KAAK,MAAM,GAAG,MAAM,CAAC;EAC/B,UAAU;GACR,IAAI,QAAQ;EACd;CACF,CAAC;CACD,MAAM,QAAQ,IAAI,KAAK;CACvB,OAAO;AACT"}

package/dist/upload/finish.cjs

@@ -0,0 +1,59 @@
+const require_errors_index = require("../errors/index.cjs");
+//#region src/upload/finish.ts
+/**
+* Calls `b2_finish_large_file` and classifies failures after dispatch that can
+* hide an already-committed file as ambiguous finish failures.
+*
+* @param raw - Low-level B2 API client.
+* @param accountInfo - Authorized account state.
+* @param context - Finish request data and reconciliation metadata.
+*
+* @returns The completed file version metadata.
+*/
+async function finishLargeFileWithAbortReconciliation(raw, accountInfo, context) {
+	context.signal?.throwIfAborted();
+	try {
+		return await raw.finishLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {
+			fileId: context.fileId,
+			partSha1Array: context.partSha1s
+		}, context.signal === void 0 && context.retry === void 0 ? void 0 : {
+			...context.signal !== void 0 ? { signal: context.signal } : {},
+			...context.retry !== void 0 ? { retry: context.retry } : {}
+		});
+	} catch (err) {
+		if (err instanceof require_errors_index.FinishLargeFileResponseBodyError) throw finishLargeFileResponseBodyErrorWithContext(err, context);
+		if (isAmbiguousFinishDispatchFailure(err, context.signal)) throw new require_errors_index.FinishLargeFileResponseBodyError("b2_finish_large_file failed after dispatch; final file state is ambiguous.", {
+			cause: err,
+			fileId: context.fileId,
+			bucketId: context.bucketId,
+			fileName: context.fileName
+		});
+		throw err;
+	}
+}
+function finishLargeFileResponseBodyErrorWithContext(err, context) {
+	if (err.fileId === context.fileId && err.bucketId === context.bucketId && err.fileName === context.fileName) return err;
+	return new require_errors_index.FinishLargeFileResponseBodyError(err.message, {
+		cause: err.cause ?? err,
+		fileId: context.fileId,
+		bucketId: context.bucketId,
+		fileName: context.fileName
+	});
+}
+function isAmbiguousFinishDispatchFailure(err, signal) {
+	if (err instanceof require_errors_index.NetworkError) return true;
+	if (isTimeoutError(err)) return true;
+	if (signal?.aborted !== true) return false;
+	if (signal.reason !== void 0 && Object.is(err, signal.reason)) return true;
+	return isAbortError(err);
+}
+function isAbortError(err) {
+	return err instanceof DOMException && err.name === "AbortError" || err instanceof Error && err.name === "AbortError";
+}
+function isTimeoutError(err) {
+	return err instanceof DOMException && err.name === "TimeoutError" || err instanceof Error && err.name === "TimeoutError";
+}
+//#endregion
+exports.finishLargeFileWithAbortReconciliation = finishLargeFileWithAbortReconciliation;
+
+//# sourceMappingURL=finish.cjs.map

package/dist/upload/finish.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish.cjs","names":[],"sources":["../../src/upload/finish.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport { FinishLargeFileResponseBodyError, NetworkError } from '../errors/index.ts'\nimport type { RetryOptions } from '../http/retry.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport type { FileVersion } from '../types/file.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\n\n/** Context for safely finalizing a large file. */\nexport interface FinishLargeFileContext {\n  readonly fileId: LargeFileId\n  readonly bucketId: BucketId\n  readonly fileName: string\n  readonly partSha1s: readonly string[]\n  readonly signal?: AbortSignal\n  readonly retry?: Partial<RetryOptions>\n}\n\n/**\n * Calls `b2_finish_large_file` and classifies failures after dispatch that can\n * hide an already-committed file as ambiguous finish failures.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state.\n * @param context - Finish request data and reconciliation metadata.\n *\n * @returns The completed file version metadata.\n */\nexport async function finishLargeFileWithAbortReconciliation(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  context: FinishLargeFileContext,\n): Promise<FileVersion> {\n  context.signal?.throwIfAborted()\n  try {\n    return await raw.finishLargeFile(\n      accountInfo.getApiUrl(),\n      accountInfo.getAuthToken(),\n      {\n        fileId: context.fileId,\n        partSha1Array: context.partSha1s,\n      },\n      context.signal === undefined && context.retry === undefined\n        ? undefined\n        : {\n            ...(context.signal !== undefined ? { signal: context.signal } : {}),\n            ...(context.retry !== undefined ? { retry: context.retry } : {}),\n          },\n    )\n  } catch (err) {\n    if (err instanceof FinishLargeFileResponseBodyError) {\n      throw finishLargeFileResponseBodyErrorWithContext(err, context)\n    }\n    if (isAmbiguousFinishDispatchFailure(err, context.signal)) {\n      throw new FinishLargeFileResponseBodyError(\n        'b2_finish_large_file failed after dispatch; final file state is ambiguous.',\n        {\n          cause: err,\n          fileId: context.fileId,\n          bucketId: context.bucketId,\n          fileName: context.fileName,\n        },\n      )\n    }\n    throw err\n  }\n}\n\nfunction finishLargeFileResponseBodyErrorWithContext(\n  err: FinishLargeFileResponseBodyError,\n  context: FinishLargeFileContext,\n): FinishLargeFileResponseBodyError {\n  if (\n    err.fileId === context.fileId &&\n    err.bucketId === context.bucketId &&\n    err.fileName === context.fileName\n  ) {\n    return err\n  }\n  return new FinishLargeFileResponseBodyError(err.message, {\n    cause: err.cause ?? err,\n    fileId: context.fileId,\n    bucketId: context.bucketId,\n    fileName: context.fileName,\n  })\n}\n\nfunction isAmbiguousFinishDispatchFailure(err: unknown, signal: AbortSignal | undefined): boolean {\n  if (err instanceof NetworkError) return true\n  if (isTimeoutError(err)) return true\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\nfunction isAbortError(err: unknown): boolean {\n  return (\n    (err instanceof DOMException && err.name === 'AbortError') ||\n    (err instanceof Error && err.name === 'AbortError')\n  )\n}\n\nfunction isTimeoutError(err: unknown): boolean {\n  return (\n    (err instanceof DOMException && err.name === 'TimeoutError') ||\n    (err instanceof Error && err.name === 'TimeoutError')\n  )\n}\n"],"mappings":";;;;;;;;;;;;AA2BA,eAAsB,uCACpB,KACA,aACA,SACsB;CACtB,QAAQ,QAAQ,eAAe;CAC/B,IAAI;EACF,OAAO,MAAM,IAAI,gBACf,YAAY,UAAU,GACtB,YAAY,aAAa,GACzB;GACE,QAAQ,QAAQ;GAChB,eAAe,QAAQ;EACzB,GACA,QAAQ,WAAW,KAAA,KAAa,QAAQ,UAAU,KAAA,IAC9C,KAAA,IACA;GACE,GAAI,QAAQ,WAAW,KAAA,IAAY,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;GACjE,GAAI,QAAQ,UAAU,KAAA,IAAY,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;EAChE,CACN;CACF,SAAS,KAAK;EACZ,IAAI,eAAe,qBAAA,kCACjB,MAAM,4CAA4C,KAAK,OAAO;EAEhE,IAAI,iCAAiC,KAAK,QAAQ,MAAM,GACtD,MAAM,IAAI,qBAAA,iCACR,8EACA;GACE,OAAO;GACP,QAAQ,QAAQ;GAChB,UAAU,QAAQ;GAClB,UAAU,QAAQ;EACpB,CACF;EAEF,MAAM;CACR;AACF;AAEA,SAAS,4CACP,KACA,SACkC;CAClC,IACE,IAAI,WAAW,QAAQ,UACvB,IAAI,aAAa,QAAQ,YACzB,IAAI,aAAa,QAAQ,UAEzB,OAAO;CAET,OAAO,IAAI,qBAAA,iCAAiC,IAAI,SAAS;EACvD,OAAO,IAAI,SAAS;EACpB,QAAQ,QAAQ;EAChB,UAAU,QAAQ;EAClB,UAAU,QAAQ;CACpB,CAAC;AACH;AAEA,SAAS,iCAAiC,KAAc,QAA0C;CAChG,IAAI,eAAe,qBAAA,cAAc,OAAO;CACxC,IAAI,eAAe,GAAG,GAAG,OAAO;CAChC,IAAI,QAAQ,YAAY,MAAM,OAAO;CACrC,IAAI,OAAO,WAAW,KAAA,KAAa,OAAO,GAAG,KAAK,OAAO,MAAM,GAAG,OAAO;CACzE,OAAO,aAAa,GAAG;AACzB;AAEA,SAAS,aAAa,KAAuB;CAC3C,OACG,eAAe,gBAAgB,IAAI,SAAS,gBAC5C,eAAe,SAAS,IAAI,SAAS;AAE1C;AAEA,SAAS,eAAe,KAAuB;CAC7C,OACG,eAAe,gBAAgB,IAAI,SAAS,kBAC5C,eAAe,SAAS,IAAI,SAAS;AAE1C"}