@opra/mongodb 1.26.3 → 1.26.4

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

@@ -7,45 +7,93 @@ import type { MongoPatchDTO } from '../types.js';
 import type { MongoEntityService } from './mongo-entity-service.js';
 import { MongoService } from './mongo-service.js';
 /**
- *
- * @namespace MongoNestedService
+ * Options for MongoNestedService.
  */
 export declare namespace MongoNestedService {
     /**
-     * The constructor options of MongoArrayService.
+     * Configuration options for MongoNestedService.
      */
     interface Options extends MongoService.Options {
+        /**
+         * Default maximum number of records returned by `findMany`.
+         */
         defaultLimit?: number;
+        /**
+         * The field name of the primary key in the nested collection.
+         */
         nestedKey?: string;
+        /**
+         * Optional filter for nested operations.
+         */
         nestedFilter?: MongoAdapter.FilterInput | ((args: MongoService.CommandInfo, _this: this) => MongoAdapter.FilterInput | Promise<MongoAdapter.FilterInput> | undefined);
     }
+    /**
+     * 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> {
         documentFilter?: MongoAdapter.FilterInput;
     }
+    /**
+     * Options for the `delete` operation.
+     * @template T - The type of the document.
+     */
     interface DeleteOptions<T> extends MongoService.DeleteOptions<T> {
         documentFilter?: MongoAdapter.FilterInput;
     }
+    /**
+     * Options for the `deleteMany` operation.
+     * @template T - The type of the document.
+     */
     interface DeleteManyOptions<T> extends MongoService.DeleteManyOptions<T> {
         documentFilter?: MongoAdapter.FilterInput;
     }
+    /**
+     * 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> {
         documentFilter?: MongoAdapter.FilterInput;
     }
+    /**
+     * Options for the `findMany` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface FindManyOptions<T> extends MongoService.FindManyOptions<T> {
         documentFilter?: MongoAdapter.FilterInput;
         nestedFilter?: MongoAdapter.FilterInput;
     }
+    /**
+     * Options for the `update` / `updateOnly` operations.
+     *
+     * @template T - The type of the document.
+     */
     interface UpdateOneOptions<T> extends MongoService.UpdateOneOptions<T> {
         documentFilter?: MongoAdapter.FilterInput;
+        initArrayFields?: string[];
     }
+    /**
+     * Options for the `updateMany` operation.
+     *
+     * @template T - The type of the document.
+     */
     interface UpdateManyOptions<T> extends MongoService.UpdateManyOptions<T> {
         documentFilter?: MongoAdapter.FilterInput;
+        initArrayFields?: string[];
     }
     interface CreateCommand<T> extends RequiredSome<CommandInfo, 'documentId' | 'input'> {
         crud: 'create';
@@ -91,51 +139,43 @@ export declare namespace MongoNestedService {
 export declare class MongoNestedService<T extends mongodb.Document> extends MongoService<T> {
     /**
      * Represents the name of the array field in parent document
-     *
-     * @type {string}
      */
     fieldName: string;
     /**
      * Represents the value of a nested array key field
-     *
-     * @type {string}
      */
     nestedKey: string;
     /**
      * Represents the default limit value for a certain operation.
-     *
-     * @type {number}
      */
     defaultLimit: number;
     /**
      * Represents a common array filter function
-     *
-     * @type {FilterInput | Function}
      */
     nestedFilter?: MongoAdapter.FilterInput | ((args: MongoService.CommandInfo, _this: this) => MongoAdapter.FilterInput | Promise<MongoAdapter.FilterInput> | undefined);
     /**
      * 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: Type | string, fieldName: string, options?: MongoNestedService.Options);
     /**
-     * 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(): ComplexType;
     /**
      * 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
      */
@@ -144,87 +184,87 @@ export declare class MongoNestedService<T extends mongodb.Document> extends Mong
      * 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.
      */
     assert(documentId: MongoAdapter.AnyId, id: MongoAdapter.AnyId, options?: MongoNestedService.ExistsOptions<T>): Promise<void>;
     /**
      * Adds a single item into the array field.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
-     * @param {PartialDTO<T>} input - The item to be added to the array field.
-     * @param {MongoNestedService.CreateOptions<T>} [options] - Optional options for the create operation.
-     * @return {Promise<PartialDTO<T>>} - A promise that resolves with the partial output of the created item.
-     * @throws {ResourceNotAvailableError} - If the parent document is not found.
+     * @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 with the partial output of the created item.
+     * @throws {@link ResourceNotAvailableError} - If the parent document is not found.
      */
     create(documentId: MongoAdapter.AnyId, input: PartialDTO<T>, options: RequiredSome<MongoNestedService.CreateOptions, 'projection'>): Promise<PartialDTO<T>>;
     create(documentId: MongoAdapter.AnyId, input: PartialDTO<T>, options?: MongoNestedService.CreateOptions): Promise<T>;
     /**
      * 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.
      */
     createOnly(documentId: MongoAdapter.AnyId, input: DTO<T>, options?: MongoNestedService.CreateOptions): Promise<PartialDTO<T>>;
     protected _create(command: MongoNestedService.CreateCommand<T>): Promise<T>;
     /**
      * 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.
      */
     count(documentId: MongoAdapter.AnyId, options?: MongoNestedService.CountOptions<T>): Promise<number>;
     protected _count(command: MongoNestedService.CountCommand<T>): Promise<number>;
     /**
      * 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).
      */
     delete(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.DeleteOptions<T>): Promise<number>;
     protected _delete(command: MongoNestedService.DeleteCommand<T>): Promise<number>;
     /**
      * 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.
      */
     deleteMany(documentId: MongoAdapter.AnyId, options?: MongoNestedService.DeleteManyOptions<T>): Promise<number>;
     protected _deleteMany(command: MongoNestedService.DeleteCommand<T>): Promise<number>;
     /**
      * 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.
      */
     exists(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.ExistsOptions<T>): Promise<boolean>;
     /**
      * 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.
      */
     existsOne(documentId: MongoAdapter.AnyId, options?: MongoNestedService.ExistsOptions<T>): Promise<boolean>;
     /**
      * Finds an element in array field by its parent ID and ID.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the document.
-     * @param {MongoAdapter.AnyId} nestedId - The ID of the document.
-     * @param {MongoNestedService.FindOneOptions<T>} [options] - The optional options for the operation.
-     * @returns {Promise<PartialDTO<T> | undefined>} - A promise that resolves to the found document or undefined if not found.
+     * @param documentId - The ID of the document.
+     * @param nestedId - The ID of the document.
+     * @param [options] - The optional options for the operation.
+     * @returns A promise that resolves to the found document or undefined if not found.
      */
     findById(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options: RequiredSome<MongoNestedService.FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>;
     findById(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<T | undefined>;
@@ -232,9 +272,9 @@ export declare class MongoNestedService<T extends mongodb.Document> extends Mong
     /**
      * Finds the first array element that matches the given parentId.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the document.
-     * @param {MongoNestedService.FindOneOptions<T>} [options] - Optional options to customize the query.
-     * @returns {Promise<PartialDTO<T> | undefined>} A promise that resolves to the first matching document, or `undefined` if no match is found.
+     * @param documentId - The ID of the document.
+     * @param [options] - Optional options to customize the query.
+     * @returns A promise that resolves to the first matching document, or `undefined` if no match is found.
      */
     findOne(documentId: MongoAdapter.AnyId, options: RequiredSome<MongoNestedService.FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>;
     findOne(documentId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<T | undefined>;
@@ -242,9 +282,9 @@ export declare class MongoNestedService<T extends mongodb.Document> extends Mong
     /**
      * Finds multiple elements in an array field.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
-     * @param {MongoNestedService.FindManyOptions<T>} [options] - The options for finding the documents.
-     * @returns {Promise<PartialDTO<T>[]>} - The found documents.
+     * @param documentId - The ID of the parent document.
+     * @param [options] - The options for finding the documents.
+     * @returns The found documents.
      */
     findMany(documentId: MongoAdapter.AnyId, options: RequiredSome<MongoNestedService.FindManyOptions<T>, 'projection'>): Promise<PartialDTO<T>[]>;
     findMany(documentId: MongoAdapter.AnyId, options?: MongoNestedService.FindManyOptions<T>): Promise<T[]>;
@@ -252,9 +292,9 @@ export declare class MongoNestedService<T extends mongodb.Document> extends Mong
     /**
      * Finds multiple elements in an array field.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the parent document.
-     * @param {MongoNestedService.FindManyOptions<T>} [options] - The options for finding the documents.
-     * @returns {Promise<PartialDTO<T>[]>} - The found documents.
+     * @param documentId - The ID of the parent document.
+     * @param [options] - The options for finding the documents.
+     * @returns The found documents.
      */
     findManyWithCount(documentId: MongoAdapter.AnyId, options: RequiredSome<MongoNestedService.FindManyOptions<T>, 'projection'>): Promise<{
         count: number;
@@ -271,44 +311,53 @@ export declare class MongoNestedService<T extends mongodb.Document> extends Mong
     /**
      * Retrieves a specific item from the array of a document.
      *
-     * @param {MongoAdapter.AnyId} documentId - The ID of the document.
-     * @param {MongoAdapter.AnyId} nestedId - The ID of the item.
-     * @param {MongoNestedService.FindOneOptions<T>} [options] - The options for finding the item.
-     * @returns {Promise<PartialDTO<T>>} - The item found.
-     * @throws {ResourceNotAvailableError} - If the item is not found.
+     * @param documentId - The ID of the document.
+     * @param nestedId - The ID of the item.
+     * @param options - Options including a required `projection`.
+     * @returns A promise that resolves to the retrieved document as a partial DTO.
+     * @throws {@link ResourceNotAvailableError} - If the item is not found.
      */
     get(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options: RequiredSome<MongoNestedService.FindOneOptions<T>, 'projection'>): Promise<PartialDTO<T>>;
+    /**
+     * Retrieves a specific item from the array of a document and returns it as a full DTO.
+     *
+     * @param documentId - The ID of the document.
+     * @param nestedId - The ID of the item.
+     * @param options - Optional query options.
+     * @returns A promise that resolves to the retrieved document as a full DTO.
+     * @throws {@link ResourceNotAvailableError} - If the item is not found.
+     */
     get(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<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} nestedId - The ID of the item to update within the document.
-     * @param {MongoPatchDTO<T>} input - The new data to update the item with.
-     * @param {MongoNestedService.UpdateOneOptions<T>} [options] - Additional update options.
-     * @returns {Promise<PartialDTO<T> | undefined>} The updated item or undefined if it does not exist.
-     * @throws {Error} If an error occurs while updating the item.
+     * @param documentId - The ID of the document to update.
+     * @param nestedId - The ID of the item to update within the document.
+     * @param input - The new data to update the item with.
+     * @param [options] - Additional update options.
+     * @returns The updated item or undefined if it does not exist.
+     * @throws {@link Error} If an error occurs while updating the item.
      */
     update(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, input: MongoPatchDTO<T>, options: RequiredSome<MongoNestedService.UpdateOneOptions<T>, 'projection'>): Promise<PartialDTO<T> | undefined>;
     update(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, input: MongoPatchDTO<T>, options?: MongoNestedService.UpdateOneOptions<T>): Promise<T | undefined>;
     /**
      * 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.
      */
     updateOnly(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, input: MongoPatchDTO<T>, options?: MongoNestedService.UpdateOneOptions<T>): Promise<number>;
     protected _updateOnly(command: MongoNestedService.UpdateOneCommand<T>): Promise<number>;
     /**
      * 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.
      */
     updateMany(documentId: MongoAdapter.AnyId, input: MongoPatchDTO<T>, options?: MongoNestedService.UpdateManyOptions<T>): Promise<number>;
     protected _updateMany(command: MongoNestedService.UpdateManyCommand<T>): Promise<number>;
@@ -317,7 +366,7 @@ export declare class MongoNestedService<T extends mongodb.Document> extends Mong
      * 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.
      */
     protected _getNestedFilter(args: MongoService.CommandInfo): MongoAdapter.FilterInput | Promise<MongoAdapter.FilterInput> | undefined;