Consider enabling `add(path)` to the files API

[daviddias]

@jbenet brought up that a lot of users will expect ipfs.add(path) to just work as if they were in the terminal.

In the past, we went through several iterations and discussions and eventually ended up agreeing that it would be beneficial to have utilities like addFromFs and addFromUrl as actions that are explicit, this keeps the promise intact that code can be run in the browser and in Node.js, as long as the dev is using the ipfs-core API.

We can add this feature, we will just need to be verbose about that caveat.

[dignifiedquire]

👎 on this, it makes the api more complicated. Having an api call that has entirely different semantics depending on if it is run in node.js or the browser seems like it will only cause more confusion.

[jbenet]

This is a basic expectation of ipfs nodes and tooling.

• I would expect ipfs.add(path) to work, everywhere, and only fail when the path is inaccessible.
• in the browser, the limitation is the access to the files, similar to how in the filesystem permissions may hide parts of the fs. ipfs.add("~/foo/bar") is not possible in the browser because the files are not accessible.
• you could choose to make ipfs.add(url) work in the browser, as i would expect to work. (http is sort of the fs of the web.)

Bottom line, these should be trivially easy to use:

// direct analogues with ipfs add in the cli, in node.
ipfs.add("~/path/to/my-file")
ipfs.add("~/path/to/my-dir", {recursive: true})
ipfs.add("my-file")
ipfs.add("my-dir", {recursive: true})
ipfs.add(stream) // makes a file

// direct analogues with ipfs add in the cli, but on the browser
ipfs.add("https://foo.com/my-page")
// arguably, people would expcet this to work like wget mirroring:
ipfs.add("https://foo.com/my-page", {recursive: true})
// but i'm fine not supporting it.

Conversely, i would expect cat to work equally easily:

ipfs.cat(ipfsPath) # returns a stream

The emphasis here is in:

• consistency with ipfs tooling + expectations everywhere else
• trivially simple command for trivially simple use case
• maintaining backwards compatibility. don't break interfaces.

[jbenet]

"i just want to add some json and get it back" this should be absolutely trivial, and exactly the same as it works in the cli.

[hacdias]

@diasdavid it seems to be already working on the JavaScript API. Is there anything else to do on this issue I can help with?

[wraithgar]

The docs in the JavaScript API were erroneous. The files.add method only allows Buffers or Streams (either directly or as the content attribute in an object)

[daviddias]

There is a very valuable and impressive work being done and thought through by @alanshaw, @olizilla and @achingbrain with regards to APIs around Files and js-ipfs APIs in general (ipfsx).

As a stepping stone towards that, I want to bring the .addFromFs to the top level. In the future there will be just on ipfs.add command when we have the async generators goodness (and no more myriad of Streams)