knuth-shuffle-seeded

What is knuth-shuffle-seeded?

The knuth-shuffle-seeded npm package provides a seeded implementation of the Knuth (or Fisher-Yates) shuffle algorithm. This allows for reproducible shuffling of arrays, which can be useful in scenarios where deterministic results are needed, such as in testing or simulations.

What are knuth-shuffle-seeded's main functionalities?

Seeded Shuffle

This feature allows you to shuffle an array in a reproducible manner using a seed. The same seed will always produce the same shuffled array.

const shuffle = require('knuth-shuffle-seeded');
const seed = 'my-seed';
let array = [1, 2, 3, 4, 5];
shuffle(array, seed);
console.log(array);

Other packages similar to knuth-shuffle-seeded

seedrandom

The seedrandom package provides a seeded random number generator. While it does not directly shuffle arrays, it can be used in conjunction with custom shuffle algorithms to achieve similar functionality. It offers more control over random number generation compared to knuth-shuffle-seeded.

shuffle-seed

The shuffle-seed package provides a similar functionality to knuth-shuffle-seeded by allowing arrays to be shuffled in a reproducible manner using a seed. It offers a simple API for shuffling and unshuffling arrays based on a seed.

lodash.shuffle

The lodash.shuffle package is part of the Lodash library and provides a method to shuffle arrays. While it does not support seeding, it is widely used and well-documented, making it a popular choice for general-purpose shuffling.

README

knuth-shuffle-seeded

The Fisher-Yates (aka Knuth) shuffle for the browser and Node.js, with seeds support using seed-random.

This project is initially forked from [coolaj86/knuth-shuffle] (https://github.com/coolaj86/knuth-shuffle), but extended so that it is possible to specify a seed to use in the shuffling, to ensure test reproducability.

Getting Started

Node.js

npm install knuth-shuffle-seeded

Then look at example.js.

The Browser

Put shuffle.js into your js/. Then look at example.html.

Why not contribute to the original repo?

I have considered that, but the introduction of an npm dependency makes it necessary to use Browserify to generate a browser-compatible JavaScript file, which is too far away from the simple approach of knuth-shuffle.

Authors

AJ O'Neal (@coolaj86) -- initial author Timothy Gu (@TimothyGu) -- seed-random support

License

Copyright 2013 AJ O'Neal Copyright 2015 Tiancheng "Timothy" Gu

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Changelog

1.0.0: 2015-01-19

• Proper README.
• Example for using this module in the browser.

• Various fixes in package.json.
• Better error reporting on input not being an Array.
• JSDoc documentation.