@banou/ponyfill 0.0.2 → 0.0.3

package/build/storage.cjs

@@ -21,31 +21,52 @@ var QUOTA_CEILING = {
 };
 var isDirectory = (handle) => typeof handle.values === "function";
 /**
-* Every byte under a directory, measured rather than asked for.
+* Never walk forever: a cycle is impossible in OPFS, but a pathological tree is not worth the tick.
 *
-* Recursive, and it counts a file's REPORTED SIZE, which for OPFS is the file's extent rather than
-* how much of it has been written. That is the same accounting the quota system uses, which is the
-* whole point: a one byte write a gigabyte into a file is charged a gigabyte, and a measurement that
-* disagreed with the charge would be no more useful than the figure it replaces.
+* These are bounds, not correctness: hitting either returns what was counted so far rather than
+* failing, which keeps the answer a floor in the same direction as everything else here.
+*/
+var MAX_DEPTH = 8;
+var MAX_ENTRIES = 2e4;
+/**
+* Every byte under a directory, measured rather than asked for, or `null` when the walk could not
+* be done at all.
+*
+* The null is a distinct third answer and callers depend on it: "the origin holds nothing" and "the
+* file system was unreachable" lead to opposite decisions, and collapsing them to 0 would have
+* {@link correctedUsage} report an empty origin for one that simply could not be read.
+*
+* Counts a file's REPORTED SIZE, which for OPFS is its extent rather than how much of it has been
+* written. That is the same accounting the quota system uses, which is the point: a one byte write a
+* gigabyte into a file is charged a gigabyte, and a measurement disagreeing with the charge would be
+* no more useful than the figure it replaces.
 *
-* An unreadable entry is SKIPPED rather than fatal. A file the engine currently holds an exclusive
-* sync access handle for cannot be opened by anyone else, and a walk that threw on the first of
-* those would return nothing for exactly the origins that hold the most.
+* An unreadable ENTRY is skipped rather than fatal. A file the engine currently holds an exclusive
+* sync access handle for cannot be opened by anyone else, and `getFile()` on it throws rather than
+* waiting, so a walk that gave up on the first of those would return nothing for exactly the origins
+* holding the most. The answer is therefore a floor: short by the files open right now, never long.
 */
-var measureDirectoryBytes = async (directory) => {
+var measureDirectoryBytes = async (directory, { maxDepth = 8, maxEntries = MAX_ENTRIES } = {}) => {
 	let total = 0;
-	const visit = async (handle) => {
+	let seen = 0;
+	const visit = async (handle, depth) => {
+		if (depth > maxDepth) return;
 		for await (const child of handle.values()) {
+			if (++seen > maxEntries) return;
 			if (isDirectory(child)) {
-				await visit(child);
+				await visit(child, depth + 1);
 				continue;
 			}
 			const file = await child.getFile().catch(() => null);
 			if (file) total += file.size;
 		}
 	};
-	await visit(directory);
-	return total;
+	try {
+		await visit(directory, 0);
+		return total;
+	} catch {
+		return null;
+	}
 };
 /**
 * The usage figure to believe, given what the browser said and what a walk found.
@@ -156,6 +177,8 @@ var measureQuotaCeiling = async ({ probeBytes = 536870912, name = ".ponyfill-quo
 	}
 };
 //#endregion
+exports.MAX_DEPTH = MAX_DEPTH;
+exports.MAX_ENTRIES = MAX_ENTRIES;
 exports.QUOTA_CEILING = QUOTA_CEILING;
 exports.correctedUsage = correctedUsage;
 exports.isUsageUnderReported = isUsageUnderReported;

package/build/storage.d.ts

@@ -90,18 +90,35 @@ type WalkableFile = {
     }>;
 };
 /**
- * Every byte under a directory, measured rather than asked for.
+ * Never walk forever: a cycle is impossible in OPFS, but a pathological tree is not worth the tick.
  *
- * Recursive, and it counts a file's REPORTED SIZE, which for OPFS is the file's extent rather than
- * how much of it has been written. That is the same accounting the quota system uses, which is the
- * whole point: a one byte write a gigabyte into a file is charged a gigabyte, and a measurement that
- * disagreed with the charge would be no more useful than the figure it replaces.
- *
- * An unreadable entry is SKIPPED rather than fatal. A file the engine currently holds an exclusive
- * sync access handle for cannot be opened by anyone else, and a walk that threw on the first of
- * those would return nothing for exactly the origins that hold the most.
+ * These are bounds, not correctness: hitting either returns what was counted so far rather than
+ * failing, which keeps the answer a floor in the same direction as everything else here.
+ */
+export declare const MAX_DEPTH = 8;
+export declare const MAX_ENTRIES = 20000;
+/**
+ * Every byte under a directory, measured rather than asked for, or `null` when the walk could not
+ * be done at all.
+ *
+ * The null is a distinct third answer and callers depend on it: "the origin holds nothing" and "the
+ * file system was unreachable" lead to opposite decisions, and collapsing them to 0 would have
+ * {@link correctedUsage} report an empty origin for one that simply could not be read.
+ *
+ * Counts a file's REPORTED SIZE, which for OPFS is its extent rather than how much of it has been
+ * written. That is the same accounting the quota system uses, which is the point: a one byte write a
+ * gigabyte into a file is charged a gigabyte, and a measurement disagreeing with the charge would be
+ * no more useful than the figure it replaces.
+ *
+ * An unreadable ENTRY is skipped rather than fatal. A file the engine currently holds an exclusive
+ * sync access handle for cannot be opened by anyone else, and `getFile()` on it throws rather than
+ * waiting, so a walk that gave up on the first of those would return nothing for exactly the origins
+ * holding the most. The answer is therefore a floor: short by the files open right now, never long.
  */
-export declare const measureDirectoryBytes: (directory: WalkableDirectory) => Promise<number>;
+export declare const measureDirectoryBytes: (directory: WalkableDirectory, { maxDepth, maxEntries }?: {
+    maxDepth?: number;
+    maxEntries?: number;
+}) => Promise<number | null>;
 /**
  * The usage figure to believe, given what the browser said and what a walk found.
  *

package/build/storage.js

@@ -20,31 +20,52 @@ var QUOTA_CEILING = {
 };
 var isDirectory = (handle) => typeof handle.values === "function";
 /**
-* Every byte under a directory, measured rather than asked for.
+* Never walk forever: a cycle is impossible in OPFS, but a pathological tree is not worth the tick.
 *
-* Recursive, and it counts a file's REPORTED SIZE, which for OPFS is the file's extent rather than
-* how much of it has been written. That is the same accounting the quota system uses, which is the
-* whole point: a one byte write a gigabyte into a file is charged a gigabyte, and a measurement that
-* disagreed with the charge would be no more useful than the figure it replaces.
+* These are bounds, not correctness: hitting either returns what was counted so far rather than
+* failing, which keeps the answer a floor in the same direction as everything else here.
+*/
+var MAX_DEPTH = 8;
+var MAX_ENTRIES = 2e4;
+/**
+* Every byte under a directory, measured rather than asked for, or `null` when the walk could not
+* be done at all.
+*
+* The null is a distinct third answer and callers depend on it: "the origin holds nothing" and "the
+* file system was unreachable" lead to opposite decisions, and collapsing them to 0 would have
+* {@link correctedUsage} report an empty origin for one that simply could not be read.
+*
+* Counts a file's REPORTED SIZE, which for OPFS is its extent rather than how much of it has been
+* written. That is the same accounting the quota system uses, which is the point: a one byte write a
+* gigabyte into a file is charged a gigabyte, and a measurement disagreeing with the charge would be
+* no more useful than the figure it replaces.
 *
-* An unreadable entry is SKIPPED rather than fatal. A file the engine currently holds an exclusive
-* sync access handle for cannot be opened by anyone else, and a walk that threw on the first of
-* those would return nothing for exactly the origins that hold the most.
+* An unreadable ENTRY is skipped rather than fatal. A file the engine currently holds an exclusive
+* sync access handle for cannot be opened by anyone else, and `getFile()` on it throws rather than
+* waiting, so a walk that gave up on the first of those would return nothing for exactly the origins
+* holding the most. The answer is therefore a floor: short by the files open right now, never long.
 */
-var measureDirectoryBytes = async (directory) => {
+var measureDirectoryBytes = async (directory, { maxDepth = 8, maxEntries = MAX_ENTRIES } = {}) => {
 	let total = 0;
-	const visit = async (handle) => {
+	let seen = 0;
+	const visit = async (handle, depth) => {
+		if (depth > maxDepth) return;
 		for await (const child of handle.values()) {
+			if (++seen > maxEntries) return;
 			if (isDirectory(child)) {
-				await visit(child);
+				await visit(child, depth + 1);
 				continue;
 			}
 			const file = await child.getFile().catch(() => null);
 			if (file) total += file.size;
 		}
 	};
-	await visit(directory);
-	return total;
+	try {
+		await visit(directory, 0);
+		return total;
+	} catch {
+		return null;
+	}
 };
 /**
 * The usage figure to believe, given what the browser said and what a walk found.
@@ -155,4 +176,4 @@ var measureQuotaCeiling = async ({ probeBytes = 536870912, name = ".ponyfill-quo
 	}
 };
 //#endregion
-export { QUOTA_CEILING, correctedUsage, isUsageUnderReported, measureDirectoryBytes, measureQuotaCeiling, storage };
+export { MAX_DEPTH, MAX_ENTRIES, QUOTA_CEILING, correctedUsage, isUsageUnderReported, measureDirectoryBytes, measureQuotaCeiling, storage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/ponyfill",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "main": "build/index.cjs",
   "module": "build/index.js",