A pseudo-random array shuffling library using Permuted Congruential Generator (PCG) for high-quality randomness with 2^64 period.
npm install @tuki0918/seeded-shuffleA pseudo-random array shuffling library using Permuted Congruential Generator (PCG) for high-quality randomness.
- đ 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)
``bash`
npm i @tuki0918/seeded-shuffle
`typescript
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); // [2, 9, 8, 6, 7, 10, 5, 3, 4, 1] (deterministic)
// Using string seed
const shuffled2 = shuffle(array, "my-seed");
console.log(shuffled2); // [9, 2, 4, 8, 10, 7, 5, 6, 3, 1] (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!
``
This library uses a Permuted Congruential Generator (PCG) algorithm for high-quality randomness:
- Period: 2^64 (effectively unlimited for practical purposes)
- Performance: Fast generation suitable for high-volume applications
> [!WARNING]
> This is not suitable for cryptographic purposes.
MIT License - see LICENSE file for details.