pwd-fs 3.3.5 → 3.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { PoweredFileSystem } from './powered-file-system';
 /**
- * Default file system instance rooted at the current working directory.
+ * Default file system instance using the current working directory as its base.
  */
 export declare const pfs: PoweredFileSystem;
 export default PoweredFileSystem;

package/dist/index.js

@@ -17,7 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pfs = void 0;
 const powered_file_system_1 = require("./powered-file-system");
 /**
- * Default file system instance rooted at the current working directory.
+ * Default file system instance using the current working directory as its base.
  */
 exports.pfs = new powered_file_system_1.PoweredFileSystem();
 exports.default = powered_file_system_1.PoweredFileSystem;

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

@@ -1,9 +1,12 @@
-import type { PoweredFileSystem } from '../powered-file-system';
+import type { AsyncOption, MaybeSyncOption, PoweredFileSystem, SyncOption } from '../powered-file-system';
+type AppendOptions = {
+    encoding?: BufferEncoding | null;
+    umask?: number;
+};
 /**
  * Backward-compatible append wrapper implemented on top of `write()`.
  */
-export declare function append<T extends boolean = false>(this: PoweredFileSystem, src: string, data: Buffer | string, options?: {
-    sync?: T;
-    encoding?: BufferEncoding | null;
-    umask?: number;
-}): T extends true ? void : Promise<void>;
+export declare function append(this: PoweredFileSystem, src: string, data: Buffer | string, options: SyncOption & AppendOptions): void;
+export declare function append(this: PoweredFileSystem, src: string, data: Buffer | string, options?: AsyncOption & AppendOptions): Promise<void>;
+export declare function append(this: PoweredFileSystem, src: string, data: Buffer | string, options?: MaybeSyncOption & AppendOptions): void | Promise<void>;
+export {};

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

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.append = append;
-/**
- * Backward-compatible append wrapper implemented on top of `write()`.
- */
 function append(src, data, options) {
     const { sync = false, encoding = 'utf8', umask = 0o000 } = options ?? {};
-    return this.write(src, data, { sync, encoding, umask, flag: 'a' });
+    if (sync) {
+        return this.write(src, data, { sync: true, encoding, umask, flag: 'a' });
+    }
+    return this.write(src, data, { encoding, umask, flag: 'a' });
 }

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

@@ -1,7 +1,7 @@
-import type { PoweredFileSystem } from '../powered-file-system';
+import type { AsyncOption, MaybeSyncOption, PoweredFileSystem, SyncOption } from '../powered-file-system';
 /**
  * Resolves the target path and delegates recursive mode updates.
  */
-export declare function chmod<T extends boolean = false>(this: PoweredFileSystem, src: string, mode: number, options?: {
-    sync?: T;
-}): T extends true ? void : Promise<void>;
+export declare function chmod(this: PoweredFileSystem, src: string, mode: number, options: SyncOption): void;
+export declare function chmod(this: PoweredFileSystem, src: string, mode: number, options?: AsyncOption): Promise<void>;
+export declare function chmod(this: PoweredFileSystem, src: string, mode: number, options?: MaybeSyncOption): void | Promise<void>;

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

@@ -1,23 +1,22 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chmod = chmod;
-const node_path_1 = __importDefault(require("node:path"));
 const recurse_io_1 = require("../recurse-io");
 const recurse_io_sync_1 = require("../recurse-io-sync");
-/**
- * Resolves the target path and delegates recursive mode updates.
- */
 function chmod(src, mode, options) {
     const { sync = false } = options ?? {};
-    src = node_path_1.default.resolve(this.pwd, src);
     if (sync) {
-        (0, recurse_io_sync_1.chmodSync)(src, mode);
-        return undefined;
+        (0, recurse_io_sync_1.chmodSync)(this.resolve(src), mode);
+        return;
     }
     return new Promise((resolve, reject) => {
+        try {
+            src = this.resolve(src);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         (0, recurse_io_1.chmod)(src, mode, (err) => {
             if (err) {
                 return reject(err);

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

@@ -1,9 +1,12 @@
-import type { PoweredFileSystem } from '../powered-file-system';
+import type { AsyncOption, MaybeSyncOption, PoweredFileSystem, SyncOption } from '../powered-file-system';
 /**
  * Resolves the target path and applies recursive ownership changes where supported.
  */
-export declare function chown<T extends boolean = false>(this: PoweredFileSystem, src: string, options?: {
-    sync?: T;
+type ChownOptions = {
     uid?: number;
     gid?: number;
-}): T extends true ? void : Promise<void>;
+};
+export declare function chown(this: PoweredFileSystem, src: string, options: SyncOption & ChownOptions): void;
+export declare function chown(this: PoweredFileSystem, src: string, options?: AsyncOption & ChownOptions): Promise<void>;
+export declare function chown(this: PoweredFileSystem, src: string, options?: MaybeSyncOption & ChownOptions): void | Promise<void>;
+export {};

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

@@ -5,26 +5,29 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chown = chown;
 const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
 const recurse_io_1 = require("../recurse-io");
 const recurse_io_sync_1 = require("../recurse-io-sync");
-/**
- * Resolves the target path and applies recursive ownership changes where supported.
- */
 function chown(src, options) {
-    const { sync = false, uid = 0, gid = 0 } = options ?? {};
-    src = node_path_1.default.resolve(this.pwd, src);
+    const { sync = false, uid, gid } = options ?? {};
     if (sync) {
+        src = this.resolve(src);
         if (process.platform === 'win32') {
             // Windows does not expose POSIX ownership changes; keep existence checks consistent.
             node_fs_1.default.lstatSync(src);
-            return undefined;
+            return;
         }
         (0, recurse_io_sync_1.chownSync)(src, uid, gid);
-        return undefined;
+        return;
     }
     if (process.platform === 'win32') {
         return new Promise((resolve, reject) => {
+            try {
+                src = this.resolve(src);
+            }
+            catch (err) {
+                reject(err);
+                return;
+            }
             // Match Unix behavior by validating the path even when ownership cannot be changed.
             node_fs_1.default.lstat(src, (err) => {
                 if (err) {
@@ -35,6 +38,13 @@ function chown(src, options) {
         });
     }
     return new Promise((resolve, reject) => {
+        try {
+            src = this.resolve(src);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         (0, recurse_io_1.chown)(src, uid, gid, (err) => {
             if (err) {
                 return reject(err);

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

@@ -1,8 +1,13 @@
-import type { PoweredFileSystem } from '../powered-file-system';
+import type { AsyncOption, CopyFilter, MaybeSyncOption, PoweredFileSystem, SyncOption } from '../powered-file-system';
+type CopyOptions = {
+    umask?: number;
+    overwrite?: boolean;
+    filter?: CopyFilter;
+};
 /**
  * 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;
-}): T extends true ? void : Promise<void>;
+export declare function copy(this: PoweredFileSystem, src: string, dest: string, options: SyncOption & CopyOptions): void;
+export declare function copy(this: PoweredFileSystem, src: string, dest: string, options?: AsyncOption & CopyOptions): Promise<void>;
+export declare function copy(this: PoweredFileSystem, src: string, dest: string, options?: MaybeSyncOption & CopyOptions): void | Promise<void>;
+export {};

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

@@ -1,25 +1,25 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.copy = copy;
-const node_path_1 = __importDefault(require("node:path"));
 const recurse_io_1 = require("../recurse-io");
 const recurse_io_sync_1 = require("../recurse-io-sync");
-/**
- * Resolves source and destination paths before delegating recursive copy work.
- */
 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 = filter ? { umask, overwrite, filter } : { umask, overwrite };
     if (sync) {
-        (0, recurse_io_sync_1.copySync)(src, dest, umask);
-        return undefined;
+        (0, recurse_io_sync_1.copySync)(this.resolve(src), this.resolve(dest), copyOptions);
+        return;
     }
     return new Promise((resolve, reject) => {
-        (0, recurse_io_1.copy)(src, dest, umask, (err) => {
+        try {
+            src = this.resolve(src);
+            dest = this.resolve(dest);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        (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 { AsyncOption, MaybeSyncOption, PoweredFileSystem, SyncOption } from '../powered-file-system';
+/**
+ * Removes directory contents while preserving the directory itself.
+ */
+export declare function emptyDir(this: PoweredFileSystem, src: string, options: SyncOption): void;
+export declare function emptyDir(this: PoweredFileSystem, src: string, options?: AsyncOption): Promise<void>;
+export declare function emptyDir(this: PoweredFileSystem, src: string, options?: MaybeSyncOption): void | Promise<void>;

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

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyDir = emptyDir;
+const recurse_io_1 = require("../recurse-io");
+const recurse_io_sync_1 = require("../recurse-io-sync");
+function emptyDir(src, options) {
+    const { sync = false } = options ?? {};
+    if (sync) {
+        (0, recurse_io_sync_1.emptyDirSync)(this.resolve(src));
+        return;
+    }
+    return new Promise((resolve, reject) => {
+        try {
+            src = this.resolve(src);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        (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/mkdir.d.ts

@@ -1,8 +1,11 @@
-import type { PoweredFileSystem } from '../powered-file-system';
+import type { AsyncOption, MaybeSyncOption, PoweredFileSystem, SyncOption } from '../powered-file-system';
+type MkdirOptions = {
+    umask?: number;
+};
 /**
- * Creates directories relative to the instance root.
+ * Creates directories relative to the instance base path.
  */
-export declare function mkdir<T extends boolean = false>(this: PoweredFileSystem, dir: string, options?: {
-    sync?: T;
-    umask?: number;
-}): T extends true ? void : Promise<void>;
+export declare function mkdir(this: PoweredFileSystem, dir: string, options: SyncOption & MkdirOptions): void;
+export declare function mkdir(this: PoweredFileSystem, dir: string, options?: AsyncOption & MkdirOptions): Promise<void>;
+export declare function mkdir(this: PoweredFileSystem, dir: string, options?: MaybeSyncOption & MkdirOptions): void | Promise<void>;
+export {};

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

@@ -1,23 +1,22 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mkdir = mkdir;
-const node_path_1 = __importDefault(require("node:path"));
 const recurse_io_1 = require("../recurse-io");
 const recurse_io_sync_1 = require("../recurse-io-sync");
-/**
- * Creates directories relative to the instance root.
- */
 function mkdir(dir, options) {
     const { sync = false, umask = 0o000 } = options ?? {};
-    dir = node_path_1.default.resolve(this.pwd, dir);
     if (sync) {
-        (0, recurse_io_sync_1.mkdirSync)(dir, umask);
-        return undefined;
+        (0, recurse_io_sync_1.mkdirSync)(this.resolve(dir), umask);
+        return;
     }
     return new Promise((resolve, reject) => {
+        try {
+            dir = this.resolve(dir);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         (0, recurse_io_1.mkdir)(dir, umask, (err) => {
             if (err) {
                 return reject(err);

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

@@ -1,9 +1,13 @@
-import type { Flag, PoweredFileSystem } from '../powered-file-system';
+import type { AsyncOption, MaybeSyncOption, PoweredFileSystem, ReadOptions, SyncOption } from '../powered-file-system';
 /**
  * Reads a file relative to `pwd` and preserves Buffer mode when `encoding` is `null`.
  */
-export declare function read<T extends boolean = false>(this: PoweredFileSystem, src: string, options?: {
-    sync?: T;
-    encoding?: BufferEncoding | null;
-    flag?: Flag;
-}): T extends true ? string | Buffer : Promise<string | Buffer>;
+export declare function read(this: PoweredFileSystem, src: string, options: SyncOption & ReadOptions<true, null> & {
+    encoding: null;
+}): Buffer;
+export declare function read(this: PoweredFileSystem, src: string, options: SyncOption & ReadOptions<true, BufferEncoding>): string;
+export declare function read(this: PoweredFileSystem, src: string, options: AsyncOption & ReadOptions<false, null> & {
+    encoding: null;
+}): Promise<Buffer>;
+export declare function read(this: PoweredFileSystem, src: string, options?: AsyncOption & ReadOptions<false, BufferEncoding>): Promise<string>;
+export declare function read(this: PoweredFileSystem, src: string, options?: MaybeSyncOption & ReadOptions<boolean, BufferEncoding | null>): string | Buffer | Promise<string | Buffer>;

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

@@ -5,20 +5,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.read = read;
 const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-/**
- * Reads a file relative to `pwd` and preserves Buffer mode when `encoding` is `null`.
- */
 function read(src, options) {
     const { sync = false, encoding = 'utf8', flag = 'r' } = options ?? {};
-    const resolved = node_path_1.default.resolve(this.pwd, src);
     if (sync) {
+        const resolved = this.resolve(src);
         if (encoding === null) {
             return node_fs_1.default.readFileSync(resolved, { encoding: null, flag });
         }
         return node_fs_1.default.readFileSync(resolved, { encoding, flag });
     }
     return new Promise((resolve, reject) => {
+        let resolved;
+        try {
+            resolved = this.resolve(src);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         node_fs_1.default.readFile(resolved, { encoding, flag }, (err, raw) => {
             if (err) {
                 return reject(err);

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

@@ -1,8 +1,13 @@
-import type { PoweredFileSystem } from '../powered-file-system';
+import type { AsyncOption, MaybeSyncOption, PoweredFileSystem, ReaddirOptions, SyncOption } from '../powered-file-system';
 /**
- * Lists directory entries relative to the current instance root.
+ * Lists directory entries relative to the instance base path.
  */
-export declare function readdir<T extends boolean = false>(this: PoweredFileSystem, dir: string, options?: {
-    sync?: T;
-    encoding?: BufferEncoding | null;
-}): T extends true ? string[] : Promise<string[]>;
+export declare function readdir(this: PoweredFileSystem, dir: string, options: SyncOption & ReaddirOptions<true, null> & {
+    encoding: null;
+}): Buffer[];
+export declare function readdir(this: PoweredFileSystem, dir: string, options: SyncOption & ReaddirOptions<true, BufferEncoding>): string[];
+export declare function readdir(this: PoweredFileSystem, dir: string, options: AsyncOption & ReaddirOptions<false, null> & {
+    encoding: null;
+}): Promise<Buffer[]>;
+export declare function readdir(this: PoweredFileSystem, dir: string, options?: AsyncOption & ReaddirOptions<false, BufferEncoding>): Promise<string[]>;
+export declare function readdir(this: PoweredFileSystem, dir: string, options?: MaybeSyncOption & ReaddirOptions<boolean, BufferEncoding | null>): string[] | Buffer[] | Promise<string[] | Buffer[]>;

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

@@ -5,17 +5,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readdir = readdir;
 const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-/**
- * Lists directory entries relative to the current instance root.
- */
 function readdir(dir, options) {
     const { sync = false, encoding = 'utf8' } = options ?? {};
-    dir = node_path_1.default.resolve(this.pwd, dir);
     if (sync) {
-        return node_fs_1.default.readdirSync(dir, { encoding });
+        return node_fs_1.default.readdirSync(this.resolve(dir), { encoding });
     }
     return new Promise((resolve, reject) => {
+        try {
+            dir = this.resolve(dir);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         node_fs_1.default.readdir(dir, { encoding }, (err, list) => {
             if (err) {
                 return reject(err);

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

@@ -0,0 +1,13 @@
+import type { AsyncOption, MaybeSyncOption, PoweredFileSystem, SyncOption } from '../powered-file-system';
+/**
+ * Reads the target path stored in a symbolic link.
+ */
+export declare function readlink(this: PoweredFileSystem, src: string, options: SyncOption & {
+    encoding?: BufferEncoding;
+}): string;
+export declare function readlink(this: PoweredFileSystem, src: string, options?: AsyncOption & {
+    encoding?: BufferEncoding;
+}): Promise<string>;
+export declare function readlink(this: PoweredFileSystem, src: string, options?: MaybeSyncOption & {
+    encoding?: BufferEncoding;
+}): string | Promise<string>;

package/dist/powered-file-system/readlink.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.readlink = readlink;
+const node_fs_1 = __importDefault(require("node:fs"));
+function readlink(src, options) {
+    const { sync = false, encoding = 'utf8' } = options ?? {};
+    if (sync) {
+        return node_fs_1.default.readlinkSync(this.resolve(src), { encoding });
+    }
+    return new Promise((resolve, reject) => {
+        try {
+            src = this.resolve(src);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        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'));
+    });
+});