sanitize-filename

What is sanitize-filename?

The sanitize-filename npm package is designed to sanitize strings (especially filenames) to ensure they are safe for use within a filesystem. It removes or replaces invalid characters that could cause errors or security issues when used as filenames or paths.

What are sanitize-filename's main functionalities?

Sanitize filenames

This feature allows you to sanitize a string by removing or replacing characters that are not allowed in filenames across various operating systems. This is particularly useful for creating filenames from user input or external sources.

"const sanitize = require('sanitize-filename');\nconst title = 'My:Invalid/Filename*?<>|';\nconst safeTitle = sanitize(title);\nconsole.log(safeTitle); // Outputs 'MyInvalidFilename'"

Other packages similar to sanitize-filename

filenamify

Similar to sanitize-filename, filenamify also sanitizes strings to make them safe to use as filenames. It provides options to customize the replacement of invalid characters, which might offer more flexibility compared to sanitize-filename.

slugify

While slugify is primarily designed to convert strings into URL slugs, it can also be used to sanitize filenames by converting spaces and special characters into URL-friendly characters. It differs from sanitize-filename by focusing on URL usability rather than filesystem safety.

README

sanitize-filename

Sanitize a string to be safe for use as a filename by removing directory paths and invalid characters.

Install

npm: sanitize-filename

npm install sanitize-filename

Example

var sanitize = require("sanitize-filename");

// Some string that may be unsafe or invalid as a filename
var UNSAFE_USER_INPUT = "~/.\u0000ssh/authorized_keys";

// Sanitize the string to be safe for use as a filename.
var filename = sanitize(UNSAFE_USER_INPUT);
// -> "~.sshauthorized_keys"

Details

sanitize-filename removes the following:

• Control characters (0x00–0x1f and 0x80–0x9f)
• Reserved characters (/, ?, <, >, \, :, *, |, and ")
• Unix reserved filenames (. and ..)
• Trailing periods and spaces (for Windows)
• Windows reserved filenames (CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, and LPT9)

The resulting string is truncated to 255 bytes in length. The string will not contain any directory paths and will be safe to use as a filename.

Empty String "" Result

An empty string "" can be returned. For example:

var sanitize = require("sanitize-filename");
sanitize("..")
// -> ""

Non-unique Filenames

Two different inputs can return the same value. For example:

var sanitize = require("sanitize-filename");
sanitize("file?")
// -> "file"
sanitize ("*file*")
// -> "file"

File Systems

Sanitized filenames will be safe for use on modern Windows, OS X, and Unix file systems (NTFS, ext, etc.).

FAT 8.3 filenames are not supported.

Test Your File System

The test program will use various strings (including the Big List of Naughty Strings) to create files in the working directory. Run npm test to run tests against your file system.

API

sanitize(inputString, [options])

Sanitize inputString by removing or replacing invalid characters.

Options:

• options.replacement: optional, string/function, default: "". If passed as a string, it's used as the replacement for invalid characters. If passed as a function, the function will be called with the invalid characters and it's return value will be used as the replacement. See String.prototype.replace for more info.