@ironarachne/rng
Version:
A library for random number generation and various random ways of selecting items from arrays.
77 lines (67 loc) • 18.8 kB
HTML
<html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@ironarachne/rng</title><meta name="description" content="Documentation for @ironarachne/rng"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="index.html" class="title">@ironarachne/rng</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@ironarachne/rng</h1></div><div class="tsd-panel tsd-typography"><h1 id="ironarachnerng" class="tsd-anchor-link">@ironarachne/rng<a href="#ironarachnerng" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1><p>A comprehensive random number generation library for TypeScript and JavaScript. It provides a seeded random number generator (RNG) class for deterministic results, along with a set of global convenience functions for quick and easy use.</p>
<p>Note that this is not meant for cryptography and should not be considered "safe" for such purposes.</p>
<p>Documentation available at: <a href="https://rng.ironarachne.com/docs">rng.ironarachne.com</a></p>
<h2 id="installation" class="tsd-anchor-link">Installation<a href="#installation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">@ironarachne/rng</span>
</code><button type="button">Copy</button></pre>
<h2 id="usage" class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="the-class" class="tsd-anchor-link">The <code>RNG</code> Class<a href="#the-class" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The core of this library is the <code>RNG</code> class. You can instantiate it with a seed (number or string) to get a deterministic sequence of random numbers. This is ideal for procedural generation, games, or testing where reproducibility is key.</p>
<pre><code class="typescript"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">RNG</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">'@ironarachne/rng'</span><span class="hl-1">;</span><br/><br/><span class="hl-5">// Initialize with a numeric seed</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">rng1</span><span class="hl-1"> = </span><span class="hl-6">new</span><span class="hl-1"> </span><span class="hl-0">RNG</span><span class="hl-1">(</span><span class="hl-8">12345</span><span class="hl-1">);</span><br/><span class="hl-4">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-4">rng1</span><span class="hl-1">.</span><span class="hl-0">int</span><span class="hl-1">(</span><span class="hl-8">1</span><span class="hl-1">, </span><span class="hl-8">100</span><span class="hl-1">)); </span><span class="hl-5">// Always produces the same sequence for seed 12345</span><br/><br/><span class="hl-5">// Initialize with a string seed</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">rng2</span><span class="hl-1"> = </span><span class="hl-6">new</span><span class="hl-1"> </span><span class="hl-0">RNG</span><span class="hl-1">(</span><span class="hl-2">"my-seed-string"</span><span class="hl-1">);</span><br/><span class="hl-4">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-4">rng2</span><span class="hl-1">.</span><span class="hl-0">item</span><span class="hl-1">([</span><span class="hl-2">'apple'</span><span class="hl-1">, </span><span class="hl-2">'banana'</span><span class="hl-1">, </span><span class="hl-2">'cherry'</span><span class="hl-1">]));</span>
</code><button type="button">Copy</button></pre>
<h4 id="methods" class="tsd-anchor-link">Methods<a href="#methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><ul>
<li><strong><code>next()</code></strong>: Returns a random float between 0 (inclusive) and 1 (exclusive).</li>
<li><strong><code>int(min, max)</code></strong>: Returns a random integer between <code>min</code> and <code>max</code> (inclusive).</li>
<li><strong><code>float(min, max)</code></strong>: Returns a random float between <code>min</code> and <code>max</code>.</li>
<li><strong><code>bellFloat(min, max)</code></strong>: Returns a random float between <code>min</code> and <code>max</code> with a bell-curve distribution (approximated by summing 3 random floats).</li>
<li><strong><code>item(array)</code></strong>: Returns a random item from the given array.</li>
<li><strong><code>randomSet(count, array)</code></strong>: Returns a new array containing <code>count</code> unique items selected randomly from the source array.</li>
<li><strong><code>randomString(length)</code></strong>: Generates a random alphanumeric string of the specified length.</li>
<li><strong><code>shuffle(array)</code></strong>: Shuffles the given array in place using the Fisher-Yates algorithm.</li>
<li><strong><code>simple(max)</code></strong>: Returns a random float between 1 and <code>max</code>.</li>
<li><strong><code>weighted(items)</code></strong>: Selects a value from an array of <code>WeightedEntry</code> objects. Each entry must have a <code>value</code> and a <code>commonality</code> (weight). Returns the <code>value</code> of the selected entry.</li>
</ul>
<pre><code class="typescript"><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">lootTable</span><span class="hl-1"> = [</span><br/><span class="hl-1"> { </span><span class="hl-4">value:</span><span class="hl-1"> </span><span class="hl-2">'gold'</span><span class="hl-1">, </span><span class="hl-4">commonality:</span><span class="hl-1"> </span><span class="hl-8">10</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-4">value:</span><span class="hl-1"> </span><span class="hl-2">'silver'</span><span class="hl-1">, </span><span class="hl-4">commonality:</span><span class="hl-1"> </span><span class="hl-8">50</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-4">value:</span><span class="hl-1"> </span><span class="hl-2">'copper'</span><span class="hl-1">, </span><span class="hl-4">commonality:</span><span class="hl-1"> </span><span class="hl-8">100</span><span class="hl-1"> }</span><br/><span class="hl-1">];</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">loot</span><span class="hl-1"> = </span><span class="hl-4">rng</span><span class="hl-1">.</span><span class="hl-0">weighted</span><span class="hl-1">(</span><span class="hl-4">lootTable</span><span class="hl-1">); </span><span class="hl-5">// Returns 'gold', 'silver', or 'copper'</span>
</code><button type="button">Copy</button></pre>
<h3 id="global-convenience-functions" class="tsd-anchor-link">Global Convenience Functions<a href="#global-convenience-functions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>For simple use cases where you don't need to manage a specific seed instance, the library exports a global instance and wrapper functions. These share a single global state.</p>
<pre><code class="typescript"><span class="hl-3">import</span><span class="hl-1"> { </span><span class="hl-4">int</span><span class="hl-1">, </span><span class="hl-4">item</span><span class="hl-1">, </span><span class="hl-4">setSeed</span><span class="hl-1"> } </span><span class="hl-3">from</span><span class="hl-1"> </span><span class="hl-2">'@ironarachne/rng'</span><span class="hl-1">;</span><br/><br/><span class="hl-5">// Optional: Set the global seed</span><br/><span class="hl-0">setSeed</span><span class="hl-1">(</span><span class="hl-4">Date</span><span class="hl-1">.</span><span class="hl-0">now</span><span class="hl-1">());</span><br/><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">roll</span><span class="hl-1"> = </span><span class="hl-0">int</span><span class="hl-1">(</span><span class="hl-8">1</span><span class="hl-1">, </span><span class="hl-8">20</span><span class="hl-1">);</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">fruit</span><span class="hl-1"> = </span><span class="hl-0">item</span><span class="hl-1">([</span><span class="hl-2">'apple'</span><span class="hl-1">, </span><span class="hl-2">'banana'</span><span class="hl-1">, </span><span class="hl-2">'cherry'</span><span class="hl-1">]);</span>
</code><button type="button">Copy</button></pre>
<p>Available global functions:</p>
<ul>
<li><code>bellFloat(min, max)</code></li>
<li><code>float(min, max)</code></li>
<li><code>int(min, max)</code></li>
<li><code>item(array)</code></li>
<li><code>randomSet(count, array)</code></li>
<li><code>randomString(length)</code></li>
<li><code>setSeed(seed)</code></li>
<li><code>shuffle(array)</code></li>
<li><code>simple(max)</code> (Returns 1 to max)</li>
<li><code>weighted(items)</code></li>
</ul>
<h2 id="development" class="tsd-anchor-link">Development<a href="#development" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>This project uses TypeScript.</p>
<h3 id="setup" class="tsd-anchor-link">Setup<a href="#setup" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ol>
<li>Clone the repository.</li>
<li>Install dependencies:<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span>
</code><button type="button">Copy</button></pre>
</li>
</ol>
<h3 id="building" class="tsd-anchor-link">Building<a href="#building" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>To build the project:</p>
<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">build</span>
</code><button type="button">Copy</button></pre>
<h3 id="testing" class="tsd-anchor-link">Testing<a href="#testing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Tests are written using <a href="https://vitest.dev/">Vitest</a>.</p>
<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">test</span>
</code><button type="button">Copy</button></pre>
<h3 id="linting-and-formatting" class="tsd-anchor-link">Linting and Formatting<a href="#linting-and-formatting" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>This project uses <a href="https://biomejs.dev/">Biome</a> for linting and formatting.</p>
<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">biome</span>
</code><button type="button">Copy</button></pre>
<h3 id="documentation" class="tsd-anchor-link">Documentation<a href="#documentation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Generate documentation using TypeDoc:</p>
<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">docs</span>
</code><button type="button">Copy</button></pre>
<h2 id="contributing" class="tsd-anchor-link">Contributing<a href="#contributing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Contributions are welcome! Please follow these steps:</p>
<ol>
<li>Fork the repository.</li>
<li>Create a new branch for your feature or bugfix.</li>
<li>Write code and add tests.</li>
<li>Ensure all tests pass and the code is linted.</li>
<li>Submit a pull request.</li>
</ol>
<h2 id="license" class="tsd-anchor-link">License<a href="#license" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>MIT</p>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#ironarachnerng"><span>@ironarachne/rng</span></a><ul><li><a href="#installation"><span>Installation</span></a></li><li><a href="#usage"><span>Usage</span></a></li><li><ul><li><a href="#the-class"><span>The <wbr/>Class</span></a></li><li><ul><li><a href="#methods"><span>Methods</span></a></li></ul></li><li><a href="#global-convenience-functions"><span>Global <wbr/>Convenience <wbr/>Functions</span></a></li></ul></li><li><a href="#development"><span>Development</span></a></li><li><ul><li><a href="#setup"><span>Setup</span></a></li><li><a href="#building"><span>Building</span></a></li><li><a href="#testing"><span>Testing</span></a></li><li><a href="#linting-and-formatting"><span>Linting and <wbr/>Formatting</span></a></li><li><a href="#documentation"><span>Documentation</span></a></li></ul></li><li><a href="#contributing"><span>Contributing</span></a></li><li><a href="#license"><span>License</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">@ironarachne/rng</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>