@opra/mongodb 0.33.13 → 1.0.0-alpha.10

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

@@ -0,0 +1,258 @@
+import { ComplexType } from '@opra/common';
+import mongodb from 'mongodb';
+import { PartialDTO, PatchDTO, Type } from 'ts-gems';
+import { MongoAdapter } from './mongo-adapter.js';
+import { MongoCollectionService } from './mongo-collection-service.js';
+import { MongoService } from './mongo-service.js';
+import FilterInput = MongoAdapter.FilterInput;
+/**
+ *
+ * @namespace MongoNestedService
+ */
+export declare namespace MongoNestedService {
+    /**
+     * The constructor options of MongoArrayService.
+     */
+    interface Options extends MongoService.Options {
+        defaultLimit?: number;
+        nestedKey?: string;
+        $nestedFilter?: FilterInput | ((args: MongoService.CommandInfo, _this: this) => FilterInput | Promise<FilterInput> | undefined);
+    }
+    interface CreateOptions extends MongoService.CreateOptions {
+    }
+    interface CountOptions<T> extends MongoService.CountOptions<T> {
+        documentFilter?: FilterInput;
+    }
+    interface DeleteOptions<T> extends MongoService.DeleteOptions<T> {
+        documentFilter?: FilterInput;
+    }
+    interface DeleteManyOptions<T> extends MongoService.DeleteManyOptions<T> {
+        documentFilter?: FilterInput;
+    }
+    interface ExistsOptions<T> extends MongoService.ExistsOptions<T> {
+    }
+    interface ExistsOneOptions<T> extends MongoService.ExistsOneOptions<T> {
+    }
+    interface FindOneOptions<T> extends MongoService.FindOneOptions<T> {
+        documentFilter?: FilterInput;
+    }
+    interface FindManyOptions<T> extends MongoService.FindManyOptions<T> {
+        documentFilter?: FilterInput;
+        nestedFilter?: FilterInput;
+    }
+    interface UpdateOptions<T> extends MongoService.UpdateOptions<T> {
+        documentFilter?: FilterInput;
+    }
+    interface UpdateManyOptions<T> extends MongoService.UpdateManyOptions<T> {
+        documentFilter?: FilterInput;
+        count?: boolean;
+    }
+}
+/**
+ * A class that provides methods to perform operations on an array field in a MongoDB collection.
+ * @class MongoNestedService
+ * @template T The type of the array item.
+ */
+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?: FilterInput | ((args: MongoService.CommandInfo, _this: this) => FilterInput | Promise<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.
+     * @constructor
+     */
+    constructor(dataType: Type | string, fieldName: string, options?: MongoNestedService.Options);
+    /**
+     * 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.
+     */
+    get dataType(): ComplexType;
+    /**
+     * 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.
+     */
+    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 {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 with the partial output of the created item.
+     * @throws {ResourceNotAvailableError} - If the parent document is not found.
+     */
+    create(documentId: MongoAdapter.AnyId, input: PartialDTO<T>, options?: MongoNestedService.CreateOptions): Promise<PartialDTO<T>>;
+    protected _create(documentId: MongoAdapter.AnyId, input: PartialDTO<T>, options?: MongoNestedService.CreateOptions): Promise<PartialDTO<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.
+     */
+    count(documentId: MongoAdapter.AnyId, options?: MongoNestedService.CountOptions<T>): Promise<number>;
+    protected _count(documentId: MongoAdapter.AnyId, options?: MongoNestedService.CountOptions<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).
+     */
+    delete(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.DeleteOptions<T>): Promise<number>;
+    protected _delete(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.DeleteOptions<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.
+     */
+    deleteMany(documentId: MongoAdapter.AnyId, options?: MongoNestedService.DeleteManyOptions<T>): Promise<number>;
+    protected _deleteMany(documentId: MongoAdapter.AnyId, options?: MongoNestedService.DeleteManyOptions<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.
+     */
+    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.ExistsOneOptions} [options] - The options for the query (optional).
+     * @return {Promise<boolean>} - A Promise that resolves to a boolean indicating whether the object exists or not.
+     */
+    existsOne(documentId: MongoAdapter.AnyId, options?: MongoCollectionService.ExistsOneOptions<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.
+     */
+    findById(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<PartialDTO<T> | undefined>;
+    protected _findById(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<PartialDTO<T> | undefined>;
+    /**
+     * 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.
+     */
+    findOne(documentId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<PartialDTO<T> | undefined>;
+    protected _findOne(documentId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<PartialDTO<T> | undefined>;
+    /**
+     * 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.
+     */
+    findMany(documentId: MongoAdapter.AnyId, options?: MongoNestedService.FindManyOptions<T>): Promise<PartialDTO<T>[]>;
+    protected _findMany(documentId: MongoAdapter.AnyId, options: MongoNestedService.FindManyOptions<T>): Promise<PartialDTO<T>[]>;
+    /**
+     * 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.
+     */
+    findManyWithCount(documentId: MongoAdapter.AnyId, options?: MongoNestedService.FindManyOptions<T>): Promise<{
+        count: number;
+        items: PartialDTO<T>[];
+    }>;
+    protected _findManyWithCount(documentId: MongoAdapter.AnyId, options: MongoNestedService.FindManyOptions<T>): Promise<{
+        count: number;
+        items: PartialDTO<T>[];
+    }>;
+    /**
+     * 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.
+     */
+    get(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, options?: MongoNestedService.FindOneOptions<T>): Promise<PartialDTO<T>>;
+    /**
+     * Updates an array element with new data and returns the updated element
+     *
+     * @param {AnyId} documentId - The ID of the document to update.
+     * @param {AnyId} nestedId - The ID of the item to update within the document.
+     * @param {PatchDTO<T>} input - The new data to update the item with.
+     * @param {MongoNestedService.UpdateOptions<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.
+     */
+    update(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, input: PatchDTO<T>, options?: MongoNestedService.UpdateOptions<T>): Promise<PartialDTO<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 {PatchDTO<T>} input - The partial input object containing the fields to update.
+     * @param {MongoNestedService.UpdateOptions<T>} [options] - Optional update options.
+     * @returns {Promise<number>} - A promise that resolves to the number of elements updated.
+     */
+    updateOnly(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, input: PatchDTO<T>, options?: MongoNestedService.UpdateOptions<T>): Promise<number>;
+    protected _updateOnly(documentId: MongoAdapter.AnyId, nestedId: MongoAdapter.AnyId, input: PatchDTO<T>, options?: MongoNestedService.UpdateOptions<T>): Promise<number>;
+    /**
+     * Updates multiple array elements in document
+     *
+     * @param {MongoAdapter.AnyId} documentId - The ID of the document to update.
+     * @param {PatchDTO<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.
+     */
+    updateMany(documentId: MongoAdapter.AnyId, input: PatchDTO<T>, options?: MongoNestedService.UpdateManyOptions<T>): Promise<number>;
+    protected _updateMany(documentId: MongoAdapter.AnyId, input: PatchDTO<T>, options?: MongoNestedService.UpdateManyOptions<T>): Promise<number>;
+    /**
+     * Retrieves the common filter used for querying array elements.
+     * This method is mostly used for security issues like securing multi-tenant applications.
+     *
+     * @protected
+     * @returns {FilterInput | Promise<FilterInput> | undefined} The common filter or a Promise
+     * that resolves to the common filter, or undefined if not available.
+     */
+    protected _getNestedFilter(args: MongoService.CommandInfo): FilterInput | Promise<FilterInput> | undefined;
+}