1. Docs
  2. Packages

@samveys/mongodb

Version
1.0.2Nov 5, 2026
Install
pnpm add @samveys/mongodb

From packages/mongodb/README.md in the framework repository.

A typed document ODM for MongoDB. It is separate from @samveys/database (SQL only) and mirrors the ORM's ergonomics. The official mongodb driver is imported lazily inside connect().

Define a document

ts
import { defineDocument, field } from '@samveys/mongodb'

export const Users = defineDocument('users', {
  email: field.string().unique(),
  name: field.string(),
  age: field.int().optional(),
  tags: field.array(field.string()),
  createdAt: field.date().autoCreate(),
})

Connect and query

ts
import { createMongoManager } from '@samveys/mongodb'
import { Users } from './users.ts'

const manager = createMongoManager({ url: 'mongodb://127.0.0.1:27017/?replicaSet=rs0', database: 'app' })
await manager.connect()

const users = manager.model(Users)
await users.syncIndexes() // creates unique indexes; safe to repeat

const ann = await users.create({ email: 'ann@example.test', name: 'Ann', tags: ['admin'] })
const same = await users.findOrFail(ann.id) // ids are ObjectId hex strings

const adults = await users.query().where('age', '>', 30).orderBy('age', 'desc').limit(10).get()
const page = await users.query().where('tags', 'admin').paginate(1, 15)
const total: number = page.total

Transactions

Transactions need a replica set.

ts
import { createMongoManager } from '@samveys/mongodb'
import { Users } from './users.ts'

const manager = createMongoManager({ url: 'mongodb://127.0.0.1:27017/?replicaSet=rs0', database: 'app' })
const users = manager.model(Users)

await manager.transaction(async (session) => {
  await users.create({ email: 'tx@example.test', name: 'Tx', tags: [] }, { session })
})

Safety

  • Unknown fields are rejected on create and update (no mass assignment).
  • Values are type-checked against the schema. An object such as { $ne: null } is never interpreted as an operator and is refused.
  • Field names starting with $ or containing . are refused.
  • A unique violation becomes SVS_E083 (422) with a #/body/<field> pointer; a missing document is SVS_E073 (404).

Plugin

ts
import { mongo } from '@samveys/mongodb'

// app.use(mongo({ url, database })) binds 'mongo' and closes the client on app:terminating.