@rocketmakers/shell-fs 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+## Overview
+
+Contains helper functions for working with the file system.

package/lib/fs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Gets all sub-folders of a folder
+ * @param path The path of the folder to check
+ */
+export declare function getFolders(path: string): {
+    name: string;
+    path: string;
+}[];
+/**
+ * Gets all files within a folder (excluding sub-folders)
+ * @param path The path of the folder to check
+ */
+export declare function getFiles(path: string): {
+    name: string;
+    path: string;
+}[];
+/**
+ * Tests whether there is a directory at the given path
+ * @param path The path to check
+ */
+export declare function isDirectory(path: string): boolean;
+/**
+ * Get the directory path from the given file path.
+ *
+ * Neither the file nor the directory necessarily have to exist for this to work
+ * but if the path cannot represent a file (e.g. "/") then this will return undefined.
+ *
+ * @param filePath A string that could represent a file path
+ * @returns A string that represents the directory containing the given file,
+ * or undefined if the path could not have been a file
+ */
+export declare function getDirectoryPathFromFilePath(filePath: string): string | undefined;
+/**
+ * Tests whether the given path is an empty directory
+ * @param path The path to check
+ */
+export declare function isEmptyDirectory(path: string): boolean;

package/lib/fs.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFolders = getFolders;
+exports.getFiles = getFiles;
+exports.isDirectory = isDirectory;
+exports.getDirectoryPathFromFilePath = getDirectoryPathFromFilePath;
+exports.isEmptyDirectory = isEmptyDirectory;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * Appends the given file names to the given path
+ * @param path The path to append to
+ * @param names The names to append to the path
+ */
+function getInfo(path, names) {
+    return names.map(name => ({ name, path: (0, path_1.join)(path, name) }));
+}
+/**
+ * Gets all sub-folders of a folder
+ * @param path The path of the folder to check
+ */
+function getFolders(path) {
+    return getInfo(path, (0, fs_1.readdirSync)(path).filter(name => (0, fs_1.lstatSync)((0, path_1.join)(path, name)).isDirectory()));
+}
+/**
+ * Gets all files within a folder (excluding sub-folders)
+ * @param path The path of the folder to check
+ */
+function getFiles(path) {
+    return getInfo(path, (0, fs_1.readdirSync)(path).filter(name => (0, fs_1.lstatSync)((0, path_1.join)(path, name)).isFile()));
+}
+/**
+ * Tests whether there is a directory at the given path
+ * @param path The path to check
+ */
+function isDirectory(path) {
+    if (!(0, fs_1.existsSync)(path)) {
+        return false;
+    }
+    return (0, fs_1.lstatSync)(path).isDirectory();
+}
+/**
+ * Get the directory path from the given file path.
+ *
+ * Neither the file nor the directory necessarily have to exist for this to work
+ * but if the path cannot represent a file (e.g. "/") then this will return undefined.
+ *
+ * @param filePath A string that could represent a file path
+ * @returns A string that represents the directory containing the given file,
+ * or undefined if the path could not have been a file
+ */
+function getDirectoryPathFromFilePath(filePath) {
+    const parts = filePath.split(path_1.sep);
+    const fileName = parts.pop();
+    return fileName ? `${parts.join(path_1.sep)}${path_1.sep}` : undefined;
+}
+/**
+ * Tests whether the given path is an empty directory
+ * @param path The path to check
+ */
+function isEmptyDirectory(path) {
+    if (!isDirectory(path)) {
+        throw new Error(`isEmptyDirectory function expects '${path}' to be a directory`);
+    }
+    const contentLength = getFiles(path).length + getFolders(path).length;
+    return contentLength === 0;
+}

package/lib/source/fs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Gets all sub-folders of a folder
+ * @param path The path of the folder to check
+ */
+export declare function getFolders(path: string): {
+    name: string;
+    path: string;
+}[];
+/**
+ * Gets all files within a folder (excluding sub-folders)
+ * @param path The path of the folder to check
+ */
+export declare function getFiles(path: string): {
+    name: string;
+    path: string;
+}[];
+/**
+ * Tests whether there is a directory at the given path
+ * @param path The path to check
+ */
+export declare function isDirectory(path: string): boolean;
+/**
+ * Get the directory path from the given file path.
+ *
+ * Neither the file nor the directory necessarily have to exist for this to work
+ * but if the path cannot represent a file (e.g. "/") then this will return undefined.
+ *
+ * @param filePath A string that could represent a file path
+ * @returns A string that represents the directory containing the given file,
+ * or undefined if the path could not have been a file
+ */
+export declare function getDirectoryPathFromFilePath(filePath: string): string | undefined;
+/**
+ * Tests whether the given path is an empty directory
+ * @param path The path to check
+ */
+export declare function isEmptyDirectory(path: string): boolean;

package/lib/source/fs.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFolders = getFolders;
+exports.getFiles = getFiles;
+exports.isDirectory = isDirectory;
+exports.getDirectoryPathFromFilePath = getDirectoryPathFromFilePath;
+exports.isEmptyDirectory = isEmptyDirectory;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * Appends the given file names to the given path
+ * @param path The path to append to
+ * @param names The names to append to the path
+ */
+function getInfo(path, names) {
+    return names.map(name => ({ name, path: (0, path_1.join)(path, name) }));
+}
+/**
+ * Gets all sub-folders of a folder
+ * @param path The path of the folder to check
+ */
+function getFolders(path) {
+    return getInfo(path, (0, fs_1.readdirSync)(path).filter(name => (0, fs_1.lstatSync)((0, path_1.join)(path, name)).isDirectory()));
+}
+/**
+ * Gets all files within a folder (excluding sub-folders)
+ * @param path The path of the folder to check
+ */
+function getFiles(path) {
+    return getInfo(path, (0, fs_1.readdirSync)(path).filter(name => (0, fs_1.lstatSync)((0, path_1.join)(path, name)).isFile()));
+}
+/**
+ * Tests whether there is a directory at the given path
+ * @param path The path to check
+ */
+function isDirectory(path) {
+    if (!(0, fs_1.existsSync)(path)) {
+        return false;
+    }
+    return (0, fs_1.lstatSync)(path).isDirectory();
+}
+/**
+ * Get the directory path from the given file path.
+ *
+ * Neither the file nor the directory necessarily have to exist for this to work
+ * but if the path cannot represent a file (e.g. "/") then this will return undefined.
+ *
+ * @param filePath A string that could represent a file path
+ * @returns A string that represents the directory containing the given file,
+ * or undefined if the path could not have been a file
+ */
+function getDirectoryPathFromFilePath(filePath) {
+    const parts = filePath.split(path_1.sep);
+    const fileName = parts.pop();
+    return fileName ? `${parts.join(path_1.sep)}${path_1.sep}` : undefined;
+}
+/**
+ * Tests whether the given path is an empty directory
+ * @param path The path to check
+ */
+function isEmptyDirectory(path) {
+    if (!isDirectory(path)) {
+        throw new Error(`isEmptyDirectory function expects '${path}' to be a directory`);
+    }
+    const contentLength = getFiles(path).length + getFolders(path).length;
+    return contentLength === 0;
+}

package/lib/tests/fs.test.d.ts

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

package/lib/tests/fs.test.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const suite_1 = require("@rocketmakers/shell-tests/suite");
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const fs_2 = require("../source/fs");
+const packagePaths_1 = require("./packagePaths");
+(0, suite_1.sandboxedTestSuite)({ suiteName: 'FileSystem', sandboxRootPath: (0, packagePaths_1.sandboxPath)() }, () => {
+    describe('isDirectory', () => {
+        it('when passed empty string, returns false', () => {
+            expect((0, fs_2.isDirectory)('')).toBe(false);
+        });
+        it('when passed whitespace, returns false', () => {
+            expect((0, fs_2.isDirectory)(' \n\t\r')).toBe(false);
+        });
+        it('when passed a path that does not exist, returns false', () => {
+            expect((0, fs_2.isDirectory)((0, packagePaths_1.packagePath)('source', 'alan'))).toBe(false);
+        });
+        it('when passed a file path, returns false', () => {
+            expect((0, fs_2.isDirectory)((0, packagePaths_1.packagePath)('source', 'fs.ts'))).toBe(false);
+        });
+        it('when passed a directory path, returns true', () => {
+            expect((0, fs_2.isDirectory)((0, packagePaths_1.packagePath)('source'))).toBe(true);
+        });
+        it('when passed a directory path with a trailing slash, returns true', () => {
+            expect((0, fs_2.isDirectory)(`${(0, packagePaths_1.packagePath)('source/')}/`)).toBe(true);
+        });
+    });
+    describe('isEmptyDirectory', () => {
+        const emptyDirectoryPath = (0, packagePaths_1.sandboxPath)('empty-dir');
+        beforeEach(async () => {
+            if (!(0, fs_1.existsSync)(emptyDirectoryPath)) {
+                return (0, promises_1.mkdir)(emptyDirectoryPath, { recursive: true });
+            }
+        });
+        it('when passed empty string, throws an error', () => {
+            expect(() => (0, fs_2.isEmptyDirectory)('')).toThrow();
+        });
+        it('when passed whitespace, throws an error', () => {
+            expect(() => (0, fs_2.isEmptyDirectory)(' \n\t\r')).toThrow();
+        });
+        it('when passed a path that does not exist, throws an error', () => {
+            expect(() => (0, fs_2.isEmptyDirectory)((0, packagePaths_1.packagePath)('source', 'alan'))).toThrow();
+        });
+        it('when passed a file path, throws an error', () => {
+            expect(() => (0, fs_2.isEmptyDirectory)((0, packagePaths_1.packagePath)('source', 'fs.ts'))).toThrow();
+        });
+        it('when passed a path to an empty directory, returns true', () => {
+            expect((0, fs_2.isEmptyDirectory)(emptyDirectoryPath)).toBe(true);
+        });
+        it('when passed a path to a directory that is not empty, returns false', () => {
+            expect((0, fs_2.isEmptyDirectory)((0, packagePaths_1.packagePath)('source'))).toBe(false);
+        });
+    });
+    describe('getDirectoryPathFromFilePath', () => {
+        const expectUndefined = ['', '/'];
+        const expectDirPath = [
+            ['/myFile.txt', '/'],
+            ['./myFile.txt', './'],
+            ['/path.to/myFile.txt', '/path.to/'],
+            ['/path-to/myFile.txt', '/path-to/'],
+            ['./path/to/myFile.txt', './path/to/'],
+            ['../../up/then/down/some-file.yaml', '../../up/then/down/'],
+            ['/cheeky/path/noExtension', '/cheeky/path/'],
+            ['/some/path/to/directory/that/does/not/exist', '/some/path/to/directory/that/does/not/'],
+            [(0, packagePaths_1.sandboxPath)('some-file.json'), `${(0, packagePaths_1.sandboxPath)()}/`],
+        ];
+        it.each(expectUndefined)("'%s', returns undefined", testPath => {
+            expect((0, fs_2.getDirectoryPathFromFilePath)(testPath)).toBeUndefined();
+        });
+        it.each(expectDirPath)(`'%s', returns '%s'`, (testPath, expectedPath) => {
+            expect((0, fs_2.getDirectoryPathFromFilePath)(testPath)).toEqual(expectedPath);
+        });
+    });
+    describe('getFolders', () => {
+        it('when path contains a mix of files and folders, returns folders', async () => {
+            const parentPath = (0, packagePaths_1.sandboxPath)('getFilesTests');
+            await (0, promises_1.mkdir)(parentPath);
+            const files = ['file-1', 'file-2', 'file-3'];
+            const folders = ['dir-1', 'dir-2', 'dir-3'];
+            for (const fileName of files) {
+                await (0, promises_1.writeFile)((0, packagePaths_1.packagePath)(parentPath, fileName), 'content');
+            }
+            for (const folderName of folders) {
+                await (0, promises_1.mkdir)((0, packagePaths_1.packagePath)(parentPath, folderName), { recursive: true });
+            }
+            const result = (0, fs_2.getFolders)(parentPath);
+            const expectedResult = [
+                {
+                    name: 'dir-1',
+                    path: (0, packagePaths_1.packagePath)(parentPath, 'dir-1'),
+                },
+                {
+                    name: 'dir-2',
+                    path: (0, packagePaths_1.packagePath)(parentPath, 'dir-2'),
+                },
+                {
+                    name: 'dir-3',
+                    path: (0, packagePaths_1.packagePath)(parentPath, 'dir-3'),
+                },
+            ];
+            expect(result).toEqual(expectedResult);
+        });
+    });
+    describe('getFiles', () => {
+        it('when path contains a mix of files and folders, returns files', async () => {
+            const parentPath = (0, packagePaths_1.sandboxPath)('getFilesTests');
+            await (0, promises_1.mkdir)(parentPath);
+            const files = ['file-1', 'file-2', 'file-3'];
+            const folders = ['dir-1', 'dir-2', 'dir-3'];
+            for (const fileName of files) {
+                await (0, promises_1.writeFile)((0, packagePaths_1.packagePath)(parentPath, fileName), 'content');
+            }
+            for (const folderName of folders) {
+                await (0, promises_1.mkdir)((0, packagePaths_1.packagePath)(parentPath, folderName), { recursive: true });
+            }
+            const result = (0, fs_2.getFiles)(parentPath);
+            const expectedResult = [
+                {
+                    name: 'file-1',
+                    path: (0, packagePaths_1.packagePath)(parentPath, 'file-1'),
+                },
+                {
+                    name: 'file-2',
+                    path: (0, packagePaths_1.packagePath)(parentPath, 'file-2'),
+                },
+                {
+                    name: 'file-3',
+                    path: (0, packagePaths_1.packagePath)(parentPath, 'file-3'),
+                },
+            ];
+            expect(result).toEqual(expectedResult);
+        });
+    });
+});

package/lib/tests/packagePaths.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates an absolute path based on a relative path from the root of this package
+ * @param parts
+ */
+export declare function packagePath(...parts: string[]): string;
+/**
+ * Creates an absolute path relative to the sandbox testing path
+ * @param parts The parts of the path relative to the testing sandbox path
+ */
+export declare function sandboxPath(...parts: string[]): string;

package/lib/tests/packagePaths.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packagePath = packagePath;
+exports.sandboxPath = sandboxPath;
+const path_1 = require("path");
+/**
+ * Creates an absolute path based on a relative path from the root of this package
+ * @param parts
+ */
+function packagePath(...parts) {
+    return (0, path_1.resolve)(__dirname, '..', ...parts);
+}
+/**
+ * Creates an absolute path relative to the sandbox testing path
+ * @param parts The parts of the path relative to the testing sandbox path
+ */
+function sandboxPath(...parts) {
+    return (0, path_1.join)(packagePath('_tests-sandbox_'), ...parts);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rocketmakers/shell-fs",
+  "version": "0.1.0",
+  "exports": {
+    ".": {
+      "types": "./lib/fs.d.ts",
+      "default": "./lib/fs.js"
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "29.5.14",
+    "@types/node": "22.13.9",
+    "eslint": "8.57.1",
+    "jest": "29.7.0",
+    "jest-junit": "16.0.0",
+    "ts-jest": "29.3.0",
+    "typescript": "5.8.2",
+    "@rocketmakers/shell-tests": "0.1.0",
+    "eslint-config-shell": "0.1.0",
+    "tsconfig-shell": "0.1.0"
+  },
+  "directories": {
+    "lib": "lib"
+  },
+  "engines": {
+    "node": " ^20 || ^22"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "!lib/index.js",
+    "!lib/index.d.ts"
+  ],
+  "keywords": [],
+  "license": "MIT",
+  "repository": "Rocketmakers/rocketmakers-packages",
+  "scripts": {
+    "build": "tsc -p .",
+    "lint": "eslint . --ext .ts",
+    "lint-fix": "pnpm lint --fix",
+    "test-integration": "jest --runInBand"
+  }
+}