refactor: make add only work on single items (#3167)

`ipfs.add` now returns single items only.  Where a source would result in multiple items returned, only the last item is returned.  As a first pass `ipfs.add` still takes multiple items but only accepting single items is documented and considered supported.  In the future it may throw if multiple items are passed.

`ipfs.addAll` retains the previous behaviour of `ipfs.add`.

Examples:

```javascript
const { cid, path, mode, mtime } = await ipfs.add('Hello world')
```

```javascript
const { cid } = await ipfs.add(Uint8Array.from([0, 1, 2]))
```

```javascript
const { cid } = await ipfs.add(fs.createReadStream('/path/to/file.txt'))
```

```javascript
const { cid } = await ipfs.add({
  path: '/foo/bar/baz.txt',
  content: 'File content'
})

// Creates a DAG with multiple levels of directories.
// The returned cid is the CID for the root directory /foo

// You can retrieve the file content with an IPFS path
for await (const buf of ipfs.cat(`/ipfs/${cid}/bar/baz.txt`)) {
  ...
}

// Or get the CID of the nested file with ipfs.files.stat
const { cid: fileCid } = await ipfs.files.stat(`/ipfs/${cid}/bar/baz.txt`)

// or ipfs.dag.resolve
const { cid: fileCid } = await ipfs.dag.resolve(`/ipfs/${cid}/bar/baz.txt`)
```

```javascript
// To have `/foo` included in the ipfs path, wrap it in a directory:
const { cid } = await ipfs.add({
  path: '/foo/bar/baz.txt',
  content: 'File content'
}, {
  wrapWithDirectory: true
})

for await (const buf of ipfs.cat(`/ipfs/${cid}/foo/bar/baz.txt`)) {
  ...
}
```

BREAKING CHANGES:

- `ipfs.add` only works on single items - a Uint8Array, a String, an AsyncIterable<Uint8Array> etc
- `ipfs.addAll` works on multiple items

Author: achingbrain

README.md

@@ -147,9 +147,9 @@ const IpfsHttpClient = require('ipfs-http-client')
 const { globSource } = IpfsHttpClient
 const ipfs = IpfsHttpClient()
 
-for await (const file of ipfs.add(globSource('./docs', { recursive: true }))) {
-  console.log(file)
-}
+const file = await ipfs.add(globSource('./docs', { recursive: true }))
+console.log(file)
+
 /*
 {
   path: 'docs/assets/anchor.js',
@@ -182,9 +182,9 @@ const IpfsHttpClient = require('ipfs-http-client')
 const { urlSource } = IpfsHttpClient
 const ipfs = IpfsHttpClient()
 
-for await (const file of ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))) {
-  console.log(file)
-}
+const file = await ipfs.add(urlSource('https://ipfs.io/images/ipfs-logo.svg'))
+console.log(file)
+
 /*
 {
   path: 'ipfs-logo.svg',

package.json

@@ -53,6 +53,7 @@
     "ipld-dag-pb": "^0.18.5",
     "ipld-raw": "^5.0.0",
     "iso-url": "^0.4.7",
+    "it-last": "^1.0.1",
     "it-tar": "^1.2.2",
     "it-to-buffer": "^1.0.0",
     "it-to-stream": "^0.1.1",
@@ -72,7 +73,7 @@
     "cross-env": "^7.0.0",
     "go-ipfs": "^0.6.0",
     "interface-ipfs-core": "^0.137.0",
-    "ipfsd-ctl": "^4.1.1",
+    "ipfsd-ctl": "^5.0.0",
     "it-all": "^1.0.1",
     "it-concat": "^1.0.0",
     "it-pipe": "^1.1.0",

src/add-all.js

@@ -0,0 +1,63 @@
+'use strict'
+
+const CID = require('cids')
+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 AbortController = require('abort-controller')
+
+module.exports = configure((api) => {
+  return async function * addAll (input, options = {}) {
+    const progressFn = options.progress
+
+    // allow aborting requests on body errors
+    const controller = new AbortController()
+    const signal = anySignal([controller.signal, options.signal])
+
+    const res = await api.post('add', {
+      searchParams: toUrlSearchParams({
+        'stream-channels': true,
+        ...options,
+        progress: Boolean(progressFn)
+      }),
+      timeout: options.timeout,
+      signal,
+      ...(
+        await multipartRequest(input, controller, options.headers)
+      )
+    })
+
+    for await (let file of res.ndjson()) {
+      file = toCamel(file)
+
+      if (progressFn && file.bytes) {
+        progressFn(file.bytes)
+      } else {
+        yield toCoreInterface(file)
+      }
+    }
+  }
+})
+
+function toCoreInterface ({ name, hash, size, mode, mtime, mtimeNsecs }) {
+  const output = {
+    path: name,
+    cid: new CID(hash),
+    size: parseInt(size)
+  }
+
+  if (mode != null) {
+    output.mode = parseInt(mode, 8)
+  }
+
+  if (mtime != null) {
+    output.mtime = {
+      secs: mtime,
+      nsecs: mtimeNsecs || 0
+    }
+  }
+
+  return output
+}

src/add.js

@@ -1,63 +1,15 @@
 'use strict'
 
-const CID = require('cids')
-const toCamel = require('./lib/object-to-camel')
+const addAll = require('./add-all')
+const last = require('it-last')
 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')
 
-module.exports = configure((api) => {
-  return async function * add (input, options = {}) {
-    const progressFn = options.progress
+module.exports = (options) => {
+  const all = addAll(options)
 
-    // allow aborting requests on body errors
-    const controller = new AbortController()
-    const signal = anySignal([controller.signal, options.signal])
-
-    const res = await api.post('add', {
-      searchParams: toUrlSearchParams({
-        'stream-channels': true,
-        ...options,
-        progress: Boolean(progressFn)
-      }),
-      timeout: options.timeout,
-      signal,
-      ...(
-        await multipartRequest(input, controller, options.headers)
-      )
-    })
-
-    for await (let file of res.ndjson()) {
-      file = toCamel(file)
-
-      if (progressFn && file.bytes) {
-        progressFn(file.bytes)
-      } else {
-        yield toCoreInterface(file)
-      }
-    }
-  }
-})
-
-function toCoreInterface ({ name, hash, size, mode, mtime, mtimeNsecs }) {
-  const output = {
-    path: name,
-    cid: new CID(hash),
-    size: parseInt(size)
-  }
-
-  if (mode != null) {
-    output.mode = parseInt(mode, 8)
-  }
-
-  if (mtime != null) {
-    output.mtime = {
-      secs: mtime,
-      nsecs: mtimeNsecs || 0
+  return configure(() => {
+    return async function add (input, options = {}) { // eslint-disable-line require-await
+      return last(all(input, options))
     }
-  }
-
-  return output
+  })(options)
 }

src/index.js

@@ -21,6 +21,7 @@ const urlSource = require('ipfs-utils/src/files/url-source')
 function ipfsClient (options = {}) {
   return {
     add: require('./add')(options),
+    addAll: require('./add-all')(options),
     bitswap: require('./bitswap')(options),
     block: require('./block')(options),
     bootstrap: require('./bootstrap')(options),

test/get.spec.js

@@ -27,7 +27,7 @@ describe('.get (specific go-ipfs features)', function () {
 
   before(async () => {
     ipfs = (await f.spawn()).api
-    await all(ipfs.add(smallFile.data))
+    await ipfs.add(smallFile.data)
   })
 
   after(() => f.clean())
@@ -65,7 +65,7 @@ describe('.get (specific go-ipfs features)', function () {
     const subdir = 'tmp/c++files'
     const expectedCid = 'QmPkmARcqjo5fqK1V1o8cFsuaXxWYsnwCNLJUYS4KeZyff'
     const path = `${subdir}/${filename}`
-    const files = await all(ipfs.add([{
+    const files = await all(ipfs.addAll([{
       path,
       content: Buffer.from(path)
     }]))

test/log.spec.js

@@ -3,7 +3,6 @@
 'use strict'
 
 const { expect } = require('interface-ipfs-core/src/utils/mocha')
-const all = require('it-all')
 const { Buffer } = require('buffer')
 const f = require('./utils/factory')()
 
@@ -21,7 +20,7 @@ describe('.log', function () {
   it('.log.tail', async () => {
     const i = setInterval(async () => {
       try {
-        await all(ipfs.add(Buffer.from('just adding some data to generate logs')))
+        await ipfs.add(Buffer.from('just adding some data to generate logs'))
       } catch (_) {
         // this can error if the test has finished and we're shutting down the node
       }