# @lazy-random/df-sum

> 產生「總和固定 (Fixed Sum)」的亂數 (Random Number) 數列的分佈 (Distribution) 套件，回傳可反覆呼叫的閉包 (Closure)

Latest version **3.0.0** (published 2026-10-13) · ISC license · 0 weekly downloads

## Install

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

## 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 | 3.0.0 |
| Published | 2026-10-13 |
| First published | 2021-12-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 9 |
| Unpacked size | 200.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | bluelovers |
| Maintainers | bluelovers |
| Keywords | array, df-sum, distribution, fixed-sum, generator, lazy-random, prng, random, random-array, random-sum, rng, stats, sum, create-by-yarn-tool, create-by-tsdx |

## Links

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

## Dependencies (9)

- [@lazy-num/sum](https://npm.io/package/@lazy-num/sum.md) ^3.0.0
- [lib-r-math.js](https://npm.io/package/lib-r-math.js.md) <2 >=1.0.94
- [array-hyper-unique](https://npm.io/package/array-hyper-unique.md) ^2.1.10
- [@lazy-random/expect](https://npm.io/package/@lazy-random/expect.md) ^2.0.1
- [@lazy-random/df-uniform](https://npm.io/package/@lazy-random/df-uniform.md) ^2.0.1
- [@lazy-random/rng-abstract](https://npm.io/package/@lazy-random/rng-abstract.md) ^2.0.1
- [@lazy-random/util-distributions](https://npm.io/package/@lazy-random/util-distributions.md) ^2.0.1
- [@lazy-random/util-probabilities](https://npm.io/package/@lazy-random/util-probabilities.md) ^2.0.1
- [@lazy-random/fake-lib-r-math-rng](https://npm.io/package/@lazy-random/fake-lib-r-math-rng.md) ^2.0.1

## Recent versions

- 3.0.0 (latest) — 2026-10-13
- 2.0.1 — 2026-10-05
- 1.0.13 — 2023-11-19
- 1.0.11 — 2022-10-29
- 1.0.10 — 2022-01-03
- 1.0.8 — 2021-12-21
- 1.0.5 — 2021-12-12

## README

# @lazy-random/df-sum

產生「總和固定 (Fixed Sum)」的亂數 (Random Number) 數列的分佈 (Distribution) 套件，回傳一個可反覆呼叫的閉包 (Closure)，每次呼叫即產生一組符合指定總和的數列。

支援整數版 `dfRandSumInt` 與浮點數版 `dfRandSumFloat`，可用於需要「湊出固定預算／固定總額」的抽樣情境，例如配點、分配權重、模擬消費金額等。

## 特色 (Features)

- 產生指定長度 `size`、總和 `sum` 的隨機數列 (Random Array)
- 內建整數版 `dfRandSumInt` 與浮點數版 `dfRandSumFloat`
- 可指定每個元素的範圍 `min` / `max`
- 浮點數版支援小數位數限制 `fractionDigits`
- 整數版支援 `limit` 調整抽樣嘗試次數，並附帶快取 (Cache) 後備值
- 透過 `expect` 驗證輸入參數，參數不合規時拋出錯誤 (Throw)

## 安裝 (Installation)

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

或使用 pnpm：

```bash
pnpm add @lazy-random/df-sum
```

## 使用方式 (Usage)

### 整數版 `dfRandSumInt`

```ts
import { dfRandSumInt } from '@lazy-random/df-sum';

// 產生 5 個總和為 100 的整數
const gen = dfRandSumInt(random, 5, 100);

const values = gen();
console.log(values);
```

### 浮點數版 `dfRandSumFloat`

```ts
import { dfRandSumFloat } from '@lazy-random/df-sum';

// 產生 3 個總和為 1 的浮點數，並限制小數位數為 5 位
const gen = dfRandSumFloat(random, 3, 1, undefined, undefined, 5);

const values = gen();
console.log(values);
```

## API 文件 (API Documentation)

### `dfRandSumInt(random, size, sum?, min?, max?, limit?)`

建立產生整數數列的產生器函式 (Generator Function)。

| 參數 (Parameter) | 型別 (Type) | 預設值 | 說明 |
| --- | --- | --- | --- |
| `random` | `IRNGLike` | — | 亂數來源 (Random Number Generator)，需實作 `next()` |
| `size` | `number` | — | 數列長度，必須為大於 1 的整數 |
| `sum` | `number?` | `sum_1_to_n(size)` | 期望總和；未指定時取 `1+2+...+size` |
| `min` | `number?` | `sum > 0 ? 0 : sum` | 每個元素的下限 (Minimum) |
| `max` | `number?` | `Math.abs(sum)` | 每個元素的上限 (Maximum) |
| `limit` | `number?` | `5` | 每次抽樣嘗試的規模，數值越低越快但越容易失敗 |

**回傳 (Returns)**：`() => number[]` — 每次呼叫回傳一組長度為 `size`、總和為 `sum` 的整數數列。

**拋出 (Throws)**：

- 參數驗證失敗時（例如 `size <= 1`、非整數等）拋出錯誤。
- 找不到可行解時拋出 `can't generator value by current input argv, or try set limit for high number`，此時可調整 `limit`。

### `dfRandSumFloat(random, size, sum?, min?, max?, fractionDigits?)`

建立產生浮點數數列的產生器函式。

| 參數 (Parameter) | 型別 (Type) | 預設值 | 說明 |
| --- | --- | --- | --- |
| `random` | `IRNGLike` | — | 亂數來源，需實作 `next()` |
| `size` | `number` | — | 數列長度，必須為大於 1 的整數 |
| `sum` | `number?` | `1.0` | 期望總和；未指定且有 `min`/`max` 時取 `(size - 1) * min + max` |
| `min` | `number?` | `sum > 0 ? 0 : sum` | 每個元素的下限 |
| `max` | `number?` | `Math.abs(sum)` | 每個元素的上限 |
| `fractionDigits` | `number?` | — | 小數位數 (Fraction Digits)，須為大於 0 的整數 |

**回傳 (Returns)**：`() => number[]` — 每次呼叫回傳一組長度為 `size`、總和約為 `sum` 的浮點數數列。

## 設定 (Configuration)

本套件無額外設定檔，所有行為皆由上述函式參數控制。

## 開發 (Development)

```bash
pnpm run test
pnpm run build
```

## 變更日誌 (Changelog)

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

## 相關資源 (Related Resources)

- [Repository](https://github.com/bluelovers/ws-random)

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