Registry / database / mongo-unit-of-work

mongo-unit-of-work

library3.0.0jsnpmunverified

A TypeScript library providing MongoDB repositories with a unit-of-work abstraction for transaction-scoped operations. Current stable version is 3.0.0, released on an active cadence. It wraps the MongoDB Node.js driver (7.x) and offers BaseRepository with CRUD methods, pagination, aggregation, and audit fields via AuditableRepository. Key differentiators include first-class transaction support without boilerplate, per-repository transaction opt-out, structured logging, and an event emitter for change notifications. Requires Node.js >=20.19.0 and a MongoDB replica set or sharded cluster for transactions.

database

npm install mongo-unit-of-work

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-UNIT-OF-WORK

mongo-unit-of-work

databasejavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BaseRepository

✓ import { BaseRepository } from 'mongo-unit-of-work'

✗ const { BaseRepository } = require('mongo-unit-of-work')

ESM-only; CJS require() will fail as package exports are not CommonJS compatible

UnitOfWork

✓ import { UnitOfWork, getFactory } from 'mongo-unit-of-work'

✗ import { unitOfWork } from 'mongo-unit-of-work'

UnitOfWork class must be capitalized; getFactory is a helper for creating repository factories

IEntity

✓ import type { IEntity } from 'mongo-unit-of-work'

✗ import { IEntity } from 'mongo-unit-of-work'

IEntity is a type-only interface; use 'import type' for type erasure in production code

Demonstrates a complete workflow: connect, create repositories, add a document, commit, and clean up.

import { MongoClient } from 'mongodb'; import { BaseRepository, IEntity, UnitOfWork, getFactory } from 'mongo-unit-of-work'; interface User extends IEntity { email: string; } const client = new MongoClient(process.env.MONGODB_URI ?? ''); await client.connect(); const db = client.db('test'); const repositories = { users: (name: string, _client: MongoClient, session: any) => new BaseRepository<User>(name, db.collection<User>('users'), session), }; const uow = new UnitOfWork(client, getFactory(repositories)); const users = uow.getRepository<User>('users'); await users.add({ _id: 'user-1', email: 'user@example.com' }); await uow.commit(); await uow.dispose(); await client.close();

Debug

Known issues

breakingRequires Node.js >=20.19.0

fix

Upgrade Node.js to version 20.19.0 or later

affects: <3.0.0

breakingPeer dependency mongodb driver 7.x only; not compatible with mongodb 5.x or 6.x

fix

Install mongodb@^7.0.0 as a dependency

affects: >=3.0.0

deprecatedconfigureLogging function is deprecated in favor of a new API (not yet documented)

fix

Check upcoming release notes or migrate to new logging API if available

affects: >=3.0.0

gotchaTransactions require a MongoDB replica set or sharded cluster; standalone servers will fail on commit()

fix

Use a replica set for development (e.g., run mongod with --replSet rs0 and initiate via rs.initiate())

affects: >=1.0.0

gotchagetFactory throws on unknown repository names at runtime

fix

Ensure all repository names passed to getRepository are defined in the factory object

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'mongo-unit-of-work'

Package not installed or not included in dependencies

fix

Run 'npm install mongo-unit-of-work mongodb'

TypeError: UnitOfWork is not a constructor

Mixing default and named import; or importing from wrong path

fix

Use named import: import { UnitOfWork } from 'mongo-unit-of-work'

MongoTransactionError: Transaction 2 has been committed

Calling commit() multiple times on same UnitOfWork without creating a new one

fix

Create a new UnitOfWork for each transaction scope or reset after commit/rollback

Error: Operation `users.insertOne()` buffering timed out after 10000ms

MongoDB not connected; maybe client.connect() not awaited

fix

Ensure 'await client.connect();' runs before creating UnitOfWork

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

mongodbrequiredPeer dependency for MongoDB client and types

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Zaid-AlOmari/mongo-unit-of-work ↗

packagemongo-unit-of-work ↗

homepagehttps://github.com/Zaid-AlOmari/mongo-unit-of-work#readme ↗