@poe-platform/safe-fs 0.1.629 → 0.1.631

package/dist/safe-fs/bridge/stats.js

@@ -19,7 +19,7 @@ export function bridgeStats(stat) {
         gid: stat.gid ?? 0,
         rdev: 0,
         size: stat.size,
-        blksize: stat.preferredIoBlockSize ?? 4096,
+        blksize: stat.ioBlockSize ?? stat.preferredIoBlockSize ?? 4096,
         blocks: Math.ceil(stat.size / 512),
         atimeMs: stat.atimeMs,
         mtimeMs: stat.mtimeMs,

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

@@ -0,0 +1,31 @@
+import type { FileStat, FsOptions } from "./filesystem.js";
+export interface OpenFileOptions extends FsOptions {
+    readonly access: "read" | "write" | "readwrite";
+    readonly creation?: "never" | "ifMissing" | "exclusive";
+    readonly truncate?: boolean;
+    readonly append?: boolean;
+    readonly mode?: number;
+    readonly synchronization?: "data" | "all";
+}
+export interface FileDescriptorCapabilities {
+    readonly position?: boolean;
+    readonly readObservation?: boolean;
+    readonly openTruncate?: boolean;
+    readonly positionedRead: boolean;
+    readonly positionedWrite: boolean;
+    readonly positionedAppendWrite?: boolean;
+    readonly delegateZeroLengthWrite?: boolean;
+    readonly truncate: boolean;
+    readonly synchronization: "none" | "volatile" | "storage";
+}
+export interface FileDescriptor {
+    readonly capabilities: FileDescriptorCapabilities;
+    getPosition?(options?: FsOptions): Promise<number>;
+    probeRead?(options?: FsOptions): Promise<"ready" | "blocked" | "unknown">;
+    stat(options?: FsOptions): Promise<FileStat>;
+    read(buffer: Uint8Array, position: number | null, options?: FsOptions): Promise<number>;
+    write(buffer: Uint8Array, position: number | null, options?: FsOptions): Promise<number>;
+    truncate(length: number, options?: FsOptions): Promise<void>;
+    sync(dataOnly: boolean, options?: FsOptions): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/safe-fs/contracts/descriptor.js

@@ -0,0 +1 @@
+export {};

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

@@ -27,7 +27,7 @@ declare const descriptions: {
     readonly EPERM: "operation not permitted";
     readonly EPIPE: "broken pipe";
     readonly EROFS: "read-only file system";
-    readonly ESPIPE: "invalid seek";
+    readonly ESPIPE: "illegal seek";
     readonly ETIMEDOUT: "operation timed out";
     readonly EXDEV: "cross-device link not permitted";
 };

package/dist/safe-fs/contracts/errors.js

@@ -26,7 +26,7 @@ const descriptions = {
     EPERM: "operation not permitted",
     EPIPE: "broken pipe",
     EROFS: "read-only file system",
-    ESPIPE: "invalid seek",
+    ESPIPE: "illegal seek",
     ETIMEDOUT: "operation timed out",
     EXDEV: "cross-device link not permitted",
 };

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

@@ -1,10 +1,13 @@
 import type { ByteSource } from "./io.js";
+import type { FileDescriptor, OpenFileOptions } from "./descriptor.js";
+export type { FileDescriptor, FileDescriptorCapabilities, OpenFileOptions } from "./descriptor.js";
 export type FileType = "file" | "directory" | "symlink" | "character";
 export type EntryComparison = "same" | "distinct" | "unknown";
 export interface FileStat {
     readonly type: FileType;
     readonly size: number;
     readonly allocatedBytes?: number;
+    readonly ioBlockSize?: number;
     readonly preferredIoBlockSize?: number;
     readonly mode: number;
     readonly mtimeMs: number;
@@ -15,6 +18,8 @@ export interface FileStat {
     readonly identityScope?: object | symbol;
     readonly ino?: number;
     readonly dev?: number;
+    readonly rdevMajor?: number;
+    readonly rdevMinor?: number;
     readonly nlink?: number;
     readonly uid?: number;
     readonly gid?: number;
@@ -24,6 +29,7 @@ export interface DirectoryEntry {
     readonly type: FileType;
 }
 export interface FileSystemCapabilities {
+    readonly open?: boolean;
     readonly readOnly?: boolean;
     readonly read?: boolean;
     readonly stat?: boolean;
@@ -47,6 +53,7 @@ export interface FileSystemCapabilities {
     readonly truncate?: boolean;
     readonly streamingAppend?: boolean;
     readonly randomAccessWrite?: boolean;
+    readonly independentWriteStreams?: boolean;
     readonly symlinks?: boolean;
     readonly hardlinks?: boolean;
     readonly permissions?: boolean;
@@ -54,6 +61,7 @@ export interface FileSystemCapabilities {
     readonly atomicRename?: boolean;
     readonly atomicFileStaging?: boolean;
     readonly atomicFileMutation?: boolean;
+    readonly atomicEntryRemoval?: boolean;
     readonly atomicDirectoryMetadata?: boolean;
     readonly atomicRenameNoReplace?: boolean;
     readonly snapshotRmdir?: boolean;
@@ -151,10 +159,11 @@ export interface ConditionalWriteFileOptions extends FsOptions {
     readonly append?: boolean;
     readonly mode?: number;
 }
-export interface ConditionalRemoveFileOptions extends FsOptions {
+export interface ConditionalRemoveEntryOptions extends FsOptions {
     readonly parent: FileStat;
     readonly expected: FileStat;
 }
+export type ConditionalRemoveFileOptions = ConditionalRemoveEntryOptions;
 export interface FileStagingEntry {
     readonly path: string;
     readonly stat: FileStat;
@@ -190,8 +199,10 @@ export interface PrepareDirectoryOptions extends FsOptions {
 }
 export interface FileSystem {
     writeFileConditional?(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeEntryConditional?(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     removeFileConditional?(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     readonly capabilities: FileSystemCapabilities;
+    open?(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     prepareDirectory?(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     createStagedFile?(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile?(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
@@ -211,6 +222,8 @@ export interface FileSystem {
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
+    /** Atomic final-entry removal; every directory is refused, including raced replacements. */
+    unlink?(path: string, options?: FsOptions): Promise<void>;
     rmdir?(path: string, options?: FsOptions): Promise<void>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;
     copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;

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

@@ -1,6 +1,8 @@
 export * from "./contracts/errors.js";
 export * from "./contracts/filesystem.js";
 export * from "./contracts/io.js";
+export { openFileDescriptor } from "./fs/descriptor.js";
+export type { DescriptorBackend, DescriptorOpenOptions } from "./fs/descriptor.js";
 export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./contracts/virtual-path.js";
 export { basename, dirname, extname, isAbsolutePath, joinPath, posixPath } from "./contracts/portable-path.js";
 export * from "./fs/memory/index.js";
@@ -13,6 +15,7 @@ export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export type { RetainedFileSystemCleanupView, RetainedFileSystemCleanupOptions } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
+export * from "./python/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits } from "./xml.js";

package/dist/safe-fs/core.js

@@ -1,6 +1,7 @@
 export * from "./contracts/errors.js";
 export * from "./contracts/filesystem.js";
 export * from "./contracts/io.js";
+export { openFileDescriptor } from "./fs/descriptor.js";
 export { assertPathWithin, isPathWithin, normalizePath, relativePath, resolvePath, validatePath } from "./contracts/virtual-path.js";
 export { basename, dirname, extname, isAbsolutePath, joinPath, posixPath } from "./contracts/portable-path.js";
 export * from "./fs/memory/index.js";
@@ -12,5 +13,6 @@ export * from "./fs/quota/index.js";
 export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
+export * from "./python/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";

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

@@ -7,4 +7,4 @@ export declare function openRetainedResizeFile(filesystem: FileSystem, path: str
 export declare function readOnlyCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function quotaCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
 export declare function ownedMutationCapabilities(filesystem: FileSystem, capabilities?: FileSystemCapabilities): FileSystemCapabilities;
-export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "atomicFileMutation" | "atomicFileStaging" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;
+export declare function requireOwnedMutation(filesystem: FileSystem, path: string, capability: "atomicEntryRemoval" | "atomicFileMutation" | "atomicFileStaging" | "atomicDirectoryMetadata", options: FsOptions, create?: boolean): Promise<void>;

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

@@ -101,14 +101,14 @@ export async function openRetainedResizeFile(filesystem, path, options) {
 export function readOnlyCapabilities(capabilities) {
     const inspection = Object.fromEntries([
         "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories",
-        "symlinks", "streamingRead", "retainedRead",
+        "symlinks", "streamingRead", "open", "retainedRead",
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
         ...inspection, readOnly: true, write: false, append: false, exclusiveCreate: false,
         mkdir: false, recursiveMkdir: false, remove: false, removeDirectory: false, recursiveRemove: false,
         rename: false, copy: false, exclusiveCopy: false, truncate: false, streamingAppend: false,
         randomAccessWrite: false, hardlinks: false, permissions: false, timestamps: false,
-        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
+        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
         atomicRename: false, atomicRenameNoReplace: false, streamingWrite: false,
     });
 }
@@ -116,13 +116,15 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
+    return Object.freeze({ ...rest, open: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
 }
 export function ownedMutationCapabilities(filesystem, capabilities = filesystem.capabilities) {
     const unavailable = {};
+    if (capabilities.atomicEntryRemoval === true && (capabilities.readOnly === true || typeof filesystem.removeEntryConditional !== "function"))
+        unavailable.atomicEntryRemoval = false;
     if (capabilities.atomicFileMutation === true && (capabilities.readOnly === true || typeof filesystem.writeFileConditional !== "function" || typeof filesystem.removeFileConditional !== "function"))
         unavailable.atomicFileMutation = false;
     if (capabilities.atomicFileStaging === true && (capabilities.readOnly === true

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

@@ -0,0 +1,21 @@
+import type { FileDescriptor, FileDescriptorCapabilities, FileStat, FsOptions, OpenFileOptions } from "../contracts/filesystem.js";
+export interface DescriptorOpenOptions extends OpenFileOptions {
+    readonly creation: "never" | "ifMissing" | "exclusive";
+    readonly truncate: boolean;
+    readonly append: boolean;
+    readonly mode: number;
+}
+export interface DescriptorBackend<Resource> {
+    readonly resource: Resource;
+    readonly capabilities?: FileDescriptorCapabilities;
+    getPosition?(resource: Resource, options: FsOptions): Promise<number>;
+    probeRead?(resource: Resource, options: FsOptions): Promise<"ready" | "blocked" | "unknown">;
+    stat(resource: Resource, options: FsOptions): Promise<FileStat>;
+    read(resource: Resource, buffer: Uint8Array, position: number | null, options: FsOptions): Promise<number>;
+    write(resource: Resource, buffer: Uint8Array, position: number | null, options: FsOptions): Promise<number>;
+    truncate(resource: Resource, length: number, options: FsOptions): Promise<void>;
+    sync(resource: Resource, dataOnly: boolean, options: FsOptions): Promise<void>;
+    close(resource: Resource): Promise<void>;
+}
+export declare function forwardFileDescriptor(descriptor: FileDescriptor, operation: <Result>(syscall: string, options: FsOptions, action: () => Promise<Result>) => Promise<Result>, capabilities?: FileDescriptorCapabilities, snapshot?: (stat: FileStat) => FileStat): DescriptorBackend<FileDescriptor>;
+export declare function openFileDescriptor<Resource>(path: string, options: OpenFileOptions, capabilities: FileDescriptorCapabilities, acquire: (options: DescriptorOpenOptions) => Promise<DescriptorBackend<Resource>>): Promise<FileDescriptor>;

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

@@ -0,0 +1,244 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+function admitCapabilities(path, options, capabilities) {
+    if (![capabilities.positionedRead, capabilities.positionedWrite, capabilities.truncate].every(value => typeof value === "boolean")
+        || capabilities.position !== undefined && typeof capabilities.position !== "boolean"
+        || capabilities.readObservation !== undefined && typeof capabilities.readObservation !== "boolean"
+        || capabilities.openTruncate !== undefined && typeof capabilities.openTruncate !== "boolean"
+        || capabilities.positionedAppendWrite !== undefined && typeof capabilities.positionedAppendWrite !== "boolean"
+        || capabilities.delegateZeroLengthWrite !== undefined && typeof capabilities.delegateZeroLengthWrite !== "boolean"
+        || !["none", "volatile", "storage"].includes(capabilities.synchronization))
+        throw new FsError("EINVAL", { syscall: "open", path });
+    if (options.truncate && !(capabilities.openTruncate ?? capabilities.truncate) || options.synchronization !== undefined && capabilities.synchronization === "none") {
+        throw new FsError("ENOTSUP", { syscall: "open", path });
+    }
+}
+export function forwardFileDescriptor(descriptor, operation, capabilities, snapshot = stat => ({ ...stat })) {
+    const retainedCapabilities = Object.freeze({ ...descriptor.capabilities });
+    const selected = Object.freeze({ ...(capabilities ?? retainedCapabilities) });
+    const getPosition = selected.position === true && retainedCapabilities.position === true ? descriptor.getPosition : undefined;
+    if (selected.position === true && typeof getPosition !== "function")
+        throw new FsError("ENOTSUP", { syscall: "getPosition" });
+    const probeRead = selected.readObservation === true && retainedCapabilities.readObservation === true ? descriptor.probeRead : undefined;
+    if (selected.readObservation === true && typeof probeRead !== "function")
+        throw new FsError("ENOTSUP", { syscall: "probeRead" });
+    return {
+        resource: descriptor, capabilities: selected,
+        ...(getPosition === undefined ? {} : {
+            getPosition: (retained, options) => operation("getPosition", options, () => getPosition.call(retained, options)),
+        }),
+        ...(probeRead === undefined ? {} : {
+            probeRead: (retained, options) => operation("probeRead", options, () => probeRead.call(retained, options)),
+        }),
+        stat: (retained, options) => operation("fstat", options, async () => snapshot(await retained.stat(options))),
+        read: (retained, buffer, position, options) => operation("read", options, () => retained.read(buffer, position, options)),
+        write: (retained, buffer, position, options) => operation("write", options, () => retained.write(buffer, position, options)),
+        truncate: (retained, length, options) => operation("ftruncate", options, () => retained.truncate(length, options)),
+        sync: (retained, dataOnly, options) => operation(dataOnly ? "fdatasync" : "fsync", options, () => retained.sync(dataOnly, options)),
+        close: retained => operation("close", {}, () => retained.close()),
+    };
+}
+function integer(value, syscall, path) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new FsError("EINVAL", { syscall, path });
+}
+class ManagedFileDescriptor {
+    capabilities;
+    #path;
+    #access;
+    #append;
+    #getPosition;
+    #probeRead;
+    #backend;
+    #pending = Promise.resolve();
+    #closing;
+    constructor(path, options, capabilities, backend) {
+        this.#path = path;
+        this.#access = options.access;
+        this.#append = options.append;
+        const getPosition = capabilities.position === true ? backend.getPosition : undefined;
+        if (capabilities.position === true && typeof getPosition !== "function")
+            throw new FsError("ENOTSUP", { syscall: "getPosition", path });
+        this.#getPosition = getPosition?.bind(backend);
+        const probeRead = capabilities.readObservation === true ? backend.probeRead : undefined;
+        if (capabilities.readObservation === true && typeof probeRead !== "function")
+            throw new FsError("ENOTSUP", { syscall: "probeRead", path });
+        this.#probeRead = probeRead?.bind(backend);
+        this.#backend = backend;
+        const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && options.access !== "read";
+        this.capabilities = Object.freeze({
+            ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
+            ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
+            ...(capabilities.openTruncate === undefined ? {} : { openTruncate: capabilities.openTruncate }),
+            positionedRead: capabilities.positionedRead && options.access !== "write",
+            positionedWrite: capabilities.positionedWrite && options.access !== "read" && (!options.append || positionedAppendWrite),
+            ...(capabilities.positionedAppendWrite === undefined ? {} : { positionedAppendWrite }),
+            ...(capabilities.delegateZeroLengthWrite === undefined ? {} : { delegateZeroLengthWrite: capabilities.delegateZeroLengthWrite && options.access !== "read" }),
+            truncate: capabilities.truncate && options.access !== "read",
+            synchronization: capabilities.synchronization,
+        });
+    }
+    #run(syscall, options, action) {
+        const signal = options.signal;
+        try {
+            signal?.throwIfAborted();
+            if (this.#closing || !this.#backend)
+                throw new FsError("EBADF", { syscall, path: this.#path });
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const forwarded = signal === undefined ? {} : { signal };
+        const operation = this.#pending.then(async () => {
+            signal?.throwIfAborted();
+            try {
+                const result = await action(this.#backend, forwarded);
+                signal?.throwIfAborted();
+                return result;
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                throw error;
+            }
+        });
+        this.#pending = operation.then(() => { }, () => { });
+        return operation;
+    }
+    #position(buffer, position, syscall) {
+        if (!(buffer instanceof Uint8Array))
+            throw new FsError("EINVAL", { syscall, path: this.#path });
+        if (position !== null) {
+            integer(position, syscall, this.#path);
+            if (syscall === "write" && this.#append && this.capabilities.positionedAppendWrite !== true)
+                throw new FsError("EINVAL", { syscall, path: this.#path });
+            if (!(syscall === "read" ? this.capabilities.positionedRead : this.capabilities.positionedWrite)) {
+                throw new FsError("ESPIPE", { syscall, path: this.#path });
+            }
+        }
+    }
+    stat(options = {}) {
+        return this.#run("fstat", options, (backend, forwarded) => backend.stat(backend.resource, forwarded));
+    }
+    getPosition(options = {}) {
+        return this.#run("getPosition", options, async (backend, forwarded) => {
+            if (!this.capabilities.position || !this.#getPosition)
+                throw new FsError("ENOTSUP", { syscall: "getPosition", path: this.#path });
+            const position = await this.#getPosition(backend.resource, forwarded);
+            if (!Number.isSafeInteger(position) || position < 0)
+                throw new FsError("EIO", { syscall: "getPosition", path: this.#path });
+            return position;
+        });
+    }
+    probeRead(options = {}) {
+        return this.#run("probeRead", options, async (backend, forwarded) => {
+            if (!this.capabilities.readObservation || !this.#probeRead)
+                throw new FsError("ENOTSUP", { syscall: "probeRead", path: this.#path });
+            const readiness = await this.#probeRead(backend.resource, forwarded);
+            if (readiness !== "ready" && readiness !== "blocked" && readiness !== "unknown")
+                throw new FsError("EIO", { syscall: "probeRead", path: this.#path });
+            return readiness;
+        });
+    }
+    read(buffer, position, options = {}) {
+        return this.#run("read", options, async (backend, forwarded) => {
+            if (this.#access === "write")
+                throw new FsError("EBADF", { syscall: "read", path: this.#path });
+            this.#position(buffer, position, "read");
+            if (buffer.byteLength === 0)
+                return 0;
+            const count = await backend.read(backend.resource, buffer, position, forwarded);
+            if (!Number.isSafeInteger(count) || count < 0 || count > buffer.byteLength)
+                throw new FsError("EIO", { syscall: "read", path: this.#path });
+            return count;
+        });
+    }
+    write(buffer, position, options = {}) {
+        return this.#run("write", options, async (backend, forwarded) => {
+            if (this.#access === "read")
+                throw new FsError("EBADF", { syscall: "write", path: this.#path });
+            this.#position(buffer, position, "write");
+            if (buffer.byteLength === 0 && this.capabilities.delegateZeroLengthWrite !== true)
+                return 0;
+            const count = await backend.write(backend.resource, buffer, position, forwarded);
+            if (!Number.isSafeInteger(count) || count < 0 || count > buffer.byteLength)
+                throw new FsError("EIO", { syscall: "write", path: this.#path });
+            return count;
+        });
+    }
+    truncate(length, options = {}) {
+        return this.#run("ftruncate", options, async (backend, forwarded) => {
+            if (this.#access === "read")
+                throw new FsError("EBADF", { syscall: "ftruncate", path: this.#path });
+            integer(length, "ftruncate", this.#path);
+            if (!this.capabilities.truncate)
+                throw new FsError("ENOTSUP", { syscall: "ftruncate", path: this.#path });
+            await backend.truncate(backend.resource, length, forwarded);
+        });
+    }
+    sync(dataOnly, options = {}) {
+        return this.#run(dataOnly ? "fdatasync" : "fsync", options, async (backend, forwarded) => {
+            if (typeof dataOnly !== "boolean")
+                throw new FsError("EINVAL", { syscall: "fsync", path: this.#path });
+            if (this.capabilities.synchronization === "none")
+                throw new FsError("ENOTSUP", { syscall: dataOnly ? "fdatasync" : "fsync", path: this.#path });
+            await backend.sync(backend.resource, dataOnly, forwarded);
+        });
+    }
+    close() {
+        this.#closing ??= this.#pending.then(async () => {
+            try {
+                await this.#backend.close(this.#backend.resource);
+            }
+            finally {
+                this.#backend = undefined;
+                this.#getPosition = undefined;
+                this.#probeRead = undefined;
+                this.#pending = Promise.resolve();
+            }
+        });
+        return this.#closing;
+    }
+}
+export async function openFileDescriptor(path, options, capabilities, acquire) {
+    if (!options || typeof options !== "object")
+        throw new FsError("EINVAL", { syscall: "open", path });
+    const signal = options.signal;
+    signal?.throwIfAborted();
+    const keys = ["access", "creation", "truncate", "append", "mode", "synchronization", "signal"];
+    const { access, creation = "never", truncate = false, append = false, mode = 0o666, synchronization } = options;
+    if (Object.keys(options).some(key => !keys.includes(key))
+        || !["read", "write", "readwrite"].includes(access)
+        || !["never", "ifMissing", "exclusive"].includes(creation)
+        || typeof truncate !== "boolean" || typeof append !== "boolean"
+        || access === "read" && (truncate || append)
+        || synchronization !== undefined && !["data", "all"].includes(synchronization)
+        || !Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) {
+        throw new FsError("EINVAL", { syscall: "open", path });
+    }
+    const admitted = Object.freeze({ access, creation, truncate, append, mode,
+        ...(signal === undefined ? {} : { signal }), ...(synchronization === undefined ? {} : { synchronization }) });
+    const admittedCapabilities = Object.freeze({ ...capabilities });
+    admitCapabilities(path, admitted, admittedCapabilities);
+    let backend;
+    try {
+        backend = await acquire(admitted);
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        throw error;
+    }
+    try {
+        signal?.throwIfAborted();
+        const selected = Object.freeze({ ...(backend.capabilities ?? admittedCapabilities) });
+        signal?.throwIfAborted();
+        admitCapabilities(path, admitted, selected);
+        const descriptor = new ManagedFileDescriptor(path, admitted, selected, backend);
+        signal?.throwIfAborted();
+        return descriptor;
+    }
+    catch (error) {
+        await finishCleanup(() => backend.close(backend.resource), true);
+        signal?.throwIfAborted();
+        throw error;
+    }
+}

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

@@ -1,4 +1,5 @@
-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 { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.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";
 export declare class DeviceFileSystem implements FileSystem {
     #private;
@@ -13,6 +14,7 @@ export declare class DeviceFileSystem implements FileSystem {
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     readStream(path: string, options?: ReadStreamOptions): ByteSource;
     openReadFile(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
+    open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     resizeFile(path: string, operation: FileResizeOperation, options?: FileResizeOptions): Promise<void>;
     openResizeFile(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
@@ -21,8 +23,10 @@ export declare class DeviceFileSystem implements FileSystem {
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
+    unlink(path: string, options?: FsOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;
     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/devices/index.js

@@ -1,4 +1,5 @@
 import { FsError, isFsError } from "../../contracts/errors.js";
+import { finishCleanup } from "../../contracts/cleanup.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "../mount/comparison.js";
 import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
@@ -9,17 +10,18 @@ const views = new WeakMap();
 const deviceCapabilities = Object.freeze({
     readOnly: false, read: true, stat: true, realpath: true, access: true, readdir: false,
     write: true, append: true, exclusiveCreate: true, streamingRead: true, retainedRead: true,
-    streamingWrite: true, streamingAppend: true, copy: true, exclusiveCopy: true,
+    streamingWrite: true, streamingAppend: true, independentWriteStreams: true, copy: true, exclusiveCopy: true,
     remove: false, removeDirectory: false, recursiveRemove: false, rename: false,
     mkdir: false, recursiveMkdir: false, symlinks: false, hardlinks: false, readlink: false,
     permissions: false, timestamps: false, truncate: false, randomAccessWrite: false,
-    atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
+    open: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
     atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true, atomicResize: false,
 });
 function globalCapabilities(filesystem) {
     const capabilities = { readOnly: false };
     const optional = {
-        atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
+        open: ["open"],
+        atomicEntryRemoval: ["removeEntryConditional"], atomicFileMutation: ["writeFileConditional", "removeFileConditional"], atomicFileStaging: ["createStagedFile", "publishStagedFile", "removeStagedFile"], atomicDirectoryMetadata: ["prepareDirectory"],
         streamingRead: ["readStream"], streamingWrite: ["writeStream"], retainedRead: ["openReadFile"],
         streamingAppend: ["writeStream"], descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
         symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"],
@@ -124,7 +126,7 @@ export class DeviceFileSystem {
             return deviceCapabilities;
         if (resolved === deviceDirectory)
             return { ...deviceCapabilities, readdir: true, write: false, append: false,
-                exclusiveCreate: false, streamingWrite: false, streamingAppend: false, descriptorWriteStream: false,
+                exclusiveCreate: false, streamingWrite: false, streamingAppend: false, independentWriteStreams: false, descriptorWriteStream: false,
                 retainedRead: false, retainedResize: false, streamingRead: false, copy: false, exclusiveCopy: false };
         const query = this.#filesystem.capabilitiesFor;
         options.signal?.throwIfAborted();
@@ -134,6 +136,8 @@ export class DeviceFileSystem {
         options.signal?.throwIfAborted();
         const capabilities = observed.retainedResize === true ? retainedResizeCapabilities(this.#filesystem, observed) : observed;
         const unavailable = {};
+        if (typeof this.#filesystem.open !== "function")
+            unavailable.open = false;
         if (typeof this.#filesystem.readStream !== "function")
             unavailable.streamingRead = false;
         if (typeof this.#filesystem.writeStream !== "function") {
@@ -229,6 +233,37 @@ export class DeviceFileSystem {
             async close() { closed = true; },
         };
     }
+    async open(path, options) {
+        options?.signal?.throwIfAborted();
+        if (!options || typeof options !== "object")
+            throw new FsError("EINVAL", { syscall: "open", path });
+        const resolved = await this.#resolve(path, options, options.creation !== "exclusive");
+        options.signal?.throwIfAborted();
+        if (resolved === nullPath || resolved === deviceDirectory)
+            throw new FsError("ENOTSUP", { syscall: "open", path });
+        const query = this.#filesystem.capabilitiesFor;
+        options.signal?.throwIfAborted();
+        const capabilities = query && options.creation !== "exclusive" ? await Reflect.apply(query, this.#filesystem, [path, options]) : this.#filesystem.capabilities;
+        options.signal?.throwIfAborted();
+        const open = this.#filesystem.open;
+        options.signal?.throwIfAborted();
+        if (capabilities.readOnly === true && (options.access === "write" || options.access === "readwrite" || options.creation === "ifMissing" || options.creation === "exclusive" || options.truncate === true || options.append === true))
+            throw new FsError("EROFS", { syscall: "open", path });
+        if (capabilities.open === false || typeof open !== "function")
+            throw new FsError("ENOTSUP", { syscall: "open", path });
+        let descriptor;
+        try {
+            descriptor = await Reflect.apply(open, this.#filesystem, [path, options]);
+            options.signal?.throwIfAborted();
+            return descriptor;
+        }
+        catch (error) {
+            if (descriptor)
+                await finishCleanup(() => descriptor.close(), true);
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+    }
     async resizeFile(path, operation, options = {}) {
         await this.#mutable(path, options);
         const capabilities = await this.capabilitiesFor(path, options);
@@ -343,6 +378,13 @@ export class DeviceFileSystem {
         await this.#mutable(path, options, false);
         await this.#filesystem.rm(path, options);
     }
+    async unlink(path, options = {}) {
+        await this.#mutable(path, options, false);
+        if (!this.#filesystem.unlink)
+            throw new FsError("ENOTSUP", { syscall: "unlink", path });
+        options.signal?.throwIfAborted();
+        await this.#filesystem.unlink(path, options);
+    }
     async rmdir(path, options = {}) {
         const resolved = await this.#resolve(path, options, false);
         if (resolved === nullPath)
@@ -360,6 +402,13 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         return this.#filesystem.writeFileConditional(path, data, options);
     }
+    async removeEntryConditional(path, options) {
+        await this.#mutable(path, options, false);
+        await requireOwnedMutation(this.#filesystem, path, "atomicEntryRemoval", options);
+        if (!this.#filesystem.removeEntryConditional)
+            throw new FsError("ENOTSUP", { path });
+        await this.#filesystem.removeEntryConditional(path, options);
+    }
     async removeFileConditional(path, options) {
         await this.#mutable(path, options, false);
         await requireOwnedMutation(this.#filesystem, path, "atomicFileMutation", options);