@nimbus-cqrs/mongodb 2.0.0-beta.0

package/esm/lib/mongoConnectionManager.js

@@ -0,0 +1,195 @@
+import { getLogger } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { MongoClient, } from 'mongodb';
+/**
+ * Singleton wrapper around a single long-lived `MongoClient`.
+ *
+ * The MongoDB Node driver already handles connection pooling, server
+ * monitoring (SDAM), automatic reconnection, retryable reads/writes and
+ * per-socket idle eviction via `maxIdleTimeMS`. This class therefore does
+ * the minimum on top of the driver: hold one `MongoClient` for the lifetime
+ * of the application and provide typed `getDatabase` / `getCollection`
+ * convenience methods.
+ *
+ * Call {@link MongoConnectionManager#close} on graceful shutdown
+ * (e.g. on `SIGTERM` / `SIGINT`) to drain the pool.
+ *
+ * @example
+ * ```ts
+ * import { MongoConnectionManager } from '@nimbus/mongodb';
+ * import { ServerApiVersion } from 'mongodb';
+ *
+ * export const mongoManager = MongoConnectionManager.getInstance(
+ *     process.env['MONGO_URL'] ?? '',
+ *     {
+ *         appName: 'my-app',
+ *         serverApi: {
+ *             version: ServerApiVersion.v1,
+ *             strict: false,
+ *             deprecationErrors: true,
+ *         },
+ *     },
+ * );
+ *
+ * process.on('SIGTERM', () => {
+ *     mongoManager.close().catch(console.error);
+ * });
+ * ```
+ */
+export class MongoConnectionManager {
+    static _instance = null;
+    _client = null;
+    _connecting = null;
+    _uri;
+    _options;
+    /**
+     * Initialize the MongoConnectionManager.
+     *
+     * @param {string} uri - The MongoDB connection URI
+     * @param {MongoClientOptions} [options] - Options forwarded to the underlying `MongoClient`
+     */
+    constructor(uri, options) {
+        this._uri = uri;
+        this._options = options;
+    }
+    /**
+     * Get the singleton instance of the MongoConnectionManager.
+     *
+     * Subsequent calls return the existing instance and ignore the arguments.
+     *
+     * @param {string} uri - The MongoDB connection URI
+     * @param {MongoClientOptions} [options] - Options forwarded to the underlying `MongoClient`
+     *
+     * @returns {MongoConnectionManager} The singleton instance of the MongoConnectionManager
+     */
+    static getInstance(uri, options) {
+        if (!MongoConnectionManager._instance) {
+            MongoConnectionManager._instance = new MongoConnectionManager(uri, options);
+        }
+        return MongoConnectionManager._instance;
+    }
+    /**
+     * Get the connected MongoDB client.
+     *
+     * Lazily creates and connects a single `MongoClient` on the first call.
+     * Concurrent first-callers share the same in-flight `connect()` promise
+     * so only one connection is established.
+     *
+     * @returns {Promise<MongoClient>} The MongoDB client instance
+     */
+    getClient() {
+        if (this._client !== null) {
+            return Promise.resolve(this._client);
+        }
+        if (this._connecting !== null) {
+            return this._connecting;
+        }
+        this._connecting = (async () => {
+            try {
+                const client = new MongoClient(this._uri, this._options);
+                await client.connect();
+                this._client = client;
+                getLogger().info({
+                    category: 'Nimbus',
+                    message: 'MongoConnectionManager :: Successfully connected',
+                });
+                return client;
+            }
+            catch (error) {
+                getLogger().critical({
+                    category: 'Nimbus',
+                    message: 'MongoConnectionManager :: Connection failed',
+                    error: error,
+                });
+                throw error;
+            }
+        })().finally(() => {
+            this._connecting = null;
+        });
+        return this._connecting;
+    }
+    /**
+     * Get a database instance from the connected MongoDB client.
+     *
+     * @param {string} dbName - The name of the database
+     * @returns {Promise<Db>} The database instance
+     */
+    async getDatabase(dbName) {
+        const client = await this.getClient();
+        return client.db(dbName);
+    }
+    /**
+     * Get a collection instance from the connected MongoDB client.
+     *
+     * @param {string} dbName - The name of the database
+     * @param {string} collectionName - The name of the collection
+     * @returns {Promise<Collection>} The collection instance
+     */
+    async getCollection(dbName, collectionName) {
+        const db = await this.getDatabase(dbName);
+        return db.collection(collectionName);
+    }
+    /**
+     * Check the health of the MongoDB connection by issuing a `ping` against
+     * the `admin` database.
+     *
+     * @returns {Promise<{ status: 'healthy' | 'error'; details?: string }>} The health status and optional error details
+     */
+    async healthCheck() {
+        try {
+            const client = await this.getClient();
+            await client.db('admin').command({ ping: 1 });
+            return { status: 'healthy' };
+        }
+        catch (error) {
+            return {
+                status: 'error',
+                details: error instanceof Error
+                    ? error.message
+                    : 'Unknown error occurred',
+            };
+        }
+    }
+    /**
+     * Close the underlying MongoDB client and drain its connection pool.
+     *
+     * Intended for graceful shutdown handlers. After `close()` resolves, the
+     * next call to {@link MongoConnectionManager#getClient} establishes a
+     * fresh connection.
+     *
+     * @returns {Promise<void>}
+     */
+    async close() {
+        // If a connection is currently being established, wait for it to
+        // settle so we don't leave an orphaned client behind after shutdown.
+        if (this._connecting !== null) {
+            try {
+                await this._connecting;
+            }
+            catch {
+                // The in-flight connect failed - there is no client to close.
+            }
+        }
+        const client = this._client;
+        if (client === null) {
+            return;
+        }
+        try {
+            await client.close();
+            this._client = null;
+            getLogger().info({
+                category: 'Nimbus',
+                message: 'MongoConnectionManager :: Connection closed',
+            });
+        }
+        catch (error) {
+            // Keep `_client` so the caller can retry `close()` and we don't
+            // leak the still-open client by losing its only reference.
+            getLogger().error({
+                category: 'Nimbus',
+                message: 'MongoConnectionManager :: Error closing connection',
+                error: error,
+            });
+            throw error;
+        }
+    }
+}

package/esm/lib/mongoJSON.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Parse and stringify JSON with support for MongoDB types.
+ *
+ * The parse function takes care to convert certain datatype
+ * to the correct JS representation by looking for specific
+ * prefixes in the JSON string.
+ *
+ * @example
+ * ```ts
+ * import { MongoJSON } from '@nimbus/mongodb';
+ *
+ * const filterString = MongoJSON.stringify({
+ *     _id: 'objectId::507f1f77bcf86cd799439011',
+ *     name: 'John Doe',
+ *     age: 'int::30',
+ *     price: 'double::19.99',
+ *     createdAt: 'date::2023-01-01T00:00:00Z',
+ * });
+ *
+ * const result = MongoJSON.parse(filterString);
+ *
+ * // Result will be:
+ * // {
+ * //     _id: new ObjectId('507f1f77bcf86cd799439011'),
+ * //     name: 'John Doe',
+ * //     age: 30,
+ * //     price: 19.99,
+ * //     createdAt: new Date('2023-01-01T00:00:00Z),
+ * // }
+ * ```
+ */
+export declare const MongoJSON: {
+    parse: (text: string, operatorBlackList?: string[]) => any;
+    stringify: (object: Record<string, unknown>) => string;
+};
+//# sourceMappingURL=mongoJSON.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mongoJSON.d.ts","sourceRoot":"","sources":["../../src/lib/mongoJSON.ts"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,SAAS;kBArEZ,MAAM,sBACO,MAAM,EAAE,KAC5B,GAAG;wBAnB8B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM;CAyFnE,CAAC"}

package/esm/lib/mongoJSON.js

@@ -0,0 +1,96 @@
+import { InvalidInputException } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { ObjectId } from 'mongodb';
+/**
+ * Converts a JavaScript object to a JSON string.
+ *
+ * @param {Record<string, unknown>} object - The object to stringify.
+ * @returns {string} The JSON string representation of the object.
+ */
+const mongoJSONStringify = (object) => {
+    return JSON.stringify(object);
+};
+/**
+ * Parses a JSON string of MongoDB filter object.
+ * Converts certain datatypes to the correct JS representation
+ * by looking for specific prefixes in the JSON string.
+ *
+ * @param {string} text - JSON string to parse
+ * @param {string[]} operatorBlackList - List of operators that are not allowed. Defaults to ['$where']
+ *
+ * @returns {Object} The parsed object
+ *
+ * @throws {Error} - If the JSON string is invalid or contains a blacklisted operator
+ */
+const mongoJSONParse = (text, operatorBlackList = ['$where']) => {
+    for (const operator of operatorBlackList) {
+        if (text.includes(operator)) {
+            throw new Error(`Operator '${operator}' is not allowed`);
+        }
+    }
+    const reviver = (_key, value) => {
+        if (typeof value !== 'string') {
+            return value;
+        }
+        if (value.startsWith('objectId::')) {
+            return new ObjectId(value.replace('objectId::', ''));
+        }
+        else if (value.startsWith('date::')) {
+            return new Date(value.replace('date::', ''));
+        }
+        else if (value.startsWith('int::')) {
+            return Number.parseInt(value.replace('int::', ''));
+        }
+        else if (value.startsWith('double::')) {
+            return Number.parseFloat(value.replace('double::', ''));
+        }
+        else {
+            return value;
+        }
+    };
+    try {
+        return JSON.parse(text, reviver);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new InvalidInputException().fromError(error);
+        }
+        else {
+            throw new InvalidInputException('MongoJSON parse error');
+        }
+    }
+};
+/**
+ * Parse and stringify JSON with support for MongoDB types.
+ *
+ * The parse function takes care to convert certain datatype
+ * to the correct JS representation by looking for specific
+ * prefixes in the JSON string.
+ *
+ * @example
+ * ```ts
+ * import { MongoJSON } from '@nimbus/mongodb';
+ *
+ * const filterString = MongoJSON.stringify({
+ *     _id: 'objectId::507f1f77bcf86cd799439011',
+ *     name: 'John Doe',
+ *     age: 'int::30',
+ *     price: 'double::19.99',
+ *     createdAt: 'date::2023-01-01T00:00:00Z',
+ * });
+ *
+ * const result = MongoJSON.parse(filterString);
+ *
+ * // Result will be:
+ * // {
+ * //     _id: new ObjectId('507f1f77bcf86cd799439011'),
+ * //     name: 'John Doe',
+ * //     age: 30,
+ * //     price: 19.99,
+ * //     createdAt: new Date('2023-01-01T00:00:00Z),
+ * // }
+ * ```
+ */
+export const MongoJSON = {
+    parse: mongoJSONParse,
+    stringify: mongoJSONStringify,
+};

package/esm/lib/repository.d.ts

@@ -0,0 +1,145 @@
+import type { BulkWriteOptions, Collection, CountDocumentsOptions, DeleteOptions, Document, Filter, FindOptions, InsertOneOptions, ReplaceOptions, Sort } from 'mongodb';
+import type { ZodType } from 'zod';
+/**
+ * Type for entities that have a string id.
+ * Equivalent to the MongoDB WithId type but for the repository entity.
+ */
+export type WithStringId<TSchema> = Omit<TSchema, '_id'> & {
+    _id: string;
+};
+/**
+ * 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 declare class MongoDBRepository<TEntity extends WithStringId<Record<string, any>>> {
+    protected _getCollection: () => Promise<Collection<Document>>;
+    protected _entityType: ZodType;
+    protected _entityName: string;
+    constructor(getCollection: () => Promise<Collection<Document>>, entityType: ZodType, entityName?: string);
+    /**
+     * Function to map the MongoDB Document to the Entity.
+     * ZodType.parse is used to ensure the data is valid and type-safe.
+     */
+    protected _mapDocumentToEntity(doc: Document): TEntity;
+    /**
+     * Function to map the Entity to a  MongoDB Document.
+     */
+    protected _mapEntityToDocument(item: TEntity): Document;
+    /**
+     * Find one document based on a given filter.
+     */
+    findOne({ filter, }: {
+        filter: Filter<Document>;
+    }): Promise<TEntity>;
+    /**
+     * Find multiple documents based on a given filter.
+     */
+    find({ filter, limit, skip, sort, project, options, }: {
+        filter: Filter<Document>;
+        limit?: number;
+        skip?: number;
+        sort?: Sort;
+        project?: Document;
+        options?: FindOptions;
+    }): Promise<TEntity[]>;
+    /**
+     * Count all documents matching a given filter.
+     */
+    countDocuments({ filter, options, }: {
+        filter: Filter<Document>;
+        options?: CountDocumentsOptions;
+    }): Promise<number>;
+    /**
+     * Insert a single new document.
+     */
+    insertOne({ item, }: {
+        item: TEntity;
+        options?: InsertOneOptions;
+    }): Promise<TEntity>;
+    /**
+     * Insert multiple new documents.
+     */
+    insertMany({ items, options, }: {
+        items: TEntity[];
+        options?: BulkWriteOptions;
+    }): Promise<TEntity[]>;
+    /**
+     * Replace a single document.
+     */
+    replaceOne({ item, options, }: {
+        item: TEntity;
+        options?: ReplaceOptions;
+    }): Promise<TEntity>;
+    /**
+     * Replace multiple documents.
+     */
+    replaceMany({ items, options, }: {
+        items: TEntity[];
+        options?: BulkWriteOptions;
+    }): Promise<TEntity[]>;
+    /**
+     * Delete a single document.
+     */
+    deleteOne({ item, options, }: {
+        item: TEntity;
+        options?: DeleteOptions;
+    }): Promise<TEntity>;
+    /**
+     * Delete multiple documents.
+     */
+    deleteMany({ items, options, }: {
+        items: TEntity[];
+        options?: DeleteOptions;
+    }): Promise<TEntity[]>;
+}
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/lib/repository.ts"],"names":[],"mappings":"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"}