BSON is short for Binary JSON and is the binary-encoded serialization of JSON-like documents. You can learn more about it in [the specification](http://bsonspec.org).
This browser version of the BSON parser is compiled using [webpack](https://webpack.js.org/) and the current version is pre-compiled in the `browser_build` directory.
This is the default BSON parser, however, there is a C++ Node.js addon version as well that does not support the browser. It can be found at [mongod-js/bson-ext](https://github.com/mongodb-js/bson-ext).
## Usage
To build a new version perform the following operations:
```
npm install
npm run build
```
A simple example of how to use BSON in the browser:
```html
<script src="./browser_build/bson.js"></script>
<script>
function start() {
// Get the Long type
var Long = BSON.Long;
// Create a bson parser instance
var bson = new BSON();
// Serialize document
var doc = { long: Long.fromNumber(100) }
// Serialize a document
var data = bson.serialize(doc)
// De serialize it again
var doc_2 = bson.deserialize(data)
}
</script>
```
A simple example of how to use BSON in `Node.js`:
```js
// Get BSON parser class
var BSON = require('bson')
// Get the Long type
var Long = BSON.Long;
// Create a bson parser instance
var bson = new BSON();
// Serialize document
var doc = { long: Long.fromNumber(100) }
// Serialize a document
var data = bson.serialize(doc)
console.log('data:', data)
// Deserialize the resulting Buffer
var doc_2 = bson.deserialize(data)
console.log('doc_2:', doc_2)
```
## Installation
`npm install bson`
## API
### BSON types
For all BSON types documentation, please refer to the following sources:
* [MongoDB BSON Type Reference](https://docs.mongodb.com/manual/reference/bson-types/)
* [BSON Spec](https://bsonspec.org/)
### BSON serialization and deserialiation
**`new BSON()`** - Creates a new BSON serializer/deserializer you can use to serialize and deserialize BSON.
#### BSON.serialize
The BSON `serialize` method takes a JavaScript object and an optional options object and returns a Node.js Buffer.
* `BSON.serialize(object, options)`
* @param {Object} object the JavaScript object to serialize.
* @param {Boolean} [options.checkKeys=false] the serializer will check if keys are valid.
* @param {Boolean} [options.serializeFunctions=false] serialize the JavaScript functions.
* @param {Boolean} [options.ignoreUndefined=true]
* @return {Buffer} returns a Buffer instance.
#### BSON.serializeWithBufferAndIndex
The BSON `serializeWithBufferAndIndex` method takes an object, a target buffer instance and an optional options object and returns the end serialization index in the final buffer.
* @return {Object} returns the deserialized Javascript Object.
#### BSON.deserializeStream
The BSON `deserializeStream` method takes a Node.js Buffer, `startIndex` and allow more control over deserialization of a Buffer containing concatenated BSON documents.
* @return {Number} returns the next index in the buffer after deserialization **x** numbers of documents.
## FAQ
#### Why does `undefined` get converted to `null`?
The `undefined` BSON type has been [deprecated for many years](http://bsonspec.org/spec.html), so this library has dropped support for it. Use the `ignoreUndefined` option (for example, from the [driver](http://mongodb.github.io/node-mongodb-native/2.2/api/MongoClient.html#connect) ) to instead remove `undefined` keys.
#### How do I add custom serialization logic?
This library looks for `toBSON()` functions on every path, and calls the `toBSON()` function to get the value to serialize.