1 | # BSON parser
|
2 |
|
3 | 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).
|
4 |
|
5 | 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.
|
6 |
|
7 | 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).
|
8 |
|
9 | ## Usage
|
10 |
|
11 | To build a new version perform the following operations:
|
12 |
|
13 | ```
|
14 | npm install
|
15 | npm run build
|
16 | ```
|
17 |
|
18 | A simple example of how to use BSON in the browser:
|
19 |
|
20 | ```html
|
21 | <script src="./browser_build/bson.js"></script>
|
22 |
|
23 | <script>
|
24 | function start() {
|
25 | // Get the Long type
|
26 | var Long = BSON.Long;
|
27 | // Create a bson parser instance
|
28 | var bson = new BSON();
|
29 |
|
30 | // Serialize document
|
31 | var doc = { long: Long.fromNumber(100) }
|
32 |
|
33 | // Serialize a document
|
34 | var data = bson.serialize(doc)
|
35 | // De serialize it again
|
36 | var doc_2 = bson.deserialize(data)
|
37 | }
|
38 | </script>
|
39 | ```
|
40 |
|
41 | A simple example of how to use BSON in `Node.js`:
|
42 |
|
43 | ```js
|
44 | // Get BSON parser class
|
45 | var BSON = require('bson')
|
46 | // Get the Long type
|
47 | var Long = BSON.Long;
|
48 | // Create a bson parser instance
|
49 | var bson = new BSON();
|
50 |
|
51 | // Serialize document
|
52 | var doc = { long: Long.fromNumber(100) }
|
53 |
|
54 | // Serialize a document
|
55 | var data = bson.serialize(doc)
|
56 | console.log('data:', data)
|
57 |
|
58 | // Deserialize the resulting Buffer
|
59 | var doc_2 = bson.deserialize(data)
|
60 | console.log('doc_2:', doc_2)
|
61 | ```
|
62 |
|
63 | ## Installation
|
64 |
|
65 | `npm install bson`
|
66 |
|
67 | ## API
|
68 |
|
69 | ### BSON types
|
70 |
|
71 | For all BSON types documentation, please refer to the documentation for the [MongoDB Node.js driver](https://github.com/mongodb/node-mongodb-native).
|
72 |
|
73 | ### BSON serialization and deserialiation
|
74 |
|
75 | **`new BSON()`** - Creates a new BSON serializer/deserializer you can use to serialize and deserialize BSON.
|
76 |
|
77 | #### BSON.serialize
|
78 |
|
79 | The BSON `serialize` method takes a JavaScript object and an optional options object and returns a Node.js Buffer.
|
80 |
|
81 | * `BSON.serialize(object, options)`
|
82 | * @param {Object} object the JavaScript object to serialize.
|
83 | * @param {Boolean} [options.checkKeys=false] the serializer will check if keys are valid.
|
84 | * @param {Boolean} [options.serializeFunctions=false] serialize the JavaScript functions.
|
85 | * @param {Boolean} [options.ignoreUndefined=true]
|
86 | * @return {Buffer} returns a Buffer instance.
|
87 |
|
88 | #### BSON.serializeWithBufferAndIndex
|
89 |
|
90 | 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.
|
91 |
|
92 | * `BSON.serializeWithBufferAndIndex(object, buffer, options)`
|
93 | * @param {Object} object the JavaScript object to serialize.
|
94 | * @param {Buffer} buffer the Buffer you pre-allocated to store the serialized BSON object.
|
95 | * @param {Boolean} [options.checkKeys=false] the serializer will check if keys are valid.
|
96 | * @param {Boolean} [options.serializeFunctions=false] serialize the JavaScript functions.
|
97 | * @param {Boolean} [options.ignoreUndefined=true] ignore undefined fields.
|
98 | * @param {Number} [options.index=0] the index in the buffer where we wish to start serializing into.
|
99 | * @return {Number} returns the index pointing to the last written byte in the buffer.
|
100 |
|
101 | #### BSON.calculateObjectSize
|
102 |
|
103 | The BSON `calculateObjectSize` method takes a JavaScript object and an optional options object and returns the size of the BSON object.
|
104 |
|
105 | * `BSON.calculateObjectSize(object, options)`
|
106 | * @param {Object} object the JavaScript object to serialize.
|
107 | * @param {Boolean} [options.serializeFunctions=false] serialize the JavaScript functions.
|
108 | * @param {Boolean} [options.ignoreUndefined=true]
|
109 | * @return {Buffer} returns a Buffer instance.
|
110 |
|
111 | #### BSON.deserialize
|
112 |
|
113 | The BSON `deserialize` method takes a Node.js Buffer and an optional options object and returns a deserialized JavaScript object.
|
114 |
|
115 | * `BSON.deserialize(buffer, options)`
|
116 | * @param {Object} [options.evalFunctions=false] evaluate functions in the BSON document scoped to the object deserialized.
|
117 | * @param {Object} [options.cacheFunctions=false] cache evaluated functions for reuse.
|
118 | * @param {Object} [options.cacheFunctionsCrc32=false] use a crc32 code for caching, otherwise use the string of the function.
|
119 | * @param {Object} [options.promoteLongs=true] when deserializing a Long will fit it into a Number if it's smaller than 53 bits
|
120 | * @param {Object} [options.promoteBuffers=false] when deserializing a Binary will return it as a Node.js Buffer instance.
|
121 | * @param {Object} [options.promoteValues=false] when deserializing will promote BSON values to their Node.js closest equivalent types.
|
122 | * @param {Object} [options.fieldsAsRaw=null] allow to specify if there what fields we wish to return as unserialized raw buffer.
|
123 | * @param {Object} [options.bsonRegExp=false] return BSON regular expressions as BSONRegExp instances.
|
124 | * @return {Number} returns the next index in the buffer after deserialization **x** numbers of documents.
|
125 |
|
126 | #### BSON.deserializeStream
|
127 |
|
128 | The BSON `deserializeStream` method takes a Node.js Buffer, `startIndex` and allow more control over deserialization of a Buffer containing concatenated BSON documents.
|
129 |
|
130 | * `BSON.deserializeStream(buffer, startIndex, numberOfDocuments, documents, docStartIndex, options)`
|
131 | * @param {Buffer} buffer the buffer containing the serialized set of BSON documents.
|
132 | * @param {Number} startIndex the start index in the data Buffer where the deserialization is to start.
|
133 | * @param {Number} numberOfDocuments number of documents to deserialize.
|
134 | * @param {Array} documents an array where to store the deserialized documents.
|
135 | * @param {Number} docStartIndex the index in the documents array from where to start inserting documents.
|
136 | * @param {Object} [options.evalFunctions=false] evaluate functions in the BSON document scoped to the object deserialized.
|
137 | * @param {Object} [options.cacheFunctions=false] cache evaluated functions for reuse.
|
138 | * @param {Object} [options.cacheFunctionsCrc32=false] use a crc32 code for caching, otherwise use the string of the function.
|
139 | * @param {Object} [options.promoteLongs=true] when deserializing a Long will fit it into a Number if it's smaller than 53 bits
|
140 | * @param {Object} [options.promoteBuffers=false] when deserializing a Binary will return it as a Node.js Buffer instance.
|
141 | * @param {Object} [options.promoteValues=false] when deserializing will promote BSON values to their Node.js closest equivalent types.
|
142 | * @param {Object} [options.fieldsAsRaw=null] allow to specify if there what fields we wish to return as unserialized raw buffer.
|
143 | * @param {Object} [options.bsonRegExp=false] return BSON regular expressions as BSONRegExp instances.
|
144 | * @return {Object} returns the deserialized JavaScript Object.
|
145 |
|
146 | ## FAQ
|
147 |
|
148 | #### Why does `undefined` get converted to `null`?
|
149 |
|
150 | 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.
|