mustreams

mustream

Binary stream API for mudb. It is different from the Stream API of Node.js in that

• all streams of this API operate on typed arrays
• it provides built-in buffer pooling to help you minimize garbage collection

WIP

example

Here is a highly contrived example of using mustreams.

// on client side

var MuWriteStream = require('mustreams').MuWriteStream

var initialBufferSize = 2
var stream = new MuWriteStream(initialBufferSize)

var socket = new WebSocket(/* server url */)
// make sure data will be received in ArrayBuffer form
socket.binaryType = 'arraybuffer'

// increase the buffer size by 62 bytes
stream.grow(62)

stream.writeString('ピカチュウ')
stream.writeUint8(2)    // length of 'hp'
stream.writeASCII('hp')
stream.writeUint8(100)

// send buffered data
socket.send(stream.bytes())

// pool the buffer
stream.destroy()

// on server side

var createServer = require('http').createServer
var Server = require('uws').Server
var MuReadStream = require('mustreams').MuReadStream

var socketServer = new Server({ server: createServer() })
socketServer.on('connection', function (socket) {
    socket.onmessage = function (ev) {
        if (ev.data instanceof ArrayBuffer) {
            var stream = new MuReadStream(new Uint8Array(ev.data))

            stream.readString()                     // 'ピカチュウ'
            stream.readASCII(stream.readUint8())    // 'hp'
            stream.readUint8()                      // 100

            // pool the buffer
            stream.destroy()
        }
    }
})

table of contents

• 1 install
• 2 api
  • 2.1 MuWriteStream(bufferCapacity:number)
    • 2.1.1 buffer:MuBuffer
    • 2.1.2 offset:number
    • 2.1.3 bytes() : Uint8Array
    • 2.1.4 grow(numBytes:number)
    • 2.1.5 destroy()
    • 2.1.6 writeInt8(i:number)
    • 2.1.7 writeInt16(i:number)
    • 2.1.8 writeInt32(i:number)
    • 2.1.9 writeUint8(i:number)
    • 2.1.10 writeUint16(i:number)
    • 2.1.11 writeUint32(i:number)
    • 2.1.12 writeVarInt(i:number)
    • 2.1.13 writeFloat32(f:number)
    • 2.1.14 writeFloat64(f:number)
    • 2.1.15 writeASCII(s:string)
    • 2.1.16 writeString(s:string)
    • 2.1.17 writeUint8At(offset:number, i:number)
  • 2.2 MuReadStream(data:Uint8Array)
    • 2.2.1 buffer:MuBuffer
    • 2.2.2 offset:number
    • 2.2.3 length:number
    • 2.2.4 readInt8() : number
    • 2.2.5 readInt16() : number
    • 2.2.6 readInt32() : number
    • 2.2.7 readUint8() : number
    • 2.2.8 readUint16() : number
    • 2.2.9 readUint32() : number
    • 2.2.10 readVarInt() : number
    • 2.2.11 readFloat32() : number
    • 2.2.12 readFloat64() : number
    • 2.2.13 readASCII(length:number) : string
    • 2.2.14 readString() : string
    • 2.2.15 readUint8At(offset:number) : number
  • 2.3 MuBuffer
    • 2.3.1 buffer:ArrayBuffer
    • 2.3.2 dataView:DataView
    • 2.3.3 uint8:Uint8Array
• 3 usage tips
• 4 TODO

1 install

npm i mustreams

2 api

The methods of MuWriteStream and MuReadStream are closely related so they are meant to be used together.

2.1 MuWriteStream(bufferCapacity:number)

An interface through which you can buffer different types of data.

2.1.1 buffer:MuBuffer

A wrapper object providing access to the internal buffer.

2.1.2 offset:number

The offset in bytes from the start of the internal buffer which marks the position where the data will be written. The value of offset is automatically incremented whenever you write to the stream.

2.1.3 bytes() : Uint8Array

Creates a copy of a portion of the internal buffer, from the start to the position marked by offset.

2.1.4 grow(numBytes:number)

Increases the size of the internal buffer by a number of bytes. The resulted buffer size will always be a power of 2.

2.1.5 destroy()

Pools this.buffer.

2.1.6 writeInt8(i:number)

Buffers a signed 8-bit integer ranging from -128 to 127.

2.1.7 writeInt16(i:number)

Buffers a signed 16-bit integer ranging from -32768 to 32767.

2.1.8 writeInt32(i:number)

Buffers a signed 32-bit integer ranging from -2147483648 to 2147483647.

2.1.9 writeUint8(i:number)

Buffers an unsigned 8-bit integer ranging from 0 to 255.

2.1.10 writeUint16(i:number)

Buffers an unsigned 16-bit integer ranging from 0 to 65535.

2.1.11 writeUint32(i:number)

Buffers an unsigned 32-bit integer ranging from 0 to 4294967295.

2.1.12 writeVarInt(i:number)

Buffers an unsigned integer ranging from 0 to 4294967295. The number of bytes used to store i varies by the value. So unlike other write methods, writeVarInt() uses no more space than it is required to store i.

2.1.13 writeFloat32(f:number)

Buffers a signed 32-bit float number whose absolute value ranging from 1.2e-38 to 3.4e38, with 7 significant digits.

2.1.14 writeFloat64(f:number)

Buffers a signed 64-bit float number whose absolute value ranging from 5.0e-324 to 1.8e308, with 15 significant digits.

2.1.15 writeASCII(s:string)

Buffers a string composed of only ASCII characters.

2.1.16 writeString(s:string)

Buffers a string which may contain non-ASCII characters.

2.1.17 writeUint8At(offset:number, i:number)

Similar to writeUint8() except it writes the integer at the position marked by the specified offset. Note that unlike other write methods, this method will not increment the value of offset.

2.2 MuReadStream(data:Uint8Array)

An interface through which you can retrieve different types of data from the buffer.

2.2.1 buffer:MuBuffer

A wrapper object providing access to the internal buffer.

2.2.2 offset:number

The offset in bytes from the start of the internal buffer which marks the position the data will be read from. The value of offset is automatically incremented whenever you read from the stream.

2.2.3 length:number

2.2.4 readInt8() : number

Reads a signed 8-bit integer from buffer.

2.2.5 readInt16() : number

Reads a signed 16-bit integer from buffer.

2.2.6 readInt32() : number

Reads a signed 32-bit integer from buffer.

2.2.7 readUint8() : number

Reads a unsigned 8-bit integer from buffer.

2.2.8 readUint16() : number

Reads a unsigned 16-bit integer from buffer.

2.2.9 readUint32() : number

Reads a unsigned 32-bit integer from buffer.

2.2.10 readVarInt() : number

2.2.11 readFloat32() : number

Reads a signed 32-bit float number from buffer.

2.2.12 readFloat64() : number

Reads a signed 64-bit float number from buffer.

2.2.13 readASCII(length:number) : string

Reads a string of length consisting of only ASCII characters from buffer.

2.2.14 readString() : string

Reads a string from buffer.

2.2.15 readUint8At(offset:number) : number

Similar to readUint8() except it reads data from the specified offset. Unlike other read methods, this will not increment the value of offset.

2.3 MuBuffer

A handy wrapper that provides DataView and Uint8Array views to the internal buffer.

2.3.1 buffer:ArrayBuffer

The internal binary buffer.

2.3.2 dataView:DataView

The DataView view of this.buffer.

2.3.3 uint8:Uint8Array

The Uint8Array view of this.buffer.

3 usage tips

• normally you should not use MuBuffer directly
• remember to destroy the stream after using it
• try to minimize the uses of grow()

4 TODO

• bulk access to the internal buffer

credits

Copyright (c) 2017 Mikola Lysenko, Shenzhen Dianmao Technology Company Limited