Flex-Buffer

A flexible buffer with a complete but limited Buffer API.

• New data can only be appended.
• Written data and free space is distinguished. Only data part is accessible.
• Buffer size will auto-grow when it is not enough.
• Tested on Node 0.8-0.12, latest iojs on Mac, Linux and Windows.

Quick Start

npm install flex-buffer -S

then

FlexBuffer = require("flex-buffer");

fBuf = new FlexBuffer(4);
fBuf.write([1, 2, 3]);
fBuf.write("hello world");
fBuf.writeUInt32LE(165);

API

• FlexBuffer.SAFE_BUFFER_LENGTH

  Grow factor of the flex buffer.

  If the buffer is full, it will be resized to its origin length * grow factor. A falsey SAFE_BUFFER_LENGTH means unlimited, which may be unsafe. If grow factor is 0, the buffer will be resized to its origin length + input data's length.

  • type: { number }

• FlexBuffer.GROW_FACTOR

  If buffer length exceeds this length, it will grow as grow factor is 0.

  • type: { number }

• constructor (arg, opts = {})

  Flex Buffer constructor

  • param: arg { number | Buffer | Array | string }

    The same arg as Buffer, number is only initial byte size. Default is 1024.

  • param: opts { Object={} }

    options

  • option: encoding { string='utf8' }

    string encoding to use (only for string type)

  • option: growFactor { number=2 }

    GROW_FACTOR

  • option: safeBufferLength { number=10MB }

    SAFE_BUFFER_LENGTH

• GROW_FACTOR

  Grow factor of this flex buffer.

  • type: { number }

• SAFE_BUFFER_LENGTH

  Safe buffer length for this flex buffer.

  • type: { number }

• write (value, encoding = "utf8")

  Write/append a byte | array of bytes | buffer | string to the tail of the buffer

  • param: value { number | string | Array | Buffer }

    The value to write

  • param: encoding { string="utf8" }

    string encoding

  • return: { number }

    length to write

• slice (start = 0, end = this.length, newBuffer = false)

  The same as Buffer.slice applied on data part of the buffer, with an additional newBuffer argument.

  • param: start { number = 0 }

    start pos

  • param: end { number = this.length }

    end pos

  • param: newBuffer { boolean=false }

    return a new Buffer instance, which doesn't references the same memory as the old.

  • return: { Buffer }

    data buffer

• toBuffer (newBuffer = false)

  Return data part of the buffer.

  • param: newBuffer { boolean=false }

    return a new Buffer instance.

  • return: { Buffer }

    data buffer

• reset ()

  Release the buffer and create a buffer using initial state.

• release ()

  Release the buffer

• flush ()

  Flush the buffer, clear all data, won't release space.

• bufferLength

  internal buffer's length, including free space.

  • type: { number }

• length

  length of data part

  • type: { number }

All the native Buffer API is wrapped. However, write* methods can only append data, with no offset argument.

Test

npm test

Benchmark

npm run benchmark

Environment: , OS X 10.10.4, Intel(R) Core(TM) i7-4870HQ CPU @ 2.50GHz

io.js v2.4.0

• Write Number

  • Buffer x 1,967,194 ops/sec ±0.48% (95 runs sampled)
  • FlexBuffer x 2,608,820 ops/sec ±0.32% (96 runs sampled)

• Write String

  • Buffer x 776,848 ops/sec ±0.64% (93 runs sampled)
  • FlexBuffer x 290,386 ops/sec ±0.54% (92 runs sampled)
  • FlexBuffer(ascii) x 824,243 ops/sec ±1.18% (93 runs sampled)

• wrapped native API

  • Buffer x 19,973,789 ops/sec ±0.59% (94 runs sampled)
  • FlexBuffer x 14,407,768 ops/sec ±0.50% (93 runs sampled)

io.js v3.0.0

Due to changes in V8, io.js has reimplemented Buffer on top of V8's Uint8Array. Thus, Buffer instantiation is measurably slower. Access operations may be faster in some circumstances but the exact performance profile and difference over previous versions will depend on how Buffer is used within applications. See io.js changelog for more info.

• Write Number

  • Buffer x 1,448,511 ops/sec ±0.49% (94 runs sampled)
  • FlexBuffer x 1,137,468 ops/sec ±0.39% (95 runs sampled)

• Write String

  • Buffer x 519,786 ops/sec ±0.56% (95 runs sampled)
  • FlexBuffer x 238,278 ops/sec ±0.77% (90 runs sampled)
  • FlexBuffer(ascii) x 506,659 ops/sec ±1.36% (83 runs sampled)

• wrapped native API

  • Buffer x 10,587,654 ops/sec ±1.06% (94 runs sampled)
  • FlexBuffer x 7,510,308 ops/sec ±0.47% (94 runs sampled)

License

MIT@Jingchen Zhao