Differences between JS and IPFS-Interface docs

[mitra42]

Are the differences between:
https://github.com/ipfs/js-ipfs-api#api and https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#get intentional e.g. the latter says Javascript has ipfs.files.getReadableStream and ipfs.files.getPullStream but the former only lists cat,get,createAddStream() and "add().

I'm not sure if the interface is intended to contract to that listed in the JS doc, or expand to that in inteface-ipfs-core

[daviddias]

Good catch. Fixed it with #662. Thanks!

[mitra42]

That still looks really wrong e.g.
JS-IPFS says ipfs.files.addReadableStream([options]) but refers to the interface-ipfs-core for the details where it has the same interface but doesnt show what the options are and the example talks about WRITING to the stream, not reading from it.

I guess we are just going to have to hope that the options/events are the same as node stream options ?

[daviddias]

JS-IPFS says ipfs.files.addReadableStream([options]) but refers to the interface-ipfs-core

Yes, we have the SPEC and Tests for the core API in the package https://github.com/ipfs/interface-ipfs-core.

but doesnt show what the options are...I guess we are just going to have to hope that the options/events are the same as node stream options ?

https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#addreadablestream

about WRITING to the stream, not reading from it

This is the addReadableStream, a ReadableStream is just one type of stream -- https://www.npmjs.com/package/readable-stream --. They support, read, write, transform and duplex.

As noted in the docs:

The same way that pull-stream is just a type that has modes for read, write, transform and duplex.

, not reading from it.

If you want to read files from IPFS, then you have cat and get

• https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#cat
• https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md#get

[mitra42]

Thanks David … this would be funny if the lack of documentation wasn’t a significant barrier to using IPFS - wasted most of an afternoon trying to figure out how to read a stream from IPFS and ending up with pulling IPFS stream support from our library because I couldnt find a function that appears (see below) to be there.

The pages https://github.com/ipfs/js-ipfs-api#api (since the commit notes above) has add, addPullStream, addReadableStream, cat and get.
https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md has this plus catReadableStream and catPullStream and getReadableStream and getPullsStream (which I only just noticed) and
That new link https://github.com/ipfs/interface-ipfs-core from your email above contains a completely different list of functions for streams than the other two links. (add, createAddStream, cat get)

What I meant by the absence of options was the lack of example and that this text you boxed is a bit unclear on exactly what - I see now my confusion was that I was thinking that addReadableStream was the equivalent of the Node createReadStream, i.e. a function to read, rather than write to IPFS.

The confusing line is "Returns a Readable Stream of class Duplex, where objects can be written of the forms” which sounds like a typo - is it readable, or writable. I see now that you mean a Node “ReadableStream” it might be correct - i.e. this stream might be readable and writable, but is all about ADDing something to IPFS. That’s really confusing because why would something that ADDs to IPFS return a ReadableStream when node’s ReadableStreams don’t have a write() method https://nodejs.org/dist/v8.1.3/docs/api/stream.html#stream_readable_streams

I was trying to figure out how to turn “cat” into a stream reader, but I see now there is catReadableStream, in https://github.com/ipfs/interface-ipfs-core/blob/master/SPEC/FILES.md (which isn’t listed in either of the other two pages). Is that function on its way in (not yet added to the js-ipfs-api & interface-ipfs-core pages ) or on its way out (not yet removed from SPEC/FILES) i.e. is it safe to build on catReadableStreams, in which case I'll add support for IPFS streams back into our library.

[daviddias]

I see, their pointers to those API calls didn't get update across the board and so it was unclear what was the latest API. Thanks for catching that :)

Just updated it everywhere:

• https://github.com/ipfs/js-ipfs-api#files
• https://github.com/ipfs/js-ipfs#files