@openclaw/fs-safe 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.3 - 2026-07-18
+
+### Compatibility
+
+- Restore the pre-0.4.2 `readRegularFile` and `readRegularFileSync` overflow error message while retaining allocation-bounded reads and the structured `too-large` error on the new low-level bounded-read primitives.
+
 ## 0.4.2 - 2026-07-18
 
 ### Features

package/dist/regular-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAW7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AAWD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAuD3C;AA+CD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAwBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}
+{"version":3,"file":"regular-file.d.ts","sourceRoot":"","sources":["../src/regular-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,MAAM,MAAM,SAAS,CAAC;AAW7B,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAExF,KAAK,8BAA8B,GAAG,IAAI,CACxC,OAAO,MAAM,CAAC,SAAS,EACvB,UAAU,GAAG,SAAS,GAAG,UAAU,CACpC,GACC,OAAO,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,8BAAiD,GAC3D,MAAM,CAQR;AAsBD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CActF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAc3E;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CAyD3C;AAoDD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,KAAK,CAAC;CACb,CAqBA;AAmBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDxF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CA2D7E"}

package/dist/regular-file.js

@@ -20,6 +20,15 @@ function resolveRegularFileReadFlags() {
             ? fsSync.constants.O_NOFOLLOW
             : 0));
 }
+function regularFileTooLargeError(filePath, maxBytes, cause) {
+    return new FsSafeError("too-large", `File exceeds ${maxBytes} bytes: ${filePath}`, { cause });
+}
+function translateBoundedReadOverflow(error, filePath, maxBytes) {
+    if (error instanceof FsSafeError && error.code === "too-large") {
+        throw regularFileTooLargeError(filePath, maxBytes, error);
+    }
+    throw error;
+}
 export async function statRegularFile(filePath) {
     let stat;
     try {
@@ -59,7 +68,7 @@ export async function readRegularFile(params) {
         throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
     }
     if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${result.stat.size})`);
+        throw regularFileTooLargeError(params.filePath, params.maxBytes);
     }
     let handle;
     try {
@@ -90,13 +99,23 @@ export async function readRegularFile(params) {
             preOpenStat: result.stat,
         });
         if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-            throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${stat.size})`);
+            throw regularFileTooLargeError(params.filePath, params.maxBytes);
         }
         // With a byte cap, avoid readFile(): a raced file growth would allocate
         // the oversized content before the post-read check could reject it.
-        const buffer = params.maxBytes === undefined
-            ? await handle.readFile()
-            : await readFileHandleBounded(handle, params.maxBytes);
+        let buffer;
+        try {
+            buffer =
+                params.maxBytes === undefined
+                    ? await handle.readFile()
+                    : await readFileHandleBounded(handle, params.maxBytes);
+        }
+        catch (error) {
+            if (params.maxBytes !== undefined) {
+                translateBoundedReadOverflow(error, params.filePath, params.maxBytes);
+            }
+            throw error;
+        }
         return { buffer, stat };
     }
     finally {
@@ -121,13 +140,23 @@ function readOpenedRegularFileSync(params) {
         preOpenStat: params.preOpenStat,
     });
     if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${stat.size})`);
+        throw regularFileTooLargeError(params.filePath, params.maxBytes);
     }
     // Keep capped sync reads incremental for the same reason as async reads:
     // readFileSync(fd) would buffer a raced oversized file before throwing.
-    const buffer = params.maxBytes === undefined
-        ? fsSync.readFileSync(params.fd)
-        : readFileDescriptorBoundedSync(params.fd, params.maxBytes);
+    let buffer;
+    try {
+        buffer =
+            params.maxBytes === undefined
+                ? fsSync.readFileSync(params.fd)
+                : readFileDescriptorBoundedSync(params.fd, params.maxBytes);
+    }
+    catch (error) {
+        if (params.maxBytes !== undefined) {
+            translateBoundedReadOverflow(error, params.filePath, params.maxBytes);
+        }
+        throw error;
+    }
     return { buffer, stat };
 }
 export function readRegularFileSync(params) {
@@ -137,7 +166,7 @@ export function readRegularFileSync(params) {
         throw Object.assign(new Error(`File not found: ${params.filePath}`), { code: "ENOENT" });
     }
     if (params.maxBytes !== undefined && result.stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${result.stat.size})`);
+        throw regularFileTooLargeError(params.filePath, params.maxBytes);
     }
     const fd = fsSync.openSync(params.filePath, resolveRegularFileReadFlags());
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {