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 important difference (see below)
.slice()
returns instances of the same type (Buffer)- 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
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.
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
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 are augmented with function properties for all the Buffer
API functions. We use Uint8Array
so that square bracket notation works as expected -- it returns a single octet. By augmenting the instances, we can avoid modifying the Uint8Array
prototype.
differences
IMPORTANT: always use Buffer.isBuffer
instead of instanceof Buffer
The Buffer constructor returns a Uint8Array
(with all the Buffer methods added as
properties on the instance) for performance reasons, so instanceof Buffer
won't work. In
node, you can use either Buffer.isBuffer
or instanceof Buffer
to check if an object
is a Buffer
. But, in the browser you must use Buffer.isBuffer
to detect the special
Uint8Array
-based Buffers.
Minor: buf.slice()
does not modify parent buffer's memory in old browsers
If you only support modern browsers (specifically, those with typed array support), then
this issue does not affect you.
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.
This works correctly in browsers with typed array support (* with the exception of Firefox older than version 30). Browsers that lack typed arrays get an alternate buffer implementation based on Object
which has no mechanism to point separate Buffer
s to the same underlying slab of memory.
* Firefox older than version 30 gets the Object
implementation -- not the typed arrays one -- because of this
bug (now fixed!) that made it impossible to add properties to a typed array.
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.
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.
# Chrome 38
BrowserBuffer#bracket-notation x 11,457,464 ops/sec ±0.86% (66 runs sampled) bundle.js:5262
Uint8Array#bracket-notation x 10,824,332 ops/sec ±0.74% (65 runs sampled) bundle.js:5262
Fastest is BrowserBuffer#bracket-notation
BrowserBuffer#concat x 450,532 ops/sec ±0.76% (68 runs sampled) bundle.js:5267
Uint8Array#concat x 1,368,911 ops/sec ±1.50% (62 runs sampled) bundle.js:5267
Fastest is Uint8Array#concat
BrowserBuffer#copy(16000) x 903,001 ops/sec ±0.96% (67 runs sampled) bundle.js:5261
Uint8Array#copy(16000) x 1,422,441 ops/sec ±1.04% (66 runs sampled) bundle.js:5261
Fastest is Uint8Array#copy(16000)
BrowserBuffer#copy(16) x 11,431,358 ops/sec ±0.46% (69 runs sampled) bundle.js:5261
Uint8Array#copy(16) x 13,944,163 ops/sec ±1.12% (68 runs sampled) bundle.js:5261
Fastest is Uint8Array#copy(16)
BrowserBuffer#new(16000) x 106,329 ops/sec ±6.70% (44 runs sampled) bundle.js:5253
Uint8Array#new(16000) x 131,001 ops/sec ±2.85% (31 runs sampled) bundle.js:5253
Fastest is Uint8Array#new(16000)
BrowserBuffer#new(16) x 1,554,491 ops/sec ±1.60% (65 runs sampled) bundle.js:5253
Uint8Array#new(16) x 6,623,930 ops/sec ±1.66% (65 runs sampled) bundle.js:5253
Fastest is Uint8Array#new(16)
BrowserBuffer#readDoubleBE x 112,830 ops/sec ±0.51% (69 runs sampled) bundle.js:5274
DataView#getFloat64 x 93,500 ops/sec ±0.57% (68 runs sampled) bundle.js:5274
Fastest is BrowserBuffer#readDoubleBE
BrowserBuffer#readFloatBE x 146,678 ops/sec ±0.95% (68 runs sampled) bundle.js:5274
DataView#getFloat32 x 99,311 ops/sec ±0.41% (67 runs sampled) bundle.js:5274
Fastest is BrowserBuffer#readFloatBE
BrowserBuffer#readUInt32LE x 843,214 ops/sec ±0.70% (69 runs sampled) bundle.js:5274
DataView#getUint32 x 103,024 ops/sec ±0.64% (67 runs sampled) bundle.js:5274
Fastest is BrowserBuffer#readUInt32LE
BrowserBuffer#slice x 1,013,941 ops/sec ±0.75% (67 runs sampled) bundle.js:5257
Uint8Array#subarray x 1,903,928 ops/sec ±0.53% (67 runs sampled) bundle.js:5257
Fastest is Uint8Array#subarray
BrowserBuffer#writeFloatBE x 61,387 ops/sec ±0.90% (67 runs sampled) bundle.js:5231
DataView#setFloat32 x 141,249 ops/sec ±0.40% (66 runs sampled) bundle.js:5231
Fastest is DataView#setFloat32
# Firefox 33
"BrowserBuffer#bracket-notation x 20,800,421 ops/sec ±1.84% (60 runs sampled)" bundle.js:5262
"Uint8Array#bracket-notation x 20,826,235 ops/sec ±2.02% (61 runs sampled)" bundle.js:5262
"Fastest is BrowserBuffer#bracket-notation,Uint8Array#bracket-notation"
"BrowserBuffer#concat x 153,076 ops/sec ±2.32% (61 runs sampled)" bundle.js:5267
"Uint8Array#concat x 1,255,674 ops/sec ±8.65% (52 runs sampled)" bundle.js:5267
"Fastest is Uint8Array#concat"
"BrowserBuffer#copy(16000) x 1,105,312 ops/sec ±1.16% (63 runs sampled)" bundle.js:5261
"Uint8Array#copy(16000) x 1,615,911 ops/sec ±0.55% (66 runs sampled)" bundle.js:5261
"Fastest is Uint8Array#copy(16000)"
"BrowserBuffer#copy(16) x 16,357,599 ops/sec ±0.73% (68 runs sampled)" bundle.js:5261
"Uint8Array#copy(16) x 31,436,281 ops/sec ±1.05% (68 runs sampled)" bundle.js:5261
"Fastest is Uint8Array#copy(16)"
"BrowserBuffer#new(16000) x 52,995 ops/sec ±6.01% (35 runs sampled)" bundle.js:5253
"Uint8Array#new(16000) x 87,686 ops/sec ±5.68% (45 runs sampled)" bundle.js:5253
"Fastest is Uint8Array#new(16000)"
"BrowserBuffer#new(16) x 252,031 ops/sec ±1.61% (66 runs sampled)" bundle.js:5253
"Uint8Array#new(16) x 8,477,026 ops/sec ±0.49% (68 runs sampled)" bundle.js:5253
"Fastest is Uint8Array#new(16)"
"BrowserBuffer#readDoubleBE x 99,871 ops/sec ±0.41% (69 runs sampled)" bundle.js:5274
"DataView#getFloat64 x 285,663 ops/sec ±0.70% (68 runs sampled)" bundle.js:5274
"Fastest is DataView#getFloat64"
"BrowserBuffer#readFloatBE x 115,540 ops/sec ±0.42% (69 runs sampled)" bundle.js:5274
"DataView#getFloat32 x 288,722 ops/sec ±0.82% (68 runs sampled)" bundle.js:5274
"Fastest is DataView#getFloat32"
"BrowserBuffer#readUInt32LE x 633,926 ops/sec ±1.08% (67 runs sampled)" bundle.js:5274
"DataView#getUint32 x 294,808 ops/sec ±0.79% (64 runs sampled)" bundle.js:5274
"Fastest is BrowserBuffer#readUInt32LE"
"BrowserBuffer#slice x 349,425 ops/sec ±0.46% (69 runs sampled)" bundle.js:5257
"Uint8Array#subarray x 5,965,819 ops/sec ±0.60% (65 runs sampled)" bundle.js:5257
"Fastest is Uint8Array#subarray"
"BrowserBuffer#writeFloatBE x 59,980 ops/sec ±0.41% (67 runs sampled)" bundle.js:5231
"DataView#setFloat32 x 317,634 ops/sec ±0.63% (68 runs sampled)" bundle.js:5231
"Fastest is DataView#setFloat32"
# Safari 8
[Log] BrowserBuffer#bracket-notation x 10,279,729 ops/sec ±2.25% (56 runs sampled) (bundle.js, line 5262)
[Log] Uint8Array#bracket-notation x 10,030,767 ops/sec ±2.23% (59 runs sampled) (bundle.js, line 5262)
[Log] Fastest is BrowserBuffer#bracket-notation,Uint8Array#bracket-notation (bundle.js, line 5265)
[Log] BrowserBuffer#concat x 144,138 ops/sec ±1.38% (65 runs sampled) (bundle.js, line 5267)
[Log] Uint8Array#concat x 4,950,764 ops/sec ±1.70% (63 runs sampled) (bundle.js, line 5267)
[Log] Fastest is Uint8Array#concat (bundle.js, line 5270)
[Log] BrowserBuffer#copy(16000) x 1,058,548 ops/sec ±1.51% (64 runs sampled) (bundle.js, line 5261)
[Log] Uint8Array#copy(16000) x 1,409,666 ops/sec ±1.17% (65 runs sampled) (bundle.js, line 5261)
[Log] Fastest is Uint8Array#copy(16000) (bundle.js, line 5264)
[Log] BrowserBuffer#copy(16) x 6,282,529 ops/sec ±1.88% (58 runs sampled) (bundle.js, line 5261)
[Log] Uint8Array#copy(16) x 11,907,128 ops/sec ±2.87% (58 runs sampled) (bundle.js, line 5261)
[Log] Fastest is Uint8Array#copy(16) (bundle.js, line 5264)
[Log] BrowserBuffer#new(16000) x 101,663 ops/sec ±3.89% (57 runs sampled) (bundle.js, line 5253)
[Log] Uint8Array#new(16000) x 22,050,818 ops/sec ±6.51% (46 runs sampled) (bundle.js, line 5253)
[Log] Fastest is Uint8Array#new(16000) (bundle.js, line 5256)
[Log] BrowserBuffer#new(16) x 176,072 ops/sec ±2.13% (64 runs sampled) (bundle.js, line 5253)
[Log] Uint8Array#new(16) x 24,385,731 ops/sec ±5.01% (51 runs sampled) (bundle.js, line 5253)
[Log] Fastest is Uint8Array#new(16) (bundle.js, line 5256)
[Log] BrowserBuffer#readDoubleBE x 41,341 ops/sec ±1.06% (67 runs sampled) (bundle.js, line 5274)
[Log] DataView#getFloat64 x 322,280 ops/sec ±0.84% (68 runs sampled) (bundle.js, line 5274)
[Log] Fastest is DataView#getFloat64 (bundle.js, line 5277)
[Log] BrowserBuffer#readFloatBE x 46,141 ops/sec ±1.06% (65 runs sampled) (bundle.js, line 5274)
[Log] DataView#getFloat32 x 337,025 ops/sec ±0.43% (69 runs sampled) (bundle.js, line 5274)
[Log] Fastest is DataView#getFloat32 (bundle.js, line 5277)
[Log] BrowserBuffer#readUInt32LE x 151,551 ops/sec ±1.02% (66 runs sampled) (bundle.js, line 5274)
[Log] DataView#getUint32 x 308,278 ops/sec ±0.94% (67 runs sampled) (bundle.js, line 5274)
[Log] Fastest is DataView#getUint32 (bundle.js, line 5277)
[Log] BrowserBuffer#slice x 197,365 ops/sec ±0.95% (66 runs sampled) (bundle.js, line 5257)
[Log] Uint8Array#subarray x 9,558,024 ops/sec ±3.08% (58 runs sampled) (bundle.js, line 5257)
[Log] Fastest is Uint8Array#subarray (bundle.js, line 5260)
[Log] BrowserBuffer#writeFloatBE x 17,518 ops/sec ±1.03% (63 runs sampled) (bundle.js, line 5231)
[Log] DataView#setFloat32 x 319,751 ops/sec ±0.48% (68 runs sampled) (bundle.js, line 5231)
[Log] Fastest is DataView#setFloat32 (bundle.js, line 5234)
# Node 0.11.14
BrowserBuffer#bracket-notation x 10,489,828 ops/sec ±3.25% (90 runs sampled)
Uint8Array#bracket-notation x 10,534,884 ops/sec ±0.81% (92 runs sampled)
NodeBuffer#bracket-notation x 10,389,910 ops/sec ±0.97% (87 runs sampled)
Fastest is Uint8Array#bracket-notation,BrowserBuffer#bracket-notation
BrowserBuffer#concat x 487,830 ops/sec ±2.58% (88 runs sampled)
Uint8Array#concat x 1,814,327 ops/sec ±1.28% (88 runs sampled)
NodeBuffer#concat x 1,636,523 ops/sec ±1.88% (73 runs sampled)
Fastest is Uint8Array#concat
BrowserBuffer#copy(16000) x 1,073,665 ops/sec ±0.77% (90 runs sampled)
Uint8Array#copy(16000) x 1,348,517 ops/sec ±0.84% (89 runs sampled)
NodeBuffer#copy(16000) x 1,289,533 ops/sec ±0.82% (93 runs sampled)
Fastest is Uint8Array#copy(16000)
BrowserBuffer#copy(16) x 12,782,706 ops/sec ±0.74% (85 runs sampled)
Uint8Array#copy(16) x 14,180,427 ops/sec ±0.93% (92 runs sampled)
NodeBuffer#copy(16) x 11,083,134 ops/sec ±1.06% (89 runs sampled)
Fastest is Uint8Array#copy(16)
BrowserBuffer#new(16000) x 141,678 ops/sec ±3.30% (67 runs sampled)
Uint8Array#new(16000) x 161,491 ops/sec ±2.96% (60 runs sampled)
NodeBuffer#new(16000) x 292,699 ops/sec ±3.20% (55 runs sampled)
Fastest is NodeBuffer#new(16000)
BrowserBuffer#new(16) x 1,655,466 ops/sec ±2.41% (82 runs sampled)
Uint8Array#new(16) x 14,399,926 ops/sec ±0.91% (94 runs sampled)
NodeBuffer#new(16) x 3,894,696 ops/sec ±0.88% (92 runs sampled)
Fastest is Uint8Array#new(16)
BrowserBuffer#readDoubleBE x 109,582 ops/sec ±0.75% (93 runs sampled)
DataView#getFloat64 x 91,235 ops/sec ±0.81% (90 runs sampled)
NodeBuffer#readDoubleBE x 88,593 ops/sec ±0.96% (81 runs sampled)
Fastest is BrowserBuffer#readDoubleBE
BrowserBuffer#readFloatBE x 139,854 ops/sec ±1.03% (85 runs sampled)
DataView#getFloat32 x 98,744 ops/sec ±0.80% (89 runs sampled)
NodeBuffer#readFloatBE x 92,769 ops/sec ±0.94% (93 runs sampled)
Fastest is BrowserBuffer#readFloatBE
BrowserBuffer#readUInt32LE x 710,861 ops/sec ±0.82% (92 runs sampled)
DataView#getUint32 x 117,893 ops/sec ±0.84% (91 runs sampled)
NodeBuffer#readUInt32LE x 851,412 ops/sec ±0.72% (93 runs sampled)
Fastest is NodeBuffer#readUInt32LE
BrowserBuffer#slice x 1,673,877 ops/sec ±0.73% (94 runs sampled)
Uint8Array#subarray x 6,919,243 ops/sec ±0.67% (90 runs sampled)
NodeBuffer#slice x 4,617,604 ops/sec ±0.79% (93 runs sampled)
Fastest is Uint8Array#subarray
BrowserBuffer#writeFloatBE x 66,011 ops/sec ±0.75% (93 runs sampled)
DataView#setFloat32 x 127,760 ops/sec ±0.72% (93 runs sampled)
NodeBuffer#writeFloatBE x 103,352 ops/sec ±0.83% (93 runs sampled)
Fastest is DataView#setFloat32
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.