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

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

@@ -0,0 +1,140 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * @file CommonTypes.ts
+ * @description Defines common types and interfaces used across the data access layer for database operations.
+ * These types are database-agnostic and can be used with any database implementation (MongoDB, PostgreSQL, etc.).
+ *
+ * Key components include:
+ * - GetAllArgs: Interface for pagination, sorting, and filtering when retrieving collections of documents
+ * - AsDomainType: Type transformer that converts database schema types to domain types
+ * - GetAllWithCountResult: Type for paginated results that include both data and total count
+ * - CreateType/UpdateType: Utility types that define the shape of data for create and update operations
+ * - FilterCriteria: Generic type for filtering data across different database implementations
+ * - ISort: Interface for defining sort operations
+ *
+ * These types ensure consistency across repositories and services, providing type safety and
+ * clear contracts for data manipulation throughout the application. They form the foundation
+ * of the data access pattern used across the entire system.
+ *
+ * @see IBaseService - Service layer that uses these types
+ * @see IBaseMongoRepository - MongoDB repository implementation using these types
+ */
+import { ISort } from 'common';
+import type { ObjectId } from 'mongodb';
+/**
+ * Generic filter type that doesn't depend on specific database implementation
+ * Can be used for any database query operations
+ */
+export type FilterCriteria<T> = Partial<T> | Record<string, any>;
+
+/**
+ * Interface for defining sort operations
+ * Keys are field names, values are sort direction (1 for ascending, -1 for descending)
+ *
+ * @example
+ * // Sort by creation date descending, then by name ascending
+ * const sort: ISort = { createdAt: -1, name: 1 };
+ */
+/**
+ * Interface for the arguments used in getAll methods
+ *
+ * @property criteria - Filter criteria to narrow down results
+ * @property sort - Sorting configuration with field names and directions
+ * @property skip - Number of documents to skip (for pagination)
+ * @property limit - Maximum number of documents to return (for pagination)
+ * @property selectedFields - String of space-separated field names to include in the results
+ *
+ * @example
+ * // Get active users, sorted by creation date, second page with 10 items per page
+ * const options: GetAllArgs<UserSchema> = {
+ *   criteria: { active: true },
+ *   sort: { createdAt: -1 },
+ *   skip: 10,
+ *   limit: 10,
+ *   selectedFields: 'name email createdAt'
+ * };
+ */
+export interface GetAllArgs<T> {
+    criteria?: FilterCriteria<T>;
+    sort?: ISort;
+    skip?: number;
+    limit?: number;
+    selectedFields?: string;
+}
+
+/**
+ * Type transformer that converts database schema types to domain types
+ * For MongoDB, this typically means converting _id to id
+ *
+ * @example
+ * // MongoDB document
+ * type UserSchema = {
+ *   _id: ObjectId;
+ *   name: string;
+ *   email: string;
+ * };
+ *
+ * // Transformed domain object
+ * type UserDomain = AsDomainType<UserSchema>;
+ * // Equivalent to:
+ * // {
+ * //   id: string;
+ * //   name: string;
+ * //   email: string;
+ * // }
+ */
+export type AsDomainType<SchemaType> = Omit<SchemaType, '_id'> & { _id?: ObjectId } & { id: string };
+
+/**
+ * Type for paginated results that include both data and total count
+ * Used for implementing pagination UI components
+ *
+ * @property data - Array of domain objects matching the query criteria
+ * @property totalCount - Total number of documents that match the criteria (without pagination)
+ *
+ * @example
+ * const result: GetAllWithCountResult<UserSchema> = {
+ *   data: [{ id: '1', name: 'John' }, { id: '2', name: 'Jane' }],
+ *   totalCount: 50
+ * };
+ */
+export type GetAllWithCountResult<SchemaType> = {
+    data: AsDomainType<SchemaType>[];
+    totalCount: number;
+};
+
+/**
+ * Default pagination settings used throughout the application
+ * These values are used when no explicit pagination parameters are provided
+ */
+export enum PAGINATION_OPTIONS {
+    limit = 10,
+    skip = 0,
+}
+
+/**
+ * Type for create operations - omits system-generated fields
+ * This ensures that clients cannot specify fields that should be generated by the database
+ *
+ * @example
+ * // Valid create operation data
+ * const newUser: CreateType<UserSchema> = {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   role: 'user'
+ * };
+ */
+export type CreateType<SchemaType> = Omit<Partial<SchemaType>, '_id' | 'id' | 'createdAt' | 'updatedAt'>;
+
+/**
+ * Type for update operations - partial of the schema without system fields
+ * This allows for partial updates where only changed fields are specified
+ *
+ * @example
+ * // Update a user's email and role
+ * const updateData: UpdateType<UserSchema> = {
+ *   email: 'new.email@example.com',
+ *   role: 'admin'
+ * };
+ */
+export type UpdateType<SchemaType> = Partial<Omit<SchemaType, '_id'>>;

package/lib/templates/repositories/moleculerEventHandler.ts.template.toberemoved

@@ -0,0 +1,118 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+/**
+ * @file moleculer-event-handler.ts
+ * @description Decorator for marking service methods as Moleculer event handlers
+ * 
+ * This allows event handlers to be defined directly in the service class
+ * and automatically registered as Moleculer events.
+ */
+
+import 'reflect-metadata';
+
+/**
+ * Moleculer namespace containing event handler utilities
+ */
+export namespace Moleculer {
+    /**
+     * Metadata key for storing event handler information
+     */
+    export const EVENT_HANDLER_METADATA_KEY = 'moleculer:eventHandler';
+
+    /**
+     * Event handler metadata interface
+     */
+    export interface EventHandlerMetadata {
+        eventName: string;
+        methodName: string;
+        group?: string;
+    }
+
+    /**
+     * Decorator for marking a service method as a Moleculer event handler
+     * 
+     * @param eventName - The event name to listen for
+     * @param options - Optional event configuration
+     * 
+     * @example
+     * ```typescript
+     * class OrganizationService implements IOrganizationService {
+     *     @Moleculer.EventHandler(UserBroadcasterAction.OnUserCreated)
+     *     async onUserCreated(event: IUserCreationEvent): Promise<void> {
+     *         await this.createDefaultOrganization(event.user);
+     *     }
+     * 
+     *     @Moleculer.EventHandler(OrganizationServiceAction.OnOrganizationCreated, { group: 'org-setup' })
+     *     async onOrganizationCreated(event: IOrganizationCreatedEvent): Promise<void> {
+     *         // Handle organization creation
+     *     }
+     * }
+     * ```
+     */
+    export function EventHandler(
+        eventName: string,
+        options?: { group?: string }
+    ): MethodDecorator {
+        return function moleculerEventHandlerDecorator(
+            target: object,
+            propertyKey: string | symbol,
+            descriptor: PropertyDescriptor
+        ): PropertyDescriptor {
+            // Get existing event handlers for this class
+            const existingHandlers: EventHandlerMetadata[] = 
+                Reflect.getMetadata(EVENT_HANDLER_METADATA_KEY, target.constructor) || [];
+            
+            // Add this handler to the list
+            const metadata: EventHandlerMetadata = {
+                eventName,
+                methodName: propertyKey.toString(),
+                group: options?.group,
+            };
+            
+            existingHandlers.push(metadata);
+            
+            // Store the updated list
+            Reflect.defineMetadata(EVENT_HANDLER_METADATA_KEY, existingHandlers, target.constructor);
+            
+            return descriptor;
+        };
+    }
+
+    /**
+     * Get all Moleculer event handlers defined on a service class
+     * 
+     * @param serviceClassOrInstance - The service class constructor or instance
+     * @returns Array of event handler metadata
+     * 
+     * @example
+     * ```typescript
+     * const handlers = Moleculer.getEventHandlers(OrganizationService);
+     * // Returns: [
+     * //   { eventName: 'user.created', methodName: 'onUserCreated' },
+     * //   { eventName: 'org.created', methodName: 'onOrganizationCreated' }
+     * // ]
+     * ```
+     */
+    export function getEventHandlers(
+        serviceClassOrInstance: (new (...args: unknown[]) => unknown) | object
+    ): EventHandlerMetadata[] {
+        const target = typeof serviceClassOrInstance === 'function' 
+            ? serviceClassOrInstance 
+            : (serviceClassOrInstance as { constructor: new (...args: unknown[]) => unknown }).constructor;
+        return Reflect.getMetadata(EVENT_HANDLER_METADATA_KEY, target) || [];
+    }
+
+    /**
+     * Check if a method is marked as a Moleculer event handler
+     * 
+     * @param serviceClassOrInstance - The service class constructor or instance
+     * @param methodName - The method name to check
+     * @returns Event handler metadata if found, undefined otherwise
+     */
+    export function isEventHandler(
+        serviceClassOrInstance: (new (...args: unknown[]) => unknown) | object,
+        methodName: string
+    ): EventHandlerMetadata | undefined {
+        const handlers = getEventHandlers(serviceClassOrInstance);
+        return handlers.find(h => h.methodName === methodName);
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { Document } from 'mongoose';
+
+/**
+ * Helper type to convert a Mongoose document to a plain object
+ * Useful when working with Mongoose documents that need to be converted to domain objects
+ */
+export type AsObject<T> = T extends Document ? Omit<T, keyof Document> : T;
+
+export interface IMongoOptions {
+    collectionName?: string;
+    sessionCollectionName?: string;
+    timestamps?: {
+        createdAt: string;
+        updatedAt: string;
+    };
+    convertUserIdToMongoObjectId?: boolean;
+    convertSessionIdToMongoObjectId?: boolean;
+    caseSensitiveUserName?: boolean;
+    idProvider?: () => string | Object;
+    dateProvider?: (date?: Date) => any;
+}