@cyberskill/shared 2.20.0 → 2.25.0

package/dist/node/mongo/mongo.controller.d.ts

@@ -0,0 +1,317 @@
+import { default as mongooseRaw } from 'mongoose';
+import { I_Return } from '../../typescript/index.js';
+import { C_Db, C_Document, I_DeleteOptionsExtended, I_ExtendedModel, I_Input_CheckSlug, I_Input_CreateSlug, I_Input_GenerateSlug, I_PaginateOptionsWithPopulate, I_UpdateOptionsExtended, T_AggregatePaginateResult, T_DeleteResult, T_Filter, T_Input_Populate, T_InsertManyOptions, T_PaginateResult, T_PipelineStage, T_ProjectionType, T_QueryFilter, T_QueryOptions, T_UpdateQuery, T_UpdateResult, T_WithId } from './mongo.type.js';
+/**
+ * MongoDB native driver controller for direct database operations.
+ * This class provides a simplified interface for MongoDB operations using the native driver,
+ * with automatic generic field generation and standardized response formatting.
+ */
+export declare class MongoController<D extends Partial<C_Document>> {
+    private collection;
+    /**
+     * Creates a new MongoDB controller instance.
+     *
+     * @param db - The MongoDB database instance.
+     * @param collectionName - The name of the collection to operate on.
+     */
+    constructor(db: C_Db, collectionName: string);
+    /**
+     * Creates a single document in the collection.
+     * This method adds generic fields (id, isDel, timestamps) to the document before insertion.
+     *
+     * @param document - The document to create, with or without generic fields.
+     * @returns A promise that resolves to a standardized response with the created document.
+     */
+    createOne(document: D | Partial<D>): Promise<I_Return<D | Partial<D>>>;
+    /**
+     * Creates multiple documents in the collection.
+     * This method adds generic fields to each document before bulk insertion.
+     *
+     * @param documents - An array of documents to create.
+     * @returns A promise that resolves to a standardized response with the created documents.
+     */
+    createMany(documents: (D | Partial<D>)[]): Promise<I_Return<(D | Partial<D>)[]>>;
+    /**
+     * Finds a single document by filter criteria.
+     *
+     * @param filter - The filter criteria to find the document.
+     * @returns A promise that resolves to a standardized response with the found document.
+     */
+    findOne(filter: T_Filter<D>): Promise<I_Return<T_WithId<D>>>;
+    /**
+     * Finds all documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find documents (defaults to empty object for all documents).
+     * @returns A promise that resolves to a standardized response with the found documents.
+     */
+    findAll(filter?: T_Filter<D>): Promise<I_Return<T_WithId<D>[]>>;
+    /**
+     * Counts documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to count documents (defaults to empty object for all documents).
+     * @returns A promise that resolves to a standardized response with the document count.
+     */
+    count(filter?: T_Filter<D>): Promise<I_Return<number>>;
+    /**
+     * Updates a single document matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find the document to update.
+     * @param update - The update data to apply to the document.
+     * @returns A promise that resolves to a standardized response with the update result.
+     */
+    updateOne(filter: T_Filter<D>, update: Partial<D>): Promise<I_Return<T_UpdateResult>>;
+    /**
+     * Updates multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find documents to update.
+     * @param update - The update data to apply to the documents.
+     * @returns A promise that resolves to a standardized response with the update result.
+     */
+    updateMany(filter: T_Filter<D>, update: Partial<D>): Promise<I_Return<T_UpdateResult>>;
+    /**
+     * Deletes a single document matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find the document to delete.
+     * @returns A promise that resolves to a standardized response with the delete result.
+     */
+    deleteOne(filter: T_Filter<D>): Promise<I_Return<T_DeleteResult>>;
+    /**
+     * Deletes multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find documents to delete.
+     * @returns A promise that resolves to a standardized response with the delete result.
+     */
+    deleteMany(filter: T_Filter<D>): Promise<I_Return<T_DeleteResult>>;
+}
+/**
+ * Mongoose controller for database operations with advanced features.
+ * This class provides a comprehensive interface for Mongoose operations including
+ * pagination, aggregation, slug generation, and short ID creation.
+ */
+export declare class MongooseController<T extends Partial<C_Document>> {
+    private model;
+    /**
+     * Creates a new Mongoose controller instance.
+     *
+     * @param model - The Mongoose model to operate on.
+     */
+    constructor(model: I_ExtendedModel<T>);
+    /**
+     * Gets the model name for logging and error messages.
+     *
+     * @returns The name of the model.
+     */
+    private getModelName;
+    /**
+     * Gets the dynamic virtuals configuration from the model instance.
+     *
+     * @returns Array of dynamic virtual configurations or undefined if none exist.
+     */
+    private getDynamicVirtuals;
+    /**
+     * Populates dynamic virtuals for a single document.
+     *
+     * @param result - The document to populate dynamic virtuals for.
+     * @param populate - The populate options to determine which virtuals to populate.
+     * @returns The document with dynamic virtuals populated.
+     */
+    private populateDynamicVirtualsForDocument;
+    /**
+     * Populates dynamic virtuals for an array of documents.
+     *
+     * @param results - The documents to populate dynamic virtuals for.
+     * @param populate - The populate options to determine which virtuals to populate.
+     * @returns The documents with dynamic virtuals populated.
+     */
+    private populateDynamicVirtualsForDocuments;
+    /**
+     * Finds a single document with optional population and projection.
+     * Automatically handles dynamic virtual population if configured.
+     *
+     * @param filter - The filter criteria to find the document.
+     * @param projection - The fields to include/exclude in the result.
+     * @param options - Query options for the operation.
+     * @param populate - Population configuration for related documents.
+     * @returns A promise that resolves to a standardized response with the found document.
+     */
+    findOne(filter?: T_QueryFilter<T>, projection?: T_ProjectionType<T>, options?: T_QueryOptions<T>, populate?: T_Input_Populate): Promise<I_Return<T>>;
+    /**
+     * Finds all documents with optional population and projection.
+     * Automatically handles dynamic virtual population if configured.
+     *
+     * @param filter - The filter criteria to find documents.
+     * @param projection - The fields to include/exclude in the result.
+     * @param options - Query options for the operation.
+     * @param populate - Population configuration for related documents.
+     * @returns A promise that resolves to a standardized response with the found documents.
+     */
+    findAll(filter?: T_QueryFilter<T>, projection?: T_ProjectionType<T>, options?: T_QueryOptions<T>, populate?: T_Input_Populate): Promise<I_Return<T[]>>;
+    /**
+     * Finds documents with pagination support.
+     * Automatically handles dynamic virtual population if configured.
+     *
+     * @param filter - The filter criteria to find documents.
+     * @param options - Pagination options including page, limit, and population.
+     * @returns A promise that resolves to a standardized response with paginated results.
+     */
+    findPaging(filter?: T_QueryFilter<T>, options?: I_PaginateOptionsWithPopulate): Promise<I_Return<T_PaginateResult<T>>>;
+    /**
+     * Performs aggregation with pagination support.
+     *
+     * @param pipeline - The aggregation pipeline stages.
+     * @param options - Pagination options for the aggregation result.
+     * @returns A promise that resolves to a standardized response with paginated aggregation results.
+     */
+    findPagingAggregate(pipeline: T_PipelineStage[], options?: I_PaginateOptionsWithPopulate): Promise<I_Return<T_AggregatePaginateResult<T>>>;
+    /**
+     * Counts documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to count documents.
+     * @returns A promise that resolves to a standardized response with the document count.
+     */
+    count(filter?: T_QueryFilter<T>): Promise<I_Return<number>>;
+    /**
+     * Creates a single document.
+     *
+     * @param doc - The document to create.
+     * @returns A promise that resolves to a standardized response with the created document.
+     */
+    createOne(doc: T | Partial<T>): Promise<I_Return<T>>;
+    /**
+     * Creates multiple documents with bulk insertion.
+     *
+     * @param docs - An array of documents to create.
+     * @param options - Options for the bulk insertion operation.
+     * @returns A promise that resolves to a standardized response with the created documents.
+     */
+    createMany(docs: (T | Partial<T>)[], options?: T_InsertManyOptions): Promise<I_Return<T[]>>;
+    /**
+     * Updates a single document and returns the updated version.
+     *
+     * @param filter - The filter criteria to find the document to update.
+     * @param update - The update data to apply.
+     * @param options - Options for the update operation.
+     * @returns A promise that resolves to a standardized response with the updated document.
+     */
+    updateOne(filter?: T_QueryFilter<T>, update?: T_UpdateQuery<T>, options?: I_UpdateOptionsExtended): Promise<I_Return<T>>;
+    /**
+     * Updates multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find documents to update.
+     * @param update - The update data to apply.
+     * @param options - Options for the update operation.
+     * @returns A promise that resolves to a standardized response with the update result.
+     */
+    updateMany(filter?: T_QueryFilter<T>, update?: T_UpdateQuery<T>, options?: I_UpdateOptionsExtended): Promise<I_Return<T_UpdateResult>>;
+    /**
+     * Deletes a single document and returns the deleted version.
+     *
+     * @param filter - The filter criteria to find the document to delete.
+     * @param options - Options for the delete operation.
+     * @returns A promise that resolves to a standardized response with the deleted document.
+     */
+    deleteOne(filter?: T_QueryFilter<T>, options?: I_DeleteOptionsExtended): Promise<I_Return<T>>;
+    /**
+     * Deletes multiple documents matching the filter criteria.
+     *
+     * @param filter - The filter criteria to find documents to delete.
+     * @param options - Options for the delete operation.
+     * @returns A promise that resolves to a standardized response with the delete result.
+     */
+    deleteMany(filter?: T_QueryFilter<T>, options?: I_DeleteOptionsExtended): Promise<I_Return<T_DeleteResult>>;
+    /**
+     * Creates a unique short ID based on a given ID.
+     * This method generates multiple short IDs with increasing lengths and finds the first available one.
+     *
+     * @param id - The base ID to generate short IDs from.
+     * @param length - The initial length for short ID generation (default: 4).
+     * @returns A promise that resolves to a standardized response with the unique short ID.
+     */
+    createShortId(id: string, length?: number): Promise<I_Return<string>>;
+    /**
+     * Creates a query for slug existence checking.
+     * This method generates a query that checks for slug existence in both current and historical slug fields.
+     *
+     * @param options - Configuration for slug query generation including slug, field, and filter.
+     * @param options.slug - The slug string to check for existence.
+     * @param options.field - The field name for object-based slug checking.
+     * @param options.isObject - Whether the slug is stored as an object with nested fields.
+     * @param options.haveHistory - Whether to check historical slug fields for existence.
+     * @param options.filter - Additional filter conditions to apply to the query.
+     * @returns A MongoDB query object for checking slug existence.
+     */
+    createSlugQuery({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): (mongooseRaw.QueryFilter<T> & {
+        $or: ({
+            [x: string]: string;
+            slugHistory?: undefined;
+        } | {
+            slugHistory: {
+                $elemMatch: {
+                    [x: string]: string;
+                };
+            };
+        })[];
+    }) | (mongooseRaw.QueryFilter<T> & {
+        $or: ({
+            slug: string;
+            slugHistory?: undefined;
+        } | {
+            slugHistory: string;
+            slug?: undefined;
+        })[];
+    });
+    /**
+     * Creates a unique slug based on a given string.
+     * This method generates multiple slug variations and finds the first available one.
+     *
+     * @param options - Configuration for slug generation including slug, field, and filter.
+     * @param options.slug - The base slug string to make unique.
+     * @param options.field - The field name for object-based slug checking.
+     * @param options.isObject - Whether the slug is stored as an object with nested fields.
+     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.
+     * @param options.filter - Additional filter conditions to apply when checking slug existence.
+     * @returns A promise that resolves to a unique slug string.
+     */
+    createUniqueSlug({ slug, field, isObject, haveHistory, filter }: I_Input_GenerateSlug<T>): Promise<string>;
+    /**
+     * Creates a slug for a document field.
+     * This method handles both simple string fields and object fields with nested slug generation.
+     *
+     * @param options - Configuration for slug creation including field, source document, and filter.
+     * @param options.field - The field name to create a slug for.
+     * @param options.from - The source document containing the field value.
+     * @param options.haveHistory - Whether to check historical slug fields for uniqueness.
+     * @param options.filter - Additional filter conditions to apply when checking slug existence.
+     * @returns A promise that resolves to a standardized response with the created slug(s).
+     */
+    createSlug<R = string>({ field, from, filter, haveHistory }: I_Input_CreateSlug<T>): Promise<I_Return<R>>;
+    /**
+     * Checks if a slug already exists in the collection.
+     * This method verifies slug existence in both current and historical slug fields.
+     *
+     * @param options - Configuration for slug checking including slug, field, source document, and filter.
+     * @param options.slug - The slug string to check for existence.
+     * @param options.field - The field name for object-based slug checking.
+     * @param options.from - The source document containing the field value.
+     * @param options.haveHistory - Whether to check historical slug fields for existence.
+     * @param options.filter - Additional filter conditions to apply to the query.
+     * @returns A promise that resolves to a standardized response indicating whether the slug exists.
+     */
+    checkSlug({ slug, field, from, filter, haveHistory }: I_Input_CheckSlug<T>): Promise<I_Return<boolean>>;
+    /**
+     * Performs aggregation operations on the collection.
+     *
+     * @param pipeline - The aggregation pipeline stages to execute.
+     * @returns A promise that resolves to a standardized response with the aggregation results.
+     */
+    aggregate(pipeline: T_PipelineStage[]): Promise<I_Return<T[]>>;
+    /**
+     * Retrieves distinct values for the specified key from the collection.
+     *
+     * @param key - The field for which to return distinct values.
+     * @param filter - The filter query to apply (optional).
+     * @param options - Additional options for the distinct operation (optional).
+     * @returns A promise that resolves to a standardized response with the array of distinct values.
+     */
+    distinct(key: string, filter?: T_QueryFilter<T>, options?: T_QueryOptions<T>): Promise<I_Return<unknown[]>>;
+}