fsesm v0.2.2

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

GlobOptions

🛠️ 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! 😊