# alea-deck

> Uniform and weighted shuffling and sampling with Alea

Latest version **5.0.6** (published 2026-09-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install alea-deck
pnpm add alea-deck
yarn add alea-deck
bun add alea-deck
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.6 |
| Published | 2026-09-04 |
| First published | 2014-07-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | 22 \|\| 24 \|\| >=26 |
| Dependencies | 2 |
| Unpacked size | 12.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Kenan Yildirim <kenan@kenany.me> (https://kenany.me/) |
| Maintainers | kenan |
| Keywords | alea, math, random |

## Links

- npm: https://www.npmjs.com/package/alea-deck
- Repository: https://github.com/kenany/alea-deck
- npm.io page: https://npm.io/package/alea-deck

## Dependencies (2)

- [alea-random](https://npm.io/package/alea-random.md) ^6.0.3
- [@thi.ng/checks](https://npm.io/package/@thi.ng/checks.md) ^3.11.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

- 5.0.6 (latest) — 2026-09-04
- 5.0.5 — 2026-09-03
- 5.0.4 — 2026-07-27
- 5.0.3 — 2026-07-12
- 5.0.2 — 2026-07-10
- 5.0.1 — 2026-06-11
- 5.0.0 — 2026-05-24
- 4.1.4 — 2025-06-06
- 4.1.3 — 2024-12-27
- 4.1.2 — 2024-07-11
- 4.1.1 — 2023-10-23
- 4.1.0 — 2023-09-21
- 4.0.1 — 2022-12-26
- 4.0.0 — 2022-12-01
- 3.0.0 — 2022-02-03
- … 11 more at https://npm.io/package/alea-deck/versions

## README

# alea-deck

Uniform and weighted shuffling and sampling, just like
[deck](https://github.com/substack/node-deck), but utilizing
[Alea](https://github.com/coverslide/node-alea) instead of `Math.random`.

## Example

``` javascript
import { shuffle, pick } from 'alea-deck';

shuffle([1, 2, 3, 4]);
// => [1, 4, 2, 3]

pick([1, 2, 3, 4]);
// => 2

shuffle({
  a: 10,
  b: 8,
  c: 2,
  d: 1,
  e: 1
});
// => ['b', 'a', 'c', 'd', 'e']

pick({
  a: 10,
  b: 8,
  c: 2,
  d: 1,
  e: 1
});
// => a
```

## Installation

``` bash
$ npm install alea-deck
```

## API

``` javascript
import { deck, shuffle, pick, normalize } from 'alea-deck';
```

### `deck(collection)`

Binds `shuffle` and `pick` to `collection`, returning an object with both
methods pre-applied.

``` javascript
const d = deck([1, 2, 3, 4]);

d.shuffle(); // => [3, 1, 4, 2]
d.pick();    // => 3
```

### `shuffle(collection)`

If `collection` is an _Array_, returns a new shuffled _Array_ based on a unifrom
distributionm without mutating the original _Array_.

Otherwise, if `collection` is an _Object_, returns a new shuffled _Array_ of
`collection`'s visible keys based on the value weights of `collection`.

### `pick(collection)`

Samples `collection` without mutating `collection`.

If `collection` is an _Array_, returns a random element from `collection` with a
uniform distribution.

Otherwise, if `collection` is an _Object_, returns a random key from
`collection` biased by its normalized value.

### `normalize(obj)`

Return a new `obj` _Object_ where the values have been divided by the sum of all
the values such that the sum of all the values in the returned _Object_ is 1.

If any weights are `< 0`, an _Error_ is thrown.

---
_Source: https://npm.io/package/alea-deck · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._