@opra/mongodb 0.32.3 → 0.32.5

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

@@ -1,7 +1,8 @@
 import mongodb from 'mongodb';
 import { StrictOmit, Type } from 'ts-gems';
+import { DTO, PartialDTO, PatchDTO } from '@opra/common';
 import * as OpraCommon from '@opra/common';
-import { PartialInput, PartialOutput } from '@opra/core';
+import { FilterInput } from './adapter-utils/prepare-filter.js';
 import { MongoService } from './mongo-service.js';
 import { AnyId } from './types.js';
 /**
@@ -21,25 +22,59 @@ export declare class MongoCollectionService<T extends mongodb.Document> extends
      * @type {number}
      */
     defaultLimit: number;
+    /**
+     * Represents a common filter function for a MongoCollectionService.
+     *
+     * @type {FilterInput | Function}
+     */
+    $documentFilter?: 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 {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;
+        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 {MongoCollectionService.Options} [options] - The options for the array service.
+     * @constructor
+     */
     constructor(dataType: Type | string, options?: MongoCollectionService.Options);
     /**
      * Asserts the existence of a resource with the given ID.
      * Throws a ResourceNotFoundError if the resource does not exist.
      *
      * @param {AnyId} id - The ID of the resource to assert.
+     * @param {MongoCollectionService.ExistsOptions} [options] - Optional options for checking the existence.
      * @returns {Promise<void>} - A Promise that resolves when the resource exists.
      * @throws {ResourceNotFoundError} - If the resource does not exist.
      */
-    assert(id: AnyId): Promise<void>;
+    assert(id: AnyId, options?: MongoCollectionService.ExistsOptions): Promise<void>;
     /**
      * Creates a new document in the MongoDB collection.
      *
-     * @param {PartialInput<T>} input - The input data for creating the document.
+     * @param {DTO<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.
+     * @returns {Promise<PartialDTO<T>>} A promise that resolves to the created document.
      * @throws {Error} if an unknown error occurs while creating the document.
      */
-    create(input: PartialInput<T>, options?: MongoCollectionService.CreateOptions): Promise<PartialOutput<T>>;
+    create(input: DTO<T>, options?: MongoCollectionService.CreateOptions): Promise<PartialDTO<T>>;
     /**
      * Returns the count of documents in the collection based on the provided options.
      *
@@ -66,24 +101,25 @@ export declare class MongoCollectionService<T extends mongodb.Document> extends
      * Checks if an object with the given id exists.
      *
      * @param {AnyId} id - The id of the object to check.
+     * @param {MongoCollectionService.ExistsOptions} [options] - The options for the aggregation query (optional).
      * @return {Promise<boolean>} - A Promise that resolves to a boolean indicating whether the object exists or not.
      */
-    exists(id: AnyId): Promise<boolean>;
+    exists(id: AnyId, options?: MongoCollectionService.ExistsOptions): Promise<boolean>;
     /**
      * Finds a document by its ID.
      *
      * @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.
+     * @return {Promise<PartialDTO<T | undefined>>} - A promise resolving to the found document, or undefined if not found.
      */
-    findById(id: AnyId, options?: MongoCollectionService.FindOneOptions): Promise<PartialOutput<T | undefined>>;
+    findById(id: AnyId, options?: MongoCollectionService.FindOneOptions): Promise<PartialDTO<T> | undefined>;
     /**
      * Finds a document in the collection that matches the specified 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.
+     * @return {Promise<PartialDTO<T> | undefined>} A promise that resolves with the found document or undefined if no document is found.
      */
-    findOne(options?: MongoCollectionService.FindOneOptions): Promise<PartialOutput<T> | undefined>;
+    findOne(options?: MongoCollectionService.FindOneOptions): Promise<PartialDTO<T> | undefined>;
     /**
      * Finds multiple documents in the MongoDB collection.
      *
@@ -99,51 +135,60 @@ export declare class MongoCollectionService<T extends mongodb.Document> extends
      *
      * @return A Promise that resolves to an array of partial outputs of type T.
      */
-    findMany(options?: MongoCollectionService.FindManyOptions<T>): Promise<PartialOutput<T>[]>;
+    findMany(options?: MongoCollectionService.FindManyOptions<T>): Promise<PartialDTO<T>[]>;
     /**
      * Retrieves a document from the collection by its ID. Throws error if not found.
      *
      * @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,
+     * @returns {Promise<PartialDTO<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.
      */
-    get(id: AnyId, options?: MongoCollectionService.FindOneOptions): Promise<PartialOutput<T>>;
+    get(id: AnyId, options?: MongoCollectionService.FindOneOptions): Promise<PartialDTO<T>>;
     /**
      * Updates a document with the given id in the collection.
      *
      * @param {any} id - The id of the document to update.
-     * @param {PartialInput<T>} input - The partial input object containing the fields to update.
+     * @param {PatchDTO<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
+     * @returns {Promise<PartialDTO<T> | undefined>} A promise that resolves to the updated document or
      * undefined if the document was not found.
      */
-    update(id: any, input: PartialInput<T>, options?: MongoCollectionService.UpdateOptions<T>): Promise<PartialOutput<T> | undefined>;
+    update(id: AnyId, input: PatchDTO<T>, options?: MongoCollectionService.UpdateOptions<T>): Promise<PartialDTO<T> | undefined>;
     /**
      * Updates a document in the collection with the specified ID.
      *
      * @param {any} id - The ID of the document to update.
-     * @param {PartialInput<T>} input - The partial input data to update the document with.
+     * @param {PatchDTO<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.
      */
-    updateOnly(id: any, input: PartialInput<T>, options?: MongoCollectionService.UpdateOptions<T>): Promise<number>;
+    updateOnly(id: AnyId, input: PatchDTO<T>, options?: MongoCollectionService.UpdateOptions<T>): Promise<number>;
     /**
      * Updates multiple documents in the collection based on the specified input and options.
      *
-     * @param {OpraCommon.PartialInput<T>} input - The partial input to update the documents with.
+     * @param {PatchDTO<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.
      */
-    updateMany(input: OpraCommon.PartialInput<T>, options?: MongoCollectionService.UpdateManyOptions<T>): Promise<number>;
+    updateMany(input: PatchDTO<T>, options?: MongoCollectionService.UpdateManyOptions<T>): Promise<number>;
     /**
-     * Generates a new id for new inserting Document.
+     * 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;
 }
 /**
  *
@@ -157,8 +202,10 @@ export declare namespace MongoCollectionService {
      * @extends MongoService.Options
      */
     interface Options extends MongoService.Options {
-        collectionKey?: string;
-        defaultLimit?: number;
+        collectionKey?: MongoCollectionService<any>['collectionKey'];
+        defaultLimit?: MongoCollectionService<any>['defaultLimit'];
+        documentFilter?: MongoCollectionService<any>['$documentFilter'];
+        interceptor?: MongoCollectionService<any>['$interceptor'];
     }
     /**
      * Represents options for creating a new document.
@@ -242,4 +289,11 @@ export declare namespace MongoCollectionService {
     interface UpdateManyOptions<T> extends StrictOmit<mongodb.UpdateOptions, 'upsert'> {
         filter?: mongodb.Filter<T> | OpraCommon.OpraFilter.Ast | string;
     }
+    /**
+     * Represents options for checking the document exists
+     *
+     * @interface
+     */
+    interface ExistsOptions extends Omit<mongodb.CommandOperationOptions, 'writeConcern'> {
+    }
 }

package/types/mongo-service.d.ts

@@ -1,15 +1,9 @@
 import mongodb from 'mongodb';
 import { StrictOmit, Type } from 'ts-gems';
 import vg from 'valgen';
-import { ComplexType } from '@opra/common';
-import { ApiService, PartialOutput, RequestContext } from '@opra/core';
-export declare namespace MongoService {
-    interface Options {
-        db?: mongodb.Db;
-        collectionName?: string;
-        resourceName?: string;
-    }
-}
+import { ComplexType, PartialDTO } from '@opra/common';
+import { ApiService, RequestContext } from '@opra/core';
+import { AnyId } from './types.js';
 /**
  * Class representing a MongoDB service for interacting with a collection.
  * @extends ApiService
@@ -19,10 +13,51 @@ export declare class MongoService<T extends mongodb.Document> extends ApiService
     protected _encoders: Record<string, vg.ObjectValidator<T>>;
     protected _decoder?: vg.ObjectValidator<T>;
     protected _dataType: Type | string;
-    collectionName?: string;
-    db?: mongodb.Db;
-    session?: mongodb.ClientSession;
-    resourceName?: string;
+    /**
+     * Represents the name of a collection in MongoDB
+     *
+     * @type {string | Function} collectionName
+     */
+    collectionName?: string | ((_this: any) => string);
+    /**
+     * Represents the name of a resource.
+     *
+     * @type {string}
+     */
+    resourceName?: string | ((_this: any) => string);
+    /**
+     * Represents a MongoDB database object.
+     * @type {mongodb.Db | Function}
+     */
+    db?: mongodb.Db | ((_this: any) => mongodb.Db);
+    /**
+     * Represents a MongoDB ClientSession.
+     *
+     * @type {mongodb.ClientSession}
+     */
+    session?: mongodb.ClientSession | ((_this: any) => mongodb.ClientSession);
+    /**
+     * Generates a new id for new inserting Document.
+     *
+     * @protected
+     * @returns {AnyId} A new instance of AnyId.
+     */
+    $idGenerator?: (_this: any) => AnyId;
+    /**
+     * Callback function for handling errors.
+     *
+     * @param {unknown} error - The error object.
+     * @param {object} _this - The context object.
+     * @return {void|Promise<void>} - A void value or a promise that resolves to void.
+     */
+    $onError?: (error: unknown, _this: any) => void | Promise<void>;
+    /**
+     * Constructs a new instance
+     *
+     * @param {Type | string} dataType - The data type of the array elements.
+     * @param {MongoService.Options} [options] - The options for the array service.
+     * @constructor
+     */
     constructor(dataType: Type | string, options?: MongoService.Options);
     /**
      * Retrieves the data type of the document
@@ -32,64 +67,75 @@ export declare class MongoService<T extends mongodb.Document> extends ApiService
      */
     getDataType(): ComplexType;
     /**
-     * Creates a new instance for given context
+     * 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: 'create' | 'update'): vg.ObjectValidator<T>;
+    /**
+     * Retrieves the decoder.
      *
-     * @param source
+     * @returns {vg.ObjectValidator<T>} - The encoder for the specified operation.
      */
-    forContext(source: ApiService): this;
-    forContext(context: RequestContext, attributes?: {
-        db?: mongodb.Db;
-        session?: mongodb.ClientSession;
-    }): this;
+    getDecoder(): vg.ObjectValidator<T>;
     /**
      * Inserts a single document into MongoDB. If documents passed in do not contain the **_id** field,
      * one will be added to each of the documents missing it by the driver, mutating the document. This behavior
      * can be overridden by setting the **forceServerObjectId** flag.
      *
-     * @param doc
-     * @param options
+     * @param {T} doc - The document to be inserted.
+     * @param {mongodb.InsertOneOptions} options - The options for the insert operation.
+     * @returns {Promise<mongodb.InsertOneWriteOpResult<mongodb.OptionalId<T>>>} - A promise that resolves with the result of the insert operation.
      * @protected
      */
     protected __insertOne(doc: mongodb.OptionalUnlessRequiredId<T>, options?: mongodb.InsertOneOptions): Promise<mongodb.InsertOneResult<T>>;
     /**
      * Gets the number of documents matching the filter.
      *
-     * @param filter
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter used to match documents.
+     * @param {mongodb.CountOptions} options - The options for counting documents.
+     * @returns {Promise<number>} - The number of documents matching the filter.
      * @protected
      */
     protected __countDocuments(filter?: mongodb.Filter<T>, options?: mongodb.CountOptions): Promise<number>;
     /**
      * Delete a document from a collection
      *
-     * @param filter - The filter used to select the document to remove
-     * @param options - Optional settings for the command
+     * @param {mongodb.Filter<T>} filter - The filter used to select the document to remove
+     * @param {mongodb.DeleteOptions} options - Optional settings for the command
+     * @return {Promise<mongodb.DeleteResult>} A Promise that resolves to the result of the delete operation
      */
     protected __deleteOne(filter?: mongodb.Filter<T>, options?: mongodb.DeleteOptions): Promise<mongodb.DeleteResult>;
     /**
-     * Delete multiple documents from a collection
+     * Deletes multiple documents from a collection.
      *
-     * @param filter
-     * @param options
+     * @param {mongodb.Filter<T>} [filter] - The filter object specifying the documents to delete.
+     * If not provided, all documents in the collection will be deleted.
+     * @param {mongodb.DeleteOptions} [options] - The options for the delete operation.
+     * @returns {Promise<mongodb.DeleteResult>} A promise that resolves with the delete result object.
      * @protected
      */
     protected __deleteMany(filter?: mongodb.Filter<T>, options?: mongodb.DeleteOptions): Promise<mongodb.DeleteResult>;
     /**
-     * Create a new Change Stream, watching for new changes (insertions, updates, replacements, deletions, and invalidations) in this collection.
+     * Create a new Change Stream, watching for new changes
+     * (insertions, updates, replacements, deletions, and invalidations) in this collection.
      *
-     * @param pipeline
-     * @param options
+     * @param {mongodb.Document[]} pipeline - The pipeline of aggregation stages to apply to the collection.
+     * @param {mongodb.AggregateOptions} options - The options to customize the aggregation.
+     * @returns {Promise<mongodb.ChangeStream<T>>} - A promise that resolves to a Change Stream that represents the result of the aggregation.
      * @protected
      */
     protected __aggregate(pipeline?: mongodb.Document[], options?: mongodb.AggregateOptions): Promise<mongodb.AggregationCursor<T>>;
     /**
      * Fetches the first document that matches the filter
      *
-     * @param filter
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter object to match documents against
+     * @param {mongodb.FindOptions} [options] - The options to use when querying the collection
      * @protected
+     * @returns {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the first matching document, or undefined if no match is found
      */
-    protected __findOne(filter: mongodb.Filter<T>, options?: mongodb.FindOptions): Promise<PartialOutput<T> | undefined>;
+    protected __findOne(filter: mongodb.Filter<T>, options?: mongodb.FindOptions): Promise<PartialDTO<T> | undefined>;
     /**
      * Creates a cursor for a filter that can be used to iterate over results from MongoDB.
      *
@@ -100,58 +146,93 @@ export declare class MongoService<T extends mongodb.Document> extends ApiService
      */
     protected __find(filter: mongodb.Filter<T>, options?: mongodb.FindOptions): Promise<mongodb.FindCursor<T>>;
     /**
-     * Update a single document in a collection
+     * Update a single document in a collection.
      *
-     * @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
+     * @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
+     * @returns {Promise<mongodb.UpdateResult>} - A promise that resolves to the result of the update operation.
      */
     protected __updateOne(filter: mongodb.Filter<T>, update: mongodb.UpdateFilter<T>, options?: mongodb.UpdateOptions): Promise<mongodb.UpdateResult<T>>;
     /**
      * Find a document and update it in one atomic operation. Requires a write lock for the duration of the operation.
      *
-     * @param filter
-     * @param doc
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter to select the document to be updated.
+     * @param {mongodb.UpdateFilter<T>} doc - The update document.
+     * @param {mongodb.FindOneAndUpdateOptions} [options] - Optional options for the find one and update operation.
+     * @returns {Promise<T | null>} - A promise that resolves to the updated document or null if no document matched the filter.
      * @protected
      */
     protected __findOneAndUpdate(filter: mongodb.Filter<T>, doc: mongodb.UpdateFilter<T>, options?: mongodb.FindOneAndUpdateOptions): Promise<mongodb.WithId<T> | null>;
     /**
-     * Update multiple documents in a collection
+     * Update multiple documents in a collection.
      *
-     * @param filter
-     * @param doc
-     * @param options
+     * @param {mongodb.Filter<T>} filter - The filter used to select the documents to be updated.
+     * @param {mongodb.UpdateFilter<T> | Partial<T>} doc - The updates to be applied to the selected documents.
+     * @param {StrictOmit<mongodb.UpdateOptions, 'upsert'>} [options] - The optional settings for the update operation.
+     * @return {Promise<mongodb.UpdateResult>} - A Promise that resolves to the result of the update operation.
      * @protected
      */
     protected __updateMany(filter: mongodb.Filter<T>, doc: mongodb.UpdateFilter<T> | Partial<T>, options?: StrictOmit<mongodb.UpdateOptions, 'upsert'>): Promise<mongodb.UpdateResult<T>>;
-    protected _onError(error: unknown): Promise<void>;
-    protected getDatabase(): mongodb.Db | Promise<mongodb.Db>;
+    /**
+     * Retrieves the database connection.
+     *
+     * @protected
+     *
+     * @returns {Promise<mongodb.Db>} The database connection.
+     * @throws {Error} If the context or database is not set.
+     */
+    protected getDatabase(): mongodb.Db;
+    /**
+     * Retrieves the database session.
+     *
+     * @protected
+     *
+     * @returns {Promise<mongodb.ClientSession>} The database connection.
+     * @throws {Error} If the context or database is not set.
+     */
+    protected getSession(): mongodb.ClientSession | undefined;
+    /**
+     * Retrieves a MongoDB collection from the given database.
+     *
+     * @param {mongodb.Db} db - The MongoDB database.
+     * @protected
+     * @returns {Promise<mongodb.Collection<T>>} A promise that resolves to the MongoDB collection.
+     */
     protected getCollection(db: mongodb.Db): Promise<mongodb.Collection<T>>;
-    protected getCollectionName(): string;
-    protected _cacheMatch(service: MongoService<any>, context: RequestContext, attributes?: any): boolean;
     /**
-     * Retrieves the encoder for the specified operation.
+     * Retrieves the collection name.
      *
-     * @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.
+     * @protected
+     * @returns {string} The collection name.
+     * @throws {Error} If the collection name is not defined.
      */
-    getEncoder(operation: 'create' | 'update'): vg.ObjectValidator<T>;
+    getCollectionName(): string;
     /**
-     * Retrieves the decoder.
+     * Retrieves the resource name.
      *
-     * @returns {vg.ObjectValidator<T>} - The encoder for the specified operation.
+     * @protected
+     * @returns {string} The collection name.
+     * @throws {Error} If the collection name is not defined.
      */
-    getDecoder(): vg.ObjectValidator<T>;
+    getResourceName(): string;
+    /**
+     * Compares the current instance with the provided attributes and returns true if they match, false otherwise.
+     * This method is protected and should only be called by subclasses.
+     *
+     * @param {MongoService<any>} service - The service instance to compare.
+     * @param {RequestContext} context - The request context.
+     * @param {Object} attributes - Optional attributes object for comparison.
+     * @return {boolean} - True if the instance matches the provided attributes, false otherwise.
+     * @protected
+     */
+    protected _instanceCompare(service: MongoService<any>, context: RequestContext, attributes?: any): boolean;
     /**
      * 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.
      */
     protected _generateEncoder(operation: 'create' | 'update'): vg.ObjectValidator<T>;
@@ -159,9 +240,23 @@ export declare class MongoService<T extends mongodb.Document> extends ApiService
      * Generates an encoder for the specified operation.
      *
      * @protected
-     *
      * @returns {vg.Validator} - The generated encoder for the specified operation.
      */
     protected _generateDecoder(): vg.ObjectValidator<T>;
-    protected onError?(error: unknown): void | Promise<void>;
+}
+/**
+ * The namespace for the MongoService.
+ *
+ * @namespace MongoService
+ */
+export declare namespace MongoService {
+    interface Options {
+        db?: MongoService<any>['db'];
+        collectionName?: MongoService<any>['collectionName'];
+        resourceName?: MongoService<any>['resourceName'];
+        session?: MongoService<any>['session'];
+        idGenerator?: MongoService<any>['$idGenerator'];
+        onError?: MongoService<any>['$onError'];
+    }
+    type CrudOp = 'create' | 'read' | 'update' | 'delete';
 }