feat: type check & generate defs from jsdoc (#3281)

1. Add missing type info (via jsdoc) and fix existing one so that `tsc --noEmit` can succeed without an error.
2. Fix all the issues that `tsc` pointed out once it got enabled.
3. Add a npm script that generates typedefs & typedef maps in `dist` directory & corresponding settings in `package.json` so that when package installed from npm no config will be required to get all the typings.

Co-authored-by: Xmader <[email protected]>
Co-authored-by: Alex Potsides <[email protected]>
Co-authored-by: achingbrain <[email protected]>

Author: 3 people

.github/workflows/bundlesize.yml

@@ -0,0 +1,39 @@
+# Checks bundlesize, does not run on master
+on:
+  pull_request:
+    branches:
+      - '*'
+
+name: Bundlesize
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+        project:
+          - packages/ipfs-core-utils
+          - packages/ipfs-core
+          - packages/ipfs-http-client
+          - packages/ipfs
+          - packages/ipfs-message-port-protocol
+          - packages/ipfs-message-port-client
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Restore dependencies
+        id: cache-modules
+        uses: actions/checkout@v2
+        with:
+          path: node_modules
+          key: ${{ matrix.node-version }}-${{ runner.OS }}-build-${{ hashFiles('package.json') }}
+      - name: Install dependencies
+        run: npm install
+      - name: Bundlesize ${{ matrix.project }}
+        uses: ipfs/aegir/actions/[email protected]
+        with:
+          project: ${{ matrix.project }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/main.yml

@@ -0,0 +1,42 @@
+on:
+  pull_request:
+    branches:
+      - '*'
+
+name: Typecheck
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [12.x]
+        project:
+          - packages/ipfs-core-utils
+          - packages/ipfs-core
+          - packages/ipfs-http-client
+          - packages/ipfs
+          - packages/ipfs-cli
+          - packages/ipfs-http-server
+          - packages/ipfs-http-gateway
+          - packages/ipfs-message-port-protocol
+          - packages/ipfs-message-port-server
+          - packages/ipfs-message-port-client
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Restore dependencies
+        id: cache-modules
+        uses: actions/checkout@v2
+        with:
+          path: node_modules
+          key: ${{ matrix.node-version }}-${{ runner.OS }}-build-${{ hashFiles('package.json') }}
+      - name: Install dependencies
+        run: npm install
+      - name: Typecheck ${{ matrix.project }}
+        uses: gozala/[email protected]
+        with:
+          project: ${{ matrix.project }}
+

.github/workflows/typecheck.yml

@@ -229,12 +229,13 @@ jobs:
     - stage: test
       name: examples
       script:
-        - npx json -I -f ./lerna.json -e "this.packages.push('examples/*')"
-        - npx json -I -f ./lerna.json -e "this.command.bootstrap.nohoist = ['ipfs-css', 'tachyons']"
-        - npm run reset
-        - npm install
-        - npm run build -- --scope={ipfs,ipfs-http-client,ipfs-message-port-*}
-        - npm run test -- --scope=example* --concurrency=1
+        # Travis lets scripts continue even if previous steps fail: https://github.com/travis-ci/travis-ci/issues/1066
+        - npm run build -- --scope={ipfs-core,ipfs,ipfs-http-client,ipfs-message-port-*} &&
+          rm -rf node_modules packages/*/node_modules &&
+          npx json -I -f ./lerna.json -e "this.packages.push('examples/*')" &&
+          npx json -I -f ./lerna.json -e "this.command.bootstrap.nohoist = ['ipfs-css', 'tachyons']" &&
+          npm install &&
+          npm run test -- --scope=example* --concurrency=1
 
     - stage: release-rc
       # only run on changes to master

.travis.yml

@@ -62,7 +62,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| peerId | [PeerId][], [CID][], `String` or `Buffer` | A peer ID to return the wantlist for |
+| peerId | [PeerId][], [CID][], `String` or `Uint8Array` | A peer ID to return the wantlist for |
 
 ### Options
 

docs/core-api/BITSWAP.md

@@ -29,7 +29,7 @@
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| cid | [CID][], `String` or `Buffer` | A CID that corresponds to the desired block |
+| cid | [CID][], `String` or `Uint8Array` | A CID that corresponds to the desired block |
 
 ### Options
 
@@ -63,7 +63,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| block | A `Buffer` or [Block][] instance | The block or data to store |
+| block | A `Uint8Array` or [Block][] instance | The block or data to store |
 
 ### Options
 

docs/core-api/BLOCK.md

@@ -55,7 +55,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Object>` | An object that contains an array with all the added addresses |
+| `Promise<{ Peers: Array<MultiAddr> }>` | An object that contains an array with all the added addresses |
 
 example of the returned object:
 
@@ -141,7 +141,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Object>` | An object that contains an array with all the bootstrap addresses |
+| `Promise<{ Peers: Array<MultiAddr> }>` | An object that contains an array with all the bootstrap addresses |
 
 example of the returned object:
 
@@ -225,7 +225,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Object>` | An object that contains an array with all the removed addresses |
+| `Promise<{ Peers: Array<MultiAddr> }>` | An object that contains an array with all the removed addresses |
 
 ```JavaScript
 {

docs/core-api/BOOTSTRAP.md

@@ -126,7 +126,7 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| key | `Buffer` or `string` | The key associated with the value to find |
+| key | `Uint8Array` or `string` | The key associated with the value to find |
 
 ### Options
 
@@ -141,7 +141,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Buffer>` | The value that was stored under that key |
+| `Promise<Uint8Array>` | The value that was stored under that key |
 
 ### Example
 
@@ -228,8 +228,8 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| key | Buffer | The key to put the value as |
-| value | Buffer | Value to put |
+| key | Uint8Array | The key to put the value as |
+| value | Uint8Array | Value to put |
 
 ### Options
 

docs/core-api/DHT.md

@@ -242,8 +242,8 @@ An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| chunker | `String` | `'size-262144'` | chunking algorithm used to build ipfs DAGs |
-| cidVersion | `Number` | `0` | the CID version to use when storing the data |
+| chunker | `string` | `'size-262144'` | chunking algorithm used to build ipfs DAGs |
+| cidVersion | `number` | `0` | the CID version to use when storing the data |
 | enableShardingExperiment | `boolean` | `false` |  allows to create directories with an unlimited number of entries currently size of unixfs directories is limited by the maximum block size. Note that this is an experimental feature |
 | hashAlg | `String` | `'sha2-256'` | multihash hashing algorithm to use |
 | onlyHash | `boolean` | `false` | If true, will not add blocks to the blockstore |
@@ -415,7 +415,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `AsyncIterable<Buffer>` | An async iterable that yields [`Buffer`][b] objects with the contents of `path` |
+| `AsyncIterable<Uint8Array>` | An async iterable that yields `Uint8Array` objects with the contents of `path` |
 
 #### Example
 
@@ -842,7 +842,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `AsyncIterable<Buffer>` | An async iterable that yields [`Buffer`][b] objects with the contents of `path` |
+| `AsyncIterable<Uint8Array>` | An async iterable that yields `Uint8Array` objects with the contents of `path` |
 
 #### Example
 
@@ -866,7 +866,7 @@ console.log(uint8ArrayConcat(chunks).toString())
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | path | `String` | The [MFS path] where you will write to |
-| content | `String`, `Buffer`, `AsyncIterable<Buffer>` or [`Blob`][blob] | The content to write to the path |
+| content | `String`, `Uint8Array`, `AsyncIterable<Uint8Array>` or [`Blob`][blob] | The content to write to the path |
 
 #### Options
 
@@ -902,7 +902,7 @@ await ipfs.files.write('/hello-world', new TextEncoder().encode('Hello, world!')
 
 ### `ipfs.files.mv(...from, to, [options])`
 
-> Move files from one location to another#### Parameters
+> Move files from one location to another
 
 #### Parameters
 

docs/core-api/FILES.md

@@ -100,15 +100,15 @@ A great source of [examples][] can be found in the tests for this API.
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| obj | `Object{ Data: <data>, Links: [] }`, `Buffer` or [DAGNode][] | The MerkleDAG Node to be stored |
+| obj | `Object{ Data: <data>, Links: [] }`, `Uint8Array` or [DAGNode][] | The MerkleDAG Node to be stored |
 
 ### Options
 
 An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| enc | `String` | `undefined` | The encoding of the Buffer (json, yml, etc), if passed a Buffer |
+| enc | `String` | `undefined` | The encoding of the Uint8Array (json, yml, etc), if passed a Uint8Array |
 | timeout | `Number` | `undefined` | A timeout in ms |
 | signal | [AbortSignal][] | `undefined` |  Can be used to cancel any long running requests started as a result of this call |
 
@@ -195,7 +195,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `Promise<Buffer>` | An Promise that resolves to Buffer objects with the data that the MerkleDAG node contained |
+| `Promise<Uint8Array>` | An Promise that resolves to Uint8Array objects with the data that the MerkleDAG node contained |
 
 ### Example
 
@@ -431,7 +431,7 @@ A great source of [examples][] can be found in the tests for this API.
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | cid | [CID][] | Add data to the [DAGNode][] that corresponds to this CID |
-| data | `Buffer` | The data to append to the `.Data` field of the node |
+| data | `Uint8Array` | The data to append to the `.Data` field of the node |
 
 ### Options
 
@@ -465,7 +465,7 @@ A great source of [examples][] can be found in the tests for this API.
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | cid | [CID][] | Replace data of the [DAGNode][] that corresponds to this CID |
-| data | `Buffer` | The data to overwrite with |
+| data | `Uint8Array` | The data to overwrite with |
 
 ### Options
 

docs/core-api/OBJECT.md

@@ -32,7 +32,7 @@
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | topic | `String` | The topic name |
-| handler | `Function<(msg) => {}>` | Event handler which will be called with a message object everytime one is received. The `msg` has the format `{from: String, seqno: Buffer, data: Buffer, topicIDs: Array<String>}` |
+| handler | `Function<(msg) => {}>` | Event handler which will be called with a message object everytime one is received. The `msg` has the format `{from: String, seqno: Uint8Array, data: Uint8Array, topicIDs: Array<String>}` |
 
 ### Options
 
@@ -125,7 +125,7 @@ If **only** the `topic` param is provided, unsubscribe will remove **all** handl
 > Publish a data message to a pubsub topic.
 
 - `topic: String`
-- `data: Buffer|String` - The message to send
+- `data: Uint8Array|String` - The message to send
 
 ### Returns
 

docs/core-api/PUBSUB.md

@@ -27,7 +27,7 @@ const createFiles = (directory) => {
   return [{
     path: `${directory}/file1.txt`,
 
-    // content could be a stream, a url, a Buffer, a File etc
+    // content could be a stream, a url, a Uint8Array, a File etc
     content: 'one'
   }, {
     path: `${directory}/file2.txt`,

examples/browser-add-readable-stream/index.js

@@ -7,6 +7,7 @@ const pRetry = require("p-retry");
 const last = require("it-last");
 const cryptoKeys = require("human-crypto-keys"); // { getKeyPairFromSeed }
 const uint8ArrayToString = require('uint8arrays/to-string')
+const uint8ArrayFromString = require('uint8arrays/from-string')
 
 const { sleep, Logger, onEnterPress, catchAndLog } = require("./util");
 
@@ -142,7 +143,7 @@ async function main() {
       try {
         // quick and dirty key gen, don't do this in real life
         const key = await IPFS.multihashing.digest(
-          Buffer.from(keyName + Math.random().toString(36).substring(2)),
+          uint8ArrayFromString(keyName + Math.random().toString(36).substring(2)),
           "sha2-256"
         );
         const keyPair = await cryptoKeys.getKeyPairFromSeed(key, "rsa");

examples/browser-ipns-publish/index.js

@@ -87,7 +87,7 @@ Output:
 ```js
 { link:
    { '/':
-      <Buffer 12 20 8a…> } }
+      <Uint8Array 12 20 8a…> } }
 ```
 
 Now:
@@ -108,7 +108,7 @@ Output:
      codec: 'dag-pb',
      version: 0,
      multihash:
-      <Buffer 12 20 8a…> } }
+      <Uint8Array 12 20 8a…> } }
 ```
 
 See https://github.com/ipld/ipld/issues/44 for more information on why this

examples/traverse-ipld-graphs/CHANGELOG.md

@@ -22,6 +22,7 @@
     "test:interface:message-port-client": "lerna run test:interface:message-port-client",
     "coverage": "lerna run coverage",
     "build": "lerna run build",
+    "build:types": "lerna run build:types",
     "clean": "lerna run clean",
     "lint": "lerna run lint",
     "dep-check": "lerna run dep-check",

package.json

@@ -66,7 +66,7 @@
     "uint8arrays": "^1.1.0"
   },
   "devDependencies": {
-    "aegir": "^27.0.0",
+    "aegir": "^28.0.0",
     "ipfsd-ctl": "^7.0.2"
   },
   "contributors": [