Compatibility

Mondel version: 0.3.x

Upgrading Mondel versions

From → To	Guide
0.2.x → 0.3.x	Upgrade from 0.2 to 0.3 — API stability, behavior matrix, checklist

0.3 vs 0.2 in one line: public API preserved; not bit-for-bit identical behavior (defaults on create, $set validation in strict, timestamps: false fix, soft: true now honored).

Matrix

Layer	Supported	Notes
MongoDB server	6.0, 7.0, 8.0–8.x	CRUD, indexes, JSON Schema validators
Node.js	≥ 18	≥ 20 recommended when using mongodb@7
mongodb driver (peer)	^6.0.0 || ^7.0.0	Re-export ObjectId from the same peer
zod (peer)	^3.24.0 || ^4.0.0	Both major lines supported
TypeScript	5.x recommended	strict improves inference
Runtimes	Node, Workers, Edge*	Needs a working MongoDB driver stack / Atlas

* Edge depends on your bundler and Atlas connectivity (TCP). Prefer official Atlas + Workers guidance.

MongoDB 8

Mondel does not require a special build for MongoDB 8. It uses stable driver APIs.

App-level behaviors to know when your cluster moves to 8:

Change	Impact
null equality no longer matches undefined	Filters like { field: null } may return fewer docs if you stored JS undefined historically
Stricter geospatial input	Invalid GeoJSON fails instead of soft-accepting
"majority" write concern ack timing	Faster ack (oplog majority); rarely app-breaking
Direct shard connections restricted	Always connect via mongos / Atlas SRV URI

None of these require Mondel API changes. See MongoDB’s 8.0 compatibility notes.

Driver 6 vs 7

	Driver 6	Driver 7
Mondel peer	Yes	Yes
Node floor (driver)	16+ historically	20+ (driver 7 dropped 16/18)
BSON	6.x	7.x — use Mondel’s ObjectId re-export

import { ObjectId } from "mondel"; // same BSON as your mongodb peer

What Mondel does not claim

• Full Prisma-level relation API
• Automatic schema migrations of data
• Perfect TypeScript narrowing on every select
• Built-in connection pooler for massive serverless fan-out (use Atlas limits + driver options)

Versioning policy

• Minor (0.3 → 0.4): additive APIs, docs, and fixes that preserve existing method signatures. Behavior may still change when fixing bugs or aligning with documented intent (see upgrade guides).
• Major (1.0): intentional breaks (stricter types by default, removed deprecated syncIndexes, etc.)

We do not claim “100% bit-compatible” across minors when a fix corrects incorrect prior behavior. We do claim stable public API names and shapes unless marked major.

See CHANGELOG.