just-binary 3.0.2 → 3.1.0

package/dist/fs/in-memory-fs/in-memory-fs.d.ts

@@ -20,6 +20,7 @@ export declare class InMemoryFs implements IFileSystem {
         mtime?: Date;
     }): void;
     readFile(path: string): Promise<ByteStream>;
+    readRange(path: string, offset: number, length: number): Promise<Uint8Array>;
     readFileText(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
     writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
     appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;

package/dist/fs/interface.d.ts

@@ -75,6 +75,17 @@ export interface IFileSystem {
      * @throws if path does not exist or is a directory
      */
     readFile(path: string): Promise<ByteStream>;
+    /**
+     * Read a byte range from a file. Returns at most `length` bytes starting at
+     * `offset`; if the range extends past EOF, returns the truncated tail (may
+     * be empty). Designed for random-access workloads (ZIP central directory,
+     * PDF xref, file footers) that would otherwise have to drain the whole
+     * stream into memory.
+     *
+     * @throws if path does not exist or is a directory, or if offset/length
+     *   are negative or non-finite
+     */
+    readRange(path: string, offset: number, length: number): Promise<Uint8Array>;
     /**
      * Read a file fully as decoded text (default encoding: utf8).
      * Convenience for small/text files.

package/dist/fs/mountable-fs/mountable-fs.d.ts

@@ -85,6 +85,7 @@ export declare class MountableFs implements IFileSystem {
      */
     private getChildMountPoints;
     readFile(path: string): Promise<ByteStream>;
+    readRange(path: string, offset: number, length: number): Promise<Uint8Array>;
     readFileText(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
     writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
     appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;

package/dist/fs/overlay-fs/overlay-fs.d.ts

@@ -80,6 +80,13 @@ export declare class OverlayFs implements IFileSystem {
      */
     private existsInOverlay;
     readFile(path: string): Promise<ByteStream>;
+    readRange(path: string, offset: number, length: number): Promise<Uint8Array>;
+    /**
+     * Resolve a path through symlinks for read purposes, returning either the
+     * in-memory chunked representation or the underlying real-fs path so the
+     * caller can choose between random-access and full reads.
+     */
+    private resolveForRead;
     readFileText(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
     /**
      * Internal: resolve symlinks and produce raw chunks. Memory hits return

package/dist/fs/range.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared helpers for readRange implementations across filesystem backends.
+ */
+export declare function validateRange(offset: number, length: number): void;
+/**
+ * Slice a contiguous byte range out of a chunked file representation. Walks
+ * chunks lazily; only the requested bytes are copied into the output. If the
+ * requested range extends past `totalSize`, the result is truncated.
+ */
+export declare function sliceChunks(chunks: Uint8Array[], totalSize: number, offset: number, length: number): Uint8Array;

package/dist/fs/read-write-fs/read-write-fs.d.ts

@@ -35,6 +35,7 @@ export declare class ReadWriteFs implements IFileSystem {
      */
     private normalizePath;
     readFile(path: string): Promise<ByteStream>;
+    readRange(path: string, offset: number, length: number): Promise<Uint8Array>;
     readFileText(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
     writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
     appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "just-binary",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "A simulated bash environment with virtual filesystem",
   "repository": {
     "type": "git",