@banou/ponyfill 0.0.4 → 0.0.5

package/README.md

@@ -58,10 +58,18 @@ That is not hypothetical. It is why four of ripple's storage eviction tests sat
 they filled the origin to provoke that condition, and 3.5 GB of padding left the free figure
 identical to the byte.
 
-This package does **not** invent a normalised quota, and does not add API for the difference either:
-on Chromium you really can write 10 more GiB, so the native answer is true, and there is no platform
-name for "which shape is this". It is written down here and in the source because the two are
-indistinguishable at rest, which is how the difference went unnoticed for months.
+**The behaviour picked is Firefox's: a ceiling does not rise because you put something under it.**
+`quota` is reported as the lowest the platform has stated for this origin, which needs no probe and
+no user agent sniffing, and invents nothing: the platform really did say the origin could hold that
+much. Two ordinary things are broken by the rising version, and both were seen in ripple:
+`usage / quota` as a gauge never fills, and `quota - usage < floor` never fires, so nothing can
+detect pressure at all.
+
+The cost is deliberate and in the safe direction. On Chromium, once bytes are written the reported
+headroom is smaller than what could really be written, so a caller reclaims cache slightly early.
+Cache is the thing that can be fetched again; a caller that never reclaims because it never sees
+pressure is the failure this replaces. The ceiling still follows the platform DOWNWARD, and is never
+reported below the bytes already held, so `quota - usage` reaches zero and never goes negative.
 
 ## Adding to it
 

package/build/storage.cjs

@@ -66,6 +66,40 @@ var reconcile = (estimate, walked) => {
 	}
 	return Math.max(reported, walked);
 };
+/**
+* The narrowest quota this origin has reported, which is the one that gets reported back.
+*
+* THE DIVERGENCE, AND THE PICK. `quota - usage` already means the same on both engines: bytes you
+* can still write. What diverges is `quota` as a TOTAL, and Chromium never states one. It states
+* `usage + headroom`, recomputed on every read, so the number grows as you fill the origin: measured
+* 10.737 GB rising to 12.353 GB across 1.615 GB written. Firefox states a real total and holds it.
+*
+* Two things a caller does with `quota` are broken by the growing version and neither is exotic:
+*
+*  - `usage / quota` as a gauge never fills, because the denominator runs away from the numerator.
+*    Ripple showed "2 MB / 10.74 GB" over a library holding 1.78 GB for exactly this reason.
+*  - `quota - usage < floor` never fires, so nothing can ever detect pressure. That is what left four
+*    of ripple's eviction tests failing for months against a condition that could not occur.
+*
+* So the behaviour picked here is FIREFOX'S: a ceiling, and a ceiling does not rise because you put
+* something under it. It is implemented as the lowest quota seen for this origin, which needs no
+* probe and no user agent sniffing, and it is TRUE in the strong sense: the platform really did say
+* the origin could hold this much, and nothing here invents a number the platform never stated.
+*
+* The cost is deliberate and is in the safe direction. On Chromium, once some bytes are written, the
+* reported headroom is smaller than what could really be written, so a caller reclaims cache
+* slightly early. Cache is the thing that can be fetched again; a caller that never reclaims because
+* it never sees pressure is the failure this replaces.
+*
+* In memory, and per page. Persisting it would mean owning storage to describe storage, and a reload
+* re-anchors on a figure the platform stated at that moment, which is the same guarantee.
+*/
+var narrowest;
+var ceiling = (reported, usage) => {
+	if (reported === void 0) return void 0;
+	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
+	return Math.max(narrowest, usage ?? 0);
+};
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
@@ -78,10 +112,11 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const walked = native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null;
+		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
 		return {
 			...estimate,
-			usage: reconcile(estimate, walked)
+			usage,
+			quota: ceiling(estimate.quota, usage)
 		};
 	},
 	persist: () => globalThis.navigator?.storage?.persist?.() ?? Promise.resolve(false),

package/build/storage.js

@@ -65,6 +65,40 @@ var reconcile = (estimate, walked) => {
 	}
 	return Math.max(reported, walked);
 };
+/**
+* The narrowest quota this origin has reported, which is the one that gets reported back.
+*
+* THE DIVERGENCE, AND THE PICK. `quota - usage` already means the same on both engines: bytes you
+* can still write. What diverges is `quota` as a TOTAL, and Chromium never states one. It states
+* `usage + headroom`, recomputed on every read, so the number grows as you fill the origin: measured
+* 10.737 GB rising to 12.353 GB across 1.615 GB written. Firefox states a real total and holds it.
+*
+* Two things a caller does with `quota` are broken by the growing version and neither is exotic:
+*
+*  - `usage / quota` as a gauge never fills, because the denominator runs away from the numerator.
+*    Ripple showed "2 MB / 10.74 GB" over a library holding 1.78 GB for exactly this reason.
+*  - `quota - usage < floor` never fires, so nothing can ever detect pressure. That is what left four
+*    of ripple's eviction tests failing for months against a condition that could not occur.
+*
+* So the behaviour picked here is FIREFOX'S: a ceiling, and a ceiling does not rise because you put
+* something under it. It is implemented as the lowest quota seen for this origin, which needs no
+* probe and no user agent sniffing, and it is TRUE in the strong sense: the platform really did say
+* the origin could hold this much, and nothing here invents a number the platform never stated.
+*
+* The cost is deliberate and is in the safe direction. On Chromium, once some bytes are written, the
+* reported headroom is smaller than what could really be written, so a caller reclaims cache
+* slightly early. Cache is the thing that can be fetched again; a caller that never reclaims because
+* it never sees pressure is the failure this replaces.
+*
+* In memory, and per page. Persisting it would mean owning storage to describe storage, and a reload
+* re-anchors on a figure the platform stated at that moment, which is the same guarantee.
+*/
+var narrowest;
+var ceiling = (reported, usage) => {
+	if (reported === void 0) return void 0;
+	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
+	return Math.max(narrowest, usage ?? 0);
+};
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
@@ -77,10 +111,11 @@ var storage = {
 		const native = globalThis.navigator?.storage;
 		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const walked = native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null;
+		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
 		return {
 			...estimate,
-			usage: reconcile(estimate, walked)
+			usage,
+			quota: ceiling(estimate.quota, usage)
 		};
 	},
 	persist: () => globalThis.navigator?.storage?.persist?.() ?? Promise.resolve(false),

package/package.json

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