@opra/mongodb 0.32.2 → 0.32.3

package/cjs/mongo-collection-service.js

@@ -8,55 +8,70 @@ const common_1 = require("@opra/common");
 const mongo_adapter_js_1 = require("./mongo-adapter.js");
 const mongo_service_js_1 = require("./mongo-service.js");
 /**
- *
  * @class MongoCollectionService
+ * @template T - The type of the documents in the collection.
  */
 class MongoCollectionService extends mongo_service_js_1.MongoService {
     constructor(dataType, options) {
         super(dataType, options);
-        this._encoders = {};
         this.defaultLimit = options?.defaultLimit || 10;
         this.collectionKey = options?.collectionKey || '_id';
     }
     /**
-     * Checks if document exists. Throws error if not.
+     * Asserts the existence of a resource with the given ID.
+     * Throws a ResourceNotFoundError if the resource does not exist.
      *
-     * @param id
+     * @param {AnyId} id - The ID of the resource to assert.
+     * @returns {Promise<void>} - A Promise that resolves when the resource exists.
+     * @throws {ResourceNotFoundError} - If the resource does not exist.
      */
     async assert(id) {
         if (!(await this.exists(id)))
             throw new common_1.ResourceNotFoundError(this.resourceName || this.getCollectionName(), id);
     }
     /**
-     * Inserts a single document into MongoDB
+     * Creates a new document in the MongoDB collection.
      *
-     * @param input
-     * @param options
+     * @param {PartialInput<T>} input - The input data for creating the document.
+     * @param {MongoCollectionService.CreateOptions} [options] - The options for creating the document.
+     * @returns {Promise<PartialOutput<T>>} A promise that resolves to the created document.
+     * @throws {Error} if an unknown error occurs while creating the document.
      */
     async create(input, options) {
-        const encode = this._getEncoder('create');
+        const encode = this.getEncoder('create');
         const doc = encode(input);
         doc._id = doc._id || this._generateId();
         const r = await this.__insertOne(doc, options);
-        if (r.insertedId)
-            return doc;
+        if (r.insertedId) {
+            if (!options)
+                return doc;
+            try {
+                return this.get(doc._id, options);
+            }
+            catch (e) {
+                Error.captureStackTrace(e);
+                throw e;
+            }
+        }
         /* istanbul ignore next */
         throw new Error('Unknown error while creating document');
     }
     /**
-     * Gets the number of documents matching the filter.
+     * Returns the count of documents in the collection based on the provided options.
      *
-     * @param options
+     * @param {MongoCollectionService.CountOptions<T>} options - The options for the count operation.
+     * @return {Promise<number>} - A promise that resolves to the count of documents in the collection.
      */
     async count(options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter(options?.filter);
         return this.__countDocuments(filter, (0, lodash_omit_1.default)(options, 'filter'));
     }
     /**
-     * Delete a document from a collection
+     * Deletes a document from the collection.
      *
-     * @param id
-     * @param options
+     * @param {AnyId} id - The ID of the document to delete.
+     * @param {MongoCollectionService.DeleteOptions<T>} [options] - Optional delete options.
+     * @return {Promise<number>} - A Promise that resolves to the number of documents deleted.
      */
     async delete(id, options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
@@ -67,9 +82,10 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
         return r.deletedCount;
     }
     /**
-     * Delete multiple documents from a collection
+     * Deletes multiple documents from the collection that meet the specified filter criteria.
      *
-     * @param options
+     * @param {MongoCollectionService.DeleteManyOptions<T>} options - The options for the delete operation.
+     * @return {Promise<number>} - A promise that resolves to the number of documents deleted.
      */
     async deleteMany(options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter(options?.filter);
@@ -77,19 +93,20 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
         return r.deletedCount;
     }
     /**
-     * Checks if document exists.
-     * Returns true if document exists, false otherwise
+     * Checks if an object with the given id exists.
      *
-     * @param id
+     * @param {AnyId} id - The id of the object to check.
+     * @return {Promise<boolean>} - A Promise that resolves to a boolean indicating whether the object exists or not.
      */
     async exists(id) {
         return !!(await this.findById(id, { pick: ['_id'] }));
     }
     /**
-     * Fetches the first document matches by id.
+     * Finds a document by its ID.
      *
-     * @param id
-     * @param options
+     * @param {AnyId} id - The ID of the document.
+     * @param {MongoCollectionService.FindOneOptions} [options] - The options for the find query.
+     * @return {Promise<PartialOutput<T | undefined>>} - A promise resolving to the found document, or undefined if not found.
      */
     async findById(id, options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
@@ -99,10 +116,10 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
         return await this.findOne({ ...options, filter });
     }
     /**
-     * Fetches the first document that matches the filter.
-     * Returns undefined if not found.
+     * Finds a document in the collection that matches the specified options.
      *
-     * @param options
+     * @param {MongoCollectionService.FindOneOptions} options - The options for the query.
+     * @return {Promise<PartialOutput<T> | undefined>} A promise that resolves with the found document or undefined if no document is found.
      */
     async findOne(options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter(options?.filter);
@@ -112,13 +129,24 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
             projection: mongo_adapter_js_1.MongoAdapter.prepareProjection(this.getDataType(), options),
             limit: undefined
         };
+        const decoder = this.getDecoder();
         const out = await this.__findOne(filter, mongoOptions);
-        return out || undefined;
+        return out ? decoder(out) : undefined;
     }
     /**
-     * Fetches all document that matches the filter
+     * Finds multiple documents in the MongoDB collection.
      *
-     * @param options
+     * @param options - The options for the find operation.
+     *  - pick: string[] - An array of fields to include in the returned documents.
+     *  - include: string[] - An array of fields to include in the returned documents.
+     *  - omit: string[] - An array of fields to exclude from the returned documents.
+     *  - sort: Record<string, number> - The sorting criteria.
+     *  - skip: number - The number of documents to skip.
+     *  - limit: number - The maximum number of documents to return.
+     *  - filter: FilterQuery<T> - The filter conditions to apply to the find operation.
+     *  - count: boolean - If set to true, returns the total count of matching documents.
+     *
+     * @return A Promise that resolves to an array of partial outputs of type T.
      */
     async findMany(options) {
         const mongoOptions = {
@@ -152,6 +180,7 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
         const projection = mongo_adapter_js_1.MongoAdapter.prepareProjection(dataType, options);
         if (projection)
             dataStages.push({ $project: projection });
+        const decoder = this.getDecoder();
         const cursor = await this.__aggregate(stages, {
             ...mongoOptions
         });
@@ -159,7 +188,7 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
             if (options?.count) {
                 const facetResult = await cursor.toArray();
                 this.context.response.totalMatches = facetResult[0].count[0].totalMatches || 0;
-                return facetResult[0].data;
+                return facetResult[0].data.map((r) => decoder(r));
             }
             else
                 return await cursor.toArray();
@@ -170,10 +199,13 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
         }
     }
     /**
-     * Fetches the first Document that matches the id. Throws error undefined if not found.
+     * Retrieves a document from the collection by its ID. Throws error if not found.
      *
-     * @param id
-     * @param options
+     * @param {*} id - The ID of the document to retrieve.
+     * @param {MongoCollectionService.FindOneOptions} [options] - Optional options for the findOne operation.
+     * @returns {Promise<PartialOutput<T>>} - A promise that resolves to the retrieved document,
+     *    or rejects with a ResourceNotFoundError if the document does not exist.
+     * @throws {ResourceNotFoundError} - If the document with the specified ID does not exist.
      */
     async get(id, options) {
         const out = await this.findById(id, options);
@@ -182,20 +214,17 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
         return out;
     }
     /**
-     * Updates a single document.
-     * Returns updated document
+     * Updates a document with the given id in the collection.
      *
-     * @param id
-     * @param input
-     * @param options
+     * @param {any} id - The id of the document to update.
+     * @param {PartialInput<T>} input - The partial input object containing the fields to update.
+     * @param {MongoCollectionService.UpdateOptions<T>} [options] - The options for the update operation.
+     * @returns {Promise<PartialOutput<T> | undefined>} A promise that resolves to the updated document or
+     * undefined if the document was not found.
      */
     async update(id, input, options) {
-        const encode = this._getEncoder('update');
+        const encode = this.getEncoder('update');
         const doc = encode(input);
-        const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
-            mongo_adapter_js_1.MongoAdapter.prepareKeyValues(id, [this.collectionKey]),
-            options?.filter
-        ]);
         const patch = mongo_adapter_js_1.MongoAdapter.preparePatch(doc);
         const mongoOptions = {
             ...options,
@@ -203,24 +232,31 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
             upsert: undefined,
             projection: mongo_adapter_js_1.MongoAdapter.prepareProjection(this.getDataType(), options),
         };
+        const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
+            mongo_adapter_js_1.MongoAdapter.prepareKeyValues(id, [this.collectionKey]),
+            options?.filter
+        ]);
+        const decoder = this.getDecoder();
         const out = await this.__findOneAndUpdate(filter, patch, mongoOptions);
-        return out || undefined;
+        return out ? decoder(out) : undefined;
     }
     /**
-     * Updates a single document
-     * Returns number of updated documents
+     * Updates a document in the collection with the specified ID.
      *
-     * @param id
-     * @param input
-     * @param options
+     * @param {any} id - The ID of the document to update.
+     * @param {PartialInput<T>} input - The partial input data to update the document with.
+     * @param {MongoCollectionService.UpdateOptions<T>} options - The options for updating the document.
+     * @returns {Promise<number>} - A promise that resolves to the number of documents modified.
      */
     async updateOnly(id, input, options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
             mongo_adapter_js_1.MongoAdapter.prepareKeyValues(id, [this.collectionKey]),
             options?.filter
         ]);
-        const encode = this._getEncoder('update');
+        const encode = this.getEncoder('update');
         const doc = encode(input);
+        if (!Object.keys(doc).length)
+            return 0;
         const patch = mongo_adapter_js_1.MongoAdapter.preparePatch(doc);
         const mongoOptions = {
             ...options,
@@ -229,17 +265,20 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
             projection: mongo_adapter_js_1.MongoAdapter.prepareProjection(this.getDataType(), options),
         };
         const out = await this.__updateOne(filter, patch, mongoOptions);
-        return out.modifiedCount;
+        return out.matchedCount;
     }
     /**
-     *  Update multiple documents in a collection
+     * Updates multiple documents in the collection based on the specified input and options.
      *
-     * @param input
-     * @param options
+     * @param {OpraCommon.PartialInput<T>} input - The partial input to update the documents with.
+     * @param {MongoCollectionService.UpdateManyOptions<T>} options - The options for updating the documents.
+     * @return {Promise<number>} - A promise that resolves to the number of documents matched and modified.
      */
     async updateMany(input, options) {
-        const encode = this._getEncoder('update');
+        const encode = this.getEncoder('update');
         const doc = encode(input);
+        if (!Object.keys(doc).length)
+            return 0;
         const patch = mongo_adapter_js_1.MongoAdapter.preparePatch(doc);
         patch.$set = patch.$set || {};
         const mongoOptions = {
@@ -251,45 +290,13 @@ class MongoCollectionService extends mongo_service_js_1.MongoService {
         return r.matchedCount;
     }
     /**
-     * Generates Id value
+     * Generates a new id for new inserting Document.
      *
      * @protected
+     * @returns {AnyId} A new instance of AnyId.
      */
     _generateId() {
         return new mongodb_1.ObjectId();
     }
-    /**
-     * Generates a new Validator  for encoding or returns from cache if already generated before
-     * @param operation
-     * @protected
-     */
-    _getEncoder(operation) {
-        let encoder = this._encoders[operation];
-        if (encoder)
-            return encoder;
-        encoder = this._generateEncoder(operation);
-        this._encoders[operation] = encoder;
-        return encoder;
-    }
-    /**
-     * Generates a new Valgen Validator for encode operation
-     *
-     * @param operation
-     * @protected
-     */
-    _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;
-    }
 }
 exports.MongoCollectionService = MongoCollectionService;

package/cjs/mongo-service.js

@@ -3,9 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MongoService = void 0;
 const common_1 = require("@opra/common");
 const core_1 = require("@opra/core");
+/**
+ * Class representing a MongoDB service for interacting with a collection.
+ * @extends ApiService
+ * @template T - The type of the documents in the collection.
+ */
 class MongoService extends core_1.ApiService {
     constructor(dataType, options) {
         super();
+        this._encoders = {};
         this._dataType = dataType;
         this.db = options?.db;
         this.collectionName = options?.collectionName || options?.resourceName;
@@ -20,6 +26,12 @@ class MongoService extends core_1.ApiService {
         }
         this.resourceName = options?.resourceName || this.collectionName;
     }
+    /**
+     * 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);
     }
@@ -161,10 +173,11 @@ class MongoService extends core_1.ApiService {
         }
     }
     /**
-     * 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) {
@@ -185,10 +198,11 @@ class MongoService extends core_1.ApiService {
     /**
      * 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();
@@ -278,5 +292,71 @@ class MongoService extends core_1.ApiService {
             (!attributes?.db || service.db === attributes.db) &&
             (!attributes?.session || this.session === attributes?.session);
     }
+    /**
+     * 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;
+    }
+    /**
+     * 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;
+    }
 }
 exports.MongoService = MongoService;

package/cjs/mongo-singleton-service.js

@@ -6,8 +6,10 @@ const common_1 = require("@opra/common");
 const mongo_adapter_js_1 = require("./mongo-adapter.js");
 const mongo_service_js_1 = require("./mongo-service.js");
 /**
- *
+ * A class that provides access to a MongoDB collection, with support for singleton document operations.
  * @class MongoSingletonService
+ * @extends MongoService
+ * @template T - The type of document stored in the collection
  */
 class MongoSingletonService extends mongo_service_js_1.MongoService {
     constructor(dataType, options) {
@@ -16,33 +18,47 @@ class MongoSingletonService extends mongo_service_js_1.MongoService {
         this._id = options?._id || new mongodb_1.ObjectId('655608925cad472b75fc6485');
     }
     /**
-     * Fetches the Document. Throws error undefined if not found.
+     * Asserts the existence of a resource based on the given options.
      *
-     * @param options
+     * @returns {Promise<void>} A Promise that resolves when the resource exists.
+     * @throws {ResourceNotFoundError} If the resource does not exist.
      */
-    async assert(options) {
-        const out = await this.get(options);
-        if (!out)
+    async assert() {
+        if (!(await this.exists()))
             throw new common_1.ResourceNotFoundError(this.resourceName || this.getCollectionName());
-        return out;
     }
     /**
-     * Inserts the document into MongoDB
+     * Creates the document in the database.
      *
-     * @param doc
-     * @param options
+     * @param {PartialInput<T>} input - The partial input to create the document with.
+     * @param {MongoSingletonService.CreateOptions} [options] - The options for creating the document.
+     * @return {Promise<PartialOutput<T>>} A promise that resolves to the partial output of the created document.
+     * @throws {Error} Throws an error if an unknown error occurs while creating the document.
      */
-    async create(doc, options) {
-        const r = await this.__insertOne({ ...doc, _id: this._id }, options);
-        if (r.insertedId)
-            return doc;
+    async create(input, options) {
+        const encode = this.getEncoder('create');
+        const doc = encode(input);
+        doc._id = this._id;
+        const r = await this.__insertOne(doc, options);
+        if (r.insertedId) {
+            if (!options)
+                return doc;
+            try {
+                return this.get(options);
+            }
+            catch (e) {
+                Error.captureStackTrace(e);
+                throw e;
+            }
+        }
         /* istanbul ignore next */
         throw new Error('Unknown error while creating document');
     }
     /**
-     * Delete the document from a collection
+     * Deletes a record from the database
      *
-     * @param options
+     * @param {MongoSingletonService.DeleteOptions<T>} options - The options for deleting the record
+     * @returns {Promise<number>} The number of records deleted
      */
     async delete(options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([{ _id: this._id }, options?.filter]);
@@ -50,19 +66,20 @@ class MongoSingletonService extends mongo_service_js_1.MongoService {
         return r.deletedCount;
     }
     /**
-     * Checks if the document exists.
-     * Returns true if document exists, false otherwise
+     * Checks if the document exists in the database.
      *
+     * @return {Promise<boolean>} - A promise that resolves to a boolean value indicating if the document exists.
      */
     async exists() {
-        return !!(await this.get({ pick: ['_id'] }));
+        return !!(await this.findOne({ pick: ['_id'] }));
     }
     /**
-     * Fetches the document
+     * Fetches the document if it exists. Returns undefined if not found.
      *
-     * @param options
+     * @param {MongoSingletonService.FindOptions<T>} [options] - The options for finding the document.
+     * @returns {Promise<PartialOutput<T> | undefined>} - A promise that resolves to the found document or undefined if not found.
      */
-    async get(options) {
+    async findOne(options) {
         const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([{ _id: this._id }, options?.filter]);
         const mongoOptions = {
             ...options,
@@ -74,19 +91,29 @@ class MongoSingletonService extends mongo_service_js_1.MongoService {
         return await this.__findOne(filter, mongoOptions);
     }
     /**
-     * Updates a single document.
-     * Returns updated document
+     * Fetches the document from the Mongo collection service. Throws error if not found.
      *
-     * @param doc
-     * @param options
+     * @param {MongoCollectionService.FindOneOptions} options - The options to customize the query.
+     * @return {Promise<PartialOutput<T>>} - A promise that resolves to the fetched document.
+     * @throws {ResourceNotFoundError} - If the document is not found in the collection.
      */
-    async update(doc, options) {
-        // Prevent updating _id field
-        delete doc._id;
-        const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
-            { _id: this._id },
-            options?.filter
-        ]);
+    async get(options) {
+        const out = await this.findOne(options);
+        if (!out)
+            throw new common_1.ResourceNotFoundError(this.resourceName || this.getCollectionName());
+        return out;
+    }
+    /**
+     * Updates a document in the MongoDB collection.
+     *
+     * @param {PartialInput<T>} input - The partial input to update the document.
+     * @param {MongoSingletonService.UpdateOptions<T>} [options] - The update options.
+     *
+     * @return {Promise<PartialOutput<T> | undefined>} - A promise that resolves to the updated document or undefined if not found.
+     */
+    async update(input, options) {
+        const encode = this.getEncoder('update');
+        const doc = encode(input);
         const patch = mongo_adapter_js_1.MongoAdapter.preparePatch(doc);
         const mongoOptions = {
             ...options,
@@ -94,8 +121,13 @@ class MongoSingletonService extends mongo_service_js_1.MongoService {
             upsert: undefined,
             projection: mongo_adapter_js_1.MongoAdapter.prepareProjection(this.getDataType(), options),
         };
+        const filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
+            { _id: this._id },
+            options?.filter
+        ]);
+        const decoder = this.getDecoder();
         const out = await this.__findOneAndUpdate(filter, patch, mongoOptions);
-        return out || undefined;
+        return out ? decoder(out) : undefined;
     }
 }
 exports.MongoSingletonService = MongoSingletonService;