Readable to Simple stream converter
This project is an util for converting node readable streams to simple-stream format suggested by Tim Caswell, as well as more strict and detailed version of original spec.
http file server
var Simple = require'stream-simple'var http = require'http'var fs = require'fs'httpcreateServervar stream = SimplefscreateReadStreamrequrlslice1reson'error'streamabortreswriteHead200'Content-Type': 'text/plain';streamreadif err return resdestroyif !chunk return resendreswritechunkpush
npm install stream-simple
Simple stream is an object with two methods
.read() is used for pulling data from stream. It accepts callback function with
node's standard signature
cb(err, item). The following rules apply:
- End of stream MUST be indicated as
- Data chunk/item MUST be indicated as
item !== undefined
- Error MUST be indicated as
erris an instance of
- Stream MUST destroy itself and release all underlying resources in case it reports an error or EOF to read callback, however the exact moment of cleanup completion is undefined.
- If stream is in a destroyed state it MUST return an error to read callback, however streams which supply data from some sort of internal queue MAY return already buffered data first.
- Stream MAY (and it's recommended to) ignore stack overflow concerns and call callbacks synchronously.
.abort() method is a signal to release all underlying resources.
It accepts optional callback function with
The following rules apply:
- Stream MUST handle multiple abort calls
- Stream MUST call abort callbacks and only after completion of cleanup procedure
- Stream MAY pass errors occured on cleanup to abort callbacks.
###Why not to support .read(n, cb)?
- It is a complexity
- It is not always needed
- It could be done with separate util without issues
- There is no performance benefits
The last argument requires some clarification. There are types of streams (like file system streams) which indeed can produce certain amount of data and optimize on that. However in any system there are high-low watermark levels so that if you pull data in chunks beyound that size boundary you get either protocol or memory management overhead. For all modern systems I am personally aware of the typical size of "optimal" chunk is much larger than a typical size of protocol headers. Even if some parser currently wants only 100b it's almost always better to pull 10kb in advance. On other hand there is no much overhead in pulling 10kb instead of 100b as well as pulling 100kb in 10kb chunks. Also that "optimal" chunk size is known at the moment of stream construction and there is no need to pass it from outside.
Finally if some stream want's to support reading of certain amount of bytes it may do so, however general purpose APIs should not rely on that.
###We taught that callbacks should always be called asynchronously
process.nextTickand even on node it can be performance overhead
- With introduction of TCO by ES6 all that "next tick" stuff will become legacy quite soon
- It's not a problem. Indeed all edge cases could be handled
in general purpose utils (like
reduce) and not bother developer at all.