@poe-platform/safe-fs 0.1.154 → 0.1.155

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -52,12 +52,18 @@ export interface FileSystemCapabilities {
     readonly atomicRename?: boolean;
     readonly snapshotRmdir?: boolean;
     readonly streamingRead?: boolean;
+    readonly retainedRead?: boolean;
     readonly streamingWrite?: boolean;
     readonly [capability: string]: boolean | undefined;
 }
 export interface FsOptions {
     readonly signal?: AbortSignal;
 }
+export interface FileReadHandle {
+    stat(options?: FsOptions): Promise<FileStat>;
+    read(position: number, maxBytes: number, options?: FsOptions): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
 export interface ReadFileOptions extends FsOptions {
     readonly maxBytes?: number;
 }
@@ -96,6 +102,7 @@ export interface ReadStreamOptions extends FsOptions {
 }
 export interface FileSystem {
     readonly capabilities: FileSystemCapabilities;
+    openReadFile?(path: string, options?: FsOptions): Promise<FileReadHandle>;
     canonicalizeMissingTarget?(path: string, options?: FsOptions): string | undefined;
     capabilitiesFor?(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;

package/dist/safe-fs/fs/capabilities.d.ts

@@ -1,4 +1,6 @@
-import type { FileSystemCapabilities } from "../contracts/filesystem.js";
+import type { FileReadHandle, FileSystem, FileSystemCapabilities, FsOptions } from "../contracts/filesystem.js";
+export declare function retainedReadCapabilities(filesystem: FileSystem, capabilities?: FileSystemCapabilities): FileSystemCapabilities;
+export declare function openRetainedReadFile(filesystem: FileSystem, path: string, options: FsOptions): Promise<FileReadHandle>;
 export declare function requireCapabilities(...values: readonly (boolean | undefined)[]): boolean | undefined;
 export declare function readOnlyCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function quotaCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;

package/dist/safe-fs/fs/capabilities.js

@@ -1,10 +1,36 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+export function retainedReadCapabilities(filesystem, capabilities = filesystem.capabilities) {
+    return typeof filesystem.openReadFile === "function" ? capabilities : { ...capabilities, retainedRead: false };
+}
+export async function openRetainedReadFile(filesystem, path, options) {
+    let handle;
+    try {
+        options.signal?.throwIfAborted();
+        if (typeof filesystem.openReadFile !== "function")
+            throw new FsError("ENOTSUP", { syscall: "openReadFile", path });
+        const capabilities = await filesystem.capabilitiesFor?.(path, options) ?? filesystem.capabilities;
+        options.signal?.throwIfAborted();
+        if (retainedReadCapabilities(filesystem, capabilities).retainedRead !== true)
+            throw new FsError("ENOTSUP", { syscall: "openReadFile", path });
+        handle = await filesystem.openReadFile(path, options);
+        options.signal?.throwIfAborted();
+        return handle;
+    }
+    catch (error) {
+        if (handle)
+            await finishCleanup(() => handle.close(), true);
+        options.signal?.throwIfAborted();
+        throw error;
+    }
+}
 export function requireCapabilities(...values) {
     return values.some(value => value === false) ? false : values.every(value => value === true) ? true : undefined;
 }
 export function readOnlyCapabilities(capabilities) {
     const inspection = Object.fromEntries([
         "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories",
-        "symlinks", "streamingRead",
+        "symlinks", "streamingRead", "retainedRead",
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
         ...inspection, readOnly: true, write: false, append: false, exclusiveCreate: false,

package/dist/safe-fs/fs/memory/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileStat, FileSystem, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileStat, FileSystem, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 export declare class MemoryFileSystem implements FileSystem {
     readonly capabilities: Readonly<{
@@ -31,6 +31,7 @@ export declare class MemoryFileSystem implements FileSystem {
         timestamps: true;
         atomicRename: true;
         streamingRead: true;
+        retainedRead: true;
         streamingWrite: true;
     }>;
     private readonly identityScope;
@@ -75,6 +76,7 @@ export declare class MemoryFileSystem implements FileSystem {
     chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
     utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
     truncate(path: string, length?: number, options?: FsOptions): Promise<void>;
+    openReadFile(path: string, options?: FsOptions): Promise<FileReadHandle>;
     readStream(path: string, options?: ReadStreamOptions): ByteSource;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
 }

package/dist/safe-fs/fs/memory/index.js

@@ -62,6 +62,7 @@ export class MemoryFileSystem {
         timestamps: true,
         atomicRename: true,
         streamingRead: true,
+        retainedRead: true,
         streamingWrite: true,
     });
     identityScope = Symbol();
@@ -512,6 +513,55 @@ export class MemoryFileSystem {
         node.data = data;
         this.changed(node);
     }
+    async openReadFile(path, options = {}) {
+        options.signal?.throwIfAborted();
+        const unsupported = () => { throw new FsError("ENOTSUP", { syscall: "openReadFile", path }); };
+        const owner = ownedStores.get(this);
+        if (!owner || Object.getPrototypeOf(this) !== MemoryFileSystem.prototype
+            || Object.getOwnPropertyDescriptor(this, "root")?.value !== owner.root)
+            unsupported();
+        for (const name of ["openReadFile", "readFile", "readStream", "stat", "lstat", "realpath", "access",
+            "file", "resolve", "permission", "validatePath", "fail", "snapshot", "integer"]) {
+            const descriptor = Object.getOwnPropertyDescriptor(this, name)
+                ?? Object.getOwnPropertyDescriptor(MemoryFileSystem.prototype, name);
+            if (!descriptor || !("value" in descriptor) || descriptor.value !== memoryImplementation[name]?.value)
+                unsupported();
+        }
+        if (Object.getOwnPropertyDescriptor(this, "capabilities")?.value?.retainedRead !== true)
+            unsupported();
+        let node = this.file(path, "openReadFile");
+        this.permission(node, 4, "openReadFile", path);
+        const snapshot = this.snapshot.bind(this);
+        const integer = this.integer.bind(this);
+        let closing;
+        const current = (signal, syscall) => {
+            signal?.throwIfAborted();
+            if (!node)
+                throw new FsError("EBADF", { syscall, path });
+            return node;
+        };
+        return {
+            async stat(options = {}) {
+                return snapshot(current(options.signal, "fstat"));
+            },
+            async read(position, maxBytes, options = {}) {
+                const file = current(options.signal, "read");
+                integer(position, "read", path);
+                integer(maxBytes, "read", path);
+                if (maxBytes === 0 || maxBytes > Number.MAX_SAFE_INTEGER - position) {
+                    throw new FsError("EINVAL", { syscall: "read", path });
+                }
+                const bytes = file.data.slice(position, position + maxBytes);
+                file.atimeMs = Date.now();
+                return bytes;
+            },
+            close() {
+                node = undefined;
+                closing ??= Promise.resolve();
+                return closing;
+            },
+        };
+    }
     async *readStream(path, options = {}) {
         options.signal?.throwIfAborted();
         const start = options.start ?? 0;

package/dist/safe-fs/fs/mount/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 export interface MountFileSystemOptions {
     readonly root: FileSystem;
@@ -11,6 +11,7 @@ export declare class MountFileSystem implements FileSystem {
     private select;
     capabilitiesFor(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
     private protected;
+    openReadFile(path: string, options?: FsOptions): Promise<FileReadHandle>;
     private error;
     private operation;
     private components;

package/dist/safe-fs/fs/mount/index.js

@@ -1,7 +1,7 @@
 import { FsError, isFsError, toFsError } from "../../contracts/errors.js";
 import { readBytes } from "../../contracts/io.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
-import { readOnlyCapabilities } from "../capabilities.js";
+import { openRetainedReadFile, readOnlyCapabilities, retainedReadCapabilities } from "../capabilities.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { normalizePath, validatePath } from "../../contracts/virtual-path.js";
 import { compareIdentity } from "./identity.js";
@@ -79,6 +79,7 @@ export class MountFileSystem {
         const streaming = (capability, method) => all(capability, [method]) ? true : mounts.some(({ backend }) => backend.capabilities[capability] !== false && typeof backend[method] === "function") ? undefined : false;
         const streamingRead = streaming("streamingRead", "readStream");
         const streamingWrite = streaming("streamingWrite", "writeStream");
+        const retainedRead = streaming("retainedRead", "openReadFile");
         const append = all("append") ? true
             : mounts.every(({ backend }) => backend.capabilities.append === false) ? false : undefined;
         const common = (capability) => {
@@ -110,6 +111,7 @@ export class MountFileSystem {
             atomicRename: mounts.length === 1 && all("atomicRename"),
             ...(streamingRead === undefined ? {} : { streamingRead }),
             ...(streamingWrite === undefined ? {} : { streamingWrite }),
+            ...(retainedRead === undefined ? {} : { retainedRead }),
         });
     }
     select(path) {
@@ -118,8 +120,10 @@ export class MountFileSystem {
     async capabilitiesFor(path, options = {}) {
         return this.operation("capabilitiesFor", path, options, async () => {
             const location = await this.resolve(path, options, { allowMissing: true });
-            const capabilities = await location.mount.backend.capabilitiesFor?.(location.local, options)
+            const declared = await location.mount.backend.capabilitiesFor?.(location.local, options)
                 ?? location.mount.backend.capabilities;
+            const capabilities = location.synthetic ? { ...declared, retainedRead: false }
+                : retainedReadCapabilities(location.mount.backend, declared);
             if (location.synthetic)
                 return readOnlyCapabilities(capabilities);
             if (this.mounts.length === 1 || capabilities.readOnly === true)
@@ -136,6 +140,18 @@ export class MountFileSystem {
     protected(path) {
         return path === "/" || this.mounts.some((mount) => within(path, mount.path));
     }
+    async openReadFile(path, options = {}) {
+        try {
+            options.signal?.throwIfAborted();
+            const location = await this.resolve(path, options);
+            if (location.synthetic)
+                fail("EISDIR");
+            return await openRetainedReadFile(location.mount.backend, location.local, options);
+        }
+        catch (error) {
+            throw error ? this.error(error, "openReadFile", path, options) : error;
+        }
+    }
     error(error, syscall, path, options, dest) {
         if (options.signal?.aborted && error === options.signal.reason)
             return error;

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

@@ -18,6 +18,8 @@ export declare class OverlayFileSystem implements FileSystem {
     private queue;
     constructor(options: OverlayFileSystemOptions);
     private run;
+    capabilitiesFor(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
+    openReadFile(path: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").FileReadHandle>;
     private writable;
     private permission;
     private maybeStat;

package/dist/safe-fs/fs/overlay/index.js

@@ -1,5 +1,5 @@
 import { platform } from "#safe-fs-platform";
-import { requireCapabilities } from "../capabilities.js";
+import { openRetainedReadFile, requireCapabilities, retainedReadCapabilities } from "../capabilities.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
 import { collectBytes, readBytes } from "../../contracts/io.js";
 import { FsError, toFsError } from "../../contracts/errors.js";
@@ -79,6 +79,9 @@ export class OverlayFileSystem {
         const readable = [this.#upper, this.#lower].map((backend) => typeof backend.readStream === "function" ? backend.capabilities.streamingRead : false);
         const streamingRead = readable.every((capability) => capability === true) ? true
             : readable.every((capability) => capability === false) ? false : undefined;
+        const retained = [this.#upper, this.#lower].map((backend) => retainedReadCapabilities(backend).retainedRead);
+        const retainedRead = retained.every((capability) => capability === true) ? true
+            : retained.every((capability) => capability === false) ? false : undefined;
         const streamingWrite = writable && this.#upper.capabilities.streamingWrite === true
             && this.#upper.capabilities.streamingRead === true
             && typeof this.#upper.writeStream === "function" && typeof this.#upper.readStream === "function"
@@ -122,6 +125,7 @@ export class OverlayFileSystem {
             permissions: writable && this.#upper.capabilities.permissions === true && typeof this.#upper.chmod === "function",
             timestamps: writable && this.#upper.capabilities.timestamps === true && typeof this.#upper.utimes === "function",
             ...(streamingRead === undefined ? {} : { streamingRead }),
+            ...(retainedRead === undefined ? {} : { retainedRead }),
             ...(effectiveStreamingWrite === undefined ? {} : { streamingWrite: effectiveStreamingWrite }),
         });
         Object.defineProperty(this, "capabilities", { writable: false, configurable: false });
@@ -148,6 +152,26 @@ export class OverlayFileSystem {
             release();
         }
     }
+    capabilitiesFor(path, options = {}) {
+        return this.run(options, async () => {
+            const location = await this.resolve(path, options, true, true);
+            const backend = location.entry?.backend ?? this.#upper;
+            const capabilities = await backend.capabilitiesFor?.(location.path, options) ?? backend.capabilities;
+            options.signal?.throwIfAborted();
+            const { retainedRead: ignoredRetainedRead, ...composed } = this.capabilities;
+            const retainedRead = retainedReadCapabilities(backend, capabilities).retainedRead;
+            return Object.freeze({ ...composed, ...(retainedRead === undefined ? {} : { retainedRead }) });
+        }, false);
+    }
+    openReadFile(path, options = {}) {
+        return this.run(options, async () => {
+            const entry = await this.required(path, options);
+            if (entry.stat.type !== "file")
+                fail("EISDIR", path);
+            this.permission(entry, 4);
+            return openRetainedReadFile(entry.backend, entry.path, options);
+        }, false);
+    }
     writable(path) {
         if (this.#upper.capabilities.readOnly)
             fail("EROFS", path);

package/dist/safe-fs/fs/quota/index.js

@@ -1,5 +1,5 @@
 import { FsError } from "../../contracts/errors.js";
-import { quotaCapabilities } from "../capabilities.js";
+import { openRetainedReadFile, quotaCapabilities, retainedReadCapabilities } from "../capabilities.js";
 import { admitDirectoryEntries } from "../directory-admission.js";
 export class FileSystemQuotaError extends Error {
     maxBytes;
@@ -173,9 +173,14 @@ export function withFileSystemQuota(fs, options) {
             if (property === "canonicalizeMissingTarget")
                 return undefined;
             if (property === "capabilities")
-                return quotaCapabilities(fs.capabilities);
+                return quotaCapabilities(retainedReadCapabilities(fs));
             if (property === "capabilitiesFor")
-                return async (path, fsOptions) => quotaCapabilities(await fs.capabilitiesFor?.(path, fsOptions) ?? fs.capabilities);
+                return async (path, fsOptions) => {
+                    const capabilities = await fs.capabilitiesFor?.(path, fsOptions) ?? fs.capabilities;
+                    return quotaCapabilities(retainedReadCapabilities(fs, capabilities));
+                };
+            if (property === "openReadFile")
+                return (path, fsOptions = {}) => openRetainedReadFile(fs, path, fsOptions);
             const replacement = Reflect.get(mutations, property);
             if (typeof replacement === "function")
                 return replacement;

package/dist/safe-fs/fs/readonly/index.d.ts

@@ -5,6 +5,7 @@ export declare class ReadOnlyFileSystem implements FileSystem {
     constructor(filesystem: FileSystem);
     get capabilities(): FileSystemCapabilities;
     capabilitiesFor(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
+    openReadFile(path: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").FileReadHandle>;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;

package/dist/safe-fs/fs/readonly/index.js

@@ -2,7 +2,7 @@ import { ACCESS_MODES } from "../../contracts/filesystem.js";
 import { FsError } from "../../contracts/errors.js";
 import { readBytes } from "../../contracts/io.js";
 import { compareEntries, registerEntryView } from "../mount/comparison.js";
-import { readOnlyCapabilities } from "../capabilities.js";
+import { openRetainedReadFile, readOnlyCapabilities, retainedReadCapabilities } from "../capabilities.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 function readOnly(syscall, path, dest) {
     throw new FsError("EROFS", { syscall, path, ...(dest === undefined ? {} : { dest }) });
@@ -29,7 +29,7 @@ export class ReadOnlyFileSystem {
         registerEntryView(this, async (path) => ({ filesystem: this.#filesystem, path, readOnly: true }));
         const streamingRead = typeof filesystem.readStream === "function" ? filesystem.capabilities.streamingRead : false;
         this.#capabilities = readOnlyCapabilities({
-            ...filesystem.capabilities,
+            ...retainedReadCapabilities(filesystem),
             readOnly: true,
             append: false,
             symlinks: filesystem.capabilities.symlinks === true && typeof filesystem.readlink === "function",
@@ -46,7 +46,10 @@ export class ReadOnlyFileSystem {
     }
     async capabilitiesFor(path, options) {
         const capabilities = await this.#filesystem.capabilitiesFor?.(path, options) ?? this.#filesystem.capabilities;
-        return readOnlyCapabilities(capabilities);
+        return readOnlyCapabilities(retainedReadCapabilities(this.#filesystem, capabilities));
+    }
+    openReadFile(path, options = {}) {
+        return openRetainedReadFile(this.#filesystem, path, options);
     }
     async readFile(path, options) {
         return new Uint8Array(await this.#filesystem.readFile(path, options));

package/dist/safe-fs/fs/real/index.d.ts

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
+import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
 export interface RealFileSystemOptions {
     /** An existing, absolute host directory. It is never created implicitly. */
     readonly root: string;
@@ -69,6 +69,7 @@ export declare class RealFileSystem implements FileSystem {
     chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
     utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
     truncate(path: string, length?: number, options?: FsOptions): Promise<void>;
+    openReadFile(path: string, options?: FsOptions): Promise<FileReadHandle>;
     readStream(path: string, options?: ReadStreamOptions): ByteSource;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
 }

package/dist/safe-fs/fs/real/index.js

@@ -87,7 +87,7 @@ export class RealFileSystem {
         rename: true, copy: true, exclusiveCopy: true, readlink: true, truncate: true,
         streamingAppend: true, randomAccessWrite: true,
         readOnly: false, symlinks: true, hardlinks: true, permissions: true,
-        timestamps: true, atomicRename: true, streamingRead: true, streamingWrite: true,
+        timestamps: true, atomicRename: true, streamingRead: true, streamingWrite: true, retainedRead: true,
     });
     configuredRoot;
     rootPromise;
@@ -474,6 +474,116 @@ export class RealFileSystem {
             }
         });
     }
+    async openReadFile(path, options = {}) {
+        options.signal?.throwIfAborted();
+        const assertStock = () => {
+            const unsupported = () => { throw new FsError("ENOTSUP", { syscall: "openReadFile", path }); };
+            if (Object.getPrototypeOf(this) !== RealFileSystem.prototype)
+                unsupported();
+            for (const name of ["openReadFile", "readFile", "readStream", "stat", "lstat", "realpath", "access",
+                "root", "absoluteTarget", "walk", "path"]) {
+                const descriptor = Object.getOwnPropertyDescriptor(this, name)
+                    ?? Object.getOwnPropertyDescriptor(RealFileSystem.prototype, name);
+                if (!descriptor || !("value" in descriptor) || descriptor.value !== realImplementation[name]?.value)
+                    unsupported();
+            }
+            if (Object.getOwnPropertyDescriptor(this, "capabilities")?.value?.retainedRead !== true)
+                unsupported();
+        };
+        assertStock();
+        const failure = (error, syscall) => error
+            ? new FsError(nativeError(error).code, { syscall, path }) : error;
+        let resource;
+        try {
+            const target = await this.path(path, options);
+            options.signal?.throwIfAborted();
+            assertStock();
+            resource = await native.open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            options.signal?.throwIfAborted();
+            const stats = await resource.stat();
+            options.signal?.throwIfAborted();
+            assertStock();
+            if (stats.isDirectory())
+                throw new FsError("EISDIR");
+            if (!stats.isFile())
+                throw new FsError("ENOTSUP");
+        }
+        catch (error) {
+            await finishCleanup(async () => { await resource?.close(); }, true);
+            options.signal?.throwIfAborted();
+            throw failure(error, "openReadFile");
+        }
+        const handle = resource;
+        const pending = new Set();
+        let accepting = true;
+        let closing;
+        const assertOpen = (options, syscall) => {
+            options.signal?.throwIfAborted();
+            if (!accepting)
+                throw new FsError("EBADF", { syscall, path });
+        };
+        const perform = async (options, syscall, action) => {
+            assertOpen(options, syscall);
+            let settled;
+            const admitted = new Promise(resolve => { settled = resolve; });
+            pending.add(admitted);
+            try {
+                const value = await action();
+                options.signal?.throwIfAborted();
+                return value;
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                throw failure(error, syscall);
+            }
+            finally {
+                pending.delete(admitted);
+                settled();
+            }
+        };
+        return {
+            stat(options = {}) {
+                return perform(options, "fstat", async () => fileStat(await handle.stat()));
+            },
+            async read(position, maxBytes, options = {}) {
+                assertOpen(options, "read");
+                try {
+                    integer(position);
+                    integer(maxBytes, 1);
+                }
+                catch (error) {
+                    throw failure(error, "read");
+                }
+                if (maxBytes > Number.MAX_SAFE_INTEGER - position)
+                    throw new FsError("EINVAL", { syscall: "read", path });
+                return perform(options, "read", async () => {
+                    let bytes;
+                    try {
+                        bytes = new Uint8Array(maxBytes);
+                    }
+                    catch {
+                        throw new FsError("EFBIG");
+                    }
+                    const { bytesRead } = await handle.read(bytes, 0, bytes.byteLength, position);
+                    if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > maxBytes)
+                        throw new FsError("EIO");
+                    return bytes.slice(0, bytesRead);
+                });
+            },
+            close() {
+                accepting = false;
+                closing ??= Promise.all([...pending]).then(async () => {
+                    try {
+                        await handle.close();
+                    }
+                    catch (error) {
+                        throw failure(error, "close");
+                    }
+                });
+                return closing;
+            },
+        };
+    }
     async *readStream(path, options = {}) {
         const syscall = "readStream";
         let handle;
@@ -565,6 +675,7 @@ export class RealFileSystem {
         });
     }
 }
+const realImplementation = Object.getOwnPropertyDescriptors(RealFileSystem.prototype);
 /** Construct and validate an existing root before returning the backend. */
 export async function createRealFileSystem(options) {
     const filesystem = new RealFileSystem(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.154",
+  "version": "0.1.155",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",