file-sanity

A simple npm package to validate and sanitize filenames by removing or replacing invalid characters for Windows, macOS, and Linux.

Installation

npm install file-sanity

Usage

JavaScript API

const { sanitizeFilename, isValid } = require("file-sanity");

// Sanitize a filename: Replace invalid characters with '_'
console.log(sanitizeFilename("test<file.txt")); // Output: test_file.txt

// Custom replacement character
console.log(sanitizeFilename("test<file.txt", { replacement: "-" })); // Output: test-file.txt

// Strict mode: Throw error on invalid characters
try {
  sanitizeFilename("test<file.txt", { strict: true });
} catch (err) {
  console.log(err.message); // Output: Filename contains invalid characters: <
}

// Check if a filename is valid
console.log(isValid("test.txt")); // Output: true
console.log(isValid("test<file.txt")); // Output: false

CLI

You can use the package from the command line:

# Check if a filename is valid
npx file-sanity isValid "test.txt"
# Output: true

npx file-sanity isValid "test<file.txt"
# Output: false

# Sanitize a filename (default replacement: '_')
npx file-sanity sanitize "test<file.txt"
# Output: test_file.txt

# Sanitize with custom replacement
npx file-sanity sanitize "test<file.txt" --replace=-
# Output: test-file.txt

# Sanitize with strict mode (exits with error code 1 if invalid)
npx file-sanity sanitize "test<file.txt" --strict
# Output: Error: Filename contains invalid characters: <

API

sanitizeFilename(filename, [options])

• filename (string): The filename to sanitize.
• options (Object, optional):
  • replacement (string, default: "_"): Character to replace invalid characters.
  • strict (boolean, default: false): If true, throws an error if invalid characters are found.
• Returns: string - The sanitized filename.
• Throws: TypeError if filename is not a string; Error if strict is true and invalid characters are found.

isValid(filename)

• filename (string): The filename to check.
• Returns: boolean - true if the filename contains no invalid characters, false otherwise.
• Throws: TypeError if filename is not a string.

Invalid Characters

The package checks for the following invalid characters:

• /, \, ?, *, :, |, ", <, >
• ASCII control characters (0–31, including NUL)

License

MIT