https://github.com/CorentinTh/friendly-ids
Generate human readable unique identifiers.
https://github.com/CorentinTh/friendly-ids
Last synced: 3 months ago
JSON representation
Generate human readable unique identifiers.
- Host: GitHub
- URL: https://github.com/CorentinTh/friendly-ids
- Owner: CorentinTh
- License: mit
- Created: 2025-01-23T14:27:27.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-01-23T14:27:39.000Z (12 months ago)
- Last Synced: 2025-09-30T12:43:24.324Z (4 months ago)
- Language: TypeScript
- Size: 66.4 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# @corentinth/friendly-ids
`@corentinth/friendly-ids` is a lib that generates human-readable IDs for your projects. It is designed to be simple, fast, and easy to use.
```javascript
import { generateId } from '@corentinth/friendly-ids';
const id = generateId();
console.log(id);
// fierce-zebra-456
```
## Features
- **78,648,000 combinations**: The default generator can generate up to 78,648,000 unique IDs (348 nouns x 226 adjectives x 1000 numbers).
- **Customizable**: You can create your own generator with a custom separator and random int generator.
- **No dependencies**: The lib has no dependencies and is lightweight.
- **TypeScript support**: The lib is written in TypeScript and comes with type definitions.
- **Tree-shakable**: The lib is tree-shakable and only includes the code you use.
- **Datasets**: Each words is strictly letters, no special characters.
## Installation
To install the package, use npm or yarn:
```bash
pnpm install @corentinth/friendly-ids
npm install @corentinth/friendly-ids
yarn add @corentinth/friendly-ids
```
## Usage
### Generate a friendly ID
```javascript
import { generateId } from '@corentinth/friendly-ids';
const id = generateId();
console.log(id);
// fierce-zebra-456
```
### Create a custom generator
```javascript
import { createIdGenerator } from '@corentinth/friendly-ids';
const generateId = createIdGenerator();
const id = generateId();
console.log(id);
// fierce-zebra-456
```
With a custom separator:
```javascript
import { createIdGenerator } from '@corentinth/friendly-ids';
const generateId = createIdGenerator({ separator: '_' });
const id = generateId();
console.log(id);
// brave_horse_537
```
All options:
```javascript
import { createIdGenerator, adjectives } from '@corentinth/friendly-ids';
const generateId = createIdGenerator({
separator: '~',
// A list of chunks generators, each generator is a function that provides random helpers and expects a string or number as a return value
chunks: [
({ getRandomItem }) => getRandomItem(adjectives),
({ getRandomItem }) => getRandomItem(['foo', 'bar', 'baz']),
({ getRandomInt }) => getRandomInt({ min: 50, max: 100 }),
({ getRandomItem }) => getRandomItem(['a', 'b', 'c']),
],
// A custom implementation of the random int generator, by default based on Math.random
getRandomInt: ({ min, max }) => /* your implementation */,
});
const id = generateId();
console.log(id);
// fierce~foo~78~b
```
### Datasets
The lib comes with two datasets: [`adjectives`](./src/data/adjectives.ts) and [`animals`](./src/data/animals.ts).
You can use them to customize your generator:
```javascript
import { animals, adjectives } from '@corentinth/friendly-ids';
console.log(adjectives);
// [ 'adaptable', 'adventurous', 'affable', 'affectionate', 'afraid', ... ]
console.log(animals);
// [ 'albatross', 'alligator', 'alpaca', 'ant', 'anteater', ... ]
```
## Contributing
Contributions are welcome! Feel free to open issues or submit pull requests.
## Testing
You can run the tests with the following command:
```bash
# one shot
pnpm run test
# watch mode
pnpm run test:watch
```
## License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information.
## Credits and Acknowledgements
This project is crafted with ❤️ by [Corentin Thomasset](https://corentin.tech).
If you find this project helpful, please consider [supporting my work](https://buymeacoffee.com/cthmsst).