@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/scanners/b2.cjs

@@ -1,57 +1,241 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const file = require("../../types/file.cjs");
-class B2Folder {
-  type = "b2";
-  bucket;
-  prefix;
-  /**
-   * Creates a new B2Folder for the given bucket and optional prefix.
-   * @param bucket - The B2 bucket to scan.
-   * @param prefix - Optional key prefix to restrict the scan scope.
-   */
-  constructor(bucket, prefix = "") {
-    this.bucket = bucket;
-    this.prefix = prefix;
-  }
-  /** Lists all file versions in the bucket, groups by name, and yields the latest visible version. */
-  async *scan() {
-    const grouped = /* @__PURE__ */ new Map();
-    let startFileName;
-    let startFileId;
-    while (true) {
-      const listing = await this.bucket.listFileVersions({
-        ...this.prefix !== "" ? { prefix: this.prefix } : {},
-        ...startFileName !== void 0 ? { startFileName } : {},
-        ...startFileId !== void 0 ? { startFileId } : {}
-      });
-      for (const fv of listing.files) {
-        const existing = grouped.get(fv.fileName);
-        if (existing) {
-          existing.push(fv);
-        } else {
-          grouped.set(fv.fileName, [fv]);
-        }
-      }
-      if (!listing.nextFileName) break;
-      startFileName = listing.nextFileName;
-      startFileId = listing.nextFileId;
-    }
-    const sorted = [...grouped.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-    for (const [fileName, versions] of sorted) {
-      versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp);
-      const selected = versions[0];
-      if (!selected || selected.action === file.FileAction.Hide) continue;
-      const relativePath = this.prefix !== "" ? fileName.slice(this.prefix.length) : fileName;
-      yield {
-        relativePath,
-        modTimeMillis: selected.uploadTimestamp,
-        size: selected.contentLength,
-        selectedVersion: selected,
-        allVersions: versions
-      };
-    }
-  }
+const require_file = require("../../types/file.cjs");
+const require_regexp_safety = require("../regexp-safety.cjs");
+const require_scan_events = require("../scan-events.cjs");
+const require_filters = require("../filters.cjs");
+const require_path_order = require("../path-order.cjs");
+const require_scan_limit = require("../scan-limit.cjs");
+const require_error_reason = require("../../util/error-reason.cjs");
+const require_local_sha1 = require("../local-sha1.cjs");
+const require_sha1_metadata = require("../sha1-metadata.cjs");
+const require_path_safety = require("../path-safety.cjs");
+const require_prefix = require("../prefix.cjs");
+//#region src/sync/scanners/b2.ts
+var MAX_EMPTY_B2_SCAN_PAGES = 100;
+/**
+* Scans a B2 bucket (optionally filtered by a raw B2 key prefix) and yields
+* {@link B2SyncPath} entries sorted by `compareSyncRelativePaths(relativePath)`. Hidden files are excluded.
+* Raw B2 file names are used only as an internal tie-breaker after collision handling.
+* All versions for the listed prefix are fetched, grouped, and sorted before
+* yielding; exclude filters are applied client-side and do not reduce that
+* B2 listing memory footprint.
+* SDK-reserved temporary names fail the scan because syncing them could corrupt
+* in-progress transfers.
+*/
+var B2Folder = class {
+	type = "b2";
+	appliesScanFilters = true;
+	appliesScanSorting = true;
+	/** Raw B2 key prefix this folder scans, preserving caller-provided separators verbatim. */
+	rawPrefix;
+	bucket;
+	/**
+	* Creates a new B2Folder for the given bucket and optional prefix.
+	* @param bucket - The B2 bucket to scan.
+	* @param prefix - Optional raw B2 key prefix to restrict the scan scope.
+	* Backslashes are preserved as raw B2 key characters; pass `/` explicitly for slash prefixes.
+	*/
+	constructor(bucket, prefix = "") {
+		this.bucket = bucket;
+		this.rawPrefix = require_prefix.asRawB2KeyPrefix(prefix);
+	}
+	/**
+	* Lists all file versions in the bucket, groups by name, and yields the latest visible version.
+	* @param options - Optional scan controls.
+	*/
+	async *scan(options = {}) {
+		require_regexp_safety.validateSyncFilters(options);
+		const maxScanEntries = require_scan_limit.scanEntryLimit(options);
+		const grouped = /* @__PURE__ */ new Map();
+		const listPrefix = this.listPrefixFor(options);
+		let listedVersions = 0;
+		let startFileName;
+		let startFileId;
+		let emptyPageCount = 0;
+		while (true) {
+			if (scanIsAborted(options)) return;
+			let listing;
+			try {
+				listing = await this.bucket.listFileVersions({
+					...listPrefix !== "" ? { prefix: listPrefix } : {},
+					...startFileName !== void 0 ? { startFileName } : {},
+					...startFileId !== void 0 ? { startFileId } : {},
+					...options.signal !== void 0 ? { signal: options.signal } : {}
+				});
+			} catch (err) {
+				if (scanIsAborted(options) || require_local_sha1.isAbortError(err)) return;
+				throw emitScanError(options, "failed to scan B2 file versions", err);
+			}
+			if (scanIsAborted(options)) return;
+			if (listing.files.length === 0) {
+				emptyPageCount++;
+				if (emptyPageCount > MAX_EMPTY_B2_SCAN_PAGES) throw emitScanError(options, "failed to scan B2 file versions", /* @__PURE__ */ new Error("B2 pagination returned too many empty pages"));
+			} else emptyPageCount = 0;
+			for (const fv of listing.files) {
+				if (scanIsAborted(options)) return;
+				require_scan_limit.assertScanEntryLimit(listedVersions + 1, maxScanEntries);
+				listedVersions++;
+				if (this.rawPrefix !== "" && !fv.fileName.startsWith(this.rawPrefix)) {
+					this.emitSkip(options, fv.fileName, fv.fileName, "outside-prefix", `listed object is outside configured B2 prefix ${JSON.stringify(this.rawPrefix)}`);
+					continue;
+				}
+				if (options.requireLocalSafePaths === true && fv.fileName.includes("\\")) {
+					this.emitSkip(options, fv.fileName, fv.fileName, "local-unsafe-name", "object name contains a backslash that is unsafe for local filesystem destinations");
+					continue;
+				}
+				const relativePath = this.tryToRelativePath(fv.fileName);
+				if (relativePath === null) {
+					this.emitSkip(options, fv.fileName, fv.fileName, "unsafe-name", "object name cannot be represented as a safe sync relative path");
+					continue;
+				}
+				if (!require_filters.pathPassesSyncFilters(relativePath, options)) {
+					if (require_filters.pathSkippedByRegExpInputLimit(relativePath, options)) require_scan_events.emitScannerSkip(options, {
+						...require_scan_events.regexpInputTooLongSkip(relativePath),
+						b2FileName: fv.fileName
+					});
+					continue;
+				}
+				const existing = grouped.get(fv.fileName);
+				if (existing) existing.versions.push(fv);
+				else grouped.set(fv.fileName, {
+					relativePath,
+					versions: [fv]
+				});
+			}
+			if (!listing.nextFileName) break;
+			if (listing.nextFileName === startFileName && (listing.nextFileId ?? void 0) === startFileId) throw emitScanError(options, "failed to scan B2 file versions", /* @__PURE__ */ new Error("B2 pagination did not advance"));
+			startFileName = listing.nextFileName;
+			startFileId = listing.nextFileId ?? void 0;
+		}
+		const visible = this.visibleCandidates(grouped, options);
+		const withoutRelativeCollisions = this.rejectRelativePathCollisions(visible, options);
+		const sorted = (options.requireLocalSafePaths === true ? this.rejectLocalPathCollisions(withoutRelativeCollisions, options) : withoutRelativeCollisions).sort((a, b) => require_path_order.compareSyncRelativePaths(a.relativePath, b.relativePath) || require_path_order.compareCodeUnits(a.fileName, b.fileName));
+		for (const { relativePath, versions, selectedVersion } of sorted) {
+			if (scanIsAborted(options)) return;
+			require_path_safety.assertSyncPathAllowed(relativePath);
+			const contentSha1 = require_sha1_metadata.selectB2ComparableSha1(selectedVersion);
+			yield {
+				relativePath,
+				modTimeMillis: selectedVersion.uploadTimestamp,
+				size: selectedVersion.contentLength,
+				contentSha1,
+				contentSha1State: require_sha1_metadata.syncSha1StateOf({ contentSha1 }),
+				selectedVersion,
+				allVersions: versions
+			};
+		}
+	}
+	tryToRelativePath(fileName) {
+		try {
+			return require_prefix.b2KeyToRelativePathUnderPrefix(this.rawPrefix, fileName);
+		} catch {
+			return null;
+		}
+	}
+	listPrefixFor(filters) {
+		const filterPrefix = require_filters.literalPrefixForSyncFilters(filters);
+		if (filterPrefix === "") return this.rawPrefix;
+		if (this.rawPrefix !== "" && !this.rawPrefix.endsWith("/")) return this.rawPrefix;
+		return `${this.rawPrefix}${rawPrefixBeforeNormalizedSeparator(filterPrefix)}`;
+	}
+	visibleCandidates(grouped, filters) {
+		const visible = [];
+		for (const [fileName, entry] of grouped) {
+			entry.versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp);
+			const selected = entry.versions[0];
+			if (!selected || selected.action === require_file.FileAction.Hide) continue;
+			if (filters?.requireLocalSafePaths === true && require_prefix.localFilesystemSyncPathIsUnsafe(entry.relativePath)) {
+				this.emitSkip(filters, entry.relativePath, fileName, "local-unsafe-name", "object name is unsafe for a local filesystem destination");
+				continue;
+			}
+			visible.push({
+				fileName,
+				relativePath: entry.relativePath,
+				versions: entry.versions,
+				selectedVersion: selected
+			});
+		}
+		return visible;
+	}
+	rejectRelativePathCollisions(candidates, filters) {
+		const accepted = [];
+		const owners = /* @__PURE__ */ new Map();
+		const collidedRelativePaths = /* @__PURE__ */ new Set();
+		for (const candidate of candidates) {
+			if (collidedRelativePaths.has(candidate.relativePath)) {
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "relative-path-collision", "object normalizes to a relative path already rejected because of another raw B2 key");
+				continue;
+			}
+			const owner = owners.get(candidate.relativePath);
+			if (owner !== void 0 && owner.fileName !== candidate.fileName) {
+				owners.delete(candidate.relativePath);
+				removeAcceptedCandidate(accepted, owner);
+				collidedRelativePaths.add(candidate.relativePath);
+				this.emitSkip(filters, candidate.relativePath, owner.fileName, "relative-path-collision", `object normalizes to the same relative path as ${JSON.stringify(candidate.fileName)}`);
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "relative-path-collision", `object normalizes to the same relative path as ${JSON.stringify(owner.fileName)}`);
+				continue;
+			}
+			owners.set(candidate.relativePath, candidate);
+			accepted.push(candidate);
+		}
+		return accepted;
+	}
+	rejectLocalPathCollisions(candidates, filters) {
+		const accepted = [];
+		const owners = /* @__PURE__ */ new Map();
+		const collidedLocalPaths = /* @__PURE__ */ new Set();
+		for (const candidate of candidates) {
+			const canonicalPath = require_prefix.localFilesystemCanonicalSyncPath(candidate.relativePath);
+			if (collidedLocalPaths.has(canonicalPath)) {
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "local-path-collision", "object collides with another object on case-insensitive or Unicode-normalizing filesystems");
+				continue;
+			}
+			const owner = owners.get(canonicalPath);
+			if (owner !== void 0) {
+				owners.delete(canonicalPath);
+				removeAcceptedCandidate(accepted, owner);
+				collidedLocalPaths.add(canonicalPath);
+				this.emitSkip(filters, owner.relativePath, owner.fileName, "local-path-collision", `object collides with ${JSON.stringify(candidate.fileName)} on local filesystems`);
+				this.emitSkip(filters, candidate.relativePath, candidate.fileName, "local-path-collision", `object collides with ${JSON.stringify(owner.fileName)} on local filesystems`);
+				continue;
+			}
+			owners.set(canonicalPath, candidate);
+			accepted.push(candidate);
+		}
+		return accepted;
+	}
+	emitSkip(filters, path, b2FileName, reason, message) {
+		require_scan_events.emitScannerSkip(filters, {
+			type: "skip",
+			path,
+			size: 0,
+			message: `Skipped B2 object ${JSON.stringify(b2FileName)}: ${message}`,
+			reason,
+			b2FileName
+		});
+	}
+};
+function rawPrefixBeforeNormalizedSeparator(filterPrefix) {
+	const separatorIndex = filterPrefix.indexOf("/");
+	return separatorIndex === -1 ? filterPrefix : filterPrefix.slice(0, separatorIndex);
 }
+function emitScanError(options, message, err) {
+	const event = {
+		type: "error",
+		path: "",
+		size: 0,
+		message: `${message}: ${require_error_reason.sanitizeErrorReason(err)}`
+	};
+	options.onError?.(event);
+	return new Error(event.message);
+}
+function removeAcceptedCandidate(candidates, target) {
+	const index = candidates.indexOf(target);
+	if (index !== -1) candidates.splice(index, 1);
+}
+function scanIsAborted(filters) {
+	return filters?.signal?.aborted === true;
+}
+//#endregion
 exports.B2Folder = B2Folder;
-//# sourceMappingURL=b2.cjs.map
+
+//# sourceMappingURL=b2.cjs.map

package/dist/sync/scanners/b2.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"b2.cjs","sources":["../../../src/sync/scanners/b2.ts"],"sourcesContent":["import type { Bucket } from '../../bucket.ts'\nimport { FileAction, type FileVersion } from '../../types/file.ts'\nimport type { B2SyncPath, SyncFolder } from '../types.ts'\n\n/**\n * Scans a B2 bucket (optionally filtered by prefix) and yields {@link B2SyncPath} entries\n * sorted by file name. Hidden files are excluded. All versions are fetched and grouped.\n */\nexport class B2Folder implements SyncFolder {\n  readonly type = 'b2' as const\n  private readonly bucket: Bucket\n  private readonly prefix: string\n\n  /**\n   * Creates a new B2Folder for the given bucket and optional prefix.\n   * @param bucket - The B2 bucket to scan.\n   * @param prefix - Optional key prefix to restrict the scan scope.\n   */\n  constructor(bucket: Bucket, prefix = '') {\n    this.bucket = bucket\n    this.prefix = prefix\n  }\n\n  /** Lists all file versions in the bucket, groups by name, and yields the latest visible version. */\n  async *scan(): AsyncGenerator<B2SyncPath> {\n    const grouped = new Map<string, FileVersion[]>()\n\n    let startFileName: string | undefined\n    let startFileId: string | undefined\n\n    while (true) {\n      const listing = await this.bucket.listFileVersions({\n        ...(this.prefix !== '' ? { prefix: this.prefix } : {}),\n        ...(startFileName !== undefined ? { startFileName } : {}),\n        ...(startFileId !== undefined\n          ? { startFileId: startFileId as import('../../types/ids.ts').FileId }\n          : {}),\n      })\n\n      for (const fv of listing.files) {\n        const existing = grouped.get(fv.fileName)\n        if (existing) {\n          existing.push(fv)\n        } else {\n          grouped.set(fv.fileName, [fv])\n        }\n      }\n\n      if (!listing.nextFileName) break\n      startFileName = listing.nextFileName\n      startFileId = listing.nextFileId as string | undefined\n    }\n\n    const sorted = [...grouped.entries()].sort((a, b) => a[0].localeCompare(b[0]))\n\n    for (const [fileName, versions] of sorted) {\n      versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp)\n      const selected = versions[0]\n      if (!selected || selected.action === FileAction.Hide) continue\n\n      const relativePath = this.prefix !== '' ? fileName.slice(this.prefix.length) : fileName\n\n      yield {\n        relativePath,\n        modTimeMillis: selected.uploadTimestamp,\n        size: selected.contentLength,\n        selectedVersion: selected,\n        allVersions: versions,\n      }\n    }\n  }\n}\n"],"names":["FileAction"],"mappings":";;;AAQO,MAAM,SAA+B;AAAA,EACjC,OAAO;AAAA,EACC;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOjB,YAAY,QAAgB,SAAS,IAAI;AACvC,SAAK,SAAS;AACd,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA,EAGA,OAAO,OAAmC;AACxC,UAAM,8BAAc,IAAA;AAEpB,QAAI;AACJ,QAAI;AAEJ,WAAO,MAAM;AACX,YAAM,UAAU,MAAM,KAAK,OAAO,iBAAiB;AAAA,QACjD,GAAI,KAAK,WAAW,KAAK,EAAE,QAAQ,KAAK,OAAA,IAAW,CAAA;AAAA,QACnD,GAAI,kBAAkB,SAAY,EAAE,cAAA,IAAkB,CAAA;AAAA,QACtD,GAAI,gBAAgB,SAChB,EAAE,gBACF,CAAA;AAAA,MAAC,CACN;AAED,iBAAW,MAAM,QAAQ,OAAO;AAC9B,cAAM,WAAW,QAAQ,IAAI,GAAG,QAAQ;AACxC,YAAI,UAAU;AACZ,mBAAS,KAAK,EAAE;AAAA,QAClB,OAAO;AACL,kBAAQ,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC;AAAA,QAC/B;AAAA,MACF;AAEA,UAAI,CAAC,QAAQ,aAAc;AAC3B,sBAAgB,QAAQ;AACxB,oBAAc,QAAQ;AAAA,IACxB;AAEA,UAAM,SAAS,CAAC,GAAG,QAAQ,QAAA,CAAS,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;AAE7E,eAAW,CAAC,UAAU,QAAQ,KAAK,QAAQ;AACzC,eAAS,KAAK,CAAC,GAAG,MAAM,EAAE,kBAAkB,EAAE,eAAe;AAC7D,YAAM,WAAW,SAAS,CAAC;AAC3B,UAAI,CAAC,YAAY,SAAS,WAAWA,KAAAA,WAAW,KAAM;AAEtD,YAAM,eAAe,KAAK,WAAW,KAAK,SAAS,MAAM,KAAK,OAAO,MAAM,IAAI;AAE/E,YAAM;AAAA,QACJ;AAAA,QACA,eAAe,SAAS;AAAA,QACxB,MAAM,SAAS;AAAA,QACf,iBAAiB;AAAA,QACjB,aAAa;AAAA,MAAA;AAAA,IAEjB;AAAA,EACF;AACF;;"}
+{"version":3,"file":"b2.cjs","names":[],"sources":["../../../src/sync/scanners/b2.ts"],"sourcesContent":["import type { Bucket } from '../../bucket.ts'\nimport { FileAction, type FileVersion } from '../../types/file.ts'\nimport type { FileId } from '../../types/ids.ts'\nimport { sanitizeErrorReason } from '../../util/error-reason.ts'\nimport {\n  literalPrefixForSyncFilters,\n  pathPassesSyncFilters,\n  pathSkippedByRegExpInputLimit,\n} from '../filters.ts'\nimport { isAbortError } from '../local-sha1.ts'\nimport { compareCodeUnits, compareSyncRelativePaths } from '../path-order.ts'\nimport { assertSyncPathAllowed } from '../paths.ts'\nimport {\n  asRawB2KeyPrefix,\n  b2KeyToRelativePathUnderPrefix,\n  localFilesystemCanonicalSyncPath,\n  localFilesystemSyncPathIsUnsafe,\n} from '../prefix.ts'\nimport { validateSyncFilters } from '../regexp-safety.ts'\nimport { emitScannerSkip, regexpInputTooLongSkip } from '../scan-events.ts'\nimport { assertScanEntryLimit, scanEntryLimit } from '../scan-limit.ts'\nimport { selectB2ComparableSha1, syncSha1StateOf } from '../sha1-metadata.ts'\nimport type {\n  B2SyncPath,\n  SyncErrorEvent,\n  SyncFolder,\n  SyncScanOptions,\n  SyncSkipReason,\n} from '../types.ts'\n\nconst MAX_EMPTY_B2_SCAN_PAGES = 100\n\ninterface B2ScanEntry {\n  relativePath: string\n  versions: FileVersion[]\n}\n\ninterface VisibleB2ScanEntry extends B2ScanEntry {\n  fileName: string\n  selectedVersion: FileVersion\n}\n\n/**\n * Scans a B2 bucket (optionally filtered by a raw B2 key prefix) and yields\n * {@link B2SyncPath} entries sorted by `compareSyncRelativePaths(relativePath)`. Hidden files are excluded.\n * Raw B2 file names are used only as an internal tie-breaker after collision handling.\n * All versions for the listed prefix are fetched, grouped, and sorted before\n * yielding; exclude filters are applied client-side and do not reduce that\n * B2 listing memory footprint.\n * SDK-reserved temporary names fail the scan because syncing them could corrupt\n * in-progress transfers.\n */\nexport class B2Folder implements SyncFolder {\n  readonly type = 'b2' as const\n  readonly appliesScanFilters = true as const\n  readonly appliesScanSorting = true as const\n  /** Raw B2 key prefix this folder scans, preserving caller-provided separators verbatim. */\n  readonly rawPrefix: string\n  private readonly bucket: Bucket\n\n  /**\n   * Creates a new B2Folder for the given bucket and optional prefix.\n   * @param bucket - The B2 bucket to scan.\n   * @param prefix - Optional raw B2 key prefix to restrict the scan scope.\n   * Backslashes are preserved as raw B2 key characters; pass `/` explicitly for slash prefixes.\n   */\n  constructor(bucket: Bucket, prefix = '') {\n    this.bucket = bucket\n    this.rawPrefix = asRawB2KeyPrefix(prefix)\n  }\n\n  /**\n   * Lists all file versions in the bucket, groups by name, and yields the latest visible version.\n   * @param options - Optional scan controls.\n   */\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: pagination, grouping, and filtering stay in one async iterator.\n  async *scan(options: SyncScanOptions = {}): AsyncGenerator<B2SyncPath> {\n    validateSyncFilters(options)\n    const maxScanEntries = scanEntryLimit(options)\n    const grouped = new Map<string, B2ScanEntry>()\n    const listPrefix = this.listPrefixFor(options)\n\n    let listedVersions = 0\n    let startFileName: string | undefined\n    let startFileId: FileId | undefined\n    let emptyPageCount = 0\n\n    while (true) {\n      if (scanIsAborted(options)) return\n\n      let listing: Awaited<ReturnType<Bucket['listFileVersions']>>\n      try {\n        listing = await this.bucket.listFileVersions({\n          ...(listPrefix !== '' ? { prefix: listPrefix } : {}),\n          ...(startFileName !== undefined ? { startFileName } : {}),\n          ...(startFileId !== undefined ? { startFileId } : {}),\n          ...(options.signal !== undefined ? { signal: options.signal } : {}),\n        })\n      } catch (err) {\n        if (scanIsAborted(options) || isAbortError(err)) return\n        throw emitScanError(options, 'failed to scan B2 file versions', err)\n      }\n      if (scanIsAborted(options)) return\n\n      if (listing.files.length === 0) {\n        emptyPageCount++\n        if (emptyPageCount > MAX_EMPTY_B2_SCAN_PAGES) {\n          throw emitScanError(\n            options,\n            'failed to scan B2 file versions',\n            new Error('B2 pagination returned too many empty pages'),\n          )\n        }\n      } else {\n        emptyPageCount = 0\n      }\n\n      for (const fv of listing.files) {\n        if (scanIsAborted(options)) return\n        assertScanEntryLimit(listedVersions + 1, maxScanEntries)\n        listedVersions++\n\n        // Real B2 honors the prefix in listFileVersions, but custom\n        // transports and the simulator can over-return. Guard before\n        // stripping the raw prefix so relativePath is never corrupted.\n        if (this.rawPrefix !== '' && !fv.fileName.startsWith(this.rawPrefix)) {\n          this.emitSkip(\n            options,\n            fv.fileName,\n            fv.fileName,\n            'outside-prefix',\n            `listed object is outside configured B2 prefix ${JSON.stringify(this.rawPrefix)}`,\n          )\n          continue\n        }\n\n        if (options.requireLocalSafePaths === true && fv.fileName.includes('\\\\')) {\n          this.emitSkip(\n            options,\n            fv.fileName,\n            fv.fileName,\n            'local-unsafe-name',\n            'object name contains a backslash that is unsafe for local filesystem destinations',\n          )\n          continue\n        }\n\n        const relativePath = this.tryToRelativePath(fv.fileName)\n        if (relativePath === null) {\n          this.emitSkip(\n            options,\n            fv.fileName,\n            fv.fileName,\n            'unsafe-name',\n            'object name cannot be represented as a safe sync relative path',\n          )\n          continue\n        }\n\n        if (!pathPassesSyncFilters(relativePath, options)) {\n          if (pathSkippedByRegExpInputLimit(relativePath, options)) {\n            emitScannerSkip(options, {\n              ...regexpInputTooLongSkip(relativePath),\n              b2FileName: fv.fileName,\n            })\n          }\n          continue\n        }\n\n        const existing = grouped.get(fv.fileName)\n        if (existing) {\n          existing.versions.push(fv)\n        } else {\n          grouped.set(fv.fileName, { relativePath, versions: [fv] })\n        }\n      }\n\n      if (!listing.nextFileName) break\n      if (\n        listing.nextFileName === startFileName &&\n        (listing.nextFileId ?? undefined) === startFileId\n      ) {\n        throw emitScanError(\n          options,\n          'failed to scan B2 file versions',\n          new Error('B2 pagination did not advance'),\n        )\n      }\n      startFileName = listing.nextFileName\n      startFileId = listing.nextFileId ?? undefined\n    }\n\n    const visible = this.visibleCandidates(grouped, options)\n    const withoutRelativeCollisions = this.rejectRelativePathCollisions(visible, options)\n    const safeCandidates =\n      options.requireLocalSafePaths === true\n        ? this.rejectLocalPathCollisions(withoutRelativeCollisions, options)\n        : withoutRelativeCollisions\n    const sorted = safeCandidates.sort(\n      (a, b) =>\n        compareSyncRelativePaths(a.relativePath, b.relativePath) ||\n        compareCodeUnits(a.fileName, b.fileName),\n    )\n\n    for (const { relativePath, versions, selectedVersion } of sorted) {\n      if (scanIsAborted(options)) return\n      // Reserved SDK temp names are a hard safety failure, not an ordinary filter.\n      assertSyncPathAllowed(relativePath)\n      const contentSha1 = selectB2ComparableSha1(selectedVersion)\n      yield {\n        relativePath,\n        modTimeMillis: selectedVersion.uploadTimestamp,\n        size: selectedVersion.contentLength,\n        contentSha1,\n        contentSha1State: syncSha1StateOf({ contentSha1 }),\n        selectedVersion,\n        allVersions: versions,\n      }\n    }\n  }\n\n  private tryToRelativePath(fileName: string): string | null {\n    try {\n      return b2KeyToRelativePathUnderPrefix(this.rawPrefix, fileName)\n    } catch {\n      return null\n    }\n  }\n\n  private listPrefixFor(filters: SyncScanOptions | undefined): string {\n    const filterPrefix = literalPrefixForSyncFilters(filters)\n    if (filterPrefix === '') return this.rawPrefix\n    if (this.rawPrefix !== '' && !this.rawPrefix.endsWith('/')) return this.rawPrefix\n    return `${this.rawPrefix}${rawPrefixBeforeNormalizedSeparator(filterPrefix)}`\n  }\n\n  private visibleCandidates(\n    grouped: Map<string, B2ScanEntry>,\n    filters: SyncScanOptions | undefined,\n  ): VisibleB2ScanEntry[] {\n    const visible: VisibleB2ScanEntry[] = []\n\n    for (const [fileName, entry] of grouped) {\n      entry.versions.sort((a, b) => b.uploadTimestamp - a.uploadTimestamp)\n      const selected = entry.versions[0]\n      if (!selected || selected.action === FileAction.Hide) continue\n\n      if (\n        filters?.requireLocalSafePaths === true &&\n        localFilesystemSyncPathIsUnsafe(entry.relativePath)\n      ) {\n        this.emitSkip(\n          filters,\n          entry.relativePath,\n          fileName,\n          'local-unsafe-name',\n          'object name is unsafe for a local filesystem destination',\n        )\n        continue\n      }\n\n      visible.push({\n        fileName,\n        relativePath: entry.relativePath,\n        versions: entry.versions,\n        selectedVersion: selected,\n      })\n    }\n\n    return visible\n  }\n\n  private rejectRelativePathCollisions(\n    candidates: VisibleB2ScanEntry[],\n    filters: SyncScanOptions | undefined,\n  ): VisibleB2ScanEntry[] {\n    const accepted: VisibleB2ScanEntry[] = []\n    const owners = new Map<string, VisibleB2ScanEntry>()\n    const collidedRelativePaths = new Set<string>()\n\n    for (const candidate of candidates) {\n      if (collidedRelativePaths.has(candidate.relativePath)) {\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'relative-path-collision',\n          'object normalizes to a relative path already rejected because of another raw B2 key',\n        )\n        continue\n      }\n\n      const owner = owners.get(candidate.relativePath)\n      if (owner !== undefined && owner.fileName !== candidate.fileName) {\n        owners.delete(candidate.relativePath)\n        removeAcceptedCandidate(accepted, owner)\n        collidedRelativePaths.add(candidate.relativePath)\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          owner.fileName,\n          'relative-path-collision',\n          `object normalizes to the same relative path as ${JSON.stringify(candidate.fileName)}`,\n        )\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'relative-path-collision',\n          `object normalizes to the same relative path as ${JSON.stringify(owner.fileName)}`,\n        )\n        continue\n      }\n\n      owners.set(candidate.relativePath, candidate)\n      accepted.push(candidate)\n    }\n\n    return accepted\n  }\n\n  private rejectLocalPathCollisions(\n    candidates: VisibleB2ScanEntry[],\n    filters: SyncScanOptions | undefined,\n  ): VisibleB2ScanEntry[] {\n    const accepted: VisibleB2ScanEntry[] = []\n    const owners = new Map<string, VisibleB2ScanEntry>()\n    const collidedLocalPaths = new Set<string>()\n\n    for (const candidate of candidates) {\n      const canonicalPath = localFilesystemCanonicalSyncPath(candidate.relativePath)\n      if (collidedLocalPaths.has(canonicalPath)) {\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'local-path-collision',\n          'object collides with another object on case-insensitive or Unicode-normalizing filesystems',\n        )\n        continue\n      }\n\n      const owner = owners.get(canonicalPath)\n      if (owner !== undefined) {\n        owners.delete(canonicalPath)\n        removeAcceptedCandidate(accepted, owner)\n        collidedLocalPaths.add(canonicalPath)\n        this.emitSkip(\n          filters,\n          owner.relativePath,\n          owner.fileName,\n          'local-path-collision',\n          `object collides with ${JSON.stringify(candidate.fileName)} on local filesystems`,\n        )\n        this.emitSkip(\n          filters,\n          candidate.relativePath,\n          candidate.fileName,\n          'local-path-collision',\n          `object collides with ${JSON.stringify(owner.fileName)} on local filesystems`,\n        )\n        continue\n      }\n\n      owners.set(canonicalPath, candidate)\n      accepted.push(candidate)\n    }\n\n    return accepted\n  }\n\n  private emitSkip(\n    filters: SyncScanOptions | undefined,\n    path: string,\n    b2FileName: string,\n    reason: SyncSkipReason,\n    message: string,\n  ): void {\n    emitScannerSkip(filters, {\n      type: 'skip',\n      path,\n      size: 0,\n      message: `Skipped B2 object ${JSON.stringify(b2FileName)}: ${message}`,\n      reason,\n      b2FileName,\n    })\n  }\n}\n\nfunction rawPrefixBeforeNormalizedSeparator(filterPrefix: string): string {\n  const separatorIndex = filterPrefix.indexOf('/')\n  return separatorIndex === -1 ? filterPrefix : filterPrefix.slice(0, separatorIndex)\n}\n\nfunction emitScanError(options: SyncScanOptions, message: string, err: unknown): Error {\n  const event: SyncErrorEvent = {\n    type: 'error',\n    path: '',\n    size: 0,\n    message: `${message}: ${sanitizeErrorReason(err)}`,\n  }\n  options.onError?.(event)\n  return new Error(event.message)\n}\n\nfunction removeAcceptedCandidate(\n  candidates: VisibleB2ScanEntry[],\n  target: VisibleB2ScanEntry,\n): void {\n  const index = candidates.indexOf(target)\n  if (index !== -1) candidates.splice(index, 1)\n}\n\nfunction scanIsAborted(filters: SyncScanOptions | undefined): boolean {\n  return filters?.signal?.aborted === true\n}\n"],"mappings":"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"}

package/dist/sync/scanners/b2.d.cts

@@ -1,20 +1,39 @@
 import { Bucket } from '../../bucket.js';
-import { B2SyncPath, SyncFolder } from '../types.js';
+import { B2SyncPath, SyncFolder, SyncScanOptions } from '../types.js';
 /**
- * Scans a B2 bucket (optionally filtered by prefix) and yields {@link B2SyncPath} entries
- * sorted by file name. Hidden files are excluded. All versions are fetched and grouped.
+ * Scans a B2 bucket (optionally filtered by a raw B2 key prefix) and yields
+ * {@link B2SyncPath} entries sorted by `compareSyncRelativePaths(relativePath)`. Hidden files are excluded.
+ * Raw B2 file names are used only as an internal tie-breaker after collision handling.
+ * All versions for the listed prefix are fetched, grouped, and sorted before
+ * yielding; exclude filters are applied client-side and do not reduce that
+ * B2 listing memory footprint.
+ * SDK-reserved temporary names fail the scan because syncing them could corrupt
+ * in-progress transfers.
  */
 export declare class B2Folder implements SyncFolder {
     readonly type: "b2";
+    readonly appliesScanFilters: true;
+    readonly appliesScanSorting: true;
+    /** Raw B2 key prefix this folder scans, preserving caller-provided separators verbatim. */
+    readonly rawPrefix: string;
     private readonly bucket;
-    private readonly prefix;
     /**
      * Creates a new B2Folder for the given bucket and optional prefix.
      * @param bucket - The B2 bucket to scan.
-     * @param prefix - Optional key prefix to restrict the scan scope.
+     * @param prefix - Optional raw B2 key prefix to restrict the scan scope.
+     * Backslashes are preserved as raw B2 key characters; pass `/` explicitly for slash prefixes.
      */
     constructor(bucket: Bucket, prefix?: string);
-    /** Lists all file versions in the bucket, groups by name, and yields the latest visible version. */
-    scan(): AsyncGenerator<B2SyncPath>;
+    /**
+     * Lists all file versions in the bucket, groups by name, and yields the latest visible version.
+     * @param options - Optional scan controls.
+     */
+    scan(options?: SyncScanOptions): AsyncGenerator<B2SyncPath>;
+    private tryToRelativePath;
+    private listPrefixFor;
+    private visibleCandidates;
+    private rejectRelativePathCollisions;
+    private rejectLocalPathCollisions;
+    private emitSkip;
 }
 //# sourceMappingURL=b2.d.ts.map

package/dist/sync/scanners/b2.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"b2.d.ts","sourceRoot":"","sources":["../../../src/sync/scanners/b2.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEzD;;;GAGG;AACH,qBAAa,QAAS,YAAW,UAAU;IACzC,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B;;;;OAIG;gBACS,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK;IAKvC,oGAAoG;IAC7F,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC;CA+C1C"}
+{"version":3,"file":"b2.d.ts","sourceRoot":"","sources":["../../../src/sync/scanners/b2.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAsB7C,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EACV,eAAe,EAEhB,MAAM,aAAa,CAAA;AAcpB;;;;;;;;;GASG;AACH,qBAAa,QAAS,YAAW,UAAU;IACzC,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAS;IAC7B,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK;IAKvC;;;OAGG;IAEI,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAAC,UAAU,CAAC;IAiJtE,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,iBAAiB;IAoCzB,OAAO,CAAC,4BAA4B;IAiDpC,OAAO,CAAC,yBAAyB;IAkDjC,OAAO,CAAC,QAAQ;CAgBjB"}

package/dist/sync/scanners/b2.d.ts

@@ -1,20 +1,39 @@
 import { Bucket } from '../../bucket.js';
-import { B2SyncPath, SyncFolder } from '../types.js';
+import { B2SyncPath, SyncFolder, SyncScanOptions } from '../types.js';
 /**
- * Scans a B2 bucket (optionally filtered by prefix) and yields {@link B2SyncPath} entries
- * sorted by file name. Hidden files are excluded. All versions are fetched and grouped.
+ * Scans a B2 bucket (optionally filtered by a raw B2 key prefix) and yields
+ * {@link B2SyncPath} entries sorted by `compareSyncRelativePaths(relativePath)`. Hidden files are excluded.
+ * Raw B2 file names are used only as an internal tie-breaker after collision handling.
+ * All versions for the listed prefix are fetched, grouped, and sorted before
+ * yielding; exclude filters are applied client-side and do not reduce that
+ * B2 listing memory footprint.
+ * SDK-reserved temporary names fail the scan because syncing them could corrupt
+ * in-progress transfers.
  */
 export declare class B2Folder implements SyncFolder {
     readonly type: "b2";
+    readonly appliesScanFilters: true;
+    readonly appliesScanSorting: true;
+    /** Raw B2 key prefix this folder scans, preserving caller-provided separators verbatim. */
+    readonly rawPrefix: string;
     private readonly bucket;
-    private readonly prefix;
     /**
      * Creates a new B2Folder for the given bucket and optional prefix.
      * @param bucket - The B2 bucket to scan.
-     * @param prefix - Optional key prefix to restrict the scan scope.
+     * @param prefix - Optional raw B2 key prefix to restrict the scan scope.
+     * Backslashes are preserved as raw B2 key characters; pass `/` explicitly for slash prefixes.
      */
     constructor(bucket: Bucket, prefix?: string);
-    /** Lists all file versions in the bucket, groups by name, and yields the latest visible version. */
-    scan(): AsyncGenerator<B2SyncPath>;
+    /**
+     * Lists all file versions in the bucket, groups by name, and yields the latest visible version.
+     * @param options - Optional scan controls.
+     */
+    scan(options?: SyncScanOptions): AsyncGenerator<B2SyncPath>;
+    private tryToRelativePath;
+    private listPrefixFor;
+    private visibleCandidates;
+    private rejectRelativePathCollisions;
+    private rejectLocalPathCollisions;
+    private emitSkip;
 }
 //# sourceMappingURL=b2.d.ts.map

package/dist/sync/scanners/b2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"b2.d.ts","sourceRoot":"","sources":["../../../src/sync/scanners/b2.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEzD;;;GAGG;AACH,qBAAa,QAAS,YAAW,UAAU;IACzC,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B;;;;OAIG;gBACS,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK;IAKvC,oGAAoG;IAC7F,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC;CA+C1C"}
+{"version":3,"file":"b2.d.ts","sourceRoot":"","sources":["../../../src/sync/scanners/b2.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAsB7C,OAAO,KAAK,EACV,UAAU,EAEV,UAAU,EACV,eAAe,EAEhB,MAAM,aAAa,CAAA;AAcpB;;;;;;;;;GASG;AACH,qBAAa,QAAS,YAAW,UAAU;IACzC,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAS;IAC7B,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,QAAQ,CAAC,kBAAkB,EAAG,IAAI,CAAS;IAC3C,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK;IAKvC;;;OAGG;IAEI,IAAI,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAAC,UAAU,CAAC;IAiJtE,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,iBAAiB;IAoCzB,OAAO,CAAC,4BAA4B;IAiDpC,OAAO,CAAC,yBAAyB;IAkDjC,OAAO,CAAC,QAAQ;CAgBjB"}