@eeplatform/core 1.8.3 → 1.8.6

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @eeplatform/core
 
+## 1.8.6
+
+### Patch Changes
+
+- 26b7703: Increase max limit and remove aggregation sort
+
+## 1.8.5
+
+### Patch Changes
+
+- 7145ec1: Fix query
+
+## 1.8.4
+
+### Patch Changes
+
+- dd69528: Update PSGC query
+
 ## 1.8.3
 
 ### Patch Changes

package/CONVENTION.md

@@ -0,0 +1,632 @@
+# EEPlatform Coding Convention
+
+## Table of Contents
+
+- [Project Architecture Overview](#project-architecture-overview)
+- [Layer Responsibilities](#layer-responsibilities)
+- [File Structure & Naming Conventions](#file-structure--naming-conventions)
+- [Models Layer](#models-layer)
+- [Repository Layer](#repository-layer)
+- [Service Layer](#service-layer)
+- [Controller Layer](#controller-layer)
+- [Routes Layer](#routes-layer)
+- [Type Definitions](#type-definitions)
+- [Error Handling](#error-handling)
+- [Documentation](#documentation)
+
+## Project Architecture Overview
+
+Our project follows a layered architecture with clear separation of concerns:
+
+```
+Routes → Controllers → Services → Repositories → Database
+   ↓         ↓           ↓           ↓
+Models ← Models    ← Models    ← Models
+```
+
+Each layer has specific responsibilities and should only communicate with adjacent layers.
+
+## Layer Responsibilities
+
+### Models
+
+- Define data structures and types
+- Contain data validation schemas using Joi
+- Transform and validate incoming data
+- Handle ObjectId conversion and data cleaning
+
+### Repositories
+
+- Direct database interactions using MongoDB native driver
+- Implement caching strategies (Redis)
+- Handle cache invalidation on mutations
+- Set cache on read operations
+- Manage database sessions and transactions
+
+### Services
+
+- Business logic implementation
+- Third-party service integrations
+- Coordinate multiple repositories
+- Handle complex operations requiring transactions
+- Transform data between layers
+
+### Controllers
+
+- Handle HTTP request/response lifecycle
+- Input validation using Joi schemas
+- Choose between repository or service calls based on complexity
+- Direct repository calls for simple CRUD operations
+- Service calls for complex business logic
+
+### Routes
+
+- Define API endpoints and HTTP methods
+- Apply middleware (authentication, rate limiting, etc.)
+- Map endpoints to appropriate controller methods
+- Handle route-specific security requirements
+
+## File Structure & Naming Conventions
+
+### Directory Structure
+
+```
+src/
+├── resources/
+│   ├── [resource-name]/
+│   │   ├── [resource-name].model.ts
+│   │   ├── [resource-name].repository.ts
+│   │   ├── [resource-name].service.ts
+│   │   ├── [resource-name].controller.ts
+│   │   └── index.ts
+├── routes/
+│   ├── [resource-name].route.ts
+│   └── index.ts
+└── config.ts
+```
+
+### Naming Conventions
+
+- **Files**: Use kebab-case (e.g., `user-profile.model.ts`)
+- **Types**: Use PascalCase with 'T' prefix (e.g., `TUser`, `TSchool`)
+- **Schemas**: Use camelCase with 'schema' prefix (e.g., `schemaUser`, `schemaSchoolUpdate`)
+- **Functions**: Use camelCase (e.g., `createUser`, `getUserById`)
+- **Exported Functions**: Use 'use' prefix for composition functions (e.g., `useUserRepo`, `useUserService`)
+
+## Models Layer
+
+### Responsibilities
+
+- Define TypeScript types/interfaces
+- Create Joi validation schemas
+- Implement model transformation functions
+- Handle ObjectId conversions
+
+### Example Structure
+
+```typescript
+import { BadRequestError } from "@eeplatform/nodejs-utils";
+import Joi from "joi";
+import { ObjectId } from "mongodb";
+
+// Type Definition
+export type TUser = {
+  _id?: ObjectId;
+  email: string;
+  firstName: string;
+  lastName: string;
+  status?: string;
+  createdAt?: Date | string;
+  updatedAt?: Date | string;
+  deletedAt?: Date | string;
+};
+
+// Joi Schema
+export const schemaUser = Joi.object({
+  _id: Joi.string().hex().optional().allow("", null),
+  email: Joi.string().email().required(),
+  firstName: Joi.string().required(),
+  lastName: Joi.string().required(),
+  status: Joi.string().optional().allow("", null),
+  createdAt: Joi.date().optional().allow("", null),
+  updatedAt: Joi.date().optional().allow("", null),
+  deletedAt: Joi.date().optional().allow("", null),
+});
+
+// Model Function
+export function MUser(value: TUser): TUser {
+  const { error } = schemaUser.validate(value);
+  if (error) {
+    throw new BadRequestError(error.message);
+  }
+
+  // Handle ObjectId conversion
+  if (value._id && typeof value._id === "string") {
+    try {
+      value._id = new ObjectId(value._id);
+    } catch (error) {
+      throw new BadRequestError("Invalid ID.");
+    }
+  }
+
+  return {
+    _id: value._id ?? new ObjectId(),
+    email: value.email,
+    firstName: value.firstName,
+    lastName: value.lastName,
+    status: value.status ?? "active",
+    createdAt: value.createdAt ? new Date(value.createdAt) : new Date(),
+    updatedAt: value.updatedAt ? new Date(value.updatedAt) : new Date(),
+    deletedAt: value.deletedAt ? new Date(value.deletedAt) : null,
+  };
+}
+```
+
+### Validation Guidelines
+
+- Use `.required()` for mandatory fields
+- Use `.optional().allow("", null)` for optional fields
+- Use `.hex()` for MongoDB ObjectId validation
+- Use `.email()` for email validation
+- Use `.isoDate()` for date string validation
+
+## Repository Layer
+
+### Responsibilities
+
+- Database CRUD operations
+- Caching implementation
+- Cache invalidation strategies
+- Database indexing
+- Query optimization
+
+### Example Structure
+
+```typescript
+import {
+  useAtlas,
+  useCache,
+  makeCacheKey,
+  logger,
+} from "@eeplatform/nodejs-utils";
+import { ObjectId, ClientSession } from "mongodb";
+import { TUser, MUser } from "./user.model";
+
+export function useUserRepo() {
+  const db = useAtlas.getDb();
+  if (!db) {
+    throw new Error("Unable to connect to server.");
+  }
+
+  const namespace_collection = "users";
+  const collection = db.collection(namespace_collection);
+  const { getCache, setCache, delNamespace } = useCache(namespace_collection);
+
+  // Cache management
+  function delCachedData() {
+    delNamespace()
+      .then(() => {
+        logger.log({
+          level: "info",
+          message: `Cache namespace cleared for ${namespace_collection}`,
+        });
+      })
+      .catch((err) => {
+        logger.log({
+          level: "error",
+          message: `Failed to clear cache namespace: ${err.message}`,
+        });
+      });
+  }
+
+  // Create operation
+  async function add(value: TUser, session?: ClientSession) {
+    const user = MUser(value);
+    const result = await collection.insertOne(user, { session });
+    delCachedData(); // Invalidate cache on mutations
+    return result.insertedId;
+  }
+
+  // Read operation with caching
+  async function getById(_id: string | ObjectId) {
+    try {
+      _id = new ObjectId(_id);
+    } catch (error) {
+      throw new BadRequestError("Invalid ID.");
+    }
+
+    const cacheKey = makeCacheKey(namespace_collection, {
+      _id: _id.toString(),
+    });
+
+    // Check cache first
+    const cachedData = await getCache<TUser>(cacheKey);
+    if (cachedData) {
+      logger.log({
+        level: "info",
+        message: `Cache hit for user by ID: ${cacheKey}`,
+      });
+      return cachedData;
+    }
+
+    // Fetch from database
+    const data = await collection.findOne<TUser>({ _id });
+
+    // Set cache for future requests
+    if (data) {
+      setCache(cacheKey, data, 600) // 10 minutes TTL
+        .then(() => {
+          logger.log({
+            level: "info",
+            message: `Cache set for user by ID: ${cacheKey}`,
+          });
+        })
+        .catch((err) => {
+          logger.log({
+            level: "error",
+            message: `Failed to set cache: ${err.message}`,
+          });
+        });
+    }
+
+    return data;
+  }
+
+  return {
+    add,
+    getById,
+    delCachedData,
+  };
+}
+```
+
+### Caching Guidelines
+
+- **Cache Keys**: Use `makeCacheKey(namespace, options)` for consistent key generation
+- **Cache TTL**: Use appropriate TTL values (300s for user data, 600s for less frequently changing data)
+- **Cache Invalidation**: Clear cache on all mutation operations (create, update, delete)
+- **Cache Logging**: Log cache hits/misses and errors for monitoring
+- **Error Handling**: Cache failures should not break functionality
+
+## Service Layer
+
+### Responsibilities
+
+- Business logic implementation
+- Third-party integrations
+- Multi-repository coordination
+- Transaction management
+- Complex data transformations
+
+### Example Structure
+
+```typescript
+import { BadRequestError, useAtlas } from "@eeplatform/nodejs-utils";
+import { useUserRepo } from "./user.repository";
+import { useRoleRepo } from "../role/role.repository";
+import { TUser } from "./user.model";
+
+export function useUserService() {
+  const { add: addUser, getById: getUserById } = useUserRepo();
+  const { add: addRole } = useRoleRepo();
+
+  async function createUserWithRole(userData: TUser, roleData: any) {
+    const session = useAtlas.getClient()?.startSession();
+    if (!session) {
+      throw new BadRequestError("Unable to start database session.");
+    }
+
+    session.startTransaction();
+
+    try {
+      // Business logic: Create user first
+      const userId = await addUser(userData, session);
+
+      // Business logic: Assign default role
+      roleData.user = userId;
+      await addRole(roleData, session);
+
+      await session.commitTransaction();
+      return "User created successfully with role assigned.";
+    } catch (error) {
+      await session.abortTransaction();
+      throw new BadRequestError("Failed to create user with role.");
+    } finally {
+      session.endSession();
+    }
+  }
+
+  return {
+    createUserWithRole,
+  };
+}
+```
+
+### Service Guidelines
+
+- **Use transactions** for operations involving multiple repositories
+- **Coordinate business logic** across different domains
+- **Handle third-party integrations** (APIs, file uploads, external services)
+- **Transform data** between different formats/schemas
+- **Implement retry logic** for external service calls
+
+## Controller Layer
+
+### Responsibilities
+
+- Handle HTTP request/response lifecycle
+- Input validation
+- Choose between repository or service calls
+- Error handling and response formatting
+
+### Example Structure
+
+```typescript
+import { Request, Response, NextFunction } from "express";
+import { BadRequestError } from "@eeplatform/nodejs-utils";
+import Joi from "joi";
+import { useUserRepo } from "./user.repository";
+import { useUserService } from "./user.service";
+import { schemaUser } from "./user.model";
+
+export function useUserController() {
+  const { getById: _getById } = useUserRepo();
+  const { createUserWithRole } = useUserService();
+
+  // Simple operation - use repository directly
+  async function getById(req: Request, res: Response, next: NextFunction) {
+    const validation = Joi.object({
+      id: Joi.string().hex().required(),
+    });
+
+    const { error } = validation.validate(req.params);
+    if (error) {
+      next(new BadRequestError(`Validation error: ${error.message}`));
+      return;
+    }
+
+    try {
+      const user = await _getById(req.params.id);
+      res.json(user);
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  // Complex operation - use service
+  async function createWithRole(
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ) {
+    const { error } = schemaUser.validate(req.body);
+    if (error) {
+      next(new BadRequestError(`Validation error: ${error.message}`));
+      return;
+    }
+
+    try {
+      const result = await createUserWithRole(req.body.user, req.body.role);
+      res.status(201).json({ message: result });
+    } catch (error) {
+      next(error);
+    }
+  }
+
+  return {
+    getById,
+    createWithRole,
+  };
+}
+```
+
+### Controller Decision Matrix
+
+- **Use Repository** for:
+
+  - Simple CRUD operations
+  - Direct data retrieval
+  - Single-table operations
+  - Operations without business logic
+
+- **Use Service** for:
+  - Complex business logic
+  - Multi-repository operations
+  - Third-party integrations
+  - Transaction-based operations
+  - Data transformation requirements
+
+## Routes Layer
+
+### Responsibilities
+
+- Define API endpoints
+- Apply middleware
+- Map HTTP methods to controllers
+- Handle route-specific security
+
+### Example Structure
+
+```typescript
+import express from "express";
+import { requireAuth } from "@eeplatform/nodejs-utils";
+import { useUserController } from "./user.controller";
+
+const router = express.Router();
+
+const { getById, createWithRole, updateById, deleteById } = useUserController();
+
+// Public routes
+router.post("/register", createWithRole);
+
+// Protected routes
+router.get("/:id", requireAuth, getById);
+router.put("/:id", requireAuth, updateById);
+router.delete("/:id", requireAuth, deleteById);
+
+export default router;
+```
+
+### Route Guidelines
+
+- **Group related endpoints** in the same route file
+- **Apply authentication middleware** to protected routes
+- **Use consistent HTTP methods** (GET, POST, PUT, PATCH, DELETE)
+- **Include route parameters** in URL paths (e.g., `/:id`)
+- **Apply rate limiting** for public endpoints
+- **Use specific middleware** for route-specific requirements
+
+### HTTP Method Conventions
+
+- **GET**: Retrieve data (no side effects)
+- **POST**: Create new resources
+- **PUT**: Replace entire resource
+- **PATCH**: Partial resource updates
+- **DELETE**: Remove resources
+
+## Type Definitions
+
+### Naming Conventions
+
+```typescript
+// Types with 'T' prefix
+export type TUser = {
+  /* ... */
+};
+export type TSchool = {
+  /* ... */
+};
+
+// Interfaces with 'I' prefix (rare usage)
+export interface IUserService {
+  /* ... */
+}
+
+// Enums with descriptive names
+export enum UserStatus {
+  ACTIVE = "active",
+  INACTIVE = "inactive",
+  SUSPENDED = "suspended",
+}
+```
+
+### Common Type Patterns
+
+```typescript
+// Base fields for all entities
+type BaseEntity = {
+  _id?: ObjectId;
+  status?: string;
+  createdAt?: Date | string;
+  updatedAt?: Date | string;
+  deletedAt?: Date | string;
+  createdBy?: string | ObjectId;
+  updatedBy?: string | ObjectId;
+  deletedBy?: string | ObjectId;
+};
+
+// Pagination parameters
+type PaginationParams = {
+  page?: number;
+  limit?: number;
+  search?: string;
+  sort?: Record<string, number>;
+  status?: string;
+};
+```
+
+## Error Handling
+
+### Error Types
+
+```typescript
+import {
+  BadRequestError,
+  NotFoundError,
+  InternalServerError,
+  UnauthorizedError,
+  ForbiddenError,
+} from "@eeplatform/nodejs-utils";
+
+// Usage examples
+throw new BadRequestError("Invalid input data");
+throw new NotFoundError("User not found");
+throw new UnauthorizedError("Access token required");
+throw new ForbiddenError("Insufficient permissions");
+throw new InternalServerError("Database connection failed");
+```
+
+### Error Handling Patterns
+
+```typescript
+// In Controllers
+try {
+  const result = await someOperation();
+  res.json(result);
+} catch (error) {
+  next(error); // Pass to error middleware
+}
+
+// In Services/Repositories
+if (!data) {
+  throw new NotFoundError("Resource not found");
+}
+
+if (validationError) {
+  throw new BadRequestError(`Validation failed: ${validationError.message}`);
+}
+```
+
+## Documentation
+
+### Code Documentation
+
+```typescript
+/**
+ * Creates a new user with assigned role
+ * @param userData - User information and credentials
+ * @param roleData - Role assignment details
+ * @returns Success message
+ * @throws BadRequestError when validation fails
+ * @throws InternalServerError when database operation fails
+ */
+async function createUserWithRole(
+  userData: TUser,
+  roleData: any
+): Promise<string> {
+  // Implementation
+}
+```
+
+### API Documentation
+
+- Use OpenAPI/Swagger specifications
+- Document request/response schemas
+- Include example payloads
+- Document error responses
+- Provide authentication requirements
+
+### README Requirements
+
+Each module should include:
+
+- Purpose and functionality
+- Installation instructions
+- Configuration options
+- Usage examples
+- API endpoint documentation
+- Contributing guidelines
+
+## Best Practices Summary
+
+1. **Separation of Concerns**: Each layer has distinct responsibilities
+2. **Caching Strategy**: Cache reads, invalidate on writes
+3. **Error Handling**: Use appropriate error types and propagate properly
+4. **Validation**: Validate at model level and controller level
+5. **Transactions**: Use for operations affecting multiple collections
+6. **Logging**: Log cache operations, errors, and important events
+7. **Type Safety**: Use TypeScript strictly, define all types
+8. **Documentation**: Clear, maintained documentation for all APIs
+9. **Security**: Apply authentication and authorization consistently
+
+This convention ensures maintainable, scalable, and consistent code across the entire EEPlatform ecosystem.