ByteBuffer.js - A Java-like ByteBuffer

Provides a Java-like ByteBuffer implementation using typed arrays. It also tries to abstract the complexity away by providing convenience methods for those who just want to write stuff without caring about signed, unsigned and the actual bit sizes. It's also used for the cross-platform multiplayer component in eSoccer, a HTML5 game developed at University of Applied Sciences Bonn.

ByteBuffer

• Mimics Java ByteBuffers as close as reasonable while using typed array terms

• Simple allocation (new ByteBuffer(capacity[, littleEndian]) or ByteBuffer.allocate(capacity[, littleEndian]))

• Wrapping of quite everything which is or includes an ArrayBuffer (ByteBuffer.wrap(buffer[, littleEndian]))

• Cloning using the same (ByteBuffer#clone()) and copying using an independent backing buffer (ByteBuffer#copy())

• Slicing using the same (ByteBuffer#slice(begin, end)) and using an indepentent backing buffer (ByteBuffer#sliceAndCompact(begin, end))

• Manual offset (ByteBuffer#offset and ByteBuffer#length) and array manipulation (ByteBuffer#array)

• Remaining readable bytes (ByteBuffer#remaining()) and backing buffer capacity getters (ByteBuffer#capacity())

• Explicit (ByteBuffer#resize(capacity)) and implicit resizing (ByteBuffer#ensureCapacity(capacity))

• Efficient implicit resizing by doubling the current capacity

• Flipping (ByteBuffer#flip()) and resetting (ByteBuffer#reset()) like known from Java ByteBuffers

• Compacting of the backing buffer (ByteBuffer#compact())

• Conversion to ArrayBuffer (ByteBuffer#toArrayBuffer([forceCopy])) (i.e. to send data over the wire, e.g. a WebSocket with binaryType="arraybuffer")

• Explicit destruction (ByteBuffer#destroy())

• ByteBuffer#writeUint/Int8/16/32(value[, offset]) and ByteBuffer#readUint/Int8/16/32([offset])

• ByteBuffer#writeFloat32/64(value[, offset]) and ByteBuffer#readFloat32/64([offset])

• ByteBuffer#write/readByte, ByteBuffer#write/readShort, ByteBuffer#write/readInt, ByteBuffer#write/readLong (all signed), ByteBuffer#write/readFloat, ByteBuffer#write/readDouble aliases for the above for convenience

• ByteBuffer#writeUTF8String(str[, offset]) and ByteBuffer#readUTF8String(chars[, offset]) using the included UTF8 en-/decoder (full 6 bytes, ref)

• ByteBuffer#writeLString(str[, offset])) and ByteBuffer#readLString([offset]) to write respectively read a length-prepended (number of characters as UTF8 char) string (recommended over ByteBuffer#write/readCString, which would break in the case of contained NULL characters)

• ByteBuffer#writeCString(str[, offset]) and ByteBuffer#readCString([offset]) to write respectively read a NULL-terminated (Uint8 0x00) string

• ByteBuffer#writeJSON(data[, offset[, stringify]]) and ByteBuffer#readJSON([offset[, parse]]) to write respectively read arbitraty object data. Allows overriding the default stringify (default: JSON.stringify) and parse (default: JSON.parse) implementations.

• All with implicit offset advance if the offset parameter is omitted or without, if specified

• Chaining of all operations that allow this (i.e. do not return some specific value like in read operations), e.g.

  var bb = new ByteBuffer();
  ...
  bb.reset().writeInt(1).writeLString("Hello world!").flip().compact()...

• ByteBuffer#toString(), ByteBuffer#toHex([wrap]) and ByteBuffer#printDebug() for easy debugging

Features

• CommonJS compatible
• RequireJS/AMD compatible
• Shim compatible (include the script, then use var ByteBuffer = dcodeIO.ByteBuffer;)
• node.js compatible, also available via npm
• Closure Compiler ADVANCED_OPTIMIZATIONS compatible (fully annotated)
• Fully documented (jsdoc3)
• Tested through nodeunit (TODO: heavily test UTF8 en-/decoding)
• Zero dependencies
• Small footprint

Usage

Node.js / CommonJS

• Install: npm install bytebuffer

var ByteBuffer = require("bytebuffer");
var bb = new ByteBuffer();
bb.writeLString("Hello world!");
bb.flip();
console.log(bb.readLString()+" from ByteBuffer.js");

Browser (shim)

<script src="//raw.github.com/dcodeIO/ByteBuffer.js/master/ByteBuffer.min.js"></script>

var ByteBuffer = dcodeIO.ByteBuffer;
var bb = new ByteBuffer();
bb.writeLString("Hello world!");
bb.flip();
alert(bb.readLString()+" from ByteBuffer.js");

Require.js / AMD

var ByteBuffer = require("/path/to/ByteBuffer.js");
var bb = new ByteBuffer();
bb.writeLString("Hello world!");
bb.flip();
alert(bb.readLString()+" from ByteBuffer.js");

Documentation

• View documentation
• Create: jsdoc -c jsdoc.json README.md (you'll need to comment out the eSoccer template in jsdoc.json)

Tests (& Examples)

• View source
• Install: npm install -g nodeunit
• Run: nodeunit tests/suite.js

Prerequisites to run it against IE<10, FF<15, Chrome<9 etc.

• Working ArrayBuffer, DataView & Uint8Array implementations (i.e. use a polyfill, 2)

License

Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.html