# @lazy-random/cross-crypto

> 在 Node.js 與瀏覽器環境之間以單一 API 取得加密安全亂數 (Cryptographically Secure Random) 的跨環境 (Cross-environment) 工具

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

## Install

```sh
npm install @lazy-random/cross-crypto
pnpm add @lazy-random/cross-crypto
yarn add @lazy-random/cross-crypto
bun add @lazy-random/cross-crypto
```

## 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 | 0 |
| Unpacked size | 76.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | bluelovers |
| Maintainers | bluelovers |
| Keywords | cross-crypto, crypto, random-bytes, randombytes, cryptographically-secure, secure-random, cross-env, getrandomvalues, polyfill, browser, lazy-random, typescript, create-by-yarn-tool, create-by-tsdx |

## Links

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

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-10-05
- 1.0.11 — 2023-11-19
- 1.0.9 — 2022-10-29
- 1.0.8 — 2022-01-03
- 1.0.6 — 2021-12-12

## README

# @lazy-random/cross-crypto

在 Node.js 與瀏覽器環境之間，以單一 API 取得加密安全的亂數 (Cryptographically Secure Random Number) 的跨環境 (Cross-environment) 工具套件。

套件會惰性 (Lazy) 解析目前環境可用的 `crypto` 實作並快取 (Cache) 起來，讓上層程式不需要自行判斷執行環境。

## 特色 (Features)

- 單一 API 同時適用於 Node.js 的 `require('crypto')` 與瀏覽器的 `global.crypto`
- 以閉包 (Closure) 快取解析結果，只初始化一次，避免重複載入
- 瀏覽器環境若只有 `getRandomValues`，會自動補上 (Polyfill) `randomBytes`
- 同時支援同步回傳與 `callback` 兩種呼叫方式
- 額外導出 `ICryptoLike` 介面 (Interface)，方便自行注入 (Inject) 相容實作

## 安裝 (Installation)

```bash
yarn add @lazy-random/cross-crypto
yarn-tool add @lazy-random/cross-crypto
yt add @lazy-random/cross-crypto
```

## 使用方式 (Usage)

```ts
import crossCrypto, { randomBytes } from '@lazy-random/cross-crypto'

// 取得目前環境可用的 crypto 實例（會被快取，重複呼叫不會重新初始化）
const crypto = crossCrypto()

// 同步取得 16 個位元組 (Bytes)
const buf = randomBytes(16)

// 也可以使用 callback 風格
crypto.randomBytes(8, (err, buf) =>
{
	if (err)
	{
		throw err
	}

	console.log(buf)
})
```

CommonJS 的用法：

```js
const { crossCrypto, randomBytes } = require('@lazy-random/cross-crypto')

const bytes = randomBytes(32)
```

## API 文件

### crossCrypto()

回傳目前環境可用的 `ICryptoLike` 實例；解析結果會在閉包內快取，後續呼叫直接回傳同一份實例。

- 回傳值 (Returns)：`ICryptoLike`
- 例外 (Throws)：`Error` — 環境完全不支援 `crypto` 時拋出 `not support crypto`

### randomBytes(size[, callback])

取得加密安全的隨機位元組 (Random Bytes)，內部等同於 `crossCrypto().randomBytes(size, callback)`。

| 參數 (Parameter) | 型別 (Type) | 說明 |
| --- | --- | --- |
| `size` | `number` | 要產生的位元組數 |
| `callback` | `(err: Error \| null, buf: Buffer) => void` | 選擇性的完成回呼 (Callback) |

- 回傳值 (Returns)：`Buffer`

> 在瀏覽器環境透過 `getRandomValues` 補齊時，單次 `size` 上限為 65536，超過會拋出 `requested too many random bytes`。

### ICryptoLike

描述 `crypto` 的最小共同介面 (Minimal Common Interface)：

- `randomBytes(size, callback?)`：必填 (Required)
- `getRandomValues?(array)`：選填 (Optional)，瀏覽器環境提供

## 開發 (Development)

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

## 變更日誌 (Changelog)

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

## 常見問題 (FAQ)

### 在瀏覽器中為什麼會得到 `Buffer`？

瀏覽器路徑的 `randomBytes` polyfill 會以 `Buffer.from` 包裝產生的位元組，以保持與 Node.js 相同的回傳型別，讓上層程式不需要分支處理。

### 可以自行注入其他 `crypto` 實作嗎？

可以，只要物件符合 `ICryptoLike` 介面即可；不過本套件的 `crossCrypto()` 目前只解析 `require('crypto')` 與全域 (Global) 的 `crypto`／`msCrypto`。

## 相關資源 (Resources)

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

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