{"_id":"@ajhgwdjnpm/quas-perferendis-velit","name":"@ajhgwdjnpm/quas-perferendis-velit","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ajhgwdjnpm/quas-perferendis-velit","version":"1.0.0","description":"

🎲 Random Seed Weighted Chooser

A random weighted item chooser with custom seed option for JS.

🎲 Random Seed Weighted Chooser

A random weighted item chooser with custom seed option for JS.

\n 🎲 Random Seed Weighted Chooser\n\n

\n A random weighted item chooser with custom seed option for JS.\n

\n

\n \"npm \n \"View \n \"Deploy\n

\n\r\n

\r\n \"Buy \"Sponsor\"/\r\n

\r\n\r\n\n## Documentation\n\nRead the **[official documentation](https://justinmahar.github.io/@ajhgwdjnpm/quas-perferendis-velit/)**.\n\n## Overview\n\nA random weighted item chooser with custom seed option for JavaScript.\n\nThis package allows you to choose an index from an array of weights (simplest case), or an object from an array of objects that each have a customizable `\"weight\"` property. \n\nIt also allows you to specify default weights, and to use your own seed for the pseudorandom number generator (PRNG).\n\n### Features include:\n\n- **🎲 Choose weighted items at random**\n - Randomly select items based on weights\n- **💪 Flexible and customizable**\n - Choose an index from an array of weights, or an object from an array of objects with weight properties\n- **🌱 Custom seed support**\n - Provide your own seed for full control of the PRNG results\n\n\r\n\r\n## Donate \r\n\r\nIf this project helped you, please consider buying me a coffee or sponsoring me. Your support is much appreciated!\r\n\r\n\"Buy \"Sponsor\"/\r\n\r\n\r\n\n## Table of Contents \n\n- [Documentation](#documentation)\n- [Overview](#overview)\n - [Features include:](#features-include)\n- [Donate](#donate)\n- [Table of Contents](#table-of-contents)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n - [Using An Array Of Weights](#using-an-array-of-weights)\n - [Using An Array Of Objects With Weight Properties](#using-an-array-of-objects-with-weight-properties)\n- [Bad Input](#bad-input)\n- [Examples](#examples)\n - [Weighted Random Index Choice Example](#weighted-random-index-choice-example)\n - [Weighted Random Item Choice Example](#weighted-random-item-choice-example)\n - [Lottery Example](#lottery-example)\n- [TypeScript](#typescript)\n- [Icon Attribution](#icon-attribution)\n- [Contributing](#contributing)\n- [⭐ Found It Helpful? Star It!](#-found-it-helpful-star-it)\n- [License](#license)\n\n## Installation\n\n```\nnpm i @ajhgwdjnpm/quas-perferendis-velit\n```\n\n## Quick Start\n\nTwo ways:\n\n- Randomly choose an index from an **array of weights**.\n- Randomly choose an object from an **array of objects with weight properties**.\n\n### Using An Array Of Weights\n\nYou can use an array of weight numbers to randomly choose an index in that array.\n\n```js\n\n// ...\n// Returns an index using the weights to determine chance, or -1 if empty.\nChooser.chooseWeightedIndex(arrayOfWeights);\n// Optionally, you can use a custom seed. Math.random() is used as the default.\nChooser.chooseWeightedIndex(arrayOfWeights, seed);\n// You can also specify a default weight to use if your array contains \n// non-numbers (this is a failsafe).\nChooser.chooseWeightedIndex(arrayOfWeights, seed, defaultWeight);\n```\n\nIf all weights are 0, -1 is returned.\n\n### Using An Array Of Objects With Weight Properties\n\nYou can use an array of objects, each with a weight property and number value, to randomly choose one of those objects.\n\n```js\nimport Chooser from \"@ajhgwdjnpm/quas-perferendis-velit\";\n\n// ...\n// Expects each object to have a \"weight\" property. Returns null if array is empty.\nChooser.chooseWeightedObject(arrayOfObjects);\n// Uses custom property key, default weight (if weight property is missing), and custom seed.\nChooser.chooseWeightedObject(\n arrayOfObjects,\n weightPropertyKey,\n defaultWeight,\n seed\n);\n```\n\nIf all weights are 0, null is returned.\n\n## Bad Input\n\nFor any non-object where an object is expected, or non-number weight where a number is expected:\n\n- That item will have the default weight. This will be `1` or the optional default value if provided.\n\nAll negative weights are treated as positive.\n\n## Examples\n\n### Weighted Random Index Choice Example\n\nIf all you need is an index, you can just use a number[] array of weights, like so:\n\n```js\nimport Chooser from \"@ajhgwdjnpm/quas-perferendis-velit\";\n\nlet arrayOfWeights = [10, 50, 35, 5];\n\n// Returns the randomly chosen index or -1 if the array is empty. \n// Uses Math.random() as the seed.\nChooser.chooseWeightedIndex(arrayOfWeights);\n// 10% chance of returning 0\n// 50% chance of returning 1\n// 35% chance of returning 2\n// 5% chance of returning 3\n```\n\nUnder the hood, this project uses a pseudorandom number generator (PRNG) that allows the developer to provide their own seed.\n\nSo if you want to provide your own seed, you can. Seeds can be any value (strings, numbers, etc):\n\n```js\n// Returns the randomly chosen index or -1 if the array is empty.\n// Will return the same result until the seed changes.\nlet seed = \"myseed\";\nChooser.chooseWeightedIndex(arrayOfWeights, seed); // 3\nChooser.chooseWeightedIndex(arrayOfWeights, seed); // 3\nChooser.chooseWeightedIndex(arrayOfWeights, seed); // Always 3\nseed = 12345;\nChooser.chooseWeightedIndex(arrayOfWeights, seed); // 1\nChooser.chooseWeightedIndex(arrayOfWeights, seed); // 1\nChooser.chooseWeightedIndex(arrayOfWeights, seed); // Always 1\n```\n\n### Weighted Random Item Choice Example\n\n```js\nlet iceCreamFlavors = [\n { flavor: \"chocolate\", weight: 3 },\n { flavor: \"vanilla\", weight: 1 },\n { flavor: \"piña colada\", weight: 6 }\n];\n\n// Returns the randomly chosen object based on their weights.\n// - Looks for a property called \"weight\"; default 1 if not found\n// - Uses Math.random() as the seed.\nChooser.chooseWeightedObject(iceCreamFlavors);\n// chocolate = 30% chance\n// vanilla = 10% chance\n// piña colada = 60% chance\n```\n\nYou can use any number property as the weight. Just provide the property key as the second argument, like so:\n\n```js\nlet restaurantRatings = [\n { name: \"Chipotle\", rating: 4.2 },\n { name: \"Moe's\", rating: 4.9 },\n { name: \"Dirty Bill's\", rating: 1.2 }\n];\n\n// This example uses restaurant ratings as weights.\nChooser.chooseWeightedObject(restaurantRatings, \"rating\");\n// Chipotle = 40.8% chance\n// Moe's = 47.6% chance\n// Dirty Bill's = 11.7% chance\n```\n\nIf the property is not found, the default weight is `1`. You can provide a default if you'd like. The seed defaults to `Math.random()`, but you can provide your own seed if you'd like as well:\n\n```js\nlet restaurantRatings = [\n { name: \"Chipotle\", rating: 4.2 },\n { name: \"Moe's\", rating: 4.9 },\n { name: \"Edgy Burrito\" } // Unrated restaurant\n];\n\n// Uses \"rating\" as weight, a default weight of 2.5, and a custom seed.\nlet seed = \"Brianna's pick\";\nChooser.chooseWeightedObject(restaurantRatings, \"rating\", 2.5, seed);\n// Chipotle = 36.2% chance\n// Moe's = 42.2% chance\n// Edgy Burrito = 21.6% chance (no rating property, so uses 2.5 default)\n```\n\n### Lottery Example\n\nBelow we have a lottery with 100000 items in the bag (weights total 100000).\n\n```js\nlet lottery = [\n { name: \"Impossible\", weight: 0 },\n { name: \"Nearly impossible\", weight: 1 },\n { name: \"Very low chance\", weight: 9 },\n { name: \"Low chance\", weight: 90 },\n { name: \"Medium chance\", weight: 900 },\n { name: \"High chance\", weight: 9000 },\n { name: \"Very high chance\", weight: 90000 }\n];\n\nChooser.chooseWeightedObject(lottery);\n// \"Nearly impossible\" has 1/100000 odds of occurring.\n```\n\n**🎉 Happy Random Seed Weighted Choosing! 🎉**\n\n\r\n\r\n## TypeScript\r\n\r\nType definitions have been included for [TypeScript](https://www.typescriptlang.org/) support.\r\n\r\n\r\n\n\r\n\r\n## Icon Attribution\r\n\r\nFavicon by [Twemoji](https://github.com/twitter/twemoji).\r\n\r\n\r\n\n\r\n\r\n## Contributing\r\n\r\nOpen source software is awesome and so are you. 😎\r\n\r\nFeel free to submit a pull request for bugs or additions, and make sure to update tests as appropriate. If you find a mistake in the docs, send a PR! Even the smallest changes help.\r\n\r\nFor major changes, open an issue first to discuss what you'd like to change.\r\n\r\n\n\n## ⭐ Found It Helpful? [Star It!](https://github.com/ajhgwdjnpm/quas-perferendis-velit/stargazers)\n\nIf you found this project helpful, let the community know by giving it a [star](https://github.com/ajhgwdjnpm/quas-perferendis-velit/stargazers): [👉⭐](https://github.com/ajhgwdjnpm/quas-perferendis-velit/stargazers)\n\n## License\n\nSee [LICENSE.md](https://justinmahar.github.io/@ajhgwdjnpm/quas-perferendis-velit/?path=/docs/license--docs).","readmeFilename":"README.md"}