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

.aegir.js

@@ -16,7 +16,7 @@ const server = createServer({
 let echoServer = new EchoServer()
 
 module.exports = {
-  bundlesize: { maxSize: '90kB' },
+  bundlesize: { maxSize: '81kB' },
   karma: {
     files: [{
       pattern: 'node_modules/interface-ipfs-core/test/fixtures/**/*',

README.md

@@ -96,8 +96,6 @@ All core API methods take _additional_ `options` specific to the HTTP API:
 
 * `headers` - An object or [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) instance that can be used to set custom HTTP headers. Note that this option can also be [configured globally](#custom-headers) via the constructor options.
 * `searchParams` - An object or [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) instance that can be used to add additional query parameters to the query string sent with each request.
-* `ipld.formats` - An array of additional [IPLD formats](https://github.com/ipld/interface-ipld-format) to support
-* `ipld.loadFormat` an async function that takes the name of an [IPLD format](https://github.com/ipld/interface-ipld-format) as a string and should return the implementation of that codec
 
 ### Instance Utils
 

package.json

@@ -20,6 +20,13 @@
     "go-ipfs": false,
     "ipfs-core-utils/src/files/normalise-input": "ipfs-core-utils/src/files/normalise-input/index.browser.js"
   },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "dist/*"
+      ]
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ipfs/js-ipfs.git"
@@ -34,7 +41,9 @@
     "test:chrome": "cross-env ECHO_SERVER_PORT=37496 aegir test -t browser -t webworker -- --browsers ChromeHeadless",
     "test:firefox": "cross-env ECHO_SERVER_PORT=37497 aegir test -t browser -t webworker -- --browsers FirefoxHeadless",
     "lint": "aegir lint",
-    "build": "aegir build",
+    "build": "npm run build:js && npm run build:types",
+    "build:js": "aegir build",
+    "build:types": "tsc --build",
     "coverage": "npx nyc -r html npm run test:node -- --bail",
     "clean": "rm -rf ./dist",
     "dep-check": "aegir dep-check"
@@ -70,15 +79,17 @@
     "uint8arrays": "^1.1.0"
   },
   "devDependencies": {
-    "aegir": "^27.0.0",
+    "aegir": "^28.0.0",
     "cross-env": "^7.0.0",
     "go-ipfs": "^0.7.0",
     "interface-ipfs-core": "^0.140.0",
     "ipfsd-ctl": "^7.0.2",
     "it-all": "^1.0.4",
     "it-concat": "^1.0.1",
     "it-pipe": "^1.1.0",
-    "nock": "^13.0.2"
+    "nock": "^13.0.2",
+    "ipfs-core": "0.0.1",
+    "typescript": "^4.0.3"
   },
   "engines": {
     "node": ">=10.3.0",

src/add-all.js

@@ -5,14 +5,14 @@ const toCamel = require('./lib/object-to-camel')
 const configure = require('./lib/configure')
 const multipartRequest = require('./lib/multipart-request')
 const toUrlSearchParams = require('./lib/to-url-search-params')
-const anySignal = require('any-signal')
+const { anySignal } = require('any-signal')
 const AbortController = require('native-abort-controller')
 
 module.exports = configure((api) => {
   /**
-   * @type {import('../../ipfs/src/core/components/add-all').AddAll<import('.').HttpOptions>}
+   * @type {import('.').Implements<import('ipfs-core/src/components/add-all/index')>}
    */
-  async function * addAll (input, options = {}) {
+  async function * addAll (source, options = {}) {
     const progressFn = options.progress
 
     // allow aborting requests on body errors
@@ -28,7 +28,7 @@ module.exports = configure((api) => {
       timeout: options.timeout,
       signal,
       ...(
-        await multipartRequest(input, controller, options.headers)
+        await multipartRequest(source, controller, options.headers)
       )
     })
 
@@ -46,11 +46,7 @@ module.exports = configure((api) => {
 })
 
 /**
- * @typedef {import('../../ipfs/src/core/components/add-all').UnixFSEntry} UnixFSEntry
- */
-
-/**
- * @param {*} input
+ * @param {any} input
  * @returns {UnixFSEntry}
  */
 function toCoreInterface ({ name, hash, size, mode, mtime, mtimeNsecs }) {
@@ -71,6 +67,9 @@ function toCoreInterface ({ name, hash, size, mode, mtime, mtimeNsecs }) {
     }
   }
 
-  // @ts-ignore
   return output
 }
+
+/**
+ * @typedef {import('ipfs-core/src/components/add-all/index').UnixFSEntry} UnixFSEntry
+ */

src/add.js

@@ -5,22 +5,17 @@ const last = require('it-last')
 const configure = require('./lib/configure')
 
 /**
- * @typedef {import("./lib/core").ClientOptions} ClientOptions
- */
-
-/**
- * @param {ClientOptions} options
+ * @param {import("./lib/core").ClientOptions} options
  */
 module.exports = (options) => {
   const all = addAll(options)
-
   return configure(() => {
     /**
-     * @type {import('../../ipfs/src/core/components/add').Add<import('.').HttpOptions>}
+     * @type {import('.').Implements<import('ipfs-core/src/components/add')>}
      */
-    async function add (input, options = {}) { // eslint-disable-line require-await
-      // @ts-ignore
-      return last(all(input, options))
+    async function add (input, options = {}) {
+      // @ts-ignore - last may return undefind if source is empty
+      return await last(all(input, options))
     }
     return add
   })(options)

src/bitswap/stat.js

@@ -7,7 +7,7 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('../../../ipfs/src/core/components/bitswap/stat').Stat<import('..').HttpOptions>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bitswap/stat')>}
    */
   async function stat (options = {}) {
     const res = await api.post('bitswap/stat', {

src/bitswap/unwant.js

@@ -6,13 +6,14 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('../../../ipfs/src/core/components/bitswap/unwant').Unwant<import('..').HttpOptions>}
+   * @type {import('..').Implements<import('ipfs-core/src/components/bitswap/unwant')>}
    */
   async function unwant (cid, options = {}) {
     const res = await api.post('bitswap/unwant', {
       timeout: options.timeout,
       signal: options.signal,
       searchParams: toUrlSearchParams({
+        // @ts-ignore - CID|string seems to confuse typedef
         arg: typeof cid === 'string' ? cid : new CID(cid).toString(),
         ...options
       }),

src/bitswap/wantlist-for-peer.js

@@ -6,9 +6,10 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('../../../ipfs/src/core/components/bitswap/wantlist-for-peer').WantlistForPeer<import('..').HttpOptions>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bitswap/wantlist-for-peer')>}
    */
   async function wantlistForPeer (peerId, options = {}) {
+    // @ts-ignore - CID|string seems to confuse typedef
     peerId = typeof peerId === 'string' ? peerId : new CID(peerId).toString()
 
     const res = await (await api.post('bitswap/wantlist', {

src/bitswap/wantlist.js

@@ -6,7 +6,7 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('../../../ipfs/src/core/components/bitswap/wantlist').WantlistFn<import('..').HttpOptions>}
+   * @type {import('..').Implements<typeof import('ipfs-core/src/components/bitswap/wantlist')>}
    */
   async function wantlist (options = {}) {
     const res = await (await api.post('bitswap/wantlist', {

src/block/get.js

@@ -7,9 +7,10 @@ const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
   /**
-   * @type {import('../../../ipfs/src/core/components/block/get').BlockGet<import('..').HttpOptions>}
+   * @type {import('..').Implements<import('ipfs-core/src/components/block/get')>}
    */
   async function get (cid, options = {}) {
+    // @ts-ignore - CID|string seems to confuse typedef
     cid = new CID(cid)
 
     const res = await api.post('block/get', {

src/block/put.js

@@ -6,12 +6,12 @@ const multihash = require('multihashes')
 const multipartRequest = require('../lib/multipart-request')
 const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
-const anySignal = require('any-signal')
+const { anySignal } = require('any-signal')
 const AbortController = require('native-abort-controller')
 
 module.exports = configure(api => {
   /**
-   * @type {import('../../../ipfs/src/core/components/block/put').BlockPut<import('..').HttpOptions>}
+   * @type {import('..').Implements<import('ipfs-core/src/components/block/put')>}
    */
   async function put (data, options = {}) {
     if (Block.isBlock(data)) {

src/block/rm.js

@@ -5,7 +5,10 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async function * rm (cid, options = {}) {
+  /**
+   * @type {import('..').Implements<import('ipfs-core/src/components/block/rm')>}
+   */
+  async function * rm (cid, options = {}) {
     if (!Array.isArray(cid)) {
       cid = [cid]
     }
@@ -25,6 +28,8 @@ module.exports = configure(api => {
       yield toCoreInterface(removed)
     }
   }
+
+  return rm
 })
 
 function toCoreInterface (removed) {

src/block/stat.js

@@ -5,7 +5,10 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (cid, options = {}) => {
+  /**
+   * @type {import('..').Implements<import('ipfs-core/src/components/block/stat')>}
+   */
+  async function stat (cid, options = {}) {
     const res = await api.post('block/stat', {
       timeout: options.timeout,
       signal: options.signal,
@@ -19,4 +22,6 @@ module.exports = configure(api => {
 
     return { cid: new CID(data.Key), size: data.Size }
   }
+
+  return stat
 })

src/bootstrap/add.js

@@ -1,16 +1,14 @@
 'use strict'
 
-const Multiaddr = require('multiaddr')
 const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
+const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
-  return async (addr, options = {}) => {
-    if (addr && typeof addr === 'object' && !Multiaddr.isMultiaddr(addr)) {
-      options = addr
-      addr = null
-    }
-
+  /**
+   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/add')>}
+   */
+  async function add (addr, options = {}) {
     const res = await api.post('bootstrap/add', {
       timeout: options.timeout,
       signal: options.signal,
@@ -21,6 +19,10 @@ module.exports = configure(api => {
       headers: options.headers
     })
 
-    return res.json()
+    const { Peers } = await res.json()
+
+    return { Peers: Peers.map(ma => new Multiaddr(ma)) }
   }
+
+  return add
 })

src/bootstrap/clear.js

@@ -2,9 +2,13 @@
 
 const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
+const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
-  return async (options = {}) => {
+  /**
+   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/clear')>}
+   */
+  async function clear (options = {}) {
     const res = await api.post('bootstrap/rm', {
       timeout: options.timeout,
       signal: options.signal,
@@ -15,6 +19,10 @@ module.exports = configure(api => {
       headers: options.headers
     })
 
-    return res.json()
+    const { Peers } = await res.json()
+
+    return { Peers: Peers.map(ma => new Multiaddr(ma)) }
   }
+
+  return clear
 })

src/bootstrap/list.js

@@ -2,16 +2,24 @@
 
 const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
+const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
-  return async (options = {}) => {
+  /**
+   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/list')>}
+   */
+  async function list (options = {}) {
     const res = await api.post('bootstrap/list', {
       timeout: options.timeout,
       signal: options.signal,
       searchParams: toUrlSearchParams(options),
       headers: options.headers
     })
 
-    return res.json()
+    const { Peers } = await res.json()
+
+    return { Peers: Peers.map(ma => new Multiaddr(ma)) }
   }
+
+  return list
 })

src/bootstrap/reset.js

@@ -2,9 +2,13 @@
 
 const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
+const Multiaddr = require('multiaddr')
 
 module.exports = configure(api => {
-  return async (options = {}) => {
+  /**
+   * @type {import('..').Implements<import('ipfs-core/src/components/bootstrap/reset')>}
+   */
+  async function reset (options = {}) {
     const res = await api.post('bootstrap/add', {
       timeout: options.timeout,
       signal: options.signal,
@@ -15,6 +19,10 @@ module.exports = configure(api => {
       headers: options.headers
     })
 
-    return res.json()
+    const { Peers } = await res.json()
+
+    return { Peers: Peers.map(ma => new Multiaddr(ma)) }
   }
+
+  return reset
 })