pwd-fs 3.3.0 → 3.3.5

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

@@ -0,0 +1,79 @@
+"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");
+/**
+ * Ensures `stat()` preserves file type reporting for files, directories, and symlinks.
+ */
+(0, node_test_1.describe)('stat(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, 'digest')]: { type: 'directory' },
+            [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: Must return information a file', async () => {
+        const stats = await index_1.pfs.stat(node_path_1.default.join(tmpDir, 'tings.txt'));
+        (0, node_assert_1.default)(stats.isFile());
+    });
+    (0, node_test_1.it)('Positive: Must return information a directory', async () => {
+        const stats = await index_1.pfs.stat(node_path_1.default.join(tmpDir, 'digest'));
+        (0, node_assert_1.default)(stats.isDirectory());
+    });
+    (0, node_test_1.it)('Positive: Must return information a symlink', async () => {
+        const stats = await index_1.pfs.stat(node_path_1.default.join(tmpDir, 'flexapp'));
+        (0, node_assert_1.default)(stats.isSymbolicLink());
+    });
+    (0, node_test_1.it)('Negative: Throw if not exists resource', async () => {
+        const guid = chance.guid();
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.stat(node_path_1.default.join(tmpDir, guid));
+        });
+    });
+    (0, node_test_1.it)('[sync] Positive: Must return information a file', () => {
+        const stats = index_1.pfs.stat(node_path_1.default.join(tmpDir, 'tings.txt'), {
+            sync: true
+        });
+        (0, node_assert_1.default)(stats.isFile());
+    });
+    (0, node_test_1.it)('[sync] Positive: Must return information a directory in ', () => {
+        const stats = index_1.pfs.stat(node_path_1.default.join(tmpDir, 'digest'), {
+            sync: true
+        });
+        (0, node_assert_1.default)(stats.isDirectory());
+    });
+    (0, node_test_1.it)('[sync] Positive: Must return information a symlink', () => {
+        const stats = index_1.pfs.stat(node_path_1.default.join(tmpDir, 'flexapp'), {
+            sync: true
+        });
+        (0, node_assert_1.default)(stats.isSymbolicLink());
+    });
+    (0, node_test_1.it)('[sync] Negative: Throw if not exists resource', () => {
+        const guid = chance.guid();
+        node_assert_1.default.throws(() => {
+            index_1.pfs.stat(node_path_1.default.join(tmpDir, guid), {
+                sync: true
+            });
+        });
+    });
+});

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

@@ -0,0 +1,4 @@
+import type { PoweredFileSystem } from '../powered-file-system';
+export declare function symlink<T extends boolean = false>(this: PoweredFileSystem, src: string, dest: string, options?: {
+    sync?: T;
+}): T extends true ? void : Promise<void>;

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

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.symlink = symlink;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Windows requires an explicit link type. Non-Windows platforms infer it.
+ */
+function resolveSymlinkType(src) {
+    if (process.platform !== 'win32') {
+        return undefined;
+    }
+    const stats = node_fs_1.default.lstatSync(src);
+    return stats.isDirectory() ? 'junction' : 'file';
+}
+function symlink(src, dest, options) {
+    src = node_path_1.default.resolve(this.pwd, src);
+    dest = node_path_1.default.resolve(this.pwd, dest);
+    const { sync = false } = options ?? {};
+    if (sync) {
+        const type = resolveSymlinkType(src);
+        node_fs_1.default.symlinkSync(src, dest, type);
+        return undefined;
+    }
+    return new Promise((resolve, reject) => {
+        if (process.platform === 'win32') {
+            node_fs_1.default.lstat(src, (err, stats) => {
+                if (err) {
+                    return reject(err);
+                }
+                const type = stats.isDirectory() ? 'junction' : 'file';
+                node_fs_1.default.symlink(src, dest, type, (err) => {
+                    if (err) {
+                        return reject(err);
+                    }
+                    resolve();
+                });
+            });
+        }
+        else {
+            node_fs_1.default.symlink(src, dest, (err) => {
+                if (err) {
+                    return reject(err);
+                }
+                resolve();
+            });
+        }
+    });
+}

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

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

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

@@ -0,0 +1,77 @@
+"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");
+/**
+ * Covers symlink creation for file and directory targets.
+ */
+(0, node_test_1.describe)('symlink(src, use [, 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, 'flexapp')]: {
+                type: 'symlink',
+                target: node_path_1.default.join(tmpDir, 'tings.txt')
+            }
+        };
+        const counter = chance.natural({ max: 7 });
+        for (let i = 0; i < counter; i++) {
+            frame[node_path_1.default.join(tmpDir, String(i))] = { type: 'directory' };
+        }
+        (0, test_utils_1.fmock)(frame);
+    });
+    (0, node_test_1.afterEach)(() => {
+        (0, test_utils_1.restore)(tmpDir);
+    });
+    (0, node_test_1.it)('Positive: Must be created a symbolic link', async () => {
+        await index_1.pfs.symlink(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'linkapp'));
+        const stat = node_fs_1.default.lstatSync(node_path_1.default.join(tmpDir, 'linkapp'));
+        (0, node_assert_1.default)(stat.isSymbolicLink());
+    });
+    (0, node_test_1.it)('Positive: Must be created a symbolic link for directory', async () => {
+        await index_1.pfs.symlink(node_path_1.default.join(tmpDir, 'digest'), node_path_1.default.join(tmpDir, 'linkapp'));
+        const stat = node_fs_1.default.lstatSync(node_path_1.default.join(tmpDir, 'linkapp'));
+        (0, node_assert_1.default)(stat.isSymbolicLink());
+    });
+    (0, node_test_1.it)('Negative: Throw if destination already exists', async () => {
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.symlink(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'flexapp'));
+        });
+    });
+    (0, node_test_1.it)('[sync] Positive: Must be created a symbolic link', () => {
+        index_1.pfs.symlink(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'linkapp'), {
+            sync: true
+        });
+        const stat = node_fs_1.default.lstatSync(node_path_1.default.join(tmpDir, 'linkapp'));
+        (0, node_assert_1.default)(stat.isSymbolicLink());
+    });
+    (0, node_test_1.it)('[sync] Positive: Must be created a symbolic link for directory', () => {
+        index_1.pfs.symlink(node_path_1.default.join(tmpDir, 'digest'), node_path_1.default.join(tmpDir, 'linkapp'), {
+            sync: true
+        });
+        const stat = node_fs_1.default.lstatSync(node_path_1.default.join(tmpDir, 'linkapp'));
+        (0, node_assert_1.default)(stat.isSymbolicLink());
+    });
+    (0, node_test_1.it)('[sync] Negative: Throw if destination already exists', () => {
+        node_assert_1.default.throws(() => {
+            index_1.pfs.symlink(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'flexapp'), {
+                sync: true
+            });
+        });
+    });
+});

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

@@ -0,0 +1,8 @@
+import type { Mode, PoweredFileSystem } from '../powered-file-system';
+/**
+ * Thin wrapper around `fs.access` that resolves paths against the instance root.
+ */
+export declare function test<T extends boolean = false>(this: PoweredFileSystem, src: string, options?: {
+    sync?: T;
+    flag?: Mode;
+}): T extends true ? boolean : Promise<boolean>;

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

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.test = test;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Thin wrapper around `fs.access` that resolves paths against the instance root.
+ */
+function test(src, options) {
+    const { sync = false, flag = 'e' } = options ?? {};
+    const mode = this.constants[flag];
+    src = node_path_1.default.resolve(this.pwd, src);
+    if (sync) {
+        try {
+            node_fs_1.default.accessSync(src, mode);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return new Promise((resolve) => {
+        node_fs_1.default.access(src, mode, (err) => {
+            resolve(!err);
+        });
+    });
+}

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

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

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

@@ -0,0 +1,76 @@
+"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 existence and access checks exposed by `test()`.
+ */
+(0, node_test_1.describe)('test(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, 'digest')]: { type: 'directory' }
+        });
+    });
+    (0, node_test_1.afterEach)(() => {
+        (0, test_utils_1.restore)(tmpDir);
+    });
+    (0, node_test_1.it)(`Positive: Should return 'true' for current working directory`, async () => {
+        const exist = await index_1.pfs.test('.');
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)(`Positive: For existing file should return 'true'`, async () => {
+        const exist = await index_1.pfs.test(node_path_1.default.join(tmpDir, 'tings.txt'));
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)(`Positive: For existing directory should return 'true'`, async () => {
+        const exist = await index_1.pfs.test(node_path_1.default.join(tmpDir, 'digest'));
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)(`Positive: A non-existent file must return 'false'`, async () => {
+        const guid = chance.guid();
+        const exist = await index_1.pfs.test(node_path_1.default.join(tmpDir, guid));
+        (0, node_assert_1.default)(exist === false);
+    });
+    (0, node_test_1.it)(`Positive: For existing file should return 'true'`, () => {
+        const exist = index_1.pfs.test(node_path_1.default.join(tmpDir, 'tings.txt'), {
+            sync: true
+        });
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)(`[sync] Positive: For existing directory should return 'true'`, () => {
+        const exist = index_1.pfs.test(node_path_1.default.join(tmpDir, 'digest'), {
+            sync: true
+        });
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)(`[sync] Positive: A non-existent file must return 'false'`, () => {
+        const guid = chance.guid();
+        const exist = index_1.pfs.test(node_path_1.default.join(tmpDir, guid), {
+            sync: true
+        });
+        (0, node_assert_1.default)(exist === false);
+    });
+    (0, node_test_1.it)('[sync] Positive: Should respect access flag checks', () => {
+        node_fs_1.default.chmodSync(node_path_1.default.join(tmpDir, 'tings.txt'), 0o444);
+        const writable = index_1.pfs.test(node_path_1.default.join(tmpDir, 'tings.txt'), {
+            sync: true,
+            flag: 'w'
+        });
+        (0, node_assert_1.default)(writable === false);
+    });
+});

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

@@ -0,0 +1,10 @@
+import type { Flag, PoweredFileSystem } from '../powered-file-system';
+/**
+ * Writes a file relative to `pwd` and then reapplies the computed permissions explicitly.
+ */
+export declare function write<T extends boolean = false>(this: PoweredFileSystem, src: string, data: Buffer | string, options?: {
+    sync?: T;
+    encoding?: BufferEncoding | null;
+    umask?: number;
+    flag?: Flag;
+}): T extends true ? void : Promise<void>;

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

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.write = write;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Writes a file relative to `pwd` and then reapplies the computed permissions explicitly.
+ */
+function write(src, data, options) {
+    const { sync = false, encoding = 'utf8', umask = 0o000, flag = 'w', } = options ?? {};
+    src = node_path_1.default.resolve(this.pwd, src);
+    const mode = 0o666 & ~umask;
+    if (sync) {
+        // Apply chmod explicitly so the final mode is deterministic across runtimes.
+        node_fs_1.default.writeFileSync(src, data, { encoding, mode, flag });
+        node_fs_1.default.chmodSync(src, mode);
+        return undefined;
+    }
+    return new Promise((resolve, reject) => {
+        node_fs_1.default.writeFile(src, data, { encoding, mode, flag }, (err) => {
+            if (err) {
+                return reject(err);
+            }
+            // Align async behavior with the synchronous branch.
+            node_fs_1.default.chmod(src, mode, (err) => {
+                if (err) {
+                    return reject(err);
+                }
+                resolve();
+            });
+        });
+    });
+}

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

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

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

@@ -0,0 +1,97 @@
+"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");
+/**
+ * Covers file writes, overwrite behavior, and explicit mode handling.
+ */
+const itUnix = process.platform === 'win32' ? node_test_1.it.skip : node_test_1.it;
+(0, node_test_1.describe)('write(src, data[, 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()
+            }
+        });
+    });
+    (0, node_test_1.afterEach)(() => {
+        (0, test_utils_1.restore)(tmpDir);
+    });
+    (0, node_test_1.it)('Positive: Must write content to file', async () => {
+        const payload = chance.paragraph();
+        const guid = chance.guid();
+        const filePath = node_path_1.default.join(tmpDir, `${guid}.txt`);
+        await index_1.pfs.write(filePath, payload);
+        const { size } = node_fs_1.default.lstatSync(filePath);
+        (0, node_assert_1.default)(payload.length === size);
+    });
+    (0, node_test_1.it)('Positive: Must rewrite content if file already exists', async () => {
+        const payload = chance.paragraph();
+        await index_1.pfs.write(node_path_1.default.join(tmpDir, 'tings.txt'), payload);
+        const { size } = node_fs_1.default.lstatSync(node_path_1.default.join(tmpDir, 'tings.txt'));
+        (0, node_assert_1.default)(payload.length === size);
+    });
+    (0, node_test_1.it)('Negative: Throw if resource is directory', async () => {
+        const payload = chance.paragraph();
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.write(tmpDir, payload);
+        });
+    });
+    (0, node_test_1.it)(`Negative: Unexpected option 'flag' returns Error`, async () => {
+        const payload = chance.paragraph();
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.write(node_path_1.default.join(tmpDir, 'tings.txt'), payload, {
+                flag: 'r'
+            });
+        });
+    });
+    (0, node_test_1.it)('[sync] Positive: Write contents even to a non-existent file', () => {
+        const payload = chance.paragraph();
+        const guid = chance.guid();
+        const filePath = node_path_1.default.join(tmpDir, `${guid}.txt`);
+        index_1.pfs.write(filePath, payload, {
+            sync: true
+        });
+        const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+        (0, node_assert_1.default)(payload === content);
+    });
+    (0, node_test_1.it)('[sync] Negative: Throw if resource is directory', () => {
+        const payload = chance.paragraph();
+        node_assert_1.default.throws(() => {
+            index_1.pfs.write(tmpDir, payload, {
+                sync: true
+            });
+        });
+    });
+    (0, node_test_1.it)(`[sync] Negative: Unexpected option 'flag' returns Error`, () => {
+        const payload = chance.paragraph();
+        node_assert_1.default.throws(() => {
+            index_1.pfs.write(node_path_1.default.join(tmpDir, 'tings.txt'), payload, {
+                sync: true,
+                flag: 'r'
+            });
+        });
+    });
+    itUnix('[sync] Positive: Umask should be applied with bit masking', () => {
+        const guid = chance.guid();
+        const filePath = node_path_1.default.join(tmpDir, `${guid}.txt`);
+        index_1.pfs.write(filePath, 'x', {
+            sync: true,
+            umask: 0o111
+        });
+        const mode = node_fs_1.default.statSync(filePath).mode & 0o777;
+        (0, node_assert_1.default)(mode === 0o666);
+    });
+});

package/dist/{src/powered-file-system.d.ts → powered-file-system.d.ts}

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
 import { bitmask } from './bitmask';
+/**
+ * Public API entrypoint for the path-aware file system wrapper.
+ */
 export type Mode = keyof IConstants;
-export type Flag = Mode | 'a';
+export type Flag = Extract<fs.OpenMode, string>;
 export type Stats = fs.Stats;
 export * from './bitmask';
 export interface IConstants {
@@ -10,45 +13,89 @@ export interface IConstants {
     w: number;
     x: number;
 }
+/**
+ * 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.
+ */
 export declare class PoweredFileSystem {
     readonly pwd: string;
+    /**
+     * Access mode aliases used by `test()`.
+     */
     readonly constants: IConstants;
+    /**
+     * Exposes permission mask normalization as a static helper.
+     */
     static bitmask: typeof bitmask;
+    /**
+     * @param pwd Base directory used to resolve all relative paths.
+     */
     constructor(pwd?: string);
-    private resolve;
+    /**
+     * Checks whether the given path is accessible with the requested mode.
+     */
     test<T extends boolean = false>(src: string, options?: {
         sync?: T;
         flag?: Mode;
     }): T extends true ? boolean : Promise<boolean>;
+    /**
+     * Returns `lstat` information for a path.
+     */
     stat<T extends boolean = false>(src: string, options?: {
         sync?: T;
     }): T extends true ? Stats : Promise<Stats>;
+    /**
+     * Applies a mode recursively to a file or directory tree.
+     */
     chmod<T extends boolean = false>(src: string, mode: number, options?: {
         sync?: T;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Applies ownership recursively to a file or directory tree.
+     */
     chown<T extends boolean = false>(src: string, options?: {
         sync?: T;
         uid?: number;
         gid?: number;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Creates a symbolic link from `dest` to `src`.
+     */
     symlink<T extends boolean = false>(src: string, dest: string, options?: {
         sync?: T;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Copies `src` into the destination directory.
+     */
     copy<T extends boolean = false>(src: string, dest: string, options?: {
         sync?: T;
         umask?: number;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Renames or moves a file system node.
+     */
     rename<T extends boolean = false>(src: string, dest: string, options?: {
         sync?: T;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Removes a file system node recursively.
+     */
     remove<T extends boolean = false>(src: string, options?: {
         sync?: T;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Reads a file relative to the current instance root.
+     */
     read<T extends boolean = false>(src: string, options?: {
         sync?: T;
         encoding?: BufferEncoding | null;
         flag?: Flag;
     }): T extends true ? string | Buffer : Promise<string | Buffer>;
+    /**
+     * Writes a file and applies the resulting permissions explicitly.
+     */
     write<T extends boolean = false>(src: string, data: Buffer | string, options?: {
         sync?: T;
         encoding?: BufferEncoding | null;
@@ -56,17 +103,23 @@ export declare class PoweredFileSystem {
         flag?: Flag;
     }): T extends true ? void : Promise<void>;
     /**
-    * @deprecated The method should not be used
-    */
+     * @deprecated Use `write(..., { flag: 'a' })` instead.
+     */
     append<T extends boolean = false>(src: string, data: Buffer | string, options?: {
         sync?: T;
         encoding?: BufferEncoding | null;
         umask?: number;
     }): T extends true ? void : Promise<void>;
+    /**
+     * Lists directory entries relative to the current instance root.
+     */
     readdir<T extends boolean = false>(dir: string, options?: {
         sync?: T;
         encoding?: BufferEncoding | null;
     }): T extends true ? string[] : Promise<string[]>;
+    /**
+     * Creates a directory tree relative to the current instance root.
+     */
     mkdir<T extends boolean = false>(dir: string, options?: {
         sync?: T;
         umask?: number;