@opra/mongodb 0.32.1 → 0.32.3

package/cjs/mongo-array-service.js

@@ -8,67 +8,83 @@ 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 MongoArrayService
+ * A class that provides methods to perform operations on an array field in a MongoDB collection.
+ * @template T The type of the array item.
  */
 class MongoArrayService extends mongo_service_js_1.MongoService {
     constructor(dataType, fieldName, options) {
         super(dataType, options);
-        this._encoders = {};
         this.fieldName = fieldName;
         this.defaultLimit = options?.defaultLimit || 10;
         this.collectionKey = options?.collectionKey || '_id';
         this.arrayKey = options?.arrayKey || '_id';
     }
-    getArrayDataType() {
-        const t = this.getDataType()
+    /**
+     * Retrieves the data type of the array field
+     *
+     * @returns {ComplexType} The complex data type of the field.
+     * @throws {NotAcceptableError} If the data type is not a ComplexType.
+     */
+    getDataType() {
+        const t = super.getDataType()
             .getField(this.fieldName).type;
         if (!(t instanceof common_1.ComplexType))
             throw new common_1.NotAcceptableError(`Data type "${t.name}" is not a ComplexType`);
         return t;
     }
     /**
-     * Checks if array item exists. Throws error if not.
+     * Asserts whether a resource with the specified parentId and id exists.
+     * Throws a ResourceNotFoundError if the resource does not exist.
      *
-     * @param parentId
-     * @param id
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {AnyId} id - The ID of the resource.
+     * @return {Promise<void>} - A promise that resolves with no value upon success.
+     * @throws {ResourceNotFoundError} - If the resource does not exist.
      */
-    async assert(parentId, id) {
-        if (!(await this.exists(parentId, id)))
-            throw new common_1.ResourceNotFoundError((this.resourceName || this.getCollectionName()) + '.' + this.arrayKey, parentId + '/' + id);
+    async assert(documentId, id) {
+        if (!(await this.exists(documentId, id)))
+            throw new common_1.ResourceNotFoundError((this.resourceName || this.getCollectionName()) + '.' + this.arrayKey, documentId + '/' + id);
     }
     /**
-     * Adds a single item into array field.
+     * Adds a single item into the array field.
      *
-     * @param parentId
-     * @param input
-     * @param options
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {T} input - The item to be added to the array field.
+     * @param {MongoArrayService.CreateOptions} [options] - Optional options for the create operation.
+     * @return {Promise<PartialOutput<T>>} - A promise that resolves with the partial output of the created item.
+     * @throws {ResourceNotFoundError} - If the parent document is not found.
      */
-    async create(parentId, input, options) {
-        const encode = this._getEncoder('create');
+    async create(documentId, input, options) {
+        const encode = this.getEncoder('create');
         const doc = encode(input);
         doc[this.arrayKey] = doc[this.arrayKey] || this._generateId();
-        const docFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(parentId, [this.collectionKey]);
+        const docFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(documentId, [this.collectionKey]);
         const r = await this.__updateOne(docFilter, {
             $push: { [this.fieldName]: doc }
         }, options);
-        if (r.modifiedCount)
+        if (r.modifiedCount) {
+            if (!options)
+                return doc;
             try {
-                return this.get(parentId, doc[this.arrayKey], { ...options, filter: undefined, skip: undefined });
+                return this.get(documentId, doc[this.arrayKey], { ...options, filter: undefined, skip: undefined });
             }
             catch (e) {
                 Error.captureStackTrace(e);
                 throw e;
             }
-        throw new common_1.ResourceNotFoundError(this.resourceName || this.getCollectionName(), parentId);
+        }
+        throw new common_1.ResourceNotFoundError(this.resourceName || this.getCollectionName(), documentId);
     }
     /**
-     * Gets the number of array items matching the filter.
-     * @param parentId
-     * @param options
+     * Counts the number of documents in the collection that match the specified parentId and options.
+     *
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {object} options - Optional parameters for counting.
+     * @param {object} options.filter - The filter object to apply to the count operation.
+     * @returns {Promise<number>} - A promise that resolves to the count of documents.
      */
-    async count(parentId, options) {
-        const matchFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(parentId, [this.collectionKey]);
+    async count(documentId, options) {
+        const matchFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(documentId, [this.collectionKey]);
         const stages = [
             { $match: matchFilter },
             { $unwind: { path: "$" + this.fieldName } },
@@ -89,14 +105,15 @@ class MongoArrayService extends mongo_service_js_1.MongoService {
         }
     }
     /**
-     * Removes one item from an array field
+     * Deletes an element from an array within a document in the MongoDB collection.
      *
-     * @param parentId
-     * @param id
-     * @param options
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {AnyId} id - The ID of the element to delete from the array.
+     * @param {MongoArrayService.DeleteOptions<T>} [options] - Additional options for the delete operation.
+     * @return {Promise<number>} - A Promise that resolves to the number of elements deleted (1 if successful, 0 if not).
      */
-    async delete(parentId, id, options) {
-        const matchFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(parentId, [this.collectionKey]);
+    async delete(documentId, id, options) {
+        const matchFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(documentId, [this.collectionKey]);
         const pullFilter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
             mongo_adapter_js_1.MongoAdapter.prepareKeyValues(id, [this.arrayKey]),
             options?.filter
@@ -107,15 +124,16 @@ class MongoArrayService extends mongo_service_js_1.MongoService {
         return r.modifiedCount ? 1 : 0;
     }
     /**
-     * Removes multiple items from an array field
+     * Deletes multiple items from a collection based on the parent ID and optional filter.
      *
-     * @param parentId
-     * @param options
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {MongoArrayService.DeleteManyOptions<T>} options - Optional options to specify a filter.
+     * @returns {Promise<number>} - A Promise that resolves to the number of items deleted.
      */
-    async deleteMany(parentId, options) {
-        const docFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(parentId, [this.collectionKey]);
+    async deleteMany(documentId, options) {
+        const docFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(documentId, [this.collectionKey]);
         // Count matching items, we will use this as result
-        const matchCount = await this.count(parentId, options);
+        const matchCount = await this.count(documentId, options);
         const pullFilter = mongo_adapter_js_1.MongoAdapter.prepareFilter(options?.filter) || {};
         const r = await this.__updateOne(docFilter, {
             $pull: { [this.fieldName]: pullFilter }
@@ -125,48 +143,52 @@ class MongoArrayService extends mongo_service_js_1.MongoService {
         return 0;
     }
     /**
-     * Returns true if item exists, false otherwise
+     * Checks if an array element with the given parentId and id exists.
      *
-     * @param parentId
-     * @param id
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {AnyId} id - The id of the record.
+     * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating if the record exists or not.
      */
-    async exists(parentId, id) {
-        return !!(await this.findById(parentId, id, { pick: ['_id'] }));
+    async exists(documentId, id) {
+        return !!(await this.findById(documentId, id, { pick: ['_id'] }));
     }
     /**
-     * Fetches the first item in an array field that matches by id.
+     * Finds an element in array field by its parent ID and ID.
      *
-     * @param parentId
-     * @param id
-     * @param options
+     * @param {AnyId} documentId - The ID of the document.
+     * @param {AnyId} id - The ID of the document.
+     * @param {MongoArrayService.FindOneOptions} [options] - The optional options for the operation.
+     * @returns {Promise<PartialOutput<T> | undefined>} - A promise that resolves to the found document or undefined if not found.
      */
-    async findById(parentId, id, options) {
+    async findById(documentId, id, options) {
         let filter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(id, [this.arrayKey]);
         if (options?.filter)
             filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([filter, options?.filter]);
-        return await this.findOne(parentId, { ...options, filter });
+        return await this.findOne(documentId, { ...options, filter });
     }
     /**
-     * Fetches the first item in an array field that matches the filter. Returns undefined if not found.
+     * Finds the first array element that matches the given parentId.
      *
-     * @param parentId
-     * @param options
+     * @param {AnyId} documentId - The ID of the document.
+     * @param {MongoArrayService.FindOneOptions} [options] - Optional options to customize the query.
+     * @returns {Promise<PartialOutput<T> | undefined>} A promise that resolves to the first matching document, or `undefined` if no match is found.
      */
-    async findOne(parentId, options) {
-        const rows = await this.findMany(parentId, {
+    async findOne(documentId, options) {
+        const rows = await this.findMany(documentId, {
             ...options,
             limit: 1
         });
         return rows?.[0];
     }
     /**
-     * Fetches all items in an array field that matches the filter
+     * Finds multiple elements in an array field.
      *
-     * @param parentId
-     * @param options
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {MongoArrayService.FindManyOptions<T>} [options] - The options for finding the documents.
+     * @returns {Promise<PartialOutput<T>[] | undefined>} - The found documents.
      */
-    async findMany(parentId, options) {
-        const matchFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(parentId, [this.collectionKey]);
+    async findMany(documentId, options) {
+        const matchFilter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(documentId, [this.collectionKey]);
         const mongoOptions = {
             ...(0, lodash_omit_1.default)(options, ['pick', 'include', 'omit', 'sort', 'skip', 'limit', 'filter', 'count'])
         };
@@ -198,10 +220,11 @@ class MongoArrayService extends mongo_service_js_1.MongoService {
                 dataStages.push({ $sort: sort });
         }
         dataStages.push({ $limit: limit });
-        const dataType = this.getArrayDataType();
+        const dataType = this.getDataType();
         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
         });
@@ -209,7 +232,7 @@ class MongoArrayService 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();
@@ -220,30 +243,34 @@ class MongoArrayService extends mongo_service_js_1.MongoService {
         }
     }
     /**
-     * Fetches the first item in an array field that matches the item id. Throws error undefined if not found.
+     * Retrieves a specific item from the array of a document.
      *
-     * @param parentId
-     * @param id
-     * @param options
+     * @param {AnyId} documentId - The ID of the document.
+     * @param {AnyId} id - The ID of the item.
+     * @param {MongoArrayService.FindOneOptions<T>} [options] - The options for finding the item.
+     * @returns {Promise<PartialOutput<T>>} - The item found.
+     * @throws {ResourceNotFoundError} - If the item is not found.
      */
-    async get(parentId, id, options) {
-        const out = await this.findById(parentId, id, options);
+    async get(documentId, id, options) {
+        const out = await this.findById(documentId, id, options);
         if (!out)
-            throw new common_1.ResourceNotFoundError((this.resourceName || this.getCollectionName()) + '.' + this.arrayKey, parentId + '/' + id);
+            throw new common_1.ResourceNotFoundError((this.resourceName || this.getCollectionName()) + '.' + this.arrayKey, documentId + '/' + id);
         return out;
     }
     /**
-     * Update a single item in array field
+     * Updates an array element with new data and returns the updated element
      *
-     * @param parentId
-     * @param id
-     * @param input
-     * @param options
+     * @param {AnyId} documentId - The ID of the document to update.
+     * @param {AnyId} id - The ID of the item to update within the document.
+     * @param {PartialInput<T>} input - The new data to update the item with.
+     * @param {MongoArrayService.UpdateOptions<T>} [options] - Additional update options.
+     * @returns {Promise<PartialOutput<T> | undefined>} The updated item or undefined if it does not exist.
+     * @throws {Error} If an error occurs while updating the item.
      */
-    async update(parentId, id, input, options) {
-        await this.updateOnly(parentId, id, input, options);
+    async update(documentId, id, input, options) {
+        await this.updateOnly(documentId, id, input, options);
         try {
-            return await this.findById(parentId, id, options);
+            return await this.findById(documentId, id, options);
         }
         catch (e) {
             Error.captureStackTrace(e);
@@ -251,32 +278,35 @@ class MongoArrayService extends mongo_service_js_1.MongoService {
         }
     }
     /**
-     * Update a single item in array field
-     * Returns how many master documents updated (not array items)
+     * Update an array element with new data. Returns 1 if document updated 0 otherwise.
      *
-     * @param parentId
-     * @param id
-     * @param doc
-     * @param options
+     * @param {AnyId} documentId - The ID of the parent document.
+     * @param {AnyId} id - The ID of the document to update.
+     * @param {PartialInput<T>} doc - The partial input object containing the fields to update.
+     * @param {MongoArrayService.UpdateOptions<T>} [options] - Optional update options.
+     * @returns {Promise<number>} - A promise that resolves to the number of elements updated.
      */
-    async updateOnly(parentId, id, doc, options) {
+    async updateOnly(documentId, id, doc, options) {
         let filter = mongo_adapter_js_1.MongoAdapter.prepareKeyValues(id, [this.arrayKey]);
         if (options?.filter)
             filter = mongo_adapter_js_1.MongoAdapter.prepareFilter([filter, options?.filter]);
-        return await this.updateMany(parentId, doc, { ...options, filter });
+        return await this.updateMany(documentId, doc, { ...options, filter });
     }
     /**
-     * Update multiple items in array field, returns how many master documents updated (not array items)
+     * Updates multiple array elements in document
      *
-     * @param parentId
-     * @param input
-     * @param options
+     * @param {AnyId} documentId - The ID of the document to update.
+     * @param {PartialInput<T>} input - The updated data for the document(s).
+     * @param {MongoArrayService.UpdateManyOptions<T>} [options] - Additional options for the update operation.
+     * @returns {Promise<number>} - A promise that resolves to the number of documents updated.
      */
-    async updateMany(parentId, input, options) {
-        const encode = this._getEncoder('update');
+    async updateMany(documentId, input, options) {
+        const encode = this.getEncoder('update');
         const doc = encode(input);
+        if (!Object.keys(doc).length)
+            return 0;
         const matchFilter = mongo_adapter_js_1.MongoAdapter.prepareFilter([
-            mongo_adapter_js_1.MongoAdapter.prepareKeyValues(parentId, [this.collectionKey]),
+            mongo_adapter_js_1.MongoAdapter.prepareKeyValues(documentId, [this.collectionKey]),
             { [this.fieldName]: { $exists: true } }
         ]);
         if (options?.filter) {
@@ -291,54 +321,28 @@ class MongoArrayService extends mongo_service_js_1.MongoService {
         return r.modifiedCount;
     }
     /**
-     * Update multiple items in array field and returns number of updated array items
+     * Updates multiple elements and returns the count of elements that were updated.
      *
-     * @param parentId
-     * @param doc
-     * @param options
+     * @param {AnyId} documentId - The ID of the document to update.
+     * @param {PartialInput<T>} doc - The partial document to update with.
+     * @param {MongoArrayService.UpdateManyOptions<T>} [options] - The options for updating multiple documents.
+     * @return {Promise<number>} A promise that resolves to the number of elements updated.
      */
-    async updateManyReturnCount(parentId, doc, options) {
-        const r = await this.updateMany(parentId, doc, options);
+    async updateManyReturnCount(documentId, doc, options) {
+        const r = await this.updateMany(documentId, doc, options);
         return r
             // Count matching items that fits filter criteria
-            ? await this.count(parentId, options)
+            ? await this.count(documentId, options)
             : 0;
     }
     /**
-     * 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) {
-        const dataType = this.getArrayDataType();
-        const options = {};
-        if (operation === 'update') {
-            options.omit = ['_id'];
-            options.partial = true;
-        }
-        return dataType.generateCodec('encode', options);
-    }
 }
 exports.MongoArrayService = MongoArrayService;