@perryts/mongodb

Pure-TypeScript MongoDB wire-protocol driver. Runs on Node.js 22+ and Bun, and compiles to a native binary via Perry (LLVM AOT). Zero runtime dependencies — BSON, OP_MSG framing, SCRAM auth, TLS, SDAM, transactions, change streams, and GridFS are all implemented in hand-written TypeScript.

Install

npm install @perryts/mongodb
# or
bun add @perryts/mongodb

Usage

import { MongoClient, ObjectId } from '@perryts/mongodb';

const client = await MongoClient.connect(
  'mongodb+srv://user:[email protected]/app',
);
const users = client.db('app').collection('users');

// High-level CRUD helpers
const doc = await users.findOne({ _id: new ObjectId(id) });
await users.insertMany([{ name: 'alice' }, { name: 'bob' }]);
await users.updateOne({ name: 'alice' }, { $set: { active: true } });

// Low-level: any MongoDB command, wire-format passthrough
const res = await client.db('app').command({
  find: 'users',
  filter: { status: 'active' },
  limit: 10,
});

// Sessions + transactions
const session = client.startSession();
await session.withTransaction(async () => {
  await users.updateOne({ _id: a }, { $inc: { balance: -100 } }, { session });
  await users.updateOne({ _id: b }, { $inc: { balance:  100 } }, { session });
});

// Change streams
for await (const change of users.watch()) {
  console.log(change.operationType, change.fullDocument);
}

await client.close();

Compared to the official mongodb driver

• Pure TypeScript, zero runtime deps. No bson, no mongodb-connection-string-url, no native addons.
• Perry AOT compilable. Same source compiles to a static native binary via the Perry toolchain.
• Runs on Node 22+ and Bun. No fallback shims.
• MongoDB 5.0+ only. OP_MSG wire protocol only; no OP_QUERY.
• No CSFLE (client-side field level encryption). Deferred until a pure-TS mongocrypt replacement exists.
• No zstd/snappy compression. zlib only (OP_COMPRESSED).

Benchmarks

10 operations, the same MongoDB 7.0 instance over loopback, mongo's official sample_mflix / sample_analytics / sample_training fixtures. Every cell verifies cross-driver equivalence by hashing the first iteration's result — all 7 cells produced byte-identical results across all 10 operations.

Latency, mean ms / op (lower is better):

| op | bun mongodb | bun mongoose | bun perryts | node mongodb | node mongoose | node perryts | perry-aot perryts | |---|---:|---:|---:|---:|---:|---:|---:| | findOne_by_id_movie | 0.70 | 0.46 | 0.35 | 0.35 | 0.52 | 0.26 | 0.24 | | find_movies sort+limit_50 | 12.05 | 10.35 | 9.10 | 10.46 | 10.49 | 8.63 | 8.49 | | count_grades_score_gte_80 | 35.25 | 35.08 | 29.55 | 34.61 | 32.59 | 28.80 | 28.62 | | distinct_movies_genres_year_2000 | 8.14 | 7.85 | 6.78 | 7.22 | 10.17 | 6.76 | 6.60 | | aggregate_lookup_customer | 0.85 | 1.31 | 0.81 | 0.94 | 1.33 | 0.65 | 0.63 | | aggregate_movies_group_by_year | 14.24 | 13.38 | 11.19 | 13.84 | 15.50 | 10.93 | 11.45 | | cursor_all_zips (~30k docs) | 83.58 | 82.13 | 80.71 | 72.60 | 97.68 | 92.57 | n/a | | insertMany_1000 | 7.07 | 9.69 | 8.69 | 7.75 | 8.69 | 7.23 | 39.00 | | updateMany_inc_touches | 35.93 | 38.30 | 28.65 | 40.23 | 34.89 | 29.34 | 28.20 | | deleteMany_1000 | 13.17 | 15.87 | 10.25 | 16.08 | 11.14 | 10.55 | 66.90 |

@perryts/mongodb is the fastest (or tied-fastest) driver on 8 of 9 applicable ops under Bun and Node, and on 5 of 9 under Perry-AOT. The remaining gap is on bulk-write paths under Perry-AOT (insertMany_1000, deleteMany_1000) — these are slower than the official C-extension driver because Perry-AOT's per-method-call dispatch on BufferWriter primitives is currently ~10× heavier than V8's IC-cached path. That's a Perry codegen concern, not an algorithmic one; the same source under Bun and Node clears the official driver on the same workload.

cursor_all_zips is intentionally skipped on Perry-AOT — the ~30k-document sequential getMore chain currently runs on a 1ms-resolution clock there, which produces noisy quantized samples. It will be brought back when Perry exposes performance.now() or process.hrtime.

The full harness — three runtimes × three drivers × ten operations, with cross-cell result verification — lives in bench/. To reproduce locally:

mongosh   # mongo://127.0.0.1:27017 with sample_mflix / sample_analytics / sample_training loaded
cd bench && bash scripts/matrix.sh
bun run summarize.ts

License

MIT