@common-stack/store-mongo 7.0.4-alpha.6 → 7.1.1-alpha.11

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

@@ -0,0 +1,461 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file IBaseServiceMixin.ts
+ * @description Defines the interface and types for the BaseServiceMixin functionality.
+ * This file documents the contract and behavior of the BaseServiceMixin without implementation details.
+ *
+ * The BaseServiceMixin provides a way to add standardized service methods to Moleculer service schemas.
+ * It implements the IBaseService interface and connects it to Moleculer's service framework,
+ * creating action handlers for all standard service operations.
+ *
+ * Architecture Context:
+ * - Part of the service layer in a microservices architecture
+ * - Bridges domain services with the Moleculer microservice framework
+ * - Follows a consistent pattern for exposing domain operations as microservice actions
+ * - Implements an event-driven architecture by emitting events on data changes
+ * - Provides automatic parameter validation through Moleculer's built-in validator
+ *
+ * Key features:
+ * - Automatic action creation for all IBaseService methods
+ * - Event emission for data changes (create, update, delete)
+ * - Parameter validation for all actions
+ * - Consistent error handling
+ * - Type safety through generics
+ *
+ * Usage Patterns:
+ * - Include this mixin in any Moleculer service that needs standard CRUD operations
+ * - Customize event emission by providing a custom events array
+ * - Extend with additional service-specific actions
+ * - Use with any implementation of IBaseService (typically a concrete service class)
+ *
+ * @see IBaseService - The interface this mixin implements
+ * @see IBaseMongoRepository - The repository interface used for data access
+ * @see BaseServiceCommands - Enum of standard service commands used as action names
+ */
+
+import type { ServiceBroker, ServiceSchema } from 'moleculer';
+import { BaseServiceCommands } from 'common';
+import { IBaseService } from './IBaseService';
+import { CreateType, UpdateType } from './dbCommonTypes';
+
+
+/**
+ * Interface for the BaseServiceMixin function
+ * This function creates a Moleculer service mixin that implements the IBaseService interface
+ *
+ * @param service - Implementation of IBaseService that will handle the actual business logic
+ * @param broker - Moleculer service broker for event emission
+ * @param name - Service name used for event naming
+ * @param events - List of operations that should emit events
+ * @returns A partial ServiceSchema that can be merged with other service definitions
+ *
+ * @example
+ * // Create a user service with the base service mixin
+ * const UserService: ServiceSchema = {
+ *   name: "users",
+ *   mixins: [
+ *     BaseServiceMixin(userService, broker, "users")
+ *   ],
+ *   // Additional service-specific actions and methods
+ *   actions: {
+ *     changePassword: { ... }
+ *   }
+ * };
+ *
+ * // Example of customizing event emission
+ * const ProductService: ServiceSchema = {
+ *   name: "products",
+ *   mixins: [
+ *     // Only emit events for create and update operations
+ *     BaseServiceMixin(
+ *       productService,
+ *       broker,
+ *       "products",
+ *       [BaseServiceCommands.Create, BaseServiceCommands.Update]
+ *     )
+ *   ]
+ * };
+ */
+export interface IBaseServiceMixinFunction {
+    <T, C = CreateType<T>, U = UpdateType<T>>(
+        service: IBaseService<T, C, U>,
+        broker?: ServiceBroker,
+        name?: string,
+        events?: BaseServiceCommands[],
+    ): Partial<ServiceSchema>;
+}
+
+/**
+ * Interface describing the actions created by the BaseServiceMixin
+ * Each action corresponds to a method in the IBaseService interface
+ */
+export interface IBaseServiceMixinActions {
+    /**
+     * Get a single document by ID
+     *
+     * This action retrieves a single entity by its unique identifier.
+     * It maps to the IBaseService.get method and handles parameter validation.
+     *
+     * @param id - The unique identifier of the document to retrieve
+     * @returns The domain entity or null if not found
+     *
+     * @example
+     * // Call from another service
+     * const user = await broker.call('users.get', { id: '123' });
+     *
+     * // Call from API
+     * app.get('/api/users/:id', async (req, res) => {
+     *   const user = await broker.call('users.get', { id: req.params.id });
+     *   res.json(user);
+     * });
+     */
+    [BaseServiceCommands.Get]: {
+        params: {
+            id: string;
+        };
+    };
+
+    /**
+     * Count documents matching criteria
+     *
+     * This action counts entities matching the provided filter criteria.
+     * It maps to the IBaseService.count method and handles parameter validation.
+     *
+     * @param criteria - Optional filter criteria to count specific documents
+     * @returns The count of matching documents
+     *
+     * @example
+     * // Count active users
+     * const count = await broker.call('users.count', {
+     *   criteria: { active: true }
+     * });
+     */
+    [BaseServiceCommands.Count]: {
+        params: {
+            criteria?: Record<string, any>;
+        };
+    };
+
+    /**
+     * Create multiple documents
+     *
+     * This action creates multiple entities in a single operation.
+     * It maps to the IBaseService.bulkCreate method and handles parameter validation.
+     * It also emits events for the created entities if configured.
+     *
+     * @param data - Array of data objects for the new documents
+     * @returns Array of created domain entities
+     *
+     * @example
+     * // Create multiple users
+     * const users = await broker.call('users.bulkCreate', {
+     *   data: [
+     *     { name: 'John', email: 'john@example.com' },
+     *     { name: 'Jane', email: 'jane@example.com' }
+     *   ]
+     * });
+     */
+    [BaseServiceCommands.BulkCreate]: {
+        params: {
+            data: any[];
+        };
+    };
+
+    /**
+     * Create a single document
+     *
+     * This action creates a single entity.
+     * It maps to the IBaseService.create method and handles parameter validation.
+     * It also emits an event for the created entity if configured.
+     *
+     * @param data - Data object for the new document
+     * @returns The created domain entity
+     *
+     * @example
+     * // Create a new user
+     * const user = await broker.call('users.create', {
+     *   data: { name: 'John', email: 'john@example.com' }
+     * });
+     */
+    [BaseServiceCommands.Create]: {
+        params: {
+            data: any;
+        };
+    };
+
+    /**
+     * Delete a document by ID
+     *
+     * This action deletes a single entity by its unique identifier.
+     * It maps to the IBaseService.delete method and handles parameter validation.
+     * It also emits an event for the deleted entity if configured.
+     *
+     * @param id - The unique identifier of the document to delete
+     * @returns Boolean indicating success
+     *
+     * @example
+     * // Delete a user
+     * const success = await broker.call('users.delete', { id: '123' });
+     */
+    [BaseServiceCommands.Delete]: {
+        params: {
+            id: string;
+        };
+    };
+
+    /**
+     * Get documents with pagination
+     *
+     * This action retrieves multiple entities with filtering, sorting, and pagination.
+     * It maps to the IBaseService.getAll method and handles parameter validation.
+     *
+     * @param criteria - Optional filter criteria
+     * @param sort - Optional sorting configuration
+     * @param skip - Optional number of documents to skip (for pagination)
+     * @param limit - Optional maximum number of documents to return
+     * @param selectedFields - Optional space-separated list of fields to include
+     * @returns Array of domain entities
+     *
+     * @example
+     * // Get active users sorted by creation date
+     * const users = await broker.call('users.getAll', {
+     *   criteria: { active: true },
+     *   sort: { createdAt: -1 },
+     *   skip: 0,
+     *   limit: 10
+     * });
+     */
+    [BaseServiceCommands.GetAll]: {
+        params: {
+            criteria?: Record<string, any>;
+            sort?: Record<string, 1 | -1>;
+            skip?: number;
+            limit?: number;
+            selectedFields?: string;
+        };
+    };
+
+    /**
+     * Get documents with pagination and total count
+     *
+     * This action retrieves multiple entities with filtering, sorting, pagination,
+     * and includes the total count of matching documents (useful for UI pagination).
+     * It maps to the IBaseService.getAllWithCount method and handles parameter validation.
+     *
+     * @param criteria - Optional filter criteria
+     * @param sort - Optional sorting configuration
+     * @param skip - Optional number of documents to skip (for pagination)
+     * @param limit - Optional maximum number of documents to return
+     * @param selectedFields - Optional space-separated list of fields to include
+     * @returns Object with data array and total count
+     *
+     * @example
+     * // Get paginated users with total count for UI pagination
+     * const { data, totalCount } = await broker.call('users.getAllWithCount', {
+     *   criteria: { role: 'user' },
+     *   skip: 20,
+     *   limit: 10,
+     *   sort: { createdAt: -1 }
+     * });
+     */
+    [BaseServiceCommands.GetAllWithCount]: {
+        params: {
+            criteria?: Record<string, any>;
+            sort?: Record<string, 1 | -1>;
+            skip?: number;
+            limit?: number;
+            selectedFields?: string;
+        };
+    };
+
+    /**
+     * Create or update a document
+     *
+     * This action creates a new entity or updates an existing one if an ID is provided.
+     * It maps to the IBaseService.insert method and handles parameter validation.
+     * It also emits an event for the created or updated entity if configured.
+     *
+     * @param data - Data object for the new or updated document
+     * @param overwrite - Optional flag to completely replace the document instead of merging
+     * @returns The created or updated domain entity
+     *
+     * @example
+     * // Create a new product
+     * const newProduct = await broker.call('products.insert', {
+     *   data: { name: 'New Product', price: 99.99 }
+     * });
+     *
+     * // Update an existing product
+     * const updatedProduct = await broker.call('products.insert', {
+     *   data: { id: 'product123', name: 'Updated Product', price: 129.99 }
+     * });
+     */
+    [BaseServiceCommands.Insert]: {
+        params: {
+            data: any & { id?: string };
+            overwrite?: boolean;
+        };
+    };
+
+    /**
+     * Update a document by ID
+     *
+     * This action updates an existing entity by its unique identifier.
+     * It maps to the IBaseService.update method and handles parameter validation.
+     * It also emits an event for the updated entity if configured.
+     *
+     * @param id - The unique identifier of the document to update
+     * @param data - Data object with fields to update
+     * @param overwrite - Optional flag to completely replace the document instead of merging
+     * @returns The updated domain entity
+     *
+     * @example
+     * // Update a user's role
+     * const updatedUser = await broker.call('users.update', {
+     *   id: 'user123',
+     *   data: { role: 'admin', active: true }
+     * });
+     *
+     * // Replace a user document entirely
+     * const replacedUser = await broker.call('users.update', {
+     *   id: 'user123',
+     *   data: { name: 'New Name', email: 'new@example.com', role: 'user' },
+     *   overwrite: true
+     * });
+     */
+    [BaseServiceCommands.Update]: {
+        params: {
+            id: string;
+            data: any;
+            overwrite?: boolean;
+        };
+    };
+
+    /**
+     * Delete multiple documents matching criteria
+     *
+     * This action deletes multiple entities matching the provided filter criteria.
+     * It maps to the IBaseService.delete method and handles parameter validation.
+     * It also emits an event with the deletion criteria if configured.
+     *
+     * @param criteria - Filter criteria to find documents to delete
+     * @returns Number of deleted documents
+     *
+     * @example
+     * // Delete all inactive users
+     * const deletedCount = await broker.call('users.deleteMany', {
+     *   criteria: { active: false }
+     * });
+     *
+     * // Delete users with a specific role
+     * const deletedCount = await broker.call('users.deleteMany', {
+     *   criteria: { role: 'guest' }
+     * });
+     */
+    [BaseServiceCommands.DeleteMany]: {
+        params: {
+            criteria: Record<string, any>;
+        };
+    };
+}
+
+/**
+ * Interface describing the events emitted by the BaseServiceMixin
+ * Events follow a consistent naming pattern: `${serviceName}.on${CommandName}`
+ */
+export interface IBaseServiceMixinEvents {
+    /**
+     * Event emitted when a document is created
+     * Event name format: `${serviceName}.onCreate`
+     * Payload: The created domain entity
+     *
+     * @example
+     * // Listen for user creation events
+     * broker.createService({
+     *   name: 'notification',
+     *   events: {
+     *     'users.onCreate': function(payload) {
+     *       // Send welcome email to new user
+     *       this.sendWelcomeEmail(payload.email);
+     *     }
+     *   }
+     * });
+     */
+    onCreate: any;
+
+    /**
+     * Event emitted when multiple documents are created
+     * Event name format: `${serviceName}.onBulkCreate`
+     * Payload: Array of created domain entities
+     *
+     * @example
+     * // Listen for bulk user creation events
+     * broker.createService({
+     *   name: 'notification',
+     *   events: {
+     *     'users.onBulkCreate': function(payload) {
+     *       // Send welcome emails to all new users
+     *       payload.forEach(user => this.sendWelcomeEmail(user.email));
+     *     }
+     *   }
+     * });
+     */
+    onBulkCreate: any[];
+
+    /**
+     * Event emitted when a document is updated
+     * Event name format: `${serviceName}.onUpdate`
+     * Payload: The updated domain entity
+     *
+     * @example
+     * // Listen for user update events
+     * broker.createService({
+     *   name: 'audit',
+     *   events: {
+     *     'users.onUpdate': function(payload) {
+     *       // Log user update for audit trail
+     *       this.logAuditEvent('user_updated', payload.id);
+     *     }
+     *   }
+     * });
+     */
+    onUpdate: any;
+
+    /**
+     * Event emitted when a document is deleted
+     * Event name format: `${serviceName}.onDelete`
+     * Payload: Object containing the ID of the deleted entity
+     *
+     * @example
+     * // Listen for user deletion events
+     * broker.createService({
+     *   name: 'cleanup',
+     *   events: {
+     *     'users.onDelete': function(payload) {
+     *       // Clean up related user data
+     *       this.cleanupUserData(payload.id);
+     *     }
+     *   }
+     * });
+     */
+    onDelete: { id: string };
+
+    /**
+     * Event emitted when multiple documents are deleted
+     * Event name format: `${serviceName}.onDeleteMany`
+     * Payload: The criteria used for deletion
+     *
+     * @example
+     * // Listen for bulk user deletion events
+     * broker.createService({
+     *   name: 'cleanup',
+     *   events: {
+     *     'users.onDeleteMany': function(payload) {
+     *       // Clean up related data for deleted users
+     *       this.cleanupBulkUserData(payload.criteria);
+     *     }
+     *   }
+     * });
+     */
+    onDeleteMany: { criteria: Record<string, any> };
+}

package/lib/templates/repositories/IDataloader.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>[]>;
+}