@poe-platform/safe-fs 0.1.512 → 0.1.513

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

@@ -8,6 +8,7 @@ import { MemoryAllocation, MemoryLedger } from "./ledger.js";
 import { normalizeMemoryFileSystemLimits } from "./limits.js";
 export { defaultMemoryFileSystemLimits } from "./limits.js";
 const typeModes = { file: 0o100000, directory: 0o040000, symlink: 0o120000 };
+const ext4HtreeEof64 = (1n << 63n) - 1n;
 const ownedStats = new WeakMap();
 const ownedStores = new WeakMap();
 const registeredAuthorities = new WeakSet();
@@ -67,6 +68,7 @@ export class MemoryFileSystem {
             atomicRename: true,
             streamingRead: true,
             retainedRead: true,
+            get retainedResize() { return stockRetainedResize(filesystem); },
             streamingWrite: true,
             get descriptorWriteStream() { return stockDescriptorWrite(filesystem); },
         });
@@ -82,6 +84,7 @@ export class MemoryFileSystem {
         const root = this.root;
         ownedStores.set(this, {
             root,
+            ledger: this.ledger,
             capabilities: this.capabilities,
             intact: () => this.root === root,
         });
@@ -181,7 +184,7 @@ export class MemoryFileSystem {
         this.validatePath(path, syscall);
         const pending = path.split("/").filter(Boolean);
         if (path.endsWith("/"))
-            pending.push(".");
+            pending.push("");
         const stack = [{ node: this.root, name: "" }];
         let links = 0;
         while (pending.length > 0) {
@@ -189,8 +192,9 @@ export class MemoryFileSystem {
             const current = stack[stack.length - 1].node;
             if (current.type !== "directory")
                 this.fail("ENOTDIR", syscall, path);
-            this.permission(current, 1, syscall, path);
-            if (component === ".")
+            if (!(component === "" && pending.length === 0 && options.resizeCreate !== undefined))
+                this.permission(current, 1, syscall, path);
+            if (component === "." || component === "")
                 continue;
             if (component === "..") {
                 if (stack.length > 1)
@@ -199,6 +203,8 @@ export class MemoryFileSystem {
             }
             if (new TextEncoder().encode(component).byteLength > 255)
                 this.fail("ENAMETOOLONG", syscall, path);
+            if (options.resizeCreate === true && pending.length === 1 && pending[0] === "")
+                this.fail("EISDIR", syscall, path);
             let node = current.entries.get(component);
             if (!node && options.createDirectories !== undefined) {
                 this.permission(current, 3, syscall, path);
@@ -216,7 +222,9 @@ export class MemoryFileSystem {
                     this.fail("ELOOP", syscall, path);
                 const target = node.target.split("/").filter(Boolean);
                 if (node.target.endsWith("/"))
-                    target.push(".");
+                    target.push("");
+                if (options.resizeCreate !== undefined && target.at(-1) === "" && pending[0] === "")
+                    target.pop();
                 pending.unshift(...target);
                 if (node.target.startsWith("/"))
                     stack.splice(1);
@@ -251,11 +259,12 @@ export class MemoryFileSystem {
     snapshot(node) {
         return {
             type: node.type,
+            preferredIoBlockSize: 4096,
             size: node.type === "file" ? node.data.byteLength
                 : node.type === "symlink" ? new TextEncoder().encode(node.target).byteLength : 0,
             mode: node.mode, ...(ownedStores.get(this)?.intact() ? { identityScope: this.identityScope } : {}),
             ino: node.ino, dev: 0, uid: 0, gid: 0,
-            nlink: node.type === "directory"
+            nlink: node.type === "directory" && node.nlink !== 0
                 ? 2 + [...node.entries.values()].filter((entry) => entry.type === "directory").length : node.nlink,
             atimeMs: node.atimeMs, mtimeMs: node.mtimeMs, ctimeMs: node.ctimeMs, birthtimeMs: node.birthtimeMs,
         };
@@ -650,7 +659,10 @@ export class MemoryFileSystem {
         this.integer(length, "truncate", path);
         const node = this.file(path, "truncate");
         this.permission(node, 2, "truncate", path);
-        const data = this.allocate(length, "truncate", path);
+        this.resizeNode(node, length, "truncate", path);
+    }
+    resizeNode(node, length, syscall, path) {
+        const data = this.allocate(length, syscall, path);
         try {
             data.data.set(node.data.subarray(0, length));
         }
@@ -661,12 +673,71 @@ export class MemoryFileSystem {
         this.replaceData(node, data);
         this.changed(node);
     }
-    async openReadFile(path, options = {}) {
+    async openResizeFile(path, options = {}) {
         options.signal?.throwIfAborted();
+        if (!stockRetainedResize(this))
+            throw new FsError("ENOTSUP", { syscall: "openResizeFile", path });
+        const location = this.resolve(path, "openResizeFile", { allowMissing: options.create === true, resizeCreate: options.create ?? false });
+        let mode = 0o666;
+        if (location.node) {
+            if (location.node.type !== "file")
+                this.fail("EISDIR", "openResizeFile", path);
+            this.permission(location.node, 2, "openResizeFile", path);
+        }
+        else {
+            this.permission(location.parent, 3, "openResizeFile", path);
+            mode = this.mode(options.mode, mode, "openResizeFile", path);
+        }
+        this.ledger.reserve(path.length * 2, 1, "openResizeFile", path);
+        let node;
+        try {
+            node = this.openWrite(path, {}, "openResizeFile", { location, mode, append: false });
+            node.references++;
+        }
+        catch (error) {
+            this.ledger.release(path.length * 2, 1);
+            throw error;
+        }
+        const snapshot = this.snapshot.bind(this);
+        const integer = this.integer.bind(this);
+        const resizeNode = this.resizeNode.bind(this);
+        const releaseReference = this.releaseReference.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 seekEnd(options = {}) { return BigInt(current(options.signal, "lseek").data.byteLength); },
+            async truncate(length, options = {}) {
+                const file = current(options.signal, "ftruncate");
+                integer(length, "ftruncate", path);
+                resizeNode(file, length, "ftruncate", path);
+            },
+            close() {
+                if (!closing) {
+                    const retained = node;
+                    node = undefined;
+                    closing = Promise.resolve().then(() => { if (retained)
+                        releaseReference(retained, path); });
+                }
+                return closing;
+            },
+        };
+    }
+    async openReadFile(path, options = {}) {
+        const signal = options.signal;
+        signal?.throwIfAborted();
+        const allowDirectory = options.allowDirectory === true;
+        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)
+            || Object.getOwnPropertyDescriptor(this, "root")?.value !== owner.root
+            || Object.getOwnPropertyDescriptor(this, "ledger")?.value !== owner.ledger)
             unsupported();
         for (const name of ["openReadFile", "readFile", "readStream", "stat", "lstat", "realpath", "access",
             "file", "resolve", "permission", "validatePath", "fail", "snapshot", "integer", "releaseReference", "releaseNode"]) {
@@ -675,10 +746,16 @@ export class MemoryFileSystem {
             if (!descriptor || !("value" in descriptor) || descriptor.value !== memoryImplementation[name]?.value)
                 unsupported();
         }
-        if (Object.getOwnPropertyDescriptor(this, "capabilities")?.value?.retainedRead !== true)
+        const retainedRead = Object.getOwnPropertyDescriptor(this, "capabilities")?.value?.retainedRead;
+        signal?.throwIfAborted();
+        if (retainedRead !== true)
             unsupported();
-        let node = this.file(path, "openReadFile");
+        const selected = allowDirectory ? this.resolve(path, "openReadFile").node : this.file(path, "openReadFile");
+        if (selected.type !== "file" && selected.type !== "directory")
+            this.fail("EISDIR", "openReadFile", path);
+        let node = selected;
         this.permission(node, 4, "openReadFile", path);
+        signal?.throwIfAborted();
         this.ledger.reserve(path.length * 2, 1, "openReadFile", path);
         node.references++;
         const snapshot = this.snapshot.bind(this);
@@ -695,6 +772,10 @@ export class MemoryFileSystem {
             async stat(options = {}) {
                 return snapshot(current(options.signal, "fstat"));
             },
+            async seekEnd(options = {}) {
+                const file = current(options.signal, "lseek");
+                return file.type === "directory" ? ext4HtreeEof64 : BigInt(file.data.byteLength);
+            },
             async read(position, maxBytes, options = {}) {
                 const file = current(options.signal, "read");
                 integer(position, "read", path);
@@ -702,6 +783,8 @@ export class MemoryFileSystem {
                 if (maxBytes === 0 || maxBytes > Number.MAX_SAFE_INTEGER - position) {
                     throw new FsError("EINVAL", { syscall: "read", path });
                 }
+                if (file.type === "directory")
+                    throw new FsError("EISDIR", { syscall: "read", path });
                 const bytes = file.data.slice(position, position + maxBytes);
                 file.atimeMs = Date.now();
                 return bytes;
@@ -800,6 +883,20 @@ function stockDescriptorWrite(filesystem) {
     }
     return true;
 }
+function stockRetainedResize(filesystem) {
+    if (!stockDescriptorWrite(filesystem))
+        return false;
+    const owner = ownedStores.get(filesystem);
+    if (!owner || Object.getOwnPropertyDescriptor(filesystem, "ledger")?.value !== owner.ledger)
+        return false;
+    for (const name of ["openResizeFile", "truncate", "resizeNode", "snapshot"]) {
+        const descriptor = Object.getOwnPropertyDescriptor(filesystem, name)
+            ?? Object.getOwnPropertyDescriptor(MemoryFileSystem.prototype, name);
+        if (!descriptor || !("value" in descriptor) || descriptor.value !== memoryImplementation[name]?.value)
+            return false;
+    }
+    return true;
+}
 export function createMemoryFileSystem(options = {}) {
     return new MemoryFileSystem(normalizeMemoryFileSystemLimits(options));
 }

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

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

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

@@ -1,9 +1,10 @@
 import { FsError, isFsError, toFsError } from "../../contracts/errors.js";
 import { readBytes } from "../../contracts/io.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
-import { openRetainedReadFile, readOnlyCapabilities, retainedReadCapabilities } from "../capabilities.js";
+import { openRetainedReadFile, openRetainedResizeFile, readOnlyCapabilities, retainedReadCapabilities, retainedResizeCapabilities } from "../capabilities.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { normalizePath, validatePath } from "../../contracts/virtual-path.js";
+import { pathNamespace } from "../path-namespace.js";
 import { compareIdentity } from "./identity.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "./comparison.js";
 const syntheticStat = Object.freeze({
@@ -20,10 +21,11 @@ function fail(code) {
     throw new FsError(code);
 }
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
+    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
+        ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
         ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
         ...(identityScope === undefined ? {} : { identityScope }),
         ...(ino === undefined ? {} : { ino }),
@@ -67,6 +69,10 @@ export class MountFileSystem {
             add(path, backend);
         }
         this.mounts = mounts.sort((left, right) => right.path.length - left.path.length);
+        const selectNamespace = this.select.bind(this);
+        Object.defineProperty(this, pathNamespace, {
+            value: Object.freeze({ select: (path) => selectNamespace(path).path }),
+        });
         registerEntryView(this, (path, options) => this.operation("compareEntry", path, options, async () => {
             const location = await this.resolve(path, options);
             if (location.synthetic)
@@ -85,7 +91,7 @@ export class MountFileSystem {
         const common = (capability) => {
             const optional = {
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
-                descriptorWriteStream: ["writeStream"],
+                descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"],
             };
             const values = mounts.map(({ backend }) => {
                 if (backend.capabilities.readOnly === true
@@ -104,7 +110,7 @@ export class MountFileSystem {
             "read", "stat", "readdir", "realpath", "access",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
-            "streamingAppend", "randomAccessWrite", "descriptorWriteStream", "symlinks", "hardlinks", "permissions", "timestamps",
+            "streamingAppend", "randomAccessWrite", "descriptorWriteStream", "retainedResize", "symlinks", "hardlinks", "permissions", "timestamps",
         ].map(capability => [capability, common(capability)]).filter(([, value]) => value !== undefined));
         this.capabilities = Object.freeze({
             get snapshotRmdir() { return mounts.some(({ backend }) => backend.capabilities.snapshotRmdir === true); },
@@ -122,14 +128,17 @@ export class MountFileSystem {
     }
     async capabilitiesFor(path, options = {}) {
         return this.operation("capabilitiesFor", path, options, async () => {
-            const location = await this.resolve(path, options, { allowMissing: true });
+            const location = await this.resolve(path, options, {
+                allowMissing: options.create ?? true,
+                ...(options.create === undefined ? {} : { resizeCreate: options.create }),
+            });
             const observed = await location.mount.backend.capabilitiesFor?.(location.local, options)
                 ?? location.mount.backend.capabilities;
             const declared = observed.descriptorWriteStream === true
                 && (typeof location.mount.backend.writeStream !== "function" || observed.readOnly === true || observed.streamingWrite === false)
                 ? { ...observed, descriptorWriteStream: false } : observed;
             const capabilities = location.synthetic ? { ...declared, retainedRead: false }
-                : retainedReadCapabilities(location.mount.backend, declared);
+                : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, declared));
             if (location.synthetic)
                 return readOnlyCapabilities(capabilities);
             if (this.mounts.length === 1 || capabilities.readOnly === true)
@@ -158,6 +167,27 @@ export class MountFileSystem {
             throw error ? this.error(error, "openReadFile", path, options) : error;
         }
     }
+    async openResizeFile(path, options = {}) {
+        try {
+            options.signal?.throwIfAborted();
+            const resolution = this.resolve(path, options, { allowMissing: options.create === true, resizeCreate: options.create ?? false });
+            const signal = options.signal;
+            const location = await (signal ? new Promise((resolve, reject) => {
+                const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+                signal.addEventListener("abort", abort, { once: true });
+                resolution.then(value => { signal.removeEventListener("abort", abort); resolve(value); }, error => { signal.removeEventListener("abort", abort); reject(error); });
+                if (signal.aborted)
+                    abort();
+            }) : resolution);
+            options.signal?.throwIfAborted();
+            if (location.synthetic)
+                fail("EROFS");
+            return await openRetainedResizeFile(location.mount.backend, location.local, options);
+        }
+        catch (error) {
+            throw error ? this.error(error, "openResizeFile", path, options) : error;
+        }
+    }
     error(error, syscall, path, options, dest) {
         if (options.signal?.aborted && error === options.signal.reason)
             return error;
@@ -210,24 +240,28 @@ export class MountFileSystem {
         const stack = [await this.lookup("/", options)];
         let boundary;
         let verification;
+        let creationVerification;
         const verified = async (location) => {
-            if (verification) {
-                const canonical = await verification.mount.backend.realpath(verification.path, options);
+            const inspection = !location.stat && settings.resizeCreate === true ? creationVerification : verification;
+            if (inspection) {
+                const canonical = await inspection.mount.backend.realpath(inspection.path, options);
                 validatePath(canonical);
                 if (!canonical.startsWith("/") || normalizePath(canonical) !== canonical)
                     fail("EIO");
-                if (verification.finalName !== undefined) {
+                if (inspection.finalName !== undefined) {
                     try {
-                        await verification.mount.backend.lstat(`${verification.path}/${verification.finalName}`, options);
+                        await inspection.mount.backend.lstat(`${inspection.path}/${inspection.finalName}`, options);
+                        if (!location.stat && settings.resizeCreate === true)
+                            fail("ENOTSUP");
                     }
                     catch (error) {
                         if (location.stat || toFsError(error).code !== "ENOENT")
                             throw error;
                     }
                 }
-                const expected = verification.finalName === undefined ? canonical
-                    : `${canonical === "/" ? "" : canonical}/${verification.finalName}`;
-                if (location.mount !== verification.mount || location.local !== expected)
+                const expected = inspection.finalName === undefined ? canonical
+                    : `${canonical === "/" ? "" : canonical}/${inspection.finalName}`;
+                if (location.mount !== inspection.mount || location.local !== expected)
                     fail("ENOTSUP");
             }
             return location;
@@ -239,8 +273,10 @@ export class MountFileSystem {
             const current = stack[stack.length - 1];
             if (current.stat?.type !== "directory")
                 fail("ENOTDIR");
+            if (component.trailing && pending.length === 0 && settings.resizeCreate !== undefined)
+                fail("EISDIR");
             if (!current.synthetic && !settings.createDirectories?.has(current.path)) {
-                const mode = current.mount.backend.capabilities.permissions === false ? 0 : 1;
+                const mode = settings.resizeCreate === undefined && current.mount.backend.capabilities.permissions === false ? 0 : 1;
                 await current.mount.backend.access(current.local, mode, options);
             }
             if (component.name === ".")
@@ -257,6 +293,8 @@ export class MountFileSystem {
             const nextPath = `${current.path === "/" ? "" : current.path}/${component.name}`;
             if (boundary && this.select(nextPath) !== boundary)
                 fail("EACCES");
+            if (settings.resizeCreate === true && pending.length === 1 && pending[0].trailing)
+                fail("EISDIR");
             let next = settings.createDirectories?.get(nextPath)
                 ?? await this.lookup(nextPath, options, current, settings.createDirectories?.has(current.path));
             if (!next.stat) {
@@ -299,6 +337,20 @@ export class MountFileSystem {
                 const readlink = this.optional(next, "readlink", "symlinks");
                 const target = await readlink.call(next.mount.backend, next.local, options);
                 const targetParts = this.components(target);
+                if (settings.resizeCreate !== undefined && targetParts.at(-1)?.trailing && pending[0]?.trailing)
+                    targetParts.pop();
+                if (settings.resizeCreate === true) {
+                    const remainder = [...targetParts, ...pending];
+                    const finalName = remainder.at(-1)?.name;
+                    if (finalName !== undefined && finalName !== "." && finalName !== "..") {
+                        const parent = target.startsWith("/") ? "" : next.local.slice(0, next.local.lastIndexOf("/"));
+                        creationVerification = {
+                            mount: next.mount,
+                            path: `${parent}/${remainder.slice(0, -1).map(part => part.name).join("/")}`,
+                            finalName,
+                        };
+                    }
+                }
                 if (target.startsWith("/")) {
                     const rootIndex = stack.findIndex((entry) => entry.path === next.mount.path);
                     if (rootIndex < 0)

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

@@ -1,5 +1,5 @@
 import type { ByteSource } from "../../contracts/io.js";
-import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 export interface OverlayFileSystemOptions {
     readonly upper: FileSystem;
     readonly lower: FileSystem;
@@ -18,8 +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>;
+    capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
+    openReadFile(path: string, options?: OpenReadFileOptions): Promise<import("../../contracts/filesystem.js").FileReadHandle>;
     private writable;
     private permission;
     private maybeStat;

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

@@ -8,10 +8,11 @@ import { compareIdentity } from "../mount/identity.js";
 import { compareEntries, registerEntryView } from "../mount/comparison.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
+    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, identityScope, ino, dev, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
+        ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
         ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
         ...(identityScope === undefined ? {} : { identityScope }),
         ...(ino === undefined ? {} : { ino }),
@@ -119,6 +120,7 @@ export class OverlayFileSystem {
             ...(effectiveAppend === undefined ? {} : { append: effectiveAppend }),
             atomicRename: false, atomicRenameNoReplace: false,
             descriptorWriteStream: false,
+            retainedResize: false,
             hardlinks: false,
             symlinks: writable && this.#upper.capabilities.symlinks === true
                 && typeof this.#upper.symlink === "function" && typeof this.#upper.readlink === "function"
@@ -167,8 +169,12 @@ export class OverlayFileSystem {
     openReadFile(path, options = {}) {
         return this.run(options, async () => {
             const entry = await this.required(path, options);
-            if (entry.stat.type !== "file")
-                fail("EISDIR", path);
+            if (entry.stat.type !== "file") {
+                const allowDirectory = options.allowDirectory === true;
+                options.signal?.throwIfAborted();
+                if (entry.stat.type !== "directory" || !allowDirectory)
+                    fail("EISDIR", path);
+            }
             this.permission(entry, 4);
             return openRetainedReadFile(entry.backend, entry.path, options);
         }, false);

package/dist/safe-fs/fs/path-namespace.d.ts

@@ -0,0 +1,4 @@
+import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
+export declare const pathNamespace: unique symbol;
+export declare function capturePathNamespace(filesystem: FileSystem, options: FsOptions): ((path: string) => string) | undefined;
+export declare function readOnlyPathNamespace(projection: unknown): object | undefined;

package/dist/safe-fs/fs/path-namespace.js

@@ -0,0 +1,63 @@
+import { FsError } from "../contracts/errors.js";
+import { normalizePath, validatePath } from "../contracts/virtual-path.js";
+export const pathNamespace = Symbol.for("@poe-code/safe-fs/path-namespace/v1");
+const captureNamespace = Symbol.for("@poe-code/safe-fs/capture-path-namespace/v1");
+export function capturePathNamespace(filesystem, options) {
+    options.signal?.throwIfAborted();
+    const projection = Reflect.get(filesystem, pathNamespace);
+    options.signal?.throwIfAborted();
+    if (projection === undefined)
+        return undefined;
+    return captureProjection(projection, options);
+}
+export function readOnlyPathNamespace(projection) {
+    if (projection === undefined)
+        return undefined;
+    const select = (path) => captureProjection(projection, {})(path);
+    Object.defineProperty(select, captureNamespace, {
+        value: Object.freeze((options) => captureProjection(projection, options)),
+    });
+    return Object.freeze({ select: Object.freeze(select) });
+}
+function captureProjection(projection, options) {
+    options.signal?.throwIfAborted();
+    if (projection === null || typeof projection !== "object")
+        throw new FsError("EIO");
+    const frozen = Object.isFrozen(projection);
+    options.signal?.throwIfAborted();
+    if (!frozen)
+        throw new FsError("EIO");
+    let select = Reflect.get(projection, "select");
+    options.signal?.throwIfAborted();
+    if (typeof select !== "function")
+        throw new FsError("EIO");
+    const capture = Reflect.get(select, captureNamespace);
+    options.signal?.throwIfAborted();
+    let receiver = projection;
+    if (capture !== undefined) {
+        if (typeof capture !== "function")
+            throw new FsError("EIO");
+        select = Reflect.apply(capture, select, [options]);
+        options.signal?.throwIfAborted();
+        if (typeof select !== "function")
+            throw new FsError("EIO");
+        receiver = undefined;
+    }
+    const selected = select;
+    return path => {
+        options.signal?.throwIfAborted();
+        const root = Reflect.apply(selected, receiver, [path]);
+        options.signal?.throwIfAborted();
+        if (typeof root !== "string" || !root.startsWith("/"))
+            throw new FsError("EIO", { path });
+        try {
+            validatePath(root);
+        }
+        catch (cause) {
+            throw new FsError("EIO", { path, cause });
+        }
+        if (normalizePath(root) !== root || root !== "/" && path !== root && !path.startsWith(`${root}/`))
+            throw new FsError("EIO", { path });
+        return root;
+    };
+}