@common-stack/store-mongo 8.0.2-alpha.0 → 8.1.1-alpha.13

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

@@ -0,0 +1,211 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file IDataLoader.ts
+ * @description Defines interfaces for implementing the DataLoader pattern to efficiently batch and cache database queries.
+ *
+ * The DataLoader pattern helps prevent the N+1 query problem by consolidating multiple individual requests
+ * into a single batch request. This significantly improves performance for nested queries and relationship
+ * traversal in GraphQL or REST APIs.
+ *
+ * Architecture Context:
+ * - Part of the data access optimization layer
+ * - Sits between repositories and services/resolvers
+ * - Implements request batching and caching for efficient data access
+ * - Particularly valuable for GraphQL implementations to solve the N+1 query problem
+ * - Works with MongoDB collections through Mongoose
+ *
+ * Key features:
+ * - Request batching: Combines multiple individual requests into a single database query
+ * - In-memory caching: Prevents duplicate requests for the same entity
+ * - Custom loading options: Supports flexible query criteria beyond simple ID lookups
+ * - Clear cache methods: Allows for cache invalidation when data changes
+ *
+ * Usage Patterns:
+ * - Create a DataLoader instance for each entity type in your application
+ * - Use the load method for single entity retrieval by ID
+ * - Use loadMany for retrieving multiple entities by their IDs
+ * - Use withOptions for more complex queries with custom criteria
+ * - Clear cache entries when entities are modified
+ *
+ * Performance Impact:
+ * - Reduces database round trips by batching requests
+ * - Minimizes redundant queries through caching
+ * - Particularly effective for nested relationship queries in GraphQL
+ * - Can dramatically improve response times for complex data graphs
+ *
+ * @see IBaseMongoRepository - Repository layer that provides the underlying data access
+ * @see AsDomainType - Type transformation for domain objects
+ */
+
+import DataLoader from 'dataloader';
+import type { FilterQuery } from 'mongoose';
+import { AsDomainType } from './dbCommonTypes';
+
+/**
+ * Options for configuring how entities are loaded through the DataLoader
+ *
+ * @property id - Unique identifier for the request (used for caching)
+ * @property searchKey - The field to search by (typically 'id' or another indexed field)
+ * @property comparator - Optional custom function to determine if an item matches the search criteria
+ * @property criteria - Optional additional filter criteria to apply to the query
+ *
+ * @example
+ * // Basic options for loading by ID
+ * const options: DataLoaderOptions<UserSchema> = {
+ *   id: '123',
+ *   searchKey: 'id'
+ * };
+ *
+ * // Advanced options with custom criteria
+ * const options: DataLoaderOptions<UserSchema> = {
+ *   id: 'active-admins',
+ *   searchKey: 'role',
+ *   criteria: { active: true, role: 'admin' },
+ *   comparator: (opt, item) => item.role === 'admin' && item.active === true
+ * };
+ */
+export interface DataLoaderOptions<SchemaType> {
+    /** Unique identifier for the request (used for caching) */
+    id: string;
+
+    /** The field to search by (typically 'id' or another indexed field) */
+    searchKey: keyof AsDomainType<SchemaType> | string;
+
+    /** Optional custom function to determine if an item matches the search criteria */
+    comparator?: (option: DataLoaderOptions<SchemaType>, item: AsDomainType<SchemaType>) => boolean;
+
+    /** Optional additional filter criteria to apply to the query */
+    criteria?: FilterQuery<SchemaType>;
+
+    /** Additional custom properties can be added as needed */
+    [key: string]: any;
+}
+
+/**
+ * Interface for implementing the DataLoader pattern to efficiently batch and cache database queries
+ *
+ * The IDataLoader interface provides methods for loading single or multiple entities by ID,
+ * clearing cache entries, and loading entities with custom options. This implementation
+ * supports MongoDB collections through Mongoose.
+ *
+ * @example
+ * // Create a user data loader
+ * const userLoader = new MongoDataLoader(UserModel);
+ *
+ * // Load a user by ID (batched and cached)
+ * const user1 = await userLoader.load('user1');
+ * const user2 = await userLoader.load('user2');
+ *
+ * // Load multiple users by ID in a single batch
+ * const users = await userLoader.loadMany(['user3', 'user4', 'user5']);
+ *
+ * // Load users with custom criteria
+ * const activeAdmins = await userLoader.withOptions.load({
+ *   id: 'active-admins',
+ *   searchKey: 'role',
+ *   criteria: { active: true, role: 'admin' }
+ * });
+ *
+ * // Clear cache when a user is updated
+ * userLoader.clear('user1');
+ */
+export interface IDataLoader<SchemaType> {
+    /**
+     * Load a single entity by ID
+     *
+     * This method retrieves a single entity by its unique identifier.
+     * Requests are batched with other load calls in the same tick of the event loop
+     * and results are cached to prevent duplicate database queries.
+     *
+     * @param id - The unique identifier of the entity to load
+     * @returns Promise resolving to the domain entity or null if not found
+     *
+     * @example
+     * // Load a user by ID
+     * const user = await userLoader.load('user123');
+     *
+     * // Handle case where entity might not exist
+     * const product = await productLoader.load('product456');
+     * if (product) {
+     *   // Product exists, use it
+     * } else {
+     *   // Product not found
+     * }
+     */
+    load: (id: string) => Promise<AsDomainType<SchemaType> | null>;
+
+    /**
+     * Load multiple entities by their IDs
+     *
+     * This method retrieves multiple entities by their unique identifiers in a single batch.
+     * Results are cached to prevent duplicate database queries.
+     *
+     * @param ids - Array of unique identifiers of the entities to load
+     * @returns Promise resolving to an array of domain entities, nulls, or errors
+     *
+     * @example
+     * // Load multiple users by their IDs
+     * const users = await userLoader.loadMany(['user1', 'user2', 'user3']);
+     *
+     * // Handle results which may include nulls for not found entities
+     * const validUsers = users.filter(user => user !== null && !(user instanceof Error));
+     */
+    loadMany: (ids: string[]) => Promise<(AsDomainType<SchemaType> | null | Error)[]>;
+
+    /**
+     * Clear a single entity from the cache
+     *
+     * This method removes a specific entity from the cache, forcing the next load
+     * request for this ID to query the database. Use this when an entity is updated
+     * or deleted to ensure fresh data is loaded.
+     *
+     * @param id - The unique identifier of the entity to remove from cache
+     * @returns The DataLoader instance for method chaining
+     *
+     * @example
+     * // Update a user and clear the cache
+     * await userService.update('user123', { name: 'New Name' });
+     * userLoader.clear('user123');
+     */
+    clear: (id: string) => DataLoader<string, AsDomainType<SchemaType> | null>;
+
+    /**
+     * Clear all entities from the cache
+     *
+     * This method removes all entities from the cache, forcing the next load
+     * requests to query the database. Use this when multiple entities are updated
+     * or when you need to ensure all data is fresh.
+     *
+     * @returns The DataLoader instance for method chaining
+     *
+     * @example
+     * // After a bulk update operation, clear the entire cache
+     * await userService.bulkUpdate({ role: 'user' }, { active: true });
+     * userLoader.clearAll();
+     */
+    clearAll: () => DataLoader<string, AsDomainType<SchemaType> | null>;
+
+    /**
+     * DataLoader for loading entities with custom options
+     *
+     * This property provides a DataLoader instance that supports more complex
+     * loading scenarios beyond simple ID lookups. Use this when you need to
+     * load entities based on other criteria or with additional filtering.
+     *
+     * @example
+     * // Load active users with the admin role
+     * const adminUsers = await userLoader.withOptions.load({
+     *   id: 'active-admins', // Unique cache key
+     *   searchKey: 'role',
+     *   criteria: { active: true, role: 'admin' }
+     * });
+     *
+     * // Load products in a specific price range
+     * const affordableProducts = await productLoader.withOptions.load({
+     *   id: 'affordable-products',
+     *   searchKey: 'price',
+     *   criteria: { price: { $lt: 100 } }
+     * });
+     */
+    withOptions: DataLoader<DataLoaderOptions<SchemaType>, AsDomainType<SchemaType>[]>;
+}

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
+     * SchemaType & { id: string } represents the schema with virtual id field included
+     */
+    model: Model<SchemaType & { id: string }>;
+
+    /**
+     * 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>;
+}