TypeScript definitions. Browser module defaults to minified ES6

This commit is contained in:
juanelas 2020-03-03 09:36:04 +01:00
parent 14008fade1
commit 5d2e2a7fd0
7 changed files with 219 additions and 6 deletions

View File

@ -14,7 +14,7 @@ bigint-crypto-utils can be imported to your project with `npm`:
npm install bigint-crypto-utils 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. 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.

34
build/build.dts.js Normal file
View File

@ -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);

6
package-lock.json generated
View File

@ -3211,6 +3211,12 @@
"integrity": "sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==", "integrity": "sha512-4dbzIzqvjtgiM5rw1k5rEHtBANKmdudhGyBEajN01fEyhaAIhsoKNy6y7+IN93IfpFtwY9iqi7kD+xwKhQsNJA==",
"dev": true "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": { "typical": {
"version": "2.6.1", "version": "2.6.1",
"resolved": "https://registry.npmjs.org/typical/-/typical-2.6.1.tgz", "resolved": "https://registry.npmjs.org/typical/-/typical-2.6.1.tgz",

View File

@ -20,18 +20,21 @@
}, },
"repository": "github:juanelas/bigint-crypto-utils", "repository": "github:juanelas/bigint-crypto-utils",
"main": "./dist/bigint-crypto-utils-latest.node.js", "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": { "directories": {
"build": "./build", "build": "./build",
"dist": "./dist", "dist": "./dist",
"src": "./src", "src": "./src",
"test": "./test" "test": "./test",
"types": "/types"
}, },
"scripts": { "scripts": {
"test": "mocha --timeout 600000", "test": "mocha --timeout 600000",
"build:js": "node build/build.rollup.js", "build:js": "node build/build.rollup.js",
"build:browserTests": "node build/build.browser.tests.js", "build:browserTests": "node build/build.browser.tests.js",
"build:docs": "jsdoc2md --template=./src/readme-template.hbs --files ./src/main.js > README.md", "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:**", "build": "run-s build:**",
"prepublishOnly": "npm run build" "prepublishOnly": "npm run build"
}, },
@ -46,6 +49,7 @@
"rollup-plugin-babel-minify": "^9.1.0", "rollup-plugin-babel-minify": "^9.1.0",
"rollup-plugin-commonjs": "^10.1.0", "rollup-plugin-commonjs": "^10.1.0",
"rollup-plugin-multi-entry": ">=2.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"
} }
} }

View File

@ -14,7 +14,7 @@ bigint-crypto-utils can be imported to your project with `npm`:
npm install bigint-crypto-utils 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. 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.

View File

@ -12,7 +12,7 @@
<script type="module"> <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; window.bigintCryptoUtils = bigintCryptoUtils;
import './tests.js'; import './tests.js';
mocha.run(); mocha.run();

169
types/bigint-crypto-utils.d.ts vendored Normal file
View File

@ -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;
};