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

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, CreateInterface = CreateType<SchemaType>, UpdateInterface = UpdateType<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(data: CreateInterface): 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(data: CreateInterface[]): 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(id: string, data: Partial<UpdateInterface>, 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(
+        data: (CreateInterface | UpdateInterface) & { 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>;
+}

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

@@ -0,0 +1,477 @@
+/* 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;
+        };
+    };
+
+    /**
+     * Get multiple documents by their IDs
+     *
+     * This action retrieves multiple entities by their unique identifiers.
+     * It maps to the IBaseService.getByIds method and handles parameter validation.
+     * Useful for retrieving a specific set of entities in a single operation.
+     */
+    [BaseServiceCommands.GetByIds]: {
+        params: {
+            ids: { 
+                type: 'array', 
+                items: 'string',
+                optional: false
+            };
+        };
+    };
+
+    /**
+     * 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> };
+}