From 5bba6de3f9cd2b74bf5b5e3aa2646c641475b470 Mon Sep 17 00:00:00 2001 From: Juanra Dikal Date: Wed, 21 Apr 2021 20:05:45 +0200 Subject: [PATCH] better docs --- README.md | 32 ++++---------------------------- build/build.docs.js | 21 +++++++++++++-------- docs/API.md | 20 +++++++++----------- package.json | 3 +-- src/docs/index.md | 34 +++++----------------------------- tsconfig.json | 2 +- 6 files changed, 33 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index facc6ad..093c286 100644 --- a/README.md +++ b/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: diff --git a/build/build.docs.js b/build/build.docs.js index d766560..3a29e48 100644 --- a/build/build.docs.js +++ b/build/build.docs.js @@ -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 = /^(?:(?@.*?)\/)?(?.*)/ // 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 = `[![Node CI](https://github.com/${repoUsername}/${repoName}/workflows/Node%20CI/badge.svg)](https://github.com/${repoUsername}/${repoName}/actions?query=workflow%3A%22Node+CI%22)` coverallsBadge = `[![Coverage Status](https://coveralls.io/repos/github/${repoUsername}/${repoName}/badge.svg?branch=master)](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: diff --git a/docs/API.md b/docs/API.md index 45aadd9..f6349c2 100644 --- a/docs/API.md +++ b/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) ___ diff --git a/package.json b/package.json index 980bbb8..7793516 100644 --- a/package.json +++ b/package.json @@ -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}'", diff --git a/src/docs/index.md b/src/docs/index.md index 17c0d6d..954c087 100644 --- a/src/docs/index.md +++ b/src/docs/index.md @@ -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: diff --git a/tsconfig.json b/tsconfig.json index 6891f30..702962b 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -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. */