@opra/mongodb 1.26.3 → 1.26.4

package/services/mongo-nested-service.js

@@ -12,34 +12,26 @@ import { MongoService } from './mongo-service.js';
 export class MongoNestedService extends MongoService {
     /**
      * Represents the name of the array field in parent document
-     *
-     * @type {string}
      */
     fieldName;
     /**
      * Represents the value of a nested array key field
-     *
-     * @type {string}
      */
     nestedKey;
     /**
      * Represents the default limit value for a certain operation.
-     *
-     * @type {number}
      */
     defaultLimit;
     /**
      * Represents a common array filter function
-     *
-     * @type {FilterInput | Function}
      */
     nestedFilter;
     /**
      * 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.
+     * @param dataType - The data type of the array elements.
+     * @param fieldName - The name of the field in the document representing the array.
+     * @param [options] - The options for the array service.
      * @constructor
      */
     constructor(dataType, fieldName, options) {
@@ -50,10 +42,10 @@ export class MongoNestedService extends MongoService {
         this.nestedFilter = options?.nestedFilter;
     }
     /**
-     * Retrieves the data type of the array field
+     * 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.
+     * @returns The complex data type of the field.
+     * @throws {@link NotAcceptableError} If the data type is not a ComplexType.
      */
     get dataType() {
         const t = super.dataType.getField(this.fieldName, this.scope).type;
@@ -64,10 +56,10 @@ export class MongoNestedService extends MongoService {
     /**
      * Create a copy of this instance with given properties and context applied.
      *
-     * @param {C | ServiceBase} context - The execution context or service base to associate with this instance.
-     * @param {Nullish<P>} [overwriteProperties] - An optional object containing properties to overwrite in the current instance.
-     * @param {Partial<C>} [overwriteContext] - An optional partial context to apply and potentially overwrite parts of the provided execution context.
-     * @return {this & Required<P>} The current instance with the specified properties and context applied.
+     * @param context - The execution context or service base to associate with this instance.
+     * @param [overwriteProperties] - An optional object containing properties to overwrite in the current instance.
+     * @param [overwriteContext] - An optional partial context to apply and potentially overwrite parts of the provided execution context.
+     * @returns The current instance with the specified properties and context applied.
      * @template P
      * @template C
      */
@@ -78,11 +70,11 @@ export class MongoNestedService extends MongoService {
      * 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.
+     * @param documentId - The ID of the parent document.
+     * @param id - The ID of the resource.
+     * @param options - Optional parameters for checking resource existence.
+     * @returns A promise that resolves with no value upon success.
+     * @throws {@link ResourceNotAvailableError} - If the resource does not exist.
      */
     async assert(documentId, id, options) {
         if (!(await this.exists(documentId, id, options))) {
@@ -127,11 +119,11 @@ export class MongoNestedService extends MongoService {
     /**
      * Adds a single item into the array field.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
-     * @param {DTO<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 create operation result
-     * @throws {ResourceNotAvailableError} - If the parent document is not found.
+     * @param documentId - The ID of the parent document.
+     * @param input - The item to be added to the array field.
+     * @param [options] - Optional options for the create operation.
+     * @returns A promise that resolves create operation result
+     * @throws {@link ResourceNotAvailableError} - If the parent document is not found.
      */
     async createOnly(documentId, input, options) {
         const command = {
@@ -175,9 +167,9 @@ export class MongoNestedService extends MongoService {
     /**
      * 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.
+     * @param documentId - The ID of the parent document.
+     * @param [options] - Optional parameters for counting.
+     * @returns A promise that resolves to the count of documents.
      */
     async count(documentId, options) {
         const command = {
@@ -232,10 +224,10 @@ export class MongoNestedService extends MongoService {
     /**
      * 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).
+     * @param documentId - The ID of the parent document.
+     * @param nestedId - The ID of the element to delete from the nested array.
+     * @param [options] - Additional options for the delete operation.
+     * @returns A Promise that resolves to the number of elements deleted (1 if successful, 0 if not).
      */
     async delete(documentId, nestedId, options) {
         const command = {
@@ -285,9 +277,9 @@ export class MongoNestedService extends MongoService {
     /**
      * 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.
+     * @param documentId - The ID of the parent document.
+     * @param [options] - Optional options to specify a filter.
+     * @returns A Promise that resolves to the number of items deleted.
      */
     async deleteMany(documentId, options) {
         const command = {
@@ -340,10 +332,10 @@ export class MongoNestedService extends MongoService {
     /**
      * 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.
+     * @param documentId - The ID of the parent document.
+     * @param nestedId - The id of the record.
+     * @param [options] - The options for the exists method.
+     * @returns A promise that resolves to a boolean indicating if the record exists or not.
      */
     async exists(documentId, nestedId, options) {
         const command = {
@@ -370,9 +362,9 @@ export class MongoNestedService extends MongoService {
     /**
      * Checks if an object with the given arguments exists.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
-     * @param {MongoNestedService.ExistsOptions} [options] - The options for the query (optional).
-     * @return {Promise<boolean>} - A Promise that resolves to a boolean indicating whether the object exists or not.
+     * @param documentId - The ID of the parent document.
+     * @param [options] - The options for the query (optional).
+     * @returns A Promise that resolves to a boolean indicating whether the object exists or not.
      */
     async existsOne(documentId, options) {
         const command = {
@@ -506,10 +498,10 @@ export class MongoNestedService extends MongoService {
             { $unwind: { path: '$' + this.fieldName } },
             { $replaceRoot: { newRoot: '$' + this.fieldName } },
         ];
-        /** Pre-Stages */
+        /* Pre-Stages */
         if (options?.preStages)
             stages.push(...options.preStages);
-        /** Filter */
+        /* Filter */
         if (options?.filter || options?.nestedFilter) {
             const optionsFilter = MongoAdapter.prepareFilter([
                 options?.filter,
@@ -517,22 +509,22 @@ export class MongoNestedService extends MongoService {
             ]);
             stages.push({ $match: optionsFilter });
         }
-        /** Sort */
+        /* Sort */
         if (options?.sort) {
             const sort = MongoAdapter.prepareSort(options.sort);
             if (sort)
                 stages.push({ $sort: sort });
         }
-        /** Skip */
+        /* Skip */
         if (options?.skip)
             stages.push({ $skip: options.skip });
-        /** Limit */
+        /* Limit */
         stages.push({ $limit: limit });
         const dataType = this.dataType;
         const projection = MongoAdapter.prepareProjection(dataType, options?.projection, this._dataTypeScope);
         if (projection)
             stages.push({ $project: projection });
-        /** Post-Stages */
+        /* Post-Stages */
         if (options?.postStages)
             stages.push(...options.postStages);
         const db = this.getDatabase();
@@ -598,10 +590,10 @@ export class MongoNestedService extends MongoService {
                 },
             },
         ];
-        /** Pre-Stages */
+        /* Pre-Stages */
         if (options?.preStages)
             dataStages.push(...options.preStages);
-        /** Filter */
+        /* Filter */
         if (options?.filter || options?.nestedFilter) {
             const optionsFilter = MongoAdapter.prepareFilter([
                 options?.filter,
@@ -609,18 +601,18 @@ export class MongoNestedService extends MongoService {
             ]);
             dataStages.push({ $match: optionsFilter });
         }
-        /** Sort */
+        /* Sort */
         if (options?.sort) {
             const sort = MongoAdapter.prepareSort(options.sort);
             if (sort)
                 dataStages.push({ $sort: sort });
         }
-        /** Skip */
+        /* Skip */
         if (options?.skip)
             dataStages.push({ $skip: options.skip });
-        /** Limit */
+        /* Limit */
         dataStages.push({ $limit: limit });
-        /** Post-Stages */
+        /* Post-Stages */
         if (options?.postStages)
             dataStages.push(...options.postStages);
         const dataType = this.dataType;
@@ -704,11 +696,11 @@ export class MongoNestedService extends MongoService {
     /**
      * 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 {MongoPatchDTO<T>} input - The partial input object containing the fields to update.
-     * @param {MongoNestedService.UpdateOneOptions<T>} [options] - Optional update options.
-     * @returns {Promise<number>} - A promise that resolves to the number of elements updated.
+     * @param documentId - The ID of the parent document.
+     * @param nestedId - The ID of the document to update.
+     * @param input - The partial input object containing the fields to update.
+     * @param [options] - Optional update options.
+     * @returns A promise that resolves to the number of elements updated.
      */
     async updateOnly(documentId, nestedId, input, options) {
         const command = {
@@ -755,10 +747,10 @@ export class MongoNestedService extends MongoService {
     /**
      * Updates multiple array elements in document
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the document to update.
-     * @param {MongoPatchDTO<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.
+     * @param documentId - The ID of the document to update.
+     * @param input - The updated data for the document(s).
+     * @param [options] - Additional options for the update operation.
+     * @returns A promise that resolves to the number of documents updated.
      */
     async updateMany(documentId, input, options) {
         const command = {
@@ -831,7 +823,7 @@ export class MongoNestedService extends MongoService {
      * This method is mostly used for security issues like securing multi-tenant applications.
      *
      * @protected
-     * @returns {MongoAdapter.FilterInput | Promise<MongoAdapter.FilterInput> | undefined} The common filter or a Promise
+     * @returns The common filter or a Promise
      * that resolves to the common filter, or undefined if not available.
      */
     _getNestedFilter(args) {
@@ -842,7 +834,7 @@ export class MongoNestedService extends MongoService {
     async _executeCommand(command, commandFn) {
         try {
             const result = await super._executeCommand(command, async () => {
-                /** Call before[X] hooks */
+                /* Call before[X] hooks */
                 if (command.crud === 'create')
                     await this._beforeCreate(command);
                 else if (command.crud === 'update' && command.byId) {
@@ -857,10 +849,10 @@ export class MongoNestedService extends MongoService {
                 else if (command.crud === 'delete' && !command.byId) {
                     await this._beforeDeleteMany(command);
                 }
-                /** Call command function */
+                /* Call command function */
                 return commandFn();
             });
-            /** Call after[X] hooks */
+            /* Call after[X] hooks */
             if (command.crud === 'create')
                 await this._afterCreate(command, result);
             else if (command.crud === 'update' && command.byId) {

package/services/mongo-service.d.ts

@@ -5,23 +5,57 @@ import type { Nullish, StrictOmit, Type } from 'ts-gems';
 import type { vg } from 'valgen';
 import { MongoAdapter } from '../adapter/mongo-adapter.js';
 /**
- * The namespace for the MongoService.
- *
- * @namespace MongoService
+ * The namespace for the MongoService, containing types and options.
  */
 export declare namespace MongoService {
+    /**
+     * Options for initializing MongoService.
+     */
     interface Options extends ServiceBase.Options {
+        /**
+         * The MongoDB client or database instance.
+         */
         db?: MongoService<any>['db'];
+        /**
+         * Optional MongoDB client session for transactions.
+         */
         session?: MongoService<any>['session'];
+        /**
+         * The name of the collection.
+         */
         collectionName?: MongoService<any>['collectionName'];
+        /**
+         * The name of the resource managed by this service.
+         */
         resourceName?: MongoService<any>['resourceName'];
+        /**
+         * Optional common filter applied to all read/write operations.
+         */
         documentFilter?: MongoService<any>['documentFilter'];
+        /**
+         * Optional interceptor for the service operations.
+         */
         interceptor?: MongoService<any>['interceptor'];
+        /**
+         * Optional function to generate IDs for new documents.
+         */
         idGenerator?: MongoService<any>['idGenerator'];
+        /**
+         * Optional scope for the service.
+         */
         scope?: MongoService<any>['scope'];
+        /**
+         * Optional error handler.
+         */
         onError?: MongoService<any>['onError'];
     }
+    /**
+     * Represents the CRUD operation types.
+     */
     type CrudOp = 'create' | 'read' | 'replace' | 'update' | 'delete';
+    /**
+     * Information about the command being executed.
+     */
     interface CommandInfo {
         crud: CrudOp;
         method: string;
@@ -31,57 +65,54 @@ export declare namespace MongoService {
         input?: any;
         options?: any;
     }
+    /**
+     * Type definition for a document filter.
+     */
     type DocumentFilter = MongoAdapter.FilterInput | ((args: CommandInfo, _this: MongoService<any>) => MongoAdapter.FilterInput | Promise<MongoAdapter.FilterInput> | undefined);
     /**
-     * Represents options for "create" operation
-     *
-     * @interface
+     * Represents options for "create" operation.
      */
     interface CreateOptions extends mongodb.InsertOneOptions {
         projection?: string | string[] | Document | '*';
     }
     /**
-     * Represents options for "count" operation
+     * Represents options for "count" operation.
      *
-     * @interface
      * @template T - The type of the document.
      */
     interface CountOptions<T> extends mongodb.CountOptions {
         filter?: MongoAdapter.FilterInput<T>;
     }
     /**
-     * Represents options for "delete" operation
+     * Represents options for "delete" operation.
      *
-     * @interface
      * @template T - The type of the document.
      */
     interface DeleteOptions<T> extends mongodb.DeleteOptions {
         filter?: MongoAdapter.FilterInput<T>;
     }
     /**
-     * Represents options for "deleteMany" operation
+     * Represents options for "deleteMany" operation.
      *
-     * @interface
      * @template T - The type of the document.
      */
     interface DeleteManyOptions<T> extends mongodb.DeleteOptions {
         filter?: MongoAdapter.FilterInput<T>;
     }
     /**
-     * Represents options for "distinct" operation
+     * Represents options for "distinct" operation.
      *
-     * @interface
      * @template T - The type of the document.
      */
     interface DistinctOptions<T> extends mongodb.DistinctOptions {
         filter?: MongoAdapter.FilterInput<T>;
     }
     /**
-     * Represents options for "exists" operation
+     * Represents options for "exists" operation.
      *
-     * @interface
+     * @template T - The type of the document.
      */
-    interface ExistsOptions<T> extends Omit<mongodb.CommandOperationOptions, 'writeConcern'> {
+    interface ExistsOptions<T> extends Omit<mongodb.CommandOperationOptions, 'session'> {
         filter?: MongoAdapter.FilterInput<T>;
     }
     /**
@@ -141,9 +172,9 @@ export interface MongoService {
      * Interceptor function for handling callback execution with provided arguments.
      * @type Function
      * @param next - The callback function to be intercepted.
-     * @param {MongoService.CommandInfo} command - The arguments object containing the following properties:
+     * @param command - The arguments object containing the following properties:
      * @param _this - The reference to the current object.
-     * @returns - The promise that resolves to the result of the callback execution.
+     * @returns The promise that resolves to the result of the callback execution.
      */
     interceptor?(next: () => any, command: MongoService.CommandInfo, _this: any): Promise<any>;
 }
@@ -168,7 +199,6 @@ export declare class MongoService<T extends mongodb.Document = mongodb.Document>
     collectionName?: string | ((_this: any) => string);
     /**
      * Represents the name of a resource.
-     * @type {string}
      */
     resourceName?: string | ((_this: any) => string);
     /**
@@ -187,14 +217,12 @@ export declare class MongoService<T extends mongodb.Document = mongodb.Document>
     /**
      * Callback function for handling errors.
      *
-     * @param {unknown} error - The error object.
+     * @param error - The error object.
      * @param _this - The context object.
      */
     onError?: (error: unknown, _this: any) => void | Promise<void>;
     /**
      * Represents a common filter function for a MongoService.
-     *
-     * @type {FilterInput | Function}
      */
     documentFilter?: MongoService.DocumentFilter | MongoService.DocumentFilter[];
     /**
@@ -211,21 +239,21 @@ export declare class MongoService<T extends mongodb.Document = mongodb.Document>
      *
      * @protected
      * @returns The collection name.
-     * @throws {Error} If the collection name is not defined.
+     * @throws {@link Error} If the collection name is not defined.
      */
     getCollectionName(): string;
     /**
      * Retrieves the resource name.
      *
      * @protected
-     * @returns {string} The resource name.
-     * @throws {Error} If the resource name is not defined.
+     * @returns The resource name.
+     * @throws {@link Error} If the resource name is not defined.
      */
     getResourceName(): string;
     /**
-     * Retrieves the OPRA data type
+     * Retrieves the OPRA data type.
      *
-     * @throws {NotAcceptableError} If the data type is not a ComplexType.
+     * @throws {@link NotAcceptableError} If the data type is not a ComplexType.
      */
     get dataType(): ComplexType;
     /**
@@ -239,16 +267,14 @@ export declare class MongoService<T extends mongodb.Document = mongodb.Document>
      * Retrieves the database connection.
      *
      * @protected
-     *
-     * @throws {Error} If the context or database is not set.
+     * @throws {@link Error} If the context or database is not set.
      */
     protected getDatabase(): mongodb.Db;
     /**
      * Retrieves the database session.
      *
      * @protected
-     *
-     * @throws {Error} If the context or database is not set.
+     * @throws {@link Error} If the context or database is not set.
      */
     protected getSession(): mongodb.ClientSession | undefined;
     /**
@@ -262,7 +288,7 @@ export declare class MongoService<T extends mongodb.Document = mongodb.Document>
      * Generates an ID.
      *
      * @protected
-     * @returns {MongoAdapter.AnyId} The generated ID.
+     * @returns The generated ID.
      */
     protected _generateId(command: MongoService.CommandInfo): MongoAdapter.AnyId;
     /**
@@ -270,7 +296,7 @@ export declare class MongoService<T extends mongodb.Document = mongodb.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
+     * @returns The common filter or a Promise
      * that resolves to the common filter, or undefined if not available.
      */
     protected _getDocumentFilter(command: MongoService.CommandInfo): MongoAdapter.FilterInput | Promise<MongoAdapter.FilterInput> | undefined;

package/services/mongo-service.js

@@ -24,7 +24,6 @@ export class MongoService extends ServiceBase {
     collectionName;
     /**
      * Represents the name of a resource.
-     * @type {string}
      */
     resourceName;
     /**
@@ -43,14 +42,12 @@ export class MongoService extends ServiceBase {
     /**
      * Callback function for handling errors.
      *
-     * @param {unknown} error - The error object.
+     * @param error - The error object.
      * @param _this - The context object.
      */
     onError;
     /**
      * Represents a common filter function for a MongoService.
-     *
-     * @type {FilterInput | Function}
      */
     documentFilter;
     /**
@@ -99,7 +96,7 @@ export class MongoService extends ServiceBase {
      *
      * @protected
      * @returns The collection name.
-     * @throws {Error} If the collection name is not defined.
+     * @throws {@link Error} If the collection name is not defined.
      */
     getCollectionName() {
         const out = typeof this.collectionName === 'function'
@@ -113,8 +110,8 @@ export class MongoService extends ServiceBase {
      * Retrieves the resource name.
      *
      * @protected
-     * @returns {string} The resource name.
-     * @throws {Error} If the resource name is not defined.
+     * @returns The resource name.
+     * @throws {@link Error} If the resource name is not defined.
      */
     getResourceName() {
         const out = typeof this.resourceName === 'function'
@@ -125,9 +122,9 @@ export class MongoService extends ServiceBase {
         throw new Error('resourceName is not defined');
     }
     /**
-     * Retrieves the OPRA data type
+     * Retrieves the OPRA data type.
      *
-     * @throws {NotAcceptableError} If the data type is not a ComplexType.
+     * @throws {@link NotAcceptableError} If the data type is not a ComplexType.
      */
     get dataType() {
         if (this._dataType && this._dataTypeScope !== this.scope)
@@ -187,8 +184,7 @@ export class MongoService extends ServiceBase {
      * Retrieves the database connection.
      *
      * @protected
-     *
-     * @throws {Error} If the context or database is not set.
+     * @throws {@link Error} If the context or database is not set.
      */
     getDatabase() {
         const ctx = this.context;
@@ -204,8 +200,7 @@ export class MongoService extends ServiceBase {
      * Retrieves the database session.
      *
      * @protected
-     *
-     * @throws {Error} If the context or database is not set.
+     * @throws {@link Error} If the context or database is not set.
      */
     getSession() {
         const ctx = this.context;
@@ -229,7 +224,7 @@ export class MongoService extends ServiceBase {
      * Generates an ID.
      *
      * @protected
-     * @returns {MongoAdapter.AnyId} The generated ID.
+     * @returns The generated ID.
      */
     _generateId(command) {
         return typeof this.idGenerator === 'function'
@@ -241,7 +236,7 @@ export class MongoService extends ServiceBase {
      * 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
+     * @returns The common filter or a Promise
      * that resolves to the common filter, or undefined if not available.
      */
     _getDocumentFilter(command) {