pwd-fs 3.3.0 → 3.3.2

package/dist/bitmask.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Normalizes a permission mask to the standard rwxrwxrwx bit set.
+ */
+export declare function bitmask(mode: number): number;

package/dist/{src/bitmask.js → bitmask.js}

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bitmask = bitmask;
+/**
+ * Normalizes a permission mask to the standard rwxrwxrwx bit set.
+ */
 function bitmask(mode) {
     if (typeof mode !== 'number') {
         throw new TypeError(`Expected 'number', got '${typeof mode}'`);
@@ -12,4 +15,3 @@ function bitmask(mode) {
         return (mode & flag) ? umask + flag : umask;
     }, 0);
 }
-//# sourceMappingURL=bitmask.js.map

package/dist/bitmask.test.d.ts

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

package/dist/bitmask.test.js

@@ -0,0 +1,29 @@
+"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_test_1 = require("node:test");
+const index_1 = require("./index");
+/**
+ * Covers normalization of permission masks exposed through the public entrypoint.
+ */
+(0, node_test_1.describe)('static bitmask(mode: number)', () => {
+    (0, node_test_1.it)('Positive: Calculate bitmask', () => {
+        (0, node_assert_1.default)((0, index_1.bitmask)(33024) === 0o400);
+        (0, node_assert_1.default)((0, index_1.bitmask)(33152) === 0o600);
+        (0, node_assert_1.default)((0, index_1.bitmask)(33216) === 0o700);
+        (0, node_assert_1.default)((0, index_1.bitmask)(32800) === 0o040);
+        (0, node_assert_1.default)((0, index_1.bitmask)(32816) === 0o060);
+        (0, node_assert_1.default)((0, index_1.bitmask)(32824) === 0o070);
+        (0, node_assert_1.default)((0, index_1.bitmask)(32772) === 0o004);
+        (0, node_assert_1.default)((0, index_1.bitmask)(32774) === 0o006);
+        (0, node_assert_1.default)((0, index_1.bitmask)(32775) === 0o007);
+    });
+    (0, node_test_1.it)(`Negative: Throw an exception if the argument is 'null' type`, () => {
+        node_assert_1.default.throws(() => {
+            (0, index_1.bitmask)(null);
+        });
+    });
+});

package/dist/{src/index.d.ts → index.d.ts}

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

package/dist/{src/index.js → index.js}

@@ -16,7 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 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.
+ */
 exports.pfs = new powered_file_system_1.PoweredFileSystem();
 exports.default = powered_file_system_1.PoweredFileSystem;
 __exportStar(require("./powered-file-system"), exports);
-//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,9 @@
+import type { PoweredFileSystem } from '../powered-file-system';
+/**
+ * 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>;

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

@@ -0,0 +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' });
+}

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

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

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

@@ -0,0 +1,47 @@
+"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 the deprecated append helper in both async and sync modes.
+ */
+(0, node_test_1.describe)('append(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: 'hoodie'
+            }
+        });
+    });
+    (0, node_test_1.afterEach)(() => {
+        (0, test_utils_1.restore)(tmpDir);
+    });
+    (0, node_test_1.it)('Positive: Must append content to file', async () => {
+        const payload = chance.paragraph();
+        const filePath = node_path_1.default.join(tmpDir, 'tings.txt');
+        await index_1.pfs.append(filePath, payload);
+        const { size } = node_fs_1.default.statSync(filePath);
+        (0, node_assert_1.default)(payload.length + 6 === size);
+    });
+    (0, node_test_1.it)('[sync] Positive: Must append content to file', () => {
+        const payload = chance.paragraph();
+        const filePath = node_path_1.default.join(tmpDir, 'tings.txt');
+        index_1.pfs.append(filePath, payload, {
+            sync: true
+        });
+        const { size } = node_fs_1.default.statSync(filePath);
+        (0, node_assert_1.default)(payload.length + 6 === size);
+    });
+});

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

@@ -0,0 +1,7 @@
+import type { PoweredFileSystem } 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>;

package/dist/powered-file-system/chmod.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.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;
+    }
+    return new Promise((resolve, reject) => {
+        (0, recurse_io_1.chmod)(src, mode, (err) => {
+            if (err) {
+                return reject(err);
+            }
+            resolve();
+        });
+    });
+}

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

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

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

@@ -0,0 +1,71 @@
+"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 recursive permission updates affect both directories and nested files.
+ */
+(0, node_test_1.describe)('chmod(src, mode [, 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: Changes directory and file permissions', async () => {
+        await index_1.pfs.chmod(tmpDir, 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);
+    });
+    (0, node_test_1.it)('Negative: Throw if not exists resource', async () => {
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.chmod('./non-existent-source', 0o744);
+        });
+    });
+    (0, node_test_1.it)('[sync] Positive: Changes permissions of directory', () => {
+        index_1.pfs.chmod(tmpDir, 0o444, {
+            sync: true
+        });
+        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);
+    });
+    (0, node_test_1.it)('[sync] Positive: Changes file permissions', () => {
+        index_1.pfs.chmod(node_path_1.default.join(tmpDir, 'tings.txt'), 0o444, {
+            sync: true
+        });
+        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);
+    });
+    (0, node_test_1.it)('[sync] Negative: Throw if not exists resource', () => {
+        const guid = chance.guid();
+        node_assert_1.default.throws(() => {
+            index_1.pfs.chmod(`./${guid}`, 0o744, {
+                sync: true
+            });
+        });
+    });
+});

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

@@ -0,0 +1,9 @@
+import type { PoweredFileSystem } 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;
+    uid?: number;
+    gid?: number;
+}): T extends true ? void : Promise<void>;

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

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": 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);
+    if (sync) {
+        if (process.platform === 'win32') {
+            // Windows does not expose POSIX ownership changes; keep existence checks consistent.
+            node_fs_1.default.lstatSync(src);
+            return undefined;
+        }
+        (0, recurse_io_sync_1.chownSync)(src, uid, gid);
+        return undefined;
+    }
+    if (process.platform === 'win32') {
+        return new Promise((resolve, reject) => {
+            // Match Unix behavior by validating the path even when ownership cannot be changed.
+            node_fs_1.default.lstat(src, (err) => {
+                if (err) {
+                    return reject(err);
+                }
+                resolve();
+            });
+        });
+    }
+    return new Promise((resolve, reject) => {
+        (0, recurse_io_1.chown)(src, uid, gid, (err) => {
+            if (err) {
+                return reject(err);
+            }
+            resolve();
+        });
+    });
+}

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

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

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

@@ -0,0 +1,82 @@
+"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");
+/**
+ * Validates ownership changes while preserving path validation semantics.
+ */
+(0, node_test_1.describe)('chown(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: Changes the permissions of a file', async () => {
+        const filePath = node_path_1.default.join(tmpDir, 'tings.txt');
+        const { uid, gid } = node_fs_1.default.statSync(filePath);
+        await index_1.pfs.chown(filePath, { uid, gid });
+        (0, node_assert_1.default)(node_fs_1.default.existsSync(filePath));
+    });
+    (0, node_test_1.it)('Positive: Changes the permissions of a directory', async () => {
+        const dirPath = node_path_1.default.join(tmpDir, 'digest');
+        const { uid, gid } = node_fs_1.default.statSync(dirPath);
+        await index_1.pfs.chown(dirPath, { uid, gid });
+        (0, node_assert_1.default)(node_fs_1.default.existsSync(dirPath));
+    });
+    (0, node_test_1.it)('Negative: To a non-existent resource to return an Error', async () => {
+        const guid = chance.guid();
+        const { uid, gid } = node_fs_1.default.statSync(node_path_1.default.join(tmpDir, 'tings.txt'));
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.chown(node_path_1.default.join(tmpDir, guid), { uid, gid });
+        });
+    });
+    (0, node_test_1.it)('[sync] Positive: Changes the permissions of a file', () => {
+        const filePath = node_path_1.default.join(tmpDir, 'tings.txt');
+        const { uid, gid } = node_fs_1.default.statSync(filePath);
+        index_1.pfs.chown(filePath, {
+            sync: true,
+            uid,
+            gid
+        });
+        (0, node_assert_1.default)(node_fs_1.default.existsSync(filePath));
+    });
+    (0, node_test_1.it)('[sync] Positive: Changes the permissions of a directory', () => {
+        const dirPath = node_path_1.default.join(tmpDir, 'digest');
+        const { uid, gid } = node_fs_1.default.statSync(dirPath);
+        index_1.pfs.chown(dirPath, {
+            sync: true,
+            uid,
+            gid
+        });
+        (0, node_assert_1.default)(node_fs_1.default.existsSync(dirPath));
+    });
+    (0, node_test_1.it)('[sync] Negative: To a non-existent resource to return an Error', () => {
+        const guid = chance.guid();
+        const { uid, gid } = node_fs_1.default.statSync(node_path_1.default.join(tmpDir, 'tings.txt'));
+        node_assert_1.default.throws(() => {
+            index_1.pfs.chown(node_path_1.default.join(tmpDir, guid), {
+                sync: true,
+                uid,
+                gid
+            });
+        });
+    });
+});

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

@@ -0,0 +1,8 @@
+import type { 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;
+}): T extends true ? void : Promise<void>;

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

@@ -0,0 +1,29 @@
+"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 ?? {};
+    if (sync) {
+        (0, recurse_io_sync_1.copySync)(src, dest, umask);
+        return undefined;
+    }
+    return new Promise((resolve, reject) => {
+        (0, recurse_io_1.copy)(src, dest, umask, (err) => {
+            if (err) {
+                return reject(err);
+            }
+            resolve();
+        });
+    });
+}

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

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

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

@@ -0,0 +1,82 @@
+"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 and directory copy behavior, including collision handling.
+ */
+(0, node_test_1.describe)('copy(src, dir [, 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: Copying a item file', async () => {
+        await index_1.pfs.copy(node_path_1.default.join(tmpDir, 'tings.txt'), node_path_1.default.join(tmpDir, 'digest'));
+        const exist = node_fs_1.default.existsSync(node_path_1.default.join(tmpDir, 'digest', 'tings.txt'));
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)('Positive: Recursive copying a directory', async () => {
+        await index_1.pfs.copy(node_path_1.default.resolve('./src'), tmpDir);
+        const exist = node_fs_1.default.existsSync(node_path_1.default.join(tmpDir, 'src'));
+        (0, node_assert_1.default)(exist);
+    });
+    (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.copy(node_path_1.default.join(tmpDir, guid), tmpDir);
+        });
+    });
+    (0, node_test_1.it)('Negative: An attempt to copy to an existing resource should return an Error', async () => {
+        await node_assert_1.default.rejects(async () => {
+            await index_1.pfs.copy(tmpDir, node_path_1.default.dirname(tmpDir));
+        });
+    });
+    (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
+        });
+        const exist = node_fs_1.default.existsSync(node_path_1.default.join(tmpDir, 'digest', 'tings.txt'));
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)('[sync] Positive: Recursive copying a directory', () => {
+        index_1.pfs.copy(node_path_1.default.resolve('./src'), tmpDir, {
+            sync: true
+        });
+        const exist = node_fs_1.default.existsSync(node_path_1.default.join(tmpDir, 'src'));
+        (0, node_assert_1.default)(exist);
+    });
+    (0, node_test_1.it)('[sync] Negative: Throw if not exists resource', () => {
+        const guid = chance.guid();
+        node_assert_1.default.throws(() => {
+            index_1.pfs.copy(node_path_1.default.join(tmpDir, guid), tmpDir, {
+                sync: true
+            });
+        });
+    });
+    (0, node_test_1.it)('[sync] Negative: An attempt to copy to an existing resource should return an Error', () => {
+        node_assert_1.default.throws(() => {
+            index_1.pfs.copy(tmpDir, node_path_1.default.dirname(tmpDir), {
+                sync: true
+            });
+        });
+    });
+});

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

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

package/dist/powered-file-system/mkdir.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.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;
+    }
+    return new Promise((resolve, reject) => {
+        (0, recurse_io_1.mkdir)(dir, umask, (err) => {
+            if (err) {
+                return reject(err);
+            }
+            resolve();
+        });
+    });
+}

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

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