ipfs.files.add: Notes about ipfs.types.Buffer.

[klueq]

I've spent an hour trying to figure out how to do ipfs add in the browser: docs describe the "Buffer" part really vaguely and don't mention that ipfs.files.add in fact creates a directory object unless used with a correctly created buffer. It works with an incorrectly created buffer, but creates a directory with auto-generated name:

let data = new Uint8Array([0x41, 0x42, 0x43]);
let results = await ipfs.files.add(data);

Here results is

[
  {
    "path": "QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn",
    "hash": "QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn",
    "size": 4
  }
]

Now open this hash in ipfs.io and try to figure out wtf that is and why size is 4. The ipfs.types.Buffer was the key.

[alanshaw]

Thanks for the PR @klueq - lets get these docs fixed up so they're easier to understand. There's a few things going on here that I should mention:

Firstly, js-ipfs doesn't seem to be validating the input correctly, you shouldn't be able to pass a Uint8Array, it should be a ipfs.types.Buffer or Buffer (the former is === the latter).

When you pass it a Uint8Array, for some reason it's adding an empty directory, the first point, combined with this is a bug - it would be awesome if you could open an issue on js-ipfs for this so we can get it fixed....and even more awesome if you have time to PR a fix and a test!

Lastly, if you add some content like this:

const files = [
  {
    path: '/tmp/myfile.txt',
    content:  ipfs.types.Buffer.from('ABC')
  }
]

You'll get a directory AND a file because you've specified the path as /tmp/myfile.txt. IPFS automatically creates any missing intermediate directories and gives you back their CIDs along with the CIDs for the files too.

So you can now access tmp using the gateway at the URL https://ipfs.io/ipfs/QmWXdjNC362aPDtwHPUE9o2VMqPeNeCQuTBTv1NsKtwypg and myfile.txt using the gateway at https://ipfs.io/ipfs/QmWXdjNC362aPDtwHPUE9o2VMqPeNeCQuTBTv1NsKtwypg/myfile.txt or directly at https://ipfs.io/ipfs/QmNz1UBzpdd4HfZ3qir3aPiRdX5a93XwTuDNyXRc6PKhWW

[alanshaw]

I think we just need to tweak this wording to something like: "The following allows you to add multiple files at once. Note that intermediate directories in file paths will be automatically created and returned in the response along with files:"