bpm

mongodb

v0.1.0 Pure bnl

MongoDB driver — pure bnl over net + tls + crypto.

@mamun MIT Published

mongodb

MongoDB driver for bnl — pure bnl, no native deps. Implements the MongoDB OP_MSG wire protocol directly over net + tls + crypto, so it runs anywhere bnl runs.

Install

bpm install mongodb

Use

import "mongodb" as mongo;

function main() {
    var client = wait mongo.connect({
        host:     "127.0.0.1",
        port:     27017,
        user:     "appuser",
        password: "secret"
    });

    var users = client.db("app").collection("users");

    var ins = wait users.insert_one({name: "Alice", age: 30});
    print("inserted:", ins.inserted_id);

    var alice = wait users.find_one({name: "Alice"});
    print("found:", alice.name, alice.age);

    var rows = wait users.find({age: {"$gte": 18}});
    print("adults:", rows.length);

    wait users.update_one({name: "Alice"}, {"$inc": {age: 1}});
    var n = wait users.count_documents({});
    print("count:", n);

    client.close();
}

main();

Every method on client / db / collection returns a Future — pair with wait.

API

mongodb.connect(uri_or_opts) → Future<client>

Accepts either a mongodb:// URI string or an opts map.

// URI form
var client = wait mongo.connect("mongodb://root:[email protected]:27017/myapp?authSource=admin");

// Opts form (equivalent)
var client = wait mongo.connect({
    host:        "127.0.0.1",
    port:        27017,
    user:        "root",
    password:    "secret",
    database:    "myapp",
    auth_source: "admin"
});

URI: mongodb://[user[:password]@]host[:port][/db][?param=value&…]

URI query param Maps to Notes
authSource auth_source falls back to the path /db if absent, then "admin"
tls / ssl ssl accepts true / 1 / yes
tlsAllowInvalidCertificates ssl_verify=false for self-signed dev servers

mongodb+srv:// (Atlas SRV discovery) is not supported in v0.1 — resolve the SRV record yourself and pass the explicit host:port. Multiple hosts (replica set) parse but only the first is used.

Opts map keys:

Key Type Default
host string "127.0.0.1"
port number 27017
user string none (omit for unauthenticated mongod)
password string none (required when user is set)
auth_source string "admin"
ssl bool false
ssl_verify bool true

Resolves to a client once the SCRAM-SHA-256 handshake completes.

client methods

Method Returns Notes
client.db(name) db namespace handle
client.run_command(db_name, cmd) Future<reply> raw command for admin / unsupported ops
client.ping() Future<reply> {ping: 1} against admin
client.server_info() map the hello reply (server version, max wire version, …)
client.close() — tear down the socket

db methods

var db = client.db("app");

Method Returns
db.collection(name) collection
db.run_command(cmd) Future<reply>
db.list_collections() Future<list of map> (firstBatch)
db.drop() Future<reply>

collection methods

var users = db.collection("users");

Method Returns Notes
insert_one(doc) Future<{inserted_id, n}> auto-generates _id ObjectId if absent
insert_many(docs) Future<{inserted_ids, n}> same
find(filter?, opts?) Future<list of map> drains the cursor (getMore loop)
find_one(filter?, opts?) Future<map | null> first match or null
update_one(filter, update) Future<{matched, modified}>
update_many(filter, update) Future<{matched, modified}>
replace_one(filter, replacement) Future<{matched, modified}>
delete_one(filter) Future<{deleted}>
delete_many(filter) Future<{deleted}>
count_documents(filter?) Future<number>
aggregate(pipeline, opts?) Future<list of map> drains the cursor
drop() Future<reply>

opts (when accepted) recognises: projection, sort, limit, skip, batch_size.

mongodb.pool(opts) → pool

Same opts as connect, plus max (default 10). Exposes:

var pool = mongo.pool({host: "...", user: "...", password: "...", max: 20});

wait pool.run(function (client) {
    return client.db("app").collection("users").insert_one({name: "x"});
});

pool.size();
pool.idle_size();
pool.close();

run(fn) acquires a client, hands it to fn, releases on settle.

Helpers

Function Returns
mongodb.new_object_id() {$oid: "<24-hex>"} ready to drop into documents
mongodb.encode_bson(doc) raw BSON bytes (mostly useful for debugging)
mongodb.decode_bson(buf, off?) [doc, end_offset]
mongodb.version() "0.1.0"

BSON value mapping

Most bnl values map naturally to BSON. Special types use a marker map convention (MongoDB Extended JSON) so they survive a round trip:

bnl BSON
null null
true / false bool
integer-valued number, |n| < 2^31 int32
integer-valued number, 2^31 ≤ |n| ≤ 2^53 - 1 int64
non-integer number double (IEEE-754 LE, encoded in pure bnl)
string utf8
map document
list array
{$oid: "<24-hex>"} ObjectId
{$date: ms} UTC datetime
{$binary: bytes, $subtype: n} binary (subtype defaults to 0)
{$regex: "...", $options: "..."} regex
{$timestamp: {t: secs, i: incr}} timestamp
{$minKey: 1} / {$maxKey: 1} MinKey / MaxKey
{$numberLong: "<digits>"} int64 (for values outside safe-int range)

Int64 values whose absolute value exceeds 2^53 - 1 are decoded as {$numberLong: "..."} so precision survives — bnl numbers are doubles.

Errors

Server errors reject with a structured map:

try {
    wait users.insert_one(...);
} catch (e) {
    if (type(e) == "map" and e.code == 11000) {
        print("duplicate key:", e.message);
    } else {
        throw e;
    }
}
Field Notes
code Mongo numeric error code (e.g. 11000 duplicate key)
codeName Symbolic name ("DuplicateKey") when sent
message Server's errmsg

Client-side errors (TCP failure, malformed BSON, etc.) reject with a string prefixed "mongo: ".

License

MIT.