pwd-fs 3.3.5 → 3.4.0

package/dist/powered-file-system/copy.d.ts

@@ -1,8 +1,10 @@
-import type { PoweredFileSystem } from '../powered-file-system';
+import type { CopyFilter, PoweredFileSystem } from '../powered-file-system';
 /**
  * Resolves source and destination paths before delegating recursive copy work.
  */
 export declare function copy<T extends boolean = false>(this: PoweredFileSystem, src: string, dest: string, options?: {
     sync?: T;
     umask?: number;
+    overwrite?: boolean;
+    filter?: CopyFilter;
 }): T extends true ? void : Promise<void>;

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

@@ -13,13 +13,14 @@ const recurse_io_sync_1 = require("../recurse-io-sync");
 function copy(src, dest, options) {
     src = node_path_1.default.resolve(this.pwd, src);
     dest = node_path_1.default.resolve(this.pwd, dest);
-    const { sync = false, umask = 0o000 } = options ?? {};
+    const { sync = false, umask = 0o000, overwrite = false, filter } = options ?? {};
+    const copyOptions = { umask, overwrite, filter };
     if (sync) {
-        (0, recurse_io_sync_1.copySync)(src, dest, umask);
+        (0, recurse_io_sync_1.copySync)(src, dest, copyOptions);
         return undefined;
     }
     return new Promise((resolve, reject) => {
-        (0, recurse_io_1.copy)(src, dest, umask, (err) => {
+        (0, recurse_io_1.copy)(src, dest, copyOptions, (err) => {
             if (err) {
                 return reject(err);
             }

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

@@ -50,6 +50,28 @@ const test_utils_1 = require("../test-utils");
             await index_1.pfs.copy(tmpDir, node_path_1.default.dirname(tmpDir));
         });
     });
+    (0, node_test_1.it)('Positive: Overwrite should replace an existing target file', async () => {
+        node_fs_1.default.writeFileSync(node_path_1.default.join(tmpDir, 'digest', 'tings.txt'), 'old');
+        await index_1.pfs.copy(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'digest'), {
+            overwrite: true
+        });
+        const content = node_fs_1.default.readFileSync(node_path_1.default.join(tmpDir, 'digest', 'tings.txt'), 'utf8');
+        (0, node_assert_1.default)(content !== 'old');
+    });
+    (0, node_test_1.it)('Positive: Filter should skip matching entries', async () => {
+        const destRoot = (0, test_utils_1.createTmpDir)();
+        try {
+            await index_1.pfs.copy(tmpDir, destRoot, {
+                overwrite: true,
+                filter: (src) => node_path_1.default.basename(src) !== 'tings.txt'
+            });
+            (0, node_assert_1.default)(node_fs_1.default.existsSync(node_path_1.default.join(destRoot, node_path_1.default.basename(tmpDir), 'digest')));
+            (0, node_assert_1.default)(node_fs_1.default.existsSync(node_path_1.default.join(destRoot, node_path_1.default.basename(tmpDir), 'tings.txt')) === false);
+        }
+        finally {
+            (0, test_utils_1.restore)(destRoot);
+        }
+    });
     (0, node_test_1.it)('[sync] Positive: Copying a file', () => {
         index_1.pfs.copy(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'digest'), {
             sync: true
@@ -79,4 +101,28 @@ const test_utils_1 = require("../test-utils");
             });
         });
     });
+    (0, node_test_1.it)('[sync] Positive: Overwrite should replace an existing target file', () => {
+        node_fs_1.default.writeFileSync(node_path_1.default.join(tmpDir, 'digest', 'tings.txt'), 'old');
+        index_1.pfs.copy(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'digest'), {
+            sync: true,
+            overwrite: true
+        });
+        const content = node_fs_1.default.readFileSync(node_path_1.default.join(tmpDir, 'digest', 'tings.txt'), 'utf8');
+        (0, node_assert_1.default)(content !== 'old');
+    });
+    (0, node_test_1.it)('[sync] Positive: Filter should skip matching entries', () => {
+        const destRoot = (0, test_utils_1.createTmpDir)();
+        try {
+            index_1.pfs.copy(tmpDir, destRoot, {
+                sync: true,
+                overwrite: true,
+                filter: (src) => node_path_1.default.basename(src) !== 'tings.txt'
+            });
+            (0, node_assert_1.default)(node_fs_1.default.existsSync(node_path_1.default.join(destRoot, node_path_1.default.basename(tmpDir), 'digest')));
+            (0, node_assert_1.default)(node_fs_1.default.existsSync(node_path_1.default.join(destRoot, node_path_1.default.basename(tmpDir), 'tings.txt')) === false);
+        }
+        finally {
+            (0, test_utils_1.restore)(destRoot);
+        }
+    });
 });

package/dist/powered-file-system/empty-dir.d.ts

@@ -0,0 +1,7 @@
+import type { PoweredFileSystem } from '../powered-file-system';
+/**
+ * Removes directory contents while preserving the directory itself.
+ */
+export declare function emptyDir<T extends boolean = false>(this: PoweredFileSystem, src: string, options?: {
+    sync?: T;
+}): T extends true ? void : Promise<void>;

package/dist/powered-file-system/empty-dir.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyDir = emptyDir;
+const node_path_1 = __importDefault(require("node:path"));
+const recurse_io_1 = require("../recurse-io");
+const recurse_io_sync_1 = require("../recurse-io-sync");
+/**
+ * Removes directory contents while preserving the directory itself.
+ */
+function emptyDir(src, options) {
+    src = node_path_1.default.resolve(this.pwd, src);
+    const { sync = false } = options ?? {};
+    if (sync) {
+        (0, recurse_io_sync_1.emptyDirSync)(src);
+        return undefined;
+    }
+    return new Promise((resolve, reject) => {
+        (0, recurse_io_1.emptyDir)(src, (err) => {
+            if (err) {
+                return reject(err);
+            }
+            resolve();
+        });
+    });
+}

package/dist/powered-file-system/empty-dir.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const chance_1 = __importDefault(require("chance"));
+const node_test_1 = require("node:test");
+const index_1 = require("../index");
+const test_utils_1 = require("../test-utils");
+/**
+ * Verifies directory cleanup while preserving the directory itself.
+ */
+(0, node_test_1.describe)('emptyDir(src [, options])', () => {
+    const chance = new chance_1.default();
+    let tmpDir = '';
+    (0, node_test_1.beforeEach)(() => {
+        tmpDir = (0, test_utils_1.createTmpDir)();
+        const frame = {
+            [node_path_1.default.join(tmpDir, 'tings.txt')]: {
+                type: 'file',
+                data: chance.string()
+            },
+            [node_path_1.default.join(tmpDir, 'digest')]: { type: 'directory' },
+            [node_path_1.default.join(tmpDir, 'digest', 'nested.txt')]: {
+                type: 'file',
+                data: chance.string()
+            }
+        };
+        (0, test_utils_1.fmock)(frame);
+    });
+    (0, node_test_1.afterEach)(() => {
+        (0, test_utils_1.restore)(tmpDir);
+    });
+    (0, node_test_1.it)('Positive: Removes all directory contents but preserves the directory', async () => {
+        await index_1.pfs.emptyDir(tmpDir);
+        (0, node_assert_1.default)(node_fs_1.default.existsSync(tmpDir));
+        node_assert_1.default.deepStrictEqual(node_fs_1.default.readdirSync(tmpDir), []);
+    });
+    (0, node_test_1.it)('Negative: Throw if resource is not directory', async () => {
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.emptyDir(node_path_1.default.join(tmpDir, 'tings.txt'));
+        });
+    });
+    (0, node_test_1.it)('[sync] Positive: Removes all directory contents but preserves the directory', () => {
+        index_1.pfs.emptyDir(tmpDir, {
+            sync: true
+        });
+        (0, node_assert_1.default)(node_fs_1.default.existsSync(tmpDir));
+        node_assert_1.default.deepStrictEqual(node_fs_1.default.readdirSync(tmpDir), []);
+    });
+    (0, node_test_1.it)('[sync] Negative: Throw if resource is not directory', () => {
+        node_assert_1.default.throws(() => {
+            index_1.pfs.emptyDir(node_path_1.default.join(tmpDir, 'tings.txt'), {
+                sync: true
+            });
+        });
+    });
+});

package/dist/powered-file-system/readlink.d.ts

@@ -0,0 +1,8 @@
+import type { PoweredFileSystem } from '../powered-file-system';
+/**
+ * Reads the target path stored in a symbolic link.
+ */
+export declare function readlink<T extends boolean = false>(this: PoweredFileSystem, src: string, options?: {
+    sync?: T;
+    encoding?: BufferEncoding;
+}): T extends true ? string : Promise<string>;

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

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readlink = readlink;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Reads the target path stored in a symbolic link.
+ */
+function readlink(src, options) {
+    src = node_path_1.default.resolve(this.pwd, src);
+    const { sync = false, encoding = 'utf8' } = options ?? {};
+    if (sync) {
+        return node_fs_1.default.readlinkSync(src, { encoding });
+    }
+    return new Promise((resolve, reject) => {
+        node_fs_1.default.readlink(src, { encoding }, (err, resolved) => {
+            if (err) {
+                return reject(err);
+            }
+            resolve(resolved);
+        });
+    });
+}

package/dist/powered-file-system/readlink.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_path_1 = __importDefault(require("node:path"));
+const chance_1 = __importDefault(require("chance"));
+const node_test_1 = require("node:test");
+const index_1 = require("../index");
+const test_utils_1 = require("../test-utils");
+/**
+ * Verifies symbolic link target resolution without dereferencing it.
+ */
+(0, node_test_1.describe)('readlink(src [, options])', () => {
+    const chance = new chance_1.default();
+    let tmpDir = '';
+    (0, node_test_1.beforeEach)(() => {
+        tmpDir = (0, test_utils_1.createTmpDir)();
+        (0, test_utils_1.fmock)({
+            [node_path_1.default.join(tmpDir, 'tings.txt')]: {
+                type: 'file',
+                data: chance.string()
+            },
+            [node_path_1.default.join(tmpDir, 'flexapp')]: {
+                type: 'symlink',
+                target: node_path_1.default.join(tmpDir, 'tings.txt')
+            }
+        });
+    });
+    (0, node_test_1.afterEach)(() => {
+        (0, test_utils_1.restore)(tmpDir);
+    });
+    (0, node_test_1.it)('Positive: Reads the stored symlink target', async () => {
+        const target = await index_1.pfs.readlink(node_path_1.default.join(tmpDir, 'flexapp'));
+        (0, node_assert_1.default)(target === node_path_1.default.join(tmpDir, 'tings.txt'));
+    });
+    (0, node_test_1.it)('[sync] Positive: Reads the stored symlink target', () => {
+        const target = index_1.pfs.readlink(node_path_1.default.join(tmpDir, 'flexapp'), {
+            sync: true
+        });
+        (0, node_assert_1.default)(target === node_path_1.default.join(tmpDir, 'tings.txt'));
+    });
+});

package/dist/powered-file-system/realpath.d.ts

@@ -0,0 +1,8 @@
+import type { PoweredFileSystem } from '../powered-file-system';
+/**
+ * Resolves a path to its canonical absolute location.
+ */
+export declare function realpath<T extends boolean = false>(this: PoweredFileSystem, src: string, options?: {
+    sync?: T;
+    encoding?: BufferEncoding;
+}): T extends true ? string : Promise<string>;

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

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.realpath = realpath;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Resolves a path to its canonical absolute location.
+ */
+function realpath(src, options) {
+    src = node_path_1.default.resolve(this.pwd, src);
+    const { sync = false, encoding = 'utf8' } = options ?? {};
+    if (sync) {
+        return node_fs_1.default.realpathSync(src, { encoding });
+    }
+    return new Promise((resolve, reject) => {
+        node_fs_1.default.realpath(src, { encoding }, (err, resolved) => {
+            if (err) {
+                return reject(err);
+            }
+            resolve(resolved);
+        });
+    });
+}

package/dist/powered-file-system/realpath.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_path_1 = __importDefault(require("node:path"));
+const chance_1 = __importDefault(require("chance"));
+const node_test_1 = require("node:test");
+const index_1 = require("../index");
+const test_utils_1 = require("../test-utils");
+/**
+ * Verifies canonical path resolution through symbolic links.
+ */
+(0, node_test_1.describe)('realpath(src [, options])', () => {
+    const chance = new chance_1.default();
+    let tmpDir = '';
+    (0, node_test_1.beforeEach)(() => {
+        tmpDir = (0, test_utils_1.createTmpDir)();
+        (0, test_utils_1.fmock)({
+            [node_path_1.default.join(tmpDir, 'tings.txt')]: {
+                type: 'file',
+                data: chance.string()
+            },
+            [node_path_1.default.join(tmpDir, 'flexapp')]: {
+                type: 'symlink',
+                target: node_path_1.default.join(tmpDir, 'tings.txt')
+            }
+        });
+    });
+    (0, node_test_1.afterEach)(() => {
+        (0, test_utils_1.restore)(tmpDir);
+    });
+    (0, node_test_1.it)('Positive: Resolves the canonical target path', async () => {
+        const target = await index_1.pfs.realpath(node_path_1.default.join(tmpDir, 'flexapp'));
+        (0, node_assert_1.default)(target === node_path_1.default.join(tmpDir, 'tings.txt'));
+    });
+    (0, node_test_1.it)('[sync] Positive: Resolves the canonical target path', () => {
+        const target = index_1.pfs.realpath(node_path_1.default.join(tmpDir, 'flexapp'), {
+            sync: true
+        });
+        (0, node_assert_1.default)(target === node_path_1.default.join(tmpDir, 'tings.txt'));
+    });
+});

package/dist/powered-file-system.d.ts

@@ -6,6 +6,7 @@ import { bitmask } from './bitmask';
 export type Mode = keyof IConstants;
 export type Flag = Extract<fs.OpenMode, string>;
 export type Stats = fs.Stats;
+export type CopyFilter = (src: string, dest: string) => boolean;
 export * from './bitmask';
 export interface IConstants {
     e: number;
@@ -72,6 +73,8 @@ export declare class PoweredFileSystem {
     copy<T extends boolean = false>(src: string, dest: string, options?: {
         sync?: T;
         umask?: number;
+        overwrite?: boolean;
+        filter?: CopyFilter;
     }): T extends true ? void : Promise<void>;
     /**
      * Renames or moves a file system node.
@@ -85,6 +88,12 @@ export declare class PoweredFileSystem {
     remove<T extends boolean = false>(src: string, options?: {
         sync?: T;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Removes all directory entries while preserving the directory itself.
+     */
+    emptyDir<T extends boolean = false>(src: string, options?: {
+        sync?: T;
+    }): T extends true ? void : Promise<void>;
     /**
      * Reads a file relative to the current instance root.
      */
@@ -117,6 +126,20 @@ export declare class PoweredFileSystem {
         sync?: T;
         encoding?: BufferEncoding | null;
     }): T extends true ? string[] : Promise<string[]>;
+    /**
+     * Resolves the target of a symbolic link.
+     */
+    readlink<T extends boolean = false>(src: string, options?: {
+        sync?: T;
+        encoding?: BufferEncoding;
+    }): T extends true ? string : Promise<string>;
+    /**
+     * Resolves a path to its canonical absolute location.
+     */
+    realpath<T extends boolean = false>(src: string, options?: {
+        sync?: T;
+        encoding?: BufferEncoding;
+    }): T extends true ? string : Promise<string>;
     /**
      * Creates a directory tree relative to the current instance root.
      */

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");
@@ -110,6 +113,12 @@ class PoweredFileSystem {
     remove(src, options) {
         return remove_1.remove.call(this, src, options);
     }
+    /**
+     * Removes all directory entries while preserving the directory itself.
+     */
+    emptyDir(src, options) {
+        return empty_dir_1.emptyDir.call(this, src, options);
+    }
     /**
      * Reads a file relative to the current instance root.
      */
@@ -134,6 +143,18 @@ class PoweredFileSystem {
     readdir(dir, options) {
         return readdir_1.readdir.call(this, dir, options);
     }
+    /**
+     * Resolves the target of a symbolic link.
+     */
+    readlink(src, options) {
+        return readlink_1.readlink.call(this, src, options);
+    }
+    /**
+     * Resolves a path to its canonical absolute location.
+     */
+    realpath(src, options) {
+        return realpath_1.realpath.call(this, src, options);
+    }
     /**
      * Creates a directory tree relative to the current instance root.
      */

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

@@ -1,3 +1,4 @@
+import type { ICopyOptions } from './recurse-io';
 /**
  * Synchronous counterpart of the recursive chmod implementation.
  */
@@ -9,11 +10,15 @@ export declare function chownSync(src: string, uid: number, gid: number): 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"));
@@ -45,23 +46,33 @@ function chownSync(src, uid, gid) {
 /**
  * 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;
+        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);
+        if (options.overwrite && node_fs_1.default.existsSync(dest)) {
+            removeSync(dest);
+        }
+        node_fs_1.default.copyFileSync(src, dest);
+        node_fs_1.default.chmodSync(dest, 0o666 & ~options.umask);
     }
 }
 /**
@@ -84,6 +95,15 @@ function removeSync(src) {
         node_fs_1.default.unlinkSync(src);
     }
 }
+/**
+ * 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) {
+        removeSync(node_path_1.default.join(src, loc));
+    }
+}
 /**
  * Synchronously creates a directory tree using permissions derived from umask.
  */

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.
  */
@@ -10,11 +15,15 @@ export declare function chown(src: string, uid: number, gid: number, callback: N
 /**
  * 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,6 +7,7 @@ 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"));
@@ -88,55 +89,113 @@ function chown(src, uid, gid, 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) {
     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();
+                }
+                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 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);
+                });
+                readStream.pipe(writeStream);
+            };
+            if (!options.overwrite) {
+                return write();
+            }
+            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);
         }
     });
 }
@@ -177,6 +236,30 @@ function remove(src, callback) {
         }
     });
 }
+/**
+ * Removes all entries inside a directory while preserving the directory itself.
+ */
+function emptyDir(src, callback) {
+    node_fs_1.default.readdir(src, (err, list) => {
+        if (err) {
+            return callback(err);
+        }
+        if (list.length === 0) {
+            return callback(null);
+        }
+        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) {
+                    callback(null);
+                }
+            });
+        }
+    });
+}
 /**
  * Creates a directory tree with the permissions derived from the provided umask.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pwd-fs",
-  "version": "3.3.5",
+  "version": "3.4.0",
   "description": "Path-aware file system utilities with scoped working directories and recursive operations",
   "keywords": [
     "umask",

package/readme.md

@@ -31,6 +31,42 @@ It is especially useful for:
 npm install pwd-fs
 ```
 
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Common Recipes](#common-recipes)
+- [Compatibility](#compatibility)
+- [Exports](#exports)
+- [API](#api)
+- [`new PoweredFileSystem(pwd?)`](#new-poweredfilesystempwd)
+- [`pfs.pwd`](#pfspwd)
+- [`pfs.constants`](#pfsconstants)
+- [`PoweredFileSystem.bitmask(mode)`](#poweredfilesystembitmaskmode)
+- [`pfs.test(src, options?)`](#pfstestsrc-options)
+- [`pfs.stat(src, options?)`](#pfsstatsrc-options)
+- [`pfs.chmod(src, mode, options?)`](#pfschmodsrc-mode-options)
+- [`pfs.chown(src, options?)`](#pfschownsrc-options)
+- [`pfs.symlink(src, dest, options?)`](#pfssymlinksrc-dest-options)
+- [`pfs.copy(src, dest, options?)`](#pfscopysrc-dest-options)
+- [`pfs.rename(src, dest, options?)`](#pfsrenamesrc-dest-options)
+- [`pfs.remove(src, options?)`](#pfsremovesrc-options)
+- [`pfs.emptyDir(src, options?)`](#pfsemptydirsrc-options)
+- [`pfs.read(src, options?)`](#pfsreadsrc-options)
+- [`pfs.write(src, data, options?)`](#pfswritesrc-data-options)
+- [`pfs.append(src, data, options?)`](#pfsappendsrc-data-options)
+- [`pfs.readdir(dir, options?)`](#pfsreaddirdir-options)
+- [`pfs.readlink(src, options?)`](#pfsreadlinksrc-options)
+- [`pfs.realpath(src, options?)`](#pfsrealpathsrc-options)
+- [`pfs.mkdir(dir, options?)`](#pfsmkdirdir-options)
+- [Sync Mode](#sync-mode)
+- [Error Behavior](#error-behavior)
+- [Umask Behavior](#umask-behavior)
+- [Notes](#notes)
+- [Platform Caveats](#platform-caveats)
+- [When To Use Native `fs`](#when-to-use-native-fs)
+- [Development](#development)
+- [License](#license)
+
 ## Quick Start
 
 ```ts
@@ -65,6 +101,19 @@ Result:
 - destination directory: `./dist`
 - created output: `./dist/assets`
 
+### Empty a directory but keep it
+
+```ts
+await pfs.emptyDir('./cache');
+```
+
+### Resolve a symlink target
+
+```ts
+const target = await pfs.readlink('./current');
+const resolved = await pfs.realpath('./current');
+```
+
 ### Append to a file
 
 ```ts
@@ -232,7 +281,12 @@ Copies `src` into the destination directory.
 copy<T extends boolean = false>(
   src: string,
   dest: string,
-  options?: { sync?: T; umask?: number }
+  options?: {
+    sync?: T;
+    umask?: number;
+    overwrite?: boolean;
+    filter?: (src: string, dest: string) => boolean;
+  }
 ): T extends true ? void : Promise<void>
 ```
 
@@ -241,6 +295,8 @@ Behavior:
 - copying a file creates `dest/<basename(src)>`
 - copying a directory creates `dest/<basename(src)>` recursively
 - the target must not already exist
+- `overwrite: true` replaces an existing target entry with the same basename
+- `filter()` can skip specific source entries during the copy
 
 ```ts
 await pfs.copy('./assets', './dist');
@@ -248,6 +304,13 @@ await pfs.copy('./assets', './dist');
 
 This creates `./dist/assets`, not a direct rename to `./dist`.
 
+```ts
+await pfs.copy('./assets', './dist', {
+  overwrite: true,
+  filter: (src) => !src.endsWith('.map')
+});
+```
+
 ### `pfs.rename(src, dest, options?)`
 
 Renames or moves a file system entry.
@@ -276,6 +339,21 @@ Behavior:
 - directories are removed recursively
 - symbolic links are unlinked without deleting the target
 
+### `pfs.emptyDir(src, options?)`
+
+Removes all entries inside a directory while preserving the directory itself.
+
+```ts
+emptyDir<T extends boolean = false>(
+  src: string,
+  options?: { sync?: T }
+): T extends true ? void : Promise<void>
+```
+
+```ts
+await pfs.emptyDir('./tmp');
+```
+
 ### `pfs.read(src, options?)`
 
 Reads a file.
@@ -363,6 +441,28 @@ readdir<T extends boolean = false>(
 
 - default `encoding`: `'utf8'`
 
+### `pfs.readlink(src, options?)`
+
+Reads the stored target path from a symbolic link.
+
+```ts
+readlink<T extends boolean = false>(
+  src: string,
+  options?: { sync?: T; encoding?: BufferEncoding }
+): T extends true ? string : Promise<string>
+```
+
+### `pfs.realpath(src, options?)`
+
+Resolves a path to its canonical absolute location.
+
+```ts
+realpath<T extends boolean = false>(
+  src: string,
+  options?: { sync?: T; encoding?: BufferEncoding }
+): T extends true ? string : Promise<string>
+```
+
 ### `pfs.mkdir(dir, options?)`
 
 Creates a directory tree recursively.
@@ -400,11 +500,13 @@ Typical cases:
 - `test()` is the exception:
   it returns `false` for inaccessible or missing paths instead of rejecting or throwing
 - `read()`, `stat()`, `readdir()`, `chmod()`, `chown()`, `rename()`, and `remove()` fail for missing paths
+- `readlink()` and `realpath()` fail for missing paths
 - `read()` fails when the target is a directory
 - `readdir()` fails when the target is not a directory
+- `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
+- `copy()` also fails when the destination already contains an entry with the same basename as the source, unless `overwrite: true` is used
 - `symlink()` fails when the destination already exists
 - `mkdir()` accepts an existing directory, but fails when a path segment is a file