@nimbus-cqrs/mongodb 2.0.0-beta.0

package/esm/lib/repository.js

@@ -0,0 +1,235 @@
+import { NotFoundException } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { toSnakeCase } from '../deps/jsr.io/@std/text/1.0.18/mod.js';
+import { ObjectId } from 'mongodb';
+import { bulkWrite } from './crud/bulkWrite.js';
+import { countDocuments } from './crud/countDocuments.js';
+import { deleteMany } from './crud/deleteMany.js';
+import { deleteOne } from './crud/deleteOne.js';
+import { find } from './crud/find.js';
+import { findOne } from './crud/findOne.js';
+import { insertMany } from './crud/insertMany.js';
+import { insertOne } from './crud/insertOne.js';
+import { replaceOne } from './crud/replaceOne.js';
+/**
+ * Repository for interacting with a MongoDB Collection
+ * which provides a type-safe interface for MongoDB CRUD operations.
+ *
+ * Why do we not implement a generic repository interface?
+ *
+ * Implementing a generic repository interface is incredibly difficult in terms of
+ * mapping filter patterns to the Database without the user having to change a
+ * filter input when switching databases in the background.
+ *
+ * So we feel it is better to make the underlying data store obvious to the user
+ * and give the user a way to interact with the repository in a way that feels
+ * natural to the underlying data store.
+ *
+ * @param collection - MongoDB Collection instance
+ * @param entityType - Zod type for validating the data and ensure type safety
+ * @param entityName - Name for the entity, e.g. used in error messages like "Entity not found"
+ *
+ * @example
+ * ```ts
+ * import { MongoDBRepository } from '@nimbus/mongodb';
+ * import { getEnv } from '@nimbus/utils';
+ * import { mongoClient } from './mongoDBClient.ts';
+ * import { User } from './user.type.ts';
+ * import { USER_COLLECTION } from './user.collection.ts';
+ *
+ * class UserRepository extends MongoDBRepository<User> {
+ *   constructor() {
+ *     const env = getEnv({ variables: ['MONGO_DB'] });
+ *
+ *     super(
+ *       mongoClient.db(env.MONGO_DB).collection(USER_COLLECTION.name),
+ *       User,
+ *     );
+ *   }
+ *
+ *   override _mapDocumentToEntity(doc: Document): User {
+ *     return User.parse({
+ *       _id: doc._id.toString(),
+ *       email: doc.email,
+ *     });
+ *   }
+ *
+ *   override _mapEntityToDocument(user: User): Document {
+ *     return {
+ *       _id: new ObjectId(user._id),
+ *       email: user.email,
+ *     };
+ *   }
+ * }
+ *
+ * export const userRepository = new UserRepository();
+ * ```
+ */
+export class MongoDBRepository {
+    _getCollection;
+    _entityType;
+    _entityName;
+    constructor(getCollection, entityType, entityName) {
+        this._getCollection = getCollection;
+        this._entityType = entityType;
+        this._entityName = entityName ?? 'Document';
+    }
+    /**
+     * Function to map the MongoDB Document to the Entity.
+     * ZodType.parse is used to ensure the data is valid and type-safe.
+     */
+    _mapDocumentToEntity(doc) {
+        return this._entityType.parse(doc);
+    }
+    /**
+     * Function to map the Entity to a  MongoDB Document.
+     */
+    _mapEntityToDocument(item) {
+        return item;
+    }
+    /**
+     * Find one document based on a given filter.
+     */
+    async findOne({ filter, }) {
+        try {
+            const collection = await this._getCollection();
+            const res = await findOne({
+                collection,
+                filter,
+                mapDocument: this._mapDocumentToEntity,
+                outputType: this._entityType,
+            });
+            return res;
+        }
+        catch (error) {
+            if (error.name === 'NOT_FOUND_EXCEPTION') {
+                throw new NotFoundException(`${this._entityName} not found`, {
+                    errorCode: `${toSnakeCase(this._entityName).toUpperCase()}_NOT_FOUND`,
+                    reason: `Could not find ${this._entityName} matching the given filter`,
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Find multiple documents based on a given filter.
+     */
+    async find({ filter, limit, skip, sort, project, options, }) {
+        const collection = await this._getCollection();
+        return find({
+            collection,
+            filter,
+            limit,
+            skip,
+            sort,
+            project,
+            mapDocument: this._mapDocumentToEntity,
+            outputType: this._entityType,
+            options,
+        });
+    }
+    /**
+     * Count all documents matching a given filter.
+     */
+    async countDocuments({ filter, options, }) {
+        const collection = await this._getCollection();
+        return countDocuments({
+            collection,
+            filter,
+            options,
+        });
+    }
+    /**
+     * Insert a single new document.
+     */
+    async insertOne({ item, }) {
+        const collection = await this._getCollection();
+        await insertOne({
+            collection,
+            document: this._mapEntityToDocument(item),
+        });
+        return item;
+    }
+    /**
+     * Insert multiple new documents.
+     */
+    async insertMany({ items, options, }) {
+        const collection = await this._getCollection();
+        await insertMany({
+            collection,
+            documents: items.map(this._mapEntityToDocument),
+            options,
+        });
+        return items;
+    }
+    /**
+     * Replace a single document.
+     */
+    async replaceOne({ item, options, }) {
+        const collection = await this._getCollection();
+        const res = await replaceOne({
+            collection,
+            filter: { _id: new ObjectId(item._id) },
+            replacement: this._mapEntityToDocument(item),
+            options,
+        });
+        if (res.matchedCount === 0) {
+            throw new NotFoundException(`${this._entityName} not found`, {
+                errorCode: `${toSnakeCase(this._entityName).toUpperCase()}_NOT_FOUND`,
+                reason: `Could not find ${this._entityName} with the id: ${item._id}`,
+            });
+        }
+        return item;
+    }
+    /**
+     * Replace multiple documents.
+     */
+    async replaceMany({ items, options, }) {
+        if (items.length > 0) {
+            const collection = await this._getCollection();
+            const operations = items.map((item) => ({
+                replaceOne: {
+                    filter: { _id: new ObjectId(item._id) },
+                    replacement: this._mapEntityToDocument(item),
+                },
+            }));
+            await bulkWrite({
+                collection,
+                operations: operations,
+                options,
+            });
+        }
+        return items;
+    }
+    /**
+     * Delete a single document.
+     */
+    async deleteOne({ item, options, }) {
+        const collection = await this._getCollection();
+        const res = await deleteOne({
+            collection,
+            filter: { _id: new ObjectId(item._id) },
+            options,
+        });
+        if (res.deletedCount === 0) {
+            throw new NotFoundException(`${this._entityName} not found`, {
+                errorCode: `${toSnakeCase(this._entityName).toUpperCase()}_NOT_FOUND`,
+                reason: `Could not find ${this._entityName} with the id: ${item._id}`,
+            });
+        }
+        return item;
+    }
+    /**
+     * Delete multiple documents.
+     */
+    async deleteMany({ items, options, }) {
+        const collection = await this._getCollection();
+        await deleteMany({
+            collection,
+            filter: {
+                _id: { $in: items.map((item) => new ObjectId(item._id)) },
+            },
+            options,
+        });
+        return items;
+    }
+}

package/esm/lib/tracing.d.ts

@@ -0,0 +1,17 @@
+import type { Collection, Document } from 'mongodb';
+export declare const tracer: import("@opentelemetry/api").Tracer;
+export declare const DB_SYSTEM = "mongodb";
+/**
+ * Wraps an async function with OpenTelemetry tracing and metrics.
+ *
+ * Records:
+ * - `mongodb_operation_total` counter with operation, collection, and status labels
+ * - `mongodb_operation_duration_seconds` histogram with operation and collection labels
+ *
+ * @param operation - The MongoDB operation name (e.g., 'findOne', 'insertMany')
+ * @param collection - The MongoDB collection being operated on
+ * @param fn - The async function to execute within the span
+ * @returns The result of the async function
+ */
+export declare const withSpan: <T>(operation: string, collection: Collection<Document>, fn: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=tracing.d.ts.map

package/esm/lib/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEpD,eAAO,MAAM,MAAM,qCAA4B,CAAC;AAEhD,eAAO,MAAM,SAAS,YAAY,CAAC;AAgBnC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACtB,WAAW,MAAM,EACjB,YAAY,UAAU,CAAC,QAAQ,CAAC,EAChC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KACrB,OAAO,CAAC,CAAC,CAoDX,CAAC"}

package/esm/lib/tracing.js

@@ -0,0 +1,62 @@
+import { metrics, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
+export const tracer = trace.getTracer('nimbus');
+export const DB_SYSTEM = 'mongodb';
+const meter = metrics.getMeter('nimbus');
+const operationCounter = meter.createCounter('mongodb_operation_total', {
+    description: 'Total number of MongoDB operations',
+});
+const operationDuration = meter.createHistogram('mongodb_operation_duration_seconds', {
+    description: 'Duration of MongoDB operations in seconds',
+    unit: 's',
+});
+/**
+ * Wraps an async function with OpenTelemetry tracing and metrics.
+ *
+ * Records:
+ * - `mongodb_operation_total` counter with operation, collection, and status labels
+ * - `mongodb_operation_duration_seconds` histogram with operation and collection labels
+ *
+ * @param operation - The MongoDB operation name (e.g., 'findOne', 'insertMany')
+ * @param collection - The MongoDB collection being operated on
+ * @param fn - The async function to execute within the span
+ * @returns The result of the async function
+ */
+export const withSpan = (operation, collection, fn) => {
+    const startTime = performance.now();
+    const metricLabels = {
+        operation,
+        collection: collection.collectionName,
+    };
+    return tracer.startActiveSpan(`mongodb.${operation}`, {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            'db.system': DB_SYSTEM,
+            'db.operation': operation,
+            'db.mongodb.collection': collection.collectionName,
+        },
+    }, async (span) => {
+        try {
+            const result = await fn();
+            // Record success metrics
+            operationCounter.add(1, { ...metricLabels, status: 'success' });
+            operationDuration.record((performance.now() - startTime) / 1000, metricLabels);
+            return result;
+        }
+        catch (error) {
+            // Record error metrics
+            operationCounter.add(1, { ...metricLabels, status: 'error' });
+            operationDuration.record((performance.now() - startTime) / 1000, metricLabels);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error
+                    ? error.message
+                    : 'Unknown error',
+            });
+            span.recordException(error instanceof Error ? error : new Error('Unknown error'));
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+};

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@nimbus-cqrs/mongodb",
+  "version": "2.0.0-beta.0",
+  "description": "MongoDB integration for the Nimbus CQRS framework.",
+  "author": "Daniel Gördes <d.goerdes@overlap.at> (https://overlap.at)",
+  "homepage": "https://nimbus.overlap.at",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/overlap-dev/Nimbus"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/overlap-dev/Nimbus/issues"
+  },
+  "module": "./esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js"
+    }
+  },
+  "scripts": {},
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "mongodb": "^7.1.1",
+    "zod": "^4.3.6",
+    "@nimbus-cqrs/core": "^2.0.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "_generatedBy": "dnt@dev"
+}