buffer-stream.md

:BufferStream : DataStream

A facilitation stream created for easy splitting or parsing buffers.

Useful for working on built-in Node.js streams from files, parsing binary formats etc.

A simple use case would be:

 fs.createReadStream('pixels.rgba')
     .pipe(new BufferStream)         // pipe a buffer stream into scramjet
     .breakup(4)                     // split into 4 byte fragments
     .parse(buffer => [
         buffer.readInt8(0),            // the output is a stream of R,G,B and Alpha
         buffer.readInt8(1),            // values from 0-255 in an array.
         buffer.readInt8(2),
         buffer.readInt8(3)
     ]);

Kind: static class
Extends: DataStream
Test: test/methods/buffer-stream-constructor.js

• :BufferStream DataStream
  • new BufferStream([opts])
  • bufferStream.shift(chars, func) ↺
  • bufferStream.split(splitter) ↺ BufferStream
  • bufferStream.breakup(number) ↺ BufferStream
  • bufferStream.stringify([encoding]) StringStream
  • bufferStream.parse(parser) DataStream
  • BufferStream:pipeline(readable) BufferStream
  • BufferStream:from(stream, [options]) BufferStream

new BufferStream([opts])

Creates the BufferStream

Param	Type	Default	Description
[opts]	DataStreamOptions	{}	Stream options passed to superclass

bufferStream.shift(chars, func) ↺

Shift given number of bytes from the original stream

Works the same way as {@see DataStream.shift}, but in this case extracts the given number of bytes.

Kind: instance method of BufferStream
Chainable
Test: test/methods/string-stream-shift.js

Param	Type	Description
chars	number	The number of bytes to shift
func	ShiftBufferCallback	Function that receives a string of shifted bytes

bufferStream.split(splitter) : BufferStream ↺

Splits the buffer stream into buffer objects

Kind: instance method of BufferStream
Chainable
Returns: BufferStream - the re-split buffer stream.
Test: test/methods/buffer-stream-split.js

Param	Type	Description
splitter	string | Buffer	the buffer or string that the stream should be split by.

bufferStream.breakup(number) : BufferStream ↺

Breaks up a stream apart into chunks of the specified length

Kind: instance method of BufferStream
Chainable
Returns: BufferStream - the resulting buffer stream.
Test: test/methods/buffer-stream-breakup.js

Param	Type	Description
number	number	the desired chunk length

bufferStream.stringify([encoding]) : StringStream

Creates a string stream from the given buffer stream

Still it returns a DataStream derivative and isn't the typical node.js stream so you can do all your transforms when you like.

Kind: instance method of BufferStream
Returns: StringStream - The converted stream.
Test: test/methods/buffer-stream-tostringstream.js

Param	Type	Default	Description
[encoding]	string | any	""utf-8""	The encoding to be used to convert the buffers to streams.

bufferStream.parse(parser) : DataStream

Parses every buffer to object

The method MUST parse EVERY buffer into a single object, so the buffer stream here should already be split or broken up.

Kind: instance method of BufferStream
Returns: DataStream - The parsed objects stream.
Test: test/methods/buffer-stream-parse.js

Param	Type	Description
parser	BufferParseCallback	The transform function

BufferStream:pipeline(readable) : BufferStream

Creates a pipeline of streams and returns a scramjet stream.

Kind: static method of BufferStream
Returns: BufferStream - a new StringStream instance of the resulting pipeline
See: DataStream.pipeline

Param	Type	Description
readable	Array | Iterable.<any> | AsyncGeneratorFunction | GeneratorFunction | AsyncFunction | function | string | Readable	the initial readable argument that is streamable by scramjet.from
...transforms	Array.<(AsyncFunction|function()|Transform)>	Transform functions (as in DataStream..use) or Transform streams (any number of these as consecutive arguments)

BufferStream:from(stream, [options]) : BufferStream

Create BufferStream from anything.

Kind: static method of BufferStream
Returns: BufferStream - new StringStream.
See: module:scramjet.from

Param	Type	Default	Description
stream	Array | Iterable.<any> | AsyncGeneratorFunction | GeneratorFunction | AsyncFunction | function | Readable		argument to be turned into new stream
[options]	DataStreamOptions | Writable	{}	options passed to the new stream if created