/elixir-bson

BSON documents in Elixir language

Primary LanguageElixirMIT LicenseMIT

elixir-bson

Build Status Hex Version Hex Downloads

WARNING: this project is outdated, please use https://hex.pm/packages/cyanide or https://hex.pm/packages/cbson instead

BSON implementation for Elixir Language

elixir-bson on GitHub source repo - documentation

BSON is a binary format in which zero or more key/value pairs are stored as a single entity, called a document. It is a data type with a standard binary representation defined at http://www.bsonspec.org.

This implements version 1.0 of that spec.

This project is used by elixir-mongo, a MongoDB driver in Elixir.

This implementation maps the Bson grammar with Elixir terms in the following way:

  • document: Map, HasDict, Keyword
  • int32 and int64: Integer
  • double: Float
  • string: String
  • Array: List (non-keyword)
  • binary: Bson.Bin (struct)
  • ObjectId: Bson.ObjectId (struct)
  • Boolean: true or false (Atom)
  • UTC datetime: Bson.UTC (struct)
  • Null value: nil (Atom)
  • Regular expression: Bson.Regex (struct)
  • JavaScript: Bson.JS (struct)
  • Timestamp: Bson.Timestamp (struct)
  • Min and Max key: MIN_KEY or MAX_KEY (Atom)

This is how to encode a sample Elixir Map into a Bson Document:

bson = Bson.encode %{a: 1, b: "2", c: [1,2,3], d: %{d1: 10, d2: 11} }

In this case, bson would be a document with 4 elements (an Integer, a String, an Array and an embeded document). This document would correspond in Javascript to:

{a: 1, b: "2", c: [1,2,3], d: {d1: 10, d2: 11} }

Conversly, to decode a bson document:

%{a: 1} == Bson.decode <<12, 0, 0, 0, 16, 97, 0, 1, 0, 0, 0, 0>>

Special Bson element that do not have obvious corresponding type in Elixir are represented with Record, for example:

jsbson = Bson.encode js: %Bson.JS{code:"function(a) return a+b;", scope: [b: 2]}
rebson = Bson.encode re: %Bson.Regex{pattern: "\d*", opts: "g"}

Some configuration can be done using fun or protocol implementation, ie, it is possible to redefine encoder end decoder of Bson.Bin to implement specific encoding. For that you can set Application envir for application :bson. Two options are available: :decoder_new_doc defaulted to Bson.Decoder.elist_to_atom_map/1 and :decoder_new_bin defaulted to &Bson.Bin.new/2.