• Stars
    star
    1,130
  • Rank 41,185 (Top 0.9 %)
  • Language
    TypeScript
  • License
    Apache License 2.0
  • Created over 12 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

BSON Parser for node and browser

BSON parser

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.

Table of Contents

Bugs / Feature Requests

Think you've found a bug? Want to see a new feature in bson? Please open a case in our issue management tool, JIRA:

  1. Create an account and login: jira.mongodb.org
  2. Navigate to the NODE project: jira.mongodb.org/browse/NODE
  3. Click Create Issue - Please provide as much information as possible about the issue and how to reproduce it.

Bug reports in JIRA for all driver projects (i.e. NODE, PYTHON, CSHARP, JAVA) and the Core Server (i.e. SERVER) project are public.

Usage

To build a new version perform the following operations:

npm install
npm run build

Node.js or Bundling Usage

When using a bundler or Node.js you can import bson using the package name:

import { BSON, EJSON, ObjectId } from 'bson';
// or:
// const { BSON, EJSON, ObjectId } = require('bson');

const bytes = BSON.serialize({ _id: new ObjectId() });
console.log(bytes);
const doc = BSON.deserialize(bytes);
console.log(EJSON.stringify(doc));
// {"_id":{"$oid":"..."}}

Browser Usage

If you are working directly in the browser without a bundler please use the .mjs bundle like so:

<script type="module">
  import { BSON, EJSON, ObjectId } from './lib/bson.mjs';

  const bytes = BSON.serialize({ _id: new ObjectId() });
  console.log(bytes);
  const doc = BSON.deserialize(bytes);
  console.log(EJSON.stringify(doc));
  // {"_id":{"$oid":"..."}}
</script>

Installation

npm install bson

Documentation

BSON

API documentation

EJSON

EJSON.parse(text, [options])

Param Type Default Description
text string
[options] object Optional settings
[options.relaxed] boolean true Attempt to return native JS types where possible, rather than BSON types (if true)

Parse an Extended JSON string, constructing the JavaScript value or object described by that string.

Example

const { EJSON } = require('bson');
const text = '{ "int32": { "$numberInt": "10" } }';

// prints { int32: { [String: '10'] _bsontype: 'Int32', value: '10' } }
console.log(EJSON.parse(text, { relaxed: false }));

// prints { int32: 10 }
console.log(EJSON.parse(text));

EJSON.stringify(value, [replacer], [space], [options])

Param Type Default Description
value object The value to convert to extended JSON
[replacer] function | array A function that alters the behavior of the stringification process, or an array of String and Number objects that serve as a whitelist for selecting/filtering the properties of the value object to be included in the JSON string. If this value is null or not provided, all properties of the object are included in the resulting JSON string
[space] string | number A String or Number object that's used to insert white space into the output JSON string for readability purposes.
[options] object Optional settings
[options.relaxed] boolean true Enabled Extended JSON's relaxed mode
[options.legacy] boolean true Output in Extended JSON v1

Converts a BSON document to an Extended JSON string, optionally replacing values if a replacer function is specified or optionally including only the specified properties if a replacer array is specified.

Example

const { EJSON } = require('bson');
const Int32 = require('mongodb').Int32;
const doc = { int32: new Int32(10) };

// prints '{"int32":{"$numberInt":"10"}}'
console.log(EJSON.stringify(doc, { relaxed: false }));

// prints '{"int32":10}'
console.log(EJSON.stringify(doc));

EJSON.serialize(bson, [options])

Param Type Description
bson object The object to serialize
[options] object Optional settings passed to the stringify function

Serializes an object to an Extended JSON string, and reparse it as a JavaScript object.

EJSON.deserialize(ejson, [options])

Param Type Description
ejson object The Extended JSON object to deserialize
[options] object Optional settings passed to the parse method

Deserializes an Extended JSON object into a plain JavaScript object with native/BSON types

Error Handling

It is our recommendation to use BSONError.isBSONError() checks on errors and to avoid relying on parsing error.message and error.name strings in your code. We guarantee BSONError.isBSONError() checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors.

Any new errors we add to the driver will directly extend an existing error class and no existing error will be moved to a different parent class outside of a major release. This means BSONError.isBSONError() will always be able to accurately capture the errors that our BSON library throws.

Hypothetical example: A collection in our Db has an issue with UTF-8 data:

let documentCount = 0;
const cursor = collection.find({}, { utf8Validation: true });
try {
  for await (const doc of cursor) documentCount += 1;
} catch (error) {
  if (BSONError.isBSONError(error)) {
    console.log(`Found the troublemaker UTF-8!: ${documentCount} ${error.message}`);
    return documentCount;
  }
  throw error;
}

React Native

BSON vendors the required polyfills for TextEncoder, TextDecoder, atob, btoa imported from React Native and therefore doesn't expect users to polyfill these. One additional polyfill, crypto.getRandomValues is recommended and can be installed with the following command:

npm install --save react-native-get-random-values

The following snippet should be placed at the top of the entrypoint (by default this is the root index.js file) for React Native projects using the BSON library. These lines must be placed for any code that imports BSON.

// Required Polyfills For ReactNative
import 'react-native-get-random-values';

Finally, import the BSON library like so:

import { BSON, EJSON } from 'bson';

This will cause React Native to import the node_modules/bson/lib/bson.rn.cjs bundle (see the "react-native" setting we have in the "exports" section of our package.json.)

Technical Note about React Native module import

The "exports" definition in our package.json will result in BSON's CommonJS bundle being imported in a React Native project instead of the ES module bundle. Importing the CommonJS bundle is necessary because BSON's ES module bundle of BSON uses top-level await, which is not supported syntax in React Native's runtime hermes.

FAQ

Why does undefined get converted to null?

The undefined BSON type has been deprecated for many years, so this library has dropped support for it. Use the ignoreUndefined option (for example, from the driver ) 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.

const BSON = require('bson');

class CustomSerialize {
  toBSON() {
    return 42;
  }
}

const obj = { answer: new CustomSerialize() };
// "{ answer: 42 }"
console.log(BSON.deserialize(BSON.serialize(obj)));

More Repositories

1

mongo

The MongoDB Database
C++
26,192
star
2

node-mongodb-native

The official MongoDB Node.js driver
TypeScript
10,030
star
3

mongo-go-driver

The Official Golang driver for MongoDB
Go
8,135
star
4

laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel (Moloquent)
PHP
6,997
star
5

mongo-python-driver

PyMongo - the Official MongoDB Python driver
Python
4,129
star
6

mongoid

The Official Ruby Object Mapper for MongoDB
Ruby
3,922
star
7

mongo-csharp-driver

The Official C# .NET Driver for MongoDB
C#
3,038
star
8

mongo-java-driver

The official MongoDB drivers for Java, Kotlin, and Scala
Java
2,568
star
9

motor

Motor - the async Python driver for MongoDB and Tornado or asyncio
Python
2,410
star
10

mongo-php-library

The Official MongoDB PHP library
PHP
1,594
star
11

mongo-hadoop

MongoDB Connector for Hadoop
Java
1,519
star
12

mongo-ruby-driver

The Official MongoDB Ruby Driver
Ruby
1,422
star
13

mongo-rust-driver

The official MongoDB Rust Driver
Rust
1,268
star
14

mongodb-kubernetes-operator

MongoDB Community Kubernetes Operator
Go
1,218
star
15

mongo-php-driver-legacy

Legacy MongoDB PHP driver
PHP
1,093
star
16

mongo-cxx-driver

C++ Driver for MongoDB
C++
1,040
star
17

mongo-tools

Go
994
star
18

homebrew-brew

The Official MongoDB Software Homebrew Tap
Ruby
924
star
19

mongo-php-driver

The Official MongoDB PHP driver
PHP
838
star
20

mongo-c-driver

The Official MongoDB driver for C language
C
815
star
21

docs

The MongoDB Documentation Project Source.
Java
738
star
22

mongo-spark

The MongoDB Spark Connector
Java
706
star
23

casbah

Casbah is now officially end-of-life (EOL).
Scala
514
star
24

bson-rust

Encoding and decoding support for BSON in Rust
Rust
402
star
25

specifications

Specifications related to MongoDB
Python
383
star
26

mongo-snippets

snippets of code that might be useful for your mongodb deployment
C++
381
star
27

cookbook

MongoDB recipes.
Ruby
354
star
28

pymodm

A Pythonic, object-oriented interface for working with MongoDB.
Python
351
star
29

mongo-perf

performance tools for mongodb
JavaScript
350
star
30

libbson

ARCHIVED - libbson has moved to https://github.com/mongodb/mongo-c-driver/tree/master/src/libbson
C
347
star
31

mongo-kafka

MongoDB Kafka Connector
Java
342
star
32

mongo-efcore-provider

MongoDB Entity Framework Core Provider
C#
329
star
33

mongo-swift-driver

The official MongoDB driver for Swift
Swift
325
star
34

mongodb-enterprise-kubernetes

MongoDB Enterprise Kubernetes Operator
Dockerfile
325
star
35

mongo-scala-driver

Scala
286
star
36

terraform-provider-mongodbatlas

Terraform MongoDB Atlas Provider: Deploy, update, and manage MongoDB Atlas infrastructure as code through HashiCorp Terraform
Go
242
star
37

leafygreen-ui

LeafyGreen UI – LeafyGreen's React UI Kit
TypeScript
219
star
38

mongodb-atlas-cli

MongoDB Atlas CLI and MongoDB CLI enable you to manage your MongoDB in the Cloud
Go
161
star
39

mongodb-atlas-kubernetes

MongoDB Atlas Kubernetes Operator - Manage your MongoDB Atlas clusters from Kubernetes
Go
148
star
40

stitch-examples

MongoDB Stitch Examples
Java
138
star
41

chatbot

MongoDB Chatbot Framework. Powered by MongoDB and Atlas Vector Search.
TypeScript
135
star
42

support-tools

For support tools to be shared publicly
Go
127
star
43

stitch-js-sdk

MongoDB Stitch JavaScript SDK
TypeScript
113
star
44

mongo-bi-connector-odbc-driver

ODBC driver for MongoDB Connector for Business Intelligence
C
110
star
45

mongo-azure

C#
103
star
46

amboy

Amboy -- A Go(lang) Job Queue Tool
Go
98
star
47

helm-charts

Smarty
94
star
48

libmongocrypt

Required C library for Client Side and Queryable Encryption in MongoDB
C
94
star
49

bsonspec.org

site for bsonspec.org
HTML
92
star
50

terraform-aws-ecs-task-definition

A Terraform module for creating Amazon ECS Task Definitions
HCL
85
star
51

go-client-mongodb-atlas

Go Client for MongoDB Atlas
Go
79
star
52

docs-ecosystem

MongoDB Ecosystem Documentation
Python
77
star
53

bson-ruby

Ruby Implementation of the BSON Specification (2.0.0+)
Ruby
77
star
54

mongo-java-driver-reactivestreams

The Java Reactive Stream driver for MongoDB
Java
73
star
55

mongodbatlas-cloudformation-resources

MongoDB Atlas CloudFormation Resources: Deploy, update, and manage MongoDB Atlas infrastructure as code through AWS CloudFormation
Go
59
star
56

stitch-android-sdk

MongoDB Stitch Android SDK
Java
57
star
57

genny

🧞‍♀️ Grants 3 wishes. As long as those wishes are to generate load 🧞‍♂️
C++
49
star
58

winkerberos

A native Kerberos client implementation for Python on Windows
C
47
star
59

docs-realm

Realm Database SDK documentation
Kotlin
44
star
60

bson-numpy

This project has been superseded by PyMongoArrow - https://github.com/mongodb-labs/mongo-arrow/tree/main/bindings/python
C
43
star
61

stitch-ios-sdk

Swift
42
star
62

docs-tools

Common tools and content for MongoDB documentation projects.
Python
42
star
63

swift-bson

pure Swift BSON library
Swift
41
star
64

signal-processing-algorithms

Python
41
star
65

mongo-jdbc-driver

JDBC Driver for MongoDB Atlas SQL interface
Java
38
star
66

design

Source code for MongoDB.design, LeafyGreen's official documentation site.
TypeScript
36
star
67

mongo-hhvm-driver

MongoDB HHVM driver **Note, this driver is no longer maintained**
PHP
35
star
68

awscdk-resources-mongodbatlas

MongoDB Atlas AWS CDK Resources
TypeScript
35
star
69

mongodb-vapor

MongoDB + Vapor integration
Swift
34
star
70

atlas-billing

JavaScript
33
star
71

atlas-app-services-examples

Example use cases for Atlas App Services
JavaScript
32
star
72

mongo-java-driver-rx

The MongoDB Java RX driver is now officially end-of-life (EOL)
Java
30
star
73

snooty

MongoDB Documentation front end
JavaScript
29
star
74

mongo-csharp-analyzer

The MongoDB Analyzer is a free tool that helps you understand how your code translates into the MongoDB Query API.
C#
27
star
75

realm-practice

realm-node-practice & realm-swift-practice
Swift
24
star
76

charts-embedding-examples

charts-embedding-examples
HTML
23
star
77

ftdc

utils for working with mongodb full-time diagnostic data capture files
Go
23
star
78

mongo-csharp-driver-jsondotnet

The C#/.NET driver will have a new component to integrate with JSON.NET that needs to live separately from the .NET driver itself.
C#
22
star
79

template-app-react-native-todo

Atlas Template Starter App - Use Device Sync from a React Native client application. This repo is generated from source code in https://github.com/mongodb-university/realm-template-apps
TypeScript
21
star
80

mongo-odbc-driver

Rust
20
star
81

marian

A search engine focused on documentation.
JavaScript
20
star
82

curator

Curator -- a build and package automation tool
Go
19
star
83

mongo-qa

General QA materials for Mongo
Java
19
star
84

anser

Data Transformation/Migration Tool
Go
19
star
85

snooty-parser

Python
19
star
86

academia-mongodb-lab-python

Lab using MongoDB with Python (PyMongo driver). Created for educational use by the MongoDB for Academia program.
Jupyter Notebook
19
star
87

kbson

Kotlin Multiplatform Bson Library
Kotlin
18
star
88

docs-compass

Python
18
star
89

docs-bi-connector

Makefile
17
star
90

atlas-sdk-go

MongoDB Atlas Golang SDK
Go
17
star
91

snooty-vscode

TypeScript
17
star
92

terraform-provider-mongodbatlas-archive

ARCHIVED ---- Hashicorp Terraform Provider for MongoDB Atlas - please use https://github.com/terraform-providers/terraform-provider-mongodbatlas
Go
17
star
93

mongo-aspnetcore-odata

Adds MongoDB support to Microsoft ASP.NET Core oData.
C#
16
star
94

template-app-swiftui-todo

Atlas Template Starter App - Use Device Sync from a SwiftUI client application. This repo is generated from source code in https://github.com/mongodb-university/realm-template-apps
Swift
16
star
95

docs-worker-pool

TypeScript
15
star
96

jasper

Jasper is a Process Management Framework
Go
15
star
97

grip

Go
15
star
98

go-client-mongodb-ops-manager

An HTTP client for Ops Manager and Cloud Manager Public API endpoints.
Go
15
star
99

vault-plugin-secrets-mongodbatlas

ARCHIVED - Hashicorp Vault MongoDB Atlas Secrets Engine - Now hosted at https://github.com/hashicorp/vault-plugin-secrets-mongodbatlas/
Go
15
star
100

docs-java

MongoDB Java driver documentation
Java
14
star