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 <xmader@outlook.com>
Co-authored-by: Alex Potsides <alex@achingbrain.net>
Co-authored-by: achingbrain <alex@achingbrain.net>

.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/bundle-size@v28.0.0
+ with:
+ project: ${{ matrix.project }}
+ github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/typecheck.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/typescript-error-reporter-action@v1.0.8
+ with:
+ project: ${{ matrix.project }}
+

.travis.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

docs/core-api/BITSWAP.md

@@ -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/BLOCK.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/BOOTSTRAP.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/DHT.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/FILES.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/OBJECT.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/PUBSUB.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
 

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

@@ -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-ipns-publish/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/traverse-ipld-graphs/CHANGELOG.md

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

package.json

@@ -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",

packages/interface-ipfs-core/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": [