@poe-platform/safe-fs 0.1.52 → 0.1.54

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

@@ -23,7 +23,28 @@ export interface DirectoryEntry {
 }
 export interface FileSystemCapabilities {
     readonly readOnly?: boolean;
+    readonly read?: boolean;
+    readonly stat?: boolean;
+    readonly readdir?: boolean;
+    readonly realpath?: boolean;
+    readonly access?: boolean;
+    readonly write?: boolean;
     readonly append?: boolean;
+    readonly exclusiveCreate?: boolean;
+    readonly explicitDirectories?: boolean;
+    readonly implicitDirectories?: boolean;
+    readonly mkdir?: boolean;
+    readonly recursiveMkdir?: boolean;
+    readonly remove?: boolean;
+    readonly removeDirectory?: boolean;
+    readonly recursiveRemove?: boolean;
+    readonly rename?: boolean;
+    readonly copy?: boolean;
+    readonly exclusiveCopy?: boolean;
+    readonly readlink?: boolean;
+    readonly truncate?: boolean;
+    readonly streamingAppend?: boolean;
+    readonly randomAccessWrite?: boolean;
     readonly symlinks?: boolean;
     readonly hardlinks?: boolean;
     readonly permissions?: boolean;
@@ -65,6 +86,7 @@ export interface ReadStreamOptions extends FsOptions {
 }
 export interface FileSystem {
     readonly capabilities: FileSystemCapabilities;
+    capabilitiesFor?(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;

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

@@ -0,0 +1,4 @@
+import type { FileSystemCapabilities } from "../contracts/filesystem.js";
+export declare function requireCapabilities(...values: readonly (boolean | undefined)[]): boolean | undefined;
+export declare function readOnlyCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;
+export declare function quotaCapabilities(capabilities: FileSystemCapabilities): FileSystemCapabilities;

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

@@ -0,0 +1,25 @@
+export function requireCapabilities(...values) {
+    return values.some(value => value === false) ? false : values.every(value => value === true) ? true : undefined;
+}
+export function readOnlyCapabilities(capabilities) {
+    const inspection = Object.fromEntries([
+        "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories",
+        "symlinks", "streamingRead",
+    ].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,
+        atomicRename: false, streamingWrite: false,
+    });
+}
+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,
+        ...(streamingWrite === undefined ? {} : { streamingWrite }),
+        ...(streamingAppend === undefined ? {} : { streamingAppend }),
+    });
+}

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

@@ -2,6 +2,28 @@ import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryCompariso
 import type { ByteSource } from "../../contracts/io.js";
 export declare class MemoryFileSystem implements FileSystem {
     readonly capabilities: Readonly<{
+        read: true;
+        stat: true;
+        readdir: true;
+        realpath: true;
+        access: true;
+        write: true;
+        append: true;
+        exclusiveCreate: true;
+        explicitDirectories: true;
+        implicitDirectories: false;
+        mkdir: true;
+        recursiveMkdir: true;
+        remove: true;
+        removeDirectory: true;
+        recursiveRemove: true;
+        rename: true;
+        copy: true;
+        exclusiveCopy: true;
+        readlink: true;
+        truncate: true;
+        streamingAppend: true;
+        randomAccessWrite: true;
         readOnly: false;
         symlinks: true;
         hardlinks: true;

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

@@ -48,6 +48,11 @@ const compareOwnedMemory = async (own, peer, options) => {
 };
 export class MemoryFileSystem {
     capabilities = Object.freeze({
+        read: true, stat: true, readdir: true, realpath: true, access: true,
+        write: true, append: true, exclusiveCreate: true, explicitDirectories: true, implicitDirectories: false,
+        mkdir: true, recursiveMkdir: true, remove: true, removeDirectory: true, recursiveRemove: true,
+        rename: true, copy: true, exclusiveCopy: true, readlink: true, truncate: true,
+        streamingAppend: true, randomAccessWrite: true,
         readOnly: false,
         symlinks: true,
         hardlinks: true,

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

@@ -9,6 +9,7 @@ export declare class MountFileSystem implements FileSystem {
     private readonly mounts;
     constructor(options: MountFileSystemOptions);
     private select;
+    capabilitiesFor(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
     private protected;
     private error;
     private operation;

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

@@ -1,6 +1,7 @@
 import { FsError, isFsError, toFsError } from "../../contracts/errors.js";
 import { readBytes } from "../../contracts/io.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
+import { readOnlyCapabilities } from "../capabilities.js";
 import { normalizePath, validatePath } from "../../contracts/virtual-path.js";
 import { compareIdentity } from "./identity.js";
 import { compareEntries, registerEntryAuthority, registerEntryView } from "./comparison.js";
@@ -79,14 +80,32 @@ export class MountFileSystem {
         const streamingWrite = streaming("streamingWrite", "writeStream");
         const append = all("append") ? true
             : mounts.every(({ backend }) => backend.capabilities.append === false) ? false : undefined;
+        const common = (capability) => {
+            const optional = {
+                symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
+            };
+            const values = mounts.map(({ backend }) => {
+                if (backend.capabilities.readOnly === true
+                    && !["read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories"].includes(capability))
+                    return false;
+                const declared = backend.capabilities[capability];
+                return declared === true && optional[capability]?.some(method => typeof backend[method] !== "function") ? false : declared;
+            });
+            if (["rename", "copy", "exclusiveCopy"].includes(capability) && mounts.length > 1)
+                return undefined;
+            return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
+        };
+        const semantics = Object.fromEntries([
+            "read", "stat", "readdir", "realpath", "access",
+            "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
+            "remove", "removeDirectory", "recursiveRemove", "rename", "copy", "exclusiveCopy", "readlink", "truncate",
+            "streamingAppend", "randomAccessWrite", "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); },
             readOnly: all("readOnly"),
             ...(append === undefined ? {} : { append }),
-            symlinks: all("symlinks", ["readlink", "symlink"]),
-            hardlinks: all("hardlinks", ["link"]),
-            permissions: all("permissions", ["chmod"]),
-            timestamps: all("timestamps", ["utimes"]),
+            ...semantics,
             atomicRename: mounts.length === 1 && all("atomicRename"),
             ...(streamingRead === undefined ? {} : { streamingRead }),
             ...(streamingWrite === undefined ? {} : { streamingWrite }),
@@ -95,6 +114,24 @@ export class MountFileSystem {
     select(path) {
         return this.mounts.find((mount) => within(mount.path, path));
     }
+    async capabilitiesFor(path, options = {}) {
+        return this.operation("capabilitiesFor", path, options, async () => {
+            const location = await this.resolve(path, options, { allowMissing: true });
+            const capabilities = await location.mount.backend.capabilitiesFor?.(location.local, options)
+                ?? location.mount.backend.capabilities;
+            if (location.synthetic)
+                return readOnlyCapabilities(capabilities);
+            if (this.mounts.length === 1 || capabilities.readOnly === true)
+                return Object.freeze({ ...capabilities });
+            const { rename: ignoredRename, copy: ignoredCopy, exclusiveCopy: ignoredExclusiveCopy, ...selected } = capabilities;
+            const cannotPublish = capabilities.write === false && capabilities.streamingWrite === false && capabilities.exclusiveCreate === false;
+            return Object.freeze({
+                ...selected,
+                ...(capabilities.copy === false && capabilities.exclusiveCopy === false && cannotPublish ? { copy: false } : {}),
+                ...(capabilities.exclusiveCopy === false && capabilities.exclusiveCreate === false && capabilities.streamingWrite === false ? { exclusiveCopy: false } : {}),
+            });
+        });
+    }
     protected(path) {
         return path === "/" || this.mounts.some((mount) => within(path, mount.path));
     }

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

@@ -1,4 +1,5 @@
 import { platform } from "#safe-fs-platform";
+import { requireCapabilities } from "../capabilities.js";
 import { finishCleanup } from "../../contracts/cleanup.js";
 import { collectBytes, readBytes } from "../../contracts/io.js";
 import { FsError, toFsError } from "../../contracts/errors.js";
@@ -83,9 +84,35 @@ export class OverlayFileSystem {
             ? readable.every((capability) => capability === true) ? true : undefined : false;
         const append = !writable || this.#upper.capabilities.append === false ? false
             : this.#upper.capabilities.append === true ? true : undefined;
+        const upper = this.#upper.capabilities;
+        const mutation = requireCapabilities(writable, upper.mkdir, upper.rename, upper.remove, upper.exclusiveCreate, upper.timestamps, upper.permissions);
+        const effectiveAppend = requireCapabilities(append, mutation);
+        const effectiveStreamingWrite = requireCapabilities(streamingWrite, mutation);
+        const semantics = Object.fromEntries([
+            ...["read", "stat", "readdir", "realpath", "access"].map(capability => [capability,
+                requireCapabilities(upper[capability], this.#lower.capabilities[capability])]),
+            ["write", requireCapabilities(mutation, upper.write)],
+            ["exclusiveCreate", requireCapabilities(mutation, upper.exclusiveCreate)],
+            ["mkdir", requireCapabilities(mutation, upper.mkdir)],
+            ["recursiveMkdir", requireCapabilities(mutation, upper.recursiveMkdir)],
+            ["remove", requireCapabilities(mutation, upper.remove)],
+            ["removeDirectory", requireCapabilities(mutation, upper.removeDirectory)],
+            ["recursiveRemove", requireCapabilities(mutation, upper.recursiveRemove)],
+            ["rename", requireCapabilities(mutation, upper.rename, upper.write)],
+            ["copy", requireCapabilities(mutation, upper.write)],
+            ["exclusiveCopy", requireCapabilities(mutation, upper.exclusiveCreate)],
+            ["truncate", requireCapabilities(mutation, upper.truncate)],
+            ["streamingAppend", requireCapabilities(mutation, streamingWrite, upper.streamingAppend)],
+            ["randomAccessWrite", requireCapabilities(mutation, upper.randomAccessWrite)],
+            ["explicitDirectories", requireCapabilities(upper.explicitDirectories, this.#lower.capabilities.explicitDirectories)],
+        ].filter(([, value]) => value !== undefined));
         this.capabilities = Object.freeze({
-            readOnly: !writable,
-            ...(append === undefined ? {} : { append }),
+            ...semantics,
+            implicitDirectories: false,
+            readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
+                : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,
+            ...(upper.readOnly === undefined ? {} : { readOnly: upper.readOnly }),
+            ...(effectiveAppend === undefined ? {} : { append: effectiveAppend }),
             atomicRename: false,
             hardlinks: false,
             symlinks: writable && this.#upper.capabilities.symlinks === true
@@ -94,7 +121,7 @@ export class OverlayFileSystem {
             permissions: writable && this.#upper.capabilities.permissions === true && typeof this.#upper.chmod === "function",
             timestamps: writable && this.#upper.capabilities.timestamps === true && typeof this.#upper.utimes === "function",
             ...(streamingRead === undefined ? {} : { streamingRead }),
-            ...(streamingWrite === undefined ? {} : { streamingWrite }),
+            ...(effectiveStreamingWrite === undefined ? {} : { streamingWrite: effectiveStreamingWrite }),
         });
         Object.defineProperty(this, "capabilities", { writable: false, configurable: false });
     }

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

@@ -1,3 +1,4 @@
+import { quotaCapabilities } from "../capabilities.js";
 export class FileSystemQuotaError extends Error {
     maxBytes;
     constructor(maxBytes) {
@@ -99,6 +100,10 @@ export function withFileSystemQuota(fs, options) {
     };
     return new Proxy(fs, {
         get(target, property) {
+            if (property === "capabilities")
+                return quotaCapabilities(target.capabilities);
+            if (property === "capabilitiesFor")
+                return async (path, fsOptions) => quotaCapabilities(await target.capabilitiesFor?.(path, fsOptions) ?? target.capabilities);
             const replacement = Reflect.get(mutations, property);
             if (typeof replacement === "function")
                 return replacement;

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

@@ -4,6 +4,7 @@ export declare class ReadOnlyFileSystem implements FileSystem {
     #private;
     constructor(filesystem: FileSystem);
     get capabilities(): FileSystemCapabilities;
+    capabilitiesFor(path: string, options?: FsOptions): Promise<FileSystemCapabilities>;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;

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

@@ -2,6 +2,7 @@ import { ACCESS_MODES } from "../../contracts/filesystem.js";
 import { FsError } from "../../contracts/errors.js";
 import { readBytes } from "../../contracts/io.js";
 import { compareEntries, registerEntryView } from "../mount/comparison.js";
+import { readOnlyCapabilities } from "../capabilities.js";
 function readOnly(syscall, path, dest) {
     throw new FsError("EROFS", { syscall, path, ...(dest === undefined ? {} : { dest }) });
 }
@@ -26,7 +27,8 @@ export class ReadOnlyFileSystem {
         this.#filesystem = filesystem;
         registerEntryView(this, async (path) => ({ filesystem: this.#filesystem, path, readOnly: true }));
         const streamingRead = typeof filesystem.readStream === "function" ? filesystem.capabilities.streamingRead : false;
-        this.#capabilities = Object.freeze({
+        this.#capabilities = readOnlyCapabilities({
+            ...filesystem.capabilities,
             readOnly: true,
             append: false,
             symlinks: filesystem.capabilities.symlinks === true && typeof filesystem.readlink === "function",
@@ -41,6 +43,10 @@ export class ReadOnlyFileSystem {
     get capabilities() {
         return this.#capabilities;
     }
+    async capabilitiesFor(path, options) {
+        const capabilities = await this.#filesystem.capabilitiesFor?.(path, options) ?? this.#filesystem.capabilities;
+        return readOnlyCapabilities(capabilities);
+    }
     async readFile(path, options) {
         return new Uint8Array(await this.#filesystem.readFile(path, options));
     }

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

@@ -80,6 +80,11 @@ function nativeError(error) {
  */
 export class RealFileSystem {
     capabilities = Object.freeze({
+        read: true, stat: true, readdir: true, realpath: true, access: true,
+        write: true, append: true, exclusiveCreate: true, explicitDirectories: true, implicitDirectories: false,
+        mkdir: true, recursiveMkdir: true, remove: true, removeDirectory: true, recursiveRemove: true,
+        rename: true, copy: true, exclusiveCopy: true, readlink: true, truncate: true,
+        streamingAppend: true, randomAccessWrite: true,
         readOnly: false, symlinks: true, hardlinks: true, permissions: true,
         timestamps: true, atomicRename: true, streamingRead: true, streamingWrite: true,
     });

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

@@ -22,6 +22,28 @@ export declare class S3RenameError extends FsError {
 }
 export declare class S3FileSystem implements FileSystem {
     readonly capabilities: Readonly<{
+        read: true;
+        stat: true;
+        readdir: true;
+        realpath: true;
+        access: true;
+        write: true;
+        explicitDirectories: true;
+        implicitDirectories: true;
+        mkdir: true;
+        recursiveMkdir: true;
+        remove: true;
+        removeDirectory: true;
+        recursiveRemove: true;
+        copy: true;
+        readlink: false;
+        exclusiveCopy: boolean;
+        append: boolean;
+        exclusiveCreate: boolean;
+        truncate: boolean;
+        rename: boolean;
+        streamingAppend: boolean;
+        randomAccessWrite: false;
         readOnly: boolean;
         symlinks: false;
         hardlinks: false;

package/dist/safe-fs/fs/s3/filesystem.js

@@ -104,6 +104,18 @@ export class S3FileSystem {
         this.maxStreamBytes = validateLimit(options.maxStreamBytes ?? 5_000_000_000, "maxStreamBytes", 0, 5_000_000_000);
         this.maxListEntries = validateLimit(options.maxListEntries ?? 100_000, "maxListEntries", 1);
         this.capabilities = Object.freeze({
+            read: true, stat: true, readdir: true, realpath: true, access: true,
+            write: true, explicitDirectories: true, implicitDirectories: true, mkdir: true, recursiveMkdir: true,
+            remove: true, removeDirectory: true, recursiveRemove: true, copy: true, readlink: false,
+            exclusiveCopy: options.transport.capabilities?.conditionalCopy === true,
+            append: options.transport.capabilities?.conditionalPut === true,
+            exclusiveCreate: options.transport.capabilities?.conditionalPut === true,
+            truncate: options.transport.capabilities?.conditionalPut === true,
+            rename: this.allowRename && options.transport.capabilities?.conditionalDelete === true
+                && (options.transport.capabilities?.conditionalCopy === true || options.transport.capabilities?.conditionalPut === true),
+            streamingAppend: options.transport.capabilities?.streamingWrite === true
+                && options.transport.capabilities?.conditionalPut === true && typeof options.transport.putObjectStream === "function",
+            randomAccessWrite: false,
             readOnly: options.readOnly ?? false,
             symlinks: false, hardlinks: false, permissions: false,
             timestamps: options.transport.capabilities?.conditionalCopy === true || options.transport.capabilities?.conditionalPut === true,

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

@@ -33,6 +33,28 @@ export interface WebDavFileSystemOptions {
 }
 export declare class WebDavFileSystem implements FileSystem {
     readonly capabilities: Readonly<{
+        read: true;
+        stat: true;
+        readdir: true;
+        realpath: true;
+        access: true;
+        write: true;
+        append: true;
+        exclusiveCreate: true;
+        explicitDirectories: true;
+        implicitDirectories: false;
+        mkdir: true;
+        recursiveMkdir: true;
+        remove: true;
+        recursiveRemove: true;
+        rename: true;
+        copy: true;
+        exclusiveCopy: true;
+        readlink: false;
+        truncate: false;
+        randomAccessWrite: false;
+        removeDirectory: boolean;
+        streamingAppend: boolean;
         symlinks: false;
         hardlinks: false;
         permissions: false;

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

@@ -140,6 +140,11 @@ function statusCode(element) {
 }
 export class WebDavFileSystem {
     capabilities = Object.freeze({
+        read: true, stat: true, readdir: true, realpath: true, access: true,
+        write: true, append: true, exclusiveCreate: true, explicitDirectories: true, implicitDirectories: false,
+        mkdir: true, recursiveMkdir: true, remove: true, recursiveRemove: true, rename: true, copy: true,
+        exclusiveCopy: true, readlink: false, truncate: false, randomAccessWrite: false,
+        removeDirectory: false, streamingAppend: false,
         symlinks: false, hardlinks: false, permissions: false, timestamps: true,
         atomicRename: false, streamingRead: true, streamingWrite: true,
     });
@@ -200,6 +205,10 @@ export class WebDavFileSystem {
         }
         this.transport = options.fetch === globalThis.fetch ? options.fetch.bind(globalThis) : options.fetch;
         this.requestStreamSupport = options.requestStreamSupport ?? (options.fetch === globalThis.fetch ? "native" : false);
+        this.capabilities = Object.freeze({ ...this.capabilities,
+            removeDirectory: this.atomicEmptyDirectory !== undefined,
+            streamingAppend: this.requestStreamSupport !== false,
+        });
         this.maxResponseBytes = positive(options.maxResponseBytes ?? 64 * 1024 * 1024, "maxResponseBytes");
         this.maxXmlBytes = positive(options.maxXmlBytes ?? 2 * 1024 * 1024, "maxXmlBytes");
         this.maxEntries = positive(options.maxEntries ?? 10_000, "maxEntries");

package/package.json

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