@poe-platform/safe-fs 0.1.629 → 0.1.631

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

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, FileDescriptor, OpenFileOptions, OpenReadFileOptions, OpenResizeFileOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 import { type MemoryFileSystemOptions } from "./limits.js";
 export { defaultMemoryFileSystemLimits, type MemoryFileSystemLimits, type MemoryFileSystemOptions } from "./limits.js";
@@ -9,6 +9,7 @@ export declare class MemoryFileSystem implements FileSystem {
         readdir: true;
         realpath: true;
         access: true;
+        open: true;
         write: true;
         append: true;
         exclusiveCreate: true;
@@ -35,6 +36,7 @@ export declare class MemoryFileSystem implements FileSystem {
         atomicRename: true;
         atomicFileStaging: true;
         atomicFileMutation: true;
+        atomicEntryRemoval: true;
         atomicDirectoryMetadata: true;
         streamingRead: true;
         retainedRead: true;
@@ -46,6 +48,7 @@ export declare class MemoryFileSystem implements FileSystem {
     private nextInode;
     private readonly ledger;
     private readonly root;
+    private totalBytes;
     constructor(options?: MemoryFileSystemOptions);
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
@@ -55,6 +58,7 @@ export declare class MemoryFileSystem implements FileSystem {
     private releaseNode;
     private releaseReference;
     private replaceData;
+    private admitSize;
     private fail;
     private validatePath;
     private permission;
@@ -68,6 +72,7 @@ export declare class MemoryFileSystem implements FileSystem {
     private snapshot;
     private bytes;
     private allocate;
+    open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     private prepareWrite;
     private openWrite;
     private writeData;
@@ -80,6 +85,7 @@ export declare class MemoryFileSystem implements FileSystem {
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
@@ -89,6 +95,7 @@ export declare class MemoryFileSystem implements FileSystem {
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
+    unlink(path: string, options?: FsOptions): Promise<void>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;
     copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
     realpath(path: string, options?: FsOptions): Promise<string>;

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

@@ -3,11 +3,13 @@ import { assertCallbackAuthorityAllowed, compareEntries, registerEntryAuthority
 import { getOwnedS3Entry } from "../s3/registry.js";
 import { getOwnedWebDavEntry } from "../webdav/resource-id.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
+import { openFileDescriptor } from "../descriptor.js";
 import { resolveMissingTarget } from "./missing-target.js";
 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 preferredIoBlockSize = 64 * 1024;
 const ext4HtreeEof64 = (1n << 63n) - 1n;
 const ownedStats = new WeakMap();
 const ownedStores = new WeakMap();
@@ -55,7 +57,7 @@ const compareOwnedMemory = async (own, peer, options) => {
 export class MemoryFileSystem {
     capabilities = ((filesystem) => {
         return Object.freeze({
-            read: true, stat: true, readdir: true, realpath: true, access: true,
+            read: true, stat: true, readdir: true, realpath: true, access: true, open: true,
             write: true, append: true, exclusiveCreate: true, explicitDirectories: true, implicitDirectories: false,
             mkdir: true, recursiveMkdir: true, remove: true, removeDirectory: true, recursiveRemove: true,
             rename: true, atomicRenameNoReplace: true, copy: true, exclusiveCopy: true, readlink: true, truncate: true,
@@ -66,7 +68,7 @@ export class MemoryFileSystem {
             permissions: true,
             timestamps: true,
             atomicRename: true,
-            atomicFileStaging: true, atomicFileMutation: true,
+            atomicFileStaging: true, atomicFileMutation: true, atomicEntryRemoval: true,
             atomicDirectoryMetadata: true,
             streamingRead: true,
             retainedRead: true,
@@ -79,6 +81,7 @@ export class MemoryFileSystem {
     nextInode = 1;
     ledger;
     root;
+    totalBytes = 0;
     constructor(options = {}) {
         this.ledger = new MemoryLedger(normalizeMemoryFileSystemLimits(options));
         this.ledger.reserve(0, 1, "mkdir", "/");
@@ -129,7 +132,11 @@ export class MemoryFileSystem {
         this.ledger.reserve(bytes, 2, syscall, path);
         try {
             const node = create();
+            if (node.type === "file")
+                this.admitSize(undefined, node.data.byteLength, syscall, path);
             parent.entries.set(name, node);
+            if (node.type === "file")
+                this.totalBytes += node.data.byteLength;
             this.changed(parent);
             return node;
         }
@@ -142,8 +149,10 @@ export class MemoryFileSystem {
         if (node.nlink !== 0 || node.references !== 0)
             return;
         this.ledger.release(node.type === "symlink" ? node.target.length * 2 : 0, 1);
-        if (node.type === "file")
+        if (node.type === "file") {
+            this.totalBytes -= node.data.byteLength;
             node.allocation.release();
+        }
     }
     releaseReference(node, path) {
         node.references--;
@@ -152,10 +161,17 @@ export class MemoryFileSystem {
     }
     replaceData(node, allocation, length = allocation.data.byteLength) {
         const previous = node.allocation;
+        this.totalBytes += length - node.data.byteLength;
         node.data = allocation.data.subarray(0, length);
         node.allocation = allocation;
         previous.release();
     }
+    admitSize(node, length, syscall, path) {
+        this.ledger.fileSize(length, syscall, path);
+        if (length - (node?.data.byteLength ?? 0) > (this.ledger.limits.maxBytes ?? Number.MAX_SAFE_INTEGER) - this.totalBytes) {
+            this.fail("ENOSPC", syscall, path);
+        }
+    }
     fail(code, syscall, path, dest) {
         throw new FsError(code, { syscall, path, ...(dest === undefined ? {} : { dest }) });
     }
@@ -262,6 +278,7 @@ export class MemoryFileSystem {
     snapshot(node) {
         return {
             type: node.type,
+            ioBlockSize: preferredIoBlockSize,
             ...(Number.isSafeInteger(node.revision) ? { revision: node.revision } : {}),
             preferredIoBlockSize: 4096,
             size: node.type === "file" ? node.data.byteLength
@@ -295,6 +312,72 @@ export class MemoryFileSystem {
             throw new FsError("EFBIG", { syscall, path, cause });
         }
     }
+    open(path, options) {
+        return openFileDescriptor(path, options, {
+            positionedRead: true, positionedWrite: true, truncate: true, synchronization: "volatile", position: true,
+        }, async (admitted) => {
+            const location = this.resolve(path, "open", {
+                followFinal: admitted.creation !== "exclusive", allowMissing: admitted.creation !== "never",
+            });
+            let node = location.node;
+            if (node) {
+                if (admitted.creation === "exclusive")
+                    this.fail("EEXIST", "open", path);
+                if (node.type !== "file")
+                    this.fail("EISDIR", "open", path);
+                this.permission(node, admitted.access === "read" ? 4 : admitted.access === "write" ? 2 : 6, "open", path);
+            }
+            else {
+                this.permission(location.parent, 3, "open", path);
+            }
+            this.ledger.reserve(path.length * 2, 1, "open", path);
+            try {
+                node ??= this.openWrite(path, {}, "open", { location, mode: admitted.mode, append: false });
+                if (admitted.truncate)
+                    this.resizeNode(node, 0, "open", path);
+            }
+            catch (error) {
+                this.ledger.release(path.length * 2, 1);
+                throw error;
+            }
+            node.references++;
+            const resource = { node, position: 0 };
+            return {
+                resource,
+                getPosition: async (retained) => retained.position,
+                stat: async (retained) => this.snapshot(retained.node),
+                read: async (retained, buffer, position) => {
+                    const inode = retained.node;
+                    const start = position ?? retained.position;
+                    const count = Math.min(buffer.byteLength, Math.max(0, inode.data.byteLength - start));
+                    buffer.set(inode.data.subarray(start, start + count));
+                    if (position === null)
+                        retained.position += count;
+                    inode.atimeMs = Date.now();
+                    return count;
+                },
+                write: async (retained, buffer, position) => {
+                    const inode = retained.node;
+                    const start = admitted.append ? inode.data.byteLength : position ?? retained.position;
+                    const end = start + buffer.byteLength;
+                    this.writeAt(inode, buffer, start, "write", path);
+                    if (position === null)
+                        retained.position = end;
+                    return buffer.byteLength;
+                },
+                truncate: async (retained, length) => {
+                    const inode = retained.node;
+                    this.resizeNode(inode, length, "ftruncate", path);
+                },
+                sync: async () => { },
+                close: async (retained) => {
+                    const inode = retained.node;
+                    retained.node = undefined;
+                    this.releaseReference(inode, path);
+                },
+            };
+        });
+    }
     prepareWrite(path, options, syscall) {
         const flag = options.flag ?? "w";
         if (!["w", "wx", "a", "ax"].includes(flag))
@@ -329,7 +412,7 @@ export class MemoryFileSystem {
         const target = this.prepareWrite(path, options, syscall);
         const current = target.location.node;
         const length = (target.append ? current?.data.byteLength ?? 0 : 0) + data.byteLength;
-        this.ledger.fileSize(length, syscall, path);
+        this.admitSize(current, length, syscall, path);
         const growth = target.append && length > (current?.allocation.data.byteLength ?? 0) ? length : 0;
         this.ledger.check(data.byteLength + growth + (current ? 0 : target.location.name.length * 2), current ? 0 : 2, syscall, path);
         const copied = this.bytes(data, syscall, path);
@@ -373,6 +456,7 @@ export class MemoryFileSystem {
         const end = position + data.byteLength;
         this.ledger.fileSize(end, syscall, path);
         const length = Math.max(node.data.byteLength, end);
+        this.admitSize(node, length, syscall, path);
         let allocation = node.allocation;
         if (length > allocation.data.byteLength) {
             this.ledger.check(length, 0, syscall, path);
@@ -394,8 +478,10 @@ export class MemoryFileSystem {
         }
         if (allocation !== node.allocation)
             this.replaceData(node, allocation, length);
-        else
+        else {
+            this.totalBytes += length - node.data.byteLength;
             node.data = allocation.data.subarray(0, length);
+        }
         this.changed(node);
     }
     async readFile(path, options = {}) {
@@ -460,6 +546,8 @@ export class MemoryFileSystem {
                 this.fail("EINVAL", "createStagedFile", directoryPath);
         if (content.type === "file" && !(content.data instanceof Uint8Array))
             throw new TypeError("Staged files require Uint8Array data");
+        if (content.type === "file")
+            this.admitSize(undefined, content.data.byteLength, "createStagedFile", directoryPath);
         if (content.type === "symlink")
             this.validatePath(content.target, "createStagedFile");
         const retained = (location.name.length + name.length) * 2 + (content.type === "symlink" ? content.target.length * 2 : 0);
@@ -480,6 +568,8 @@ export class MemoryFileSystem {
                 file.mtimeMs = options.mtimeMs;
             directory.entries.set(name, file);
             location.parent.entries.set(location.name, directory);
+            if (file.type === "file")
+                this.totalBytes += file.data.byteLength;
         }
         catch (error) {
             allocation?.release();
@@ -566,6 +656,29 @@ export class MemoryFileSystem {
         this.writeData(path, data, { ...(options.mode === undefined ? {} : { mode: options.mode }), flag: options.append ? "a" : "w" }, "writeFileConditional");
         return Object.freeze(this.snapshot(location.parent.entries.get(location.name)));
     }
+    async removeEntryConditional(path, options) {
+        options.signal?.throwIfAborted();
+        const location = this.entry(path, "removeEntryConditional", true);
+        this.expectEntry(location.parent, options.parent, path, false);
+        this.expectEntry(location.node, options.expected, path);
+        const node = location.node;
+        if (this.terminalDot(path))
+            this.fail("EINVAL", "removeEntryConditional", path);
+        if (node === this.root)
+            this.fail("EBUSY", "removeEntryConditional", path);
+        if (node.type !== "file" && node.type !== "symlink" && node.type !== "directory")
+            this.fail("EINVAL", "removeEntryConditional", path);
+        this.permission(location.parent, 3, "removeEntryConditional", path);
+        if (node.type === "directory" && node.entries.size > 0)
+            this.fail("ENOTEMPTY", "removeEntryConditional", path);
+        location.parent.entries.delete(location.name);
+        this.ledger.release(location.name.length * 2, 1);
+        node.nlink--;
+        node.ctimeMs = Date.now();
+        node.revision = Math.min(Number.MAX_SAFE_INTEGER + 1, node.revision + 1);
+        this.releaseNode(node);
+        this.changed(location.parent);
+    }
     async removeFileConditional(path, options) {
         options.signal?.throwIfAborted();
         const location = this.entry(path, "removeFileConditional", true);
@@ -692,6 +805,10 @@ export class MemoryFileSystem {
         }
         this.changed(location.parent);
     }
+    unlink(path, options = {}) {
+        // Do not allow an untyped recursive option to widen final-entry removal.
+        return this.rm(path, { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+    }
     async rename(source, destination, options = {}) {
         options.signal?.throwIfAborted();
         try {
@@ -762,7 +879,6 @@ export class MemoryFileSystem {
                 this.fail("EINVAL", "copyFile", source, destination);
             const node = this.writeData(destination, origin.data, { mode: origin.mode & 0o7777, flag: options.exclusive ? "wx" : "w" }, "copyFile");
             node.mode = origin.mode;
-            this.changed(node);
             origin.atimeMs = Date.now();
         }
         catch (error) {
@@ -847,6 +963,7 @@ export class MemoryFileSystem {
         this.resizeNode(node, length, "truncate", path);
     }
     resizeNode(node, length, syscall, path) {
+        this.admitSize(node, length, syscall, path);
         const data = this.allocate(length, syscall, path);
         try {
             data.data.set(node.data.subarray(0, length));
@@ -987,7 +1104,7 @@ export class MemoryFileSystem {
     async *readStream(path, options = {}) {
         options.signal?.throwIfAborted();
         const start = options.start ?? 0;
-        const chunkSize = options.chunkSize ?? 64 * 1024;
+        const chunkSize = options.chunkSize ?? preferredIoBlockSize;
         this.integer(start, "readStream", path);
         this.integer(chunkSize, "readStream", path);
         if (chunkSize === 0)
@@ -1060,7 +1177,7 @@ function stockDescriptorWrite(filesystem) {
         return false;
     for (const name of ["writeStream", "writeFile", "appendFile", "access", "stat", "lstat", "realpath",
         "openWrite", "prepareWrite", "writeData", "addNode", "replaceData", "releaseReference", "releaseNode",
-        "resolve", "permission", "validatePath", "mode", "bytes", "allocate", "changed", "metadata", "integer", "writeAt", "fail"]) {
+        "resolve", "permission", "validatePath", "mode", "bytes", "allocate", "admitSize", "changed", "metadata", "integer", "writeAt", "fail"]) {
         const descriptor = Object.getOwnPropertyDescriptor(filesystem, name)
             ?? Object.getOwnPropertyDescriptor(MemoryFileSystem.prototype, name);
         if (!descriptor || !("value" in descriptor) || descriptor.value !== memoryImplementation[name]?.value)

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

@@ -1,4 +1,5 @@
 export interface MemoryFileSystemLimits {
+    readonly maxBytes?: number;
     readonly maxFileBytes: number;
     readonly maxRetainedBytes: number;
     readonly maxMetadataUnits: number;

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

@@ -6,8 +6,14 @@ export const defaultMemoryFileSystemLimits = Object.freeze({
 });
 export function normalizeMemoryFileSystemLimits(options) {
     const keys = ["maxFileBytes", "maxRetainedBytes", "maxMetadataUnits"];
-    const record = readConfigRecord(options, "memory option", keys);
+    const record = readConfigRecord(options, "memory option", [...keys, "maxBytes"]);
     const limits = { ...defaultMemoryFileSystemLimits };
+    if (Object.hasOwn(record, "maxBytes") && record.maxBytes !== undefined) {
+        if (typeof record.maxBytes !== "number" || !Number.isSafeInteger(record.maxBytes) || record.maxBytes < 0) {
+            throw new RangeError("maxBytes must be a nonnegative safe integer");
+        }
+        limits.maxBytes = record.maxBytes;
+    }
     for (const key of keys) {
         const value = Object.hasOwn(record, key) ? record[key] : limits[key];
         if (typeof value !== "number" || !Number.isSafeInteger(value) || value < (key === "maxMetadataUnits" ? 1 : 0)) {

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

@@ -1,5 +1,6 @@
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
+import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 export interface MountFileSystemOptions {
     readonly root: FileSystem;
     readonly mounts?: Readonly<Record<string, FileSystem>>;
@@ -23,6 +24,7 @@ export declare class MountFileSystem implements FileSystem {
     private entryPath;
     private optional;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
@@ -30,9 +32,11 @@ export declare class MountFileSystem implements FileSystem {
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;
+    unlink(path: string, options?: FsOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
     private localStaging;
     writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     createStagedFile(path: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;

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

@@ -4,6 +4,7 @@ import { finishCleanup } from "../../contracts/cleanup.js";
 import { requireOwnedMutation, ownedMutationCapabilities, openRetainedReadFile, openRetainedResizeFile, readOnlyCapabilities, retainedReadCapabilities, retainedResizeCapabilities } from "../capabilities.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { normalizePath, validatePath } from "../../contracts/virtual-path.js";
+import { forwardFileDescriptor, openFileDescriptor } from "../descriptor.js";
 import { pathNamespace } from "../path-namespace.js";
 import { compareIdentity } from "./identity.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "./comparison.js";
@@ -21,16 +22,19 @@ function fail(code) {
     throw new FsError(code);
 }
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, ino, dev, nlink, uid, gid } = stat;
+    const { type, size, allocatedBytes, ioBlockSize, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, ino, dev, rdevMajor, rdevMinor, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
         ...(revision === undefined ? {} : { revision }),
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
+        ...(ioBlockSize === undefined ? {} : { ioBlockSize }),
         ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
         ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
         ...(identityScope === undefined ? {} : { identityScope }),
         ...(ino === undefined ? {} : { ino }),
         ...(dev === undefined ? {} : { dev }),
+        ...(rdevMajor === undefined ? {} : { rdevMajor }),
+        ...(rdevMinor === undefined ? {} : { rdevMinor }),
         ...(nlink === undefined ? {} : { nlink }),
         ...(uid === undefined ? {} : { uid }),
         ...(gid === undefined ? {} : { gid }),
@@ -91,13 +95,14 @@ export class MountFileSystem {
             : mounts.every(({ backend }) => backend.capabilities.append === false) ? false : undefined;
         const common = (capability) => {
             const optional = {
-                atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
+                open: ["open"],
+                atomicEntryRemoval: ["removeEntryConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
                 descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
             };
             const values = mounts.map(({ backend }) => {
                 if (backend.capabilities.readOnly === true
-                    && !["read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories"].includes(capability))
+                    && !["open", "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories"].includes(capability))
                     return false;
                 const declared = backend.capabilities[capability];
                 if (capability === "descriptorWriteStream" && backend.capabilities.streamingWrite === false)
@@ -109,7 +114,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
-            "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access",
+            "atomicEntryRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
             "streamingAppend", "randomAccessWrite", "descriptorWriteStream", "retainedResize", "atomicResize", "symlinks", "hardlinks", "permissions", "timestamps",
@@ -141,8 +146,9 @@ export class MountFileSystem {
                 ? { ...observed, descriptorWriteStream: false } : observed;
             const resize = declared.atomicResize === true && (typeof location.mount.backend.resizeFile !== "function" || declared.readOnly === true)
                 ? { ...declared, atomicResize: false } : declared;
-            const capabilities = location.synthetic ? { ...resize, retainedRead: false }
-                : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, resize));
+            const withOpen = { ...resize, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
+                : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)
                 return readOnlyCapabilities(capabilities);
             if (this.mounts.length === 1 || capabilities.readOnly === true)
@@ -413,6 +419,38 @@ export class MountFileSystem {
             return location.mount.backend.readFile(location.local, options);
         });
     }
+    open(path, options) {
+        return openFileDescriptor(globalPath(path), options, {
+            positionedRead: true, positionedWrite: true, truncate: true, synchronization: "storage",
+        }, async (admitted) => {
+            try {
+                const location = await this.resolve(path, admitted, {
+                    allowMissing: admitted.creation !== "never", followFinal: admitted.creation !== "exclusive",
+                });
+                if (location.synthetic)
+                    fail("EISDIR");
+                if (admitted.access !== "read" || admitted.creation !== "never" || admitted.truncate || admitted.append)
+                    this.mutable(location);
+                const backend = location.mount.backend;
+                const capabilities = await backend.capabilitiesFor?.(location.local, admitted) ?? backend.capabilities;
+                if (!backend.open || capabilities.open === false)
+                    fail("ENOTSUP");
+                admitted.signal?.throwIfAborted();
+                const descriptor = await backend.open(location.local, admitted);
+                try {
+                    return forwardFileDescriptor(descriptor, (syscall, forwarded, action) => this.operation(syscall, path, forwarded, action), descriptor.capabilities, snapshotStat);
+                }
+                catch (error) {
+                    await finishCleanup(() => descriptor.close(), true);
+                    throw error;
+                }
+            }
+            catch (error) {
+                admitted.signal?.throwIfAborted();
+                throw this.error(error, "open", path, admitted);
+            }
+        });
+    }
     writeFile(path, data, options = {}) {
         return this.operation("writeFile", path, options, async () => {
             const location = await this.resolve(path, options, { allowMissing: true, followFinal: !options.flag?.endsWith("x") });
@@ -499,6 +537,18 @@ export class MountFileSystem {
             await backend.rmdir(location.local, options);
         });
     }
+    unlink(path, options = {}) {
+        return this.operation("unlink", path, options, async () => {
+            const location = await this.resolve(path, options, { followFinal: false, entry: true });
+            this.mutable(location);
+            this.entryPath(path);
+            const backend = location.mount.backend;
+            if (!backend.unlink)
+                fail("ENOTSUP");
+            options.signal?.throwIfAborted();
+            await backend.unlink(location.local, options);
+        });
+    }
     rm(path, options = {}) {
         return this.operation("rm", path, options, async () => {
             let location;
@@ -544,6 +594,19 @@ export class MountFileSystem {
             return snapshotStat(await backend.writeFileConditional(location.local, data, options));
         }, undefined, true);
     }
+    removeEntryConditional(path, options) {
+        return this.operation("removeEntryConditional", path, options, async () => {
+            const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true });
+            if (this.protected(location.path))
+                fail("EBUSY");
+            this.mutable(location);
+            const backend = location.mount.backend;
+            await requireOwnedMutation(backend, location.local, "atomicEntryRemoval", options);
+            if (!backend.removeEntryConditional)
+                fail("ENOTSUP");
+            await backend.removeEntryConditional(location.local, options);
+        });
+    }
     removeFileConditional(path, options) {
         return this.operation("removeFileConditional", path, options, async () => {
             const location = await this.resolve(path, options, { followFinal: false, entry: true, allowMissing: true });

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

@@ -1,4 +1,5 @@
 import type { ByteSource } from "../../contracts/io.js";
+import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.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;
@@ -17,6 +18,7 @@ export declare class OverlayFileSystem implements FileSystem {
     private readonly linkOrigins;
     private queue;
     constructor(options: OverlayFileSystemOptions);
+    open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     private run;
     capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
     openReadFile(path: string, options?: OpenReadFileOptions): Promise<import("../../contracts/filesystem.js").FileReadHandle>;

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

@@ -8,16 +8,19 @@ 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, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, ino, dev, nlink, uid, gid } = stat;
+    const { type, size, allocatedBytes, ioBlockSize, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, ino, dev, rdevMajor, rdevMinor, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
+        ...(ioBlockSize === undefined ? {} : { ioBlockSize }),
         ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
         ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
         ...(revision === undefined ? {} : { revision }),
         ...(identityScope === undefined ? {} : { identityScope }),
         ...(ino === undefined ? {} : { ino }),
         ...(dev === undefined ? {} : { dev }),
+        ...(rdevMajor === undefined ? {} : { rdevMajor }),
+        ...(rdevMinor === undefined ? {} : { rdevMinor }),
         ...(nlink === undefined ? {} : { nlink }),
         ...(uid === undefined ? {} : { uid }),
         ...(gid === undefined ? {} : { gid }),
@@ -114,6 +117,7 @@ export class OverlayFileSystem {
         ].filter(([, value]) => value !== undefined));
         this.capabilities = Object.freeze({
             ...semantics,
+            open: false,
             atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
             implicitDirectories: false,
             readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
@@ -135,6 +139,10 @@ export class OverlayFileSystem {
         });
         Object.defineProperty(this, "capabilities", { writable: false, configurable: false });
     }
+    async open(path, options) {
+        options.signal?.throwIfAborted();
+        throw new FsError("ENOTSUP", { syscall: "open", path });
+    }
     async run(options, operation, cleanup = true) {
         options.signal?.throwIfAborted();
         const previous = this.queue;

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

@@ -183,6 +183,10 @@ export function withFileSystemQuota(fs, options) {
             throw new FileSystemQuotaError(options.maxBytes);
     };
     const mutations = {
+        async open(path, openOptions) {
+            openOptions.signal?.throwIfAborted();
+            throw new FsError("ENOTSUP", { syscall: "open", path });
+        },
         openResizeFile(path, resizeOptions = {}) {
             return mutate(async () => {
                 let retained;
@@ -316,7 +320,7 @@ export function withFileSystemQuota(fs, options) {
     // capabilities and methods without violating invariants on own properties.
     return new Proxy(Object.create(fs), {
         get(_target, property) {
-            if (property === "writeFileConditional" || property === "removeFileConditional" || property === "resizeFile" || property === "canonicalizeMissingTarget" || property === "createStagedFile" || property === "publishStagedFile" || property === "removeStagedFile" || property === "prepareDirectory")
+            if (property === "removeEntryConditional" || property === "unlink" || property === "writeFileConditional" || property === "removeFileConditional" || property === "resizeFile" || property === "canonicalizeMissingTarget" || property === "createStagedFile" || property === "publishStagedFile" || property === "removeStagedFile" || property === "prepareDirectory")
                 return undefined;
             if (property === "capabilities")
                 return quotaCapabilities(retainedResizeCapabilities(fs, retainedReadCapabilities(fs)));

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

@@ -1,10 +1,12 @@
 import type { ByteSource } from "../../contracts/io.js";
 import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileResizeHandle, FileStat, OpenReadFileOptions, OpenResizeFileOptions, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
 export declare class ReadOnlyFileSystem implements FileSystem {
     #private;
     constructor(filesystem: FileSystem);
     get capabilities(): FileSystemCapabilities;
     capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
+    open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     openReadFile(path: string, options?: OpenReadFileOptions): Promise<import("../../contracts/filesystem.js").FileReadHandle>;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;