@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/sync/regexp-safety.js

@@ -0,0 +1,190 @@
+//#region src/sync/regexp-safety.ts
+var MAX_REGEXP_SOURCE_LENGTH = 512;
+var MAX_REGEXP_INPUT_LENGTH = 1024;
+var MAX_REGEXP_UNBOUNDED_QUANTIFIERS = 1;
+var MAX_REGEXP_BOUNDED_QUANTIFIER = 200;
+var MAX_REGEXP_BOUNDED_QUANTIFIERS = 16;
+var MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT = 1e4;
+var safeRegExpCache = /* @__PURE__ */ new WeakMap();
+var validatedFilterCache = /* @__PURE__ */ new WeakSet();
+/**
+* Validates every RegExp filter in an include/exclude filter set.
+*
+* @param filters - Optional include and exclude filters to validate.
+*
+* @throws When a RegExp filter is too large or structurally unsafe.
+*/
+function validateSyncFilters(filters) {
+	if (filters === void 0) return;
+	if (validatedFilterCache.has(filters)) return;
+	validateSyncFilterList("include", filters.include);
+	validateSyncFilterList("exclude", filters.exclude);
+	validatedFilterCache.add(filters);
+}
+/**
+* Tests a path with a caller-provided RegExp without retaining `lastIndex` state.
+*
+* @param relativePath - Folder-relative path to test.
+* @param pattern - Caller-provided RegExp filter.
+*
+* @returns True when the RegExp matches the relative path.
+*
+* @throws When the RegExp filter is too large or structurally unsafe.
+*/
+function regexpMatchesSyncPath(relativePath, pattern) {
+	if (pathExceedsSafeRegExpInput(relativePath)) return false;
+	return regexpWithoutState(pattern).test(relativePath);
+}
+/**
+* Tests whether a relative path is too long to feed to caller-provided RegExp filters.
+*
+* @param relativePath - Folder-relative path to test.
+*
+* @returns True when RegExp filters should not be evaluated for the path.
+*/
+function pathExceedsSafeRegExpInput(relativePath) {
+	return relativePath.length > MAX_REGEXP_INPUT_LENGTH;
+}
+function validateSyncFilterList(kind, patterns) {
+	for (const pattern of patterns ?? []) if (typeof pattern !== "string") regexpWithoutState(pattern, kind);
+}
+function regexpWithoutState(pattern, kind = "pattern") {
+	const cached = safeRegExpCache.get(pattern);
+	if (cached !== void 0) return cached;
+	assertSafeRegExp(pattern, kind);
+	const compiled = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+	safeRegExpCache.set(pattern, compiled);
+	return compiled;
+}
+function assertSafeRegExp(pattern, kind) {
+	const source = pattern.source;
+	if (source.length > MAX_REGEXP_SOURCE_LENGTH) throw new Error(`Sync filter RegExp is too long (${kind}: /${source}/)`);
+	if (!regexpSourceLooksSafe(source)) throw new Error(`Sync filter RegExp is too complex (${kind}: /${source}/)`);
+}
+/**
+* Best-effort linear RegExp guard for filters matched synchronously on attacker-controlled paths.
+*
+* The accepted subset intentionally rejects constructs that are hard to bound in the JavaScript
+* RegExp engine: backreferences, unterminated escapes/classes/groups, repeated unbounded
+* quantifiers, bounded quantifiers above {@link MAX_REGEXP_BOUNDED_QUANTIFIER}, too many bounded
+* quantifiers or too large a bounded-quantifier product, and any quantified group whose subtree
+* already contains a quantifier or alternation. Group state is propagated upward so nested groups
+* cannot hide a quantified or alternated subtree before an outer bounded or unbounded quantifier.
+*
+* @param source - RegExp source text to inspect.
+*
+* @returns True when the source passes the SDK's structural safety heuristic.
+*/
+function regexpSourceLooksSafe(source) {
+	let escaped = false;
+	let inClass = false;
+	let unboundedQuantifiers = 0;
+	let boundedQuantifiers = 0;
+	let boundedQuantifierProduct = 1;
+	const groups = [];
+	let lastToken = null;
+	for (let i = 0; i < source.length; i++) {
+		const char = source[i] ?? "";
+		if (escaped) {
+			if (!inClass && char === "k" && source[i + 1] === "<") return false;
+			if (!inClass && /[1-9]/.test(char)) return false;
+			escaped = false;
+			lastToken = { type: "atom" };
+			continue;
+		}
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (inClass) {
+			if (char === "]") inClass = false;
+			continue;
+		}
+		if (char === "[") {
+			inClass = true;
+			lastToken = { type: "atom" };
+			continue;
+		}
+		if (char === "(") {
+			groups.push({
+				hasQuantifier: false,
+				hasAlternation: false
+			});
+			lastToken = null;
+			continue;
+		}
+		if (char === ")") {
+			const group = groups.pop();
+			if (!group) return false;
+			const parent = groups.at(-1);
+			if (parent) mergeGroupState(parent, group);
+			lastToken = {
+				type: "group",
+				...group
+			};
+			continue;
+		}
+		if (char === "|") {
+			const group = groups.at(-1);
+			if (group) group.hasAlternation = true;
+			lastToken = null;
+			continue;
+		}
+		const quantifier = lastToken !== null ? parseQuantifier(source, i) : null;
+		if (lastToken !== null && quantifier !== null) {
+			if (lastToken?.type === "group" && (lastToken.hasQuantifier || lastToken.hasAlternation)) return false;
+			if (quantifier.unbounded) {
+				unboundedQuantifiers++;
+				if (unboundedQuantifiers > MAX_REGEXP_UNBOUNDED_QUANTIFIERS) return false;
+			} else {
+				boundedQuantifiers++;
+				if (boundedQuantifiers > MAX_REGEXP_BOUNDED_QUANTIFIERS) return false;
+				if (quantifier.maxRepetitions > MAX_REGEXP_BOUNDED_QUANTIFIER) return false;
+				boundedQuantifierProduct *= Math.max(quantifier.maxRepetitions, 1);
+				if (boundedQuantifierProduct > MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT) return false;
+			}
+			const group = groups.at(-1);
+			if (group) group.hasQuantifier = true;
+			i = quantifier.endIndex;
+			lastToken = null;
+			continue;
+		}
+		lastToken = { type: "atom" };
+	}
+	return !escaped && !inClass && groups.length === 0;
+}
+function mergeGroupState(target, source) {
+	target.hasQuantifier = target.hasQuantifier || source.hasQuantifier;
+	target.hasAlternation = target.hasAlternation || source.hasAlternation;
+}
+function parseQuantifier(source, index) {
+	const char = source[index];
+	if (char === "*" || char === "+") return {
+		endIndex: index,
+		maxRepetitions: Number.POSITIVE_INFINITY,
+		unbounded: true
+	};
+	if (char === "?") return {
+		endIndex: index,
+		maxRepetitions: 1,
+		unbounded: false
+	};
+	if (char !== "{") return null;
+	const end = source.indexOf("}", index + 1);
+	if (end === -1) return null;
+	const body = source.slice(index + 1, end);
+	const match = /^(\d+)(?:,(\d*))?$/.exec(body);
+	if (!match) return null;
+	const min = Number(match[1]);
+	const maxText = match[2];
+	const unbounded = body.includes(",") && maxText === "";
+	return {
+		endIndex: end,
+		maxRepetitions: unbounded ? Number.POSITIVE_INFINITY : Number(maxText ?? min),
+		unbounded
+	};
+}
+//#endregion
+export { pathExceedsSafeRegExpInput, regexpMatchesSyncPath, validateSyncFilters };
+
+//# sourceMappingURL=regexp-safety.js.map

package/dist/sync/regexp-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regexp-safety.js","names":[],"sources":["../../src/sync/regexp-safety.ts"],"sourcesContent":["import type { SyncFilterOptions, SyncFilterPattern } from './types.ts'\n\nconst MAX_REGEXP_SOURCE_LENGTH = 512\nconst MAX_REGEXP_INPUT_LENGTH = 1024\nconst MAX_REGEXP_UNBOUNDED_QUANTIFIERS = 1\nconst MAX_REGEXP_BOUNDED_QUANTIFIER = 200\nconst MAX_REGEXP_BOUNDED_QUANTIFIERS = 16\nconst MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT = 10_000\nconst safeRegExpCache = new WeakMap<RegExp, RegExp>()\n// Validation is memoized by object identity. Treat filter objects and their\n// include/exclude arrays as immutable after first use, otherwise new patterns\n// added later would not be revalidated through this cache.\nconst validatedFilterCache = new WeakSet<SyncFilterOptions>()\n\ninterface RegExpGroupState {\n  hasQuantifier: boolean\n  hasAlternation: boolean\n}\n\ntype RegExpTokenState = { type: 'atom' } | ({ type: 'group' } & RegExpGroupState)\n\ninterface RegExpQuantifier {\n  endIndex: number\n  maxRepetitions: number\n  unbounded: boolean\n}\n\n/**\n * Validates every RegExp filter in an include/exclude filter set.\n *\n * @param filters - Optional include and exclude filters to validate.\n *\n * @throws When a RegExp filter is too large or structurally unsafe.\n */\nexport function validateSyncFilters(filters: SyncFilterOptions | undefined): void {\n  if (filters === undefined) return\n  if (validatedFilterCache.has(filters)) return\n\n  validateSyncFilterList('include', filters.include)\n  validateSyncFilterList('exclude', filters.exclude)\n  validatedFilterCache.add(filters)\n}\n\n/**\n * Tests a path with a caller-provided RegExp without retaining `lastIndex` state.\n *\n * @param relativePath - Folder-relative path to test.\n * @param pattern - Caller-provided RegExp filter.\n *\n * @returns True when the RegExp matches the relative path.\n *\n * @throws When the RegExp filter is too large or structurally unsafe.\n */\nexport function regexpMatchesSyncPath(relativePath: string, pattern: RegExp): boolean {\n  if (pathExceedsSafeRegExpInput(relativePath)) return false\n  return regexpWithoutState(pattern).test(relativePath)\n}\n\n/**\n * Tests whether a relative path is too long to feed to caller-provided RegExp filters.\n *\n * @param relativePath - Folder-relative path to test.\n *\n * @returns True when RegExp filters should not be evaluated for the path.\n */\nexport function pathExceedsSafeRegExpInput(relativePath: string): boolean {\n  return relativePath.length > MAX_REGEXP_INPUT_LENGTH\n}\n\nfunction validateSyncFilterList(\n  kind: 'include' | 'exclude',\n  patterns: readonly SyncFilterPattern[] | undefined,\n): void {\n  for (const pattern of patterns ?? []) {\n    if (typeof pattern !== 'string') {\n      regexpWithoutState(pattern, kind)\n    }\n  }\n}\n\nfunction regexpWithoutState(pattern: RegExp, kind = 'pattern'): RegExp {\n  const cached = safeRegExpCache.get(pattern)\n  if (cached !== undefined) return cached\n\n  assertSafeRegExp(pattern, kind)\n  const compiled = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''))\n  safeRegExpCache.set(pattern, compiled)\n  return compiled\n}\n\nfunction assertSafeRegExp(pattern: RegExp, kind: string): void {\n  const source = pattern.source\n  if (source.length > MAX_REGEXP_SOURCE_LENGTH) {\n    throw new Error(`Sync filter RegExp is too long (${kind}: /${source}/)`)\n  }\n\n  if (!regexpSourceLooksSafe(source)) {\n    throw new Error(`Sync filter RegExp is too complex (${kind}: /${source}/)`)\n  }\n}\n\n/**\n * Best-effort linear RegExp guard for filters matched synchronously on attacker-controlled paths.\n *\n * The accepted subset intentionally rejects constructs that are hard to bound in the JavaScript\n * RegExp engine: backreferences, unterminated escapes/classes/groups, repeated unbounded\n * quantifiers, bounded quantifiers above {@link MAX_REGEXP_BOUNDED_QUANTIFIER}, too many bounded\n * quantifiers or too large a bounded-quantifier product, and any quantified group whose subtree\n * already contains a quantifier or alternation. Group state is propagated upward so nested groups\n * cannot hide a quantified or alternated subtree before an outer bounded or unbounded quantifier.\n *\n * @param source - RegExp source text to inspect.\n *\n * @returns True when the source passes the SDK's structural safety heuristic.\n */\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: keep the regex safety scan linear.\nfunction regexpSourceLooksSafe(source: string): boolean {\n  let escaped = false\n  let inClass = false\n  let unboundedQuantifiers = 0\n  let boundedQuantifiers = 0\n  let boundedQuantifierProduct = 1\n  const groups: RegExpGroupState[] = []\n  let lastToken: RegExpTokenState | null = null\n\n  for (let i = 0; i < source.length; i++) {\n    const char = source[i] ?? ''\n\n    if (escaped) {\n      if (!inClass && char === 'k' && source[i + 1] === '<') return false\n      if (!inClass && /[1-9]/.test(char)) return false\n      escaped = false\n      lastToken = { type: 'atom' }\n      continue\n    }\n\n    if (char === '\\\\') {\n      escaped = true\n      continue\n    }\n\n    if (inClass) {\n      if (char === ']') inClass = false\n      continue\n    }\n\n    if (char === '[') {\n      inClass = true\n      lastToken = { type: 'atom' }\n      continue\n    }\n\n    if (char === '(') {\n      groups.push({ hasQuantifier: false, hasAlternation: false })\n      lastToken = null\n      continue\n    }\n\n    if (char === ')') {\n      const group = groups.pop()\n      if (!group) return false\n      const parent = groups.at(-1)\n      if (parent) mergeGroupState(parent, group)\n      lastToken = { type: 'group', ...group }\n      continue\n    }\n\n    if (char === '|') {\n      const group = groups.at(-1)\n      if (group) group.hasAlternation = true\n      lastToken = null\n      continue\n    }\n\n    const quantifier = lastToken !== null ? parseQuantifier(source, i) : null\n    if (lastToken !== null && quantifier !== null) {\n      if (lastToken?.type === 'group' && (lastToken.hasQuantifier || lastToken.hasAlternation)) {\n        return false\n      }\n\n      if (quantifier.unbounded) {\n        unboundedQuantifiers++\n        if (unboundedQuantifiers > MAX_REGEXP_UNBOUNDED_QUANTIFIERS) return false\n      } else {\n        boundedQuantifiers++\n        if (boundedQuantifiers > MAX_REGEXP_BOUNDED_QUANTIFIERS) return false\n        if (quantifier.maxRepetitions > MAX_REGEXP_BOUNDED_QUANTIFIER) return false\n        boundedQuantifierProduct *= Math.max(quantifier.maxRepetitions, 1)\n        if (boundedQuantifierProduct > MAX_REGEXP_BOUNDED_QUANTIFIER_PRODUCT) return false\n      }\n\n      const group = groups.at(-1)\n      if (group) group.hasQuantifier = true\n\n      i = quantifier.endIndex\n      lastToken = null\n      continue\n    }\n\n    lastToken = { type: 'atom' }\n  }\n\n  return !escaped && !inClass && groups.length === 0\n}\n\nfunction mergeGroupState(target: RegExpGroupState, source: RegExpGroupState): void {\n  target.hasQuantifier = target.hasQuantifier || source.hasQuantifier\n  target.hasAlternation = target.hasAlternation || source.hasAlternation\n}\n\nfunction parseQuantifier(source: string, index: number): RegExpQuantifier | null {\n  const char = source[index]\n  if (char === '*' || char === '+') {\n    return { endIndex: index, maxRepetitions: Number.POSITIVE_INFINITY, unbounded: true }\n  }\n  if (char === '?') {\n    return { endIndex: index, maxRepetitions: 1, unbounded: false }\n  }\n  if (char !== '{') return null\n\n  const end = source.indexOf('}', index + 1)\n  if (end === -1) return null\n\n  const body = source.slice(index + 1, end)\n  const match = /^(\\d+)(?:,(\\d*))?$/.exec(body)\n  if (!match) return null\n\n  const min = Number(match[1])\n  const maxText = match[2]\n  const unbounded = body.includes(',') && maxText === ''\n  return {\n    endIndex: end,\n    maxRepetitions: unbounded ? Number.POSITIVE_INFINITY : Number(maxText ?? min),\n    unbounded,\n  }\n}\n"],"mappings":"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"}

package/dist/sync/scan-events.cjs

@@ -0,0 +1,33 @@
+//#region src/sync/scan-events.ts
+/**
+* Emits a scanner skip event without letting observer failures abort the scan.
+*
+* @param filters - Scan options that may include an onSkip callback.
+* @param event - Skip event to report.
+*/
+function emitScannerSkip(filters, event) {
+	try {
+		filters?.onSkip?.(event);
+	} catch {}
+}
+/**
+* Builds a consistent skip event for paths that cannot be safely tested against RegExp filters.
+*
+* @param relativePath - Sync-relative path that exceeded the RegExp input limit.
+*
+* @returns A typed scanner skip event.
+*/
+function regexpInputTooLongSkip(relativePath) {
+	return {
+		type: "skip",
+		path: relativePath,
+		size: 0,
+		message: `Skipped sync path ${JSON.stringify(relativePath)}: path exceeds the RegExp filter input limit`,
+		reason: "path-too-long-for-regexp"
+	};
+}
+//#endregion
+exports.emitScannerSkip = emitScannerSkip;
+exports.regexpInputTooLongSkip = regexpInputTooLongSkip;
+
+//# sourceMappingURL=scan-events.cjs.map

package/dist/sync/scan-events.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-events.cjs","names":[],"sources":["../../src/sync/scan-events.ts"],"sourcesContent":["import type { SyncScanOptions, SyncSkipEvent } from './types.ts'\n\n/**\n * Emits a scanner skip event without letting observer failures abort the scan.\n *\n * @param filters - Scan options that may include an onSkip callback.\n * @param event - Skip event to report.\n */\nexport function emitScannerSkip(filters: SyncScanOptions | undefined, event: SyncSkipEvent): void {\n  try {\n    filters?.onSkip?.(event)\n  } catch {\n    // Diagnostics hooks must not change scan behavior.\n  }\n}\n\n/**\n * Builds a consistent skip event for paths that cannot be safely tested against RegExp filters.\n *\n * @param relativePath - Sync-relative path that exceeded the RegExp input limit.\n *\n * @returns A typed scanner skip event.\n */\nexport function regexpInputTooLongSkip(relativePath: string): SyncSkipEvent {\n  return {\n    type: 'skip',\n    path: relativePath,\n    size: 0,\n    message: `Skipped sync path ${JSON.stringify(\n      relativePath,\n    )}: path exceeds the RegExp filter input limit`,\n    reason: 'path-too-long-for-regexp',\n  }\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,gBAAgB,SAAsC,OAA4B;CAChG,IAAI;EACF,SAAS,SAAS,KAAK;CACzB,QAAQ,CAER;AACF;;;;;;;;AASA,SAAgB,uBAAuB,cAAqC;CAC1E,OAAO;EACL,MAAM;EACN,MAAM;EACN,MAAM;EACN,SAAS,qBAAqB,KAAK,UACjC,YACF,EAAE;EACF,QAAQ;CACV;AACF"}

package/dist/sync/scan-events.d.cts

@@ -0,0 +1,17 @@
+import { SyncScanOptions, SyncSkipEvent } from './types.js';
+/**
+ * Emits a scanner skip event without letting observer failures abort the scan.
+ *
+ * @param filters - Scan options that may include an onSkip callback.
+ * @param event - Skip event to report.
+ */
+export declare function emitScannerSkip(filters: SyncScanOptions | undefined, event: SyncSkipEvent): void;
+/**
+ * Builds a consistent skip event for paths that cannot be safely tested against RegExp filters.
+ *
+ * @param relativePath - Sync-relative path that exceeded the RegExp input limit.
+ *
+ * @returns A typed scanner skip event.
+ */
+export declare function regexpInputTooLongSkip(relativePath: string): SyncSkipEvent;
+//# sourceMappingURL=scan-events.d.ts.map

package/dist/sync/scan-events.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-events.d.ts","sourceRoot":"","sources":["../../src/sync/scan-events.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEhE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAMhG;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAU1E"}

package/dist/sync/scan-events.d.ts

@@ -0,0 +1,17 @@
+import { SyncScanOptions, SyncSkipEvent } from './types.js';
+/**
+ * Emits a scanner skip event without letting observer failures abort the scan.
+ *
+ * @param filters - Scan options that may include an onSkip callback.
+ * @param event - Skip event to report.
+ */
+export declare function emitScannerSkip(filters: SyncScanOptions | undefined, event: SyncSkipEvent): void;
+/**
+ * Builds a consistent skip event for paths that cannot be safely tested against RegExp filters.
+ *
+ * @param relativePath - Sync-relative path that exceeded the RegExp input limit.
+ *
+ * @returns A typed scanner skip event.
+ */
+export declare function regexpInputTooLongSkip(relativePath: string): SyncSkipEvent;
+//# sourceMappingURL=scan-events.d.ts.map

package/dist/sync/scan-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-events.d.ts","sourceRoot":"","sources":["../../src/sync/scan-events.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEhE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAMhG;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAU1E"}

package/dist/sync/scan-events.js

@@ -0,0 +1,32 @@
+//#region src/sync/scan-events.ts
+/**
+* Emits a scanner skip event without letting observer failures abort the scan.
+*
+* @param filters - Scan options that may include an onSkip callback.
+* @param event - Skip event to report.
+*/
+function emitScannerSkip(filters, event) {
+	try {
+		filters?.onSkip?.(event);
+	} catch {}
+}
+/**
+* Builds a consistent skip event for paths that cannot be safely tested against RegExp filters.
+*
+* @param relativePath - Sync-relative path that exceeded the RegExp input limit.
+*
+* @returns A typed scanner skip event.
+*/
+function regexpInputTooLongSkip(relativePath) {
+	return {
+		type: "skip",
+		path: relativePath,
+		size: 0,
+		message: `Skipped sync path ${JSON.stringify(relativePath)}: path exceeds the RegExp filter input limit`,
+		reason: "path-too-long-for-regexp"
+	};
+}
+//#endregion
+export { emitScannerSkip, regexpInputTooLongSkip };
+
+//# sourceMappingURL=scan-events.js.map

package/dist/sync/scan-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-events.js","names":[],"sources":["../../src/sync/scan-events.ts"],"sourcesContent":["import type { SyncScanOptions, SyncSkipEvent } from './types.ts'\n\n/**\n * Emits a scanner skip event without letting observer failures abort the scan.\n *\n * @param filters - Scan options that may include an onSkip callback.\n * @param event - Skip event to report.\n */\nexport function emitScannerSkip(filters: SyncScanOptions | undefined, event: SyncSkipEvent): void {\n  try {\n    filters?.onSkip?.(event)\n  } catch {\n    // Diagnostics hooks must not change scan behavior.\n  }\n}\n\n/**\n * Builds a consistent skip event for paths that cannot be safely tested against RegExp filters.\n *\n * @param relativePath - Sync-relative path that exceeded the RegExp input limit.\n *\n * @returns A typed scanner skip event.\n */\nexport function regexpInputTooLongSkip(relativePath: string): SyncSkipEvent {\n  return {\n    type: 'skip',\n    path: relativePath,\n    size: 0,\n    message: `Skipped sync path ${JSON.stringify(\n      relativePath,\n    )}: path exceeds the RegExp filter input limit`,\n    reason: 'path-too-long-for-regexp',\n  }\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,gBAAgB,SAAsC,OAA4B;CAChG,IAAI;EACF,SAAS,SAAS,KAAK;CACzB,QAAQ,CAER;AACF;;;;;;;;AASA,SAAgB,uBAAuB,cAAqC;CAC1E,OAAO;EACL,MAAM;EACN,MAAM;EACN,MAAM;EACN,SAAS,qBAAqB,KAAK,UACjC,YACF,EAAE;EACF,QAAQ;CACV;AACF"}

package/dist/sync/scan-limit.cjs

@@ -0,0 +1,33 @@
+//#region src/sync/scan-limit.ts
+/** Default maximum number of entries a sync scanner may retain before failing. */
+var DEFAULT_MAX_SCAN_ENTRIES = 1e6;
+/**
+* Resolves and validates the effective scan entry limit.
+* @param options - Optional scan options carrying an override.
+*
+* @returns The configured or default scan entry limit.
+*
+* @throws When the configured limit is not a positive safe integer or Infinity.
+*/
+function scanEntryLimit(options) {
+	const limit = options?.maxScanEntries ?? 1e6;
+	if (limit === Number.POSITIVE_INFINITY) return limit;
+	if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("maxScanEntries must be a positive safe integer or Infinity");
+	return limit;
+}
+/**
+* Throws when a scanner has retained more entries than the configured limit.
+* @param count - Number of retained entries.
+* @param limit - Maximum allowed retained entries.
+*
+* @throws When count is greater than limit.
+*/
+function assertScanEntryLimit(count, limit) {
+	if (count > limit) throw new Error(`Sync scan entry limit exceeded: maxScanEntries=${limit} was exceeded after ${count} scanned entries; raising maxScanEntries increases peak scanner memory`);
+}
+//#endregion
+exports.DEFAULT_MAX_SCAN_ENTRIES = DEFAULT_MAX_SCAN_ENTRIES;
+exports.assertScanEntryLimit = assertScanEntryLimit;
+exports.scanEntryLimit = scanEntryLimit;
+
+//# sourceMappingURL=scan-limit.cjs.map

package/dist/sync/scan-limit.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-limit.cjs","names":[],"sources":["../../src/sync/scan-limit.ts"],"sourcesContent":["import type { SyncScanOptions } from './types.ts'\n\n/** Default maximum number of entries a sync scanner may retain before failing. */\nexport const DEFAULT_MAX_SCAN_ENTRIES = 1_000_000\n\n/**\n * Resolves and validates the effective scan entry limit.\n * @param options - Optional scan options carrying an override.\n *\n * @returns The configured or default scan entry limit.\n *\n * @throws When the configured limit is not a positive safe integer or Infinity.\n */\nexport function scanEntryLimit(options: SyncScanOptions | undefined): number {\n  const limit = options?.maxScanEntries ?? DEFAULT_MAX_SCAN_ENTRIES\n  if (limit === Number.POSITIVE_INFINITY) return limit\n  if (!Number.isSafeInteger(limit) || limit < 1) {\n    throw new Error('maxScanEntries must be a positive safe integer or Infinity')\n  }\n  return limit\n}\n\n/**\n * Throws when a scanner has retained more entries than the configured limit.\n * @param count - Number of retained entries.\n * @param limit - Maximum allowed retained entries.\n *\n * @throws When count is greater than limit.\n */\nexport function assertScanEntryLimit(count: number, limit: number): void {\n  if (count > limit) {\n    throw new Error(\n      `Sync scan entry limit exceeded: maxScanEntries=${limit} was exceeded after ${count} scanned entries; raising maxScanEntries increases peak scanner memory`,\n    )\n  }\n}\n"],"mappings":";;AAGA,IAAa,2BAA2B;;;;;;;;;AAUxC,SAAgB,eAAe,SAA8C;CAC3E,MAAM,QAAQ,SAAS,kBAAA;CACvB,IAAI,UAAU,OAAO,mBAAmB,OAAO;CAC/C,IAAI,CAAC,OAAO,cAAc,KAAK,KAAK,QAAQ,GAC1C,MAAM,IAAI,MAAM,4DAA4D;CAE9E,OAAO;AACT;;;;;;;;AASA,SAAgB,qBAAqB,OAAe,OAAqB;CACvE,IAAI,QAAQ,OACV,MAAM,IAAI,MACR,kDAAkD,MAAM,sBAAsB,MAAM,uEACtF;AAEJ"}

package/dist/sync/scan-limit.d.cts

@@ -0,0 +1,21 @@
+import { SyncScanOptions } from './types.js';
+/** Default maximum number of entries a sync scanner may retain before failing. */
+export declare const DEFAULT_MAX_SCAN_ENTRIES = 1000000;
+/**
+ * Resolves and validates the effective scan entry limit.
+ * @param options - Optional scan options carrying an override.
+ *
+ * @returns The configured or default scan entry limit.
+ *
+ * @throws When the configured limit is not a positive safe integer or Infinity.
+ */
+export declare function scanEntryLimit(options: SyncScanOptions | undefined): number;
+/**
+ * Throws when a scanner has retained more entries than the configured limit.
+ * @param count - Number of retained entries.
+ * @param limit - Maximum allowed retained entries.
+ *
+ * @throws When count is greater than limit.
+ */
+export declare function assertScanEntryLimit(count: number, limit: number): void;
+//# sourceMappingURL=scan-limit.d.ts.map

package/dist/sync/scan-limit.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-limit.d.ts","sourceRoot":"","sources":["../../src/sync/scan-limit.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,UAAY,CAAA;AAEjD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAO3E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMvE"}

package/dist/sync/scan-limit.d.ts

@@ -0,0 +1,21 @@
+import { SyncScanOptions } from './types.js';
+/** Default maximum number of entries a sync scanner may retain before failing. */
+export declare const DEFAULT_MAX_SCAN_ENTRIES = 1000000;
+/**
+ * Resolves and validates the effective scan entry limit.
+ * @param options - Optional scan options carrying an override.
+ *
+ * @returns The configured or default scan entry limit.
+ *
+ * @throws When the configured limit is not a positive safe integer or Infinity.
+ */
+export declare function scanEntryLimit(options: SyncScanOptions | undefined): number;
+/**
+ * Throws when a scanner has retained more entries than the configured limit.
+ * @param count - Number of retained entries.
+ * @param limit - Maximum allowed retained entries.
+ *
+ * @throws When count is greater than limit.
+ */
+export declare function assertScanEntryLimit(count: number, limit: number): void;
+//# sourceMappingURL=scan-limit.d.ts.map

package/dist/sync/scan-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-limit.d.ts","sourceRoot":"","sources":["../../src/sync/scan-limit.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,UAAY,CAAA;AAEjD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAO3E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMvE"}

package/dist/sync/scan-limit.js

@@ -0,0 +1,31 @@
+//#region src/sync/scan-limit.ts
+/** Default maximum number of entries a sync scanner may retain before failing. */
+var DEFAULT_MAX_SCAN_ENTRIES = 1e6;
+/**
+* Resolves and validates the effective scan entry limit.
+* @param options - Optional scan options carrying an override.
+*
+* @returns The configured or default scan entry limit.
+*
+* @throws When the configured limit is not a positive safe integer or Infinity.
+*/
+function scanEntryLimit(options) {
+	const limit = options?.maxScanEntries ?? 1e6;
+	if (limit === Number.POSITIVE_INFINITY) return limit;
+	if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("maxScanEntries must be a positive safe integer or Infinity");
+	return limit;
+}
+/**
+* Throws when a scanner has retained more entries than the configured limit.
+* @param count - Number of retained entries.
+* @param limit - Maximum allowed retained entries.
+*
+* @throws When count is greater than limit.
+*/
+function assertScanEntryLimit(count, limit) {
+	if (count > limit) throw new Error(`Sync scan entry limit exceeded: maxScanEntries=${limit} was exceeded after ${count} scanned entries; raising maxScanEntries increases peak scanner memory`);
+}
+//#endregion
+export { DEFAULT_MAX_SCAN_ENTRIES, assertScanEntryLimit, scanEntryLimit };
+
+//# sourceMappingURL=scan-limit.js.map

package/dist/sync/scan-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-limit.js","names":[],"sources":["../../src/sync/scan-limit.ts"],"sourcesContent":["import type { SyncScanOptions } from './types.ts'\n\n/** Default maximum number of entries a sync scanner may retain before failing. */\nexport const DEFAULT_MAX_SCAN_ENTRIES = 1_000_000\n\n/**\n * Resolves and validates the effective scan entry limit.\n * @param options - Optional scan options carrying an override.\n *\n * @returns The configured or default scan entry limit.\n *\n * @throws When the configured limit is not a positive safe integer or Infinity.\n */\nexport function scanEntryLimit(options: SyncScanOptions | undefined): number {\n  const limit = options?.maxScanEntries ?? DEFAULT_MAX_SCAN_ENTRIES\n  if (limit === Number.POSITIVE_INFINITY) return limit\n  if (!Number.isSafeInteger(limit) || limit < 1) {\n    throw new Error('maxScanEntries must be a positive safe integer or Infinity')\n  }\n  return limit\n}\n\n/**\n * Throws when a scanner has retained more entries than the configured limit.\n * @param count - Number of retained entries.\n * @param limit - Maximum allowed retained entries.\n *\n * @throws When count is greater than limit.\n */\nexport function assertScanEntryLimit(count: number, limit: number): void {\n  if (count > limit) {\n    throw new Error(\n      `Sync scan entry limit exceeded: maxScanEntries=${limit} was exceeded after ${count} scanned entries; raising maxScanEntries increases peak scanner memory`,\n    )\n  }\n}\n"],"mappings":";;AAGA,IAAa,2BAA2B;;;;;;;;;AAUxC,SAAgB,eAAe,SAA8C;CAC3E,MAAM,QAAQ,SAAS,kBAAA;CACvB,IAAI,UAAU,OAAO,mBAAmB,OAAO;CAC/C,IAAI,CAAC,OAAO,cAAc,KAAK,KAAK,QAAQ,GAC1C,MAAM,IAAI,MAAM,4DAA4D;CAE9E,OAAO;AACT;;;;;;;;AASA,SAAgB,qBAAqB,OAAe,OAAqB;CACvE,IAAI,QAAQ,OACV,MAAM,IAAI,MACR,kDAAkD,MAAM,sBAAsB,MAAM,uEACtF;AAEJ"}