pwd-fs 3.4.0 → 3.5.0

package/dist/recurse-io.d.ts

@@ -11,7 +11,7 @@ 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.
  */

package/dist/recurse-io.js

@@ -11,10 +11,22 @@ 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)
@@ -49,40 +61,38 @@ 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);
         }
     });
 }
@@ -90,6 +100,7 @@ function chown(src, uid, gid, callback) {
  * Copies a file system node into the target directory, creating directories as needed.
  */
 function copy(src, dir, options, callback) {
+    callback = once(callback);
     node_fs_1.default.stat(src, (err, stat) => {
         if (err) {
             return callback(err);
@@ -135,6 +146,7 @@ function copy(src, dir, options, callback) {
                 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 === 'ENOENT') {
@@ -162,18 +174,18 @@ function copy(src, dir, options, callback) {
         else {
             const mode = 0o666 & ~options.umask;
             const write = () => {
-                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', () => {
+                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);
                 });
-                readStream.pipe(writeStream);
             };
             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') {
@@ -203,43 +215,13 @@ function copy(src, dir, options, callback) {
  * Removes files, directories, and symlinks without following symbolic links.
  */
 function remove(src, callback) {
-    node_fs_1.default.lstat(src, (err, stat) => {
-        if (err) {
-            return callback(err);
-        }
-        if (stat.isSymbolicLink()) {
-            return node_fs_1.default.unlink(src, callback);
-        }
-        if (stat.isDirectory()) {
-            node_fs_1.default.readdir(src, (err, list) => {
-                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);
-                        }
-                    });
-                }
-            });
-        }
-        else {
-            node_fs_1.default.unlink(src, callback);
-        }
-    });
+    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);
@@ -249,7 +231,7 @@ function emptyDir(src, callback) {
         }
         let reduce = list.length;
         for (const loc of list) {
-            remove(node_path_1.default.join(src, loc), (err) => {
+            node_fs_1.default.rm(node_path_1.default.join(src, loc), { recursive: true, force: false }, (err) => {
                 if (err) {
                     return callback(err);
                 }

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.4.0",
+  "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"
   }
 }

package/readme.md

@@ -12,11 +12,11 @@ It provides:
 - matching synchronous variants via `{ sync: true }`
 - recursive helpers for copy, remove, chmod, chown, and mkdir
 
-All relative paths are resolved against `pfs.pwd`.
+Relative paths are resolved against `pfs.pwd`. Absolute paths are used as-is, so `pfs.pwd` is a convenience base path, not a sandbox.
 
 ## Why Use It
 
-Use `pwd-fs` when you want file system operations to be scoped to a specific working directory without manually calling `path.resolve()` before every operation.
+Use `pwd-fs` when you want file system operations to be rooted at a specific working directory without manually calling `path.resolve()` before every operation.
 
 It is especially useful for:
 
@@ -40,6 +40,7 @@ npm install pwd-fs
 - [API](#api)
 - [`new PoweredFileSystem(pwd?)`](#new-poweredfilesystempwd)
 - [`pfs.pwd`](#pfspwd)
+- [`pfs.resolve(src)`](#pfsresolvesrc)
 - [`pfs.constants`](#pfsconstants)
 - [`PoweredFileSystem.bitmask(mode)`](#poweredfilesystembitmaskmode)
 - [`pfs.test(src, options?)`](#pfstestsrc-options)
@@ -77,7 +78,7 @@ await pfs.mkdir('./own/project'); // recursively create the directory
 
 ## Common Recipes
 
-### Work inside a scoped directory
+### Work inside a project directory
 
 ```ts
 import { PoweredFileSystem } from 'pwd-fs';
@@ -137,7 +138,7 @@ if (await pfs.test('./tmp')) {
 
 ## Compatibility
 
-- package `engines`: Node.js `>=13.2.0`
+- package `engines`: Node.js `>=18`
 - module format: CommonJS package output with TypeScript declarations
 - platform notes:
   - `chown()` is effectively a no-op on Windows apart from path validation
@@ -158,7 +159,7 @@ import PoweredFileSystem, { pfs, bitmask } from 'pwd-fs';
 
 ### `new PoweredFileSystem(pwd?)`
 
-Creates a new instance rooted at `pwd`.
+Creates a new instance with `pwd` as the base directory for relative paths.
 
 - `pwd?: string`
 - default: `process.cwd()`
@@ -171,7 +172,22 @@ const pfs = new PoweredFileSystem('./workspace');
 
 ### `pfs.pwd`
 
-Absolute base directory used to resolve all relative paths.
+Absolute base directory used to resolve relative paths.
+
+### `pfs.resolve(src)`
+
+Resolves `src` against `pfs.pwd`.
+
+```ts
+const pfs = new PoweredFileSystem('/workspace/project');
+const file = pfs.resolve('./src/index.ts');
+```
+
+Absolute paths are preserved:
+
+```ts
+pfs.resolve('/tmp/outside.txt'); // '/tmp/outside.txt'
+```
 
 ### `pfs.constants`
 
@@ -506,7 +522,8 @@ Typical cases:
 - `emptyDir()` fails when the target is not a directory
 - `write()` fails when the target path points to a directory
 - `copy()` fails when the source does not exist
-- `copy()` also fails when the destination already contains an entry with the same basename as the source, unless `overwrite: true` is used
+- `copy()` fails when the destination already contains an entry with the same basename as the source, unless `overwrite: true` is used
+- `copy()` fails when a directory is copied into itself
 - `symlink()` fails when the destination already exists
 - `mkdir()` accepts an existing directory, but fails when a path segment is a file
 
@@ -535,7 +552,8 @@ Effective permissions:
 
 ## Notes
 
-- Relative paths are always resolved against `pfs.pwd`
+- Relative paths are resolved against `pfs.pwd`
+- Absolute paths are not constrained by `pfs.pwd`
 - `stat()` returns `lstat()` data
 - `remove()` does not follow symbolic links
 - `append()` is kept for backward compatibility and is deprecated
@@ -562,9 +580,10 @@ Prefer native `node:fs` APIs directly when you need:
 ## Development
 
 ```bash
-npm install
-npm run build
-npm test
+yarn install --frozen-lockfile
+yarn lint
+yarn build
+yarn test
 ```
 
 ## License