feat: callbackify and top level jsdoc and more

Author: hugomrdias

package.json

@@ -54,6 +54,7 @@
     "once": "^1.4.0",
     "peer-id": "~0.11.0",
     "peer-info": "~0.14.1",
+    "promise-nodeify": "^3.0.1",
     "promisify-es6": "^1.0.3",
     "pull-defer": "~0.2.2",
     "pull-pushable": "^2.2.0",

src/add2/add2.js

@@ -2,10 +2,20 @@
 
 const { Readable } = require('stream')
 const toPull = require('stream-to-pull-stream')
+const promiseNodeify = require('promise-nodeify')
 const concatStream = require('concat-stream')
 const pump = require('pump')
 const SendStream = require('./send-stream')
 
+/** @module api/add */
+
+/**
+ * Converts an array to a stream
+ *
+ * @private
+ * @param {Array} data
+ * @returns {Readable}
+ */
 const arrayToStream = (data) => {
   let i = 0
   return new Readable({
@@ -16,10 +26,59 @@ const arrayToStream = (data) => {
   })
 }
 
-const add = (send) => (files, options) => {
-  // check if we can receive pull-stream after callbackify
+/**
+ * @typedef {Object} AddOptions
+ * @property  {number} chunkSize - Value of array element
+ * @property {number} [cidVersion=0] - Defaults to 0. The CID version to use when storing the data (storage keys are based on the CID, including it's version)
+ * @property {function(bytes: number): void} progress - function that will be called with the byte length of chunks as a file is added to ipfs.
+ * @property {Boolean} recursive - When a Path is passed, this option can be enabled to add recursively all the files.
+ * @property {string} hashAlg - Multihash hashing algorithm to use. (default: sha2-256) The list of all possible values {@link https://github.com/multiformats/js-multihash/blob/master/src/constants.js#L5-L343 hashAlg values}
+ * @property {Boolean} wrapWithDirectory - Adds a wrapping node around the content.
+ * @property {Boolean} onlyHash - Doesn't actually add the file to IPFS, but rather calculates its hash.
+ * @property {Boolean} [pin=true] - Defaults to true. Pin this object when adding.
+ * @property {Boolean} [rawLeaves=false] - Defaults to false. If true, DAG leaves will contain raw file data and not be wrapped in a protobuf
+ * @property {string} [chunker=size-262144] Chunking algorithm used to build ipfs DAGs. Available formats:
+ * - size-{size}
+ * - rabin
+ * - rabin-{avg}
+ * - rabin-{min}-{avg}-{max}
+ */
+
+/**
+ * @typedef {Object} AddResult
+ * @property {string} path
+ * @property {string} hash
+ * @property {number} size
+ */
+
+/**
+ * This callback is displayed as a global member.
+ * @callback AddCallback
+ * @param {Error} err
+ * @param {AddResult[]} res
+ */
+
+/** @typedef {Function} PullStream */
+/** @typedef {(Object[]|Readable|File|PullStream|Buffer)} AddData */
+/**
+ * @typedef {function(AddData, AddOptions, AddCallback): (Promise.<AddResult[]>|void)} AddFunction
+ */
+
+/**
+ * Add to data to ipfs
+ *
+ * @param {Function} send
+ * @returns {AddFunction}
+ * @memberof api/add
+ */
+const add = (send) => (files, options, callback) => {
+  if (typeof options === 'function') {
+    callback = options
+    options = {}
+  }
+
   let result = []
-  return new Promise((resolve, reject) => {
+  const r = new Promise((resolve, reject) => {
     pump(
       arrayToStream([].concat(files)),
       new SendStream(send, options),
@@ -32,13 +91,29 @@ const add = (send) => (files, options) => {
       }
     )
   })
+
+  return promiseNodeify(r, callback)
 }
 
-const addReadableStream = (send) => (options) => {
+/**
+ * Add to data to ipfs
+ *
+ * @param {Function} send
+ * @returns {function(AddOptions): Readable}
+ * @memberof api/add
+ */
+const addReadableStream = (send) => (options = {}) => {
   return new SendStream(send, options)
 }
 
-const addPullStream = (send) => (options) => {
+/**
+ * Add to data to ipfs
+ *
+ * @param {Function} send
+ * @returns {function(AddOptions): PullStream}
+ * @memberof api/add
+ */
+const addPullStream = (send) => (options = {}) => {
   return toPull(new SendStream(send, options))
 }
 

src/add2/multipart2.js

@@ -4,10 +4,18 @@ const { Duplex } = require('stream')
 const { isSource } = require('is-pull-stream')
 const toStream = require('pull-stream-to-stream')
 
+/** @private @typedef {import("./add2").AddOptions} AddOptions */
+
 const PADDING = '--'
 const NEW_LINE = '\r\n'
 const NEW_LINE_BUFFER = Buffer.from(NEW_LINE)
 
+/**
+ * Generate a random boundary to use in a multipart request
+ *
+ * @private
+ * @returns {string}
+ */
 const generateBoundary = () => {
   var boundary = '--------------------------'
   for (var i = 0; i < 24; i++) {
@@ -17,6 +25,14 @@ const generateBoundary = () => {
   return boundary
 }
 
+/**
+ * Generate leading section for a multipart body
+ *
+ * @private
+ * @param {Object} [headers={}]
+ * @param {string} boundary
+ * @returns {string}
+ */
 const leading = (headers = {}, boundary) => {
   var leading = [PADDING + boundary]
 
@@ -32,16 +48,27 @@ const leading = (headers = {}, boundary) => {
   return Buffer.from(leadingStr)
 }
 
+/**
+ * Multipart class to generate a multipart body chunked and non chunked
+ *
+ * @private
+ * @class Multipart
+ * @extends {Duplex}
+ */
 class Multipart extends Duplex {
-  constructor ({ chunkSize }) {
+  /**
+   * Creates an instance of Multipart.
+   * @param {AddOptions} options
+   */
+  constructor (options) {
     super({
       writableObjectMode: true,
       writableHighWaterMark: 1
     })
 
     this._boundary = generateBoundary()
     this.source = null
-    this.chunkSize = chunkSize || 0
+    this.chunkSize = options.chunkSize || 0
     this.buffer = Buffer.alloc(this.chunkSize)
     this.bufferOffset = 0
     this.extraBytes = 0
@@ -97,7 +124,7 @@ class Multipart extends Duplex {
       return this.push(null)
     }
 
-    if (!this.chunkSize) {
+    if (this.chunkSize === 0) {
       return this.push(chunk)
     }
 

src/add2/send-stream.js

@@ -6,8 +6,16 @@ const pump = require('pump')
 const Multipart = require('./multipart2')
 const { prepareWithHeaders } = require('./../utils/prepare-file')
 
+/** @private @typedef {import("./add2").AddOptions} AddOptions */
+
 const noop = () => {}
 
+/**
+ * Factory for prepare stream
+ * @private
+ * @param {*} options
+ * @returns {Function}
+ */
 const prepareTransform = (options) => new Transform({
   objectMode: true,
   transform (chunk, encoding, callback) {
@@ -19,8 +27,20 @@ const prepareTransform = (options) => new Transform({
   }
 })
 
+/**
+ * Class to create a stream to send data to the API
+ *
+ * @private
+ * @class SendStream
+ * @extends {Duplex}
+ */
 class SendStream extends Duplex {
-  constructor (send, options) {
+  /**
+   * Creates an instance of SendStream.
+   * @param {Function} send
+   * @param {AddOptions} [options={}]
+   */
+  constructor (send, options = {}) {
     super({ objectMode: true, highWaterMark: 1 })
     this.waiting = null
     this.options = options