# bson-ext

> The C++ bson parser for the node.js mongodb driver.

Latest version **4.0.3** (published 2022-09-15) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install bson-ext
pnpm add bson-ext
yarn add bson-ext
bun add bson-ext
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.3 |
| Published | 2022-09-15 |
| First published | 2015-03-26 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6.9.0 |
| Dependencies | 4 |
| Unpacked size | 131.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 42 |
| Author | The MongoDB NodeJS Team |
| Maintainers | mbroadst, durran, nbbeeken, kmahar, dariakp |
| Keywords | mongodb, bson, parser |

## Links

- npm: https://www.npmjs.com/package/bson-ext
- Repository: https://github.com/mongodb-js/bson-ext
- Homepage: https://github.com/mongodb-js/bson-ext#readme
- Issues: https://jira.mongodb.org/projects/NODE/issues/
- npm.io page: https://npm.io/package/bson-ext

## Dependencies (4)

- [nan](https://npm.io/package/nan.md) ^2.14.2
- [bson](https://npm.io/package/bson.md) ^4.7.0
- [bindings](https://npm.io/package/bindings.md) ^1.5.0
- [prebuild-install](https://npm.io/package/prebuild-install.md) ^6.1.2

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 4.0.3 (latest) — 2022-09-15
- 2.0.6 (LTS) — 2021-10-05
- 4.0.2 — 2021-10-05
- 4.0.1 — 2021-09-14
- 4.0.0 — 2021-05-25
- 2.0.5 — 2020-07-31
- 2.0.4 — 2020-07-31
- 2.0.3 — 2019-08-22
- 2.0.2 — 2019-04-08
- 2.0.1 — 2018-08-17
- 2.0.0 — 2018-03-02
- 1.0.5 — 2017-01-20
- 1.0.4 — 2017-01-11
- 1.0.3 — 2017-01-03
- 1.0.2 — 2017-01-02
- … 15 more at https://npm.io/package/bson-ext/versions

## README

# BSON-EXT

_A BSON parser Node.JS native addon._

BSON is short for Bin­ary JSON and is the bin­ary-en­coded seri­al­iz­a­tion of JSON-like doc­u­ments. You can learn more about it in [the specification](http://bsonspec.org).

While this library is compatible with the mongodb driver version 4+, bson-ext will soon be deprecated and no longer supported.  It is strongly recommended
that [js-bson](https://github.com/mongodb/js-bson) be used instead.

**NOTE: bson-ext version 4+ works with js-bson version 4+ and the mongodb driver version 4+.**

## Installation

```sh
npm install bson-ext
```

## Usage

A simple example of how to use BSON in `Node.js`:

```js
// Get BSON parser class
const BSON = require('bson-ext')
// Get the Long type
const Long = BSON.Long;

// Serialize document
const doc = { long: Long.fromNumber(100) }

// Serialize a document
const data = BSON.serialize(doc)
console.log('data:', data)

// Deserialize the resulting Buffer
var docRoundTrip = bson.deserialize(data)
console.log('docRoundTrip:', docRoundTrip)
```

## Compiling

To build a new version perform the following operation.

```sh
npm install
npm run build
```

## API

### BSON types

For all BSON types documentation, please refer to the documentation for the [MongoDB Node.js driver](http://mongodb.github.io/node-mongodb-native/4.0).

#### BSON.serialize

The BSON `serialize` method takes a JavaScript object and an optional options object and returns a Node.js Buffer.

```typescript
/**
 * The BSON library accepts plain javascript objects.
 * It serializes to BSON by iterating the keys
 */
interface Document {
    [key: string]: any;
}

interface SerializeOptions {
    /** the serializer will check if keys are valid. */
    checkKeys?: boolean;
    /** serialize the javascript functions **(default:false)**. */
    serializeFunctions?: boolean;
    /** serialize will not emit undefined fields **(default:true)** */
    ignoreUndefined?: boolean;
}

/**
 * Serialize a Javascript object.
 *
 * @param object - the Javascript object to serialize.
 * @returns Buffer object containing the serialized object.
 */
function serialize(object: Document, options?: SerializeOptions): Buffer;
```

#### 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.

```typescript
/**
 * Serialize a Javascript object using a predefined Buffer and index into the buffer,
 * useful when pre-allocating the space for serialization.
 *
 * @param object - the Javascript object to serialize.
 * @param finalBuffer - the Buffer you pre-allocated to store the serialized BSON object.
 * @returns the index pointing to the last written byte in the buffer.
 */
function serializeWithBufferAndIndex(object: Document, finalBuffer: Buffer, options?: SerializeOptions): number;
```

#### BSON.calculateObjectSize

The BSON `calculateObjectSize` method takes a JavaScript object and an optional options object and returns the size of the BSON object.

```typescript
interface CalculateObjectSizeOptions {
    /** serialize the javascript functions **(default:false)**. */
    serializeFunctions?: boolean;
    /** serialize will not emit undefined fields **(default:true)** */
    ignoreUndefined?: boolean;
}


/**
 * Calculate the bson size for a passed in Javascript object.
 *
 * @param object - the Javascript object to calculate the BSON byte size for
 * @returns size of BSON object in bytes
 * @public
 */
function calculateObjectSize(object: Document, options?: CalculateObjectSizeOptions): number;
```

#### BSON.deserialize

The BSON `deserialize` method takes a Node.js Buffer and an optional options object and returns a deserialized JavaScript object.

```typescript
interface DeserializeOptions {
    /** evaluate functions in the BSON document scoped to the object deserialized. */
    evalFunctions?: boolean;
    /** cache evaluated functions for reuse. */
    cacheFunctions?: boolean;
    /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits */
    promoteLongs?: boolean;
    /** when deserializing a Binary will return it as a node.js Buffer instance. */
    promoteBuffers?: boolean;
    /** when deserializing will promote BSON values to their Node.js closest equivalent types. */
    promoteValues?: boolean;
    /** allow to specify if there what fields we wish to return as unserialized raw buffer. */
    fieldsAsRaw?: Document;
    /** return BSON regular expressions as BSONRegExp instances. */
    bsonRegExp?: boolean;
    /** allows the buffer to be larger than the parsed BSON object */
    allowObjectSmallerThanBufferSize?: boolean;
    /** Offset into buffer to begin reading document from */
    index?: number;
}

/**
 * Deserialize data as BSON.
 *
 * @param buffer - the buffer containing the serialized set of BSON documents.
 * @returns returns the deserialized Javascript Object.
 * @public
 */
function deserialize(buffer: Buffer | ArrayBufferView | ArrayBuffer, options?: DeserializeOptions): Document;
```

#### 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.

```typescript
/**
 * Deserialize stream data as BSON documents.
 *
 * @param data - the buffer containing the serialized set of BSON documents.
 * @param startIndex - the start index in the data Buffer where the deserialization is to start.
 * @param numberOfDocuments - number of documents to deserialize.
 * @param documents - an array where to store the deserialized documents.
 * @param docStartIndex - the index in the documents array from where to start inserting documents.
 * @param options - additional options used for the deserialization.
 * @returns next index in the buffer after deserialization **x** numbers of documents.
 * @public
 */
function deserializeStream(data: Buffer | ArrayBufferView | ArrayBuffer, startIndex: number, numberOfDocuments: number, documents: Document[], docStartIndex: number, options: DeserializeOptions): number;
```

---
_Source: https://npm.io/package/bson-ext · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._