https://github.com/hichemtab-tech/namecrement
A smart JavaScript utility that generates unique incremental names, preventing naming collisions by automatically appending incremental suffixes.
https://github.com/hichemtab-tech/namecrement
auto-increment collision duplicate filename generator increment incremental javascript name names naming package unique utility
Last synced: 3 months ago
JSON representation
A smart JavaScript utility that generates unique incremental names, preventing naming collisions by automatically appending incremental suffixes.
- Host: GitHub
- URL: https://github.com/hichemtab-tech/namecrement
- Owner: HichemTab-tech
- License: mit
- Created: 2025-04-28T16:12:48.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-09-02T23:52:35.000Z (9 months ago)
- Last Synced: 2025-09-03T00:23:13.594Z (9 months ago)
- Topics: auto-increment, collision, duplicate, filename, generator, increment, incremental, javascript, name, names, naming, package, unique, utility
- Language: TypeScript
- Homepage:
- Size: 139 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Namecrement
[](https://github.com/HichemTab-tech/Namecrement/blob/main/LICENSE)
[](https://www.npmjs.com/package/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](https://github.com/HichemTab-tech/Namecrement-php)
* Python: [Namecrement-py](https://github.com/HichemTab-tech/Namecrement-py)
## 📦 Installation
```bash
npm install namecrement
```
or
```bash
pnpm add namecrement
```
---
## 🚀 Usage
```javascript
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
```ts
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.
```ts
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
```javascript
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