@opra/mongodb 0.32.3 → 0.32.4

package/esm/mongo-singleton-service.js

@@ -9,10 +9,19 @@ import { MongoService } from './mongo-service.js';
  * @template T - The type of document stored in the collection
  */
 export class MongoSingletonService extends MongoService {
+    /**
+     * Constructs a new instance
+     *
+     * @param {Type | string} dataType - The data type of the array elements.
+     * @param {MongoSingletonService.Options} [options] - The options for the array service.
+     * @constructor
+     */
     constructor(dataType, options) {
         super(dataType, options);
-        this.collectionKey = options?.collectionKey || '_id';
-        this._id = options?._id || new ObjectId('655608925cad472b75fc6485');
+        this.collectionKey = this.collectionKey || options?.collectionKey || '_id';
+        this._id = this._id || options?._id || new ObjectId('655608925cad472b75fc6485');
+        this.$documentFilter = this.$documentFilter || options?.documentFilter;
+        this.$interceptor = this.$interceptor || options?.interceptor;
     }
     /**
      * Asserts the existence of a resource based on the given options.
@@ -20,19 +29,26 @@ export class MongoSingletonService extends MongoService {
      * @returns {Promise<void>} A Promise that resolves when the resource exists.
      * @throws {ResourceNotFoundError} If the resource does not exist.
      */
-    async assert() {
-        if (!(await this.exists()))
-            throw new ResourceNotFoundError(this.resourceName || this.getCollectionName());
+    async assert(options) {
+        if (!(await this.exists(options)))
+            throw new ResourceNotFoundError(this.getResourceName());
     }
     /**
      * Creates the document in the database.
      *
-     * @param {PartialInput<T>} input - The partial input to create the document with.
+     * @param {DTO<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.
+     * @return {Promise<PartialDTO<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(input, options) {
+        if (this.$interceptor && !options?.__interceptor__)
+            return this.$interceptor(() => this.create(input, { ...options, __interceptor__: true }), {
+                crud: 'create',
+                method: 'create',
+                input,
+                options,
+            }, this);
         const encode = this.getEncoder('create');
         const doc = encode(input);
         doc._id = this._id;
@@ -58,7 +74,17 @@ export class MongoSingletonService extends MongoService {
      * @returns {Promise<number>} The number of records deleted
      */
     async delete(options) {
-        const filter = MongoAdapter.prepareFilter([{ _id: this._id }, options?.filter]);
+        if (this.$interceptor && !options?.__interceptor__)
+            return this.$interceptor(() => this.delete({ ...options, __interceptor__: true }), {
+                crud: 'delete',
+                method: 'delete',
+                options,
+            }, this);
+        const filter = MongoAdapter.prepareFilter([
+            { _id: this._id },
+            await this._getDocumentFilter(),
+            options?.filter
+        ]);
         const r = await this.__deleteOne(filter, options);
         return r.deletedCount;
     }
@@ -67,17 +93,33 @@ export class MongoSingletonService extends MongoService {
      *
      * @return {Promise<boolean>} - A promise that resolves to a boolean value indicating if the document exists.
      */
-    async exists() {
-        return !!(await this.findOne({ pick: ['_id'] }));
+    async exists(options) {
+        if (this.$interceptor && !options?.__interceptor__)
+            return this.$interceptor(() => this.exists({ ...options, __interceptor__: true }), {
+                crud: 'read',
+                method: 'exists',
+                options,
+            }, this);
+        return !!(await this.findOne({ ...options, pick: ['_id'] }));
     }
     /**
      * Fetches the document if it exists. Returns undefined if not found.
      *
      * @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.
+     * @returns {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the found document or undefined if not found.
      */
     async findOne(options) {
-        const filter = MongoAdapter.prepareFilter([{ _id: this._id }, options?.filter]);
+        if (this.$interceptor && !options?.__interceptor__)
+            return this.$interceptor(() => this.findOne({ ...options, __interceptor__: true }), {
+                crud: 'read',
+                method: 'find',
+                options,
+            }, this);
+        const filter = MongoAdapter.prepareFilter([
+            { _id: this._id },
+            await this._getDocumentFilter(),
+            options?.filter
+        ]);
         const mongoOptions = {
             ...options,
             projection: MongoAdapter.prepareProjection(this.getDataType(), options),
@@ -85,30 +127,72 @@ export class MongoSingletonService extends MongoService {
             skip: undefined,
             limit: undefined
         };
-        return await this.__findOne(filter, mongoOptions);
+        const decoder = this.getDecoder();
+        const out = await this.__findOne(filter, mongoOptions);
+        return out ? decoder(out) : undefined;
     }
     /**
      * Fetches the document from the Mongo collection service. Throws error if not found.
      *
      * @param {MongoCollectionService.FindOneOptions} options - The options to customize the query.
-     * @return {Promise<PartialOutput<T>>} - A promise that resolves to the fetched document.
+     * @return {Promise<PartialDTO<T>>} - A promise that resolves to the fetched document.
      * @throws {ResourceNotFoundError} - If the document is not found in the collection.
      */
     async get(options) {
         const out = await this.findOne(options);
         if (!out)
-            throw new ResourceNotFoundError(this.resourceName || this.getCollectionName());
+            throw new ResourceNotFoundError(this.getResourceName());
         return out;
     }
     /**
      * Updates a document in the MongoDB collection.
      *
-     * @param {PartialInput<T>} input - The partial input to update the document.
+     * @param {PatchDTO<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.
+     * @return {Promise<number>} - A promise that resolves to the updated document or undefined if not found.
+     */
+    async updateOnly(input, options) {
+        if (this.$interceptor && !options?.__interceptor__)
+            return this.$interceptor(() => this.updateOnly(input, { ...options, __interceptor__: true }), {
+                crud: 'update',
+                method: 'update',
+                input,
+                options,
+            }, this);
+        const encode = this.getEncoder('update');
+        const doc = encode(input);
+        const patch = MongoAdapter.preparePatch(doc);
+        const mongoOptions = {
+            ...options,
+            includeResultMetadata: false,
+            upsert: undefined,
+            projection: MongoAdapter.prepareProjection(this.getDataType(), options),
+        };
+        const filter = MongoAdapter.prepareFilter([
+            { _id: this._id },
+            await this._getDocumentFilter(),
+            options?.filter
+        ]);
+        const r = await this.__updateOne(filter, patch, mongoOptions);
+        return r.modifiedCount;
+    }
+    /**
+     * Updates a document in the MongoDB collection.
+     *
+     * @param {PatchDTO<T>} input - The partial input to update the document.
+     * @param {MongoSingletonService.UpdateOptions<T>} [options] - The update options.
+     *
+     * @return {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the updated document or undefined if not found.
      */
     async update(input, options) {
+        if (this.$interceptor && !options?.__interceptor__)
+            return this.$interceptor(() => this.update(input, { ...options, __interceptor__: true }), {
+                crud: 'update',
+                method: 'update',
+                input,
+                options,
+            }, this);
         const encode = this.getEncoder('update');
         const doc = encode(input);
         const patch = MongoAdapter.preparePatch(doc);
@@ -120,10 +204,23 @@ export class MongoSingletonService extends MongoService {
         };
         const filter = MongoAdapter.prepareFilter([
             { _id: this._id },
+            await this._getDocumentFilter(),
             options?.filter
         ]);
         const decoder = this.getDecoder();
         const out = await this.__findOneAndUpdate(filter, patch, mongoOptions);
         return out ? decoder(out) : undefined;
     }
+    /**
+     * Retrieves the common filter used for querying the document.
+     * 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.
+     */
+    _getDocumentFilter() {
+        return typeof this.$documentFilter === 'function' ?
+            this.$documentFilter(this) : this.$documentFilter;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/mongodb",
-  "version": "0.32.3",
+  "version": "0.32.4",
   "description": "Opra MongoDB adapter package",
   "author": "Panates",
   "license": "MIT",
@@ -26,14 +26,12 @@
   },
   "devDependencies": {
     "@faker-js/faker": "^8.3.1",
-    "@types/lodash.isnil": "^4.0.9",
-    "@types/lodash.omitby": "^4.6.9",
     "mongodb": "^6.3.0",
-    "ts-gems": "^2.7.1"
+    "ts-gems": "^2.8.0"
   },
   "peerDependencies": {
-    "@opra/common": "^0.32.3",
-    "@opra/core": "^0.32.3",
+    "@opra/common": "^0.32.4",
+    "@opra/core": "^0.32.4",
     "mongodb": ">=6.x.x"
   },
   "type": "module",

package/types/adapter-utils/prepare-filter.d.ts

@@ -1,12 +1,15 @@
 import mongodb from 'mongodb';
 import { OpraFilter } from '@opra/common';
-type FilterInput = (OpraFilter.Expression | mongodb.Filter<any> | string | undefined);
+export type FilterInput = (OpraFilter.Expression | mongodb.Filter<any> | string | undefined);
 /**
- * Convert filter expressions to MongoDB filter objects.
- * This method also merges multiple expressions into one single filter object
- * @param filters
+ * Prepare the MongoDB filter based on the provided filters and options.
+ *
+ * @param {FilterInput|FilterInput[]} filters - The filter(s) to be applied.
+ * @param {Object} [options] - Additional options.
+ * @param {string} [options.fieldPrefix] - The prefix to be added to field names.
+ *
+ * @returns {mongodb.Filter<any>} - The prepared MongoDB filter.
  */
 export default function prepareFilter(filters: FilterInput | FilterInput[], options?: {
     fieldPrefix?: string;
 }): mongodb.Filter<any>;
-export {};

package/types/mongo-array-service.d.ts

@@ -1,9 +1,8 @@
 import mongodb from 'mongodb';
 import { StrictOmit, Type } from 'ts-gems';
 import * as OpraCommon from '@opra/common';
-import { ComplexType, PartialInput } from '@opra/common';
-import { PartialOutput } from '@opra/core';
-import { MongoCollectionService } from './mongo-collection-service.js';
+import { ComplexType, DTO, PartialDTO, PatchDTO } from '@opra/common';
+import { FilterInput } from './adapter-utils/prepare-filter.js';
 import { MongoService } from './mongo-service.js';
 import { AnyId } from './types.js';
 /**
@@ -35,34 +34,70 @@ export declare class MongoArrayService<T extends mongodb.Document> extends Mongo
      * @type {number}
      */
     defaultLimit: number;
-    constructor(dataType: Type | string, fieldName: string, options?: MongoArrayService.Options);
     /**
-     * Retrieves the data type of the array field
+     * Represents a common document filter function for a MongoCollectionService.
      *
-     * @returns {ComplexType} The complex data type of the field.
-     * @throws {NotAcceptableError} If the data type is not a ComplexType.
+     * @type {FilterInput
      */
-    getDataType(): ComplexType;
+    $documentFilter?: FilterInput | ((_this: this) => FilterInput | Promise<FilterInput> | undefined);
+    /**
+     * Represents a common array filter function for a MongoCollectionService.
+     *
+     * @type {FilterInput | MongoCollectionService.CommonFilterFunction}
+     */
+    $arrayFilter?: FilterInput | ((_this: this) => FilterInput | Promise<FilterInput> | undefined);
+    /**
+     * Interceptor function for handling callback execution with provided arguments.
+     *
+     * @param {Function} callback - The callback function to be intercepted.
+     * @param {Object} args - The arguments object containing the following properties:
+     *   @param {string} crud - The CRUD operation type.
+     *   @param {string} method - The method name.
+     *   @param {AnyId} documentId - The document ID (optional).
+     *   @param {AnyId} itemId -  ID for an item. (optional).
+     *   @param {Object} input - The input object (optional).
+     *   @param {Object} options - Additional options (optional).
+     * @param {Object} _this - The reference to the current object.
+     * @returns {Promise<any>} - The promise that resolves to the result of the callback execution.
+     */
+    $interceptor?: (callback: (...args: any[]) => any, args: {
+        crud: MongoService.CrudOp;
+        method: string;
+        documentId?: AnyId;
+        itemId?: AnyId;
+        input?: Object;
+        options?: Record<string, any>;
+    }, _this: any) => Promise<any>;
+    /**
+     * 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 {MongoArrayService.Options} [options] - The options for the array service.
+     * @constructor
+     */
+    constructor(dataType: Type | string, fieldName: string, options?: MongoArrayService.Options);
     /**
      * Asserts whether a resource with the specified parentId and id exists.
      * Throws a ResourceNotFoundError if the resource does not exist.
      *
      * @param {AnyId} documentId - The ID of the parent document.
      * @param {AnyId} id - The ID of the resource.
+     * @param {MongoArrayService.ExistsOptions} [options] - Optional parameters for checking resource existence.
      * @return {Promise<void>} - A promise that resolves with no value upon success.
      * @throws {ResourceNotFoundError} - If the resource does not exist.
      */
-    assert(documentId: AnyId, id: AnyId): Promise<void>;
+    assert(documentId: AnyId, id: AnyId, options?: MongoArrayService.ExistsOptions): Promise<void>;
     /**
      * Adds a single item into the array field.
      *
      * @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.
+     * @return {Promise<PartialDTO<T>>} - A promise that resolves with the partial output of the created item.
      * @throws {ResourceNotFoundError} - If the parent document is not found.
      */
-    create(documentId: AnyId, input: T, options?: MongoArrayService.CreateOptions): Promise<PartialOutput<T>>;
+    create(documentId: AnyId, input: DTO<T>, options?: MongoArrayService.CreateOptions): Promise<PartialDTO<T>>;
     /**
      * Counts the number of documents in the collection that match the specified parentId and options.
      *
@@ -94,90 +129,116 @@ export declare class MongoArrayService<T extends mongodb.Document> extends Mongo
      *
      * @param {AnyId} documentId - The ID of the parent document.
      * @param {AnyId} id - The id of the record.
+     * @param {MongoArrayService.ExistsOptions} [options] - The options for the exists method.
      * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating if the record exists or not.
      */
-    exists(documentId: AnyId, id: AnyId): Promise<boolean>;
+    exists(documentId: AnyId, id: AnyId, options?: MongoArrayService.ExistsOptions): Promise<boolean>;
     /**
      * Finds an element in array field by its parent ID and ID.
      *
      * @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.
+     * @returns {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the found document or undefined if not found.
      */
-    findById(documentId: AnyId, id: AnyId, options?: MongoArrayService.FindOneOptions): Promise<PartialOutput<T> | undefined>;
+    findById(documentId: AnyId, id: AnyId, options?: MongoArrayService.FindOneOptions): Promise<PartialDTO<T> | undefined>;
     /**
      * Finds the first array element that matches the given parentId.
      *
      * @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.
+     * @returns {Promise<PartialDTO<T> | undefined>} A promise that resolves to the first matching document, or `undefined` if no match is found.
      */
-    findOne(documentId: AnyId, options?: MongoArrayService.FindOneOptions): Promise<PartialOutput<T> | undefined>;
+    findOne(documentId: AnyId, options?: MongoArrayService.FindOneOptions): Promise<PartialDTO<T> | undefined>;
     /**
      * Finds multiple elements in an array field.
      *
      * @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.
+     * @returns {Promise<PartialDTO<T>[]>} - The found documents.
      */
-    findMany(documentId: AnyId, options?: MongoArrayService.FindManyOptions<T>): Promise<PartialOutput<T>[] | undefined>;
+    findMany(documentId: AnyId, options?: MongoArrayService.FindManyOptions<T>): Promise<PartialDTO<T>[]>;
     /**
      * Retrieves a specific item from the array of a document.
      *
      * @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.
+     * @returns {Promise<PartialDTO<T>>} - The item found.
      * @throws {ResourceNotFoundError} - If the item is not found.
      */
-    get(documentId: AnyId, id: AnyId, options?: MongoArrayService.FindOneOptions<T>): Promise<PartialOutput<T>>;
+    get(documentId: AnyId, id: AnyId, options?: MongoArrayService.FindOneOptions<T>): Promise<PartialDTO<T>>;
     /**
      * Updates an array element with new data and returns the updated element
      *
      * @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 {PatchDTO<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.
+     * @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.
      */
-    update(documentId: AnyId, id: AnyId, input: PartialInput<T>, options?: MongoArrayService.UpdateOptions<T>): Promise<PartialOutput<T> | undefined>;
+    update(documentId: AnyId, id: AnyId, input: PatchDTO<T>, options?: MongoArrayService.UpdateOptions<T>): Promise<PartialDTO<T> | undefined>;
     /**
      * Update an array element with new data. Returns 1 if document updated 0 otherwise.
      *
      * @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 {PatchDTO<T>} input - 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.
      */
-    updateOnly(documentId: AnyId, id: AnyId, doc: PartialInput<T>, options?: MongoArrayService.UpdateOptions<T>): Promise<number>;
+    updateOnly(documentId: AnyId, id: AnyId, input: PatchDTO<T>, options?: MongoArrayService.UpdateOptions<T>): Promise<number>;
     /**
      * Updates multiple array elements in document
      *
      * @param {AnyId} documentId - The ID of the document to update.
-     * @param {PartialInput<T>} input - The updated data for the document(s).
+     * @param {PatchDTO<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.
      */
-    updateMany(documentId: AnyId, input: PartialInput<T>, options?: MongoArrayService.UpdateManyOptions<T>): Promise<number>;
+    updateMany(documentId: AnyId, input: PatchDTO<T>, options?: MongoArrayService.UpdateManyOptions<T>): Promise<number>;
     /**
      * Updates multiple elements and returns the count of elements that were updated.
      *
      * @param {AnyId} documentId - The ID of the document to update.
-     * @param {PartialInput<T>} doc - The partial document to update with.
+     * @param {PatchDTO<T>} input - 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.
      */
-    updateManyReturnCount(documentId: AnyId, doc: PartialInput<T>, options?: MongoArrayService.UpdateManyOptions<T>): Promise<number>;
+    updateManyReturnCount(documentId: AnyId, input: PatchDTO<T>, options?: MongoArrayService.UpdateManyOptions<T>): Promise<number>;
     /**
-     * Generates a new id for new inserting Document.
+     * 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(): ComplexType;
+    /**
+     * Generates an ID.
      *
      * @protected
-     * @returns {AnyId} A new instance of AnyId.
+     * @returns {AnyId} The generated ID.
      */
     protected _generateId(): AnyId;
+    /**
+     * Retrieves the common filter used for querying documents.
+     * 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.
+     */
+    protected _getDocumentFilter(): FilterInput | Promise<FilterInput> | undefined;
+    /**
+     * 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.
+     */
+    protected _getArrayFilter(): FilterInput | Promise<FilterInput> | undefined;
 }
 /**
  *
@@ -187,8 +248,13 @@ export declare namespace MongoArrayService {
     /**
      * The constructor options of MongoArrayService.
      */
-    interface Options extends MongoCollectionService.Options {
-        arrayKey?: string;
+    interface Options extends MongoService.Options {
+        collectionKey?: MongoArrayService<any>['collectionKey'];
+        defaultLimit?: MongoArrayService<any>['defaultLimit'];
+        arrayKey?: MongoArrayService<any>['arrayKey'];
+        documentFilter?: MongoArrayService<any>['$documentFilter'];
+        arrayFilter?: MongoArrayService<any>['$arrayFilter'];
+        interceptor?: MongoArrayService<any>['$interceptor'];
     }
     /**
      * Represents options for creating objects.
@@ -272,4 +338,11 @@ export declare namespace MongoArrayService {
     interface UpdateManyOptions<T> extends mongodb.UpdateOptions {
         filter?: mongodb.Filter<T> | OpraCommon.OpraFilter.Ast | string;
     }
+    /**
+     * Represents options for checking the document exists
+     *
+     * @interface
+     */
+    interface ExistsOptions extends Omit<mongodb.CommandOperationOptions, 'writeConcern'> {
+    }
 }