@opra/mongodb 1.26.3 → 1.27.0

package/services/mongo-entity-service.d.ts

@@ -3,42 +3,91 @@ import type { PartialDTO, StrictOmit, Type } from 'ts-gems';
 import type { MongoPatchDTO } from '../types.js';
 import { MongoService } from './mongo-service.js';
 /**
- *
- * @namespace MongoEntityService
+ * Options for MongoEntityService.
  */
 export declare namespace MongoEntityService {
     /**
-     * The constructor options of MongoEntityService.
-     *
-     * @interface Options
-     * @extends MongoService.Options
+     * Configuration options for MongoEntityService.
      */
     interface Options extends MongoService.Options {
     }
+    /**
+     * Information about the command being executed.
+     */
     interface CommandInfo extends MongoService.CommandInfo {
     }
     interface CreateOptions extends MongoService.CreateOptions {
     }
+    /**
+     * Options for the `count` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface CountOptions<T> extends MongoService.CountOptions<T> {
     }
+    /**
+     * Options for the `delete` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface DeleteOptions<T> extends MongoService.DeleteOptions<T> {
     }
+    /**
+     * Options for the `deleteMany` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface DeleteManyOptions<T> extends MongoService.DeleteManyOptions<T> {
     }
+    /**
+     * Options for the `distinct` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface DistinctOptions<T> extends MongoService.DistinctOptions<T> {
     }
+    /**
+     * Options for the `exists` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface ExistsOptions<T> extends MongoService.ExistsOptions<T> {
     }
+    /**
+     * Options for the `findOne` / `findById` operations.
+     *
+     * @template T - The type of the document.
+     */
     interface FindOneOptions<T> extends MongoService.FindOneOptions<T> {
     }
+    /**
+     * Options for the `findMany` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface FindManyOptions<T> extends MongoService.FindManyOptions<T> {
         noDecode?: boolean;
     }
+    /**
+     * Options for the `replace` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface ReplaceOptions<T> extends MongoService.ReplaceOptions<T> {
     }
+    /**
+     * Options for the `update` / `updateOnly` operations.
+     *
+     * @template T - The type of the document.
+     */
     interface UpdateOneOptions<T> extends MongoService.UpdateOneOptions<T> {
         initArrayFields?: string[];
     }
+    /**
+     * Options for the `updateMany` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface UpdateManyOptions<T> extends MongoService.UpdateManyOptions<T> {
         initArrayFields?: string[];
     }
@@ -96,71 +145,70 @@ export declare namespace MongoEntityService {
  */
 export declare class MongoEntityService<T extends mongodb.Document> extends MongoService<T> {
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param {Type | string} dataType - The data type of the array elements.
-     * @param {MongoEntityService.Options} [options] - The options for the array service.
-     * @constructor
+     * @param dataType - The data type of the managed entities.
+     * @param options - The options for the entity service.
      */
     constructor(dataType: Type | string, options?: MongoEntityService.Options);
     /**
      * Creates a new document in the MongoDB collection
      *
-     * @param {MongoEntityService.CreateCommand} command
+     * @param command - The command information.
      * @protected
      */
     protected _create(command: MongoEntityService.CreateCommand<T>): Promise<T>;
     /**
      * Returns the count of documents in the collection based on the provided options.
      *
-     * @param {MongoEntityService.CountCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     protected _count(command: MongoEntityService.CountCommand<T>): Promise<number>;
     /**
      * Deletes a document from the collection
      *
-     * @param {MongoEntityService.DeleteCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     protected _delete(command: MongoEntityService.DeleteCommand<T>): Promise<number>;
     /**
      * Deletes multiple documents from the collection that meet the specified filter criteria.
      *
-     * @param {MongoEntityService.DeleteCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     protected _deleteMany(command: MongoEntityService.DeleteCommand<T>): Promise<number>;
     /**
      * The distinct command returns a list of distinct values for the given key across a collection
      *
-     * @param {MongoEntityService.DistinctCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     protected _distinct(command: MongoEntityService.DistinctCommand<T>): Promise<any[]>;
     /**
      * Finds a document by its ID.
      *
-     * @param { MongoEntityService.FindOneCommand<T>} command
+     * @param command - The command information.
      */
     protected _findById(command: MongoEntityService.FindOneCommand<T>): Promise<PartialDTO<T> | undefined>;
     /**
      * Finds a document in the collection that matches the specified options.
      *
-     * @param {MongoEntityService.FindOneCommand<T>} command
+     * @param command - The command information.
      */
     protected _findOne(command: MongoEntityService.FindOneCommand<T>): Promise<PartialDTO<T> | undefined>;
     /**
      * Finds multiple documents in the MongoDB collection
      *
-     * @param {MongoEntityService.FindManyCommand<T>} command
+     * @param command - The command information.
      */
     protected _findMany(command: MongoEntityService.FindManyCommand<T>): Promise<PartialDTO<T>[]>;
     /**
      * Finds multiple documents in the collection and returns both records (max limit)
      * and total count that matched the given criteria
      *
-     * @param {MongoEntityService.FindManyCommand<T>} command
+     * @param command - The command information.
      */
     protected _findManyWithCount(command: MongoEntityService.FindManyCommand<T>): Promise<{
         count: number;
@@ -169,25 +217,25 @@ export declare class MongoEntityService<T extends mongodb.Document> extends Mong
     /**
      * Updates a document with the given id in the collection
      *
-     * @param {MongoEntityService.UpdateOneCommand<T>} command
+     * @param command - The command information.
      */
     protected _update(command: MongoEntityService.UpdateOneCommand<T>): Promise<PartialDTO<T> | undefined>;
     /**
      * Updates a document in the collection with the specified ID.
      *
-     * @param {MongoEntityService.UpdateOneCommand<T>} command
+     * @param command - The command information.
      */
     protected _updateOnly(command: MongoEntityService.UpdateOneCommand<T>): Promise<number>;
     /**
      * Updates multiple documents in the collection based on the specified input and options.
      *
-     * @param {MongoEntityService.UpdateManyCommand<T>} command
+     * @param command - The command information.
      */
     protected _updateMany(command: MongoEntityService.UpdateManyCommand<T>): Promise<number>;
     /**
      * Replaces a document with the given id in the collection
      *
-     * @param {MongoEntityService.ReplaceCommand<T>} command
+     * @param command - The command information.
      */
     protected _replace(command: MongoEntityService.ReplaceCommand<T>): Promise<PartialDTO<T> | undefined>;
     protected _prepareUpdate(command: MongoEntityService.UpdateOneCommand<T> | MongoEntityService.UpdateManyCommand<T>): UpdateFilter<T>;

package/services/mongo-entity-service.js

@@ -10,11 +10,10 @@ import { MongoService } from './mongo-service.js';
  */
 export class MongoEntityService extends MongoService {
     /**
-     * Constructs a new instance
+     * Constructs a new instance.
      *
-     * @param {Type | string} dataType - The data type of the array elements.
-     * @param {MongoEntityService.Options} [options] - The options for the array service.
-     * @constructor
+     * @param dataType - The data type of the managed entities.
+     * @param options - The options for the entity service.
      */
     constructor(dataType, options) {
         super(dataType, options);
@@ -22,7 +21,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Creates a new document in the MongoDB collection
      *
-     * @param {MongoEntityService.CreateCommand} command
+     * @param command - The command information.
      * @protected
      */
     async _create(command) {
@@ -47,7 +46,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Returns the count of documents in the collection based on the provided options.
      *
-     * @param {MongoEntityService.CountCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     async _count(command) {
@@ -64,7 +63,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Deletes a document from the collection
      *
-     * @param {MongoEntityService.DeleteCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     async _delete(command) {
@@ -85,7 +84,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Deletes multiple documents from the collection that meet the specified filter criteria.
      *
-     * @param {MongoEntityService.DeleteCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     async _deleteMany(command) {
@@ -101,7 +100,7 @@ export class MongoEntityService extends MongoService {
     /**
      * The distinct command returns a list of distinct values for the given key across a collection
      *
-     * @param {MongoEntityService.DistinctCommand<T>} command
+     * @param command - The command information.
      * @protected
      */
     async _distinct(command) {
@@ -117,7 +116,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Finds a document by its ID.
      *
-     * @param { MongoEntityService.FindOneCommand<T>} command
+     * @param command - The command information.
      */
     async _findById(command) {
         isNotNullish(command.documentId, { label: 'documentId' });
@@ -141,7 +140,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Finds a document in the collection that matches the specified options.
      *
-     * @param {MongoEntityService.FindOneCommand<T>} command
+     * @param command - The command information.
      */
     async _findOne(command) {
         const { options } = command;
@@ -158,32 +157,32 @@ export class MongoEntityService extends MongoService {
     /**
      * Finds multiple documents in the MongoDB collection
      *
-     * @param {MongoEntityService.FindManyCommand<T>} command
+     * @param command - The command information.
      */
     async _findMany(command) {
         const { options } = command;
         const stages = [];
-        /** Pre-Stages */
+        /* Pre-Stages */
         if (options?.preStages)
             stages.push(...options.preStages);
-        /** "Filter" stage */
+        /* "Filter" stage */
         let filter;
         if (options?.filter)
             filter = MongoAdapter.prepareFilter(options?.filter);
         if (filter)
             stages.push({ $match: filter });
-        /** "Skip" stage */
+        /* "Skip" stage */
         if (options?.skip)
             stages.push({ $skip: options.skip });
-        /** "Sort" stage */
+        /* "Sort" stage */
         if (options?.sort) {
             const sort = MongoAdapter.prepareSort(options.sort);
             if (sort)
                 stages.push({ $sort: sort });
         }
-        /** "Limit" stage */
+        /* "Limit" stage */
         stages.push({ $limit: options?.limit || 10 });
-        /** Post-Stages */
+        /* Post-Stages */
         if (options?.postStages)
             stages.push(...options.postStages);
         const dataType = this.dataType;
@@ -196,12 +195,12 @@ export class MongoEntityService extends MongoService {
             ...omit(options, ['projection', 'sort', 'skip', 'limit', 'filter']),
             session: options?.session ?? this.getSession(),
         });
-        /** Execute db command */
+        /* Execute db command */
         try {
-            /** Fetch the cursor */
+            /* Fetch the cursor */
             if (options?.noDecode)
                 return cursor.toArray();
-            /** Decode result objects */
+            /* Decode result objects */
             const outputCodec = this._getOutputCodec('find');
             return (await cursor.toArray()).map((r) => outputCodec(r));
         }
@@ -214,7 +213,7 @@ export class MongoEntityService extends MongoService {
      * Finds multiple documents in the collection and returns both records (max limit)
      * and total count that matched the given criteria
      *
-     * @param {MongoEntityService.FindManyCommand<T>} command
+     * @param command - The command information.
      */
     async _findManyWithCount(command) {
         const { options } = command;
@@ -232,39 +231,39 @@ export class MongoEntityService extends MongoService {
                 },
             },
         ];
-        /** Pre-Stages */
+        /* Pre-Stages */
         if (options?.preStages)
             dataStages.push(...options.preStages);
-        /** Filter */
+        /* Filter */
         if (filter) {
             countStages.push({ $match: filter });
             dataStages.push({ $match: filter });
         }
         countStages.push({ $count: 'totalMatches' });
-        /** 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 });
         const dataType = this.dataType;
         const projection = MongoAdapter.prepareProjection(dataType, options?.projection, this._dataTypeScope);
         if (projection)
             dataStages.push({ $project: projection });
         const outputCodec = this._getOutputCodec('find');
-        /** Execute db command */
+        /* Execute db command */
         const db = this.getDatabase();
         const collection = await this.getCollection(db);
         const cursor = collection.aggregate(stages, {
             ...omit(options, ['projection', 'sort', 'skip', 'limit', 'filter']),
             session: options?.session ?? this.getSession(),
         });
-        /** Fetch the cursor and decode the result objects */
+        /* Fetch the cursor and decode the result objects */
         try {
             const facetResult = await cursor.toArray();
             return {
@@ -282,7 +281,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Updates a document with the given id in the collection
      *
-     * @param {MongoEntityService.UpdateOneCommand<T>} command
+     * @param command - The command information.
      */
     async _update(command) {
         isNotNullish(command.documentId, { label: 'documentId' });
@@ -314,7 +313,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Updates a document in the collection with the specified ID.
      *
-     * @param {MongoEntityService.UpdateOneCommand<T>} command
+     * @param command - The command information.
      */
     async _updateOnly(command) {
         isNotNullish(command.documentId, { label: 'documentId' });
@@ -331,7 +330,7 @@ export class MongoEntityService extends MongoService {
         ]);
         const db = this.getDatabase();
         const collection = await this.getCollection(db);
-        /** Create array fields if not exists */
+        /* Create array fields if not exists */
         if (options?.initArrayFields) {
             const $set = options.initArrayFields.reduce((a, k) => {
                 a[k] = { $ifNull: ['$' + k, []] };
@@ -345,7 +344,7 @@ export class MongoEntityService extends MongoService {
             });
             delete options.initArrayFields;
         }
-        /** Execute update operation */
+        /* Execute update operation */
         return (await collection.updateOne(filter || {}, update, {
             ...options,
             session: options?.session ?? this.getSession(),
@@ -355,7 +354,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Updates multiple documents in the collection based on the specified input and options.
      *
-     * @param {MongoEntityService.UpdateManyCommand<T>} command
+     * @param command - The command information.
      */
     async _updateMany(command) {
         isNotNullish(command.input, { label: 'input' });
@@ -369,7 +368,7 @@ export class MongoEntityService extends MongoService {
         const filter = MongoAdapter.prepareFilter(options?.filter);
         const db = this.getDatabase();
         const collection = await this.getCollection(db);
-        /** Create array fields if not exists */
+        /* Create array fields if not exists */
         if (options?.initArrayFields) {
             const $set = options.initArrayFields.reduce((a, k) => {
                 a[k] = { $ifNull: ['$' + k, []] };
@@ -383,7 +382,7 @@ export class MongoEntityService extends MongoService {
             });
             delete options.initArrayFields;
         }
-        /** Execute update operation */
+        /* Execute update operation */
         return (await collection.updateMany(filter || {}, update, {
             ...omit(options, ['filter']),
             session: options?.session ?? this.getSession(),
@@ -393,7 +392,7 @@ export class MongoEntityService extends MongoService {
     /**
      * Replaces a document with the given id in the collection
      *
-     * @param {MongoEntityService.ReplaceCommand<T>} command
+     * @param command - The command information.
      */
     async _replace(command) {
         const input = command.input;
@@ -452,7 +451,7 @@ export class MongoEntityService 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 === 'delete' && command.byId) {
@@ -470,10 +469,10 @@ export class MongoEntityService extends MongoService {
                 else if (command.crud === 'update' && !command.byId) {
                     await this._beforeUpdateMany(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 === 'delete' && command.byId) {