ebson

High-performance BSON encoder/decoder for Erlang.

Features

• Zero-copy traversal - Navigate BSON documents without decoding values
• Efficient skipping - Skip entire subtrees using BSON length prefixes
• Memory safe - All decoded values are copied to avoid retaining source binaries
• Full type support - All common BSON types including decimal128

Installation

Add to your rebar.config:

{deps, [
    {ebson, "0.1.0"}
]}.

Quick Start

Encode a map to BSON

Map = #{
    <<"_id">> => {objectid, <<1,2,3,4,5,6,7,8,9,10,11,12>>},
    <<"name">> => <<"Alice">>,
    <<"age">> => 30,
    <<"tags">> => [<<"developer">>, <<"erlang">>]
},
{ok, Bson} = ebson:encode_map(Map).

Decode BSON to a map

{ok, Map} = ebson:decode_map(Bson).

Zero-copy traversal

%% Create iterator
{ok, Iter} = ebson_iter:new(Bson),

%% Iterate elements
{ok, Key, Type, ValueRef, Iter2} = ebson_iter:next(Iter),

%% Decode only when needed
{ok, Value} = ebson_iter:decode_value(Type, ValueRef).

Direct field lookup

%% Find a top-level key
{ok, Type, ValueRef} = ebson_iter:peek(Bson, <<"name">>),
{ok, <<"Alice">>} = ebson_iter:decode_value(Type, ValueRef).

%% Navigate nested paths
{ok, Type, ValueRef} = ebson_iter:find_path(Bson, [<<"address">>, <<"city">>]).

Modules

ebson_iter

Zero-copy BSON binary iterator for hot paths. Use this when you need to:

• Filter documents without full decode
• Access specific fields efficiently
• Skip large nested structures

ebson

Convenience encode/decode for Erlang maps. Use this when you need to:

• Fully decode documents for processing
• Encode Erlang maps for storage
• Work with documents in admin tools or tests

Type Mappings

Erlang Value	BSON Type
integer (32-bit range)	int32
integer (64-bit range)	int64
float	double
binary	string (UTF-8)
true / false	boolean
null	null
map	document
list	array
{objectid, <<12 bytes>>}	objectid
{datetime_ms, Integer}	datetime
{binary, Subtype, Data}	binary
{timestamp, Increment, Time}	timestamp
{decimal128, Coeff, Exp}	decimal128
{regex, Pattern, Options}	regex
minkey / maxkey	minkey / maxkey

Memory Safety

ValueRefs from ebson_iter point into the original binary without copying. This is efficient but means the source binary stays in memory.

To release the source binary:

• Call ebson_iter:decode_value/2 which uses binary:copy/1
• Use ebson:decode_map/1 for full document decode

License

Apache-2.0