DeepBase MongoDB Driver

3.6.9 verified Sat May 09 auth: no javascript

MongoDB driver for DeepBase, a reactive nested-object database. Version 3.6.9 is the latest stable release. It stores DeepBase data in MongoDB collections using upsert logic, supports atomic $inc/$dec operations, dot-notation nested updates, and multi-driver setups (e.g., MongoDB primary with JSON backup). Requires the deepbase package as a peer dependency. Well-suited for production applications needing scalability and complex queries, with TypeScript types included.

Common errors

error Error: Cannot find module 'deepbase' ↓

cause Missing peer dependency deepbase is not installed.

fix

Run: npm install deepbase

error MongoDB connection error: MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017 ↓

cause MongoDB server is not running or not accessible at the given URL.

fix

Start MongoDB or adjust the url option. For local development: docker run -d -p 27017:27017 --name mongodb mongodb/mongodb-community-server:latest

error TypeError: MongoDriver is not a constructor ↓

cause CommonJS require without .default on ESM-only package.

fix

Use: const MongoDriver = require('deepbase-mongodb').default;

error Error: Invalid scheme, expected mongodb or mongodb+srv ↓

cause The url option is missing or has an unsupported protocol.

fix

Provide a valid MongoDB connection string starting with mongodb:// or mongodb+srv://

Warnings

breaking The package switched to ESM-only in v3.0.0. Older CommonJS require() patterns no longer work without .default. ↓

fix Use import MongoDriver from 'deepbase-mongodb' for ESM, or const MongoDriver = require('deepbase-mongodb').default for CJS.

deprecated Using collection option without also setting database may lead to unexpected defaults in future versions. ↓

fix Always provide both database and collection options explicitly.

gotcha The driver uses upsert by default for set operations. If a key is missing, it creates a new document. This can accidentally overwrite data if not careful. ↓

fix Verify keys before writing or use transactions/check-exists logic.

gotcha Nested operations using dot notation may conflict with MongoDB's interpretation of dots. Ensure keys do not contain dots to avoid unexpected document structure. ↓

fix Avoid dots in key names, or escape them if necessary.

breaking The base/database option was renamed to database in v2.0.0. The old base option is no longer supported. ↓

fix Use database: 'myapp' instead of base: 'myapp'.

Install

npm install deepbase-mongodb

yarn add deepbase-mongodb

pnpm add deepbase-mongodb

Imports

MongoDriver

wrong

import { MongoDriver } from 'deepbase-mongodb';

correct

import MongoDriver from 'deepbase-mongodb';

Default export only; named export will be undefined at runtime.

MongoDriver

wrong

const MongoDriver = require('deepbase-mongodb');

correct

const MongoDriver = require('deepbase-mongodb').default;

CommonJS requires accessing the .default property because the package is ESM-first.

DeepBase
wrong
```
import DeepBase from 'deepbase-mongodb';
```
correct
```
import DeepBase from 'deepbase';
```
DeepBase is the core package, not part of this driver. Both packages are needed.

Quickstart

Shows how to instantiate DeepBase with the MongoDriver, connect to MongoDB, and perform basic get/set operations.

import DeepBase from 'deepbase';
import MongoDriver from 'deepbase-mongodb';

const db = new DeepBase(new MongoDriver({
  url: process.env.MONGO_URL ?? 'mongodb://localhost:27017',
  database: 'myapp',
  collection: 'documents'
}));

await db.connect();

await db.set('users', 'alice', { name: 'Alice', age: 30 });
const alice = await db.get('users', 'alice');
console.log('Alice:', alice);