@common-stack/store-mongo 7.1.1-alpha.8 → 7.1.1-alpha.9

package/lib/module.d.ts

@@ -1,2 +1,3 @@
-declare const _default: any;
+import { Feature } from '@common-stack/server-core';
+declare const _default: Feature<import("@common-stack/server-core").ConfigurationScope, any>;
 export default _default;

package/lib/templates/constants/SERVER_TYPES.ts.template

@@ -0,0 +1,5 @@
+export const SERVER_TYPES = {
+    BaseMongoRepository: Symbol.for('BaseMongoRepository'),
+    BaseMongoService: Symbol.for('BaseMongoService'),
+    BaseService: Symbol.for('BaseService'),
+}

package/lib/templates/repositories/DatabaseMigration.ts.template

@@ -0,0 +1,13 @@
+
+export interface IDatabaseMigration {
+
+    /**
+     * ID of the migration, and it should be changed inorder to overwrite previous migration
+     */
+    id: string;
+
+    up?(): Promise<void>;
+
+
+    down?(): Promise<void>;
+}

package/lib/templates/repositories/IBaseMongoRepository.ts.template

@@ -0,0 +1,284 @@
+/**
+ * @file BaseMongoRepository.ts
+ * @description Defines the IBaseMongoRepository interface that provides a standardized set of methods for interacting with MongoDB collections.
+ * This interface serves as a contract for repository implementations, ensuring consistent data access patterns across the application.
+ * It includes methods for CRUD operations, querying with filters, pagination, and aggregation pipelines.
+ *
+ * The interface is generic, accepting a SchemaType parameter that represents the Mongoose schema structure for the collection.
+ * Methods return domain objects (with 'id' instead of '_id') using the AsDomainType transformation.
+ *
+ * Key features:
+ * - Consistent data access patterns across different entity types
+ * - Type-safe operations with MongoDB collections
+ * - Support for pagination, filtering, and sorting
+ * - Aggregation pipeline integration for complex queries
+ * - Bulk operations for performance optimization
+ *
+ * This repository pattern creates a clean separation between the data access layer and business logic,
+ * making the codebase more maintainable and testable.
+ *
+ * @see IBaseService2 - Service layer that uses repositories for business logic
+ * @see IDataLoader2 - Efficient data loading pattern that can utilize repositories
+ * @see GetAllArgs - Common arguments for querying collections
+ */
+
+import type { FilterQuery, Model, PipelineStage, UpdateQuery } from 'mongoose';
+import { AsDomainType, CreateType, GetAllArgs, GetAllWithCountResult, UpdateType } from './dbCommonTypes';
+
+export interface IBaseMongoRepository<SchemaType> {
+    /**
+     * The Mongoose model associated with this repository
+     * Used for direct database operations
+     */
+    model: Model<SchemaType>;
+
+    /**
+     * Counts documents matching the specified conditions
+     *
+     * @param conditions - Optional filter criteria to count specific documents
+     * @returns Promise resolving to the count of matching documents
+     *
+     * @example
+     * // Count all active users
+     * const activeUserCount = await userRepository.count({ active: true });
+     */
+    count(conditions?: FilterQuery<SchemaType>): Promise<number>;
+
+    /**
+     * Retrieves documents matching the specified options
+     *
+     * @param options - Query options including filtering, sorting, pagination, and field selection
+     * @returns Promise resolving to an array of domain objects
+     *
+     * @example
+     * // Get recently created users with pagination
+     * const users = await userRepository.getAll({
+     *   criteria: { active: true },
+     *   sort: { createdAt: -1 },
+     *   skip: 0,
+     *   limit: 10
+     * });
+     */
+    getAll(options: GetAllArgs<SchemaType>): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Retrieves documents using a custom aggregation pipeline
+     *
+     * @param options - Base query options for filtering and pagination
+     * @param customPipeline - Optional MongoDB aggregation pipeline stages
+     * @returns Promise resolving to an array of domain objects
+     *
+     * @example
+     * // Get users with computed fields using aggregation
+     * const users = await userRepository.getAllWithPipeline(
+     *   { limit: 10 },
+     *   [
+     *     { $lookup: { from: 'posts', localField: '_id', foreignField: 'userId', as: 'posts' } },
+     *     { $addFields: { postCount: { $size: '$posts' } } }
+     *   ]
+     * );
+     */
+    getAllWithPipeline(
+        options: GetAllArgs<SchemaType>,
+        customPipeline?: PipelineStage[],
+    ): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Retrieves documents with pagination and total count
+     *
+     * @param options - Query options including filtering, sorting, pagination, and field selection
+     * @returns Promise resolving to object with data array and total count
+     *
+     * @example
+     * // Get paginated users with total count for UI pagination
+     * const { data, totalCount } = await userRepository.getAllWithCount({
+     *   criteria: { role: 'user' },
+     *   skip: 20,
+     *   limit: 10
+     * });
+     */
+    getAllWithCount(options: GetAllArgs<SchemaType>): Promise<GetAllWithCountResult<SchemaType>>;
+
+    /**
+     * Retrieves documents with pagination, total count, and custom aggregation pipeline
+     *
+     * @param options - Base query options for filtering and pagination
+     * @param customPipeline - Optional MongoDB aggregation pipeline stages
+     * @returns Promise resolving to object with data array and total count
+     *
+     * @example
+     * // Get paginated users with related data and total count
+     * const result = await userRepository.getAllWithCountAndPipeline(
+     *   { limit: 10, skip: 0 },
+     *   [{ $lookup: { from: 'departments', localField: 'departmentId', foreignField: '_id', as: 'department' } }]
+     * );
+     */
+    getAllWithCountAndPipeline(
+        options: GetAllArgs<SchemaType>,
+        customPipeline?: PipelineStage[],
+    ): Promise<{
+        data: AsDomainType<SchemaType>[];
+        totalCount: number;
+    }>;
+
+    /**
+     * Retrieves a single document matching the specified conditions
+     *
+     * @param conditions - Filter criteria to find the document
+     * @param selectedFields - Optional space-separated string of fields to include
+     * @returns Promise resolving to a domain object or null if not found
+     *
+     * @example
+     * // Get user by email with selected fields
+     * const user = await userRepository.get({ email: 'user@example.com' }, 'name email role');
+     */
+    get(conditions?: FilterQuery<SchemaType>, selectedFields?: string): Promise<AsDomainType<SchemaType> | null>;
+
+    /**
+     * Finds a single document matching the specified conditions
+     * Similar to get() but with partial filter query support
+     *
+     * @param conditions - Partial filter criteria to find the document
+     * @param selectedFields - Optional space-separated string of fields to include
+     * @returns Promise resolving to a domain object or null if not found
+     *
+     * @example
+     * // Find user by partial match
+     * const user = await userRepository.find({ name: { $regex: 'John' } });
+     */
+    find(
+        conditions: Partial<FilterQuery<SchemaType>>,
+        selectedFields?: string,
+    ): Promise<AsDomainType<SchemaType> | null>;
+
+    /**
+     * Creates a new document
+     *
+     * @param data - Data for the new document
+     * @returns Promise resolving to the created domain object
+     *
+     * @example
+     * // Create a new user
+     * const newUser = await userRepository.create({
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     *   role: 'user'
+     * });
+     */
+    create<T = CreateType<SchemaType>>(data: T): Promise<AsDomainType<SchemaType>>;
+
+    /**
+     * Updates a document if it exists, otherwise creates it
+     *
+     * @param conditions - Filter criteria to find the document to update
+     * @param update - Data to update or create the document
+     * @param options - Optional MongoDB options for the operation
+     * @returns Promise resolving to the updated or created domain object
+     *
+     * @example
+     * // Upsert a user by email
+     * const user = await userRepository.upsert(
+     *   { email: 'john@example.com' },
+     *   { name: 'John Doe', role: 'admin' }
+     * );
+     */
+    upsert<T = UpdateType<SchemaType>>(
+        conditions: FilterQuery<SchemaType>,
+        update: T,
+        options?: Record<string, unknown>,
+    ): Promise<AsDomainType<SchemaType>>;
+
+    /**
+     * Updates a single document matching the criteria
+     *
+     * @param criteria - Filter criteria to find the document to update
+     * @param update - Data to update the document
+     * @param options - Optional MongoDB options for the operation
+     * @returns Promise resolving to the updated domain object
+     *
+     * @example
+     * // Update a user's role
+     * const updatedUser = await userRepository.update(
+     *   { _id: userId },
+     *   { role: 'admin' }
+     * );
+     */
+    update<T = UpdateType<SchemaType>>(
+        criteria: FilterQuery<SchemaType>,
+        update: T | UpdateQuery<SchemaType>,
+        options?: Record<string, unknown>,
+    ): Promise<AsDomainType<SchemaType>>;
+
+    /**
+     * Updates multiple documents matching the criteria
+     *
+     * @param criteria - Filter criteria to find documents to update
+     * @param update - Data to update the documents
+     * @param options - Optional MongoDB options for the operation
+     * @returns Promise resolving to an array of updated domain objects
+     *
+     * @example
+     * // Update all inactive users to active
+     * const updatedUsers = await userRepository.bulkUpdate(
+     *   { active: false },
+     *   { active: true }
+     * );
+     */
+    bulkUpdate<T = UpdateType<SchemaType>>(
+        criteria: FilterQuery<SchemaType>,
+        update: T | UpdateQuery<SchemaType>,
+        options?: Record<string, unknown>,
+    ): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Deletes a document matching the criteria
+     *
+     * @param criteria - Filter criteria to find the document to delete
+     * @returns Promise resolving to boolean indicating success
+     *
+     * @example
+     * // Delete a user by ID
+     * const success = await userRepository.delete({ _id: userId });
+     */
+    delete(criteria: FilterQuery<SchemaType>): Promise<boolean>;
+
+    /**
+     * Retrieves multiple documents by their IDs
+     *
+     * @param ids - Array of document IDs to retrieve
+     * @param selectedFields - Optional space-separated string of fields to include
+     * @returns Promise resolving to an array of domain objects
+     *
+     * @example
+     * // Get multiple users by their IDs
+     * const users = await userRepository.bulkGet(['id1', 'id2', 'id3']);
+     */
+    bulkGet(ids: string[], selectedFields?: string): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Creates multiple documents in a single operation
+     *
+     * @param data - Array of data for the new documents
+     * @returns Promise resolving to an array of created domain objects
+     *
+     * @example
+     * // Create multiple users at once
+     * const newUsers = await userRepository.bulkCreate([
+     *   { name: 'John', email: 'john@example.com' },
+     *   { name: 'Jane', email: 'jane@example.com' }
+     * ]);
+     */
+    bulkCreate<T = CreateType<SchemaType>>(data: T[]): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Deletes multiple documents matching the criteria
+     *
+     * @param criteria - Filter criteria to find documents to delete
+     * @returns Promise resolving to the number of deleted documents
+     *
+     * @example
+     * // Delete all inactive users
+     * const deletedCount = await userRepository.bulkDelete({ active: false });
+     */
+    bulkDelete(criteria: FilterQuery<SchemaType>): Promise<number>;
+}

package/lib/templates/repositories/IBaseService.ts.template

@@ -0,0 +1,231 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file BaseService.ts
+ * @description Defines the IBaseService interface that provides a standardized set of service methods for business logic operations.
+ * This interface acts as an abstraction layer between controllers and repositories, implementing domain-specific logic.
+ * It offers methods for retrieving, creating, updating, and deleting domain entities, with support for filtering and pagination.
+ *
+ * The interface is generic, accepting a SchemaType parameter that represents the underlying data structure.
+ * Methods operate on and return domain objects (with 'id' instead of '_id') using the AsDomainType transformation.
+ *
+ * Key features:
+ * - Abstraction layer between controllers and repositories
+ * - Consistent API for business logic operations
+ * - Database-agnostic design
+ * - Domain-focused data manipulation
+ * - Support for single and bulk operations
+ * - Type-safe method signatures
+ *
+ * This service layer helps maintain separation of concerns and promotes code reusability across the application.
+ * Services typically use repositories for data access but add business rules, validation, and orchestration.
+ *
+ * @see IBaseMongoRepository - MongoDB data access layer used by services
+ * @see AsDomainType - Type transformation for domain objects
+ * @see GetAllArgs - Query options for retrieving collections
+ */
+
+import { GetAllArgs, AsDomainType, CreateType, UpdateType, FilterCriteria } from './dbCommonTypes';
+
+export interface IBaseService<SchemaType> {
+    /**
+     * Retrieves documents with pagination and total count
+     * Useful for implementing paginated UIs that need to know total pages
+     *
+     * @param options - Query options including filtering, sorting, pagination, and field selection
+     * @returns Promise resolving to object with data array and total count
+     *
+     * @example
+     * // Get paginated users with total count for UI pagination
+     * const { data, totalCount } = await userService.getAllWithCount({
+     *   criteria: { role: 'user' },
+     *   skip: 20,
+     *   limit: 10,
+     *   sort: { createdAt: -1 }
+     * });
+     */
+    getAllWithCount(options: GetAllArgs<SchemaType>): Promise<{
+        data: AsDomainType<SchemaType>[];
+        totalCount: number;
+    }>;
+
+    /**
+     * Counts documents matching the specified conditions
+     *
+     * @param conditions - Optional filter criteria to count specific documents
+     * @returns Promise resolving to the count of matching documents
+     *
+     * @example
+     * // Count all active users
+     * const activeUserCount = await userService.count({ active: true });
+     */
+    count(conditions?: FilterCriteria<SchemaType>): Promise<number>;
+
+    /**
+     * Retrieves a single document by ID or matching the specified conditions
+     *
+     * @param conditions - Document ID as string or filter criteria to find the document
+     * @returns Promise resolving to a domain object or null if not found
+     *
+     * @example
+     * // Get user by ID
+     * const user = await userService.get('60d21b4667d0d8992e610c85');
+     *
+     * // Get user by email
+     * const user = await userService.get({ email: 'user@example.com' });
+     */
+    get(conditions: string | FilterCriteria<SchemaType>): Promise<AsDomainType<SchemaType> | null>;
+
+    /**
+     * Retrieves a single document by name field
+     * Commonly used for entities that have a unique name identifier
+     *
+     * @param name - Name value to search for
+     * @returns Promise resolving to a domain object or null if not found
+     *
+     * @example
+     * // Get product by name
+     * const product = await productService.getByName('Premium Subscription');
+     */
+    getByName(name: string): Promise<AsDomainType<SchemaType> | null>;
+
+    /**
+     * Retrieves documents matching the specified options
+     *
+     * @param options - Query options including filtering, sorting, pagination, and field selection
+     * @returns Promise resolving to an array of domain objects
+     *
+     * @example
+     * // Get recently created users with pagination
+     * const users = await userService.getAll({
+     *   criteria: { active: true },
+     *   sort: { createdAt: -1 },
+     *   skip: 0,
+     *   limit: 10
+     * });
+     */
+    getAll(options: GetAllArgs<SchemaType>): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Retrieves multiple documents by their IDs
+     *
+     * @param ids - Array of document IDs to retrieve
+     * @returns Promise resolving to an array of domain objects
+     *
+     * @example
+     * // Get multiple users by their IDs
+     * const users = await userService.getByIds(['id1', 'id2', 'id3']);
+     */
+    getByIds(ids: string[]): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Creates a new document
+     *
+     * @param data - Data for the new document
+     * @returns Promise resolving to the created domain object
+     *
+     * @example
+     * // Create a new user
+     * const newUser = await userService.create({
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     *   role: 'user'
+     * });
+     */
+    create<T = CreateType<SchemaType>>(data: T): Promise<AsDomainType<SchemaType>>;
+
+    /**
+     * Creates multiple documents in a single operation
+     *
+     * @param data - Array of data for the new documents
+     * @returns Promise resolving to an array of created domain objects
+     *
+     * @example
+     * // Create multiple users at once
+     * const newUsers = await userService.bulkCreate([
+     *   { name: 'John', email: 'john@example.com' },
+     *   { name: 'Jane', email: 'jane@example.com' }
+     * ]);
+     */
+    bulkCreate<T = CreateType<SchemaType>>(data: T[]): Promise<AsDomainType<SchemaType>[]>;
+
+    /**
+     * Updates a document by ID
+     *
+     * @param id - ID of the document to update
+     * @param data - Data to update the document
+     * @param overwrite - Whether to completely replace the document (true) or merge with existing (false)
+     * @returns Promise resolving to the updated domain object
+     *
+     * @example
+     * // Update a user's role
+     * const updatedUser = await userService.update(
+     *   'user123',
+     *   { role: 'admin', active: true }
+     * );
+     *
+     * // Replace a user document entirely
+     * const replacedUser = await userService.update(
+     *   'user123',
+     *   { name: 'New Name', email: 'new@example.com', role: 'user' },
+     *   true
+     * );
+     */
+    update<T = UpdateType<SchemaType>>(id: string, data: T, overwrite?: boolean): Promise<AsDomainType<SchemaType>>;
+
+    /**
+     * Creates a new document or updates it if ID is provided
+     * Useful for forms that handle both creation and updates
+     *
+     * @param data - Data for the new or updated document, optionally including an ID
+     * @param overwrite - Whether to completely replace the document (true) or merge with existing (false)
+     * @returns Promise resolving to the created or updated domain object
+     *
+     * @example
+     * // Create a new product
+     * const newProduct = await productService.insert({
+     *   name: 'New Product',
+     *   price: 99.99
+     * });
+     *
+     * // Update an existing product
+     * const updatedProduct = await productService.insert({
+     *   id: 'product123',
+     *   name: 'Updated Product',
+     *   price: 129.99
+     * });
+     */
+    insert<T = CreateType<SchemaType>>(
+        data: T & { id?: string },
+        overwrite?: boolean,
+    ): Promise<AsDomainType<SchemaType>>;
+
+    /**
+     * Deletes a document by ID or matching criteria
+     *
+     * @param id - Document ID as string or filter criteria to find the document to delete
+     * @returns Promise resolving to boolean indicating success
+     *
+     * @example
+     * // Delete a user by ID
+     * const success = await userService.delete('user123');
+     *
+     * // Delete a user by email
+     * const success = await userService.delete({ email: 'user@example.com' });
+     */
+    delete(id: string | FilterCriteria<SchemaType>): Promise<boolean>;
+
+    /**
+     * Deletes multiple documents matching the criteria
+     *
+     * @param criteria - Filter criteria to find documents to delete
+     * @returns Promise resolving to the number of deleted documents
+     *
+     * @example
+     * // Delete all inactive users
+     * const deletedCount = await userService.bulkDelete({ active: false });
+     *
+     * // Delete users with a specific role
+     * const deletedCount = await userService.bulkDelete({ role: 'guest' });
+     */
+    bulkDelete(criteria: FilterCriteria<SchemaType>): Promise<number>;
+}