buffer-stream.md

March 29, 2021 · View on GitHub

: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])

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