@corentinth/friendly-ids

中文文档
0.0.1发布于 2025/01/23MITTypeScriptESM + CJS零依赖近 30 天下载 1972

A human friendly ID generator

原始使用文档
文档目录10 节
  1. Features
  2. Installation
  3. Usage
  4. Generate a friendly ID
  5. Create a custom generator
  6. Datasets
  7. Contributing
  8. Testing
  9. License
  10. Credits and Acknowledgements

@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.

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:

pnpm install @corentinth/friendly-ids

npm install @corentinth/friendly-ids

yarn add @corentinth/friendly-ids

Usage

Generate a friendly ID

import { generateId } from '@corentinth/friendly-ids';

const id = generateId();

console.log(id);
// fierce-zebra-456

Create a custom generator

import { createIdGenerator } from '@corentinth/friendly-ids';

const generateId = createIdGenerator();
const id = generateId();

console.log(id);
// fierce-zebra-456

With a custom separator:

import { createIdGenerator } from '@corentinth/friendly-ids';

const generateId = createIdGenerator({ separator: '_' });
const id = generateId();

console.log(id);
// brave_horse_537

All options:

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 and animals. You can use them to customize your generator:

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:

# one shot
pnpm run test

# watch mode
pnpm run test:watch

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Credits and Acknowledgements

This project is crafted with ❤️ by Corentin Thomasset. If you find this project helpful, please consider supporting my work.

版本与发布记录

@corentinth/friendly-ids 共发布 1 个版本,首次发布于 2025/01/23;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.0.1latest2025/01/231.8 年前

关于 @corentinth/friendly-ids 的常见问题

@corentinth/friendly-ids 是什么?

A human friendly ID generator

如何安装 @corentinth/friendly-ids?

在项目目录运行 npm install @corentinth/friendly-ids,或使用 pnpm add / yarn add / bun add。

@corentinth/friendly-ids 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@corentinth/friendly-ids 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@corentinth/friendly-ids 可以商用吗?

@corentinth/friendly-ids 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@corentinth/friendly-ids 的下载量有多少?

根据 npm 官方下载统计,@corentinth/friendly-ids 在 2026/10/11 – 2026/11/09 这 30 天内被下载 1,972 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@corentinth/friendly-ids 还在维护吗?

最新版本 0.0.1 发布于 2025/01/23(1.8 年前);至今共发布 1 个版本,其中过去 12 个月发布了 0 个;首次发布于 2025/01/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。