@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/local-sha1.cjs

@@ -0,0 +1,119 @@
+const require_hash = require("../streams/hash.cjs");
+const require_to_error = require("../util/to-error.cjs");
+const require_error_reason = require("../util/error-reason.cjs");
+const require_local_file_identity = require("./local-file-identity.cjs");
+const require_sha1_options = require("./sha1-options.cjs");
+//#region src/sync/local-sha1.ts
+/**
+* Formats a hash error for public sync events without leaking filesystem paths.
+*
+* @param error - Error thrown while hashing.
+*
+* @returns A sanitized reason suitable for event messages.
+*/
+function formatHashError(error) {
+	return require_error_reason.sanitizeErrorReason(error);
+}
+/**
+* Returns whether an error represents an abort.
+*
+* @param err - Unknown thrown value.
+*
+* @returns True for AbortError values.
+*/
+function isAbortError(err) {
+	return require_to_error.toError(err).name === "AbortError";
+}
+/**
+* Reads a local file and computes its SHA-1 digest with non-regular-file rejection,
+* scanned-size bounds, abort support, and an idle/no-progress timeout.
+*
+* @param path - Local sync path to hash.
+* @param signal - Optional abort signal.
+* @param options - Optional idle timeout override.
+*
+* @returns The lowercase SHA-1 digest of the file bytes.
+*/
+async function readLocalSha1File(path, signal, options = {}) {
+	const { constants } = await import("node:fs");
+	const { lstat, open } = await import("node:fs/promises");
+	const timeoutMillis = require_sha1_options.normalizeSha1TimeoutMillis(options.timeoutMillis);
+	const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+	const hash = new require_hash.IncrementalSha1();
+	let stream;
+	let file;
+	let timeout;
+	function armTimeout(onTimeout) {
+		if (timeout !== void 0) clearTimeout(timeout);
+		timeout = setTimeout(onTimeout, timeoutMillis);
+	}
+	try {
+		signal?.throwIfAborted();
+		require_local_file_identity.assertSameScannedRegularFile(await withTimeout(lstat(path.absolutePath), timeoutMillis, "sha1 file status"), path, "sha1 comparison");
+		file = await openWithTimeout(open(path.absolutePath, flags), timeoutMillis);
+		require_local_file_identity.assertSameScannedRegularFile(await withTimeout(lstat(path.absolutePath), timeoutMillis, "sha1 file status"), path, "sha1 comparison");
+		require_local_file_identity.assertSameScannedRegularFile(await withTimeout(file.stat(), timeoutMillis, "sha1 file status"), path, "sha1 comparison");
+		stream = file.createReadStream({
+			...path.size > 0 ? {
+				start: 0,
+				end: path.size - 1
+			} : {},
+			...signal !== void 0 ? { signal } : {}
+		});
+		let bytesRead = 0;
+		/* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */
+		armTimeout(() => {
+			stream?.destroy(/* @__PURE__ */ new Error(`sha1 read stalled for ${timeoutMillis} ms`));
+		});
+		for await (const chunk of stream) {
+			bytesRead += chunk.byteLength;
+			await hash.update(chunk);
+			/* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */
+			armTimeout(() => {
+				stream?.destroy(/* @__PURE__ */ new Error(`sha1 read stalled for ${timeoutMillis} ms`));
+			});
+		}
+		/* v8 ignore next -- defensive TOCTOU guard after the bounded stream completes */
+		if (bytesRead !== path.size) throw new Error("file changed during sha1 comparison");
+		return hash.digest();
+	} finally {
+		if (timeout !== void 0) clearTimeout(timeout);
+		stream?.destroy();
+		await file?.close().catch(() => {});
+	}
+}
+/* v8 ignore start -- defensive stale-filesystem stall handling is not portable to trigger */
+async function withTimeout(promise, timeoutMillis, operation) {
+	let timeout;
+	try {
+		return await Promise.race([promise, new Promise((_, reject) => {
+			timeout = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`${operation} stalled for ${timeoutMillis} ms`));
+			}, timeoutMillis);
+		})]);
+	} finally {
+		if (timeout !== void 0) clearTimeout(timeout);
+	}
+}
+async function openWithTimeout(promise, timeoutMillis) {
+	let timedOut = false;
+	const tracked = promise.then((file) => {
+		if (timedOut) file.close().catch(() => {});
+		return file;
+	}, (err) => {
+		throw err;
+	});
+	try {
+		return await withTimeout(tracked, timeoutMillis, "sha1 file open");
+	} catch (err) {
+		timedOut = true;
+		throw err;
+	}
+}
+/* v8 ignore stop */
+//#endregion
+exports.formatHashError = formatHashError;
+exports.isAbortError = isAbortError;
+exports.readLocalSha1File = readLocalSha1File;
+
+//# sourceMappingURL=local-sha1.cjs.map

package/dist/sync/local-sha1.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-sha1.cjs","names":[],"sources":["../../src/sync/local-sha1.ts"],"sourcesContent":["import { IncrementalSha1 } from '../streams/hash.ts'\nimport { sanitizeErrorReason } from '../util/error-reason.ts'\nimport { toError } from '../util/to-error.ts'\nimport { assertSameScannedRegularFile } from './local-file-identity.ts'\nimport { normalizeSha1TimeoutMillis } from './sha1-options.ts'\nimport type { LocalSyncPath } from './types.ts'\n\n/** Options for reading a local file SHA-1 digest. */\nexport interface LocalSha1ReadOptions {\n  /**\n   * Maximum milliseconds to allow without filesystem progress while hashing.\n   * Defaults to 30 seconds.\n   */\n  readonly timeoutMillis?: number\n}\n\n/** Reads a local file and returns its SHA-1 digest, or null when unavailable. */\nexport type LocalSha1Reader = (\n  path: LocalSyncPath,\n  signal?: AbortSignal,\n  options?: LocalSha1ReadOptions,\n) => Promise<string | null>\n\n/**\n * Formats a hash error for public sync events without leaking filesystem paths.\n *\n * @param error - Error thrown while hashing.\n *\n * @returns A sanitized reason suitable for event messages.\n */\nexport function formatHashError(error: Error): string {\n  return sanitizeErrorReason(error)\n}\n\n/**\n * Returns whether an error represents an abort.\n *\n * @param err - Unknown thrown value.\n *\n * @returns True for AbortError values.\n */\nexport function isAbortError(err: unknown): boolean {\n  const error = toError(err)\n  return error.name === 'AbortError'\n}\n\n/**\n * Reads a local file and computes its SHA-1 digest with non-regular-file rejection,\n * scanned-size bounds, abort support, and an idle/no-progress timeout.\n *\n * @param path - Local sync path to hash.\n * @param signal - Optional abort signal.\n * @param options - Optional idle timeout override.\n *\n * @returns The lowercase SHA-1 digest of the file bytes.\n */\nexport async function readLocalSha1File(\n  path: LocalSyncPath,\n  signal?: AbortSignal,\n  options: LocalSha1ReadOptions = {},\n): Promise<string> {\n  const { constants } = await import('node:fs')\n  const { lstat, open } = await import('node:fs/promises')\n  const timeoutMillis = normalizeSha1TimeoutMillis(options.timeoutMillis)\n  const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)\n  const hash = new IncrementalSha1()\n  let stream: (AsyncIterable<Uint8Array> & { destroy(error?: Error): void }) | undefined\n  let file: Awaited<ReturnType<typeof open>> | undefined\n  let timeout: ReturnType<typeof setTimeout> | undefined\n\n  function armTimeout(onTimeout: () => void): void {\n    if (timeout !== undefined) clearTimeout(timeout)\n    timeout = setTimeout(onTimeout, timeoutMillis)\n  }\n\n  try {\n    signal?.throwIfAborted()\n\n    const preOpenStat = await withTimeout(\n      lstat(path.absolutePath),\n      timeoutMillis,\n      'sha1 file status',\n    )\n    assertSameScannedRegularFile(preOpenStat, path, 'sha1 comparison')\n\n    file = await openWithTimeout(open(path.absolutePath, flags), timeoutMillis)\n\n    const postOpenStat = await withTimeout(\n      lstat(path.absolutePath),\n      timeoutMillis,\n      'sha1 file status',\n    )\n    assertSameScannedRegularFile(postOpenStat, path, 'sha1 comparison')\n\n    const stat = await withTimeout(file.stat(), timeoutMillis, 'sha1 file status')\n    assertSameScannedRegularFile(stat, path, 'sha1 comparison')\n\n    stream = file.createReadStream({\n      ...(path.size > 0 ? { start: 0, end: path.size - 1 } : {}),\n      ...(signal !== undefined ? { signal } : {}),\n    })\n\n    let bytesRead = 0\n    /* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */\n    armTimeout(() => {\n      stream?.destroy(new Error(`sha1 read stalled for ${timeoutMillis} ms`))\n    })\n    for await (const chunk of stream) {\n      bytesRead += chunk.byteLength\n      await hash.update(chunk)\n      /* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */\n      armTimeout(() => {\n        stream?.destroy(new Error(`sha1 read stalled for ${timeoutMillis} ms`))\n      })\n    }\n\n    /* v8 ignore next -- defensive TOCTOU guard after the bounded stream completes */\n    if (bytesRead !== path.size) throw new Error('file changed during sha1 comparison')\n    return hash.digest()\n  } finally {\n    if (timeout !== undefined) clearTimeout(timeout)\n    stream?.destroy()\n    await file?.close().catch(() => {})\n  }\n}\n\n/* v8 ignore start -- defensive stale-filesystem stall handling is not portable to trigger */\nasync function withTimeout<T>(\n  promise: Promise<T>,\n  timeoutMillis: number,\n  operation: string,\n): Promise<T> {\n  let timeout: ReturnType<typeof setTimeout> | undefined\n  try {\n    return await Promise.race([\n      promise,\n      new Promise<never>((_, reject) => {\n        timeout = setTimeout(() => {\n          reject(new Error(`${operation} stalled for ${timeoutMillis} ms`))\n        }, timeoutMillis)\n      }),\n    ])\n  } finally {\n    if (timeout !== undefined) clearTimeout(timeout)\n  }\n}\n\nasync function openWithTimeout<T extends { close(): Promise<void> }>(\n  promise: Promise<T>,\n  timeoutMillis: number,\n): Promise<T> {\n  let timedOut = false\n  const tracked = promise.then(\n    (file) => {\n      if (timedOut) void file.close().catch(() => {})\n      return file\n    },\n    (err: unknown) => {\n      throw err\n    },\n  )\n\n  try {\n    return await withTimeout(tracked, timeoutMillis, 'sha1 file open')\n  } catch (err) {\n    timedOut = true\n    throw err\n  }\n}\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;AA8BA,SAAgB,gBAAgB,OAAsB;CACpD,OAAO,qBAAA,oBAAoB,KAAK;AAClC;;;;;;;;AASA,SAAgB,aAAa,KAAuB;CAElD,OADc,iBAAA,QAAQ,GACf,CAAA,CAAM,SAAS;AACxB;;;;;;;;;;;AAYA,eAAsB,kBACpB,MACA,QACA,UAAgC,CAAC,GAChB;CACjB,MAAM,EAAE,cAAc,MAAM,OAAO;CACnC,MAAM,EAAE,OAAO,SAAS,MAAM,OAAO;CACrC,MAAM,gBAAgB,qBAAA,2BAA2B,QAAQ,aAAa;CACtE,MAAM,QAAQ,UAAU,YAAY,UAAU,cAAc,MAAM,UAAU,cAAc;CAC1F,MAAM,OAAO,IAAI,aAAA,gBAAgB;CACjC,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,SAAS,WAAW,WAA6B;EAC/C,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;EAC/C,UAAU,WAAW,WAAW,aAAa;CAC/C;CAEA,IAAI;EACF,QAAQ,eAAe;EAOvB,4BAAA,6BAA6B,MALH,YACxB,MAAM,KAAK,YAAY,GACvB,eACA,kBACF,GAC0C,MAAM,iBAAiB;EAEjE,OAAO,MAAM,gBAAgB,KAAK,KAAK,cAAc,KAAK,GAAG,aAAa;EAO1E,4BAAA,6BAA6B,MALF,YACzB,MAAM,KAAK,YAAY,GACvB,eACA,kBACF,GAC2C,MAAM,iBAAiB;EAGlE,4BAAA,6BAA6B,MADV,YAAY,KAAK,KAAK,GAAG,eAAe,kBAAkB,GAC1C,MAAM,iBAAiB;EAE1D,SAAS,KAAK,iBAAiB;GAC7B,GAAI,KAAK,OAAO,IAAI;IAAE,OAAO;IAAG,KAAK,KAAK,OAAO;GAAE,IAAI,CAAC;GACxD,GAAI,WAAW,KAAA,IAAY,EAAE,OAAO,IAAI,CAAC;EAC3C,CAAC;EAED,IAAI,YAAY;;EAEhB,iBAAiB;GACf,QAAQ,wBAAQ,IAAI,MAAM,yBAAyB,cAAc,IAAI,CAAC;EACxE,CAAC;EACD,WAAW,MAAM,SAAS,QAAQ;GAChC,aAAa,MAAM;GACnB,MAAM,KAAK,OAAO,KAAK;;GAEvB,iBAAiB;IACf,QAAQ,wBAAQ,IAAI,MAAM,yBAAyB,cAAc,IAAI,CAAC;GACxE,CAAC;EACH;;EAGA,IAAI,cAAc,KAAK,MAAM,MAAM,IAAI,MAAM,qCAAqC;EAClF,OAAO,KAAK,OAAO;CACrB,UAAU;EACR,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;EAC/C,QAAQ,QAAQ;EAChB,MAAM,MAAM,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;CACpC;AACF;;AAGA,eAAe,YACb,SACA,eACA,WACY;CACZ,IAAI;CACJ,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CACxB,SACA,IAAI,SAAgB,GAAG,WAAW;GAChC,UAAU,iBAAiB;IACzB,uBAAO,IAAI,MAAM,GAAG,UAAU,eAAe,cAAc,IAAI,CAAC;GAClE,GAAG,aAAa;EAClB,CAAC,CACH,CAAC;CACH,UAAU;EACR,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;CACjD;AACF;AAEA,eAAe,gBACb,SACA,eACY;CACZ,IAAI,WAAW;CACf,MAAM,UAAU,QAAQ,MACrB,SAAS;EACR,IAAI,UAAU,KAAU,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;EAC9C,OAAO;CACT,IACC,QAAiB;EAChB,MAAM;CACR,CACF;CAEA,IAAI;EACF,OAAO,MAAM,YAAY,SAAS,eAAe,gBAAgB;CACnE,SAAS,KAAK;EACZ,WAAW;EACX,MAAM;CACR;AACF"}

package/dist/sync/local-sha1.d.cts

@@ -0,0 +1,39 @@
+import { LocalSyncPath } from './types.js';
+/** Options for reading a local file SHA-1 digest. */
+export interface LocalSha1ReadOptions {
+    /**
+     * Maximum milliseconds to allow without filesystem progress while hashing.
+     * Defaults to 30 seconds.
+     */
+    readonly timeoutMillis?: number;
+}
+/** Reads a local file and returns its SHA-1 digest, or null when unavailable. */
+export type LocalSha1Reader = (path: LocalSyncPath, signal?: AbortSignal, options?: LocalSha1ReadOptions) => Promise<string | null>;
+/**
+ * Formats a hash error for public sync events without leaking filesystem paths.
+ *
+ * @param error - Error thrown while hashing.
+ *
+ * @returns A sanitized reason suitable for event messages.
+ */
+export declare function formatHashError(error: Error): string;
+/**
+ * Returns whether an error represents an abort.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns True for AbortError values.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Reads a local file and computes its SHA-1 digest with non-regular-file rejection,
+ * scanned-size bounds, abort support, and an idle/no-progress timeout.
+ *
+ * @param path - Local sync path to hash.
+ * @param signal - Optional abort signal.
+ * @param options - Optional idle timeout override.
+ *
+ * @returns The lowercase SHA-1 digest of the file bytes.
+ */
+export declare function readLocalSha1File(path: LocalSyncPath, signal?: AbortSignal, options?: LocalSha1ReadOptions): Promise<string>;
+//# sourceMappingURL=local-sha1.d.ts.map

package/dist/sync/local-sha1.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-sha1.d.ts","sourceRoot":"","sources":["../../src/sync/local-sha1.js"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;AAE3B;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGlD;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAgEjB"}

package/dist/sync/local-sha1.d.ts

@@ -0,0 +1,39 @@
+import { LocalSyncPath } from './types.js';
+/** Options for reading a local file SHA-1 digest. */
+export interface LocalSha1ReadOptions {
+    /**
+     * Maximum milliseconds to allow without filesystem progress while hashing.
+     * Defaults to 30 seconds.
+     */
+    readonly timeoutMillis?: number;
+}
+/** Reads a local file and returns its SHA-1 digest, or null when unavailable. */
+export type LocalSha1Reader = (path: LocalSyncPath, signal?: AbortSignal, options?: LocalSha1ReadOptions) => Promise<string | null>;
+/**
+ * Formats a hash error for public sync events without leaking filesystem paths.
+ *
+ * @param error - Error thrown while hashing.
+ *
+ * @returns A sanitized reason suitable for event messages.
+ */
+export declare function formatHashError(error: Error): string;
+/**
+ * Returns whether an error represents an abort.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns True for AbortError values.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Reads a local file and computes its SHA-1 digest with non-regular-file rejection,
+ * scanned-size bounds, abort support, and an idle/no-progress timeout.
+ *
+ * @param path - Local sync path to hash.
+ * @param signal - Optional abort signal.
+ * @param options - Optional idle timeout override.
+ *
+ * @returns The lowercase SHA-1 digest of the file bytes.
+ */
+export declare function readLocalSha1File(path: LocalSyncPath, signal?: AbortSignal, options?: LocalSha1ReadOptions): Promise<string>;
+//# sourceMappingURL=local-sha1.d.ts.map

package/dist/sync/local-sha1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-sha1.d.ts","sourceRoot":"","sources":["../../src/sync/local-sha1.js"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,iFAAiF;AACjF,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;AAE3B;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGlD;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,MAAM,CAAC,CAgEjB"}

package/dist/sync/local-sha1.js

@@ -0,0 +1,117 @@
+import { IncrementalSha1 } from "../streams/hash.js";
+import { toError } from "../util/to-error.js";
+import { sanitizeErrorReason } from "../util/error-reason.js";
+import { assertSameScannedRegularFile } from "./local-file-identity.js";
+import { normalizeSha1TimeoutMillis } from "./sha1-options.js";
+//#region src/sync/local-sha1.ts
+/**
+* Formats a hash error for public sync events without leaking filesystem paths.
+*
+* @param error - Error thrown while hashing.
+*
+* @returns A sanitized reason suitable for event messages.
+*/
+function formatHashError(error) {
+	return sanitizeErrorReason(error);
+}
+/**
+* Returns whether an error represents an abort.
+*
+* @param err - Unknown thrown value.
+*
+* @returns True for AbortError values.
+*/
+function isAbortError(err) {
+	return toError(err).name === "AbortError";
+}
+/**
+* Reads a local file and computes its SHA-1 digest with non-regular-file rejection,
+* scanned-size bounds, abort support, and an idle/no-progress timeout.
+*
+* @param path - Local sync path to hash.
+* @param signal - Optional abort signal.
+* @param options - Optional idle timeout override.
+*
+* @returns The lowercase SHA-1 digest of the file bytes.
+*/
+async function readLocalSha1File(path, signal, options = {}) {
+	const { constants } = await import("node:fs");
+	const { lstat, open } = await import("node:fs/promises");
+	const timeoutMillis = normalizeSha1TimeoutMillis(options.timeoutMillis);
+	const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+	const hash = new IncrementalSha1();
+	let stream;
+	let file;
+	let timeout;
+	function armTimeout(onTimeout) {
+		if (timeout !== void 0) clearTimeout(timeout);
+		timeout = setTimeout(onTimeout, timeoutMillis);
+	}
+	try {
+		signal?.throwIfAborted();
+		assertSameScannedRegularFile(await withTimeout(lstat(path.absolutePath), timeoutMillis, "sha1 file status"), path, "sha1 comparison");
+		file = await openWithTimeout(open(path.absolutePath, flags), timeoutMillis);
+		assertSameScannedRegularFile(await withTimeout(lstat(path.absolutePath), timeoutMillis, "sha1 file status"), path, "sha1 comparison");
+		assertSameScannedRegularFile(await withTimeout(file.stat(), timeoutMillis, "sha1 file status"), path, "sha1 comparison");
+		stream = file.createReadStream({
+			...path.size > 0 ? {
+				start: 0,
+				end: path.size - 1
+			} : {},
+			...signal !== void 0 ? { signal } : {}
+		});
+		let bytesRead = 0;
+		/* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */
+		armTimeout(() => {
+			stream?.destroy(/* @__PURE__ */ new Error(`sha1 read stalled for ${timeoutMillis} ms`));
+		});
+		for await (const chunk of stream) {
+			bytesRead += chunk.byteLength;
+			await hash.update(chunk);
+			/* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */
+			armTimeout(() => {
+				stream?.destroy(/* @__PURE__ */ new Error(`sha1 read stalled for ${timeoutMillis} ms`));
+			});
+		}
+		/* v8 ignore next -- defensive TOCTOU guard after the bounded stream completes */
+		if (bytesRead !== path.size) throw new Error("file changed during sha1 comparison");
+		return hash.digest();
+	} finally {
+		if (timeout !== void 0) clearTimeout(timeout);
+		stream?.destroy();
+		await file?.close().catch(() => {});
+	}
+}
+/* v8 ignore start -- defensive stale-filesystem stall handling is not portable to trigger */
+async function withTimeout(promise, timeoutMillis, operation) {
+	let timeout;
+	try {
+		return await Promise.race([promise, new Promise((_, reject) => {
+			timeout = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`${operation} stalled for ${timeoutMillis} ms`));
+			}, timeoutMillis);
+		})]);
+	} finally {
+		if (timeout !== void 0) clearTimeout(timeout);
+	}
+}
+async function openWithTimeout(promise, timeoutMillis) {
+	let timedOut = false;
+	const tracked = promise.then((file) => {
+		if (timedOut) file.close().catch(() => {});
+		return file;
+	}, (err) => {
+		throw err;
+	});
+	try {
+		return await withTimeout(tracked, timeoutMillis, "sha1 file open");
+	} catch (err) {
+		timedOut = true;
+		throw err;
+	}
+}
+/* v8 ignore stop */
+//#endregion
+export { formatHashError, isAbortError, readLocalSha1File };
+
+//# sourceMappingURL=local-sha1.js.map

package/dist/sync/local-sha1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-sha1.js","names":[],"sources":["../../src/sync/local-sha1.ts"],"sourcesContent":["import { IncrementalSha1 } from '../streams/hash.ts'\nimport { sanitizeErrorReason } from '../util/error-reason.ts'\nimport { toError } from '../util/to-error.ts'\nimport { assertSameScannedRegularFile } from './local-file-identity.ts'\nimport { normalizeSha1TimeoutMillis } from './sha1-options.ts'\nimport type { LocalSyncPath } from './types.ts'\n\n/** Options for reading a local file SHA-1 digest. */\nexport interface LocalSha1ReadOptions {\n  /**\n   * Maximum milliseconds to allow without filesystem progress while hashing.\n   * Defaults to 30 seconds.\n   */\n  readonly timeoutMillis?: number\n}\n\n/** Reads a local file and returns its SHA-1 digest, or null when unavailable. */\nexport type LocalSha1Reader = (\n  path: LocalSyncPath,\n  signal?: AbortSignal,\n  options?: LocalSha1ReadOptions,\n) => Promise<string | null>\n\n/**\n * Formats a hash error for public sync events without leaking filesystem paths.\n *\n * @param error - Error thrown while hashing.\n *\n * @returns A sanitized reason suitable for event messages.\n */\nexport function formatHashError(error: Error): string {\n  return sanitizeErrorReason(error)\n}\n\n/**\n * Returns whether an error represents an abort.\n *\n * @param err - Unknown thrown value.\n *\n * @returns True for AbortError values.\n */\nexport function isAbortError(err: unknown): boolean {\n  const error = toError(err)\n  return error.name === 'AbortError'\n}\n\n/**\n * Reads a local file and computes its SHA-1 digest with non-regular-file rejection,\n * scanned-size bounds, abort support, and an idle/no-progress timeout.\n *\n * @param path - Local sync path to hash.\n * @param signal - Optional abort signal.\n * @param options - Optional idle timeout override.\n *\n * @returns The lowercase SHA-1 digest of the file bytes.\n */\nexport async function readLocalSha1File(\n  path: LocalSyncPath,\n  signal?: AbortSignal,\n  options: LocalSha1ReadOptions = {},\n): Promise<string> {\n  const { constants } = await import('node:fs')\n  const { lstat, open } = await import('node:fs/promises')\n  const timeoutMillis = normalizeSha1TimeoutMillis(options.timeoutMillis)\n  const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)\n  const hash = new IncrementalSha1()\n  let stream: (AsyncIterable<Uint8Array> & { destroy(error?: Error): void }) | undefined\n  let file: Awaited<ReturnType<typeof open>> | undefined\n  let timeout: ReturnType<typeof setTimeout> | undefined\n\n  function armTimeout(onTimeout: () => void): void {\n    if (timeout !== undefined) clearTimeout(timeout)\n    timeout = setTimeout(onTimeout, timeoutMillis)\n  }\n\n  try {\n    signal?.throwIfAborted()\n\n    const preOpenStat = await withTimeout(\n      lstat(path.absolutePath),\n      timeoutMillis,\n      'sha1 file status',\n    )\n    assertSameScannedRegularFile(preOpenStat, path, 'sha1 comparison')\n\n    file = await openWithTimeout(open(path.absolutePath, flags), timeoutMillis)\n\n    const postOpenStat = await withTimeout(\n      lstat(path.absolutePath),\n      timeoutMillis,\n      'sha1 file status',\n    )\n    assertSameScannedRegularFile(postOpenStat, path, 'sha1 comparison')\n\n    const stat = await withTimeout(file.stat(), timeoutMillis, 'sha1 file status')\n    assertSameScannedRegularFile(stat, path, 'sha1 comparison')\n\n    stream = file.createReadStream({\n      ...(path.size > 0 ? { start: 0, end: path.size - 1 } : {}),\n      ...(signal !== undefined ? { signal } : {}),\n    })\n\n    let bytesRead = 0\n    /* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */\n    armTimeout(() => {\n      stream?.destroy(new Error(`sha1 read stalled for ${timeoutMillis} ms`))\n    })\n    for await (const chunk of stream) {\n      bytesRead += chunk.byteLength\n      await hash.update(chunk)\n      /* v8 ignore next 3 -- idle-timeout firing is timing-dependent in filesystem tests */\n      armTimeout(() => {\n        stream?.destroy(new Error(`sha1 read stalled for ${timeoutMillis} ms`))\n      })\n    }\n\n    /* v8 ignore next -- defensive TOCTOU guard after the bounded stream completes */\n    if (bytesRead !== path.size) throw new Error('file changed during sha1 comparison')\n    return hash.digest()\n  } finally {\n    if (timeout !== undefined) clearTimeout(timeout)\n    stream?.destroy()\n    await file?.close().catch(() => {})\n  }\n}\n\n/* v8 ignore start -- defensive stale-filesystem stall handling is not portable to trigger */\nasync function withTimeout<T>(\n  promise: Promise<T>,\n  timeoutMillis: number,\n  operation: string,\n): Promise<T> {\n  let timeout: ReturnType<typeof setTimeout> | undefined\n  try {\n    return await Promise.race([\n      promise,\n      new Promise<never>((_, reject) => {\n        timeout = setTimeout(() => {\n          reject(new Error(`${operation} stalled for ${timeoutMillis} ms`))\n        }, timeoutMillis)\n      }),\n    ])\n  } finally {\n    if (timeout !== undefined) clearTimeout(timeout)\n  }\n}\n\nasync function openWithTimeout<T extends { close(): Promise<void> }>(\n  promise: Promise<T>,\n  timeoutMillis: number,\n): Promise<T> {\n  let timedOut = false\n  const tracked = promise.then(\n    (file) => {\n      if (timedOut) void file.close().catch(() => {})\n      return file\n    },\n    (err: unknown) => {\n      throw err\n    },\n  )\n\n  try {\n    return await withTimeout(tracked, timeoutMillis, 'sha1 file open')\n  } catch (err) {\n    timedOut = true\n    throw err\n  }\n}\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;AA8BA,SAAgB,gBAAgB,OAAsB;CACpD,OAAO,oBAAoB,KAAK;AAClC;;;;;;;;AASA,SAAgB,aAAa,KAAuB;CAElD,OADc,QAAQ,GACf,CAAA,CAAM,SAAS;AACxB;;;;;;;;;;;AAYA,eAAsB,kBACpB,MACA,QACA,UAAgC,CAAC,GAChB;CACjB,MAAM,EAAE,cAAc,MAAM,OAAO;CACnC,MAAM,EAAE,OAAO,SAAS,MAAM,OAAO;CACrC,MAAM,gBAAgB,2BAA2B,QAAQ,aAAa;CACtE,MAAM,QAAQ,UAAU,YAAY,UAAU,cAAc,MAAM,UAAU,cAAc;CAC1F,MAAM,OAAO,IAAI,gBAAgB;CACjC,IAAI;CACJ,IAAI;CACJ,IAAI;CAEJ,SAAS,WAAW,WAA6B;EAC/C,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;EAC/C,UAAU,WAAW,WAAW,aAAa;CAC/C;CAEA,IAAI;EACF,QAAQ,eAAe;EAOvB,6BAA6B,MALH,YACxB,MAAM,KAAK,YAAY,GACvB,eACA,kBACF,GAC0C,MAAM,iBAAiB;EAEjE,OAAO,MAAM,gBAAgB,KAAK,KAAK,cAAc,KAAK,GAAG,aAAa;EAO1E,6BAA6B,MALF,YACzB,MAAM,KAAK,YAAY,GACvB,eACA,kBACF,GAC2C,MAAM,iBAAiB;EAGlE,6BAA6B,MADV,YAAY,KAAK,KAAK,GAAG,eAAe,kBAAkB,GAC1C,MAAM,iBAAiB;EAE1D,SAAS,KAAK,iBAAiB;GAC7B,GAAI,KAAK,OAAO,IAAI;IAAE,OAAO;IAAG,KAAK,KAAK,OAAO;GAAE,IAAI,CAAC;GACxD,GAAI,WAAW,KAAA,IAAY,EAAE,OAAO,IAAI,CAAC;EAC3C,CAAC;EAED,IAAI,YAAY;;EAEhB,iBAAiB;GACf,QAAQ,wBAAQ,IAAI,MAAM,yBAAyB,cAAc,IAAI,CAAC;EACxE,CAAC;EACD,WAAW,MAAM,SAAS,QAAQ;GAChC,aAAa,MAAM;GACnB,MAAM,KAAK,OAAO,KAAK;;GAEvB,iBAAiB;IACf,QAAQ,wBAAQ,IAAI,MAAM,yBAAyB,cAAc,IAAI,CAAC;GACxE,CAAC;EACH;;EAGA,IAAI,cAAc,KAAK,MAAM,MAAM,IAAI,MAAM,qCAAqC;EAClF,OAAO,KAAK,OAAO;CACrB,UAAU;EACR,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;EAC/C,QAAQ,QAAQ;EAChB,MAAM,MAAM,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;CACpC;AACF;;AAGA,eAAe,YACb,SACA,eACA,WACY;CACZ,IAAI;CACJ,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CACxB,SACA,IAAI,SAAgB,GAAG,WAAW;GAChC,UAAU,iBAAiB;IACzB,uBAAO,IAAI,MAAM,GAAG,UAAU,eAAe,cAAc,IAAI,CAAC;GAClE,GAAG,aAAa;EAClB,CAAC,CACH,CAAC;CACH,UAAU;EACR,IAAI,YAAY,KAAA,GAAW,aAAa,OAAO;CACjD;AACF;AAEA,eAAe,gBACb,SACA,eACY;CACZ,IAAI,WAAW;CACf,MAAM,UAAU,QAAQ,MACrB,SAAS;EACR,IAAI,UAAU,KAAU,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;EAC9C,OAAO;CACT,IACC,QAAiB;EAChB,MAAM;CACR,CACF;CAEA,IAAI;EACF,OAAO,MAAM,YAAY,SAAS,eAAe,gBAAgB;CACnE,SAAS,KAAK;EACZ,WAAW;EACX,MAAM;CACR;AACF"}

package/dist/sync/pairing.cjs

@@ -1,31 +1,120 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-async function* zipFolders(source, dest) {
-  const sourceIter = source.scan()[Symbol.asyncIterator]();
-  const destIter = dest.scan()[Symbol.asyncIterator]();
-  let sourceResult = await sourceIter.next();
-  let destResult = await destIter.next();
-  while (!sourceResult.done || !destResult.done) {
-    const s = sourceResult.done ? null : sourceResult.value;
-    const d = destResult.done ? null : destResult.value;
-    if (s === null) {
-      yield [null, d];
-      destResult = await destIter.next();
-    } else if (d === null) {
-      yield [s, null];
-      sourceResult = await sourceIter.next();
-    } else if (s.relativePath < d.relativePath) {
-      yield [s, null];
-      sourceResult = await sourceIter.next();
-    } else if (d.relativePath < s.relativePath) {
-      yield [null, d];
-      destResult = await destIter.next();
-    } else {
-      yield [s, d];
-      sourceResult = await sourceIter.next();
-      destResult = await destIter.next();
-    }
-  }
+const require_regexp_safety = require("./regexp-safety.cjs");
+const require_filters = require("./filters.cjs");
+const require_path_order = require("./path-order.cjs");
+const require_scan_limit = require("./scan-limit.cjs");
+//#region src/sync/pairing.ts
+/**
+* Merge-joins two sorted folder scans by relative path, yielding paired tuples.
+* Files present only in source yield `[source, null]`, only in dest yield `[null, dest]`,
+* and files in both yield `[source, dest]`.
+*
+* @param source - The source folder to scan.
+* @param dest - The destination folder to scan.
+* @param options - Optional scan controls and filters shared by both folders.
+* @param scanCallbacks - Optional internal source/destination skip callbacks.
+*/
+async function* zipFolders(source, dest, options = {}, scanCallbacks = {}) {
+	require_regexp_safety.validateSyncFilters(options);
+	const sourceOptions = scanOptionsSnapshot(options, scanCallbacks.onSourceSkip);
+	const destOptions = scanOptionsSnapshot(options, scanCallbacks.onDestSkip);
+	const sourceIter = scanWithFilters(source, sourceOptions)[Symbol.asyncIterator]();
+	const destIter = scanWithFilters(dest, destOptions)[Symbol.asyncIterator]();
+	let sourceDone = false;
+	let destDone = false;
+	try {
+		let [sourceResult, destResult] = await Promise.all([sourceIter.next(), destIter.next()]);
+		sourceDone = sourceResult.done === true;
+		destDone = destResult.done === true;
+		while (!sourceResult.done || !destResult.done) {
+			const s = sourceResult.done ? null : sourceResult.value;
+			const d = destResult.done ? null : destResult.value;
+			if (s === null) {
+				yield [null, d];
+				destResult = await destIter.next();
+				destDone = destResult.done === true;
+			} else if (d === null) {
+				yield [s, null];
+				sourceResult = await sourceIter.next();
+				sourceDone = sourceResult.done === true;
+			} else {
+				const comparison = require_path_order.compareSyncRelativePaths(s.relativePath, d.relativePath);
+				if (comparison < 0) {
+					yield [s, null];
+					sourceResult = await sourceIter.next();
+					sourceDone = sourceResult.done === true;
+				} else if (comparison > 0) {
+					yield [null, d];
+					destResult = await destIter.next();
+					destDone = destResult.done === true;
+				} else {
+					yield [s, d];
+					sourceResult = await sourceIter.next();
+					destResult = await destIter.next();
+					sourceDone = sourceResult.done === true;
+					destDone = destResult.done === true;
+				}
+			}
+		}
+	} finally {
+		await closeScanIterator(sourceIter, sourceDone);
+		await closeScanIterator(destIter, destDone);
+	}
 }
+async function closeScanIterator(iterator, alreadyDone) {
+	if (alreadyDone || iterator.return === void 0) return;
+	try {
+		await iterator.return();
+	} catch {}
+}
+function scanWithFilters(folder, options) {
+	const scanned = require_filters.filterSyncPaths(folder.scan(options.scanner), options.sdk);
+	if (folder.appliesScanSorting === true) return limitSyncPaths(scanned, options.sdk);
+	return sortSyncPaths(scanned, options.sdk);
+}
+async function* limitSyncPaths(paths, filters) {
+	const maxScanEntries = require_scan_limit.scanEntryLimit(filters);
+	let count = 0;
+	for await (const path of paths) {
+		count++;
+		require_scan_limit.assertScanEntryLimit(count, maxScanEntries);
+		yield path;
+	}
+}
+async function* sortSyncPaths(paths, filters) {
+	const maxScanEntries = require_scan_limit.scanEntryLimit(filters);
+	const collected = [];
+	for await (const path of paths) {
+		collected.push(path);
+		require_scan_limit.assertScanEntryLimit(collected.length, maxScanEntries);
+	}
+	collected.sort((a, b) => require_path_order.compareSyncRelativePaths(a.relativePath, b.relativePath));
+	yield* collected;
+}
+function scanOptionsSnapshot(options, onSkip) {
+	const onSkipSnapshot = options.onSkip === void 0 && onSkip === void 0 ? void 0 : (event) => {
+		options.onSkip?.(event);
+		onSkip?.(event);
+	};
+	return {
+		scanner: frozenScanOptions(options, frozenPatterns(options.include), frozenPatterns(options.exclude), onSkipSnapshot),
+		sdk: frozenScanOptions(options, frozenPatterns(options.include), frozenPatterns(options.exclude), onSkipSnapshot)
+	};
+}
+function frozenScanOptions(options, include, exclude, onSkip) {
+	return Object.freeze({
+		...include !== void 0 ? { include } : {},
+		...exclude !== void 0 ? { exclude } : {},
+		...options.signal !== void 0 ? { signal: options.signal } : {},
+		...options.onError !== void 0 ? { onError: options.onError } : {},
+		...onSkip !== void 0 ? { onSkip } : {},
+		...options.requireLocalSafePaths !== void 0 ? { requireLocalSafePaths: options.requireLocalSafePaths } : {},
+		...options.maxScanEntries !== void 0 ? { maxScanEntries: options.maxScanEntries } : {}
+	});
+}
+function frozenPatterns(patterns) {
+	return patterns === void 0 ? void 0 : Object.freeze([...patterns]);
+}
+//#endregion
 exports.zipFolders = zipFolders;
-//# sourceMappingURL=pairing.cjs.map
+
+//# sourceMappingURL=pairing.cjs.map

package/dist/sync/pairing.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"pairing.cjs","sources":["../../src/sync/pairing.ts"],"sourcesContent":["import type { SyncFolder, SyncPath } from './types.ts'\n\n/** A paired tuple of source and destination files. Either side may be null if the file is absent. */\nexport type SyncPair = readonly [SyncPath | null, SyncPath | null]\n\n/**\n * Merge-joins two sorted folder scans by relative path, yielding paired tuples.\n * Files present only in source yield `[source, null]`, only in dest yield `[null, dest]`,\n * and files in both yield `[source, dest]`.\n *\n * @param source - The source folder to scan.\n * @param dest - The destination folder to scan.\n */\nexport async function* zipFolders(source: SyncFolder, dest: SyncFolder): AsyncGenerator<SyncPair> {\n  const sourceIter = source.scan()[Symbol.asyncIterator]()\n  const destIter = dest.scan()[Symbol.asyncIterator]()\n\n  let sourceResult = await sourceIter.next()\n  let destResult = await destIter.next()\n\n  while (!sourceResult.done || !destResult.done) {\n    const s = sourceResult.done ? null : sourceResult.value\n    const d = destResult.done ? null : destResult.value\n\n    if (s === null) {\n      yield [null, d]\n      destResult = await destIter.next()\n    } else if (d === null) {\n      yield [s, null]\n      sourceResult = await sourceIter.next()\n    } else if (s.relativePath < d.relativePath) {\n      yield [s, null]\n      sourceResult = await sourceIter.next()\n    } else if (d.relativePath < s.relativePath) {\n      yield [null, d]\n      destResult = await destIter.next()\n    } else {\n      yield [s, d]\n      sourceResult = await sourceIter.next()\n      destResult = await destIter.next()\n    }\n  }\n}\n"],"names":[],"mappings":";;AAaA,gBAAuB,WAAW,QAAoB,MAA4C;AAChG,QAAM,aAAa,OAAO,KAAA,EAAO,OAAO,aAAa,EAAA;AACrD,QAAM,WAAW,KAAK,KAAA,EAAO,OAAO,aAAa,EAAA;AAEjD,MAAI,eAAe,MAAM,WAAW,KAAA;AACpC,MAAI,aAAa,MAAM,SAAS,KAAA;AAEhC,SAAO,CAAC,aAAa,QAAQ,CAAC,WAAW,MAAM;AAC7C,UAAM,IAAI,aAAa,OAAO,OAAO,aAAa;AAClD,UAAM,IAAI,WAAW,OAAO,OAAO,WAAW;AAE9C,QAAI,MAAM,MAAM;AACd,YAAM,CAAC,MAAM,CAAC;AACd,mBAAa,MAAM,SAAS,KAAA;AAAA,IAC9B,WAAW,MAAM,MAAM;AACrB,YAAM,CAAC,GAAG,IAAI;AACd,qBAAe,MAAM,WAAW,KAAA;AAAA,IAClC,WAAW,EAAE,eAAe,EAAE,cAAc;AAC1C,YAAM,CAAC,GAAG,IAAI;AACd,qBAAe,MAAM,WAAW,KAAA;AAAA,IAClC,WAAW,EAAE,eAAe,EAAE,cAAc;AAC1C,YAAM,CAAC,MAAM,CAAC;AACd,mBAAa,MAAM,SAAS,KAAA;AAAA,IAC9B,OAAO;AACL,YAAM,CAAC,GAAG,CAAC;AACX,qBAAe,MAAM,WAAW,KAAA;AAChC,mBAAa,MAAM,SAAS,KAAA;AAAA,IAC9B;AAAA,EACF;AACF;;"}
+{"version":3,"file":"pairing.cjs","names":[],"sources":["../../src/sync/pairing.ts"],"sourcesContent":["import { filterSyncPaths } from './filters.ts'\nimport { compareSyncRelativePaths } from './path-order.ts'\nimport { validateSyncFilters } from './regexp-safety.ts'\nimport { assertScanEntryLimit, scanEntryLimit } from './scan-limit.ts'\nimport type {\n  SyncFilterPattern,\n  SyncFolder,\n  SyncPath,\n  SyncScanOptions,\n  SyncSkipEvent,\n} from './types.ts'\n\n/** A paired tuple of source and destination files. Either side may be null if the file is absent. */\nexport type SyncPair = readonly [SyncPath | null, SyncPath | null]\n\n/**\n * Merge-joins two sorted folder scans by relative path, yielding paired tuples.\n * Files present only in source yield `[source, null]`, only in dest yield `[null, dest]`,\n * and files in both yield `[source, dest]`.\n *\n * @param source - The source folder to scan.\n * @param dest - The destination folder to scan.\n * @param options - Optional scan controls and filters shared by both folders.\n * @param scanCallbacks - Optional internal source/destination skip callbacks.\n */\nexport async function* zipFolders(\n  source: SyncFolder,\n  dest: SyncFolder,\n  options: SyncScanOptions = {},\n  scanCallbacks: {\n    readonly onSourceSkip?: (event: SyncSkipEvent) => void\n    readonly onDestSkip?: (event: SyncSkipEvent) => void\n  } = {},\n): AsyncGenerator<SyncPair> {\n  validateSyncFilters(options)\n  const sourceOptions = scanOptionsSnapshot(options, scanCallbacks.onSourceSkip)\n  const destOptions = scanOptionsSnapshot(options, scanCallbacks.onDestSkip)\n  const sourceIter = scanWithFilters(source, sourceOptions)[Symbol.asyncIterator]()\n  const destIter = scanWithFilters(dest, destOptions)[Symbol.asyncIterator]()\n  let sourceDone = false\n  let destDone = false\n\n  try {\n    let [sourceResult, destResult] = await Promise.all([sourceIter.next(), destIter.next()])\n    sourceDone = sourceResult.done === true\n    destDone = destResult.done === true\n\n    while (!sourceResult.done || !destResult.done) {\n      const s = sourceResult.done ? null : sourceResult.value\n      const d = destResult.done ? null : destResult.value\n\n      if (s === null) {\n        yield [null, d]\n        destResult = await destIter.next()\n        destDone = destResult.done === true\n      } else if (d === null) {\n        yield [s, null]\n        sourceResult = await sourceIter.next()\n        sourceDone = sourceResult.done === true\n      } else {\n        const comparison = compareSyncRelativePaths(s.relativePath, d.relativePath)\n        if (comparison < 0) {\n          yield [s, null]\n          sourceResult = await sourceIter.next()\n          sourceDone = sourceResult.done === true\n        } else if (comparison > 0) {\n          yield [null, d]\n          destResult = await destIter.next()\n          destDone = destResult.done === true\n        } else {\n          yield [s, d]\n          sourceResult = await sourceIter.next()\n          destResult = await destIter.next()\n          sourceDone = sourceResult.done === true\n          destDone = destResult.done === true\n        }\n      }\n    }\n  } finally {\n    await closeScanIterator(sourceIter, sourceDone)\n    await closeScanIterator(destIter, destDone)\n  }\n}\n\nasync function closeScanIterator(\n  iterator: AsyncIterator<SyncPath>,\n  alreadyDone: boolean,\n): Promise<void> {\n  if (alreadyDone || iterator.return === undefined) return\n  try {\n    await iterator.return()\n  } catch {\n    // Best-effort scanner cleanup should not mask the original stop reason.\n  }\n}\n\nfunction scanWithFilters(\n  folder: SyncFolder,\n  options: { readonly scanner: SyncScanOptions; readonly sdk: SyncScanOptions },\n): AsyncIterable<SyncPath> {\n  const scanned = filterSyncPaths(folder.scan(options.scanner), options.sdk)\n  if (folder.appliesScanSorting === true) return limitSyncPaths(scanned, options.sdk)\n  return sortSyncPaths(scanned, options.sdk)\n}\n\nasync function* limitSyncPaths(\n  paths: AsyncIterable<SyncPath>,\n  filters: SyncScanOptions | undefined,\n): AsyncGenerator<SyncPath> {\n  const maxScanEntries = scanEntryLimit(filters)\n  let count = 0\n  for await (const path of paths) {\n    count++\n    assertScanEntryLimit(count, maxScanEntries)\n    yield path\n  }\n}\n\nasync function* sortSyncPaths(\n  paths: AsyncIterable<SyncPath>,\n  filters: SyncScanOptions | undefined,\n): AsyncGenerator<SyncPath> {\n  const maxScanEntries = scanEntryLimit(filters)\n  const collected: SyncPath[] = []\n  for await (const path of paths) {\n    collected.push(path)\n    assertScanEntryLimit(collected.length, maxScanEntries)\n  }\n  collected.sort((a, b) => compareSyncRelativePaths(a.relativePath, b.relativePath))\n  yield* collected\n}\n\nfunction scanOptionsSnapshot(\n  options: SyncScanOptions,\n  onSkip: ((event: SyncSkipEvent) => void) | undefined,\n): { readonly scanner: SyncScanOptions; readonly sdk: SyncScanOptions } {\n  const onSkipSnapshot =\n    options.onSkip === undefined && onSkip === undefined\n      ? undefined\n      : (event: SyncSkipEvent): void => {\n          options.onSkip?.(event)\n          onSkip?.(event)\n        }\n\n  return {\n    scanner: frozenScanOptions(\n      options,\n      frozenPatterns(options.include),\n      frozenPatterns(options.exclude),\n      onSkipSnapshot,\n    ),\n    sdk: frozenScanOptions(\n      options,\n      frozenPatterns(options.include),\n      frozenPatterns(options.exclude),\n      onSkipSnapshot,\n    ),\n  }\n}\n\nfunction frozenScanOptions(\n  options: SyncScanOptions,\n  include: readonly SyncFilterPattern[] | undefined,\n  exclude: readonly SyncFilterPattern[] | undefined,\n  onSkip: ((event: SyncSkipEvent) => void) | undefined,\n): SyncScanOptions {\n  return Object.freeze({\n    ...(include !== undefined ? { include } : {}),\n    ...(exclude !== undefined ? { exclude } : {}),\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n    ...(options.onError !== undefined ? { onError: options.onError } : {}),\n    ...(onSkip !== undefined ? { onSkip } : {}),\n    ...(options.requireLocalSafePaths !== undefined\n      ? { requireLocalSafePaths: options.requireLocalSafePaths }\n      : {}),\n    ...(options.maxScanEntries !== undefined ? { maxScanEntries: options.maxScanEntries } : {}),\n  })\n}\n\nfunction frozenPatterns(\n  patterns: readonly SyncFilterPattern[] | undefined,\n): readonly SyncFilterPattern[] | undefined {\n  return patterns === undefined ? undefined : Object.freeze([...patterns])\n}\n"],"mappings":"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"}

package/dist/sync/pairing.d.cts

@@ -1,4 +1,4 @@
-import { SyncFolder, SyncPath } from './types.js';
+import { SyncFolder, SyncPath, SyncScanOptions, SyncSkipEvent } from './types.js';
 /** A paired tuple of source and destination files. Either side may be null if the file is absent. */
 export type SyncPair = readonly [SyncPath | null, SyncPath | null];
 /**
@@ -8,6 +8,11 @@ export type SyncPair = readonly [SyncPath | null, SyncPath | null];
  *
  * @param source - The source folder to scan.
  * @param dest - The destination folder to scan.
+ * @param options - Optional scan controls and filters shared by both folders.
+ * @param scanCallbacks - Optional internal source/destination skip callbacks.
  */
-export declare function zipFolders(source: SyncFolder, dest: SyncFolder): AsyncGenerator<SyncPair>;
+export declare function zipFolders(source: SyncFolder, dest: SyncFolder, options?: SyncScanOptions, scanCallbacks?: {
+    readonly onSourceSkip?: (event: SyncSkipEvent) => void;
+    readonly onDestSkip?: (event: SyncSkipEvent) => void;
+}): AsyncGenerator<SyncPair>;
 //# sourceMappingURL=pairing.d.ts.map

package/dist/sync/pairing.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/sync/pairing.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEtD,qGAAqG;AACrG,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;AAElE;;;;;;;GAOG;AACH,wBAAuB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,CA6BhG"}
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/sync/pairing.js"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,UAAU,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACd,MAAM,YAAY,CAAA;AAEnB,qGAAqG;AACrG,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;AAElE;;;;;;;;;GASG;AACH,wBAAuB,UAAU,CAC/B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,eAAoB,EAC7B,aAAa,GAAE;IACb,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;CAChD,GACL,cAAc,CAAC,QAAQ,CAAC,CAiD1B"}

package/dist/sync/pairing.d.ts

@@ -1,4 +1,4 @@
-import { SyncFolder, SyncPath } from './types.js';
+import { SyncFolder, SyncPath, SyncScanOptions, SyncSkipEvent } from './types.js';
 /** A paired tuple of source and destination files. Either side may be null if the file is absent. */
 export type SyncPair = readonly [SyncPath | null, SyncPath | null];
 /**
@@ -8,6 +8,11 @@ export type SyncPair = readonly [SyncPath | null, SyncPath | null];
  *
  * @param source - The source folder to scan.
  * @param dest - The destination folder to scan.
+ * @param options - Optional scan controls and filters shared by both folders.
+ * @param scanCallbacks - Optional internal source/destination skip callbacks.
  */
-export declare function zipFolders(source: SyncFolder, dest: SyncFolder): AsyncGenerator<SyncPair>;
+export declare function zipFolders(source: SyncFolder, dest: SyncFolder, options?: SyncScanOptions, scanCallbacks?: {
+    readonly onSourceSkip?: (event: SyncSkipEvent) => void;
+    readonly onDestSkip?: (event: SyncSkipEvent) => void;
+}): AsyncGenerator<SyncPair>;
 //# sourceMappingURL=pairing.d.ts.map

package/dist/sync/pairing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/sync/pairing.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAEtD,qGAAqG;AACrG,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;AAElE;;;;;;;GAOG;AACH,wBAAuB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,CA6BhG"}
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/sync/pairing.js"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,UAAU,EACV,QAAQ,EACR,eAAe,EACf,aAAa,EACd,MAAM,YAAY,CAAA;AAEnB,qGAAqG;AACrG,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;AAElE;;;;;;;;;GASG;AACH,wBAAuB,UAAU,CAC/B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,eAAoB,EAC7B,aAAa,GAAE;IACb,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;CAChD,GACL,cAAc,CAAC,QAAQ,CAAC,CAiD1B"}