@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/upload/cancel.d.cts

@@ -1,6 +1,56 @@
 import { AccountInfo } from '../auth/account-info.js';
+import { FinishLargeFileResponseBodyError } from '../errors/index.js';
 import { RawClient } from '../raw/index.js';
-import { LargeFileId } from '../types/ids.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+/** Event emitted when best-effort `b2_cancel_large_file` cleanup fails. */
+export interface CancelLargeFileCleanupFailureEvent {
+    /** Unfinished large file that may remain orphaned. */
+    readonly fileId: LargeFileId;
+    /** Error thrown by `b2_cancel_large_file`. */
+    readonly error: unknown;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'cancel-failed';
+}
+/** Event emitted when cleanup is skipped because finish may have committed. */
+export interface AmbiguousFinishCleanupFailureEvent {
+    /** Large file whose final server-side state is ambiguous. */
+    readonly fileId: LargeFileId;
+    /** Error thrown to the caller with reconciliation metadata. */
+    readonly error: FinishLargeFileResponseBodyError;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'finish-ambiguous';
+}
+/** Event emitted when large-file cleanup fails or is deliberately skipped. */
+export type CleanupFailureEvent = CancelLargeFileCleanupFailureEvent | AmbiguousFinishCleanupFailureEvent;
+/** Callback invoked when best-effort cancellation fails or finish cleanup is skipped. */
+export type CleanupFailureListener = (event: CleanupFailureEvent) => void;
+/** Shared option for observing large-file cleanup failures or skipped cleanup. */
+export interface CleanupFailureOptions {
+    /**
+     * Callback invoked if best-effort cancellation fails, or if cancellation is
+     * skipped because `b2_finish_large_file` may already have committed.
+     */
+    readonly onCleanupFailure?: CleanupFailureListener;
+}
+/** Default wall-clock bound for best-effort cleanup calls after upload failure. */
+export declare const DEFAULT_CLEANUP_TIMEOUT_MS = 30000;
+/** Context needed to reconcile or cancel an unfinished large file after an error. */
+export interface LargeFileCleanupContext {
+    readonly fileId: LargeFileId;
+    readonly bucketId: BucketId;
+    readonly fileName: string;
+    readonly signal?: AbortSignal | undefined;
+    readonly onCleanupFailure?: CleanupFailureListener | undefined;
+}
+/** Options for applying the shared large-file cleanup policy. */
+export interface LargeFileCleanupPolicyOptions {
+    /**
+     * Whether non-ambiguous failures should cancel the unfinished large file.
+     * Defaults to true. Explicit resume callers can disable this so the SDK does
+     * not cancel a large file that it did not create.
+     */
+    readonly cancelOnError?: boolean;
+}
 /**
  * Cancels an unfinished large file on a best-effort basis. Used at every
  * error-handling boundary in the multipart upload, write-stream, and
@@ -15,9 +65,67 @@ import { LargeFileId } from '../types/ids.js';
  * @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.
  */
-export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId): Promise<void>;
+export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, options?: {
+    readonly signal?: AbortSignal;
+} & CleanupFailureOptions): Promise<void>;
+/**
+ * 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.
+ */
+export declare function cleanupRequestOptions(signal: AbortSignal | undefined, timeoutMs?: number): {
+    readonly signal: AbortSignal;
+};
+/**
+ * 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.
+ */
+export declare function notifyAmbiguousLargeFileCleanupSkipped(fileId: LargeFileId, error: FinishLargeFileResponseBodyError, onCleanupFailure?: CleanupFailureListener): void;
+/**
+ * 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}.
+ */
+export declare function handleAmbiguousFinishLargeFileResponseBodyError(err: FinishLargeFileResponseBodyError, options: LargeFileCleanupContext): FinishLargeFileResponseBodyError;
+/**
+ * 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.
+ */
+export declare function resolveLargeFileErrorAfterCleanup(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<unknown>;
+/**
+ * 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.
+ */
+export declare function cleanupAfterLargeFileError(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<never>;
 //# sourceMappingURL=cancel.d.ts.map

package/dist/upload/cancel.d.cts.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.d.ts

@@ -1,6 +1,56 @@
 import { AccountInfo } from '../auth/account-info.js';
+import { FinishLargeFileResponseBodyError } from '../errors/index.js';
 import { RawClient } from '../raw/index.js';
-import { LargeFileId } from '../types/ids.js';
+import { BucketId, LargeFileId } from '../types/ids.js';
+/** Event emitted when best-effort `b2_cancel_large_file` cleanup fails. */
+export interface CancelLargeFileCleanupFailureEvent {
+    /** Unfinished large file that may remain orphaned. */
+    readonly fileId: LargeFileId;
+    /** Error thrown by `b2_cancel_large_file`. */
+    readonly error: unknown;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'cancel-failed';
+}
+/** Event emitted when cleanup is skipped because finish may have committed. */
+export interface AmbiguousFinishCleanupFailureEvent {
+    /** Large file whose final server-side state is ambiguous. */
+    readonly fileId: LargeFileId;
+    /** Error thrown to the caller with reconciliation metadata. */
+    readonly error: FinishLargeFileResponseBodyError;
+    /** Cleanup phase that produced the observable event. */
+    readonly reason: 'finish-ambiguous';
+}
+/** Event emitted when large-file cleanup fails or is deliberately skipped. */
+export type CleanupFailureEvent = CancelLargeFileCleanupFailureEvent | AmbiguousFinishCleanupFailureEvent;
+/** Callback invoked when best-effort cancellation fails or finish cleanup is skipped. */
+export type CleanupFailureListener = (event: CleanupFailureEvent) => void;
+/** Shared option for observing large-file cleanup failures or skipped cleanup. */
+export interface CleanupFailureOptions {
+    /**
+     * Callback invoked if best-effort cancellation fails, or if cancellation is
+     * skipped because `b2_finish_large_file` may already have committed.
+     */
+    readonly onCleanupFailure?: CleanupFailureListener;
+}
+/** Default wall-clock bound for best-effort cleanup calls after upload failure. */
+export declare const DEFAULT_CLEANUP_TIMEOUT_MS = 30000;
+/** Context needed to reconcile or cancel an unfinished large file after an error. */
+export interface LargeFileCleanupContext {
+    readonly fileId: LargeFileId;
+    readonly bucketId: BucketId;
+    readonly fileName: string;
+    readonly signal?: AbortSignal | undefined;
+    readonly onCleanupFailure?: CleanupFailureListener | undefined;
+}
+/** Options for applying the shared large-file cleanup policy. */
+export interface LargeFileCleanupPolicyOptions {
+    /**
+     * Whether non-ambiguous failures should cancel the unfinished large file.
+     * Defaults to true. Explicit resume callers can disable this so the SDK does
+     * not cancel a large file that it did not create.
+     */
+    readonly cancelOnError?: boolean;
+}
 /**
  * Cancels an unfinished large file on a best-effort basis. Used at every
  * error-handling boundary in the multipart upload, write-stream, and
@@ -15,9 +65,67 @@ import { LargeFileId } from '../types/ids.js';
  * @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.
  */
-export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId): Promise<void>;
+export declare function cancelLargeFileBestEffort(raw: RawClient, accountInfo: AccountInfo, fileId: LargeFileId, options?: {
+    readonly signal?: AbortSignal;
+} & CleanupFailureOptions): Promise<void>;
+/**
+ * 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.
+ */
+export declare function cleanupRequestOptions(signal: AbortSignal | undefined, timeoutMs?: number): {
+    readonly signal: AbortSignal;
+};
+/**
+ * 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.
+ */
+export declare function notifyAmbiguousLargeFileCleanupSkipped(fileId: LargeFileId, error: FinishLargeFileResponseBodyError, onCleanupFailure?: CleanupFailureListener): void;
+/**
+ * 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}.
+ */
+export declare function handleAmbiguousFinishLargeFileResponseBodyError(err: FinishLargeFileResponseBodyError, options: LargeFileCleanupContext): FinishLargeFileResponseBodyError;
+/**
+ * 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.
+ */
+export declare function resolveLargeFileErrorAfterCleanup(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<unknown>;
+/**
+ * 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.
+ */
+export declare function cleanupAfterLargeFileError(err: unknown, raw: RawClient, accountInfo: AccountInfo, context: LargeFileCleanupContext, options?: LargeFileCleanupPolicyOptions): Promise<never>;
 //# sourceMappingURL=cancel.d.ts.map

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