# @lazy-random/array-rand-index

> 產生陣列隨機索引 (Random Index) 的極簡工具，可作為洗牌 (Shuffle) 或抽籤演算法的預設取樣 (Sampling) 函式

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

## Install

```sh
npm install @lazy-random/array-rand-index
pnpm add @lazy-random/array-rand-index
yarn add @lazy-random/array-rand-index
bun add @lazy-random/array-rand-index
```

## 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 | 36.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | bluelovers |
| Maintainers | bluelovers |
| Keywords | array, array-rand-index, index, math-random, pick, random, random-index, random-integer, sample, sampling, shuffle, lazy-random, create-by-yarn-tool, create-by-tsdx |

## Links

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

## Dependencies (1)

- [@lazy-random/original-math-random](https://npm.io/package/@lazy-random/original-math-random.md) ^2.0.1

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-10-05
- 1.0.16 — 2023-11-19
- 1.0.14 — 2022-10-29
- 1.0.13 — 2022-01-03
- 1.0.11 — 2021-12-21
- 1.0.6 — 2021-12-12

## README

# @lazy-random/array-rand-index

產生陣列 (Array) 隨機索引 (Random Index) 的極簡工具，可作為洗牌 (Shuffle) 或抽籤演算法的預設取樣函式。

## 特色 (Features)

- 兩個函式：依長度取樣 `arrayRandIndexByLength`、依陣列取樣 `arrayRandIndex`
- 隨機數來源 (Random Source) 使用 `@lazy-random/original-math-random` 包裝的 `Math.random()`
- 相容多餘參數 (Rest Arguments) 的回呼 (Callback) 簽章，可直接作為 `fn` 參數傳入其他演算法
- 支援 TypeScript 型別宣告 (Type Declarations)

## 安裝 (Installation)

```bash
yarn add @lazy-random/array-rand-index
yarn-tool add @lazy-random/array-rand-index
yt add @lazy-random/array-rand-index
```

## 使用方式 (Usage)

### CommonJS

```js
const { arrayRandIndexByLength, arrayRandIndex } = require('@lazy-random/array-rand-index');
```

### ESM

```js
import { arrayRandIndexByLength, arrayRandIndex } from '@lazy-random/array-rand-index';
```

### 範例 (Examples)

```js
// 從長度 10 的範圍取出 0 ~ 9 的隨機索引
arrayRandIndexByLength(10); // 例如 7

// 直接對陣列取樣
const arr = ['a', 'b', 'c'];
arr[arrayRandIndex(arr)]; // 例如 'b'

// 作為其他演算法的預設 fn（如 @lazy-random/array-algorithm 的 swapAlgorithm）
import { swapAlgorithm } from '@lazy-random/array-algorithm';
swapAlgorithm(arr, false, arrayRandIndexByLength);
```

## API 文件 (API Reference)

### `arrayRandIndexByLength(len, ...argv): number`

回傳 `0` 至 `len - 1` 之間的隨機整數 (Random Integer)。

| 參數 (Parameter) | 型別 (Type) | 說明 (Description) |
| --- | --- | --- |
| `len` | `number` | 取樣範圍的長度（上界，不含） |
| `...argv` | `any[]` | 相容回呼簽章的多餘參數，目前未被使用 |

- 回傳 (Returns)：`number` — `Math.floor(_MathRandom() * len)` 的結果
- 邊界情況 (Edge Case)：`len <= 0` 或為 `NaN` 時會回傳 `0` 以外的非預期值（`Math.floor` 得到 `NaN` 或 `-1`），呼叫前請自行確認 `len` 為正整數

### `arrayRandIndex(array, ...argv): number`

對給定陣列取樣，回傳 `0` 至 `array.length - 1` 的隨機索引。

| 參數 (Parameter) | 型別 (Type) | 說明 (Description) |
| --- | --- | --- |
| `array` | `any[]` | 要取樣的陣列（僅使用其 `length`） |
| `...argv` | `any[]` | 相容回呼簽章的多餘參數，目前未被使用 |

- 回傳 (Returns)：`number` — 隨機索引
- 此函式也是套件的預設匯出 (Default Export)

## 開發 (Development)

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

## 變更日誌 (Changelog)

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

## FAQ

### 為什麼不直接用 `Math.random()`？

`arrayRandIndexByLength` 透過 `@lazy-random/original-math-random` 取得隨機數，確保使用的是「未被覆寫的原始 `Math.random()`」，避免與其他替換了全域隨機數來源的程式碼互相干擾。

### `len` 可以傳 0 或負數嗎？

不建議。內部沒有做參數驗證 (Parameter Validation)，`len <= 0` 或 `NaN` 會導致 `Math.floor` 回傳 `NaN` 或 `-1`，請由呼叫端保證傳入正整數。

## 相關資源 (Related Resources)

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

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