@opra/mongodb 1.28.4 → 1.29.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Panates
+Copyright (c) 2020-present Panates®
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,71 @@
+<div align="center">
+
+<a href="https://oprajs.com">
+  <img src="https://oprajs.com/img/opra-header-block.webp" width="880" alt="OPRA — Open Platform for Rich APIs" />
+</a>
+
 # @opra/mongodb
 
+MongoDB data service adapter for the OPRA framework
+
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
 [![CI Tests][ci-test-image]][ci-test-url]
 [![Test Coverage][coveralls-image]][coveralls-url]
 
+[🌐 Documentation](https://oprajs.com) · [🚀 Getting Started](https://oprajs.com/docs/introduction) · [📦 Packages](https://github.com/panates/opra#packages) · [💬 Issues](https://github.com/panates/opra/issues)
+
+</div>
+
+---
+
+MongoDB data service adapter for the [OPRA](https://oprajs.com) framework. Connects your MongoDB collections to OPRA's operation model — pagination, filtering, sorting, and projections work out of the box.
+
+## Features
+
+- **`MongoService`** — Base service with MongoClient or database integration and transaction support
+- **`MongoCollectionService`** — Ready-made CRUD service for a MongoDB collection
+- **`MongoEntityService`** — Entity-level service for single-document operations
+- **`MongoAdapter`** — Utility namespace: `prepareFilter()`, `prepareSort()`, `prepareProjection()`, `prepareKeyValues()`
+- Automatic translation of OPRA filter DSL to MongoDB query objects
+- ObjectId handling and schema-aware field projection
+
+## Installation
 
-## Support
-You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+```bash
+npm install @opra/mongodb
+```
+
+## Usage
+
+```typescript
+import { MongoCollectionService } from '@opra/mongodb';
+
+@HttpController({ path: 'users' })
+export class UsersController extends MongoCollectionService<User> {
+  constructor(db: Db) {
+    super(User, db.collection('users'));
+  }
+
+  @HttpOperation.Entity.FindMany({ type: User })
+  findMany() {
+    return super.findMany();
+  }
+
+  @HttpOperation.Entity.GetOne({ type: User })
+  @HttpOperation.PathParam('id', 'objectId')
+  getOne(id: ObjectId) {
+    return super.getOne(id);
+  }
+}
+```
 
 ## Node Compatibility
-- node >= 20.x
 
+- node >= 20.x
 
 ## License
+
 Available under [MIT](LICENSE) license.
 
 [npm-image]: https://img.shields.io/npm/v/@opra/mongodb

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@opra/mongodb",
-  "version": "1.28.4",
+  "version": "1.29.0",
   "description": "Opra MongoDB adapter package",
   "author": "Panates",
   "license": "MIT",
+  "homepage": "https://www.oprajs.com",
   "dependencies": {
-    "@jsopen/objects": "^2.2.2",
+    "@jsopen/objects": "^2.2.3",
     "tslib": "^2.8.1",
-    "valgen": "^6.2.0"
+    "valgen": "^6.2.2"
   },
   "peerDependencies": {
-    "@opra/common": "^1.28.4",
-    "@opra/core": "^1.28.4",
-    "@opra/http": "^1.28.4",
+    "@opra/common": "^1.29.0",
+    "@opra/core": "^1.29.0",
+    "@opra/http": "^1.29.0",
     "mongodb": "^7.0.0"
   },
   "exports": {

package/services/mongo-service.d.ts

@@ -1,6 +1,6 @@
 import { ComplexType } from '@opra/common';
 import { ExecutionContext, ServiceBase } from '@opra/core';
-import mongodb, { ClientSession, type Document, type TransactionOptions } from 'mongodb';
+import mongodb, { ClientSession, type Document, MongoClient, type TransactionOptions } from 'mongodb';
 import type { Nullish, StrictOmit, Type } from 'ts-gems';
 import type { vg } from 'valgen';
 import { MongoAdapter } from '../adapter/mongo-adapter.js';
@@ -270,6 +270,13 @@ export declare class MongoService<T extends mongodb.Document = mongodb.Document>
      * @throws {@link Error} If the context or database is not set.
      */
     protected getDatabase(): mongodb.Db;
+    /**
+     * Retrieves the MongoClient.
+     *
+     * @protected
+     * @throws {@link Error} If the context or database is not set.
+     */
+    protected getDBClient(): MongoClient;
     /**
      * Retrieves the database session.
      *

package/services/mongo-service.js

@@ -2,7 +2,8 @@ import { ComplexType, DataType, DATATYPE_METADATA } from '@opra/common';
 import { ExecutionContext, ServiceBase } from '@opra/core';
 import mongodb, { ClientSession, MongoClient, ObjectId, } from 'mongodb';
 import { MongoAdapter } from '../adapter/mongo-adapter.js';
-const transactionKey = Symbol.for('transaction');
+const dbInstanceKey = Symbol.for('db-instance');
+const dbSessionKey = Symbol.for('db-session');
 /**
  * Class representing a MongoDB service for interacting with a collection.
  * @extends ServiceBase
@@ -143,21 +144,13 @@ export class MongoService extends ServiceBase {
     async withTransaction(callback, options) {
         const ctx = this.context;
         let closeSessionOnFinish = false;
-        let transaction = ctx[transactionKey];
-        let session;
-        if (transaction) {
-            session = transaction.session;
-        }
-        else {
-            const db = this.getDatabase();
-            const client = db.client;
+        const dbInstance = this.getDatabase();
+        let session = this.getSession();
+        if (!session) {
+            const client = dbInstance.client;
             session = client.startSession();
+            ctx[dbSessionKey] = session;
             closeSessionOnFinish = true;
-            transaction = {
-                db,
-                session,
-            };
-            ctx[transactionKey] = transaction;
         }
         const oldInTransaction = session.inTransaction();
         try {
@@ -174,7 +167,8 @@ export class MongoService extends ServiceBase {
             throw e;
         }
         finally {
-            delete ctx[transactionKey];
+            delete ctx[dbInstanceKey];
+            delete ctx[dbSessionKey];
             if (closeSessionOnFinish) {
                 await session.endSession();
             }
@@ -188,14 +182,28 @@ export class MongoService extends ServiceBase {
      */
     getDatabase() {
         const ctx = this.context;
-        const transaction = ctx[transactionKey];
-        if (transaction)
-            return transaction.db;
-        const db = typeof this.db === 'function' ? this.db(this) : this.db;
-        if (db)
-            return db;
+        let dbInstance = ctx[dbInstanceKey] || ctx.bundle?.[dbInstanceKey];
+        if (dbInstance)
+            return dbInstance;
+        dbInstance = typeof this.db === 'function' ? this.db(this) : this.db;
+        if (dbInstance) {
+            if (ctx.bundle?.transaction) {
+                ctx.bundle[dbInstanceKey] = dbInstance;
+            }
+            return dbInstance;
+        }
         throw new Error(`Database not set!`);
     }
+    /**
+     * Retrieves the MongoClient.
+     *
+     * @protected
+     * @throws {@link Error} If the context or database is not set.
+     */
+    getDBClient() {
+        const dbInstance = this.getDatabase();
+        return dbInstance.client;
+    }
     /**
      * Retrieves the database session.
      *
@@ -204,12 +212,36 @@ export class MongoService extends ServiceBase {
      */
     getSession() {
         const ctx = this.context;
-        const transaction = ctx[transactionKey];
-        if (transaction)
-            return transaction.session;
-        const session = typeof this.session === 'function' ? this.session(this) : this.session;
+        let session = ctx[dbSessionKey] || ctx.bundle?.[dbSessionKey];
+        if (session)
+            return session;
+        session =
+            typeof this.session === 'function' ? this.session(this) : this.session;
         if (session)
             return session;
+        if (ctx.bundle?.transaction) {
+            const dbInstance = this.getDatabase();
+            const client = dbInstance.client;
+            session = client.startSession();
+            ctx.bundle[dbSessionKey] = session;
+            /* Commit or Rollback transaction after executed */
+            ctx.bundle.on('after-execute', async () => {
+                try {
+                    if (session.inTransaction()) {
+                        if (ctx.bundle.success)
+                            await session.commitTransaction();
+                        else
+                            await session.abortTransaction();
+                    }
+                }
+                finally {
+                    delete ctx.bundle[dbInstanceKey];
+                    delete ctx.bundle[dbSessionKey];
+                    await session.endSession();
+                }
+            });
+        }
+        return session;
     }
     /**
      * Retrieves a MongoDB collection from the given database.