unused-foldername

Get an unused foldername by appending a number if it exists: folder → folder (1)

Useful for safely writing, copying, moving folders without overwriting existing folders.

Install

npm install unused-foldername

Usage

.
├── rainbow (1)
├── rainbow
└── unicorn

import {unusedFoldername} from 'unused-foldername';

console.log(await unusedFoldername('rainbow'));
//=> 'rainbow (2)'

API

unusedFoldername(folderPath, options?)

Returns a Promise<string> containing either the original foldername or the foldername increment by options.incrementer.

If an already incremented folderPath is passed, unusedFoldername will simply increment and replace the already existing index:

import {unusedFoldername} from 'unused-foldername';

console.log(await unusedFoldername('rainbow (1)'));
//=> 'rainbow (2)'

unusedFoldernameSync(folderPath, options?)

Synchronous version of unusedFoldername.

folderPath

Type: string

The path to check for foldername collision.

options

Type: object

incrementer

Type: (folderPath: string) => [string, string]
Default: Parentheses incrementer: folder → folder (1)

A function that accepts a folder path, and increments its index.

It's the incrementer's responsibility to extract an already existing index from the given folder 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 [originalFoldername, incrementedFoldername], where originalFoldername is the foldername without the index, and incrementedFoldername is a foldername with input's index bumped by one.

import {unusedFoldername} from 'unused-foldername';

// Incrementer that inserts a new index as a prefix.
const prefixIncrementer = (foldername) => {
	const match = foldername.match(/^(?<index>\d+)_(?<originalFoldername>.*)$/);
	let {originalFoldername, index} = match ? match.groups : {originalFoldername: foldername, index: 0};
	originalFoldername = originalFoldername.trim();
	return [`${originalFoldername}`, `${++index}_${originalFoldername}`];
};

console.log(await unusedFoldername('rainbow', {incrementer: prefixIncrementer}));
//=> '1_rainbow'

maxTries

Type: number
Default: Infinity

The maximum number of attempts to find an unused foldername.

When the limit is reached, the function will throw MaxTryError.

separatorIncrementer

Creates an incrementer that appends a number after a separator.

separatorIncrementer('_') will increment folder → folder_1.

Not all characters can be used as separators:

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

import {unusedFoldername, separatorIncrementer} from 'unused-foldername';

console.log(await unusedFoldername('rainbow', {incrementer: separatorIncrementer('_')}));
//=> 'rainbow_1'

MaxTryError

The error thrown when maxTries limit is reached without finding an unused foldername.

It comes with 2 custom properties:

• originalPath - Path without incrementation sequence.
• lastTriedPath - The last tested incremented path.

Example:

import {unusedFoldername, MaxTryError} from 'unused-foldername';

try {
	const path = await unusedFoldername('rainbow (1)', {maxTries: 0});
} catch (error) {
	if (error instanceof MaxTryError) {
		console.log(error.originalPath); // 'rainbow'
		console.log(error.lastTriedPath); // 'rainbow (1)'
	}
}

Related

• unused-filename - Get an unused filename by appending a number if it exists: file.txt → file (1).txt
• filenamify - Convert a string to a valid safe foldername