seeded-shuffle

A deterministic reversible array shuffling library using seedable xoshiro128++ randomness.

Features

• 🔀 Shuffle: Deterministic array shuffling using Fisher-Yates algorithm
• ↩️ Unshuffle: Restore original order using the same seed
• 🎲 RandInt: Generate random integers within specified ranges
• 🎯 Choice: Random element selection from arrays (with/without replacement)

Installation

npm i @tuki0918/seeded-shuffle

Quick Start

Simple Array Shuffling

import { shuffle, unshuffle } from "@tuki0918/seeded-shuffle";

const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

// Using numeric seed
const shuffled1 = shuffle(array, 12345);
console.log(shuffled1); // [8, 6, 5, 2, 7, 10, 4, 9, 1, 3] (deterministic)

// Using string seed
const shuffled2 = shuffle(array, "my-seed");
console.log(shuffled2); // [5, 9, 7, 1, 3, 6, 4, 10, 8, 2] (deterministic)

// Same seed = same result
const shuffled3 = shuffle(array, 12345);
console.log(JSON.stringify(shuffled1) === JSON.stringify(shuffled3));

// Unshuffle: restore original order using the same seed
const restored1 = unshuffle(shuffled1, 12345);
console.log(restored1); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - back to original!

const restored2 = unshuffle(shuffled2, "my-seed");
console.log(restored2); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - back to original!

Algorithm

This library uses xoshiro128++ for deterministic pseudo-randomness:

• State size: 128-bit internal state derived from number or string seeds
• Period: 2^128 - 1 for non-zero generator states
• Performance: 32-bit integer operations only; no BigInt in hot paths
• Reversibility: Designed for large deterministic permutations such as pixel arrays, as long as the same seed and package major version are used

[!NOTE] Version 2 changes the seeded output sequence. The same seed remains deterministic, but it will not produce the same shuffle order as version 1.

[!WARNING] This is not suitable for cryptographic purposes.

Benchmarks

Run the benchmark suite to compare the current implementation with the latest stable baseline tag:

npm run benchmark

The benchmark uses node:perf_hooks and compares v1.0.1 with the current working tree by default. Override the comparison refs when needed:

BENCH_BASE_REF=v1.0.1 BENCH_CANDIDATE_REF=HEAD npm run benchmark

CI runs a shorter benchmark job with npm run benchmark:ci on Node.js 22. The CI job is intended to keep the benchmark script operational and publish timing logs; use local benchmark results for performance release notes.

License

MIT License - see LICENSE file for details.