@objectstack/driver-mongodb

MongoDB driver for ObjectStack — native document database support via the official MongoDB Node.js driver.

Installation

pnpm add @objectstack/driver-mongodb mongodb

Configuration

Option A — Env vars (recommended for objectstack dev / objectstack serve)

export OS_DATABASE_URL=mongodb://localhost:27017/myapp
pnpm dev

The ObjectStack CLI auto-registers this driver when OS_DATABASE_URL starts with mongodb:// or mongodb+srv://. You do not need to set OS_DATABASE_DRIVER separately — the URL scheme is enough. Set it only as an explicit override (recognised values: mongodb, mongo).

Option B — Programmatic via defineStack

import { defineStack } from '@objectstack/spec';
import { MongoDBDriver } from '@objectstack/driver-mongodb';

export default defineStack({
  driver: new MongoDBDriver({
    url: 'mongodb://localhost:27017/myapp',
    database: 'myapp',        // Optional: overrides URI database
    maxPoolSize: 10,          // Optional: connection pool size (default: 10)
    minPoolSize: 1,           // Optional: minimum pool (default: 1)
    connectTimeoutMS: 10000,  // Optional: connection timeout
  }),
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string | required | MongoDB connection URI | | database | string | from URI | Database name | | maxPoolSize | number | 10 | Max connection pool size | | minPoolSize | number | 1 | Min connection pool size | | connectTimeoutMS | number | 10000 | Connection timeout (ms) | | serverSelectionTimeoutMS | number | 5000 | Server selection timeout (ms) | | options | MongoClientOptions | {} | Additional MongoClient options |

Features

Capabilities

| Category | Capability | Supported | |----------|-----------|-----------| | CRUD | create, read, update, delete | ✅ | | Bulk | bulkCreate, bulkUpdate, bulkDelete | ✅ | | Query | filters, sorting, pagination, aggregations | ✅ | | Transactions | Multi-document transactions | ✅ (requires replica set) | | Streaming | Cursor-based async iteration | ✅ | | Schema | Collection + index sync | ✅ | | Advanced | Full-text search, JSON queries, geospatial | ✅ | | Joins | Cross-collection joins ($lookup) | ❌ | | Window Functions | ROW_NUMBER, RANK, etc. | ❌ |

ID Handling

ObjectStack uses string IDs (nanoid). The driver:

• Stores id as a regular string field with a unique index
• Auto-generates id via nanoid if not provided
• Never exposes MongoDB's internal _id field in results

Filter Operators

All ObjectStack filter operators are supported:

// MongoDB-style filters (pass-through)
await driver.find('task', {
  where: {
    status: { $in: ['active', 'pending'] },
    priority: { $gte: 3 },
    title: { $contains: 'urgent' },
    deleted_at: { $null: true },
  }
});

// Legacy array-style filters
await driver.find('task', {
  where: [['status', '=', 'active'], 'or', ['priority', '>=', 5]]
});

Transactions

Transactions require a MongoDB replica set (including single-node replica sets for development).

const session = await driver.beginTransaction();
try {
  await driver.create('order', { total: 100 }, { transaction: session });
  await driver.update('inventory', itemId, { stock: newStock }, { transaction: session });
  await driver.commit(session);
} catch (error) {
  await driver.rollback(session);
  throw error;
}

Schema Sync

Schema sync creates collections and indexes:

await driver.syncSchema('account', {
  name: 'account',
  fields: {
    name: { type: 'string', unique: true },
    email: { type: 'email', indexed: true },
    company_id: { type: 'lookup', reference_to: 'company' },
  },
});
// Creates: idx_id_unique, idx_name_unique, idx_email, idx_company_id_lookup

Aggregation

const results = await driver.aggregate('order', {
  where: { status: 'completed' },
  aggregations: [
    { function: 'sum', field: 'amount', alias: 'total_revenue' },
    { function: 'count', alias: 'order_count' },
  ],
  groupBy: ['region'],
});

Plugin Usage

Register as an ObjectStack plugin:

import mongodbPlugin from '@objectstack/driver-mongodb';

// The plugin registers automatically via onEnable
kernel.use(mongodbPlugin, {
  url: 'mongodb://localhost:27017/myapp',
});

Development

# Run tests
pnpm test

# Build
pnpm build

License

Apache-2.0