FSESM 🚀 - Modern FS Utilities for ESM & TypeScript Projects

A modern, lightweight utility library for working with the file system in ESM and TypeScript projects.

🔹 What is FSESM?

FSESM is a collection of utility functions designed to simplify file system operations in ESM (ECMAScript Modules) and TypeScript projects. It provides sugar-coated methods for common tasks like reading, writing, moving, and managing files and directories, while avoiding unnecessary dependencies and keeping your code clean.

With FSESM, you can:

• Handle files and directories with ease.
• Work with JSON and .env files seamlessly.
• Ensure directories and files exist before operations.
• Recursively list files or check file types.
• Manage .env variables programmatically.

✅ Modern.
🚀 Lightweight.
🛠️ TypeScript-first.

🚀 Quick Start

Install FSESM via npm:

npm install fsesm

🔍 Key Features

1️⃣ File System Utilities

• Ensure directories and files exist before operations.
• Read, write, and update JSON files with ease.
• Move, copy, and remove files/directories safely.
• Recursively list files in a directory.

2️⃣ .env File Management

• Read, write, and update .env files programmatically.
• Find missing or empty .env keys.
• Parse .env files into objects with automatic type conversion.

3️⃣ Advanced Utilities

• Find files upwards from a directory (e.g., package.json or .env).
• Simple glob-based file searching with support for .gitignore.
• Symlink management with safety checks.

📦 Installation

Install FSESM globally or locally:

npm install -g fsesm

Or add it to your project:

npm install fsesm

📋 All Methods at a Glance

| Method | Description | Parameters | | --------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | ensureDir(dirPath) | Ensures a directory exists. Creates it recursively if missing. | dirPath: string | | ensureFile(filePath) | Ensures a file exists. Creates parent directories and an empty file if missing. | filePath: string | | readJson<T>(filePath) | Reads and parses a JSON file. Returns null if the file is missing or invalid. | filePath: string | | writeJson(filePath, data) | Writes an object to a JSON file. Creates parent directories if needed. | filePath: string, data: unknown | | updateJson<T>(filePath, updater) | Updates a JSON file using an async updater function. | filePath: string, updater: (data: T) => Promise<T> \| T | | outputFile(filePath, data) | Writes data to a file, ensuring parent directories exist. | filePath: string, data: string \| Buffer | | move(src, dest, overwrite) | Moves a file or directory. Handles cross-device moves by copying and deleting. | src: string, dest: string, overwrite: boolean = false | | copy(src, dest) | Copies a file or directory recursively. | src: string, dest: string | | remove(path) | Removes a file or directory recursively. | path: string | | pathExists(path) | Checks if a file or directory exists. | path: string | | ensureSymlink(src, dest, type) | Ensures a symbolic link exists at the destination. | src: string, dest: string, type?: "file" \| "dir" \| "junction" | | emptyDir(dirPath) | Empties a directory by removing its contents. Creates the directory if missing. | dirPath: string | | readFileSafe(filePath, encoding) | Reads a file safely. Returns null if the file doesn't exist. | filePath: string, encoding: BufferEncoding \| null = "utf-8" | | isDirectory(path) | Checks if a path is a directory. | path: string | | isFile(path) | Checks if a path is a file. | path: string | | listFiles(dirPath) | Recursively lists all files in a directory. | dirPath: string | | findPackageJson(options) | Finds the nearest package.json file. | options: { cwd?: string, maxDepth?: number } | | readPackageJson<T>(options or path) | Reads and parses the nearest package.json file. | options: { cwd?: string, maxDepth?: number } | | updatePackageJson<T>(updater, options) | Updates the nearest package.json file using an async updater function. | options: { cwd?: string, maxDepth?: number }, updater: UpdateJsonFunc<T> | | findEnvFile(fileName?, options) | Finds the nearest .env file. | options: { cwd?: string, maxDepth?: number } | | readEnvFile<T>(fileName?, options) | Reads and parses the nearest .env file. | options: { cwd?: string, maxDepth?: number } | | parseEnv<T>(data) | Parses a .env file content into an object. | data: string | | writeEnvVar(envPath, key, value, onlyIfEmpty) | Writes a key-value pair to a .env file. Updates if the key exists. | envPath: string, key: string, value: string, onlyIfEmpty: boolean = false | | getEmptyEnvKeys(envPath) | Finds empty or missing keys in a .env file. | envPath: string | | writeEnvRecord(envPath, record) | Writes a record of key-value pairs to a .env file. | envPath: string, record: Record<string, string> | | updateEnv<T>(envPath, updater) | Updates a .env file using an async updater function. | envPath: string, updater: UpdateJsonFunc<T> | | findFileUpwards(fileName, options) | Finds a file by searching upwards from a directory. | fileName: string, options: { cwd?: string, maxDepth?: number } | | find(patterns, options) | Finds files or folders matching glob patterns. | patterns: string \| string[], options: GlobOptions |

GlobOptions

| Option | Description | | ----------------------------- | ------------------------------------------------------------------------------------ | | cwd | The directory to start searching from. Default: process.cwd(). | | maxDepth | Maximum depth to search. Default: Infinity. | | ignore | Patterns to ignore. Can include negations (e.g., !**/node_modules/**). | | matchFilesWithoutExtensions | Whether to match files without extensions. Default: true. | | absolute | Whether to return absolute paths. Default: false. | | useGitignore | Whether to respect .gitignore files. Default: false. | | type | Type of items to search for: 'files', 'folders', or 'all'. Default: 'files'. |

🛠️ Methods & Examples

1️⃣ File System Utilities

ensureDir(dirPath: string): Promise<void>

Ensures a directory exists. Creates it recursively if it doesn't.

import { ensureDir } from "fsesm";

await ensureDir("./path/to/directory");

ensureFile(filePath: string): Promise<void>

Ensures a file exists. Creates parent directories and an empty file if missing.

import { ensureFile } from "fsesm";

await ensureFile("./path/to/file.txt");

readJson<T = unknown>(filePath: string): Promise<T | null>

Reads and parses a JSON file. Returns null if the file doesn't exist or has invalid JSON.

import { readJson } from "fsesm";

const data = await readJson<{ key: string }>("./path/to/file.json");

writeJson(filePath: string, data: unknown): Promise<void>

Writes an object to a JSON file. Creates parent directories if needed.

import { writeJson } from "fsesm";

await writeJson("./path/to/file.json", { key: "value" });

move(src: string, dest: string, overwrite = false): Promise<void>

Moves a file or directory. Handles cross-device moves by copying and deleting.

import { move } from "fsesm";

await move("./source/file.txt", "./destination/file.txt");

copy(src: string, dest: string): Promise<void>

Copies a file or directory recursively.

import { copy } from "fsesm";

await copy("./source/file.txt", "./destination/file.txt");

remove(path: string): Promise<void>

Removes a file or directory recursively.

import { remove } from "fsesm";

await remove("./path/to/delete");

2️⃣ .env File Management

readEnvFile<T = Record<string, any>>(options: FindEnvFileOptions): Promise<{ path: string; data: T } | null>

Reads and parses a .env file into an object.

import { readEnvFile } from "fsesm";

const env = await readEnvFile<{ API_KEY: string }>();

writeEnvVar(envPath: string, key: string, value: string, onlyIfEmpty = false): Promise<void>

Writes a key-value pair to a .env file. Updates the value if the key exists.

import { writeEnvVar } from "fsesm";

await writeEnvVar("./.env", "API_KEY", "your-api-key");

getEmptyEnvKeys(envPath: string): Promise<string[]>

Finds keys in a .env file that are empty or missing.

import { getEmptyEnvKeys } from "fsesm";

const missingKeys = await getEmptyEnvKeys("./.env");

3️⃣ Advanced Utilities

findFileUpwards(fileName: string, options: FindFileUpwardsOptions): Promise<string | null>

Finds a file by searching upwards from the current directory.

import { findFileUpwards } from "fsesm";

const packageJsonPath = await findFileUpwards("package.json");

find(patterns: string | string[], options: GlobOptions): Promise<string[]>

Finds files or folders matching glob patterns.

import { find } from "fsesm";

const files = await find("**/*.ts", { cwd: "./src" });

ensureSymlink(src: string, dest: string, type?: "file" | "dir" | "junction"): Promise<void>

Ensures a symbolic link exists at the destination.

import { ensureSymlink } from "fsesm";

await ensureSymlink("./source/file.txt", "./destination/link.txt");

🔐 Why FSESM?

• No unnecessary dependencies.
• Fully typed for TypeScript.
• Works seamlessly with ESM projects.
• Handles edge cases gracefully.
• Lightweight and fast.

📜 License

FSESM is licensed under the MIT License.
© 2025 Unbywyd.

🔗 Links

🔹 NPM: FSESM on NPM
🔹 GitHub: FSESM Repository
🔹 Issues: Report a bug

🚀 Simplify your file system operations with FSESM!

Need more features? Open an issue or contribute on GitHub! 😊