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

• PHP: Namecrement-php
• Python: Namecrement-py

📦 Installation

npm install namecrement

or

pnpm add namecrement

🚀 Usage

import { namecrement } from 'namecrement';

// Example list of existing names
const existing = ['file', 'file (1)', 'file (2)'];

// Generate a unique name
const newName = namecrement('file', existing);

console.log(newName); // Output: "file (3)"

🧠 Advanced Usage

namecrement('file', ['file', 'file -1-', 'file -2-'], ' -%N%-');
// → '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.

namecrement('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

namecrement('report', ['report', 'report (1)']); 
// → 'report (2)'

namecrement('image', ['photo', 'image', 'image (1)', 'image (2)']);
// → 'image (3)'

namecrement('new', []);
// → 'new'

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

namecrement('file', [], ' (%N%)', 5);
// → 'file (5)'

📄 License

MIT License © 2025 Hichem Taboukouyout