Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mpaland/bsonfy
Ultrafast BSON typescript serializer and parser
https://github.com/mpaland/bsonfy
bson bson-format deserializer json parser serializer typescript
Last synced: 2 months ago
JSON representation
Ultrafast BSON typescript serializer and parser
- Host: GitHub
- URL: https://github.com/mpaland/bsonfy
- Owner: mpaland
- License: mit
- Created: 2016-07-08T15:14:33.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-01-12T23:55:21.000Z (about 3 years ago)
- Last Synced: 2023-08-01T19:17:45.589Z (over 1 year ago)
- Topics: bson, bson-format, deserializer, json, parser, serializer, typescript
- Language: TypeScript
- Homepage:
- Size: 20.5 KB
- Stars: 16
- Watchers: 3
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# bsonfy - ultrafast BSON parser
[](https://www.npmjs.com/package/bsonfy)
[](https://www.npmjs.com/package/bsonfy)
[](http://github.com/mpaland/bsonfy/issues)
[](https://github.com/mpaland/bsonfy/releases)
[](https://raw.githubusercontent.com/mpaland/mipher/master/LICENSE)
**bsonfy** is an ultrafast serializer and deserializer for the [BSON](http://bsonspec.org) format.
It is written in clean typescript and has no other lib dependencies.
BSON is mainly used as compact transport format for (JSON) objects.
### Motivation
I needed a simple, fast and clean (typescript) module to generate and parse BSON for storing JSON objects in files efficiently.
There are some parsers around (2016/06), mainly the primary one of the mongodb project. But I found that it's really not lightweight enough and too slow for mobile usage.
A further requirement was using typed arrays (`Uint8Array`) instead of nodejs buffers, to get this baby portable and running in browsers, too.
### Design goals:
- Written in typescript
- Fast and lightweight parser
- Very easy to use, just one include module, NO dependencies
- tslint warning free, clean code
- Unit tested, around 50 passing test cases
- Rocksolid (I hope so)
- MIT license
## Usage
Using this module is rather simple. Copy or (npm) install *bsonfy* to your project and use it like:
```typescript
import { BSON } from 'bsonfy';
// create a test document
let doc = { id: 10, time: new BSON.UTC(), arr: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]) };
// serialize the document
let bson = BSON.serialize(doc);
// and deserialize it, using BSON.UTC objects as time representation
let orig = BSON.deserialize(bson, true);
```
## API
Basically the API consists of just two static methods to serialize/deserialize objects to/from BSON format:
### BSON serialization and deserialiation
**`BSON.serialize(object)`**
* @param {Object} object The Javascript object to serialize
* @return {Uint8Array} returns an Uint8Array in BSON format.
Unknown objects are ignored in serialization.
**`BSON.deserialize(buffer, useUTC)`**
* @param {Uint8Array} buffer An Uint8Array containing the BSON data
* @param {Boolean} useUTC Optional, if set a `BSON.UTC` object is created for 'UTC datetime' instead of a normal JS `Date` object. Defaults to false
* @return {Object} returns the deserialized Javascript object or `undefined` in case of a parsing error (unsupported BSON element etc.)
### UTC
**`bson.ObjectId.isValid(id)`** - Returns true if `id` is a valid number or hexadecimal string representing an ObjectId.
**`bson.ObjectId.createFromHexString(hexString)`** - Returns the ObjectId the `hexString` represents.
**`bson.ObjectId.createFromTime(time)`** - Returns an ObjectId containing the passed time.
* `time` - A Unix timestamp (number of seconds since the epoch).
### UUID
**`bson.ObjectId.isValid(id)`** - Returns true if `id` is a valid number or hexadecimal string representing an ObjectId.
**`bson.ObjectId.createFromHexString(hexString)`** - Returns the ObjectId the `hexString` represents.
**`bson.ObjectId.createFromTime(time)`** - Returns an ObjectId containing the passed time.
* `time` - A Unix timestamp (number of seconds since the epoch).
### ObjectId
**`bson.ObjectId.isValid(id)`** - Returns true if `id` is a valid number or hexadecimal string representing an ObjectId.
**`bson.ObjectId.createFromHexString(hexString)`** - Returns the ObjectId the `hexString` represents.
**`bson.ObjectId.createFromTime(time)`** - Returns an ObjectId containing the passed time.
* `time` - A Unix timestamp (number of seconds since the epoch).
### Unsupported elements
The following BSON elements are currently not supported (and lead to a deserialiation error):
- JavaScript code
- Min key
- Max key
- Regular expression (implemented, but untested yet - so don't rely on it)
## Caveats
- 64-bit integer BSON values are converted to the Javascript Number type.
However, Javascript supports integer precision up to 2^53 as maximum size.
If a parsed 64-bit integer exceeds this size, floating point rounding errors may occur!
## Test suite
bsonfy is using the mocha test suite for testing.
To do all tests just run `npm run test`.
## Contributing
If you find any bugs, have any comments, improvements or suggestions:
1. Create an issue and describe your idea
2. [Fork it](https://github.com/mpaland/bsonfy/fork)
3. Create your feature branch (`git checkout -b my-new-feature`)
4. Commit your changes (`git commit -am 'Add some feature'`)
5. Publish the branch (`git push origin my-new-feature`)
6. Create a new pull request
7. Profit! :white_check_mark:
## License
bsonfy is written under the [MIT license](http://www.opensource.org/licenses/MIT).