{"id":22945094,"url":"https://github.com/seregpie/justmyluck","last_synced_at":"2025-04-01T21:43:42.932Z","repository":{"id":57287403,"uuid":"176548477","full_name":"SeregPie/JustMyLuck","owner":"SeregPie","description":"A collection of utility functions for working with randomness.","archived":false,"fork":false,"pushed_at":"2020-06-15T16:40:55.000Z","size":110,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T09:41:26.271Z","etag":null,"topics":["array","boolean","chance","combination","date","float","integer","luck","mersenne-twister","permutation","random","range","sample","shuffle","string","weight"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SeregPie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-19T15:54:08.000Z","updated_at":"2020-06-15T16:40:57.000Z","dependencies_parsed_at":"2022-09-01T06:53:48.191Z","dependency_job_id":null,"html_url":"https://github.com/SeregPie/JustMyLuck","commit_stats":null,"previous_names":["seregpie/glossywheel"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeregPie%2FJustMyLuck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeregPie%2FJustMyLuck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeregPie%2FJustMyLuck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SeregPie%2FJustMyLuck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SeregPie","download_url":"https://codeload.github.com/SeregPie/JustMyLuck/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246716830,"owners_count":20822527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["array","boolean","chance","combination","date","float","integer","luck","mersenne-twister","permutation","random","range","sample","shuffle","string","weight"],"created_at":"2024-12-14T14:29:40.381Z","updated_at":"2025-04-01T21:43:42.911Z","avatar_url":"https://github.com/SeregPie.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JustMyLuck\n\nA collection of utility functions for working with randomness.\n\n## setup\n\n### npm\n\n```shell\nnpm i just-my-luck\n```\n\n### ES module\n\n```javascript\nimport JustMyLuck from 'just-my-luck';\n```\n\n### Node\n\n```javascript\nlet JustMyLuck = require('just-my-luck');\n```\n\n### browser\n\n```html\n\u003cscript src=\"https://unpkg.com/just-my-luck\"\u003e\u003c/script\u003e\n```\n\nThe module is globally available as `JustMyLuck`.\n\n## members\n\n### static properties\n\n`.random = Math.random`\n\n---\n\n`.MersenneTwister(seed)`\n\nThe implementation of the Mersenne Twister pseudo-random number generator.\n\n| argument | description |\n| ---: | :--- |\n| `seed` | A number as the initial seed. |\n\nReturns the pseudo-random number generator as a function.\n\n```javascript\nlet random = JustMyLuck.MersenneTwister(835);\nconsole.log(random()); // =\u003e 0.7212939869047637\nconsole.log(random()); // =\u003e 0.2532498844651273\n```\n\n---\n\n`.lowerCasedAlphabetic = 'abcdefghijklmnopqrstuvwxyz'`\n\n---\n\n`.upperCasedAlphabetic = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'`\n\n---\n\n`.alphabetic = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'`\n\n---\n\n`.numeric = '0123456789'`\n\n---\n\n`.lowerCasedAlphanumeric = 'abcdefghijklmnopqrstuvwxyz0123456789'`\n\n---\n\n`.upperCasedAlphanumeric = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'`\n\n---\n\n`.alphanumeric = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'`\n\n### constructor\n\n`new JustMyLuck(random)`\n\n| argument | description |\n| ---: | :--- |\n| `random` | A function that returns a float greater than or equal to 0 and less than 1. |\n\n```javascript\nlet seed = Date.now();\nlet luck1 = new JustMyLuck(JustMyLuck.MersenneTwister(seed));\nlet luck2 = new JustMyLuck(JustMyLuck.MersenneTwister(seed));\nlet integer1 = luck1.integer(-2, 2, true);\nlet integer2 = luck2.integer(-2, 2, true);\nconsole.log(integer1 === integer2); // =\u003e true;\n```\n\n### instance properties\n\n`.random`\n\nThe pseudo-random number generator.\n\n### static and instance methods\n\n`.chance(p)`\n\nTests the chance with a probability.\n\n| argument | description |\n| ---: | :--- |\n| `p` | A number as the probability. |\n\nReturns a boolean.\n\n```javascript\nlet x = JustMyLuck.chance(0.38);\n// =\u003e either true (38%) or false (62%)\n```\n\n```javascript\nconsole.log(JustMyLuck.chance(-Infinity)); // =\u003e false\nconsole.log(JustMyLuck.chance(-1.57)); // =\u003e false\nconsole.log(JustMyLuck.chance(0)); // =\u003e false\n\nconsole.log(JustMyLuck.chance(1)); // =\u003e true\nconsole.log(JustMyLuck.chance(42)); // =\u003e true\nconsole.log(JustMyLuck.chance(Infinity)); // =\u003e true\n```\n\n---\n\n`.boolean()`\n\nGenerates a boolean.\n\nReturns the generated boolean.\n\n```javascript\nlet boolean = JustMyLuck.boolean();\n// =\u003e either true or false\n```\n\n---\n\n`.booleanWeighted(weight)`\n\nGenerates a boolean using a weighted probability.\n\n| argument | description |\n| ---: | :--- |\n| `weight` | A number as the weighted probability. |\n\nReturns the generated boolean.\n\n```javascript\nlet boolean = JustMyLuck.booleanWeighted(3);\n// =\u003e either true (75%) or false (25%)\n```\n\n```javascript\nconsole.log(JustMyLuck.booleanWeighted(-1.57)); // =\u003e false\nconsole.log(JustMyLuck.booleanWeighted(0)); // =\u003e false\n\nconsole.log(JustMyLuck.booleanWeighted(Infinity)); // =\u003e true\n```\n\n---\n\n`.float(min, max, inclusive = false)`\n\nGenerates a float within a range.\n\n| argument | description |\n| ---: | :--- |\n| `min` | A number as the inclusive minimum. |\n| `max` | A number as the exclusive maximum. |\n| `inclusive` | If `true`, the maximum is inclusive. |\n\nReturns the generated float.\n\n```javascript\nlet float = JustMyLuck.float(0.4, 2.7);\n// =\u003e a float greater than or equal to 0.4 and less than 2.7\n```\n\n```javascript\nlet float = JustMyLuck.float(0.4, 2.7, true);\n// =\u003e a float greater than or equal to 0.4 and less than or equal to 2.7\n```\n\n```javascript\nlet float = 6.5;\nconsole.log(JustMyLuck.float(float, float, true) === float); // =\u003e true\n```\n\n---\n\n`.integer(min, max, inclusive = false)`\n\nGenerates an integer within a range.\n\n| argument | description |\n| ---: | :--- |\n| `min` | A number as the inclusive minimum. |\n| `max` | A number as the exclusive maximum. |\n| `inclusive` | If `true`, the maximum is inclusive. |\n\nReturns the generated integer.\n\n```javascript\nlet integer = JustMyLuck.integer(2, 11);\n// =\u003e an integer greater than or equal to 2 and less than 11\n```\n\n```javascript\nlet integer = JustMyLuck.integer(2, 11, true);\n// =\u003e an integer greater than or equal to 2 and less than or equal to 11\n```\n\n```javascript\nconsole.log(JustMyLuck.integer(4.3, 6.5) === 5); // =\u003e true\n```\n\n---\n\n`.string(alphabet, length)`\n\nGenerates a string using an alphabet.\n\n| argument | description |\n| ---: | :--- |\n| `alphabet` | An array-like or iterable object of characters as the alphabet. |\n| `length` | A number as the length of the string to generate. |\n\nReturns the generated string.\n\n```javascript\nlet string = JustMyLuck.string(JustMyLuck.alphabetic, JustMyLuck.integer(8, 16, true));\n// =\u003e e.g. 'eFEgkjWzTsTmA'\n```\n\n---\n\n`.date(min, max, inclusive = false)`\n\nGenerates a `Date` instance within a range.\n\n| argument | description |\n| ---: | :--- |\n| `min` | A `Date` instance as the inclusive minimum. |\n| `max` | A `Date` instance as the exclusive maximum. |\n| `inclusive` | If `true`, the maximum is inclusive. |\n\nReturns the generated `Date` instance.\n\n```javascript\nlet date = JustMyLuck.date(new Date('01 Jan 1970'), new Date('04 Dec 1995'));\n// =\u003e e.g. '1989-08-26T01:02:17.622Z'\n```\n\n```javascript\nlet date = new Date('04 Dec 1995');\nconsole.log(JustMyLuck.date(date, date, true).getTime() === date.getTime()); // =\u003e true\n```\n\n---\n\n`.pick(collection)`\n\nPicks a value from a collection.\n\n| argument | description |\n| ---: | :--- |\n| `collection` | An array-like or iterable object to pick from. |\n\nReturns the picked value.\n\n```javascript\nlet value = JustMyLuck.pick(['a', 'b', 'c']);\n// =\u003e either 'a', 'b' or 'c'\n```\n\n---\n\n`.pickWeighted(weightedCollection)`\n\nPicks a value from a collection using a weighted probability.\n\n| argument | description |\n| ---: | :--- |\n| `weightedCollection` | An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked. |\n\nReturns the picked value.\n\n```javascript\nlet value = JustMyLuck.pickWeighted([['a', 3.3], ['b', 0.7], ['c', 1]]);\n// =\u003e either 'a' (66%), 'b' (14%) or 'c' (20%)\n```\n\n```javascript\nlet value = JustMyLuck.pickWeighted([['a', Infinity], ['b', 1], ['c', 1]]);\n// =\u003e always 'a'\n```\n\n```javascript\nlet value = JustMyLuck.pickWeighted([['a', 0], ['b', 1], ['c', 1]]);\n// =\u003e either 'b' or 'c'\n```\n\n---\n\n`.pickIndex(array)`\n\nPicks an index from an array.\n\n| argument | description |\n| ---: | :--- |\n| `array` | An array-like object to pick the index from. |\n\nReturns the picked index.\n\n```javascript\nlet index = JustMyLuck.pickIndex(['a', 'b', 'c']);\n// =\u003e either 0, 1 or 2\n```\n\n---\n\n`.pickCombination(collection, count)`\n\nPicks a combination of values without repetition from a collection. Preserves the order of the values.\n\n| argument | description |\n| ---: | :--- |\n| `collection` | An array-like or iterable object to pick from. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickCombination(['a', 'b', 'c', 'd', 'e'], 3);\n// =\u003e e.g. ['a', 'b', 'd']\n```\n\n---\n\n`.pickCombinationWeighted(weightedCollection, count)`\n\nPicks a combination of values without repetition from a collection using a weighted probability. Preserves the order of the values.\n\n| argument | description |\n| ---: | :--- |\n| `weightedCollection` | An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickCombinationWeighted([['a', 2], ['b', 7], ['c', 8], ['d', 5], ['e', 8]], 3);\n// =\u003e e.g. ['a', 'c', 'e']\n```\n\n```javascript\nlet values = JustMyLuck.pickCombinationWeighted([['a', Infinity], ['b', 1], ['c', 0], ['d', 1], ['e', Infinity]], 3);\n// =\u003e 'a' and 'e' are always included, 'c' is never included\n```\n\n---\n\n`.pickPermutation(collection, count)`\n\nPicks a permutation of values without repetition from a collection.\n\n| argument | description |\n| ---: | :--- |\n| `collection` | An array-like or iterable object to pick from. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickPermutation(['a', 'b', 'c', 'd', 'e'], 3);\n// =\u003e e.g. ['b', 'd', 'a']\n```\n\n---\n\n`.pickPermutationWeighted(weightedCollection, count)`\n\nPicks a permutation of values without repetition from a collection using a weighted probability.\n\n| argument | description |\n| ---: | :--- |\n| `weightedCollection` | An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickPermutationWeighted([['a', 2], ['b', 7], ['c', 8], ['d', 5], ['e', 8]], 3);\n// =\u003e e.g. ['c', 'e', 'a']\n```\n\n```javascript\nlet values = JustMyLuck.pickPermutationWeighted([['a', Infinity], ['b', 1], ['c', 0], ['d', 1], ['e', Infinity]], 3);\n// =\u003e 'a' and 'e' are always included, 'c' is never included\n```\n\n---\n\n`.pickMulticombination(collection, count)`\n\nPicks a combination of values with repetition from a collection. Preserves the order of the values.\n\n| argument | description |\n| ---: | :--- |\n| `collection` | An array-like or iterable object to pick from. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickMulticombination(['a', 'b'], 8);\n// =\u003e e.g. ['a', 'a', 'a', 'a', 'a', 'b', 'b', 'b']\n```\n\n---\n\n`.pickMulticombinationWeighted(weightedCollection, count)`\n\nPicks a combination of values with repetition from a collection using a weighted probability. Preserves the order of the values.\n\n| argument | description |\n| ---: | :--- |\n| `weightedCollection` | An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickMulticombinationWeighted([['a', 1], ['b', 3]], 8);\n// =\u003e e.g. ['a', 'b', 'b', 'b', 'b', 'b', 'b', 'b']\n```\n\n```javascript\nlet values = JustMyLuck.pickMulticombinationWeighted([['a', Infinity], ['b', 1]], 4);\n// =\u003e ['a', 'a', 'a', 'a']\n```\n\n```javascript\nlet values = JustMyLuck.pickMulticombinationWeighted([['a', 0], ['b', 1]], 4);\n// =\u003e ['b', 'b', 'b', 'b']\n```\n\n---\n\n`.pickMultipermutation(collection, count)`\n\nPicks a permutation of values with repetition from a collection.\n\n| argument | description |\n| ---: | :--- |\n| `collection` | An array-like or iterable object to pick from. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickMultipermutation(['a', 'b'], 8);\n// =\u003e e.g. ['a', 'a', 'b', 'b', 'a', 'a', 'b', 'a']\n```\n\n---\n\n`.pickMultipermutationWeighted(weightedCollection, count)`\n\nPicks a permutation of values with repetition from a collection using a weighted probability.\n\n| argument | description |\n| ---: | :--- |\n| `weightedCollection` | An array-like or iterable object of value-weight pairs. A value-weight pair is an array where the first item is the value and the second item is a number as the weighted probability for this value to be picked. |\n| `count` | A number as the count of the values to pick. |\n\nReturns the picked values as an array.\n\n```javascript\nlet values = JustMyLuck.pickMultipermutationWeighted([['a', 1], ['b', 3]], 8);\n// =\u003e e.g. ['b', 'b', 'b', 'a', 'b', 'b', 'b', 'b']\n```\n\n```javascript\nlet values = JustMyLuck.pickMultipermutationWeighted([['a', Infinity], ['b', 1]], 4);\n// =\u003e ['a', 'a', 'a', 'a']\n```\n\n```javascript\nlet values = JustMyLuck.pickMultipermutationWeighted([['a', 0], ['b', 1]], 4);\n// =\u003e ['b', 'b', 'b', 'b']\n```\n\n---\n\n`.shuffle(collection)`\n\nShuffles a collection.\n\n| argument | description |\n| ---: | :--- |\n| `collection` | An array-like or iterable object to shuffle. |\n\nReturns the shuffled collection as an array.\n\n```javascript\nlet values = JustMyLuck.shuffle([1, 2, 3, 4, 5]);\n// =\u003e e.g. [4, 3, 2, 5, 1]\n```\n\n---\n\n`.shuffleInPlace(array)`\n\nShuffles an array in place.\n\n| argument | description |\n| ---: | :--- |\n| `array` | An array-like object to shuffle. |\n\nReturns the same array but shuffled.\n\n## plugins\n\nWrite your own plugins to extend the library.\n\n```javascript\nimport JustMyLuck from 'just-my-luck';\n\nJustMyLuck.extend({\n  color() {\n    return `rgb(${[0, 0, 0].map(() =\u003e this.integer(0, 255, true)).join(',')})`;\n  },\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseregpie%2Fjustmyluck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseregpie%2Fjustmyluck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseregpie%2Fjustmyluck/lists"}