# @kakegurui/shuffle

> Shuffle utilities for Kakegurui Games

Latest version **1.0.1** (published 2024-03-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @kakegurui/shuffle
pnpm add @kakegurui/shuffle
yarn add @kakegurui/shuffle
bun add @kakegurui/shuffle
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2024-03-25 |
| First published | 2024-03-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 25.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Ravener |
| Maintainers | ravener |
| Keywords | shuffle, kakegurui, gamble, gambling, riffle, gilbreath, random, deck, cards, pile, deal, casino |

## Links

- npm: https://www.npmjs.com/package/@kakegurui/shuffle
- Repository: https://github.com/kakegurui-club/shuffle
- Homepage: https://github.com/kakegurui-club/shuffle#readme
- Issues: https://github.com/kakegurui-club/shuffle/issues
- npm.io page: https://npm.io/package/@kakegurui/shuffle

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2024-03-25
- 1.0.0 — 2024-03-25

## README

# `@kakegurui/shuffle`
This module implements shuffle utilities assisting in implementing card-based games as seen in the Anime series Kakegurui.

## Install

Use your favorite package manager:

```sh
$ npm install @kakegurui/shuffle
$ yarn add @kakegurui/shuffle
$ pnpm install @kakegurui/shuffle
```

It supports both ESM and CJS and is written in TypeScript.

## Usage

Import the function you need, currently, there is:

- `shuffle` Basic shuffle using the [Fisher–Yates shuffle](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle) algorithm. This modifies the array in place.
- `riffleShuffle` Riffle shuffle between two decks.
- `gilbreathShuffle` Gilbreath shuffle as seen on the Nim Type Zero game in Kakegurui XX.
- `cutDeck` Shuffle a deck by 'cutting'
- `randomNumber` Get a random number within a given range.
- `riffleShuffle` Riffle shuffle two decks.
- `deal` Deals several cards onto a separate pile.

```ts
// ESM/TypeScript
import { shuffle } from '@kakegurui/shuffle';
// CommonJS
const { shuffle } = require('@kakegurui/shuffle');
```

### `shuffle(array)`

Shuffles an array in place using the Fisher-Yates/Knuth Shuffle algorithm.

```ts
const array = [1, 2, 3, 4, 5];
const shuffled = shuffle(array);

// Array is shuffled in place.
console.log(array === shuffled); // true

// If you want to preserve the original array, pass a copy.
const array2 = [1, 2, 3, 4, 5];
const shuffled2 = shuffle(array2.slice());

console.log(array2 === shuffled2); // false
```

### `randomNumber(start, end)`

Generates a random integer between the given `start` and `end` ranges.

```ts
// Random number between 1 to 5
const num = randomNumber(1, 5);

console.log(num); // Either 1, 2, 3, 4 or 5
```

### `riffleShuffle(deck1, deck2)`

Combines two decks with a riffle shuffle

```ts
const deck1 = [1, 2, 3];
const deck2 = [4, 5, 6];

const shuffled = riffleShuffle(deck1, deck2);
```

### `cutDeck(cards, cuts)`

Shuffles a deck of `cards` by randomly cutting the deck `cuts` times. The array is modified in place.

```ts
const deck = [1, 2, 3, 4, 5, 6, 7, 8, 9];
const shuffled = cutDeck(deck, 10);

// Array is modified in place.
console.log(deck === shuffled);

// You can cut the deck several times using randomNumber.
const shuffled = cutDeck(deck, randomNumber(1, 10));
```

### `deal(cards, numCards)`

Deals `numCards` from the top of the `cards`, top here meaning the beginning of the array, it deals it one by one, therefore, the new pile will have the cards in reverse order.

```ts
const cards = [1, 2, 3, 4, 5, 6];
const pile = deal(cards, 3);

console.log(pile); // [3, 2, 1]
// Array is modified in place.
console.log(cards); // [4, 5, 6]
```

## `gilbreathShuffle(cards, split)`

<video src="https://github.com/kakegurui-club/shuffle/assets/31079629/66f2e100-26d3-4355-8749-a68c5a09c322"></video>

Performs a [Gilbreath Shuffle](https://en.wikipedia.org/wiki/Gilbreath_shuffle) on `cards` by first splitting the deck into a separate pile of `split` cards and then riffle shuffling them together.

```ts
const cards = [1, 2, 3, 4, 5, 6, 7, 8, 9];
const shuffled = gilbreathShuffle(cards, 4);

// Array is modified in place.
console.log(cards === shuffled);
```

For the true Kakegurui experience, we recommend cutting the deck using `cutDeck` a few times as well before doing a `gilbreathShuffle`

## License
[MIT](LICENSE)

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