@poe-platform/safe-fs 0.1.531 → 0.1.533

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

@@ -9,7 +9,8 @@ export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
-export { scopeFileSystem } from "./fs/scoped.js";
+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 { compareEntries } from "./fs/mount/comparison.js";

package/dist/safe-fs/core.js

@@ -9,7 +9,7 @@ export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
-export { scopeFileSystem } from "./fs/scoped.js";
+export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";

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

@@ -1,2 +1,12 @@
-import type { FileSystem } from "../contracts/filesystem.js";
-export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal): FileSystem;
+import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
+export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal, cleanupCharge?: () => void): FileSystem;
+export interface RetainedFileSystemCleanupView {
+    readonly lstat: FileSystem["lstat"];
+    readonly realpath: FileSystem["realpath"];
+    readonly rm: (path: string, options?: FsOptions) => Promise<void>;
+    readonly rmdir?: NonNullable<FileSystem["rmdir"]>;
+}
+export interface RetainedFileSystemCleanupOptions {
+    readonly maxOperations?: number;
+}
+export declare function retainFileSystemCleanup(filesystem: FileSystem, cleanupCallback: (view: RetainedFileSystemCleanupView) => void | PromiseLike<void>, options?: RetainedFileSystemCleanupOptions): () => Promise<void>;

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

@@ -9,8 +9,8 @@ const operations = new Set([
     "readlink", "realpath", "rename", "rm", "rmdir", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
 ]);
-export function scopeFileSystem(filesystem, charge, signal) {
-    const original = originals.get(filesystem) ?? filesystem;
+export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = charge) {
+    const original = originals.get(filesystem)?.filesystem ?? filesystem;
     const methods = new Map();
     const assertOpen = (options) => {
         signal.throwIfAborted();
@@ -165,7 +165,7 @@ export function scopeFileSystem(filesystem, charge, signal) {
                 }
                 if (property === "compareEntry") {
                     const peer = args[1];
-                    args[1] = originals.get(peer) ?? peer;
+                    args[1] = originals.get(peer)?.filesystem ?? peer;
                 }
                 if (property === "rename" && args[2]?.noReplace)
                     return (async () => {
@@ -199,10 +199,94 @@ export function scopeFileSystem(filesystem, charge, signal) {
             return scoped;
         },
     });
-    originals.set(view, original);
+    originals.set(view, { filesystem: original, signal, cleanupCharge });
     registerEntryView(view, async (path, options) => {
         assertOpen(options);
         return { filesystem: original, path };
     });
     return view;
 }
+export function retainFileSystemCleanup(filesystem, cleanupCallback, options) {
+    const maximum = options?.maxOperations === undefined ? 256 : options.maxOperations;
+    if (!Number.isSafeInteger(maximum) || maximum < 0 || maximum > 4096)
+        throw new RangeError("cleanup maxOperations must be an integer between 0 and 4096");
+    if (typeof cleanupCallback !== "function")
+        throw new TypeError("cleanup callback must be a function");
+    const scope = originals.get(filesystem);
+    scope?.signal.throwIfAborted();
+    const backing = scope?.filesystem ?? filesystem;
+    const pending = new Set();
+    let operations = 0;
+    let active = false;
+    let closing;
+    const invoke = (method, path, settings) => {
+        if (!active) {
+            const rejected = Promise.reject(new FsError("EBADF", { syscall: method, path, message: "cleanup callback is not active" }));
+            void rejected.catch(() => { });
+            return rejected;
+        }
+        let result;
+        try {
+            settings?.signal?.throwIfAborted();
+            if (operations >= maximum)
+                throw new FsError("EFBIG", { syscall: method, path, message: "cleanup operation limit exceeded" });
+            operations++;
+            scope?.cleanupCharge();
+            settings?.signal?.throwIfAborted();
+            const operation = backing[method];
+            if (typeof operation !== "function")
+                throw new FsError("ENOTSUP", { syscall: method, path });
+            const parameters = method === "rm" ? { ...settings, recursive: false, force: false } : settings;
+            result = Promise.resolve(Reflect.apply(operation, backing, [path, parameters]));
+        }
+        catch (error) {
+            result = Promise.reject(error);
+            void result.catch(() => { });
+            return result;
+        }
+        const completion = result.then(() => { pending.delete(completion); return { status: "fulfilled", value: undefined }; }, error => { pending.delete(completion); return { status: "rejected", reason: error }; });
+        pending.add(completion);
+        return result;
+    };
+    const view = Object.freeze(Object.assign(Object.create(null), {
+        lstat: invoke.bind(undefined, "lstat"),
+        realpath: invoke.bind(undefined, "realpath"),
+        rm: invoke.bind(undefined, "rm"),
+        ...(typeof backing.rmdir === "function" ? { rmdir: invoke.bind(undefined, "rmdir") } : {}),
+    }));
+    scope?.signal.throwIfAborted();
+    return () => {
+        if (!closing) {
+            closing = Promise.resolve().then(async () => {
+                active = true;
+                let callbackFailed = false;
+                let callbackFailure;
+                try {
+                    const result = cleanupCallback(view);
+                    if (result !== undefined)
+                        await result;
+                }
+                catch (error) {
+                    callbackFailed = true;
+                    callbackFailure = error;
+                }
+                finally {
+                    active = false;
+                }
+                const outcomes = await Promise.all(pending);
+                if (callbackFailed)
+                    throw callbackFailure;
+                const failures = [];
+                for (const outcome of outcomes)
+                    if (outcome.status === "rejected")
+                        failures.push(outcome.reason);
+                if (failures.length === 1)
+                    throw failures[0];
+                if (failures.length > 1)
+                    throw new AggregateError(failures, "retained filesystem cleanup failed");
+            });
+            void closing.catch(() => { });
+        }
+        return closing;
+    };
+}

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

@@ -10,7 +10,8 @@ export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
-export { scopeFileSystem } from "./fs/scoped.js";
+export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
+export type { RetainedFileSystemCleanupView, RetainedFileSystemCleanupOptions } from "./fs/scoped.js";
 export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";

package/dist/safe-fs/index.js

@@ -9,7 +9,7 @@ export * from "./fs/readonly/index.js";
 export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
-export { scopeFileSystem } from "./fs/scoped.js";
+export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createNodeFileSystemAdapterRegistry } from "./config.node.js";

package/package.json

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