@opra/mongodb 0.32.2 → 0.32.4

package/esm/mongo-service.js

@@ -1,11 +1,24 @@
 import { DATATYPE_METADATA } from '@opra/common';
 import { ApiService } from '@opra/core';
+/**
+ * Class representing a MongoDB service for interacting with a collection.
+ * @extends ApiService
+ * @template T - The type of the documents in the collection.
+ */
 export class MongoService extends ApiService {
+    /**
+     * Constructs a new instance
+     *
+     * @param {Type | string} dataType - The data type of the array elements.
+     * @param {MongoService.Options} [options] - The options for the array service.
+     * @constructor
+     */
     constructor(dataType, options) {
         super();
+        this._encoders = {};
         this._dataType = dataType;
         this.db = options?.db;
-        this.collectionName = options?.collectionName || options?.resourceName;
+        this.collectionName = options?.collectionName;
         if (!this.collectionName) {
             if (typeof dataType === 'string')
                 this.collectionName = dataType;
@@ -15,264 +28,407 @@ export class MongoService extends ApiService {
                     this.collectionName = metadata.name;
             }
         }
-        this.resourceName = options?.resourceName || this.collectionName;
+        this.resourceName = options?.resourceName;
+        this.$idGenerator = options?.idGenerator;
     }
+    /**
+     * Retrieves the data type of the document
+     *
+     * @returns {ComplexType} The complex data type of the field.
+     * @throws {NotAcceptableError} If the data type is not a ComplexType.
+     */
     getDataType() {
         return this.context.api.getComplexType(this._dataType);
     }
-    forContext(arg0, attributes) {
-        return super.forContext(arg0, attributes);
+    /**
+     * Retrieves the encoder for the specified operation.
+     *
+     * @param {String} operation - The operation to retrieve the encoder for. Valid values are 'create' and 'update'.
+     * @returns {vg.ObjectValidator<T>} - The encoder for the specified operation.
+     */
+    getEncoder(operation) {
+        let encoder = this._encoders[operation];
+        if (encoder)
+            return encoder;
+        encoder = this._generateEncoder(operation);
+        this._encoders[operation] = encoder;
+        return encoder;
+    }
+    /**
+     * Retrieves the decoder.
+     *
+     * @returns {vg.ObjectValidator<T>} - The encoder for the specified operation.
+     */
+    getDecoder() {
+        let decoder = this._decoder;
+        if (decoder)
+            return decoder;
+        decoder = this._generateDecoder();
+        this._decoder = decoder;
+        return decoder;
     }
     /**
      * Inserts a single document into MongoDB. If documents passed in do not contain the **_id** field,
      * one will be added to each of the documents missing it by the driver, mutating the document. This behavior
      * can be overridden by setting the **forceServerObjectId** flag.
      *
-     * @param doc
-     * @param options
+     * @param {T} doc - The document to be inserted.
+     * @param {mongodb.InsertOneOptions} options - The options for the insert operation.
+     * @returns {Promise<mongodb.InsertOneWriteOpResult<mongodb.OptionalId<T>>>} - A promise that resolves with the result of the insert operation.
      * @protected
      */
     async __insertOne(doc, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
-            session: options?.session || this.session
+            session: options?.session || this.getSession()
         };
         try {
             return await collection.insertOne(doc, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
      * Gets the number of documents matching the filter.
      *
-     * @param filter
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter used to match documents.
+     * @param {mongodb.CountOptions} options - The options for counting documents.
+     * @returns {Promise<number>} - The number of documents matching the filter.
      * @protected
      */
     async __countDocuments(filter, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
             limit: undefined,
-            session: options?.session || this.session
+            session: options?.session || this.getSession()
         };
         try {
-            return await collection.countDocuments(filter, options) || 0;
+            return await collection.countDocuments(filter || {}, options) || 0;
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
      * Delete a document from a collection
      *
-     * @param filter - The filter used to select the document to remove
-     * @param options - Optional settings for the command
+     * @param {mongodb.Filter<T>} filter - The filter used to select the document to remove
+     * @param {mongodb.DeleteOptions} options - Optional settings for the command
+     * @return {Promise<mongodb.DeleteResult>} A Promise that resolves to the result of the delete operation
      */
     async __deleteOne(filter, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
-            session: options?.session || this.session
+            session: options?.session || this.getSession()
         };
         try {
-            return await collection.deleteOne(filter, options);
+            return await collection.deleteOne(filter || {}, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
-     * Delete multiple documents from a collection
+     * Deletes multiple documents from a collection.
      *
-     * @param filter
-     * @param options
+     * @param {mongodb.Filter<T>} [filter] - The filter object specifying the documents to delete.
+     * If not provided, all documents in the collection will be deleted.
+     * @param {mongodb.DeleteOptions} [options] - The options for the delete operation.
+     * @returns {Promise<mongodb.DeleteResult>} A promise that resolves with the delete result object.
      * @protected
      */
     async __deleteMany(filter, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
-            session: options?.session || this.session
+            session: options?.session || this.getSession()
         };
         try {
-            return await collection.deleteMany(filter, options);
+            return await collection.deleteMany(filter || {}, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
-     * Create a new Change Stream, watching for new changes (insertions, updates, replacements, deletions, and invalidations) in this collection.
+     * Create a new Change Stream, watching for new changes
+     * (insertions, updates, replacements, deletions, and invalidations) in this collection.
      *
-     * @param pipeline
-     * @param options
+     * @param {mongodb.Document[]} pipeline - The pipeline of aggregation stages to apply to the collection.
+     * @param {mongodb.AggregateOptions} options - The options to customize the aggregation.
+     * @returns {Promise<mongodb.ChangeStream<T>>} - A promise that resolves to a Change Stream that represents the result of the aggregation.
      * @protected
      */
     async __aggregate(pipeline, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
-            session: options?.session || this.session
+            session: options?.session || this.getSession()
         };
         try {
             return await collection.aggregate(pipeline, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
      * Fetches the first document that matches the filter
      *
-     * @param filter
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter object to match documents against
+     * @param {mongodb.FindOptions} [options] - The options to use when querying the collection
      * @protected
+     * @returns {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the first matching document, or undefined if no match is found
      */
     async __findOne(filter, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
-            session: options?.session || this.session
+            session: options?.session || this.getSession()
         };
         try {
-            return await collection.findOne(filter, options);
+            return await collection.findOne(filter || {}, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
-     * Creates a cursor for a filter that can be used to iterate over results from MongoDB
+     * Creates a cursor for a filter that can be used to iterate over results from MongoDB.
      *
-     * @param filter
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter to apply when searching for results.
+     * @param {mongodb.FindOptions} [options] - The options to customize the search behavior.
+     * @returns {mongodb.Cursor<T>} - The cursor object that can be used to iterate over the results.
      * @protected
      */
     async __find(filter, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
-            session: options?.session || this.session
+            session: options?.session || this.getSession()
         };
         try {
-            return collection.find(filter, options);
+            return collection.find(filter || {}, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
-     * Update a single document in a collection
+     * Update a single document in a collection.
      *
-     * @param filter
-     * @param update
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter to select the document(s) to update.
+     * @param {mongodb.UpdateFilter<T>} update - The update operation to be applied on the selected document(s).
+     * @param {mongodb.UpdateOptions} [options] - Optional settings for the update operation.
      * @protected
+     * @returns {Promise<mongodb.UpdateResult>} - A promise that resolves to the result of the update operation.
      */
     async __updateOne(filter, update, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
-            session: this.session,
-            ...options
+            ...options,
+            session: options?.session || this.getSession(),
         };
         try {
-            return collection.updateOne(filter, update, options);
+            return collection.updateOne(filter || {}, update, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
      * Find a document and update it in one atomic operation. Requires a write lock for the duration of the operation.
      *
-     * @param filter
-     * @param doc
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter to select the document to be updated.
+     * @param {mongodb.UpdateFilter<T>} doc - The update document.
+     * @param {mongodb.FindOneAndUpdateOptions} [options] - Optional options for the find one and update operation.
+     * @returns {Promise<T | null>} - A promise that resolves to the updated document or null if no document matched the filter.
      * @protected
      */
     async __findOneAndUpdate(filter, doc, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         const opts = {
             returnDocument: 'after',
-            session: this.session,
             includeResultMetadata: false,
             ...options,
+            session: options?.session || this.getSession(),
         };
         try {
-            return await collection.findOneAndUpdate(filter, doc, opts);
+            return await collection.findOneAndUpdate(filter || {}, doc, opts);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
     /**
-     * Update multiple documents in a collection
+     * Update multiple documents in a collection.
      *
-     * @param filter
-     * @param doc
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter used to select the documents to be updated.
+     * @param {mongodb.UpdateFilter<T> | Partial<T>} doc - The updates to be applied to the selected documents.
+     * @param {StrictOmit<mongodb.UpdateOptions, 'upsert'>} [options] - The optional settings for the update operation.
+     * @return {Promise<mongodb.UpdateResult>} - A Promise that resolves to the result of the update operation.
      * @protected
      */
     async __updateMany(filter, doc, options) {
-        const db = await this.getDatabase();
+        const db = this.getDatabase();
         const collection = await this.getCollection(db);
         options = {
             ...options,
-            session: options?.session || this.session,
+            session: options?.session || this.getSession(),
             upsert: false
         };
         try {
-            return await collection.updateMany(filter, doc, options);
+            return await collection.updateMany(filter || {}, doc, options);
         }
         catch (e) {
-            await this._onError(e);
+            await this.$onError?.(e, this);
             throw e;
         }
     }
-    async _onError(error) {
-        if (this.onError)
-            await this.onError(error);
-    }
+    /**
+     * Retrieves the database connection.
+     *
+     * @protected
+     *
+     * @returns {Promise<mongodb.Db>} The database connection.
+     * @throws {Error} If the context or database is not set.
+     */
     getDatabase() {
-        if (!this.context)
-            throw new Error(`Context not set!`);
-        if (!this.db)
+        const db = typeof this.db === 'function'
+            ? this.db(this)
+            : this.db;
+        if (!db)
             throw new Error(`Database not set!`);
-        return this.db;
+        return db;
     }
+    /**
+     * Retrieves the database session.
+     *
+     * @protected
+     *
+     * @returns {Promise<mongodb.ClientSession>} The database connection.
+     * @throws {Error} If the context or database is not set.
+     */
+    getSession() {
+        return typeof this.session === 'function'
+            ? this.session(this)
+            : this.session;
+    }
+    /**
+     * Retrieves a MongoDB collection from the given database.
+     *
+     * @param {mongodb.Db} db - The MongoDB database.
+     * @protected
+     * @returns {Promise<mongodb.Collection<T>>} A promise that resolves to the MongoDB collection.
+     */
     async getCollection(db) {
         return db.collection(this.getCollectionName());
     }
+    /**
+     * Retrieves the collection name.
+     *
+     * @protected
+     * @returns {string} The collection name.
+     * @throws {Error} If the collection name is not defined.
+     */
     getCollectionName() {
-        if (this.collectionName)
-            return this.collectionName;
+        const out = typeof this.collectionName === 'function'
+            ? this.collectionName(this)
+            : this.collectionName;
+        if (out)
+            return out;
         throw new Error('collectionName is not defined');
     }
-    _cacheMatch(service, context, attributes) {
-        return super._cacheMatch(service, context, attributes) &&
-            (!attributes?.db || service.db === attributes.db) &&
-            (!attributes?.session || this.session === attributes?.session);
+    /**
+     * Retrieves the resource name.
+     *
+     * @protected
+     * @returns {string} The collection name.
+     * @throws {Error} If the collection name is not defined.
+     */
+    getResourceName() {
+        const out = typeof this.resourceName === 'function'
+            ? this.resourceName(this)
+            : this.resourceName || this.getCollectionName();
+        if (out)
+            return out;
+        throw new Error('resourceName is not defined');
+    }
+    /**
+     * Compares the current instance with the provided attributes and returns true if they match, false otherwise.
+     * This method is protected and should only be called by subclasses.
+     *
+     * @param {MongoService<any>} service - The service instance to compare.
+     * @param {RequestContext} context - The request context.
+     * @param {Object} attributes - Optional attributes object for comparison.
+     * @return {boolean} - True if the instance matches the provided attributes, false otherwise.
+     * @protected
+     */
+    _instanceCompare(service, context, attributes) {
+        return super._instanceCompare(service, context, attributes) &&
+            (!attributes?.db ||
+                (typeof service.db === 'object' && service.db === attributes.db) ||
+                (typeof service.db === 'function' && service.getDatabase() === attributes.db)) &&
+            (!attributes?.session ||
+                (typeof service.session === 'object' && service.session === attributes?.session) ||
+                (typeof service.session === 'function' && service.getSession() === attributes?.session));
+    }
+    /**
+     * Generates an encoder for the specified operation.
+     *
+     * @param {string} operation - The operation to generate the encoder for. Must be either 'create' or 'update'.
+     * @protected
+     * @returns {vg.Validator} - The generated encoder for the specified operation.
+     */
+    _generateEncoder(operation) {
+        let encoder = this._encoders[operation];
+        if (encoder)
+            return encoder;
+        const dataType = this.getDataType();
+        const options = {};
+        if (operation === 'update') {
+            options.omit = ['_id'];
+            options.partial = true;
+        }
+        encoder = dataType.generateCodec('encode', options);
+        this._encoders[operation] = encoder;
+        return encoder;
+    }
+    /**
+     * Generates an encoder for the specified operation.
+     *
+     * @protected
+     * @returns {vg.Validator} - The generated encoder for the specified operation.
+     */
+    _generateDecoder() {
+        let decoder = this._decoder;
+        if (decoder)
+            return decoder;
+        const dataType = this.getDataType();
+        const options = {};
+        decoder = this._decoder = dataType.generateCodec('decode', options);
+        return decoder;
     }
 }