Make Streams API mirror node core's API more closely

[jhermsmeier]

Connects to: #15

Changes:

• Added an fd option to BlockMap.ReadStream, so that if passed, the filename argument will be ignored, and the fd used instead (analog to node core's fs.ReadStream)
• Added start and end offset options to BlockMap.ReadStream
• Added autoClose option to BlockMap.ReadStream
• Added BlockMap.createFilterStream(), analog to .createReadStream()
• Updated the docs respectively

[lurch]

Perhaps it's just me misunderstanding things, but in some places fd is specified as a Number, but in other places it's specified as a String? :confused:

[jhermsmeier]

Nope, not just you – I mangled the type. Fixed now.

[lurch]

LGTM, but I don't know the nodejs API well enough to give this "official approval" ;-)

[jhermsmeier]

Now that I think about it, I should probably implement the other fs.ReadStream options as well, to be fully compatible with that API.

[jhermsmeier]

I've added the other fs.ReadStream options (start, end, autoClose) as well now, with exception of mode, as that's only used when creating a file, which is not applicable in this case.

[lurch]

Should createReadStream be documented as having the same options as new ReadStream?

[jhermsmeier]

Should createReadStream be documented as having the same options as new ReadStream?

Yup, fixed.

[lurch]

One more question... ;-) If we pass in a filename instead of an fd, does the autoClose setting effectively get ignored? Does that need a unit-test?

[jhermsmeier]

No, the autoClose option is not coupled to the fd option, so if you pass a filename and autoClose: false, then the readStream.fd will still be open & usable after the stream has ended. Test added.

[jviotti]

I'd love to see the following test cases:

• start and/or end are -1
• end is 0
• start is greater than end
• start is equal to end
• start goes beyond the file
• end goes beyond the file

[jhermsmeier]

Good catch! Added tests, and fixed a case they caught.