buffer

The buffer module from node.js, for the browser.

With browserify, simply require('buffer') or use the Buffer global and you will get this module.

The goal is to provide an API that is 100% identical to node's Buffer API. Read the official docs for the full list of properties, instance methods, and class methods that are supported.

features

• Manipulate binary data like a boss, in all browsers -- even IE6!
• Super fast. Backed by Typed Arrays (Uint8Array/ArrayBuffer, not Object)
• Extremely small bundle size (5.04KB minified + gzipped, 35.5KB with comments)
• Excellent browser support (IE 6+, Chrome 4+, Firefox 3+, Safari 5.1+, Opera 11+, iOS, etc.)
• Preserves Node API exactly, with one minor difference (see below)
• Square-bracket buf[4] notation works, even in old browsers like IE6!
• Does not modify any browser prototypes or put anything on window
• Comprehensive test suite (including all buffer tests from node.js core)

install

To use this module directly (without browserify), install it:

npm install buffer

This module was previously called native-buffer-browserify, but please use buffer from now on.

A standalone bundle is available here, for non-browserify users.

usage

The module's API is identical to node's Buffer API. Read the official docs for the full list of properties, instance methods, and class methods that are supported.

As mentioned above, require('buffer') or use the Buffer global with browserify and this module will automatically be included in your bundle. Almost any npm module will work in the browser, even if it assumes that the node Buffer API will be available.

To depend on this module explicitly (without browserify), require it like this:

var Buffer = require('buffer/').Buffer  // note: the trailing slash is important!

To require this module explicitly, use require('buffer/') which tells the node.js module lookup algorithm (also used by browserify) to use the npm module named buffer instead of the node.js core module named buffer!

how does it work?

The Buffer constructor returns instances of Uint8Array that have their prototype changed to Buffer.prototype. Furthermore, Buffer is a subclass of Uint8Array, so the returned instances will have all the node Buffer methods and the Uint8Array methods. Square bracket notation works as expected -- it returns a single octet.

The Uint8Array prototype remains unmodified.

one minor difference

In old browsers, buf.slice() does not modify parent buffer's memory

If you only support modern browsers (specifically, those with typed array support), then this issue does not affect you. If you support super old browsers, then read on.

In node, the slice() method returns a new Buffer that shares underlying memory with the original Buffer. When you modify one buffer, you modify the other. Read more.

In browsers with typed array support, this Buffer implementation supports this behavior. In browsers without typed arrays, an alternate buffer implementation is used that is based on Object which has no mechanism to point separate Buffers to the same underlying slab of memory.

You can see which browser versions lack typed array support here.

tracking the latest node api

This module tracks the Buffer API in the latest (unstable) version of node.js. The Buffer API is considered stable in the node stability index, so it is unlikely that there will ever be breaking changes. Nonetheless, when/if the Buffer API changes in node, this module's API will change accordingly.

related packages

• buffer-equals - Node.js 0.12 buffer.equals() ponyfill
• buffer-reverse - A lite module for reverse-operations on buffers
• buffer-xor - A simple module for bitwise-xor on buffers
• is-buffer - Determine if an object is a Buffer without including the whole Buffer package
• typedarray-to-buffer - Convert a typed array to a Buffer without a copy

performance

See perf tests in /perf.

BrowserBuffer is the browser buffer module (this repo). Uint8Array is included as a sanity check (since BrowserBuffer uses Uint8Array under the hood, Uint8Array will always be at least a bit faster). Finally, NodeBuffer is the node.js buffer module, which is included to compare against.

NOTE: Performance has improved since these benchmarks were taken. PR welcoem to update the README.

Chrome 38

Firefox 33

Safari 8

Node 0.11.14

iojs 1.8.1

Testing the project

First, install the project:

npm install

Then, to run tests in Node.js, run:

npm run test-node

To test locally in a browser, you can run:

npm run test-browser-local

This will print out a URL that you can then open in a browser to run the tests, using Zuul.

To run automated browser tests using Saucelabs, ensure that your SAUCE_USERNAME and SAUCE_ACCESS_KEY environment variables are set, then run:

npm test

This is what's run in Travis, to check against various browsers. The list of browsers is kept in the .zuul.yml file.

JavaScript Standard Style

This module uses JavaScript Standard Style.

To test that the code conforms to the style, npm install and run:

./node_modules/.bin/standard

credit

This was originally forked from buffer-browserify.

license

MIT. Copyright (C) Feross Aboukhadijeh, and other contributors. Originally forked from an MIT-licensed module by Romain Beauxis.