@poe-platform/safe-fs 0.1.538 → 0.1.540

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

@@ -56,6 +56,7 @@ export interface FileSystemCapabilities {
     readonly streamingRead?: boolean;
     readonly retainedRead?: boolean;
     readonly retainedResize?: boolean;
+    readonly atomicResize?: boolean;
     readonly streamingWrite?: boolean;
     readonly descriptorWriteStream?: boolean;
     readonly [capability: string]: boolean | undefined;
@@ -79,6 +80,22 @@ export interface OpenResizeFileOptions extends FsOptions {
     readonly create?: boolean;
     readonly mode?: number;
 }
+/** A single atomic read/compute/resize operation, never a caller-side stat/write pair.
+ * size and referenceSize use signed 64-bit byte integers (referenceSize is nonnegative).
+ * ioBlocks scales size by the target's preferred I/O block size before applying the
+ * modifier. Relative/min/max/round operations use referenceSize or the current size.
+ * Signed overflow rejects; negative final sizes clamp to zero. Providers enforce
+ * their size/quota/permission limits before allocation or publication. */
+export interface FileResizeOperation {
+    readonly size: bigint;
+    readonly modifier: "absolute" | "relative" | "minimum" | "maximum" | "down" | "up";
+    readonly referenceSize?: bigint;
+    readonly ioBlocks?: boolean;
+}
+export interface FileResizeOptions extends FsOptions {
+    readonly create?: boolean;
+    readonly mode?: number;
+}
 export interface FileResizeHandle {
     stat(options?: FsOptions): Promise<FileStat>;
     truncate(length: number, options?: FsOptions): Promise<void>;
@@ -128,6 +145,8 @@ export interface FileSystem {
     readonly capabilities: FileSystemCapabilities;
     openReadFile?(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
     openResizeFile?(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
+    /** Missing targets reject ENOENT unless create is true; existing bytes survive refusals. */
+    resizeFile?(path: string, operation: FileResizeOperation, options?: FileResizeOptions): Promise<void>;
     canonicalizeMissingTarget?(path: string, options?: FsOptions): string | undefined;
     capabilitiesFor?(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;

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

@@ -108,7 +108,7 @@ export function readOnlyCapabilities(capabilities) {
         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, retainedResize: false,
+        descriptorWriteStream: false, retainedResize: false, atomicResize: false,
         atomicRename: false, atomicRenameNoReplace: false, streamingWrite: false,
     });
 }
@@ -116,7 +116,7 @@ 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,
+    return Object.freeze({ ...rest, descriptorWriteStream: false, atomicResize: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });

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

@@ -1,4 +1,4 @@
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 export declare class DeviceFileSystem implements FileSystem {
     #private;
@@ -13,6 +13,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>;
+    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>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;

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

@@ -1,6 +1,6 @@
 import { FsError, isFsError } from "../../contracts/errors.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
-import { compareEntries, registerEntryView } from "../mount/comparison.js";
+import { compareEntries, registerEntryAuthority, registerEntryView } from "../mount/comparison.js";
 import { deviceDirectory, lexicalDevicePath, nullPath, resolveDevicePath } from "./path.js";
 import { deviceReadStream, drainDeviceFile, drainDeviceInput } from "./stream.js";
 import { openRetainedReadFile, openRetainedResizeFile, retainedResizeCapabilities } from "../capabilities.js";
@@ -13,13 +13,13 @@ const deviceCapabilities = Object.freeze({
     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,
-    atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true,
+    atomicRename: false, atomicRenameNoReplace: false, descriptorWriteStream: true, retainedResize: true, atomicResize: false,
 });
 function globalCapabilities(filesystem) {
     const capabilities = { readOnly: false };
     const optional = {
         streamingRead: ["readStream"], streamingWrite: ["writeStream"], retainedRead: ["openReadFile"],
-        streamingAppend: ["writeStream"], descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"],
+        streamingAppend: ["writeStream"], descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
         symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"],
         timestamps: ["utimes"], readlink: ["readlink"], truncate: ["truncate"], removeDirectory: ["rmdir"],
     };
@@ -84,6 +84,8 @@ export class DeviceFileSystem {
                         stat: resolved === nullPath ? this.#nullStat : this.#directoryStat, readOnly: false };
                 return { filesystem, path };
             });
+        // This internal view has no identity proof beyond its synthetic stats.
+        registerEntryAuthority(this, async () => "unknown");
         return view;
     }
     #resolve(path, options, followFinal = true, resizeCreate) {
@@ -139,6 +141,8 @@ export class DeviceFileSystem {
         }
         if (typeof this.#filesystem.openReadFile !== "function")
             unavailable.retainedRead = false;
+        if (observed.atomicResize === true && (typeof this.#filesystem.resizeFile !== "function" || observed.readOnly === true))
+            unavailable.atomicResize = false;
         const result = Object.keys(unavailable).some(key => capabilities[key] !== false)
             ? { ...capabilities, ...unavailable } : capabilities;
         options.signal?.throwIfAborted();
@@ -223,6 +227,19 @@ export class DeviceFileSystem {
             async close() { closed = true; },
         };
     }
+    async resizeFile(path, operation, options = {}) {
+        await this.#mutable(path, options);
+        const capabilities = await this.capabilitiesFor(path, options);
+        options.signal?.throwIfAborted();
+        if (capabilities.readOnly === true)
+            throw new FsError("EROFS", { syscall: "resizeFile", path });
+        const resize = this.#filesystem.resizeFile;
+        options.signal?.throwIfAborted();
+        if (capabilities.atomicResize !== true || typeof resize !== "function")
+            throw new FsError("ENOTSUP", { syscall: "resizeFile", path });
+        await Reflect.apply(resize, this.#filesystem, [path, operation, options]);
+        options.signal?.throwIfAborted();
+    }
     async openResizeFile(path, options = {}) {
         options.signal?.throwIfAborted();
         const resolution = this.#resolve(path, options, true, options.create ?? false);

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

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

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

@@ -91,7 +91,7 @@ export class MountFileSystem {
         const common = (capability) => {
             const optional = {
                 symlinks: ["symlink", "readlink"], hardlinks: ["link"], permissions: ["chmod"], timestamps: ["utimes"], readlink: ["readlink"],
-                descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"],
+                descriptorWriteStream: ["writeStream"], retainedResize: ["openResizeFile"], atomicResize: ["resizeFile"],
             };
             const values = mounts.map(({ backend }) => {
                 if (backend.capabilities.readOnly === true
@@ -110,7 +110,7 @@ export class MountFileSystem {
             "read", "stat", "readdir", "realpath", "access",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
-            "streamingAppend", "randomAccessWrite", "descriptorWriteStream", "retainedResize", "symlinks", "hardlinks", "permissions", "timestamps",
+            "streamingAppend", "randomAccessWrite", "descriptorWriteStream", "retainedResize", "atomicResize", "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); },
@@ -137,8 +137,10 @@ export class MountFileSystem {
             const declared = observed.descriptorWriteStream === true
                 && (typeof location.mount.backend.writeStream !== "function" || observed.readOnly === true || observed.streamingWrite === false)
                 ? { ...observed, descriptorWriteStream: false } : observed;
-            const capabilities = location.synthetic ? { ...declared, retainedRead: false }
-                : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, declared));
+            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));
             if (location.synthetic)
                 return readOnlyCapabilities(capabilities);
             if (this.mounts.length === 1 || capabilities.readOnly === true)
@@ -167,6 +169,23 @@ export class MountFileSystem {
             throw error ? this.error(error, "openReadFile", path, options) : error;
         }
     }
+    async resizeFile(path, operation, options = {}) {
+        return this.operation("resizeFile", path, options, async () => {
+            const location = await this.resolve(path, options, { allowMissing: options.create === true, resizeCreate: options.create ?? false });
+            if (location.synthetic)
+                fail("EROFS");
+            const backend = location.mount.backend;
+            const capabilities = await backend.capabilitiesFor?.(location.local, options) ?? backend.capabilities;
+            options.signal?.throwIfAborted();
+            if (capabilities.readOnly === true)
+                fail("EROFS");
+            const resize = backend.resizeFile;
+            options.signal?.throwIfAborted();
+            if (capabilities.atomicResize !== true || typeof resize !== "function")
+                fail("ENOTSUP");
+            await Reflect.apply(resize, backend, [location.local, operation, options]);
+        });
+    }
     async openResizeFile(path, options = {}) {
         try {
             options.signal?.throwIfAborted();

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

@@ -120,7 +120,7 @@ export class OverlayFileSystem {
             ...(effectiveAppend === undefined ? {} : { append: effectiveAppend }),
             atomicRename: false, atomicRenameNoReplace: false,
             descriptorWriteStream: false,
-            retainedResize: false,
+            retainedResize: false, atomicResize: false,
             hardlinks: false,
             symlinks: writable && this.#upper.capabilities.symlinks === true
                 && typeof this.#upper.symlink === "function" && typeof this.#upper.readlink === "function"

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

@@ -316,7 +316,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 === "canonicalizeMissingTarget")
+            if (property === "canonicalizeMissingTarget" || property === "resizeFile")
                 return undefined;
             if (property === "capabilities")
                 return quotaCapabilities(retainedResizeCapabilities(fs, retainedReadCapabilities(fs)));

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

@@ -6,7 +6,7 @@ const originals = new WeakMap();
 const operations = new Set([
     "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
     "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir",
-    "readlink", "realpath", "rename", "rm", "rmdir", "stat", "symlink", "truncate", "utimes",
+    "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
 ]);
 export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = charge) {

package/package.json

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