gerrit.onap Code Review - aai/esr-gui.git/blob

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