JSDoc throws. API is now sorted by function name

README.md

@@ -135,6 +135,10 @@ Take positive integers a, b as input, and return a triple (g, x, y), such that a
 <dt><a href="#gcd">gcd(a, b)</a> ⇒ <code>bigint</code></dt>
 <dd><p>Greatest-common divisor of two integers based on the iterative binary algorithm.</p>
 </dd>
+<dt><a href="#isProbablyPrime">isProbablyPrime(w, [iterations], [disableWorkers])</a> ⇒ <code>Promise.&lt;boolean&gt;</code></dt>
+<dd><p>The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
+iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)</p>
+</dd>
 <dt><a href="#lcm">lcm(a, b)</a> ⇒ <code>bigint</code></dt>
 <dd><p>The least common multiple computed as abs(a*b)/gcd(a,b)</p>
 </dd>
@@ -150,13 +154,6 @@ Take positive integers a, b as input, and return a triple (g, x, y), such that a
 <dt><a href="#modPow">modPow(b, e, n)</a> ⇒ <code>bigint</code></dt>
 <dd><p>Modular exponentiation b**e mod n. Currently using the right-to-left binary method</p>
 </dd>
-<dt><a href="#toZn">toZn(a, n)</a> ⇒ <code>bigint</code></dt>
-<dd><p>Finds the smallest positive element that is congruent to a in modulo n</p>
-</dd>
-<dt><a href="#isProbablyPrime">isProbablyPrime(w, [iterations], [disableWorkers])</a> ⇒ <code>Promise.&lt;boolean&gt;</code></dt>
-<dd><p>The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
-iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)</p>
-</dd>
 <dt><a href="#prime">prime(bitLength, [iterations])</a> ⇒ <code>Promise.&lt;bigint&gt;</code></dt>
 <dd><p>A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator.
 The browser version uses web workers to parallelise prime look up. Therefore, it does not lock the UI
@@ -183,6 +180,9 @@ The sync version is NOT RECOMMENDED since it won&#39;t use workers and thus it&#
 <dt><a href="#randBytesSync">randBytesSync(byteLength, [forceLength])</a> ⇒ <code>Buffer</code> | <code>Uint8Array</code></dt>
 <dd><p>Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()</p>
 </dd>
+<dt><a href="#toZn">toZn(a, n)</a> ⇒ <code>bigint</code></dt>
+<dd><p>Finds the smallest positive element that is congruent to a in modulo n</p>
+</dd>
 </dl>
 
 ### Typedefs
@@ -231,6 +231,20 @@ Take positive integers a, b as input, and return a triple (g, x, y), such that a
 | a | <code>number</code> \| <code>bigint</code> | 
 | b | <code>number</code> \| <code>bigint</code> | 
 
+<a name="egcdReturn"></a>
+
+### egcdReturn : <code>Object</code>
+A triple (g, x, y), such that ax + by = g = gcd(a, b).
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type |
+| --- | --- |
+| g | <code>bigint</code> | 
+| x | <code>bigint</code> | 
+| y | <code>bigint</code> | 
+
 <a name="gcd"></a>
 
 ### gcd(a, b) ⇒ <code>bigint</code>
@@ -244,6 +258,25 @@ Greatest-common divisor of two integers based on the iterative binary algorithm.
 | a | <code>number</code> \| <code>bigint</code> | 
 | b | <code>number</code> \| <code>bigint</code> | 
 
+<a name="isProbablyPrime"></a>
+
+### isProbablyPrime(w, [iterations], [disableWorkers]) ⇒ <code>Promise.&lt;boolean&gt;</code>
+The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
+iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
+
+**Kind**: global function  
+**Returns**: <code>Promise.&lt;boolean&gt;</code> - A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)  
+**Throws**:
+
+- <code>RangeError</code> w MUST be >= 0
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| w | <code>number</code> \| <code>bigint</code> |  | A positive integer to be tested for primality |
+| [iterations] | <code>number</code> | <code>16</code> | The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3 |
+| [disableWorkers] | <code>boolean</code> | <code>false</code> | Disable the use of workers for the primality test |
+
 <a name="lcm"></a>
 
 ### lcm(a, b) ⇒ <code>bigint</code>
@@ -310,34 +343,6 @@ Modular exponentiation b**e mod n. Currently using the right-to-left binary meth
 | e | <code>number</code> \| <code>bigint</code> | exponent |
 | n | <code>number</code> \| <code>bigint</code> | modulo |
 
-<a name="toZn"></a>
-
-### toZn(a, n) ⇒ <code>bigint</code>
-Finds the smallest positive element that is congruent to a in modulo n
-
-**Kind**: global function  
-**Returns**: <code>bigint</code> - The smallest positive representation of a in modulo n  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| a | <code>number</code> \| <code>bigint</code> | An integer |
-| n | <code>number</code> \| <code>bigint</code> | The modulo |
-
-<a name="isProbablyPrime"></a>
-
-### isProbablyPrime(w, [iterations], [disableWorkers]) ⇒ <code>Promise.&lt;boolean&gt;</code>
-The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
-iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
-
-**Kind**: global function  
-**Returns**: <code>Promise.&lt;boolean&gt;</code> - A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)  
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| w | <code>number</code> \| <code>bigint</code> |  | An integer to be tested for primality |
-| [iterations] | <code>number</code> | <code>16</code> | The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3 |
-| [disableWorkers] | <code>boolean</code> | <code>false</code> | Disable the use of workers for the primality test |
-
 <a name="prime"></a>
 
 ### prime(bitLength, [iterations]) ⇒ <code>Promise.&lt;bigint&gt;</code>
@@ -349,6 +354,10 @@ and can be enabled at runtime executing node --experimental-worker with node >=1
 
 **Kind**: global function  
 **Returns**: <code>Promise.&lt;bigint&gt;</code> - A promise that resolves to a bigint probable prime of bitLength bits.  
+**Throws**:
+
+- <code>RangeError</code> bitLength MUST be > 0
+
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -363,6 +372,10 @@ The sync version is NOT RECOMMENDED since it won't use workers and thus it'll be
 
 **Kind**: global function  
 **Returns**: <code>bigint</code> - A bigint probable prime of bitLength bits.  
+**Throws**:
+
+- <code>RangeError</code> bitLength MUST be > 0
+
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -376,6 +389,10 @@ Returns a cryptographically secure random integer between [min,max]. Both number
 
 **Kind**: global function  
 **Returns**: <code>bigint</code> - A cryptographically secure random bigint between [min,max]  
+**Throws**:
+
+- <code>RangeError</code> Arguments MUST be: max > 0 && min >=0 && max > min
+
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -389,6 +406,10 @@ Secure random bits for both node and browsers. Node version uses crypto.randomFi
 
 **Kind**: global function  
 **Returns**: <code>Promise.&lt;(Buffer\|Uint8Array)&gt;</code> - A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits  
+**Throws**:
+
+- <code>RangeError</code> bitLength MUST be > 0
+
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -402,6 +423,10 @@ Secure random bits for both node and browsers. Node version uses crypto.randomFi
 
 **Kind**: global function  
 **Returns**: <code>Buffer</code> \| <code>Uint8Array</code> - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits  
+**Throws**:
+
+- <code>RangeError</code> bitLength MUST be > 0
+
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -415,6 +440,10 @@ Secure random bytes for both node and browsers. Node version uses crypto.randomB
 
 **Kind**: global function  
 **Returns**: <code>Promise.&lt;(Buffer\|Uint8Array)&gt;</code> - A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes  
+**Throws**:
+
+- <code>RangeError</code> byteLength MUST be > 0
+
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -428,23 +457,26 @@ Secure random bytes for both node and browsers. Node version uses crypto.randomF
 
 **Kind**: global function  
 **Returns**: <code>Buffer</code> \| <code>Uint8Array</code> - A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes  
+**Throws**:
+
+- <code>RangeError</code> byteLength MUST be > 0
+
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | byteLength | <code>number</code> |  | The desired number of random bytes |
 | [forceLength] | <code>boolean</code> | <code>false</code> | If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1 |
 
-<a name="egcdReturn"></a>
+<a name="toZn"></a>
 
-### egcdReturn : <code>Object</code>
+### toZn(a, n) ⇒ <code>bigint</code>
-A triple (g, x, y), such that ax + by = g = gcd(a, b).
+Finds the smallest positive element that is congruent to a in modulo n
 
-**Kind**: global typedef  
+**Kind**: global function  
-**Properties**
+**Returns**: <code>bigint</code> - The smallest positive representation of a in modulo n  
 
-| Name | Type |
+| Param | Type | Description |
-| --- | --- |
+| --- | --- | --- |
-| g | <code>bigint</code> | 
+| a | <code>number</code> \| <code>bigint</code> | An integer |
-| x | <code>bigint</code> | 
+| n | <code>number</code> \| <code>bigint</code> | The modulo |
-| y | <code>bigint</code> | 
 

build/build.docs.js

@@ -53,18 +53,21 @@ const input1 = path.join(rootDir, 'node_modules', 'bigint-mod-arith', pkgJson.br
 const input2 = path.join(rootDir, pkgJson.browser) // this module
 
 // Let us replace bigint literals by standard numbers to avoid issues with bigint
-const source1 = fs.readFileSync(input1, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2')
+const source1 = fs.readFileSync(input1, { encoding: 'UTF-8' })
-const source2 = fs.readFileSync(input2, { encoding: 'UTF-8' }).replace(/([0-9]+)n([,\s\n)])/g, '$1$2')
+const source2 = fs.readFileSync(input2, { encoding: 'UTF-8' })
-const source = (source1 + '\n' + source2).replace(/^.*bigint-mod-arith.*$/mg, '') // remove import/export of bigint-mod-arith
+const source = (source1 + '\n' + source2)
-
+  .replace(/^.*bigint-mod-arith.*$/mg, '') // remove import/export of bigint-mod-arith
-const options = {
+  .replace(/([0-9]+)n([,\s\n)])/g, '$1$2') // replace bigint literals by standard numbers to avoid issues with bigint
-  source,
-  template,
-  'heading-depth': 3 // The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading"
-  // 'global-index-format': 'none' // none, grouped, table, dl.
-}
 
 jsdoc2md.clear().then(() => {
+  const data = jsdoc2md.getTemplateDataSync({ source })
+  data.sort((fn1, fn2) => (fn1.id > fn2.id) ? 1 : -1)
+  const options = {
+    data,
+    template,
+    'heading-depth': 3 // The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading"
+    // 'global-index-format': 'none' // none, grouped, table, dl.
+  }
   const readmeContents = jsdoc2md.renderSync(options)
 
   const readmeFile = path.join(rootDir, 'README.md')

lib/index.browser.mod.js

@@ -5,16 +5,19 @@ export { abs, bitLength, eGcd, gcd, lcm, max, min, modInv, modPow, toZn } from '
  * The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
  * iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
  *
- * @param {number | bigint} w An integer to be tested for primality
+ * @param {number | bigint} w A positive integer to be tested for primality
  * @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
  * @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
  *
+ * @throws {RangeError} w MUST be >= 0
+ *
  * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
  */
 function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
   if (typeof w === 'number') {
     w = BigInt(w)
   }
+  if (w < 0) throw RangeError('w MUST be >= 0')
   /* eslint-disable no-lone-blocks */
   { // browser
     return new Promise((resolve, reject) => {
@@ -49,6 +52,8 @@ function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
  */
 function prime (bitLength, iterations = 16) {
@@ -118,6 +123,8 @@ function prime (bitLength, iterations = 16) {
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {bigint} A bigint probable prime of bitLength bits.
  */
 function primeSync (bitLength, iterations = 16) {
@@ -134,10 +141,12 @@ function primeSync (bitLength, iterations = 16) {
  * @param {bigint} max Returned value will be <= max
  * @param {bigint} [min = BigInt(1)] Returned value will be >= min
  *
+ * @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
+ *
  * @returns {bigint} A cryptographically secure random bigint between [min,max]
  */
 function randBetween (max, min = 1n) {
-  if (max <= 0n || min < 0n || max <= min) throw new RangeError('inputs should be max > 0, min >= 0; max > min')
+  if (max <= 0n || min < 0n || max <= min) throw new RangeError('Arguments MUST be: max > 0 && min >=0 && max > min')
   const interval = max - min
   const bitLen = bitLength(interval)
   let rnd
@@ -154,6 +163,8 @@ function randBetween (max, min = 1n) {
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 function randBits (bitLength, forceLength = false) {
@@ -182,6 +193,8 @@ function randBits (bitLength, forceLength = false) {
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 function randBitsSync (bitLength, forceLength = false) {
@@ -207,6 +220,8 @@ function randBitsSync (bitLength, forceLength = false) {
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 function randBytes (byteLength, forceLength = false) {
@@ -231,6 +246,8 @@ function randBytes (byteLength, forceLength = false) {
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 function randBytesSync (byteLength, forceLength = false) {

lib/index.node.js

@@ -6,16 +6,19 @@ var bigintModArith = require('bigint-mod-arith')
  * The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
  * iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
  *
- * @param {number | bigint} w An integer to be tested for primality
+ * @param {number | bigint} w A positive integer to be tested for primality
  * @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
  * @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
  *
+ * @throws {RangeError} w MUST be >= 0
+ *
  * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
  */
 function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
   if (typeof w === 'number') {
     w = BigInt(w)
   }
+  if (w < 0) throw RangeError('w MUST be >= 0')
   /* eslint-disable no-lone-blocks */
   { // Node.js
     /* istanbul ignore else */
@@ -56,6 +59,8 @@ function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
  */
 function prime (bitLength, iterations = 16) {
@@ -126,6 +131,8 @@ function prime (bitLength, iterations = 16) {
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {bigint} A bigint probable prime of bitLength bits.
  */
 function primeSync (bitLength, iterations = 16) {
@@ -142,10 +149,12 @@ function primeSync (bitLength, iterations = 16) {
  * @param {bigint} max Returned value will be <= max
  * @param {bigint} [min = BigInt(1)] Returned value will be >= min
  *
+ * @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
+ *
  * @returns {bigint} A cryptographically secure random bigint between [min,max]
  */
 function randBetween (max, min = 1n) {
-  if (max <= 0n || min < 0n || max <= min) throw new RangeError('inputs should be max > 0, min >= 0; max > min')
+  if (max <= 0n || min < 0n || max <= min) throw new RangeError('Arguments MUST be: max > 0 && min >=0 && max > min')
   const interval = max - min
   const bitLen = bigintModArith.bitLength(interval)
   let rnd
@@ -162,6 +171,8 @@ function randBetween (max, min = 1n) {
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 function randBits (bitLength, forceLength = false) {
@@ -190,6 +201,8 @@ function randBits (bitLength, forceLength = false) {
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 function randBitsSync (bitLength, forceLength = false) {
@@ -215,6 +228,8 @@ function randBitsSync (bitLength, forceLength = false) {
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 function randBytes (byteLength, forceLength = false) {
@@ -242,6 +257,8 @@ function randBytes (byteLength, forceLength = false) {
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 function randBytesSync (byteLength, forceLength = false) {

src/js/index.js

@@ -6,16 +6,19 @@ export { abs, bitLength, eGcd, gcd, lcm, max, min, modInv, modPow, toZn } from '
  * The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
  * iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
  *
- * @param {number | bigint} w An integer to be tested for primality
+ * @param {number | bigint} w A positive integer to be tested for primality
  * @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
  * @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
  *
+ * @throws {RangeError} w MUST be >= 0
+ *
  * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
  */
 export function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
   if (typeof w === 'number') {
     w = BigInt(w)
   }
+  if (w < 0) throw RangeError('w MUST be >= 0')
   /* eslint-disable no-lone-blocks */
   if (!process.browser) { // Node.js
     /* istanbul ignore else */
@@ -75,6 +78,8 @@ export function isProbablyPrime (w, iterations = 16, disableWorkers = false) {
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
  */
 export function prime (bitLength, iterations = 16) {
@@ -152,6 +157,8 @@ export function prime (bitLength, iterations = 16) {
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {bigint} A bigint probable prime of bitLength bits.
  */
 export function primeSync (bitLength, iterations = 16) {
@@ -168,10 +175,12 @@ export function primeSync (bitLength, iterations = 16) {
  * @param {bigint} max Returned value will be <= max
  * @param {bigint} [min = BigInt(1)] Returned value will be >= min
  *
+ * @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
+ *
  * @returns {bigint} A cryptographically secure random bigint between [min,max]
  */
 export function randBetween (max, min = 1n) {
-  if (max <= 0n || min < 0n || max <= min) throw new RangeError('inputs should be max > 0, min >= 0; max > min')
+  if (max <= 0n || min < 0n || max <= min) throw new RangeError('Arguments MUST be: max > 0 && min >=0 && max > min')
   const interval = max - min
   const bitLen = bitLength(interval)
   let rnd
@@ -188,6 +197,8 @@ export function randBetween (max, min = 1n) {
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 export function randBits (bitLength, forceLength = false) {
@@ -216,6 +227,8 @@ export function randBits (bitLength, forceLength = false) {
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 export function randBitsSync (bitLength, forceLength = false) {
@@ -241,6 +254,8 @@ export function randBitsSync (bitLength, forceLength = false) {
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 export function randBytes (byteLength, forceLength = false) {
@@ -274,6 +289,8 @@ export function randBytes (byteLength, forceLength = false) {
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 export function randBytesSync (byteLength, forceLength = false) {

types/index.d.ts

@@ -2,10 +2,12 @@
  * The test first tries if any of the first 250 small primes are a factor of the input number and then passes several
  * iterations of Miller-Rabin Probabilistic Primality Test (FIPS 186-4 C.3.1)
  *
- * @param {number | bigint} w An integer to be tested for primality
+ * @param {number | bigint} w A positive integer to be tested for primality
  * @param {number} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
  * @param {boolean} [disableWorkers = false] Disable the use of workers for the primality test
  *
+ * @throws {RangeError} w MUST be >= 0
+ *
  * @returns {Promise<boolean>} A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
  */
 export function isProbablyPrime(w: number | bigint, iterations?: number, disableWorkers?: boolean): Promise<boolean>;
@@ -19,6 +21,8 @@ export function isProbablyPrime(w: number | bigint, iterations?: number, disable
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<bigint>} A promise that resolves to a bigint probable prime of bitLength bits.
  */
 export function prime(bitLength: number, iterations?: number): Promise<bigint>;
@@ -29,6 +33,8 @@ export function prime(bitLength: number, iterations?: number): Promise<bigint>;
  * @param {number} bitLength The required bit length for the generated prime
  * @param {number} [iterations = 16] The number of iterations for the Miller-Rabin Probabilistic Primality Test
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {bigint} A bigint probable prime of bitLength bits.
  */
 export function primeSync(bitLength: number, iterations?: number): bigint;
@@ -37,6 +43,8 @@ export function primeSync(bitLength: number, iterations?: number): bigint;
  * @param {bigint} max Returned value will be <= max
  * @param {bigint} [min = BigInt(1)] Returned value will be >= min
  *
+ * @throws {RangeError} Arguments MUST be: max > 0 && min >=0 && max > min
+ *
  * @returns {bigint} A cryptographically secure random bigint between [min,max]
  */
 export function randBetween(max: bigint, min?: bigint): bigint;
@@ -46,6 +54,8 @@ export function randBetween(max: bigint, min?: bigint): bigint;
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A Promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 export function randBits(bitLength: number, forceLength?: boolean): Promise<Uint8Array | Buffer>;
@@ -54,6 +64,8 @@ export function randBits(bitLength: number, forceLength?: boolean): Promise<Uint
  * @param {number} bitLength The desired number of random bits
  * @param {boolean} [forceLength = false] If we want to force the output to have a specific bit length. It basically forces the msb to be 1
  *
+ * @throws {RangeError} bitLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
  */
 export function randBitsSync(bitLength: number, forceLength?: boolean): Uint8Array | Buffer;
@@ -63,6 +75,8 @@ export function randBitsSync(bitLength: number, forceLength?: boolean): Uint8Arr
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Promise<Buffer | Uint8Array>} A promise that resolves to a Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 export function randBytes(byteLength: number, forceLength?: boolean): Promise<Uint8Array | Buffer>;
@@ -72,6 +86,8 @@ export function randBytes(byteLength: number, forceLength?: boolean): Promise<Ui
  * @param {number} byteLength The desired number of random bytes
  * @param {boolean} [forceLength = false] If we want to force the output to have a bit length of 8*byteLength. It basically forces the msb to be 1
  *
+ * @throws {RangeError} byteLength MUST be > 0
+ *
  * @returns {Buffer | Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
  */
 export function randBytesSync(byteLength: number, forceLength?: boolean): Uint8Array | Buffer;