feat: add typeScript support

docs/core-api/FILES.md

@@ -162,7 +162,7 @@ An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| chunker | `String` | `'size-262144` | chunking algorithm used to build ipfs DAGs |
+| chunker | `String` | `'size-262144'` | chunking algorithm used to build ipfs DAGs |
 | cidVersion | `Number` | `0` | the CID version to use when storing the data |
 | hashAlg | `String` | `'sha2-256'` | multihash hashing algorithm to use |
 | onlyHash | `boolean` | `false` | If true, will not add blocks to the blockstore |
@@ -178,7 +178,7 @@ An optional object which may have the following keys:
 
 | Type | Description |
 | -------- | -------- |
-| `UnixFSEntry` | A object describing the added data |
+| `Promise<UnixFSEntry>` | A object describing the added data |
 
 Each yielded object is of the form:
 
@@ -226,7 +226,7 @@ Now [ipfs.io/ipfs/Qm..pg/myfile.txt](https://ipfs.io/ipfs/QmWXdjNC362aPDtwHPUE9o
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| source | [FileStream<FileContent|FileObject>](#filestream) | Data to import (see below) |
+| source | [FileStream<FileContent\|FileObject>](#filestream) | Data to import (see below) |
 
 ##### FileStream
 
@@ -242,7 +242,7 @@ An optional object which may have the following keys:
 
 | Name | Type | Default | Description |
 | ---- | ---- | ------- | ----------- |
-| chunker | `String` | `'size-262144` | chunking algorithm used to build ipfs DAGs |
+| 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 |

packages/ipfs/package.json

@@ -346,6 +346,7 @@
     "tcme <hi@this-connect.me>",
     "victorbjelkholm <victorbjelkholm@gmail.com>",
     "Łukasz Magiera <magik6k@users.noreply.github.com>",
-    "Максим Ильин <negamaxi@gmail.com>"
+    "Максим Ильин <negamaxi@gmail.com>",
+    "Xmader <xmader@outlook.com>"
   ]
 }

packages/ipfs/src/core/api-manager.js

@@ -1,8 +1,22 @@
 'use strict'
 
 module.exports = class ApiManager {
+  /**
+   * @callback UndefFn
+   * @param {PropertyKey} prop
+   */
+
+  /**
+   * @template API
+   * @typedef {{ cancel(): any; api: API; }} Updated
+   */
+
   constructor () {
     this._api = {}
+    /**
+     * @type {UndefFn}
+     * @returns {any}
+     */
     this._onUndef = () => undefined
     this.api = new Proxy(this._api, {
       get: (_, prop) => {
@@ -12,12 +26,18 @@ module.exports = class ApiManager {
     })
   }
 
+  /**
+   * @template A
+   * @param {A} nextApi
+   * @param {UndefFn} [onUndef]
+   * @returns {Updated<A>}
+   */
   update (nextApi, onUndef) {
     const prevApi = { ...this._api }
     const prevUndef = this._onUndef
     Object.keys(this._api).forEach(k => { delete this._api[k] })
-    Object.assign(this._api, nextApi)
+    const api = Object.assign(this._api, nextApi)
     if (onUndef) this._onUndef = onUndef
-    return { cancel: () => this.update(prevApi, prevUndef), api: this.api }
+    return { cancel: () => this.update(prevApi, prevUndef), api }
   }
 }

packages/ipfs/src/core/components/add-all/index.js

@@ -3,13 +3,64 @@
 const importer = require('ipfs-unixfs-importer')
 const normaliseAddInput = require('ipfs-core-utils/src/files/normalise-input')
 const { parseChunkerString } = require('./utils')
-const pipe = require('it-pipe')
+const { pipe } = require('it-pipe')
 const { withTimeoutOption } = require('../../utils')
 
+/**
+ * @typedef {Uint8Array | Blob | String | Iterable<Uint8Array|Number> | AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>} FileContent
+ *
+ * @typedef {object} FileObject
+ *  - If no path is specified, then the item will be added to the root level and will be given a name according to it's CID.
+ *  - If no content is passed, then the item is treated as an empty directory.
+ *  - One of path or content must be passed.
+ * @property {string} [path] - The path you want to the file to be accessible at from the root CID _after_ it has been added
+ * @property {FileContent} [content] - The contents of the file
+ * @property {number | string} [mode] - File mode to store the entry with (see https://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation)
+ * @property {UnixTime} [mtime] - The modification time of the entry
+ *
+ * @typedef {FileContent | FileObject} Source
+ * @typedef {Iterable<Source> | AsyncIterable<Source> | ReadableStream<Source>} FileStream
+ *
+ * @typedef {Date | UnixTimeObj | [number, number]} UnixTime - As an array of numbers, it must have two elements, as per the output of [`process.hrtime()`](https://nodejs.org/dist/latest/docs/api/process.html#process_process_hrtime_time).
+ *
+ * @typedef {object} UnixTimeObj
+ * @property {number} secs - the number of seconds since (positive) or before (negative) the Unix Epoch began
+ * @property {number} [nsecs] - the number of nanoseconds since the last full second.
+ *
+ * @typedef {object} UnixFSEntry
+ * @property {string} path
+ * @property {import('cids')} cid
+ * @property {number} mode
+ * @property {UnixTimeObj} mtime
+ * @property {number} size
+ */
+
 module.exports = ({ block, gcLock, preload, pin, options: constructorOptions }) => {
   const isShardingEnabled = constructorOptions.EXPERIMENTAL && constructorOptions.EXPERIMENTAL.sharding
 
-  return withTimeoutOption(async function * addAll (source, options) {
+  /**
+   * Import multiple files and data into IPFS.
+   *
+   * @param {FileStream} source
+   *
+   * @param {object} [options]
+   * @param {string} [options.chunker] - chunking algorithm used to build ipfs DAGs (default: `'size-262144'`)
+   * @param {Number} [options.cidVersion] - the CID version to use when storing the data (default: `0`)
+   * @param {boolean} [options.enableShardingExperiment] - 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 (default: `false`)
+   * @param {String} [options.hashAlg] - multihash hashing algorithm to use (default: `'sha2-256'`)
+   * @param {boolean} [options.onlyHash] - If true, will not add blocks to the blockstore (default: `false`)
+   * @param {boolean} [options.pin] - pin this object when adding (default: `true`)
+   * @param {function} [options.progress] - a function that will be called with the byte length of chunks as a file is added to ipfs (default: `undefined`)
+   * @param {boolean} [options.rawLeaves] - if true, DAG leaves will contain raw file data and not be wrapped in a protobuf (default: `false`)
+   * @param {Number} [options.shardSplitThreshold] - Directories with more than this number of files will be created as HAMT-sharded directories (default: `1000`)
+   * @param {boolean} [options.trickle] - if true will use the [trickle DAG](https://godoc.org/github.com/ipsn/go-ipfs/gxlibs/github.com/ipfs/go-unixfs/importer/trickle) format for DAG generation (default: `false`)
+   * @param {boolean} [options.wrapWithDirectory] - Adds a wrapping node around the content (default: `false`)
+   * @param {Number} [options.timeout] - A timeout in ms (default: `undefined`)
+   * @param {AbortSignal} [options.signal] - Can be used to cancel any long running requests started as a result of this call (default: `undefined`)
+
+   * @returns {AsyncIterable<UnixFSEntry>}
+   */
+  async function * addAll (source, options) {
     options = options || {}
 
     const opts = {
@@ -58,7 +109,9 @@ module.exports = ({ block, gcLock, preload, pin, options: constructorOptions })
     } finally {
       releaseLock()
     }
-  })
+  }
+
+  return withTimeoutOption(addAll)
 }
 
 function transformFile (opts) {

packages/ipfs/src/core/components/add.js

@@ -2,8 +2,34 @@
 
 const last = require('it-last')
 
+/**
+ * @typedef {import('./add-all').Source} Source
+ * @typedef {import('./add-all').UnixFSEntry} UnixFSEntry
+ */
+
 module.exports = ({ addAll }) => {
-  return async function add (source, options) { // eslint-disable-line require-await
+  /**
+   * Import a file or data into IPFS.
+   *
+   * @param {Source} source - Data to import
+   *
+   * @param {object} [options]
+   * @param {String} [options.chunker] - chunking algorithm used to build ipfs DAGs (default: `'size-262144'`)
+   * @param {Number} [options.cidVersion] - the CID version to use when storing the data (default: `0`)
+   * @param {String} [options.hashAlg] - multihash hashing algorithm to use (default: `'sha2-256'`)
+   * @param {boolean} [options.onlyHash] - If true, will not add blocks to the blockstore (default: `false`)
+   * @param {boolean} [options.pin] - pin this object when adding (default: `true`)
+   * @param {function} [options.progress] - a function that will be called with the byte length of chunks as a file is added to ipfs (default: `undefined`)
+   * @param {boolean} [options.rawLeaves] - if true, DAG leaves will contain raw file data and not be wrapped in a protobuf (default: `false`)
+   * @param {boolean} [options.trickle] - if true will use the [trickle DAG](https://godoc.org/github.com/ipsn/go-ipfs/gxlibs/github.com/ipfs/go-unixfs/importer/trickle) format for DAG generation (default: `false`)
+   * @param {boolean} [options.wrapWithDirectory] - Adds a wrapping node around the content (default: `false`)
+   * @param {Number} [options.timeout] - A timeout in ms (default: `undefined`)
+   * @param {AbortSignal} [options.signal] - Can be used to cancel any long running requests started as a result of this call (default: `undefined`)
+   *
+   * @returns {Promise<UnixFSEntry>}
+   */
+  async function add (source, options) { // eslint-disable-line require-await
     return last(addAll(source, options))
   }
+  return add
 }

packages/ipfs/src/core/components/bitswap/stat.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const Big = require('bignumber.js')
+const Big = require('bignumber.js').default
 const CID = require('cids')
 const { withTimeoutOption } = require('../../utils')
 

packages/ipfs/src/core/components/block/rm.js

@@ -3,7 +3,7 @@
 const CID = require('cids')
 const errCode = require('err-code')
 const { parallelMap, filter } = require('streaming-iterables')
-const pipe = require('it-pipe')
+const { pipe } = require('it-pipe')
 const { PinTypes } = require('../pin/pin-manager')
 const { cleanCid } = require('./utils')
 const { withTimeoutOption } = require('../../utils')

packages/ipfs/src/core/components/index.js

@@ -77,8 +77,7 @@ exports.pin = {
 }
 exports.ping = require('./ping')
 exports.pubsub = require('./pubsub')
-exports.refs = require('./refs')
-exports.refs.local = require('./refs/local')
+exports.refs = Object.assign({}, require('./refs'), { local: require('./refs/local') })
 exports.repo = {
   gc: require('./repo/gc'),
   stat: require('./repo/stat'),

packages/ipfs/src/core/components/init.js

@@ -166,12 +166,14 @@ module.exports = ({
     })
 
     apiManager.update(api, () => { throw new NotStartedError() })
+
+    /** @type {typeof api} */
+    const initializedApi = apiManager.api
+    return initializedApi
   } catch (err) {
     cancel()
     throw err
   }
-
-  return apiManager.api
 }
 
 async function initNewRepo (repo, { privateKey, emptyRepo, algorithm, bits, profiles, config, pass, print }) {

packages/ipfs/src/core/components/start.js

@@ -143,16 +143,24 @@ module.exports = ({
     })
 
     apiManager.update(api, () => undefined)
+
+    /** @type {typeof api} */
+    const startedApi = apiManager.api
+    startPromise.resolve(startedApi)
+    return startedApi
   } catch (err) {
     cancel()
     startPromise.reject(err)
     throw err
   }
-
-  startPromise.resolve(apiManager.api)
-  return apiManager.api
 })
 
+// eslint-disable-next-line valid-jsdoc
+/**
+ * @template LIBP2P
+ * @template BlockAPI, DagAPI, FilesAPI, PinAPI
+ * @param {{ [x: string]: any; libp2p: LIBP2P; block: BlockAPI; dag: DagAPI; files: FilesAPI; pin: PinAPI; }} options
+ */
 function createApi ({
   apiManager,
   bitswap,
@@ -222,8 +230,10 @@ function createApi ({
     resolve: Components.name.resolve({ dns, ipns, peerId, isOnline, options: constructorOptions })
   }
   const resolve = Components.resolve({ name, ipld })
-  const refs = Components.refs({ ipld, resolve, preload })
-  refs.local = Components.refs.local({ repo })
+  const refs = Object.assign({},
+    Components.refs({ ipld, resolve, preload }),
+    { local: Components.refs.local({ repo }) }
+  )
 
   const pubsubNotEnabled = async () => { // eslint-disable-line require-await
     throw new NotEnabledError('pubsub not enabled')

packages/ipfs/src/core/components/stop.js

@@ -18,7 +18,7 @@ module.exports = ({
   libp2p,
   mfsPreload,
   peerId,
-  pinManager,
+  pinManager = {},
   preload,
   print,
   repo
@@ -115,8 +115,10 @@ function createApi ({
 
   const addAll = Components.addAll({ block, preload, pin, gcLock, options: constructorOptions })
   const resolve = Components.resolve({ ipld })
-  const refs = Components.refs({ ipld, resolve, preload })
-  refs.local = Components.refs.local({ repo })
+  const refs = Object.assign({},
+    Components.refs({ ipld, resolve, preload }),
+    { local: Components.refs.local({ repo }) }
+  )
 
   const notStarted = async () => { // eslint-disable-line require-await
     throw new NotStartedError()