{"id":16752495,"url":"https://github.com/jprochazk/dice-roll-eval","last_synced_at":"2025-04-05T07:09:02.906Z","repository":{"id":39703101,"uuid":"303006775","full_name":"jprochazk/dice-roll-eval","owner":"jprochazk","description":"JS module used for evaluating standard dice notation","archived":false,"fork":false,"pushed_at":"2023-01-06T15:12:51.000Z","size":990,"stargazers_count":1,"open_issues_count":12,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-10T14:51:50.619Z","etag":null,"topics":["javascript","standard-dice-notation"],"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/jprochazk.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":"2020-10-10T23:23:31.000Z","updated_at":"2020-12-31T01:48:57.000Z","dependencies_parsed_at":"2023-02-06T05:47:02.020Z","dependency_job_id":null,"html_url":"https://github.com/jprochazk/dice-roll-eval","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprochazk%2Fdice-roll-eval","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprochazk%2Fdice-roll-eval/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprochazk%2Fdice-roll-eval/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprochazk%2Fdice-roll-eval/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jprochazk","download_url":"https://codeload.github.com/jprochazk/dice-roll-eval/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299843,"owners_count":20916192,"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":["javascript","standard-dice-notation"],"created_at":"2024-10-13T02:47:13.297Z","updated_at":"2025-04-05T07:09:02.884Z","avatar_url":"https://github.com/jprochazk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dice-roll-eval\n\n\u003cp align=\"center\"\u003e\n    \u003ca href='https://travis-ci.com/jprochazk/dice-roll-eval'\u003e\n        \u003cimg src='https://travis-ci.org/jprochazk/dice-roll-eval.svg?branch=master' alt='Build Status' /\u003e\n    \u003c/a\u003e\n    \u003ca href='https://coveralls.io/github/jprochazk/dice-roll-eval?branch=master'\u003e\n        \u003cimg src='https://coveralls.io/repos/github/jprochazk/dice-roll-eval/badge.svg?branch=master' alt='Coverage Status' /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nJS module used for evaluating standard dice notation expressions. The module can actually evaluate simple mathematical expressions, consisting of integers and operators `+`, `-`, `*`, `/`, as well as sub-expressions enclosed in parentheses. To (mostly) comply with standard dice notation, an additional operator is implemented: `d`. This operator takes the form `AdX` or `dX`, where `A` is the number of rolls of `X`-sided die.\n\n### Expression examples\n\n```\n5d6 -\u003e rolls a 6-sided die, 5 times\n5d6 + 10 -\u003e rolls a 6-sided die, 5 times, and adds 10 to the result.\n5d6 / 2 -\u003e rolls a 6-sided die, 5 times, and divides the result by 2.\n(10*10)d(10*10) -\u003e rolls a (10*10)-sided die, (10*10) times.\n```\n\n### Usage\n\nExpressions are passed as plain strings to the module, which returns a number. The evaluation may throw.\n\n```js\nconst evaluate = require(\"dice-roll-eval\");\n\nconst result = evaluate(\"5d6 + 10\");\n// ...\n```\n\n`evaluate` also takes two optional parameters, `limit` and `rng`. \n\n`limit`: A dice roll like `5d6` will roll a 6-sided die 5 times. These rolls have to be executed in sequence, and in this library, that is done inside of a while loop. This stalls the event loop. To ensure that a user can't do something like `(1/0)d6` (i.e. roll a D6 Infinity times), you can set the maximum number of sequential rolls. The default is 10.\n\n`rng`: The random number generation function, which must have the following signature:\n\n```js\n(min: number, max: number) =\u003e number;\n```\n\nThe `min` and `max` numbers specify the range in which values should be generated, e.g. the call `YOUR_RNG_FUNCTION(10, 2000)` should generate a number within the range \u003c10; 2000\u003e. This parameter exists so that you can provide your own RNG implementation, such as a [Mersenne Twister](https://en.wikipedia.org/wiki/Mersenne_Twister). The default implementation uses `Math.random` and can be found [here](https://github.com/jprochazk/dice-roll-eval/blob/master/index.js#L5).\n\n### Tests\n\nTests are built with [Jest](https://jestjs.io/).\n\n```\n$ yarn test\n```\n\n### Notes\n\nBuilt for [supi-core](https://github.com/Supinic/supi-core).\n\nThis was my excuse to learn more about parsing strings. Yes, it is slightly overkill... :)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjprochazk%2Fdice-roll-eval","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjprochazk%2Fdice-roll-eval","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjprochazk%2Fdice-roll-eval/lists"}