From 1502822fc162c2fb35fb3ae735582dcbfe72fc85 Mon Sep 17 00:00:00 2001
From: Xmader <xmader@outlook.com>
Date: Thu, 3 Sep 2020 05:30:02 -0400
Subject: [PATCH] feat: add typeScript support (#3236)

TypeScript support for `ipfs` and `ipfs-http-client`

Refs: #2945
Refs: #1166

Co-authored-by: Irakli Gozalishvili <contact@gozala.io>
Co-authored-by: Alex Potsides <alex@achingbrain.net>
---
 package.json                       |  3 ++-
 src/add-all.js                     | 17 +++++++++++++++--
 src/add.js                         | 16 +++++++++++++++-
 src/bitswap/stat.js                |  7 ++++++-
 src/bitswap/unwant.js              |  7 ++++++-
 src/bitswap/wantlist-for-peer.js   |  7 ++++++-
 src/bitswap/wantlist.js            |  7 ++++++-
 src/block/get.js                   |  7 ++++++-
 src/block/put.js                   |  6 +++++-
 src/config/replace.js              |  2 +-
 src/dag/put.js                     |  2 +-
 src/files/write.js                 |  2 +-
 src/id.js                          |  7 ++++++-
 src/index.js                       | 14 +++++++++++---
 src/lib/configure.js               | 15 +++++++++++++--
 src/lib/to-url-search-params.js    |  4 ++++
 src/object/patch/append-data.js    |  2 +-
 src/object/patch/set-data.js       |  2 +-
 src/object/put.js                  |  2 +-
 src/pubsub/publish.js              |  2 +-
 src/pubsub/subscription-tracker.js |  2 +-
 src/resolve.js                     |  7 ++++++-
 src/version.js                     |  7 ++++++-
 23 files changed, 121 insertions(+), 26 deletions(-)

diff --git a/package.json b/package.json
index 06a29f033..bf85308b4 100644
--- a/package.json
+++ b/package.json
@@ -185,6 +185,7 @@
     "shunkin <hiyoko.san.ipod@gmail.com>",
     "victorbjelkholm <victorbjelkholm@gmail.com>",
     "Łukasz Magiera <magik6k@users.noreply.github.com>",
-    "Łukasz Magiera <magik6k@gmail.com>"
+    "Łukasz Magiera <magik6k@gmail.com>",
+    "Xmader <xmader@outlook.com>"
   ]
 }
diff --git a/src/add-all.js b/src/add-all.js
index de3483648..68088db5c 100644
--- a/src/add-all.js
+++ b/src/add-all.js
@@ -6,10 +6,14 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 module.exports = configure((api) => {
-  return async function * addAll (input, options = {}) {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../ipfs/src/core/components/add-all').AddAll<import('.').HttpOptions>}
+   */
+  async function * addAll (input, options = {}) {
     const progressFn = options.progress
 
     // allow aborting requests on body errors
@@ -39,8 +43,16 @@ module.exports = configure((api) => {
       }
     }
   }
+  return addAll
 })
 
+/**
+ * @typedef {import('../../ipfs/src/core/components/add-all').UnixFSEntry} UnixFSEntry
+ */
+
+/**
+ * @returns {UnixFSEntry}
+ */
 function toCoreInterface ({ name, hash, size, mode, mtime, mtimeNsecs }) {
   const output = {
     path: name,
@@ -59,5 +71,6 @@ function toCoreInterface ({ name, hash, size, mode, mtime, mtimeNsecs }) {
     }
   }
 
+  // @ts-ignore
   return output
 }
diff --git a/src/add.js b/src/add.js
index 3190b9a7d..7770be584 100644
--- a/src/add.js
+++ b/src/add.js
@@ -4,12 +4,26 @@ const addAll = require('./add-all')
 const last = require('it-last')
 const configure = require('./lib/configure')
 
+/**
+ * @typedef {import("./lib/core").ClientOptions} ClientOptions
+ */
+
+// eslint-disable-next-line valid-jsdoc
+/**
+ * @param {ClientOptions} options
+ */
 module.exports = (options) => {
   const all = addAll(options)
 
   return configure(() => {
-    return async function add (input, options = {}) { // eslint-disable-line require-await
+    // eslint-disable-next-line valid-jsdoc
+    /**
+     * @type {import('../../ipfs/src/core/components/add').Add<import('.').HttpOptions>}
+     */
+    async function add (input, options = {}) { // eslint-disable-line require-await
+      // @ts-ignore
       return last(all(input, options))
     }
+    return add
   })(options)
 }
diff --git a/src/bitswap/stat.js b/src/bitswap/stat.js
index ec2745896..8f1b64afa 100644
--- a/src/bitswap/stat.js
+++ b/src/bitswap/stat.js
@@ -6,7 +6,11 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../../ipfs/src/core/components/bitswap/stat').Stat<import('..').HttpOptions>}
+   */
+  async function stat (options = {}) {
     const res = await api.post('bitswap/stat', {
       searchParams: toUrlSearchParams(options),
       timeout: options.timeout,
@@ -16,6 +20,7 @@ module.exports = configure(api => {
 
     return toCoreInterface(await res.json())
   }
+  return stat
 })
 
 function toCoreInterface (res) {
diff --git a/src/bitswap/unwant.js b/src/bitswap/unwant.js
index b9706cebc..602776e7c 100644
--- a/src/bitswap/unwant.js
+++ b/src/bitswap/unwant.js
@@ -5,7 +5,11 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (cid, options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../../ipfs/src/core/components/bitswap/unwant').Unwant<import('..').HttpOptions>}
+   */
+  async function unwant (cid, options = {}) {
     const res = await api.post('bitswap/unwant', {
       timeout: options.timeout,
       signal: options.signal,
@@ -18,4 +22,5 @@ module.exports = configure(api => {
 
     return res.json()
   }
+  return unwant
 })
diff --git a/src/bitswap/wantlist-for-peer.js b/src/bitswap/wantlist-for-peer.js
index b777ee7d6..7d0599a38 100644
--- a/src/bitswap/wantlist-for-peer.js
+++ b/src/bitswap/wantlist-for-peer.js
@@ -5,7 +5,11 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (peerId, options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../../ipfs/src/core/components/bitswap/wantlist-for-peer').WantlistForPeer<import('..').HttpOptions>}
+   */
+  async function wantlistForPeer (peerId, options = {}) {
     peerId = typeof peerId === 'string' ? peerId : new CID(peerId).toString()
 
     const res = await (await api.post('bitswap/wantlist', {
@@ -20,4 +24,5 @@ module.exports = configure(api => {
 
     return (res.Keys || []).map(k => new CID(k['/']))
   }
+  return wantlistForPeer
 })
diff --git a/src/bitswap/wantlist.js b/src/bitswap/wantlist.js
index 2599c7ed7..96f33cad9 100644
--- a/src/bitswap/wantlist.js
+++ b/src/bitswap/wantlist.js
@@ -5,7 +5,11 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../../ipfs/src/core/components/bitswap/wantlist').WantlistFn<import('..').HttpOptions>}
+   */
+  async function wantlist (options = {}) {
     const res = await (await api.post('bitswap/wantlist', {
       timeout: options.timeout,
       signal: options.signal,
@@ -15,4 +19,5 @@ module.exports = configure(api => {
 
     return (res.Keys || []).map(k => new CID(k['/']))
   }
+  return wantlist
 })
diff --git a/src/block/get.js b/src/block/get.js
index f39aa6d96..18a1fdf3a 100644
--- a/src/block/get.js
+++ b/src/block/get.js
@@ -6,7 +6,11 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (cid, options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../../ipfs/src/core/components/block/get').BlockGet<import('..').HttpOptions>}
+   */
+  async function get (cid, options = {}) {
     cid = new CID(cid)
 
     const res = await api.post('block/get', {
@@ -21,4 +25,5 @@ module.exports = configure(api => {
 
     return new Block(new Uint8Array(await res.arrayBuffer()), cid)
   }
+  return get
 })
diff --git a/src/block/put.js b/src/block/put.js
index 09888a815..5d3f62803 100644
--- a/src/block/put.js
+++ b/src/block/put.js
@@ -7,9 +7,13 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 module.exports = configure(api => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../../ipfs/src/core/components/block/put').BlockPut<import('..').HttpOptions>}
+   */
   async function put (data, options = {}) {
     if (Block.isBlock(data)) {
       const { name, length } = multihash.decode(data.cid.multihash)
diff --git a/src/config/replace.js b/src/config/replace.js
index 63ced0e20..33df9ed5a 100644
--- a/src/config/replace.js
+++ b/src/config/replace.js
@@ -5,7 +5,7 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 module.exports = configure(api => {
   return async (config, options = {}) => {
diff --git a/src/dag/put.js b/src/dag/put.js
index e4f261c63..d0a395b43 100644
--- a/src/dag/put.js
+++ b/src/dag/put.js
@@ -9,7 +9,7 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 const multicodec = require('multicodec')
 
 module.exports = configure((api, opts) => {
diff --git a/src/files/write.js b/src/files/write.js
index c3e72c9bb..0fcbbec80 100644
--- a/src/files/write.js
+++ b/src/files/write.js
@@ -6,7 +6,7 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 module.exports = configure(api => {
   return async (path, input, options = {}) => {
diff --git a/src/id.js b/src/id.js
index e86846076..a4e86eb02 100644
--- a/src/id.js
+++ b/src/id.js
@@ -6,7 +6,11 @@ const configure = require('./lib/configure')
 const toUrlSearchParams = require('./lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../ipfs/src/core/components/id').Id<import('.').HttpOptions>}
+   */
+  async function id (options = {}) {
     const res = await api.post('id', {
       timeout: options.timeout,
       signal: options.signal,
@@ -23,4 +27,5 @@ module.exports = configure(api => {
 
     return output
   }
+  return id
 })
diff --git a/src/index.js b/src/index.js
index 3d0eeeedd..acd27d14f 100644
--- a/src/index.js
+++ b/src/index.js
@@ -14,9 +14,17 @@ const urlSource = require('ipfs-utils/src/files/url-source')
  */
 
 /**
- *
- * @param {ClientOptions } options
- * @return {Object}
+ * @typedef {object} HttpOptions
+ * @property {Headers | Record<string, string>} [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.
+ * @property {URLSearchParams | Record<string, string>} [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.
+ * @property {object} [ipld]
+ * @property {any[]} [ipld.formats] - An array of additional [IPLD formats](https://github.com/ipld/interface-ipld-format) to support
+ * @property {(format: string) => Promise<any>} [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
+ */
+
+// eslint-disable-next-line valid-jsdoc
+/**
+ * @param {ClientOptions} options
  */
 function ipfsClient (options = {}) {
   return {
diff --git a/src/lib/configure.js b/src/lib/configure.js
index 49b2d2f5a..6396c05d1 100644
--- a/src/lib/configure.js
+++ b/src/lib/configure.js
@@ -9,8 +9,19 @@ const Client = require('./core')
  */
 
 /**
- * @param {function(Client, ClientOptions): void} fn
- * @returns {function(ClientOptions): void}
+ * @template T
+ * @typedef {(client: Client, clientOptions: ClientOptions) => T} Fn
+ */
+
+/**
+ * @template T
+ * @typedef {(clientOptions: ClientOptions) => T} Factory
+ */
+
+/**
+ * @template T
+ * @param {Fn<T>} fn
+ * @returns {Factory<T>}
  */
 const configure = (fn) => {
   return (options) => {
diff --git a/src/lib/to-url-search-params.js b/src/lib/to-url-search-params.js
index 1e0bbeb4b..10f12d83d 100644
--- a/src/lib/to-url-search-params.js
+++ b/src/lib/to-url-search-params.js
@@ -3,6 +3,10 @@
 const modeToString = require('./mode-to-string')
 const mtimeToObject = require('./mtime-to-object')
 
+/**
+ * @param {object} params
+ * @returns {URLSearchParams}
+ */
 module.exports = ({ arg, searchParams, hashAlg, mtime, mode, ...options } = {}) => {
   if (searchParams) {
     options = {
diff --git a/src/object/patch/append-data.js b/src/object/patch/append-data.js
index c33490750..bb27ea8fc 100644
--- a/src/object/patch/append-data.js
+++ b/src/object/patch/append-data.js
@@ -5,7 +5,7 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 module.exports = configure(api => {
   return async (cid, data, options = {}) => {
diff --git a/src/object/patch/set-data.js b/src/object/patch/set-data.js
index 59c3394b5..a2aa4180f 100644
--- a/src/object/patch/set-data.js
+++ b/src/object/patch/set-data.js
@@ -5,7 +5,7 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 module.exports = configure(api => {
   return async (cid, data, options = {}) => {
diff --git a/src/object/put.js b/src/object/put.js
index c9e46898a..f5aa827cd 100644
--- a/src/object/put.js
+++ b/src/object/put.js
@@ -6,7 +6,7 @@ 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 AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 const unit8ArrayToString = require('uint8arrays/to-string')
 const uint8ArrayFromString = require('uint8arrays/from-string')
 
diff --git a/src/pubsub/publish.js b/src/pubsub/publish.js
index 0b24f4fc2..9ec83bc69 100644
--- a/src/pubsub/publish.js
+++ b/src/pubsub/publish.js
@@ -4,7 +4,7 @@ const configure = require('../lib/configure')
 const toUrlSearchParams = require('../lib/to-url-search-params')
 const multipartRequest = require('../lib/multipart-request')
 const anySignal = require('any-signal')
-const AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 module.exports = configure(api => {
   return async (topic, data, options = {}) => {
diff --git a/src/pubsub/subscription-tracker.js b/src/pubsub/subscription-tracker.js
index 191f832ce..d5640bdd1 100644
--- a/src/pubsub/subscription-tracker.js
+++ b/src/pubsub/subscription-tracker.js
@@ -1,6 +1,6 @@
 'use strict'
 
-const AbortController = require('abort-controller')
+const { AbortController } = require('abort-controller')
 
 class SubscriptionTracker {
   constructor () {
diff --git a/src/resolve.js b/src/resolve.js
index a7635dad1..1dbac9256 100644
--- a/src/resolve.js
+++ b/src/resolve.js
@@ -4,7 +4,11 @@ const configure = require('./lib/configure')
 const toUrlSearchParams = require('./lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (path, options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../ipfs/src/core/components/resolve').Resolve<import('.').HttpOptions>}
+   */
+  async function resolve (path, options = {}) {
     const res = await api.post('resolve', {
       timeout: options.timeout,
       signal: options.signal,
@@ -17,4 +21,5 @@ module.exports = configure(api => {
     const { Path } = await res.json()
     return Path
   }
+  return resolve
 })
diff --git a/src/version.js b/src/version.js
index 28c49101b..67d1ab314 100644
--- a/src/version.js
+++ b/src/version.js
@@ -5,7 +5,11 @@ const configure = require('./lib/configure')
 const toUrlSearchParams = require('./lib/to-url-search-params')
 
 module.exports = configure(api => {
-  return async (options = {}) => {
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @type {import('../../ipfs/src/core/components/version').Version<import('.').HttpOptions>}
+   */
+  async function version (options = {}) {
     const res = await api.post('version', {
       timeout: options.timeout,
       signal: options.signal,
@@ -16,4 +20,5 @@ module.exports = configure(api => {
 
     return toCamel(data)
   }
+  return version
 })