pwd-fs 3.3.5 → 3.5.0

package/dist/powered-file-system.js

@@ -25,9 +25,12 @@ const append_1 = require("./powered-file-system/append");
 const chmod_1 = require("./powered-file-system/chmod");
 const chown_1 = require("./powered-file-system/chown");
 const copy_1 = require("./powered-file-system/copy");
+const empty_dir_1 = require("./powered-file-system/empty-dir");
 const mkdir_1 = require("./powered-file-system/mkdir");
 const read_1 = require("./powered-file-system/read");
+const readlink_1 = require("./powered-file-system/readlink");
 const readdir_1 = require("./powered-file-system/readdir");
+const realpath_1 = require("./powered-file-system/realpath");
 const remove_1 = require("./powered-file-system/remove");
 const rename_1 = require("./powered-file-system/rename");
 const stat_1 = require("./powered-file-system/stat");
@@ -38,8 +41,7 @@ __exportStar(require("./bitmask"), exports);
 /**
  * Path-aware wrapper around Node's file system APIs.
  *
- * All relative paths are resolved against `pwd`, which makes the instance
- * suitable for sandboxed or virtual working-directory workflows.
+ * Relative paths are resolved against `pwd`; absolute paths are preserved.
  */
 class PoweredFileSystem {
     pwd;
@@ -63,80 +65,56 @@ class PoweredFileSystem {
         this.pwd = pwd ? node_path_1.default.resolve(pwd) : process.cwd();
     }
     /**
-     * Checks whether the given path is accessible with the requested mode.
+     * Resolves relative paths against `pwd` while preserving absolute paths.
      */
+    resolve(src) {
+        return node_path_1.default.resolve(this.pwd, src);
+    }
     test(src, options) {
         return test_1.test.call(this, src, options);
     }
-    /**
-     * Returns `lstat` information for a path.
-     */
     stat(src, options) {
         return stat_1.stat.call(this, src, options);
     }
-    /**
-     * Applies a mode recursively to a file or directory tree.
-     */
     chmod(src, mode, options) {
         return chmod_1.chmod.call(this, src, mode, options);
     }
-    /**
-     * Applies ownership recursively to a file or directory tree.
-     */
     chown(src, options) {
         return chown_1.chown.call(this, src, options);
     }
-    /**
-     * Creates a symbolic link from `dest` to `src`.
-     */
     symlink(src, dest, options) {
         return symlink_1.symlink.call(this, src, dest, options);
     }
-    /**
-     * Copies `src` into the destination directory.
-     */
     copy(src, dest, options) {
         return copy_1.copy.call(this, src, dest, options);
     }
-    /**
-     * Renames or moves a file system node.
-     */
     rename(src, dest, options) {
         return rename_1.rename.call(this, src, dest, options);
     }
-    /**
-     * Removes a file system node recursively.
-     */
     remove(src, options) {
         return remove_1.remove.call(this, src, options);
     }
-    /**
-     * Reads a file relative to the current instance root.
-     */
+    emptyDir(src, options) {
+        return empty_dir_1.emptyDir.call(this, src, options);
+    }
     read(src, options) {
         return read_1.read.call(this, src, options);
     }
-    /**
-     * Writes a file and applies the resulting permissions explicitly.
-     */
     write(src, data, options) {
         return write_1.write.call(this, src, data, options);
     }
-    /**
-     * @deprecated Use `write(..., { flag: 'a' })` instead.
-     */
     append(src, data, options) {
         return append_1.append.call(this, src, data, options);
     }
-    /**
-     * Lists directory entries relative to the current instance root.
-     */
     readdir(dir, options) {
         return readdir_1.readdir.call(this, dir, options);
     }
-    /**
-     * Creates a directory tree relative to the current instance root.
-     */
+    readlink(src, options) {
+        return readlink_1.readlink.call(this, src, options);
+    }
+    realpath(src, options) {
+        return realpath_1.realpath.call(this, src, options);
+    }
     mkdir(dir, options) {
         return mkdir_1.mkdir.call(this, dir, options);
     }

package/dist/powered-file-system.test.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_assert_1 = __importDefault(require("node:assert"));
+const node_path_1 = __importDefault(require("node:path"));
 const node_test_1 = require("node:test");
 const index_1 = require("./index");
+const test_utils_1 = require("./test-utils");
 /**
  * Verifies constructor path resolution semantics for the main API surface.
  */
@@ -18,4 +20,27 @@ const index_1 = require("./index");
         const { pwd } = new index_1.PoweredFileSystem(__dirname);
         (0, node_assert_1.default)(pwd === __dirname);
     });
+    (0, node_test_1.it)('Positive: Resolve should accept paths inside the working directory', () => {
+        const tmpDir = (0, test_utils_1.createTmpDir)();
+        try {
+            const pfs = new index_1.PoweredFileSystem(tmpDir);
+            const resolved = pfs.resolve('./nested/file.txt');
+            (0, node_assert_1.default)(resolved === node_path_1.default.join(tmpDir, 'nested', 'file.txt'));
+        }
+        finally {
+            (0, test_utils_1.restore)(tmpDir);
+        }
+    });
+    (0, node_test_1.it)('Positive: Resolve should preserve absolute paths outside the working directory', () => {
+        const tmpDir = (0, test_utils_1.createTmpDir)();
+        const outsidePath = node_path_1.default.resolve(node_path_1.default.dirname(tmpDir), 'outside.txt');
+        try {
+            const pfs = new index_1.PoweredFileSystem(tmpDir);
+            const resolved = pfs.resolve(outsidePath);
+            (0, node_assert_1.default)(resolved === outsidePath);
+        }
+        finally {
+            (0, test_utils_1.restore)(tmpDir);
+        }
+    });
 });

package/dist/recurse-io-sync.d.ts

@@ -1,3 +1,4 @@
+import type { ICopyOptions } from './recurse-io';
 /**
  * Synchronous counterpart of the recursive chmod implementation.
  */
@@ -5,15 +6,19 @@ export declare function chmodSync(src: string, mode: number): void;
 /**
  * Synchronous counterpart of the recursive chown implementation.
  */
-export declare function chownSync(src: string, uid: number, gid: number): void;
+export declare function chownSync(src: string, uid: number | undefined, gid: number | undefined): void;
 /**
  * Synchronously copies a file system node into the target directory.
  */
-export declare function copySync(src: string, dir: string, umask: number): void;
+export declare function copySync(src: string, dir: string, options: ICopyOptions): void;
 /**
  * Synchronously removes files, directories, and symlinks without following links.
  */
 export declare function removeSync(src: string): void;
+/**
+ * Synchronously removes all entries inside a directory while preserving it.
+ */
+export declare function emptyDirSync(src: string): void;
 /**
  * Synchronously creates a directory tree using permissions derived from umask.
  */

package/dist/recurse-io-sync.js

@@ -7,6 +7,7 @@ exports.chmodSync = chmodSync;
 exports.chownSync = chownSync;
 exports.copySync = copySync;
 exports.removeSync = removeSync;
+exports.emptyDirSync = emptyDirSync;
 exports.mkdirSync = mkdirSync;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -28,60 +29,65 @@ function chmodSync(src, mode) {
  */
 function chownSync(src, uid, gid) {
     const stats = node_fs_1.default.statSync(src);
-    if (uid === 0) {
-        uid = stats.uid;
-    }
-    if (gid === 0) {
-        gid = stats.gid;
-    }
+    // `0` is a valid uid/gid, so only nullish values mean "preserve current owner".
+    const nextUid = uid ?? stats.uid;
+    const nextGid = gid ?? stats.gid;
     if (stats.isDirectory()) {
         const list = node_fs_1.default.readdirSync(src);
         for (const loc of list) {
-            chownSync(node_path_1.default.join(src, loc), uid, gid);
+            chownSync(node_path_1.default.join(src, loc), nextUid, nextGid);
         }
     }
-    node_fs_1.default.chownSync(src, uid, gid);
+    node_fs_1.default.chownSync(src, nextUid, nextGid);
 }
 /**
  * Synchronously copies a file system node into the target directory.
  */
-function copySync(src, dir, umask) {
+function copySync(src, dir, options) {
     const stat = node_fs_1.default.statSync(src);
+    const loc = node_path_1.default.basename(src);
+    const dest = node_path_1.default.join(dir, loc);
+    if (dest === src) {
+        throw new Error(`Source and destination are identical: ${src}`);
+    }
+    if (options.filter && options.filter(src, dest) === false) {
+        return;
+    }
     if (stat.isDirectory()) {
         const list = node_fs_1.default.readdirSync(src);
-        const loc = node_path_1.default.basename(src);
-        const mode = 0o777 & ~umask;
-        dir = node_path_1.default.join(dir, loc);
-        node_fs_1.default.mkdirSync(dir, { mode });
+        const mode = 0o777 & ~options.umask;
+        // Overwrite is implemented as replace-before-copy to support directory targets.
+        if (options.overwrite && node_fs_1.default.existsSync(dest)) {
+            removeSync(dest);
+        }
+        node_fs_1.default.mkdirSync(dest, { mode });
         for (const loc of list) {
-            copySync(node_path_1.default.join(src, loc), dir, umask);
+            copySync(node_path_1.default.join(src, loc), dest, options);
         }
     }
     else {
-        const loc = node_path_1.default.basename(src);
-        const use = node_path_1.default.join(dir, loc);
-        node_fs_1.default.copyFileSync(src, use);
-        node_fs_1.default.chmodSync(use, 0o666 & ~umask);
+        // Match directory behavior by replacing the existing target before writing.
+        if (options.overwrite && node_fs_1.default.existsSync(dest)) {
+            removeSync(dest);
+        }
+        const flags = options.overwrite ? 0 : node_fs_1.default.constants.COPYFILE_EXCL;
+        node_fs_1.default.copyFileSync(src, dest, flags);
+        node_fs_1.default.chmodSync(dest, 0o666 & ~options.umask);
     }
 }
 /**
  * Synchronously removes files, directories, and symlinks without following links.
  */
 function removeSync(src) {
-    const stats = node_fs_1.default.lstatSync(src);
-    if (stats.isSymbolicLink()) {
-        node_fs_1.default.unlinkSync(src);
-        return;
-    }
-    if (stats.isDirectory()) {
-        const list = node_fs_1.default.readdirSync(src);
-        for (const loc of list) {
-            removeSync(node_path_1.default.join(src, loc));
-        }
-        node_fs_1.default.rmdirSync(src);
-    }
-    else {
-        node_fs_1.default.unlinkSync(src);
+    node_fs_1.default.rmSync(src, { recursive: true, force: false });
+}
+/**
+ * Synchronously removes all entries inside a directory while preserving it.
+ */
+function emptyDirSync(src) {
+    const list = node_fs_1.default.readdirSync(src);
+    for (const loc of list) {
+        node_fs_1.default.rmSync(node_path_1.default.join(src, loc), { recursive: true, force: false });
     }
 }
 /**

package/dist/recurse-io.d.ts

@@ -1,4 +1,9 @@
 import { NoParamCallback } from 'node:fs';
+export interface ICopyOptions {
+    umask: number;
+    overwrite: boolean;
+    filter?: (src: string, dest: string) => boolean;
+}
 /**
  * Applies chmod depth-first so directories are updated after their contents.
  */
@@ -6,15 +11,19 @@ export declare function chmod(src: string, mode: number, callback: NoParamCallba
 /**
  * Applies ownership recursively while preserving current values when uid/gid are omitted.
  */
-export declare function chown(src: string, uid: number, gid: number, callback: NoParamCallback): void;
+export declare function chown(src: string, uid: number | undefined, gid: number | undefined, callback: NoParamCallback): void;
 /**
  * Copies a file system node into the target directory, creating directories as needed.
  */
-export declare function copy(src: string, dir: string, umask: number, callback: NoParamCallback): void;
+export declare function copy(src: string, dir: string, options: ICopyOptions, callback: NoParamCallback): void;
 /**
  * Removes files, directories, and symlinks without following symbolic links.
  */
 export declare function remove(src: string, callback: NoParamCallback): void;
+/**
+ * Removes all entries inside a directory while preserving the directory itself.
+ */
+export declare function emptyDir(src: string, callback: NoParamCallback): void;
 /**
  * Creates a directory tree with the permissions derived from the provided umask.
  */

package/dist/recurse-io.js

@@ -7,13 +7,26 @@ exports.chmod = chmod;
 exports.chown = chown;
 exports.copy = copy;
 exports.remove = remove;
+exports.emptyDir = emptyDir;
 exports.mkdir = mkdir;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+function once(callback) {
+    let called = false;
+    return (err) => {
+        // Recursive branches can fail concurrently; report only the first terminal result.
+        if (called) {
+            return;
+        }
+        called = true;
+        callback(err);
+    };
+}
 /**
  * Applies chmod depth-first so directories are updated after their contents.
  */
 function chmod(src, mode, callback) {
+    callback = once(callback);
     let reduce = 0;
     node_fs_1.default.stat(src, (err, stats) => {
         if (err)
@@ -48,95 +61,153 @@ function chmod(src, mode, callback) {
  * Applies ownership recursively while preserving current values when uid/gid are omitted.
  */
 function chown(src, uid, gid, callback) {
+    callback = once(callback);
     let reduce = 0;
     node_fs_1.default.stat(src, (err, stats) => {
         if (err) {
             return callback(err);
         }
-        if (uid === 0) {
-            uid = stats.uid;
-        }
-        if (gid === 0) {
-            gid = stats.gid;
-        }
+        // `0` is a valid uid/gid, so only nullish values mean "preserve current owner".
+        const nextUid = uid ?? stats.uid;
+        const nextGid = gid ?? stats.gid;
         if (stats.isDirectory()) {
             node_fs_1.default.readdir(src, (err, list) => {
                 if (err) {
                     return callback(err);
                 }
                 if (list.length === 0) {
-                    return node_fs_1.default.chown(src, uid, gid, callback);
+                    return node_fs_1.default.chown(src, nextUid, nextGid, callback);
                 }
                 reduce = list.length;
                 for (const loc of list) {
-                    chown(node_path_1.default.join(src, loc), uid, gid, (err) => {
+                    chown(node_path_1.default.join(src, loc), nextUid, nextGid, (err) => {
                         if (err) {
                             return callback(err);
                         }
                         if (--reduce === 0) {
-                            node_fs_1.default.chown(src, uid, gid, callback);
+                            node_fs_1.default.chown(src, nextUid, nextGid, callback);
                         }
                     });
                 }
             });
         }
         else {
-            node_fs_1.default.chown(src, uid, gid, callback);
+            node_fs_1.default.chown(src, nextUid, nextGid, callback);
         }
     });
 }
 /**
  * Copies a file system node into the target directory, creating directories as needed.
  */
-function copy(src, dir, umask, callback) {
+function copy(src, dir, options, callback) {
+    callback = once(callback);
     node_fs_1.default.stat(src, (err, stat) => {
         if (err) {
             return callback(err);
         }
+        const loc = node_path_1.default.basename(src);
+        const dest = node_path_1.default.join(dir, loc);
+        if (dest === src) {
+            return callback(new Error(`Source and destination are identical: ${src}`));
+        }
+        if (options.filter && options.filter(src, dest) === false) {
+            return callback(null);
+        }
         if (stat.isDirectory()) {
             node_fs_1.default.readdir(src, (err, list) => {
                 if (err) {
                     return callback(err);
                 }
-                const loc = node_path_1.default.basename(src);
-                const destDir = node_path_1.default.join(dir, loc);
-                const mode = 0o777 & ~umask;
-                node_fs_1.default.mkdir(destDir, { mode }, (err) => {
+                const mode = 0o777 & ~options.umask;
+                const create = () => {
+                    node_fs_1.default.mkdir(dest, { mode }, (err) => {
+                        if (err) {
+                            if (err.code === 'EEXIST') {
+                                err = new Error(`Target already exists: ${dest}`);
+                            }
+                            return callback(err);
+                        }
+                        if (list.length === 0) {
+                            return callback(null);
+                        }
+                        let reduce = list.length;
+                        for (const item of list) {
+                            copy(node_path_1.default.join(src, item), dest, options, (err) => {
+                                if (err) {
+                                    return callback(err);
+                                }
+                                if (--reduce === 0) {
+                                    callback(null);
+                                }
+                            });
+                        }
+                    });
+                };
+                if (!options.overwrite) {
+                    return create();
+                }
+                // Overwrite is implemented as replace-before-copy to support directory targets.
+                node_fs_1.default.lstat(dest, (err, destStat) => {
                     if (err) {
-                        if (err.code === 'EEXIST') {
-                            err = new Error(`Target already exists: ${destDir}`);
+                        if (err.code === 'ENOENT') {
+                            return create();
                         }
                         return callback(err);
                     }
-                    if (list.length === 0) {
-                        return callback(null);
-                    }
-                    let reduce = list.length;
-                    for (const item of list) {
-                        copy(node_path_1.default.join(src, item), destDir, umask, (err) => {
+                    if (destStat.isDirectory()) {
+                        return remove(dest, (err) => {
                             if (err) {
                                 return callback(err);
                             }
-                            if (--reduce === 0) {
-                                callback(null);
-                            }
+                            create();
                         });
                     }
+                    node_fs_1.default.unlink(dest, (err) => {
+                        if (err) {
+                            return callback(err);
+                        }
+                        create();
+                    });
                 });
             });
         }
         else {
-            const loc = node_path_1.default.basename(src);
-            const dest = node_path_1.default.join(dir, loc);
-            const mode = 0o666 & ~umask;
-            const readStream = node_fs_1.default.createReadStream(src);
-            const writeStream = node_fs_1.default.createWriteStream(dest, { mode });
-            readStream.on('error', callback);
-            writeStream.on('error', callback);
-            writeStream.on('close', () => {
-                node_fs_1.default.chmod(dest, mode, callback);
+            const mode = 0o666 & ~options.umask;
+            const write = () => {
+                const flags = options.overwrite ? 0 : node_fs_1.default.constants.COPYFILE_EXCL;
+                node_fs_1.default.copyFile(src, dest, flags, (err) => {
+                    if (err) {
+                        return callback(err);
+                    }
+                    node_fs_1.default.chmod(dest, mode, callback);
+                });
+            };
+            if (!options.overwrite) {
+                return write();
+            }
+            // Match directory behavior by replacing the existing target before writing.
+            node_fs_1.default.lstat(dest, (err, destStat) => {
+                if (err) {
+                    if (err.code === 'ENOENT') {
+                        return write();
+                    }
+                    return callback(err);
+                }
+                if (destStat.isDirectory()) {
+                    return remove(dest, (err) => {
+                        if (err) {
+                            return callback(err);
+                        }
+                        write();
+                    });
+                }
+                node_fs_1.default.unlink(dest, (err) => {
+                    if (err) {
+                        return callback(err);
+                    }
+                    write();
+                });
             });
-            readStream.pipe(writeStream);
         }
     });
 }
@@ -144,37 +215,31 @@ function copy(src, dir, umask, callback) {
  * Removes files, directories, and symlinks without following symbolic links.
  */
 function remove(src, callback) {
-    node_fs_1.default.lstat(src, (err, stat) => {
+    node_fs_1.default.rm(src, { recursive: true, force: false }, once(callback));
+}
+/**
+ * Removes all entries inside a directory while preserving the directory itself.
+ */
+function emptyDir(src, callback) {
+    callback = once(callback);
+    node_fs_1.default.readdir(src, (err, list) => {
         if (err) {
             return callback(err);
         }
-        if (stat.isSymbolicLink()) {
-            return node_fs_1.default.unlink(src, callback);
+        if (list.length === 0) {
+            return callback(null);
         }
-        if (stat.isDirectory()) {
-            node_fs_1.default.readdir(src, (err, list) => {
+        let reduce = list.length;
+        for (const loc of list) {
+            node_fs_1.default.rm(node_path_1.default.join(src, loc), { recursive: true, force: false }, (err) => {
                 if (err) {
                     return callback(err);
                 }
-                if (list.length === 0) {
-                    return node_fs_1.default.rmdir(src, callback);
-                }
-                let reduce = list.length;
-                for (const loc of list) {
-                    remove(node_path_1.default.join(src, loc), (err) => {
-                        if (err) {
-                            return callback(err);
-                        }
-                        if (--reduce === 0) {
-                            node_fs_1.default.rmdir(src, callback);
-                        }
-                    });
+                if (--reduce === 0) {
+                    callback(null);
                 }
             });
         }
-        else {
-            node_fs_1.default.unlink(src, callback);
-        }
     });
 }
 /**

package/dist/suite.test.js

@@ -31,7 +31,7 @@ const distDir = node_path_1.default.resolve(__dirname);
 // The runner skips itself and forwards the rest to Node's native test harness.
 const testFiles = collectTestFiles(distDir).filter((file) => file !== __filename);
 if (!testFiles.length) {
-    console.warn("⚠️  No test files found in dist/");
+    console.warn("No test files found in dist/");
     process.exit(0);
 }
 const { status } = (0, node_child_process_1.spawnSync)(process.execPath, ['--test', ...testFiles], {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pwd-fs",
-  "version": "3.3.5",
+  "version": "3.5.0",
   "description": "Path-aware file system utilities with scoped working directories and recursive operations",
   "keywords": [
     "umask",
@@ -31,16 +31,11 @@
     "url": "https://github.com/woodger/pwd-fs/issues"
   },
   "engines": {
-    "node": ">=13.2.0"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
+    "node": ">=18"
   },
+  "packageManager": "yarn@1.22.22",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "readme.md",
@@ -53,12 +48,12 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/chance": "^1.1.7",
-    "@types/node": "^24.5.1",
+    "@types/chance": "^1.1.8",
+    "@types/node": "^25.6.2",
     "chance": "^1.1.13",
-    "eslint": "^10.1.0",
-    "globals": "^17.4.0",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.57.2"
+    "eslint": "^10.3.0",
+    "globals": "^17.6.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.2"
   }
 }