@stacksjs/storage 0.75.224 → 0.75.226

package/README.md

@@ -47,6 +47,35 @@ import {
 
 To view the full documentation, please visit [<https://stacksjs.com/storag>e](https://stacksjs.com/storage).
 
+## Bounded local text reads
+
+Use the standalone entrypoint for local text supplied by a user or worker:
+
+```ts
+import { readBoundedTextFile } from '@stacksjs/storage/bounded-text-file'
+
+const journal = await readBoundedTextFile(inputPath, { maxBytes: 4 * 1024 * 1024 })
+```
+
+`maxBytes` is required and counts encoded bytes. It accepts nonnegative integers
+below the runtime's `node:buffer` `constants.MAX_LENGTH`. The function checks the
+opened descriptor is a regular file and its size fits, then reads at most
+`maxBytes + 1` bytes to catch growth. It rejects malformed UTF-8 and always closes
+the opened descriptor. A UTF-8 BOM counts toward the limit and is omitted from
+the decoded string, following `TextDecoder` behavior.
+
+The final path component cannot be a symlink. Nonblocking opening rejects FIFOs
+without waiting for a writer. Platforms without `O_NOFOLLOW` and `O_NONBLOCK`
+support fail closed. Parent-directory symlinks are followed; callers still own
+path authorization. Concurrent edits are not an atomic content snapshot.
+
+`BoundedTextFileError.code` identifies `NOT_REGULAR_FILE`, `FILE_TOO_LARGE`,
+`INVALID_UTF8`, or `UNSUPPORTED_PLATFORM`. Invalid limits throw `RangeError`.
+Native filesystem failures propagate unchanged, including `ENOENT` and the
+platform's final-symlink error. The function and its types are also exported
+from `@stacksjs/storage`. Existing `readTextFile` and disk readers keep their
+current behavior.
+
 ## 🧪 Testing
 
 ```bash

package/dist/bounded-text-file.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Read a local regular file as strict UTF-8, consuming at most maxBytes + 1.
+ * Reject final-component symlinks and open special files without waiting for
+ * a FIFO writer. Parent directories are followed: callers own path authorization.
+ * This is a bounded read of a changing file, not an atomic content snapshot.
+ * Native open/stat/read/close errors propagate unchanged; the descriptor closes
+ * on every path after a successful open. Unsupported safety flags fail closed.
+ */
+export declare function readBoundedTextFile(path: string, options: BoundedTextFileOptions): Promise<string>;
+export declare interface BoundedTextFileOptions {
+  maxBytes: number
+}
+export type BoundedTextFileErrorCode = 'NOT_REGULAR_FILE' | 'FILE_TOO_LARGE' | 'INVALID_UTF8' | 'UNSUPPORTED_PLATFORM';
+export declare class BoundedTextFileError extends Error {
+  readonly code: BoundedTextFileErrorCode;
+  constructor(code: BoundedTextFileErrorCode, message: string, options?: ErrorOptions);
+}

package/dist/bounded-text-file.js

@@ -0,0 +1 @@
+import{constants as bufferConstants}from"node:buffer";import{constants}from"node:fs";import{open}from"node:fs/promises";export class BoundedTextFileError extends Error{code;constructor(code,message,options){super(message,options);this.name="BoundedTextFileError";this.code=code}}export async function readBoundedTextFile(path,options){const{maxBytes}=options;if(!Number.isSafeInteger(maxBytes)||maxBytes<0||maxBytes>=bufferConstants.MAX_LENGTH)throw RangeError(`maxBytes must be an integer between 0 and ${bufferConstants.MAX_LENGTH-1}`);if(!constants.O_NOFOLLOW||!constants.O_NONBLOCK)throw new BoundedTextFileError("UNSUPPORTED_PLATFORM","Bounded text reads require O_NOFOLLOW and O_NONBLOCK support");const file=await open(path,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);try{const stat=await file.stat();if(!stat.isFile())throw new BoundedTextFileError("NOT_REGULAR_FILE","Text input must be a regular file");if(stat.size>maxBytes)throw new BoundedTextFileError("FILE_TOO_LARGE",`Text file exceeds ${maxBytes} bytes`);const bytes=new Uint8Array(maxBytes+1);let length=0;while(length<bytes.length){const{bytesRead}=await file.read(bytes,length,bytes.length-length,null);if(bytesRead===0)break;length+=bytesRead}if(length>maxBytes)throw new BoundedTextFileError("FILE_TOO_LARGE",`Text file exceeds ${maxBytes} bytes`);try{return new TextDecoder("utf-8",{fatal:!0}).decode(bytes.subarray(0,length))}catch(cause){throw new BoundedTextFileError("INVALID_UTF8","Text file must contain valid UTF-8",{cause})}}finally{await file.close()}}

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export type {
 export * from './copy';
 export * from './delete';
 export * from './files';
+export * from './bounded-text-file';
 export * from './folders';
 export * from './fs';
 export * from './temporary-workspaces';

package/dist/index.js

@@ -1 +1 @@
-export*from"./copy";export*from"./delete";export*from"./files";export*from"./folders";export*from"./fs";export*from"./temporary-workspaces";export*from"./glob";export*from"./hash";export*from"./helpers";export* as storage from"./storage";export*from"./zip";export{ensureBucket,ensureConfiguredBuckets}from"./provision";export*from"./adapters";export*from"./types";export*from"./drivers";export{serveFile}from"./static-serve";export{Storage,StorageManager}from"./facade";export{UploadedFile,uploadedFile,uploadedFiles}from"./uploaded-file";export{azureDisk,backblazeDisk,configFromEnv,filebaseDisk,gcsDisk,hetznerDisk,localDisk,r2Disk,s3Disk}from"./types/filesystem";export{clearRevokedSignedStorageTokens,createSignedStorageToken,isSignedStorageTokenRevoked,revokeSignedStorageToken,verifySignedStorageToken}from"./signed-url";export{parseDiskPath,PathSanitizeError,sanitizePresignedDir,sanitizePresignedFilename}from"./path-sanitize";export{fileInfo,fileInfoFromBytes,fileKind,isPreviewable,resolveMime}from"./file-info";export{detectMimeFromMagicBytes,verifyUploadedMime}from"./mime-verify";export{signS3PresignedPost}from"./s3-presigned-post";
+export*from"./copy";export*from"./delete";export*from"./files";export*from"./bounded-text-file";export*from"./folders";export*from"./fs";export*from"./temporary-workspaces";export*from"./glob";export*from"./hash";export*from"./helpers";export* as storage from"./storage";export*from"./zip";export{ensureBucket,ensureConfiguredBuckets}from"./provision";export*from"./adapters";export*from"./types";export*from"./drivers";export{serveFile}from"./static-serve";export{Storage,StorageManager}from"./facade";export{UploadedFile,uploadedFile,uploadedFiles}from"./uploaded-file";export{azureDisk,backblazeDisk,configFromEnv,filebaseDisk,gcsDisk,hetznerDisk,localDisk,r2Disk,s3Disk}from"./types/filesystem";export{clearRevokedSignedStorageTokens,createSignedStorageToken,isSignedStorageTokenRevoked,revokeSignedStorageToken,verifySignedStorageToken}from"./signed-url";export{parseDiskPath,PathSanitizeError,sanitizePresignedDir,sanitizePresignedFilename}from"./path-sanitize";export{fileInfo,fileInfoFromBytes,fileKind,isPreviewable,resolveMime}from"./file-info";export{detectMimeFromMagicBytes,verifyUploadedMime}from"./mime-verify";export{signS3PresignedPost}from"./s3-presigned-post";

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/storage",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.224",
+  "version": "0.75.226",
   "description": "The Stacks file system.",
   "author": "Chris Breuer",
   "contributors": [
@@ -61,20 +61,20 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/arrays": "0.75.224",
-    "@stacksjs/cli": "0.75.224",
-    "@stacksjs/config": "0.75.224",
-    "@stacksjs/env": "0.75.224",
-    "@stacksjs/error-handling": "0.75.224",
-    "@stacksjs/logging": "0.75.224",
-    "@stacksjs/path": "0.75.224",
-    "@stacksjs/strings": "0.75.224",
+    "@stacksjs/arrays": "0.75.226",
+    "@stacksjs/cli": "0.75.226",
+    "@stacksjs/config": "0.75.226",
+    "@stacksjs/env": "0.75.226",
+    "@stacksjs/error-handling": "0.75.226",
+    "@stacksjs/logging": "0.75.226",
+    "@stacksjs/path": "0.75.226",
+    "@stacksjs/strings": "0.75.226",
     "@stacksjs/ts-cloud": "^0.16.58",
     "@stacksjs/ts-xml": "^0.1.0",
     "ts-images": "^0.2.23"
   },
   "devDependencies": {
-    "@stacksjs/types": "0.75.224",
+    "@stacksjs/types": "0.75.226",
     "better-dx": "^0.2.24"
   }
 }