# @lazy-random/bytes-to-uuid

> 將位元組陣列 (Byte Array) 格式化為 UUID (Universally Unique Identifier) 字串的小工具

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

## Install

```sh
npm install @lazy-random/bytes-to-uuid
pnpm add @lazy-random/bytes-to-uuid
yarn add @lazy-random/bytes-to-uuid
bun add @lazy-random/bytes-to-uuid
```

## 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 | 1 |
| Unpacked size | 60.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | bluelovers |
| Maintainers | bluelovers |
| Keywords | byte-array, bytes-to-uuid, format, guid, hex, hex-string, lookup-table, string, uuid, universally-unique-identifier, lazy-random, create-by-yarn-tool, create-by-tsdx |

## Links

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

## Dependencies (1)

- [@lazy-random/shared-lib](https://npm.io/package/@lazy-random/shared-lib.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.14 — 2023-11-19
- 1.0.12 — 2022-10-29
- 1.0.11 — 2022-01-03
- 1.0.10 — 2021-12-21
- 1.0.5 — 2021-12-12

## README

# @lazy-random/bytes-to-uuid

將位元組陣列 (Byte Array) 格式化為 UUID (Universally Unique Identifier) 字串的小工具，例如把 16 個位元組轉成 `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` 形式。

## 特色 (Features)

- 直接以查表 (Lookup Table) 加上 `Array.join()` 組出 UUID 字串，避免字串串接 (String Concatenation) 造成的記憶體問題
- 提供工廠函式 (Factory Function) `_createBytesToUuidFn`，可自訂十六進位轉換表 (Hex Lookup Table)，例如改用大寫或帶 `0x` 前綴
- 支援 `offset` 從陣列的任意位置開始讀取
- 支援 TypeScript 型別宣告 (Type Declarations)

## 安裝 (Installation)

```bash
yarn add @lazy-random/bytes-to-uuid
yarn-tool add @lazy-random/bytes-to-uuid
yt add @lazy-random/bytes-to-uuid
```

## 使用方式 (Usage)

### CommonJS

```js
// 預設匯出 (Default Export)
const bytesToUuid = require('@lazy-random/bytes-to-uuid');

// 或取得具名匯出 (Named Export)
const { bytesToUuid: toUuid, _createBytesToUuidFn } = require('@lazy-random/bytes-to-uuid');
```

### ESM

```js
// 預設匯出 (Default Export) 與具名匯出 (Named Export) 等同
import bytesToUuid, { _createBytesToUuidFn } from '@lazy-random/bytes-to-uuid';
```

### 範例 (Examples)

```js
const buf = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77,
	0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff];

bytesToUuid(buf);           // '00112233-4455-6677-8899-aabbccddeeff'
bytesToUuid(buf, 0);        // 同上，offset 省略時由 0 開始
```

```js
// 以工廠函式 (Factory Function) 固定一份十六進位轉換表 (Hex Lookup Table)
const toUuid = _createBytesToUuidFn();

toUuid(buf); // '00112233-4455-6677-8899-aabbccddeeff'
toUuid(buf, 4); // 由第 5 個位元組開始讀取；超出範圍的位元組會得到 undefined，
// 在 join('') 時被略過，因此輸出會比正常的 UUID 短
```

## API 文件 (API Reference)

### `bytesToUuid(buf, offset?, bth?): string`

將 `buf` 中自 `offset` 起的 16 個位元組轉為小寫十六進位的 UUID 字串。

| 參數 (Parameter) | 型別 (Type) | 預設值 (Default) | 說明 (Description) |
| --- | --- | --- | --- |
| `buf` | `ArrayLike<number>` | — | 來源位元組陣列 (Byte Array) |
| `offset` | `number` | `0` | 起始位置；`undefined` 或 `0` 都會由 `0` 開始 |
| `bth` | 十六進位轉換表 | `BYTE_TO_HEX_TO_LOWER_CASE` | 位元組轉兩位十六進位字串的查表 (Lookup Table)，來自 `@lazy-random/shared-lib` |

- 回傳 (Returns)：`string` — `8-4-4-4-12` 分段、以 `-` 連接的 UUID 字串
- 此函式也是套件的預設匯出 (Default Export)
- 靈感來源 (Reference Implementation)：[node-uuid `bytesToUuid`](https://github.com/kelektiv/node-uuid/blob/master/lib/bytesToUuid.js)

### `_createBytesToUuidFn(bth?): (buf, offset?) => string`

工廠函式 (Factory Function)：回傳一個與 `bytesToUuid` 相同邏輯、但 `bth` 已固定的轉換函式，適合在迴圈中重複使用時省去每次傳入查表。

| 參數 (Parameter) | 型別 (Type) | 預設值 (Default) | 說明 (Description) |
| --- | --- | --- | --- |
| `bth` | 十六進位轉換表 | `BYTE_TO_HEX_TO_LOWER_CASE` | 位元組轉十六進位字串的查表 |

- 回傳 (Returns)：`(buf: ArrayLike<number>, offset?: number) => string`

> **注意 (Note)**：`bth` 需為「以位元組值（0–255）為索引、值為兩位字串」的查表；本套件未提供現成的大寫查表，如需大寫格式請自備查表或於轉換後呼叫 `toUpperCase()`。

## 開發 (Development)

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

## 變更日誌 (Changelog)

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

## FAQ

### 為什麼不直接用字串串接 (String Concatenation)？

實作刻意改用陣列 `join('')`，原因是 V8 在大量字串串接時會有記憶體問題，詳見原始碼中的 [V8 issue #3175 說明](https://bugs.chromium.org/p/v8/issues/detail?id=3175#c4)。

### `buf` 長度不足 16 個位元組會怎樣？

函式不會做長度驗證 (Length Validation)。超出範圍的索引會取得 `undefined`，在 `join('')` 時被略過，因此會回傳「長度不足」的畸形 UUID 字串而非拋出錯誤，請由呼叫端保證 `buf` 至少有 `offset + 16` 個位元組。

### `bytesToUuid` 與 `_createBytesToUuidFn` 該用哪一個？

偶爾呼叫一次用 `bytesToUuid` 即可；若在同一個迴圈中反覆轉換、且 `bth` 固定不變，建議用 `_createBytesToUuidFn` 建立一次後重複使用。

## 相關資源 (Related Resources)

- [套件原始碼 (Repository)](https://github.com/bluelovers/ws-random/tree/master/packages/@lazy-random/bytes-to-uuid)
- [問題回報 (Issue Tracker)](https://github.com/bluelovers/ws-random/issues)

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