@opra/mongodb 0.33.13 → 1.0.0-alpha.2

package/esm/mongo-nested-service.js

@@ -0,0 +1,569 @@
+import omit from 'lodash.omit';
+import { ComplexType, NotAcceptableError, ResourceNotAvailableError } from '@opra/common';
+import { MongoAdapter } from './mongo-adapter.js';
+import { MongoService } from './mongo-service.js';
+/**
+ * A class that provides methods to perform operations on an array field in a MongoDB collection.
+ * @class MongoNestedService
+ * @template T The type of the array item.
+ */
+export class MongoNestedService extends MongoService {
+    /**
+     * Constructs a new instance
+     *
+     * @param {Type | string} dataType - The data type of the array elements.
+     * @param {string} fieldName - The name of the field in the document representing the array.
+     * @param {MongoNestedService.Options} [options] - The options for the array service.
+     * @constructor
+     */
+    constructor(dataType, fieldName, options) {
+        super(dataType, options);
+        this.fieldName = fieldName;
+        this.nestedKey = options?.nestedKey || '_id';
+        this.defaultLimit = options?.defaultLimit || 10;
+        this.$nestedFilter = options?.$nestedFilter;
+    }
+    /**
+     * Asserts whether a resource with the specified parentId and id exists.
+     * Throws a ResourceNotFoundError if the resource does not exist.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoAdapter.AnyId} id - The ID of the resource.
+     * @param {MongoNestedService.ExistsOptions<T>} [options] - Optional parameters for checking resource existence.
+     * @return {Promise<void>} - A promise that resolves with no value upon success.
+     * @throws {ResourceNotAvailableError} - If the resource does not exist.
+     */
+    async assert(documentId, id, options) {
+        if (!(await this.exists(documentId, id, options)))
+            throw new ResourceNotAvailableError(this.getResourceName() + '.' + this.nestedKey, documentId + '/' + id);
+    }
+    /**
+     * Adds a single item into the array field.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {T} input - The item to be added to the array field.
+     * @param {MongoNestedService.CreateOptions} [options] - Optional options for the create operation.
+     * @return {Promise<PartialDTO<T>>} - A promise that resolves with the partial output of the created item.
+     * @throws {ResourceNotAvailableError} - If the parent document is not found.
+     */
+    async create(documentId, input, options) {
+        const id = input._id || this._generateId();
+        if (id != null)
+            input._id = id;
+        const info = {
+            crud: 'create',
+            method: 'create',
+            byId: false,
+            documentId,
+            nestedId: id,
+            input,
+            options,
+        };
+        return this._intercept(() => this._create(documentId, input, options), info);
+    }
+    async _create(documentId, input, options) {
+        const encode = this.getEncoder('create');
+        const doc = encode(input);
+        doc._id = doc._id || this._generateId();
+        const docFilter = MongoAdapter.prepareKeyValues(documentId, ['_id']);
+        const r = await this._dbUpdateOne(docFilter, {
+            $push: { [this.fieldName]: doc },
+        }, options);
+        if (r.matchedCount) {
+            if (!options)
+                return doc;
+            const id = doc[this.nestedKey];
+            const out = await this._findById(documentId, id, {
+                ...options,
+                filter: undefined,
+                skip: undefined,
+            });
+            if (out)
+                return out;
+        }
+        throw new ResourceNotAvailableError(this.getResourceName(), documentId);
+    }
+    /**
+     * Counts the number of documents in the collection that match the specified parentId and options.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoNestedService.CountOptions<T>} [options] - Optional parameters for counting.
+     * @returns {Promise<number>} - A promise that resolves to the count of documents.
+     */
+    async count(documentId, options) {
+        const info = {
+            crud: 'read',
+            method: 'count',
+            byId: false,
+            documentId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = MongoAdapter.prepareFilter([await this._getDocumentFilter(info)]);
+            const filter = MongoAdapter.prepareFilter([await this._getNestedFilter(info), options?.filter]);
+            return this._count(documentId, { ...options, filter, documentFilter });
+        }, info);
+    }
+    async _count(documentId, options) {
+        const matchFilter = MongoAdapter.prepareFilter([
+            MongoAdapter.prepareKeyValues(documentId, ['_id']),
+            options?.documentFilter,
+        ]);
+        const stages = [
+            { $match: matchFilter },
+            { $unwind: { path: '$' + this.fieldName } },
+            { $replaceRoot: { newRoot: '$' + this.fieldName } },
+        ];
+        if (options?.filter) {
+            const filter = MongoAdapter.prepareFilter(options?.filter);
+            stages.push({ $match: filter });
+        }
+        stages.push({ $count: '*' });
+        const r = await this._dbAggregate(stages, options);
+        try {
+            const n = await r.next();
+            return n?.['*'] || 0;
+        }
+        finally {
+            await r.close();
+        }
+    }
+    /**
+     * Deletes an element from an array within a document in the MongoDB collection.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoAdapter.AnyId} nestedId - The ID of the element to delete from the nested array.
+     * @param {MongoNestedService.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(documentId, nestedId, options) {
+        const info = {
+            crud: 'delete',
+            method: 'delete',
+            byId: true,
+            documentId,
+            nestedId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = MongoAdapter.prepareFilter([await this._getDocumentFilter(info)]);
+            const filter = MongoAdapter.prepareFilter([await this._getNestedFilter(info), options?.filter]);
+            return this._delete(documentId, nestedId, { ...options, filter, documentFilter });
+        }, info);
+    }
+    async _delete(documentId, nestedId, options) {
+        const matchFilter = MongoAdapter.prepareFilter([
+            MongoAdapter.prepareKeyValues(documentId, ['_id']),
+            options?.documentFilter,
+        ]);
+        const pullFilter = MongoAdapter.prepareFilter([MongoAdapter.prepareKeyValues(nestedId, [this.nestedKey]), options?.filter]) || {};
+        const r = await this._dbUpdateOne(matchFilter, {
+            $pull: { [this.fieldName]: pullFilter },
+        }, options);
+        return r.modifiedCount ? 1 : 0;
+    }
+    /**
+     * Deletes multiple items from a collection based on the parent ID and optional filter.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoNestedService.DeleteManyOptions<T>} [options] - Optional options to specify a filter.
+     * @returns {Promise<number>} - A Promise that resolves to the number of items deleted.
+     */
+    async deleteMany(documentId, options) {
+        const info = {
+            crud: 'delete',
+            method: 'deleteMany',
+            byId: false,
+            documentId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = MongoAdapter.prepareFilter([await this._getDocumentFilter(info)]);
+            const filter = MongoAdapter.prepareFilter([await this._getNestedFilter(info), options?.filter]);
+            return this._deleteMany(documentId, { ...options, filter, documentFilter });
+        }, info);
+    }
+    async _deleteMany(documentId, options) {
+        const matchFilter = MongoAdapter.prepareFilter([
+            MongoAdapter.prepareKeyValues(documentId, ['_id']),
+            options?.documentFilter,
+        ]);
+        // Count matching items, we will use this as result
+        const matchCount = await this.count(documentId, options);
+        const pullFilter = MongoAdapter.prepareFilter(options?.filter) || {};
+        const r = await this._dbUpdateOne(matchFilter, {
+            $pull: { [this.fieldName]: pullFilter },
+        }, options);
+        if (r.matchedCount)
+            return matchCount;
+        return 0;
+    }
+    /**
+     * Checks if an array element with the given parentId and id exists.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoAdapter.AnyId} nestedId - The id of the record.
+     * @param {MongoNestedService.ExistsOptions<T>} [options] - The options for the exists method.
+     * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating if the record exists or not.
+     */
+    async exists(documentId, nestedId, options) {
+        return !!(await this.findById(documentId, nestedId, { ...options, projection: ['_id'] }));
+    }
+    /**
+     * Checks if an object with the given arguments exists.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoNestedService.ExistsOneOptions} [options] - The options for the query (optional).
+     * @return {Promise<boolean>} - A Promise that resolves to a boolean indicating whether the object exists or not.
+     */
+    async existsOne(documentId, options) {
+        return !!(await this.findOne(documentId, { ...options, projection: ['_id'] }));
+    }
+    /**
+     * Finds an element in array field by its parent ID and ID.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the document.
+     * @param {MongoAdapter.AnyId} nestedId - The ID of the document.
+     * @param {MongoNestedService.FindOneOptions<T>} [options] - The optional options for the operation.
+     * @returns {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the found document or undefined if not found.
+     */
+    async findById(documentId, nestedId, options) {
+        const info = {
+            crud: 'read',
+            method: 'findById',
+            byId: true,
+            documentId,
+            nestedId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = MongoAdapter.prepareFilter([await this._getDocumentFilter(info)]);
+            const filter = MongoAdapter.prepareFilter([await this._getNestedFilter(info), options?.filter]);
+            return this._findById(documentId, nestedId, { ...options, filter, documentFilter });
+        }, info);
+    }
+    async _findById(documentId, nestedId, options) {
+        const filter = MongoAdapter.prepareFilter([
+            MongoAdapter.prepareKeyValues(nestedId, [this.nestedKey]),
+            options?.filter,
+        ]);
+        const rows = await this._findMany(documentId, {
+            ...options,
+            filter,
+            limit: 1,
+            skip: undefined,
+            sort: undefined,
+        });
+        return rows?.[0];
+    }
+    /**
+     * Finds the first array element that matches the given parentId.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the document.
+     * @param {MongoNestedService.FindOneOptions<T>} [options] - Optional options to customize the query.
+     * @returns {Promise<PartialDTO<T> | undefined>} A promise that resolves to the first matching document, or `undefined` if no match is found.
+     */
+    async findOne(documentId, options) {
+        const info = {
+            crud: 'read',
+            method: 'findOne',
+            byId: false,
+            documentId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = MongoAdapter.prepareFilter([await this._getDocumentFilter(info)]);
+            const filter = MongoAdapter.prepareFilter([await this._getNestedFilter(info), options?.filter]);
+            return this._findOne(documentId, { ...options, filter, documentFilter });
+        }, info);
+    }
+    async _findOne(documentId, options) {
+        const rows = await this._findMany(documentId, {
+            ...options,
+            limit: 1,
+        });
+        return rows?.[0];
+    }
+    /**
+     * Finds multiple elements in an array field.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoNestedService.FindManyOptions<T>} [options] - The options for finding the documents.
+     * @returns {Promise<PartialDTO<T>[]>} - The found documents.
+     */
+    async findMany(documentId, options) {
+        const args = {
+            crud: 'read',
+            method: 'findMany',
+            byId: false,
+            documentId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = await this._getDocumentFilter(args);
+            const nestedFilter = await this._getNestedFilter(args);
+            return this._findMany(documentId, {
+                ...options,
+                documentFilter,
+                nestedFilter,
+                limit: options?.limit || this.defaultLimit,
+            });
+        }, args);
+    }
+    async _findMany(documentId, options) {
+        const matchFilter = MongoAdapter.prepareFilter([
+            MongoAdapter.prepareKeyValues(documentId, ['_id']),
+            options.documentFilter,
+        ]);
+        const mongoOptions = {
+            ...omit(options, ['documentFilter', 'nestedFilter', 'projection', 'sort', 'skip', 'limit', 'filter', 'count']),
+        };
+        const limit = options?.limit || this.defaultLimit;
+        const stages = [
+            { $match: matchFilter },
+            { $unwind: { path: '$' + this.fieldName } },
+            { $replaceRoot: { newRoot: '$' + this.fieldName } },
+        ];
+        if (options?.filter || options.nestedFilter) {
+            const optionsFilter = MongoAdapter.prepareFilter([options?.filter, options.nestedFilter]);
+            stages.push({ $match: optionsFilter });
+        }
+        if (options?.skip)
+            stages.push({ $skip: options.skip });
+        if (options?.sort) {
+            const sort = MongoAdapter.prepareSort(options.sort);
+            if (sort)
+                stages.push({ $sort: sort });
+        }
+        stages.push({ $limit: limit });
+        const dataType = this.getDataType();
+        const projection = MongoAdapter.prepareProjection(dataType, options?.projection);
+        if (projection)
+            stages.push({ $project: projection });
+        const decode = this.getDecoder();
+        const cursor = await this._dbAggregate(stages, mongoOptions);
+        try {
+            const out = await (await cursor.toArray()).map((r) => decode(r));
+            return out;
+        }
+        finally {
+            if (!cursor.closed)
+                await cursor.close();
+        }
+    }
+    /**
+     * Finds multiple elements in an array field.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoNestedService.FindManyOptions<T>} [options] - The options for finding the documents.
+     * @returns {Promise<PartialDTO<T>[]>} - The found documents.
+     */
+    async findManyWithCount(documentId, options) {
+        const args = {
+            crud: 'read',
+            method: 'findMany',
+            byId: false,
+            documentId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = await this._getDocumentFilter(args);
+            const nestedFilter = await this._getNestedFilter(args);
+            return this._findManyWithCount(documentId, {
+                ...options,
+                documentFilter,
+                nestedFilter,
+                limit: options?.limit || this.defaultLimit,
+            });
+        }, args);
+    }
+    async _findManyWithCount(documentId, options) {
+        const matchFilter = MongoAdapter.prepareFilter([
+            MongoAdapter.prepareKeyValues(documentId, ['_id']),
+            options.documentFilter,
+        ]);
+        const mongoOptions = {
+            ...omit(options, ['pick', 'include', 'omit', 'sort', 'skip', 'limit', 'filter', 'count']),
+        };
+        const limit = options?.limit || this.defaultLimit;
+        const dataStages = [];
+        const stages = [
+            { $match: matchFilter },
+            { $unwind: { path: '$' + this.fieldName } },
+            { $replaceRoot: { newRoot: '$' + this.fieldName } },
+            {
+                $facet: {
+                    data: dataStages,
+                    count: [{ $count: 'totalMatches' }],
+                },
+            },
+        ];
+        if (options?.filter || options.nestedFilter) {
+            const optionsFilter = MongoAdapter.prepareFilter([options?.filter, options.nestedFilter]);
+            dataStages.push({ $match: optionsFilter });
+        }
+        if (options?.skip)
+            dataStages.push({ $skip: options.skip });
+        if (options?.sort) {
+            const sort = MongoAdapter.prepareSort(options.sort);
+            if (sort)
+                dataStages.push({ $sort: sort });
+        }
+        dataStages.push({ $limit: limit });
+        const dataType = this.getDataType();
+        const projection = MongoAdapter.prepareProjection(dataType, options?.projection);
+        if (projection)
+            dataStages.push({ $project: projection });
+        const decode = this.getDecoder();
+        const cursor = await this._dbAggregate(stages, {
+            ...mongoOptions,
+        });
+        try {
+            const facetResult = await cursor.toArray();
+            return {
+                count: facetResult[0].count[0].totalMatches || 0,
+                items: facetResult[0].data.map((r) => decode(r)),
+            };
+        }
+        finally {
+            if (!cursor.closed)
+                await cursor.close();
+        }
+    }
+    /**
+     * Retrieves a specific item from the array of a document.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the document.
+     * @param {MongoAdapter.AnyId} nestedId - The ID of the item.
+     * @param {MongoNestedService.FindOneOptions<T>} [options] - The options for finding the item.
+     * @returns {Promise<PartialDTO<T>>} - The item found.
+     * @throws {ResourceNotAvailableError} - If the item is not found.
+     */
+    async get(documentId, nestedId, options) {
+        const out = await this.findById(documentId, nestedId, options);
+        if (!out)
+            throw new ResourceNotAvailableError(this.getResourceName() + '.' + this.nestedKey, documentId + '/' + nestedId);
+        return out;
+    }
+    /**
+     * Updates an array element with new data and returns the updated element
+     *
+     * @param {AnyId} documentId - The ID of the document to update.
+     * @param {AnyId} nestedId - The ID of the item to update within the document.
+     * @param {PatchDTO<T>} input - The new data to update the item with.
+     * @param {MongoNestedService.UpdateOptions<T>} [options] - Additional update options.
+     * @returns {Promise<PartialDTO<T> | undefined>} The updated item or undefined if it does not exist.
+     * @throws {Error} If an error occurs while updating the item.
+     */
+    async update(documentId, nestedId, input, options) {
+        const r = await this.updateOnly(documentId, nestedId, input, options);
+        if (!r)
+            return;
+        const out = await this._findById(documentId, nestedId, {
+            ...options,
+            sort: undefined,
+        });
+        if (out)
+            return out;
+        throw new ResourceNotAvailableError(this.getResourceName() + '.' + this.nestedKey, documentId + '/' + nestedId);
+    }
+    /**
+     * Update an array element with new data. Returns 1 if document updated 0 otherwise.
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
+     * @param {MongoAdapter.AnyId} nestedId - The ID of the document to update.
+     * @param {PatchDTO<T>} input - The partial input object containing the fields to update.
+     * @param {MongoNestedService.UpdateOptions<T>} [options] - Optional update options.
+     * @returns {Promise<number>} - A promise that resolves to the number of elements updated.
+     */
+    async updateOnly(documentId, nestedId, input, options) {
+        const info = {
+            crud: 'update',
+            method: 'update',
+            byId: true,
+            documentId,
+            nestedId,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = MongoAdapter.prepareFilter([await this._getDocumentFilter(info)]);
+            const filter = MongoAdapter.prepareFilter([await this._getNestedFilter(info), options?.filter]);
+            return this._updateOnly(documentId, nestedId, input, { ...options, filter, documentFilter });
+        }, info);
+    }
+    async _updateOnly(documentId, nestedId, input, options) {
+        let filter = MongoAdapter.prepareKeyValues(nestedId, [this.nestedKey]);
+        if (options?.filter)
+            filter = MongoAdapter.prepareFilter([filter, options?.filter]);
+        return await this._updateMany(documentId, input, { ...options, filter });
+    }
+    /**
+     * Updates multiple array elements in document
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the document to update.
+     * @param {PatchDTO<T>} input - The updated data for the document(s).
+     * @param {MongoNestedService.UpdateManyOptions<T>} [options] - Additional options for the update operation.
+     * @returns {Promise<number>} - A promise that resolves to the number of documents updated.
+     */
+    async updateMany(documentId, input, options) {
+        const info = {
+            crud: 'update',
+            method: 'updateMany',
+            documentId,
+            byId: false,
+            input,
+            options,
+        };
+        return this._intercept(async () => {
+            const documentFilter = MongoAdapter.prepareFilter([await this._getDocumentFilter(info)]);
+            const filter = MongoAdapter.prepareFilter([await this._getNestedFilter(info), options?.filter]);
+            return this._updateMany(documentId, input, { ...options, filter, documentFilter });
+        }, info);
+    }
+    async _updateMany(documentId, input, options) {
+        const encode = this.getEncoder('update');
+        const doc = encode(input, { coerce: true });
+        if (!Object.keys(doc).length)
+            return 0;
+        const matchFilter = MongoAdapter.prepareFilter([
+            MongoAdapter.prepareKeyValues(documentId, ['_id']),
+            options?.documentFilter,
+            { [this.fieldName]: { $exists: true } },
+        ]);
+        if (options?.filter) {
+            const elemMatch = MongoAdapter.prepareFilter([options?.filter], { fieldPrefix: 'elem.' });
+            options = options || {};
+            options.arrayFilters = [elemMatch];
+        }
+        const update = MongoAdapter.preparePatch(doc, {
+            fieldPrefix: this.fieldName + (options?.filter ? '.$[elem].' : '.$[].'),
+        });
+        const r = await this._dbUpdateOne(matchFilter, update, options);
+        if (options?.count)
+            return await this._count(documentId, options);
+        return r.modifiedCount || 0;
+    }
+    /**
+     * 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 ComplexType))
+            throw new NotAcceptableError(`Data type "${t.name}" is not a ComplexType`);
+        return t;
+    }
+    /**
+     * Retrieves the common filter used for querying array elements.
+     * This method is mostly used for security issues like securing multi-tenant applications.
+     *
+     * @protected
+     * @returns {FilterInput | Promise<FilterInput> | undefined} The common filter or a Promise
+     * that resolves to the common filter, or undefined if not available.
+     */
+    _getNestedFilter(args) {
+        return typeof this.$nestedFilter === 'function' ? this.$nestedFilter(args, this) : this.$nestedFilter;
+    }
+}