Get an unused filename by appending a number if it exists:
file.txt→file (1).txt
Useful for safely writing, copying, moving files without overwriting existing files.
npm install unused-filename.
├── rainbow (1).txt
├── rainbow.txt
└── unicorn.txt
import {unusedFilename} from 'unused-filename';
console.log(await unusedFilename('rainbow.txt'));
//=> 'rainbow (2).txt'Returns a Promise<string> containing either the original filename or the filename increment by options.incrementer.
If an already incremented filePath is passed, unusedFilename will simply increment and replace the already existing index:
import {unusedFilename} from 'unused-filename';
console.log(await unusedFilename('rainbow (1).txt'));
//=> 'rainbow (2).txt'Synchronous version of unusedFilename.
Type: string
The path to check for filename collision.
Type: object
Type: (filePath: string) => [string, string]
Default: Parentheses incrementer: file.txt → file (1).txt
A function that accepts a file path, and increments its index.
It's the incrementer's responsibility to extract an already existing index from the given file path so that it picks up and continues incrementing an already present index instead of appending a second one.
The incrementer has to return a tuple of [originalFilename, incrementedFilename], where originalFilename is the filename without the index, and incrementedFilename is a filename with input's index bumped by one.
import {unusedFilename} from 'unused-filename';
// Incrementer that inserts a new index as a prefix.
const prefixIncrementer = (filename, extension) => {
const match = filename.match(/^(?<index>\d+)_(?<originalFilename>.*)$/);
let {originalFilename, index} = match ? match.groups : {originalFilename: filename, index: 0};
originalFilename = originalFilename.trim();
return [`${originalFilename}${extension}`, `${++index}_${originalFilename}${extension}`];
};
console.log(await unusedFilename('rainbow.txt', {incrementer: prefixIncrementer}));
//=> '1_rainbow.txt'Type: number
Default: Infinity
The maximum number of attempts to find an unused filename.
When the limit is reached, the function will throw MaxTryError.
Creates an incrementer that appends a number after a separator.
separatorIncrementer('_') will increment file.txt → file_1.txt.
Not all characters can be used as separators:
- On Unix-like systems,
/is reserved. - On Windows,
<>:"/|?*along with trailing periods are reserved.
import {unusedFilename, separatorIncrementer} from 'unused-filename';
console.log(await unusedFilename('rainbow.txt', {incrementer: separatorIncrementer('_')}));
//=> 'rainbow_1.txt'The error thrown when maxTries limit is reached without finding an unused filename.
It comes with 2 custom properties:
originalPath- Path without incrementation sequence.lastTriedPath- The last tested incremented path.
Example:
import {unusedFilename, MaxTryError} from 'unused-filename';
try {
const path = await unusedFilename('rainbow (1).txt', {maxTries: 0});
} catch (error) {
if (error instanceof MaxTryError) {
console.log(error.originalPath); // 'rainbow.txt'
console.log(error.lastTriedPath); // 'rainbow (1).txt'
}
}- filenamify - Convert a string to a valid safe filename