Namecrement

Smart and simple unique name generator.
If a name already exists, Namecrement automatically increments it, like "file" → "file (1)", "file (2)", and so on.

---

✨ Features

• Automatically avoids naming collisions
• Smart incremental naming ((1), (2), etc.)
• Lightweight and dependency-free
• Works for filenames, labels, identifiers, and more

---

📦 Also Available

Need it for PHP? Check out Namecrement for PHP!

📦 Installation

1npm install namecrement

or

1pnpm add namecrement

---

🚀 Usage

1import { namecrement } from 'namecrement';
2
3// Example list of existing names
4const existing = ['file', 'file (1)', 'file (2)'];
5
6// Generate a unique name
7const newName = namecrement('file', existing);
8
9console.log(newName); // Output: "file (3)"

---

🧠 Advanced Usage

1namecrement('file', ['file', 'file -1-', 'file -2-'], ' -%N%-');
2// → 'file -3-'

You can customize how numbers are added by using the %N% placeholder in a suffixFormat:

Format Example	Output
" (%N%)"	file (1)
"-%N%"	file-1
"_v%N%"	file_v1
"<%N%>"	file<1>

---

✅ Type-Safe Format

suffixFormat must include the %N% placeholder, or the function will throw an error.

This ensures that all generated names include the incremented number in the format you define.

1namecrement('log', ['log', 'log_1'], '_%N%_'); // → log_2

---

📚 API

namecrement(baseName: string, existingNames: string[]): string

Parameter	Type	Description
baseName	string	The proposed name
existingNames	string[]	The list of names to check against
suffixFormat	string	The format for the incremented name (optional)
startingNumber	number | undefined	The starting number for incrementing (default: undefined)

Returns a unique name based on the proposed one.

---

🛠️ Examples

1namecrement('report', ['report', 'report (1)']); 
2// → 'report (2)'
3
4namecrement('image', ['photo', 'image', 'image (1)', 'image (2)']);
5// → 'image (3)'
6
7namecrement('new', []);
8// → 'new'
9
10namecrement('document', ['document', 'document -1-', 'document (2)'], ' -%N%-');
11// → 'document -2-'
12
13namecrement('file', [], ' (%N%)', 5);
14// → 'file (5)'

---

📄 License

MIT License © 2025 Hichem Taboukouyout