filenamify

filenamify

Convert a string to a valid safe filename

On Unix-like systems, / is reserved. On Windows, <>:"/\|?* along with trailing periods and spaces are reserved.

This module also removes non-printable control characters (including Unicode bidirectional marks) and normalizes Unicode whitespace.

Install

npm install filenamify

Usage

import filenamify from 'filenamify';

filenamify('<foo/bar>');
//=> '!foo!bar!'

filenamify('foo:"bar"', {replacement: '🐴'});
//=> 'foo🐴bar🐴'

API

filenamify(string, options?)

Convert a string to a valid filename.

filenamifyPath(path, options?)

Convert the filename in a path to a valid filename and return the augmented path.

import {filenamifyPath} from 'filenamify';

filenamifyPath('foo:bar');
//=> 'foo!bar'

options

Type: object

replacement

Type: string
Default: '!'

String to use as replacement for reserved filename characters.

Cannot contain: < > : " / \ | ? * or control characters.

maxLength

Type: number
Default: 100

Truncate the filename to the given length.

Only the base of the filename is truncated, preserving the extension. If the extension itself is longer than maxLength, you will get a string that is longer than maxLength, so you need to check for that if you allow arbitrary extensions.

Truncation is grapheme-aware and will not split Unicode characters (surrogate pairs or extended grapheme clusters). If the remaining budget (after accounting for the extension) is smaller than a whole grapheme, the base filename may be truncated to an empty string to avoid splitting.

Systems generally allow up to 255 characters, but we default to 100 for usability reasons.

Browser-only import

You can also import filenamify/browser, which only imports filenamify and not filenamifyPath, which relies on path being available or polyfilled. Importing filenamify this way is therefore useful when it is shipped using webpack or similar tools, and if filenamifyPath is not needed.

import filenamify from 'filenamify/browser';

filenamify('<foo/bar>');
//=> '!foo!bar!'

Related

• filenamify-cli - CLI for this module
• filenamify-url - Convert a URL to a valid filename
• valid-filename - Check if a string is a valid filename
• unused-filename - Get a unused filename by appending a number if it exists
• slugify - Slugify a string

Similar packages

Other packages similar to filenamify

sanitize-filename

The sanitize-filename package is similar to filenamify in that it sanitizes input to be safe for use as a filename. It removes or replaces invalid characters and is a straightforward alternative to filenamify.

slugify

While slugify is primarily used for creating URL slugs from strings, it can also be used to generate safe filenames. It converts strings into a URL-friendly format, which is also generally safe for filenames, though its primary use case is not for sanitizing filenames like filenamify.