better docs
This commit is contained in:
Juanra Dikal
parent
d38c20a04d
commit
5bba6de3f9
32
README.md
32
README.md
|
|
@ -35,35 +35,11 @@ import * as bigintCryptoUtils from 'bigint-crypto-utils'
|
|||
|
||||
The appropriate version for browser or node is automatically exported.
|
||||
|
||||
`bigint-crypto-utils` **CANNOT BE POLYFILLED** to suport older JS version (\< ES2020). If you are using webpack/babel to create your production bundles, you should target only the most modern browsers. For instance, for **React** apps created with [`create-react-app`](https://create-react-app.dev/), you should edit your `package.json` and modify the `browserList` so that it only targets the latest browsers (play with the number of versions that do not need polyfilling):
|
||||
> `bigint-crypto-utils` uses [ES2020 BigInt](https://tc39.es/ecma262/#sec-bigint-objects), so take into account that:
|
||||
> 1. If you experience issues using webpack/babel to create your production bundles, you may edit the supported browsers list and leave only [supported browsers and versions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility). The browsers list is usually located in your project's `package.json` or the `.browserslistrc` file.
|
||||
> 2. In order to use `bigint-crypto-utils` with TypeScript you need to set `target`, and `lib` and `module` if in use, to `ES2020` in your project's `tsconfig.json`.
|
||||
|
||||
```json
|
||||
"browserslist": {
|
||||
"production": [
|
||||
"last 1 chrome version",
|
||||
"last 1 firefox version",
|
||||
"last 1 safari version"
|
||||
],
|
||||
"development": [
|
||||
"last 1 chrome version",
|
||||
"last 1 firefox version",
|
||||
"last 1 safari version"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Also, notice that [BigInt implementation is ES2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you need to set `target` to `ES2020` in your project's `tsconfig.json`.
|
||||
|
||||
If you are using Angular, since this library uses node typings, you should also add them to the `angularCompilerOptions` in your `tsconfig.json`:
|
||||
|
||||
```json
|
||||
"angularCompilerOptions": {
|
||||
"types": ["node", ...]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
You can also download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bundles/bigint-crypto-utils.iife.js), the [ESM bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bundles/bigint-crypto-utils.esm.js) or the [UMD bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bundles/bigint-crypto-utils.umd.js) and manually add it to your project, or, if you have already imported `bigint-crypto-utils` to your project, just get the bundles from `node_modules/bigint-crypto-utils/dist/bundles/`.
|
||||
You can also download the [IIFE bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bundles/bigint-crypto-utils.iife.js), the [ESM bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bundles/bigint-crypto-utils.esm.js) or the [UMD bundle](https://raw.githubusercontent.com/juanelas/bigint-crypto-utils/master/dist/bundles/bigint-crypto-utils.umd.js) and manually add it to your project, or, if you have already installed `bigint-crypto-utils` in your project, just get the bundles from `node_modules/bigint-crypto-utils/dist/bundles/`.
|
||||
|
||||
An example of usage could be:
|
||||
|
||||
|
|
|
|||
|
|
@ -25,9 +25,10 @@ async function typedoc () {
|
|||
// typedoc options here
|
||||
entryPoints: ['src/index.ts'],
|
||||
plugin: ['typedoc-plugin-markdown'],
|
||||
includeVersion: true,
|
||||
includeVersion: false,
|
||||
entryDocument: 'API.md',
|
||||
readme: 'none'
|
||||
readme: 'none',
|
||||
hideBreadcrumbs: true
|
||||
})
|
||||
|
||||
const project = app.convert()
|
||||
|
|
@ -61,21 +62,25 @@ const regex = /^(?:(?<scope>@.*?)\/)?(?<name>.*)/ // We are going to take only t
|
|||
const { name } = pkgJson.name.match(regex).groups
|
||||
const camelCaseName = camelise(name)
|
||||
|
||||
const iifeBundlePath = path.relative('.', pkgJson.exports['./iife-browser-bundle'])
|
||||
const esmBundlePath = path.relative('.', pkgJson.exports['./esm-browser-bundle'])
|
||||
const umdBundlePath = path.relative('.', pkgJson.exports['./umd-browser-bundle'])
|
||||
|
||||
let iifeBundle, esmBundle, umdBundle, workflowBadget, coverallsBadge
|
||||
if (repoProvider) {
|
||||
switch (repoProvider) {
|
||||
case 'github':
|
||||
iifeBundle = `[IIFE bundle](https://raw.githubusercontent.com/${repoUsername}/${repoName}/master/dist/bundles/${name}.iife.js)`
|
||||
esmBundle = `[ESM bundle](https://raw.githubusercontent.com/${repoUsername}/${repoName}/master/dist/bundles/${name}.esm.js)`
|
||||
umdBundle = `[UMD bundle](https://raw.githubusercontent.com/${repoUsername}/${repoName}/master/dist/bundles/${name}.umd.js)`
|
||||
iifeBundle = `[IIFE bundle](https://raw.githubusercontent.com/${repoUsername}/${repoName}/master/${iifeBundlePath})`
|
||||
esmBundle = `[ESM bundle](https://raw.githubusercontent.com/${repoUsername}/${repoName}/master/${esmBundlePath})`
|
||||
umdBundle = `[UMD bundle](https://raw.githubusercontent.com/${repoUsername}/${repoName}/master/${umdBundlePath})`
|
||||
workflowBadget = `[](https://github.com/${repoUsername}/${repoName}/actions?query=workflow%3A%22Node+CI%22)`
|
||||
coverallsBadge = `[](https://coveralls.io/github/${repoUsername}/${repoName}?branch=master)`
|
||||
break
|
||||
|
||||
case 'gitlab':
|
||||
iifeBundle = `[IIFE bundle](https://gitlab.com/${repoUsername}/${repoName}/-/raw/master/dist/bundles/${name}.iife.js?inline=false)`
|
||||
esmBundle = `[ESM bundle](https://gitlab.com/${repoUsername}/${repoName}/-/raw/master/dist/bundles/${name}.esm.js?inline=false)`
|
||||
umdBundle = `[IIFE bundle](https://gitlab.com/${repoUsername}/${repoName}/-/raw/master/dist/bundles/${name}.umd.js?inline=false)`
|
||||
iifeBundle = `[IIFE bundle](https://gitlab.com/${repoUsername}/${repoName}/-/raw/master/dist/${iifeBundlePath}?inline=false)`
|
||||
esmBundle = `[ESM bundle](https://gitlab.com/${repoUsername}/${repoName}/-/raw/master/dist/${esmBundlePath}?inline=false)`
|
||||
umdBundle = `[UMD bundle](https://gitlab.com/${repoUsername}/${repoName}/-/raw/master/dist/${umdBundlePath}?inline=false)`
|
||||
break
|
||||
|
||||
default:
|
||||
|
|
|
|||
20
docs/API.md
20
docs/API.md
|
|
@ -1,6 +1,4 @@
|
|||
bigint-crypto-utils - v3.0.13
|
||||
|
||||
# bigint-crypto-utils - v3.0.13
|
||||
# bigint-crypto-utils
|
||||
|
||||
## Table of contents
|
||||
|
||||
|
|
@ -135,7 +133,7 @@ w MUST be >= 0
|
|||
|
||||
A promise that resolves to a boolean that is either true (a probably prime number) or false (definitely composite)
|
||||
|
||||
Defined in: [src/ts/isProbablyPrime.ts:21](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/isProbablyPrime.ts#L21)
|
||||
Defined in: [src/ts/isProbablyPrime.ts:21](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/isProbablyPrime.ts#L21)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -275,7 +273,7 @@ bitLength MUST be > 0
|
|||
|
||||
A promise that resolves to a bigint probable prime of bitLength bits.
|
||||
|
||||
Defined in: [src/ts/prime.ts:21](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/prime.ts#L21)
|
||||
Defined in: [src/ts/prime.ts:21](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/prime.ts#L21)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -300,7 +298,7 @@ bitLength MUST be > 0
|
|||
|
||||
A bigint probable prime of bitLength bits.
|
||||
|
||||
Defined in: [src/ts/prime.ts:100](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/prime.ts#L100)
|
||||
Defined in: [src/ts/prime.ts:100](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/prime.ts#L100)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -324,7 +322,7 @@ Arguments MUST be: max > 0 && min >=0 && max > min
|
|||
|
||||
A cryptographically secure random bigint between [min,max]
|
||||
|
||||
Defined in: [src/ts/randBetween.ts:15](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/randBetween.ts#L15)
|
||||
Defined in: [src/ts/randBetween.ts:15](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/randBetween.ts#L15)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -348,7 +346,7 @@ bitLength MUST be > 0
|
|||
|
||||
A Promise that resolves to a UInt8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bits
|
||||
|
||||
Defined in: [src/ts/randBits.ts:14](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/randBits.ts#L14)
|
||||
Defined in: [src/ts/randBits.ts:14](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/randBits.ts#L14)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -372,7 +370,7 @@ bitLength MUST be > 0
|
|||
|
||||
A Uint8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bits
|
||||
|
||||
Defined in: [src/ts/randBits.ts:45](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/randBits.ts#L45)
|
||||
Defined in: [src/ts/randBits.ts:45](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/randBits.ts#L45)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -396,7 +394,7 @@ byteLength MUST be > 0
|
|||
|
||||
A promise that resolves to a UInt8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bytes
|
||||
|
||||
Defined in: [src/ts/randBytes.ts:12](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/randBytes.ts#L12)
|
||||
Defined in: [src/ts/randBytes.ts:12](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/randBytes.ts#L12)
|
||||
|
||||
___
|
||||
|
||||
|
|
@ -420,7 +418,7 @@ byteLength MUST be > 0
|
|||
|
||||
A UInt8Array/Buffer (Browser/Node.js) filled with cryptographically secure random bytes
|
||||
|
||||
Defined in: [src/ts/randBytes.ts:46](https://github.com/juanelas/bigint-crypto-utils/blob/ed328f3/src/ts/randBytes.ts#L46)
|
||||
Defined in: [src/ts/randBytes.ts:46](https://github.com/juanelas/bigint-crypto-utils/blob/d38c20a/src/ts/randBytes.ts#L46)
|
||||
|
||||
___
|
||||
|
||||
|
|
|
|||
|
|
@ -56,8 +56,7 @@
|
|||
"docs": "node build/build.docs.js",
|
||||
"lint": "ts-standard --fix",
|
||||
"mocha": "node ./build/bin/mocha-ts.js --require build/testing/mocha/mocha-init.js ",
|
||||
"preversion": "run-s lint build:js test:browser coverage",
|
||||
"postversion": "npm run docs",
|
||||
"preversion": "npm run build",
|
||||
"test": "run-s test:browser test:node",
|
||||
"test:browser": "node build/testing/browser/index.js",
|
||||
"test:node": "npm run mocha -- '{src/**/*.spec.ts,test/**/*.ts}'",
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Arbitrary precision modular arithmetic, cryptographically secure random numbers
|
|||
|
||||
It relies on the native JS implementation of ([BigInt](https://tc39.es/ecma262/#sec-bigint-objects)). It can be used by any [Web Browser or webview supporting BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility) and with Node.js (>=10.4.0). The bundles can be imported directly by the browser or in Angular projects, React apps, Node.js, etc.
|
||||
|
||||
Secure random numbers are generated using the native crypto implementation of the browsers ([Web Cryptography API](https://w3c.github.io/webcrypto/)) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html)). Strong probable prime generation and testing use Miller-Rabin primality tests and are automatically sped up using parallel workers both in browsers and Node.js.
|
||||
Secure random numbers are generated using the native crypto implementation of the browsers ([Web Cryptography API](https://w3c.github.io/webcrypto/)) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html). Strong probable prime generation and testing use Miller-Rabin primality tests and are automatically sped up using parallel workers both in browsers and Node.js.
|
||||
|
||||
> The operations supported on BigInts are not constant time. BigInt can be therefore **[unsuitable for use in cryptography](https://www.chosenplaintext.ca/articles/beginners-guide-constant-time-cryptography.html).** Many platforms provide native support for cryptography, such as [Web Cryptography API](https://w3c.github.io/webcrypto/) or [Node.js Crypto](https://nodejs.org/dist/latest/docs/api/crypto.html).
|
||||
|
||||
|
|
@ -34,35 +34,11 @@ import * as {{PKG_CAMELCASE}} from '{{PKG_NAME}}'
|
|||
|
||||
The appropriate version for browser or node is automatically exported.
|
||||
|
||||
`{{PKG_NAME}}` **CANNOT BE POLYFILLED** to suport older JS version (\< ES2020). If you are using webpack/babel to create your production bundles, you should target only the most modern browsers. For instance, for **React** apps created with [`create-react-app`](https://create-react-app.dev/), you should edit your `package.json` and modify the `browserList` so that it only targets the latest browsers (play with the number of versions that do not need polyfilling):
|
||||
> `{{PKG_NAME}}` uses [ES2020 BigInt](https://tc39.es/ecma262/#sec-bigint-objects), so take into account that:
|
||||
> 1. If you experience issues using webpack/babel to create your production bundles, you may edit the supported browsers list and leave only [supported browsers and versions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#Browser_compatibility). The browsers list is usually located in your project's `package.json` or the `.browserslistrc` file.
|
||||
> 2. In order to use `{{PKG_NAME}}` with TypeScript you need to set `target`, and `lib` and `module` if in use, to `ES2020` in your project's `tsconfig.json`.
|
||||
|
||||
```json
|
||||
"browserslist": {
|
||||
"production": [
|
||||
"last 1 chrome version",
|
||||
"last 1 firefox version",
|
||||
"last 1 safari version"
|
||||
],
|
||||
"development": [
|
||||
"last 1 chrome version",
|
||||
"last 1 firefox version",
|
||||
"last 1 safari version"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Also, notice that [BigInt implementation is ES2020](https://tc39.es/ecma262/#sec-bigint-objects). In order to use it with TypeScript you need to set `target` to `ES2020` in your project's `tsconfig.json`.
|
||||
|
||||
If you are using Angular, since this library uses node typings, you should also add them to the `angularCompilerOptions` in your `tsconfig.json`:
|
||||
|
||||
```json
|
||||
"angularCompilerOptions": {
|
||||
"types": ["node", ...]
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
You can also download the {{IIFE_BUNDLE}}, the {{ESM_BUNDLE}} or the {{UMD_BUNDLE}} and manually add it to your project, or, if you have already imported `{{PKG_NAME}}` to your project, just get the bundles from `node_modules/{{PKG_NAME}}/dist/bundles/`.
|
||||
You can also download the {{IIFE_BUNDLE}}, the {{ESM_BUNDLE}} or the {{UMD_BUNDLE}} and manually add it to your project, or, if you have already installed `{{PKG_NAME}}` in your project, just get the bundles from `node_modules/{{PKG_NAME}}/dist/bundles/`.
|
||||
|
||||
An example of usage could be:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"$schema": "https://json.schemastore.org/tsconfig",
|
||||
"compilerOptions": {
|
||||
"target": "es2020", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */
|
||||
"target": "ES2020", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */
|
||||
"lib": [ "es2020", "DOM" , "WebWorker"], /* Specify library files to be included in the compilation. */
|
||||
"allowJs": true, /* Allow javascript files to be compiled. */
|
||||
"checkJs": true, /* Report errors in .js files. */
|
||||
|
|
|
|||
Loading…
Reference in New Issue