sanitize-filename

The sanitize function performs the following removals/replacements:

• Control characters: 0x00–0x1f and 0x80–0x9f.
• Reserved characters: /, ?, <, >, \, :, *, |, and ".
• Unix reserved filenames: . and ...
• Windows trailing characters: Trailing periods and spaces.
• Windows reserved filenames: CON, PRN, AUX, NUL, COM1 through COM9, and LPT1 through LPT9.

Compatibility

• Supported: Modern Windows, OS X, and Unix file systems (NTFS, ext, etc.).
• Not Supported: FAT 8.3 filenames.
• Length: The output is truncated to 255 bytes.

Install the package using npm to sanitize strings for safe filename usage.

npm install sanitize-filename

The sanitize function removes directory paths, control characters, reserved characters, and platform-specific reserved filenames (like Windows CON or NUL) to make a string safe for use as a filename. The resulting string is truncated to 255 bytes.

Note that sanitize can return an empty string "" if the input consists entirely of invalid characters (e.g., sanitize("..")), and different inputs may result in the same sanitized filename.

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"

By default, sanitize removes invalid characters (replaces them with an empty string). You can customize this behavior using the options.replacement option.

• String replacement: Provide a string to use as the replacement for every invalid character.
• Function replacement: Provide a function that will be called for each invalid character (similar to String.prototype.replace).

// Example of using a string replacement
var sanitize = require("sanitize-filename");
var filename = sanitize("file?", { replacement: "_" });
// -> "file_"

The default export is a function used to replace characters in strings that are illegal or unsafe for filenames across various operating systems. It handles illegal characters (like / ? < > \ : * | "), Unicode control codes, reserved Unix filenames (. and ..), and Windows reserved filenames (like CON, PRN, AUX, etc.). The resulting filename is also capped at 255 characters.

To use the library, call the exported function with the original filename and an optional options object.

const sanitize = require('sanitize-filename');

// Basic usage (removes unsafe characters)
const safeName = sanitize('my/unsafe:file?.txt');
// Output: 'myunsafefile.txt'

// Usage with custom replacement
const safeNameWithReplacement = sanitize('my/unsafe:file?.txt', { replacement: '_' });
// Output: 'my_unsafe_file_.txt'

When calling the sanitize function, you can provide an options object to specify how unsafe characters should be handled.

• options.replacement: A String or Function used to replace illegal characters, control codes, and reserved names. If not provided, the default behavior is to remove the characters (replace with an empty string '').

const sanitize = require('sanitize-filename');

// Using a string replacement
const result = sanitize('bad/file', { replacement: '-' });

// Using a function replacement
const resultFunc = sanitize('bad/file', { replacement: (match) => `[${match}]` });