@venturialstd/user 0.0.1

package/README.md

@@ -0,0 +1,1357 @@
+# @venturialstd/user
+
+User Management Module for Venturial - A NestJS module for managing users with comprehensive profile management, settings, and role-based access control.
+
+**🎯 Key Design Principle:** This module provides a minimal, extensible base User entity. Extend it with related entities for your specific needs (employment data, contact info, etc.) for optimal performance.
+
+## 📋 Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Module Structure](#module-structure)
+- [Quick Start](#quick-start)
+- [ACL System](#acl-system)
+- [Extending User Statuses](#extending-user-statuses)
+- [Extending the Module](#extending-the-module)
+  - [Performance Considerations](#performance-considerations)
+  - [Recommended Approach: Related Entities](#recommended-approach-related-entities)
+  - [Hybrid Approach](#hybrid-approach-optional-flexibility)
+  - [Complete Extension Example](#complete-extension-example)
+  - [Extension Methods Comparison](#extension-methods-comparison)
+- [Configuration](#configuration)
+- [Entities](#entities)
+- [API Reference](#api-reference)
+- [Enums & Constants](#enums--constants)
+- [Guards & Decorators](#guards--decorators)
+- [Test Server](#test-server)
+- [NPM Scripts](#npm-scripts)
+- [Usage Examples](#usage-examples)
+- [Performance Best Practices](#performance-best-practices)
+- [Migration Guide](#migration-guide)
+
+---
+
+## ✨ Features
+
+- 👤 **User Management**: Complete CRUD operations for users
+- 📧 **Email Verification**: Email verification system
+- ⚙️ **User Settings**: Configurable user preferences
+- 🎭 **Extensible Statuses**: Define custom user statuses for your application
+- 🔐 **ACL System**: Complete database-driven role and permission management
+- 🛡️ **Guards & Decorators**: Request-level access control
+- 🔄 **TypeORM Integration**: Full database support with migrations
+- 📦 **Fully Typed**: Complete TypeScript support
+- 🧪 **Test Infrastructure**: Standalone test server on port 3003
+- ⚡ **High Performance**: Indexed columns and optimized queries
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @venturialstd/user
+```
+
+### Peer Dependencies
+
+```json
+{
+  "@nestjs/common": "^11.0.11",
+  "@nestjs/core": "^11.0.5",
+  "@nestjs/typeorm": "^10.0.0",
+  "@venturialstd/core": "^1.0.16",
+  "class-transformer": "^0.5.1",
+  "class-validator": "^0.14.1",
+  "typeorm": "^0.3.20"
+}
+```
+
+---
+
+## 📁 Module Structure
+
+```
+src/user/
+├── src/
+│   ├── constants/
+│   │   ├── user.constant.ts           # USER_STATUS enum
+│   │   └── user.settings.constant.ts   # Settings keys and config
+│   ├── decorators/
+│   │   ├── user.decorator.ts           # @CurrentUserId(), @CurrentUser()
+│   │   └── acl.decorator.ts            # @RequirePermissions(), @RequireAclRoles()
+│   ├── entities/
+│   │   ├── user.entity.ts              # User entity
+│   │   ├── role.entity.ts              # ACL Role entity
+│   │   ├── permission.entity.ts        # ACL Permission entity
+│   │   ├── role-permission.entity.ts   # ACL Role-Permission junction
+│   │   └── user-role.entity.ts         # ACL User-Role junction
+│   ├── guards/
+│   │   ├── user.guard.ts               # UserGuard
+│   │   └── acl.guard.ts                # PermissionGuard, AclRoleGuard
+│   ├── services/
+│   │   ├── user.service.ts             # UserService
+│   │   └── acl.service.ts              # AclService
+│   ├── settings/
+│   │   └── user.settings.ts            # UserSettings interface
+│   ├── index.ts                        # Public API exports
+│   └── user.module.ts                  # Main module
+├── test/
+│   ├── controllers/
+│   │   └── user-test.controller.ts     # Test controller
+│   ├── migrations/                     # Database migrations
+│   ├── .env.example                    # Environment template
+│   ├── data-source.ts                  # TypeORM data source
+│   ├── main.ts                         # Test server bootstrap
+│   └── test-app.module.ts              # Test module
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Import the Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { UserModule } from '@venturialstd/user';
+
+@Module({
+  imports: [
+    // Basic import (uses default statuses)
+    UserModule.forRoot(),
+    
+    // Or with custom statuses
+    UserModule.forRoot({
+      allowedStatuses: ['ACTIVE', 'INACTIVE', 'SUSPENDED', 'BANNED'],
+      additionalEntities: [UserEmployment, UserProfile],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Use in Your Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { UserService, AclService } from '@venturialstd/user';
+
+@Injectable()
+export class MyService {
+  constructor(
+    private readonly userService: UserService,
+    private readonly aclService: AclService,
+  ) {}
+
+  async getUser(userId: string) {
+    return this.userService.getUserById(userId);
+  }
+  
+  async assignModeratorRole(userId: string) {
+    const role = await this.aclService.getRoleByName('MODERATOR');
+    return this.aclService.assignRoleToUser(userId, role.id);
+  }
+}
+```
+
+### 3. Use Guards and Decorators
+
+```typescript
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { CurrentUserId, UserGuard, RequirePermissions, PermissionGuard } from '@venturialstd/user';
+
+@Controller('profile')
+@UseGuards(UserGuard)
+export class ProfileController {
+  @Get()
+  async getProfile(@CurrentUserId() userId: string) {
+    return { userId };
+  }
+  
+  @Get('admin')
+  @RequirePermissions('users.delete', 'content.manage')
+  @UseGuards(UserGuard, PermissionGuard)
+  async adminAction() {
+    return { message: 'Admin action' };
+  }
+}
+```
+
+---
+
+## 🔐 ACL System
+
+The module includes a complete database-driven Access Control List (ACL) system for managing roles and permissions. See [ACL_SYSTEM.md](./ACL_SYSTEM.md) for comprehensive documentation.
+
+### Quick Overview
+
+- **Roles**: Named collections of permissions (e.g., ADMIN, MODERATOR)
+- **Permissions**: Granular access rights in `resource.action` format (e.g., `users.delete`, `posts.create`)
+- **Multiple Roles**: Users can have multiple roles with different scopes
+- **Temporal Access**: Roles can expire automatically
+- **Conditional Permissions**: Optional conditions on role-permission assignments
+
+### Example Usage
+
+```typescript
+// Create roles and permissions
+const adminRole = await aclService.createRole('ADMIN', 'Administrator');
+const userPerm = await aclService.createPermission('users', 'delete', 'Delete users');
+
+// Assign permission to role
+await aclService.assignPermissionToRole(adminRole.id, userPerm.id);
+
+// Assign role to user
+await aclService.assignRoleToUser(userId, adminRole.id);
+
+// Check permissions
+const canDelete = await aclService.userHasPermission(userId, 'users.delete');
+```
+
+---
+
+## 🎭 Extending User Statuses
+
+The module provides a flexible system for defining custom user statuses.
+
+## 🎭 Extending User Statuses
+
+The module provides a flexible system for defining custom user statuses.
+
+### Default Values
+
+By default, the module includes:
+
+**Statuses:**
+- `ACTIVE` - User is active and can use the system
+- `INACTIVE` - User is inactive
+- `SUSPENDED` - User has been suspended
+- `PENDING_VERIFICATION` - User email needs verification
+
+### Defining Custom Statuses
+
+Create an enum for your application-specific statuses:
+
+```typescript
+// Define custom statuses
+export enum AppUserStatus {
+  ACTIVE = 'ACTIVE',
+  INACTIVE = 'INACTIVE',
+  SUSPENDED = 'SUSPENDED',
+  PENDING_VERIFICATION = 'PENDING_VERIFICATION',
+  ON_HOLD = 'ON_HOLD',
+  BANNED = 'BANNED',
+  DELETED = 'DELETED',
+}
+
+@Module({
+  imports: [
+    UserModule.forRoot({
+      allowedStatuses: Object.values(AppUserStatus),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Managing Statuses
+
+```typescript
+@Injectable()
+export class UserManagementService {
+  constructor(private userService: UserService) {}
+
+  // Set user status with validation
+  async banUser(userId: string) {
+    return this.userService.setStatus(userId, AppUserStatus.BANNED);
+  }
+
+  // Get users by status
+  async getBannedUsers() {
+    return this.userService.getUsersByStatus(AppUserStatus.BANNED);
+  }
+
+  // Get all allowed statuses for your application
+  getAllStatuses() {
+    return this.userService.getAllowedStatuses();
+  }
+}
+```
+
+### Validation
+
+The module automatically validates statuses:
+
+```typescript
+// ✅ Valid - status is in allowedStatuses
+await userService.setStatus(userId, AppUserStatus.BANNED);
+
+// ❌ Invalid - throws BadRequestException
+await userService.setStatus(userId, 'INVALID_STATUS');
+// Error: Invalid status "INVALID_STATUS". Allowed statuses: ACTIVE, INACTIVE, SUSPENDED, ...
+```
+
+---
+
+## 🔧 Extending the Module
+
+### Performance Considerations
+
+**⚠️ Important:** The `metadata` and `settings` JSONB fields are available but **NOT recommended for filterable attributes** due to poor query performance.
+
+**Performance Comparison:**
+```sql
+-- ❌ SLOW: JSONB query (full table scan)
+SELECT * FROM "user" WHERE metadata->>'department' = 'Engineering';
+-- 1M records: ~50 seconds
+
+-- ⚡ FAST: Indexed column query  
+SELECT * FROM user_employment WHERE department = 'Engineering';
+-- 1M records: ~10 milliseconds
+```
+
+**Result: 5,000x faster with proper indexes!**
+
+### Recommended Approach: Related Entities
+
+**Always use related entities for any data you need to query or filter.**
+
+#### Step 1: Create Your Extended Entity
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column, OneToOne, JoinColumn, Index } from 'typeorm';
+import { User } from '@venturialstd/user';
+
+@Entity('user_employment')
+@Index(['department', 'isActive']) // Composite index for common queries
+export class UserEmployment {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  @Index() // Fast lookups by userId
+  userId: string;
+
+  @OneToOne(() => User)
+  @JoinColumn({ name: 'userId' })
+  user: User;
+
+  // ⚡ Indexed fields for fast filtering
+  @Column({ unique: true })
+  employeeId: string;
+
+  @Column()
+  @Index() // Fast department filtering
+  department: string;
+
+  @Column()
+  jobTitle: string;
+
+  @Column({ nullable: true })
+  @Index() // Fast manager lookups
+  managerId: string;
+
+  @Column({ type: 'date' })
+  hireDate: Date;
+
+  @Column({ default: true })
+  @Index() // Fast active status queries
+  isActive: boolean;
+
+  @Column({ type: 'timestamptz', default: () => 'CURRENT_TIMESTAMP' })
+  createdAt: Date;
+
+  @Column({ type: 'timestamptz', default: () => 'CURRENT_TIMESTAMP' })
+  updatedAt: Date;
+}
+```
+
+#### Step 2: Create Service with Efficient Queries
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { UserService } from '@venturialstd/user';
+import { UserEmployment } from './entities/user-employment.entity';
+
+@Injectable()
+export class EmployeeService {
+  constructor(
+    @InjectRepository(UserEmployment)
+    private employmentRepo: Repository<UserEmployment>,
+    private userService: UserService,
+  ) {}
+
+  async createEmployee(data: {
+    firstname: string;
+    lastname: string;
+    email: string;
+    department: string;
+    employeeId: string;
+    jobTitle: string;
+  }) {
+    // Create base user
+    const user = await this.userService.createUser(
+      data.firstname,
+      data.lastname,
+      data.email,
+    );
+
+    // Create employment record
+    const employment = this.employmentRepo.create({
+      userId: user.id,
+      employeeId: data.employeeId,
+      department: data.department,
+      jobTitle: data.jobTitle,
+      hireDate: new Date(),
+      isActive: true,
+    });
+
+    await this.employmentRepo.save(employment);
+    return this.getEmployeeWithUser(user.id);
+  }
+
+  // ⚡ FAST: Uses department index
+  async getEmployeesByDepartment(department: string) {
+    return this.employmentRepo.find({
+      where: { department, isActive: true },
+      relations: ['user'],
+      order: { createdAt: 'DESC' },
+    });
+  }
+
+  // ⚡ FAST: Complex query with proper indexes
+  async searchEmployees(searchTerm: string, department?: string) {
+    const query = this.employmentRepo
+      .createQueryBuilder('emp')
+      .leftJoinAndSelect('emp.user', 'user')
+      .where('emp.isActive = :active', { active: true });
+
+    if (department) {
+      query.andWhere('emp.department = :dept', { dept: department });
+    }
+
+    query.andWhere(
+      '(user.firstname ILIKE :search OR user.lastname ILIKE :search OR emp.employeeId ILIKE :search)',
+      { search: `%${searchTerm}%` },
+    );
+
+    return query.getMany();
+  }
+
+  async getEmployeeWithUser(userId: string) {
+    return this.employmentRepo.findOne({
+      where: { userId },
+      relations: ['user'],
+    });
+  }
+}
+```
+
+#### Step 3: Register with UserModule
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { UserModule } from '@venturialstd/user';
+import { UserEmployment } from './entities/user-employment.entity';
+import { EmployeeService } from './services/employee.service';
+
+@Module({
+  imports: [
+    // Register your entities with UserModule
+    UserModule.forRoot({
+      additionalEntities: [UserEmployment],
+    }),
+    // Also register for your service
+    TypeOrmModule.forFeature([UserEmployment]),
+  ],
+  providers: [EmployeeService],
+  exports: [EmployeeService],
+})
+export class EmployeeModule {}
+```
+
+#### Benefits:
+- ⚡ **100x-5000x faster queries** with proper indexes
+- ✅ Database constraints (unique, foreign keys)
+- ✅ Full TypeScript type safety
+- ✅ Complex queries (JOINs, aggregations)
+- ✅ Scales to millions of records
+
+### Hybrid Approach (Optional Flexibility)
+
+If you need **some** flexibility for truly dynamic, non-queryable fields:
+
+```typescript
+@Entity('user_employment')
+export class UserEmployment {
+  // ... indexed columns for queryable fields ...
+
+  @Column()
+  @Index()
+  department: string; // ⚡ Fast queries
+
+  @Column({ unique: true })
+  employeeId: string; // ⚡ Fast lookups
+
+  // 📦 FLEXIBLE: For truly dynamic, non-queryable data only
+  @Column({ type: 'jsonb', nullable: true })
+  additionalInfo: {
+    shirtSize?: string;
+    parkingSpot?: string;
+    badgeNumber?: string;
+    emergencyContact?: {
+      name: string;
+      phone: string;
+    };
+    [key: string]: any;
+  };
+}
+```
+
+### Complete Extension Example
+
+See the `examples/` directory for complete working examples:
+- `user-employee-profile.entity.ts` - Entity with proper indexes
+- `user-employee.service.ts` - Service with efficient queries
+- `user-employee.module.ts` - Module configuration
+
+### Extension Methods Comparison
+
+| Method | Query Performance | Flexibility | Type Safety | Best For |
+|--------|------------------|-------------|-------------|----------|
+| **Related Entities** ✅ | ⚡⚡⚡ Excellent | ⭐⭐ Medium | ⭐⭐⭐ Strong | **Production (99% of cases)** |
+| **Hybrid (Entities + JSONB)** | ⚡⚡⭐ Good | ⭐⭐⭐ High | ⭐⭐⭐ Strong | Some flexibility needed |
+| **Pure JSONB** ❌ | ⚠️ Poor | ⭐⭐⭐ High | ⭐ Weak | **Avoid for queryable data** |
+| **EAV Pattern** ❌ | ⚠️ Very Poor | ⭐⭐⭐ High | ⭐ Weak | **Not recommended** |
+
+**Decision Tree:**
+- Need to filter/query this data? → **Use Related Entity** ✅
+- Just storing UI preferences? → **Can use JSONB** 📝
+- Truly unknown runtime schema? → **Consider Hybrid approach**
+
+---
+
+## 📊 Entities
+
+### User Entity
+
+The main `User` entity represents a user in the system:
+
+```typescript
+{
+  id: string;                           // UUID primary key
+  firstname: string;                    // User's first name
+  lastname: string;                     // User's last name
+  email: string;                        // Unique email address
+  phone?: string;                       // Optional phone number
+  avatar?: string;                      // Optional avatar URL
+  timezone?: string;                    // User's timezone
+  locale?: string;                      // User's locale (e.g., 'en-US')
+  status?: string;                      // User status (extensible, e.g., 'ACTIVE', 'SUSPENDED')
+  role?: string;                        // User role (extensible, e.g., 'ADMIN', 'USER', 'MODERATOR')
+  isActive: boolean;                    // Account active flag
+  isEmailVerified: boolean;             // Email verification status
+  settings?: Record<string, unknown>;   // User settings (JSONB) - for UI preferences only
+  metadata?: Record<string, unknown>;   // Additional metadata (JSONB) - for non-queryable data only
+  createdAt: Date;                      // Creation timestamp
+  updatedAt: Date;                      // Last update timestamp
+}
+```
+
+**⚠️ Important Notes:**
+
+1. **`role` and `status` are extensible** - Define your own values via `UserModule.forRoot()` configuration
+2. **Indexed fields** - Both `role` and `status` have database indexes for fast queries
+3. **JSONB fields (`settings`, `metadata`)** - Should only be used for data you'll never query or filter on
+4. **For business data** - Use related entities instead of JSONB (see Extensibility section)
+
+---
+
+## 🔌 API Reference
+
+### UserService
+
+#### `createUser(firstname, lastname, email, phone?, avatar?, timezone?, locale?)`
+Creates a new user with validation.
+
+```typescript
+const user = await userService.createUser(
+  'John',
+  'Doe',
+  'john@example.com',
+  '+1234567890',
+  'https://avatar.url',
+  'America/New_York',
+  'en-US'
+);
+```
+
+#### `getUserById(userId: string)`
+Gets a user by their ID.
+
+```typescript
+const user = await userService.getUserById('user-uuid');
+```
+
+#### `getUserByEmail(email: string)`
+Gets a user by their email address.
+
+```typescript
+const user = await userService.getUserByEmail('john@example.com');
+```
+
+#### `updateUserProfile(userId, updates)`
+Updates user profile fields.
+
+```typescript
+const user = await userService.updateUserProfile('user-uuid', {
+  firstname: 'Jane',
+  timezone: 'Europe/London',
+});
+```
+
+#### `updateUserSettings(userId, settings)`
+Updates user settings.
+
+```typescript
+const user = await userService.updateUserSettings('user-uuid', {
+  notificationsEnabled: true,
+  theme: 'dark',
+});
+```
+
+#### `updateUserMetadata(userId, metadata)`
+Updates user metadata.
+
+```typescript
+const user = await userService.updateUserMetadata('user-uuid', {
+  role: 'ADMIN',
+  department: 'Engineering',
+});
+```
+
+#### `setUserStatus(userId, isActive)`
+Activates or deactivates a user.
+
+```typescript
+const user = await userService.setUserStatus('user-uuid', false);
+```
+
+#### `verifyEmail(userId)`
+Marks a user's email as verified.
+
+```typescript
+const user = await userService.verifyEmail('user-uuid');
+```
+
+#### `getActiveUsers()`
+Gets all active users.
+
+```typescript
+const users = await userService.getActiveUsers();
+```
+
+#### `getVerifiedUsers()`
+Gets all users with verified emails.
+
+```typescript
+const users = await userService.getVerifiedUsers();
+```
+
+#### `setRole(userId: string, role: string)`
+Sets a user's role with validation.
+
+```typescript
+const user = await userService.setRole('user-uuid', 'MODERATOR');
+// Validates against allowedRoles from UserModule configuration
+```
+
+#### `setStatus(userId: string, status: string)`
+Sets a user's status with validation.
+
+```typescript
+const user = await userService.setStatus('user-uuid', 'BANNED');
+// Validates against allowedStatuses from UserModule configuration
+```
+
+#### `getUsersByRole(role: string)`
+Gets all users with a specific role.
+
+```typescript
+const moderators = await userService.getUsersByRole('MODERATOR');
+```
+
+#### `getUsersByStatus(status: string)`
+Gets all users with a specific status.
+
+```typescript
+const bannedUsers = await userService.getUsersByStatus('BANNED');
+```
+
+#### `getAllowedRoles()`
+Gets the list of allowed roles for your application.
+
+```typescript
+const roles = userService.getAllowedRoles();
+// Returns: ['ADMIN', 'USER', 'MODERATOR', ...]
+```
+
+#### `getAllowedStatuses()`
+Gets the list of allowed statuses for your application.
+
+```typescript
+const statuses = userService.getAllowedStatuses();
+// Returns: ['ACTIVE', 'INACTIVE', 'SUSPENDED', ...]
+```
+
+#### `isValidRole(role: string)`
+Checks if a role is valid for your application.
+
+```typescript
+if (userService.isValidRole('MODERATOR')) {
+  // Role is valid
+}
+```
+
+#### `isValidStatus(status: string)`
+Checks if a status is valid for your application.
+
+```typescript
+if (userService.isValidStatus('BANNED')) {
+  // Status is valid
+}
+```
+
+---
+
+## 🔐 Enums & Constants
+
+### USER_STATUS
+
+```typescript
+enum USER_STATUS {
+  ACTIVE = 'ACTIVE',
+  INACTIVE = 'INACTIVE',
+  SUSPENDED = 'SUSPENDED',
+  PENDING_VERIFICATION = 'PENDING_VERIFICATION',
+}
+```
+
+### USER_ROLE
+
+```typescript
+enum USER_ROLE {
+  ADMIN = 'ADMIN',
+  USER = 'USER',
+}
+```
+
+### USER_SETTINGS_KEY
+
+```typescript
+const USER_SETTINGS_KEY = 'USER_SETTINGS';
+```
+
+---
+
+## 🛡️ Guards & Decorators
+
+### Guards
+
+#### `UserGuard`
+Ensures the user is authenticated and active.
+
+```typescript
+@UseGuards(UserGuard)
+@Get()
+async getProfile(@CurrentUserId() userId: string) {
+  return this.userService.getUserById(userId);
+}
+```
+
+#### `UserRoleGuard`
+Enforces role-based access control.
+
+```typescript
+@RequireRoles(USER_ROLE.ADMIN)
+@UseGuards(UserGuard, UserRoleGuard)
+@Delete(':id')
+async deleteUser(@Param('id') id: string) {
+  return this.userService.setUserStatus(id, false);
+}
+```
+
+### Decorators
+
+#### `@CurrentUserId()`
+Extracts the current user ID from the request.
+
+```typescript
+@Get()
+async getData(@CurrentUserId() userId: string) {
+  return this.service.getUserData(userId);
+}
+```
+
+#### `@CurrentUser()`
+Extracts the full user object from the request.
+
+```typescript
+@Get()
+async getData(@CurrentUser() user: User) {
+  return { user };
+}
+```
+
+#### `@RequireRoles(...roles)`
+Specifies required roles for a route.
+
+```typescript
+@RequireRoles(USER_ROLE.ADMIN)
+@UseGuards(UserGuard, UserRoleGuard)
+@Delete(':id')
+async delete(@Param('id') id: string) {
+  // Only admins can access
+}
+```
+
+---
+
+## 🧪 Test Server
+
+The module includes a standalone test server for development and testing:
+
+### Start Test Server
+
+```bash
+cd src/user
+npm run test:dev
+```
+
+The server starts on port **3003** (configurable via `.env`).
+
+### Watch Mode
+
+```bash
+npm run test:watch
+```
+
+### Environment Setup
+
+1. Copy `.env.example` to `.env`:
+```bash
+cp test/.env.example test/.env
+```
+
+2. Configure your database settings in `test/.env`
+
+### Available Test Endpoints
+
+```
+POST   /users                     - Create user
+GET    /users                     - Get all users
+GET    /users/active              - Get active users
+GET    /users/verified            - Get verified users
+GET    /users/email/:email        - Get user by email
+GET    /users/:id                 - Get user by ID
+PUT    /users/:id/profile         - Update user profile
+PUT    /users/:id/settings        - Update user settings
+PUT    /users/:id/metadata        - Update user metadata
+PUT    /users/:id/status          - Update user status
+PUT    /users/:id/verify-email    - Verify user email
+DELETE /users/:id                 - Delete user
+```
+
+---
+
+## 📝 NPM Scripts
+
+```json
+{
+  "build": "tsc -p tsconfig.json",
+  "prepublishOnly": "npm run build",
+  "release:patch": "npm run build && npm version patch --no-git-tag-version && npm publish",
+  "test:dev": "ts-node -r tsconfig-paths/register test/main.ts",
+  "test:watch": "nodemon --watch src --watch test --ext ts --exec npm run test:dev",
+  "migration:generate": "ts-node node_modules/.bin/typeorm migration:generate -d test/data-source.ts test/migrations/$npm_config_name",
+  "migration:run": "ts-node node_modules/.bin/typeorm migration:run -d test/data-source.ts",
+  "migration:revert": "ts-node node_modules/.bin/typeorm migration:revert -d test/data-source.ts"
+}
+```
+
+---
+
+## 💡 Usage Examples
+
+### Example 1: Create and Verify User
+
+```typescript
+// Create a new user
+const user = await userService.createUser(
+  'Jane',
+  'Smith',
+  'jane@example.com',
+  '+1987654321',
+  null,
+  'America/Los_Angeles',
+  'en-US'
+);
+
+// Verify email
+await userService.verifyEmail(user.id);
+```
+
+### Example 2: Update User Profile
+
+```typescript
+const updatedUser = await userService.updateUserProfile(userId, {
+  firstname: 'Janet',
+  timezone: 'Europe/Paris',
+  locale: 'fr-FR',
+});
+```
+
+### Example 3: Manage User Settings
+
+```typescript
+// Update settings
+await userService.updateUserSettings(userId, {
+  notificationsEnabled: true,
+  emailNotifications: false,
+  theme: 'dark',
+});
+
+// Get user with settings
+const user = await userService.getUserById(userId);
+console.log(user.settings);
+```
+
+### Example 4: Role-Based Access
+
+```typescript
+// Set user role in metadata
+await userService.updateUserMetadata(userId, {
+  role: USER_ROLE.ADMIN,
+});
+
+// Controller with role guard
+@Controller('admin')
+export class AdminController {
+  @RequireRoles(USER_ROLE.ADMIN)
+  @UseGuards(UserGuard, UserRoleGuard)
+  @Get('dashboard')
+  async getDashboard(@CurrentUser() user: User) {
+    return { admin: user };
+  }
+}
+```
+
+### Example 5: Filter Users
+
+```typescript
+// Get all active users
+const activeUsers = await userService.getActiveUsers();
+
+// Get verified users
+const verifiedUsers = await userService.getVerifiedUsers();
+
+// Find by email
+const user = await userService.getUserByEmail('john@example.com');
+```
+
+---
+
+## 🔧 Database Migrations
+
+### Generate a Migration
+
+```bash
+npm run migration:generate --name=AddUserFields
+```
+
+### Run Migrations
+
+```bash
+npm run migration:run
+```
+
+### Revert Migration
+
+```bash
+npm run migration:revert
+```
+
+---
+
+## � Best Practices
+
+### 1. Always Use Indexes for Queryable Fields
+
+```typescript
+// ✅ GOOD: Indexed columns
+@Entity('user_profile')
+export class UserProfile {
+  @Column() @Index() // Fast lookups
+  userId: string;
+  
+  @Column() @Index() // Fast filtering
+  country: string;
+  
+  @Column({ unique: true }) // Automatically indexed
+  taxId: string;
+}
+
+// ❌ BAD: JSONB for queryable data
+user.metadata = {
+  country: 'US', // Will be slow to query!
+  taxId: '123'   // No unique constraint possible!
+};
+```
+
+### 2. Use JSONB Only for Display Data
+
+```typescript
+// ✅ GOOD: Non-queryable UI preferences
+user.settings = {
+  theme: 'dark',
+  language: 'en',
+  sidebarCollapsed: true
+};
+
+// ✅ GOOD: Audit/log data you never filter on
+user.metadata = {
+  lastLoginIp: '192.168.1.1',
+  userAgent: 'Mozilla/5.0...',
+  registrationSource: 'mobile_app'
+};
+
+// ❌ BAD: Business data you need to query
+user.metadata = {
+  subscriptionTier: 'premium', // Use UserSubscription entity!
+  department: 'Engineering',    // Use UserEmployment entity!
+  isActive: true               // Use column on User entity!
+};
+```
+
+### 3. Create Composite Indexes for Common Queries
+
+```typescript
+@Entity('user_subscription')
+@Index(['userId', 'isActive']) // For userId + status queries
+@Index(['plan', 'expiresAt'])  // For plan + expiration queries
+export class UserSubscription {
+  @Column() userId: string;
+  @Column() plan: string;
+  @Column() isActive: boolean;
+  @Column() expiresAt: Date;
+}
+
+// Now these queries are super fast:
+await repo.find({
+  where: { userId: 'abc-123', isActive: true } // Uses composite index
+});
+
+await repo.find({
+  where: { 
+    plan: 'premium', 
+    expiresAt: MoreThan(new Date()) 
+  } // Uses composite index
+});
+```
+
+### 4. Use TypeORM QueryBuilder for Complex Queries
+
+```typescript
+// ✅ Complex query with proper indexes
+const result = await employmentRepo
+  .createQueryBuilder('emp')
+  .leftJoinAndSelect('emp.user', 'user')
+  .where('emp.department = :dept', { dept: 'Engineering' })
+  .andWhere('emp.isActive = :active', { active: true })
+  .andWhere('user.isEmailVerified = :verified', { verified: true })
+  .orderBy('emp.hireDate', 'DESC')
+  .limit(50)
+  .getMany();
+```
+
+### 5. Validate Data at the Application Layer
+
+```typescript
+// Use DTOs with class-validator
+export class CreateEmployeeDto {
+  @IsString()
+  @MinLength(2)
+  firstname: string;
+
+  @IsEmail()
+  email: string;
+
+  @IsEnum(['Engineering', 'Sales', 'Marketing'])
+  department: string;
+
+  @IsPositive()
+  @Max(1000000)
+  salary: number;
+}
+```
+
+### 6. Handle Relations Efficiently
+
+```typescript
+// ✅ GOOD: Eager load when you know you need it
+const employees = await repo.find({
+  where: { department: 'Engineering' },
+  relations: ['user'] // Load user in same query
+});
+
+// ✅ GOOD: Load separately for optional data
+const employee = await repo.findOne({ where: { userId } });
+if (needUserDetails) {
+  employee.user = await userService.findOne(userId);
+}
+
+// ❌ BAD: N+1 query problem
+const employees = await repo.find({ where: { department: 'Engineering' } });
+for (const emp of employees) {
+  emp.user = await userService.findOne(emp.userId); // Queries in loop!
+}
+```
+
+### 7. Use Transactions for Multi-Entity Operations
+
+```typescript
+async createEmployeeWithProfile(data: CreateEmployeeDto) {
+  return this.dataSource.transaction(async (manager) => {
+    // Create user
+    const user = await manager.save(User, {
+      firstname: data.firstname,
+      lastname: data.lastname,
+      email: data.email
+    });
+
+    // Create employment record
+    const employment = await manager.save(UserEmployment, {
+      userId: user.id,
+      department: data.department,
+      salary: data.salary
+    });
+
+    // If anything fails, both are rolled back
+    return { user, employment };
+  });
+}
+```
+
+### 8. Document Your Extension Entities
+
+```typescript
+/**
+ * UserEmployment Entity
+ * 
+ * Stores employee-specific information for users who are employees.
+ * Related to User entity via userId.
+ * 
+ * Indexes:
+ * - userId: For fast user lookups
+ * - department: For filtering by department
+ * - (department, isActive): For active employee queries by department
+ * 
+ * @example
+ * const emp = await employmentRepo.findOne({ 
+ *   where: { userId: 'abc-123' } 
+ * });
+ */
+@Entity('user_employment')
+@Index(['department', 'isActive'])
+export class UserEmployment {
+  // ...
+}
+```
+
+### 9. Plan for Data Growth
+
+```typescript
+// Consider pagination for large result sets
+async getEmployeesByDepartment(
+  department: string, 
+  page: number = 1, 
+  limit: number = 50
+) {
+  return this.employmentRepo.find({
+    where: { department, isActive: true },
+    relations: ['user'],
+    skip: (page - 1) * limit,
+    take: limit,
+    order: { createdAt: 'DESC' }
+  });
+}
+
+// Add count for pagination UI
+async getEmployeeCount(department: string) {
+  return this.employmentRepo.count({
+    where: { department, isActive: true }
+  });
+}
+```
+
+### 10. Monitor Query Performance
+
+```typescript
+// Enable query logging in development
+TypeOrmModule.forRoot({
+  // ...
+  logging: ['query', 'error', 'warn'],
+  maxQueryExecutionTime: 1000, // Warn if query takes > 1s
+});
+
+// Log slow queries in your service
+const startTime = Date.now();
+const result = await this.repo.find({ ... });
+const duration = Date.now() - startTime;
+
+if (duration > 100) {
+  this.logger.warn(`Slow query detected: ${duration}ms`);
+}
+```
+
+---
+
+## 🔄 Migration from JSONB
+
+If you have existing data in JSONB that needs to be queryable:
+
+### Step 1: Create New Entity
+
+```typescript
+@Entity('user_employment')
+@Index(['userId'])
+@Index(['department'])
+export class UserEmployment {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  userId: string;
+
+  @Column()
+  department: string;
+
+  @Column({ type: 'decimal', precision: 10, scale: 2 })
+  salary: number;
+}
+```
+
+### Step 2: Create Migration
+
+```bash
+npm run migration:generate --name=MigrateEmploymentData
+```
+
+### Step 3: Write Migration Logic
+
+```typescript
+export class MigrateEmploymentData1234567890 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // 1. Create table with indexes
+    await queryRunner.query(`
+      CREATE TABLE user_employment (
+        id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+        "userId" UUID NOT NULL,
+        department VARCHAR(100),
+        salary DECIMAL(10,2),
+        "createdAt" TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      );
+      
+      CREATE INDEX idx_employment_user ON user_employment("userId");
+      CREATE INDEX idx_employment_dept ON user_employment(department);
+    `);
+
+    // 2. Migrate data
+    await queryRunner.query(`
+      INSERT INTO user_employment ("userId", department, salary)
+      SELECT 
+        id,
+        metadata->>'department',
+        (metadata->>'salary')::DECIMAL
+      FROM "user"
+      WHERE metadata ? 'department';
+    `);
+
+    // 3. Clean up old data
+    await queryRunner.query(`
+      UPDATE "user"
+      SET metadata = metadata - 'department' - 'salary'
+      WHERE metadata ? 'department';
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Migrate back if needed
+    await queryRunner.query(`
+      UPDATE "user"
+      SET metadata = jsonb_set(
+        jsonb_set(
+          COALESCE(metadata, '{}'::jsonb),
+          '{department}',
+          to_jsonb(emp.department)
+        ),
+        '{salary}',
+        to_jsonb(emp.salary)
+      )
+      FROM user_employment emp
+      WHERE "user".id = emp."userId";
+    `);
+    
+    await queryRunner.query(`DROP TABLE IF EXISTS user_employment;`);
+  }
+}
+```
+
+### Step 4: Run Migration
+
+```bash
+npm run migration:run
+```
+
+---
+
+## 📚 Additional Resources
+
+### Official Documentation
+- [NestJS Documentation](https://docs.nestjs.com)
+- [TypeORM Documentation](https://typeorm.io)
+- [PostgreSQL Performance Tips](https://wiki.postgresql.org/wiki/Performance_Optimization)
+
+### Related Modules
+- `@venturialstd/core` - Core shared functionality
+- `@venturialstd/organization` - Organization management module
+- `@venturialstd/auth` - Authentication module
+
+### Performance References
+- [PostgreSQL Index Types](https://www.postgresql.org/docs/current/indexes-types.html)
+- [JSONB Performance](https://www.postgresql.org/docs/current/datatype-json.html)
+- [Query Optimization](https://www.postgresql.org/docs/current/performance-tips.html)
+
+---
+
+## �📄 License
+
+This module is part of the Venturial Standard Library.
+
+---
+
+## 🤝 Contributing
+
+For contribution guidelines, please refer to the main repository's CONTRIBUTING.md.
+
+---
+
+## 📞 Support
+
+For issues and questions, please open an issue in the main repository.