# @lazy-random/df-char-id

> 以自訂字元表 (Alphabet) 產生隨機字串 ID 的取樣函式 (Random Sampling Function)，屬 @lazy-random 系列的分佈函式 (Distribution Function) 套件

Latest version **2.0.1** (published 2026-10-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install @lazy-random/df-char-id
pnpm add @lazy-random/df-char-id
yarn add @lazy-random/df-char-id
bun add @lazy-random/df-char-id
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-10-05 |
| First published | 2021-12-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 54.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | bluelovers |
| Maintainers | bluelovers |
| Keywords | df-char-id, char-id, random-string, string, id, alphabet, token, invite-code, short-url, nanoid, prng, rng, random, lazy-random, create-by-yarn-tool, create-by-tsdx |

## Links

- npm: https://www.npmjs.com/package/@lazy-random/df-char-id
- Repository: https://github.com/bluelovers/ws-random
- Homepage: https://github.com/bluelovers/ws-random/tree/master/packages/@lazy-random/df-char-id#readme
- Issues: https://github.com/bluelovers/ws-random/issues
- npm.io page: https://npm.io/package/@lazy-random/df-char-id

## Dependencies (5)

- [uni-string](https://npm.io/package/uni-string.md) ^2.0.10
- [@lazy-random/expect](https://npm.io/package/@lazy-random/expect.md) ^2.0.1
- [@lazy-random/shared-lib](https://npm.io/package/@lazy-random/shared-lib.md) ^2.0.1
- [@lazy-num/float-to-string](https://npm.io/package/@lazy-num/float-to-string.md) ^2.0.1
- [@lazy-random/util-distributions](https://npm.io/package/@lazy-random/util-distributions.md) ^2.0.1

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-10-05
- 1.0.15 — 2023-11-20
- 1.0.14 — 2023-11-19
- 1.0.12 — 2022-10-29
- 1.0.11 — 2022-01-03
- 1.0.9 — 2021-12-21
- 1.0.6 — 2021-12-12

## README

# @lazy-random/df-char-id

以自訂字元表 (Alphabet) 產生隨機字串 ID 的取樣函式 (Random Sampling Function)，屬於 `@lazy-random` 系列的分佈函式 (Distribution Function) 套件。

傳入亂數來源 (RNG)、字元表與長度，回傳可反覆呼叫的取樣函式 (Sampler)；每次呼叫都會產生一組新的隨機字串，適合用於短網址、邀請碼、測試資料等情境。

## 特色 (Features)

- 字元表 (Alphabet) 可指定為 `ENUM_ALPHABET` 列舉、任意字串、`Buffer` 或數字
- 字元表為數字時可自動轉成字串（透過 `@lazy-num/float-to-string`）
- 支援以 `uni-string` 切分，正確處理代理對 (Surrogate Pair) 等非 BMP 字元
- 字元表不足兩個字元會立即拋出錯誤，避免產生單一字元的弱 ID

## 安裝 (Installation)

```bash
yarn add @lazy-random/df-char-id
yarn-tool add @lazy-random/df-char-id
yt add @lazy-random/df-char-id
```

## 使用方式 (Usage)

```ts
import { dfCharID } from '@lazy-random/df-char-id'

// 亂數來源需提供 next()，回傳 [0, 1) 的均勻亂數
const random = {
	next: () => Math.random(),
}

// 使用預設字元表與預設長度 8
const id = dfCharID(random)
console.log(id()) // 例如 "k3Za9Qp1"

// 指定字元表與長度
const hex = dfCharID(random, '0123456789abcdef', 6)
console.log(hex()) // 例如 "9c04ef"
```

## API 文件

### dfCharID(random, char?, size?)

建立字串取樣函式 (String Sampler)。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `random` | `IRNGLike` | 亂數來源 (Random Number Generator)，需提供 `next()` |
| `char` | `ENUM_ALPHABET \| string \| Buffer \| number` | 字元表 (Alphabet)；省略時使用 `ENUM_ALPHABET.DEFAULT` |
| `size` | `number` | 產生的字元數，需為正整數 (`> 0`)，預設 `8` |

- 當 `char` 為 `number` 且同時傳入 `size` 時，`char` 會被轉為字串字元表
- 當 `char` 為 `number` 但**未**傳入 `size` 時，該數字會被視為 `size`、字元表改用預設值

- 回傳值 (Returns)：無參數的取樣函式，每次呼叫回傳長度 `size` 的字串
- 例外 (Throws)：`size` 非正整數，或字元表切分後少於 2 個字元時，於建立時拋出驗證錯誤 (Validation Error)

## 開發 (Development)

```bash
pnpm run build
pnpm run lint
pnpm run test:jest
```

## 變更日誌 (Changelog)

請見 [CHANGELOG.md](./CHANGELOG.md)。

## 常見問題 (FAQ)

### 為什麼字元表至少要 2 個字元？

單一字元表只能產生固定字串，沒有隨機性可言；`expect(ls).lengthOf.gt(1)` 會在建立時就攔下這種設定。

### 可以用中文或 emoji 當字元表嗎？

可以。字元表透過 `uni-string` 切分，會依字元 (Code Point) 而非 16 位元單位 (UTF-16 Code Unit) 拆分，因此代理對字元（如 emoji）不會被切成半個字元。

### `char` 傳數字時的行為？

同時傳入 `size` 時，數字會轉成字串當字元表；只傳數字不傳 `size` 時，該數字代表 `size`（見上方 API 說明）。

## 相關資源 (Resources)

- [Repository](https://github.com/bluelovers/ws-random/tree/master/packages/@lazy-random/df-char-id#readme)
- [Issues](https://github.com/bluelovers/ws-random/issues)

---
_Source: https://npm.io/package/@lazy-random/df-char-id · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._