From 5d2e2a7fd03bf022dfe9fb8225a8da0de8f386fa Mon Sep 17 00:00:00 2001
From: juanelas <j.hernandez@upc.edu>
Date: Tue, 3 Mar 2020 09:36:04 +0100
Subject: [PATCH] TypeScript definitions. Browser module defaults to minified
 ES6

---
 README.md                      |   2 +-
 build/build.dts.js             |  34 +++++++
 package-lock.json              |   6 ++
 package.json                   |  10 +-
 src/readme-template.hbs        |   2 +-
 test/browser/index.html        |   2 +-
 types/bigint-crypto-utils.d.ts | 169 +++++++++++++++++++++++++++++++++
 7 files changed, 219 insertions(+), 6 deletions(-)
 create mode 100644 build/build.dts.js
 create mode 100644 types/bigint-crypto-utils.d.ts

diff --git a/README.md b/README.md
index a362aad..8729c28 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ bigint-crypto-utils can be imported to your project with `npm`:
 npm install bigint-crypto-utils
 ```
 
-NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js.
+NPM installation defaults to the minified ES6 module for browsers and the CJS one for Node.js.
 
 For web browsers, you can also directly download the [IIFE file](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bigint-crypto-utils-latest.browser.js) or the [ES6 module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bigint-crypto-utils-latest.browser.mod.min.js) from GitHub.
 
diff --git a/build/build.dts.js b/build/build.dts.js
new file mode 100644
index 0000000..6b3abee
--- /dev/null
+++ b/build/build.dts.js
@@ -0,0 +1,34 @@
+const fs = require('fs');
+const ts = require('typescript');
+const path = require('path');
+const pkgJson = require('../package.json');
+
+const rootDir = path.join(__dirname, '..');
+const jsFile = path.join(rootDir, 'src', 'main.js');
+const dtsFile = path.join(rootDir, 'types', `${pkgJson.name}.d.ts`);
+
+
+const compilerOptions = {
+    'declaration': true,
+    'noEmit': false,
+    'emitDeclarationOnly': true,
+    'allowJs': true
+};
+
+(function compile(jsFile, dtsFile, options) { // Create a Program with an in-memory emit
+    const host = ts.createCompilerHost(options);
+    // host.writeFile = (fileName, contents) => createdFiles[fileName] = contents;
+    host.writeFile = (fileName, contents) => {
+        fs.writeFileSync(dtsFile, contents);
+    };
+
+    // Prepare and emit the d.ts files
+    const program = ts.createProgram([jsFile], options, host);
+    program.emit();
+
+    // Loop through all the input files
+    // fileNames.forEach(file => {
+    //     console.log("### JavaScript\n");
+    //     console.log(host.readFile(file));
+    // });
+})(jsFile, dtsFile, compilerOptions);
diff --git a/package-lock.json b/package-lock.json
index 3d10de7..796e03e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -3211,6 +3211,12 @@
       "integrity": "sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==",
       "dev": true
     },
+    "typescript": {
+      "version": "3.8.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-3.8.3.tgz",
+      "integrity": "sha512-MYlEfn5VrLNsgudQTVJeNaQFUAI7DkhnOjdpAp4T+ku1TfQClewlbSuTVHiA+8skNBgaf02TL/kLOvig4y3G8w==",
+      "dev": true
+    },
     "typical": {
       "version": "2.6.1",
       "resolved": "https://registry.npmjs.org/typical/-/typical-2.6.1.tgz",
diff --git a/package.json b/package.json
index b3641d1..26ed39d 100644
--- a/package.json
+++ b/package.json
@@ -20,18 +20,21 @@
   },
   "repository": "github:juanelas/bigint-crypto-utils",
   "main": "./dist/bigint-crypto-utils-latest.node.js",
-  "browser": "./dist/bigint-crypto-utils-latest.browser.mod.js",
+  "browser": "./dist/bigint-crypto-utils-latest.browser.mod.min.js",
+  "types": "./types/bigint-crypto-utils.d.ts",
   "directories": {
     "build": "./build",
     "dist": "./dist",
     "src": "./src",
-    "test": "./test"
+    "test": "./test",
+    "types": "/types"
   },
   "scripts": {
     "test": "mocha --timeout 600000",
     "build:js": "node build/build.rollup.js",
     "build:browserTests": "node build/build.browser.tests.js",
     "build:docs": "jsdoc2md --template=./src/readme-template.hbs --files ./src/main.js > README.md",
+    "build:dts": "node build/build.dts.js",
     "build": "run-s build:**",
     "prepublishOnly": "npm run build"
   },
@@ -46,6 +49,7 @@
     "rollup-plugin-babel-minify": "^9.1.0",
     "rollup-plugin-commonjs": "^10.1.0",
     "rollup-plugin-multi-entry": ">=2.1.0",
-    "rollup-plugin-node-resolve": ">=5.2.0"
+    "rollup-plugin-node-resolve": ">=5.2.0",
+    "typescript": "^3.8.3"
   }
 }
diff --git a/src/readme-template.hbs b/src/readme-template.hbs
index 8cfb5b2..b4b549a 100644
--- a/src/readme-template.hbs
+++ b/src/readme-template.hbs
@@ -14,7 +14,7 @@ bigint-crypto-utils can be imported to your project with `npm`:
 npm install bigint-crypto-utils
 ```
 
-NPM installation defaults to the ES6 module for browsers and the CJS one for Node.js.
+NPM installation defaults to the minified ES6 module for browsers and the CJS one for Node.js.
 
 For web browsers, you can also directly download the [IIFE file](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bigint-crypto-utils-latest.browser.js) or the [ES6 module](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bigint-crypto-utils-latest.browser.mod.min.js) from GitHub.
 
diff --git a/test/browser/index.html b/test/browser/index.html
index 1660a98..fa25c43 100644
--- a/test/browser/index.html
+++ b/test/browser/index.html
@@ -12,7 +12,7 @@
     
     
 <script type="module">
-    import * as bigintCryptoUtils from '../../dist/bigint-crypto-utils-latest.browser.mod.js'
+    import * as bigintCryptoUtils from '../../dist/bigint-crypto-utils-latest.browser.mod.min.js'
     window.bigintCryptoUtils = bigintCryptoUtils;
     import './tests.js';
     mocha.run();
diff --git a/types/bigint-crypto-utils.d.ts b/types/bigint-crypto-utils.d.ts
new file mode 100644
index 0000000..526cc4f
--- /dev/null
+++ b/types/bigint-crypto-utils.d.ts
@@ -0,0 +1,169 @@
+/**
+ * Absolute value. abs(a)==a if a>=0. abs(a)==-a if a<0
+ *
+ * @param {number|bigint} a
+ *
+ * @returns {bigint} the absolute value of a
+ */
+export function abs(a: number | bigint): bigint;
+/**
+ * Returns the bitlength of a number
+ *
+ * @param {number|bigint} a
+ * @returns {number} - the bit length
+ */
+export function bitLength(a: number | bigint): number;
+/**
+ * @typedef {Object} egcdReturn A triple (g, x, y), such that ax + by = g = gcd(a, b).
+ * @property {bigint} g
+ * @property {bigint} x
+ * @property {bigint} y
+ */
+/**
+ * An iterative implementation of the extended euclidean algorithm or extended greatest common divisor algorithm.
+ * Take positive integers a, b as input, and return a triple (g, x, y), such that ax + by = g = gcd(a, b).
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {egcdReturn} A triple (g, x, y), such that ax + by = g = gcd(a, b).
+ */
+export function eGcd(a: number | bigint, b: number | bigint): egcdReturn;
+/**
+ * Greatest-common divisor of two integers based on the iterative binary algorithm.
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} The greatest common divisor of a and b
+ */
+export function gcd(a: number | bigint, b: number | bigint): bigint;
+/**
+ * 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} [iterations = 16] The number of iterations for the primality test. The value shall be consistent with Table C.1, C.2 or C.3
+ *
+ * @return {Promise} 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): Promise<any>;
+/**
+ * The least common multiple computed as abs(a*b)/gcd(a,b)
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} The least common multiple of a and b
+ */
+export function lcm(a: number | bigint, b: number | bigint): bigint;
+/**
+ * Maximum. max(a,b)==a if a>=b. max(a,b)==b if a<=b
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} maximum of numbers a and b
+ */
+export function max(a: number | bigint, b: number | bigint): bigint;
+/**
+ * Minimum. min(a,b)==b if a>=b. min(a,b)==a if a<=b
+ *
+ * @param {number|bigint} a
+ * @param {number|bigint} b
+ *
+ * @returns {bigint} minimum of numbers a and b
+ */
+export function min(a: number | bigint, b: number | bigint): bigint;
+/**
+ * Modular inverse.
+ *
+ * @param {number|bigint} a The number to find an inverse for
+ * @param {number|bigint} n The modulo
+ *
+ * @returns {bigint} the inverse modulo n or NaN if it does not exist
+ */
+export function modInv(a: number | bigint, n: number | bigint): bigint;
+/**
+ * Modular exponentiation b**e mod n. Currently using the right-to-left binary method
+ *
+ * @param {number|bigint} b base
+ * @param {number|bigint} e exponent
+ * @param {number|bigint} n modulo
+ *
+ * @returns {bigint} b**e mod n
+ */
+export function modPow(b: number | bigint, e: number | bigint, n: number | bigint): bigint;
+/**
+ * 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
+ * main process, and it can be much faster (if several cores or cpu are available).
+ * The node version can also use worker_threads if they are available (enabled by default with Node 11 and
+ * and can be enabled at runtime executing node --experimental-worker with node >=10.5.0).
+ *
+ * @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
+ *
+ * @returns {Promise} A promise that resolves to a bigint probable prime of bitLength bits.
+ */
+export function prime(bitLength: number, iterations?: number): Promise<any>;
+/**
+ * A probably-prime (Miller-Rabin), cryptographically-secure, random-number generator.
+ * The sync version is NOT RECOMMENDED since it won't use workers and thus it'll be slower and may freeze thw window in browser's javascript. Please consider using prime() instead.
+ *
+ * @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
+ *
+ * @returns {bigint} A bigint probable prime of bitLength bits.
+ */
+export function primeSync(bitLength: number, iterations?: number): bigint;
+/**
+ * Returns a cryptographically secure random integer between [min,max]
+ * @param {bigint} max Returned value will be <= max
+ * @param {bigint} [min = BigInt(1)] Returned value will be >= min
+ *
+ * @returns {bigint} A cryptographically secure random bigint between [min,max]
+ */
+export function randBetween(max: bigint, min?: bigint): bigint;
+/**
+ * Secure random bits for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+ *
+ * @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
+ *
+ * @returns {Buffer|Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bits
+ */
+export function randBits(bitLength: number, forceLength?: boolean): Uint8Array | Buffer;
+/**
+ * Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+ *
+ * @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
+ *
+ * @returns {Promise} 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<any>;
+/**
+ * Secure random bytes for both node and browsers. Node version uses crypto.randomFill() and browser one self.crypto.getRandomValues()
+ *
+ * @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
+ *
+ * @returns {Buffer|Uint8Array} A Buffer/UInt8Array (Node.js/Browser) filled with cryptographically secure random bytes
+ */
+export function randBytesSync(byteLength: number, forceLength?: boolean): Uint8Array | Buffer;
+/**
+ * Finds the smallest positive element that is congruent to a in modulo n
+ * @param {number|bigint} a An integer
+ * @param {number|bigint} n The modulo
+ *
+ * @returns {bigint} The smallest positive representation of a in modulo n
+ */
+export function toZn(a: number | bigint, n: number | bigint): bigint;
+/**
+ * A triple (g, x, y), such that ax + by = g = gcd(a, b).
+ */
+export type egcdReturn = {
+    g: bigint;
+    x: bigint;
+    y: bigint;
+};