rez_core 7.1.1 → 7.1.2

package/src/module/eav/EAV_USAGE_GUIDE.md

@@ -1,351 +1,351 @@
-# EAV Module Usage Guide
-
-## Overview
-
-The EAV (Entity-Attribute-Value) module provides a flexible way to store dynamic attributes for entities using different data types. It implements the **Strategy Pattern** and **Factory Pattern** for clean, maintainable code.
-
-## Architecture
-
-```mermaid
-graph TD
-    A[EavService - Orchestrator] --> B[EavFactoryService]
-    B --> C[IEavStrategy Interface]
-    C --> D[EavVarcharService]
-    C --> E[EavIntService]
-    C --> F[EavBooleanService]
-    C --> G[EavDecimalService]
-    C --> H[EavTextService]
-    C --> I[EavJsonService]
-    C --> J[EavDateService]
-    C --> K[EavTimeService]
-    C --> L[EavTimestampService]
-```
-
-## Supported Data Types
-
-- `varchar` / `string` - String values
-- `int` / `integer` - Integer values
-- `boolean` / `bool` - Boolean values
-- `decimal` / `float` - Decimal/Float values
-- `text` - Large text values
-- `json` - JSON objects
-- `date` - Date values
-- `time` - Time values
-- `timestamp` / `datetime` - Timestamp values
-
-## Basic Usage
-
-### 1. Import the Module
-
-```typescript
-import { Module } from '@nestjs/common';
-import { EavModule } from './module/eav/eav.module';
-
-@Module({
-  imports: [EavModule],
-})
-export class AppModule {}
-```
-
-### 2. Inject the Service
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { EavService } from './module/eav/service/eav.service';
-
-@Injectable()
-export class YourService {
-  constructor(private readonly eavService: EavService) {}
-}
-```
-
-### 3. Perform CRUD Operations
-
-#### Create a Record
-
-```typescript
-// Create a varchar attribute
-const result = await this.eavService.create('varchar', {
-  entity_type: 'user',
-  entity_id: 123,
-  key: 'nickname',
-  value: 'JohnDoe',
-}, 1); // modifiedBy user ID
-
-// Create an integer attribute
-await this.eavService.create('int', {
-  entity_type: 'product',
-  entity_id: 456,
-  key: 'stock_quantity',
-  value: 100,
-});
-
-// Create a JSON attribute
-await this.eavService.create('json', {
-  entity_type: 'user',
-  entity_id: 123,
-  key: 'preferences',
-  value: { theme: 'dark', language: 'en' },
-});
-```
-
-#### Find One Record
-
-```typescript
-const attribute = await this.eavService.findOne('varchar', {
-  entity_type: 'user',
-  entity_id: 123,
-  key: 'nickname',
-});
-
-console.log(attribute.value); // 'JohnDoe'
-```
-
-#### Find All Records
-
-```typescript
-// Find all attributes for a specific entity
-const userAttributes = await this.eavService.findAll('varchar', {
-  entity_type: 'user',
-  entity_id: 123,
-});
-
-// Find all attributes of a type for an entity type
-const allUserVarchars = await this.eavService.findAll('varchar', {
-  entity_type: 'user',
-});
-```
-
-#### Update a Record
-
-```typescript
-const updated = await this.eavService.update(
-  'varchar',
-  {
-    entity_type: 'user',
-    entity_id: 123,
-    key: 'nickname',
-  },
-  {
-    value: 'JaneDoe',
-  },
-  1, // modifiedBy user ID
-);
-```
-
-#### Delete a Record
-
-```typescript
-const deleted = await this.eavService.delete('varchar', {
-  entity_type: 'user',
-  entity_id: 123,
-  key: 'nickname',
-});
-
-console.log(deleted); // true if deleted, false otherwise
-```
-
-#### Upsert (Create or Update)
-
-```typescript
-// Will create if doesn't exist, update if exists
-const result = await this.eavService.upsert('varchar', {
-  entity_type: 'user',
-  entity_id: 123,
-  key: 'nickname',
-  value: 'UpdatedNickname',
-}, 1);
-```
-
-## Advanced Usage
-
-### Using the Factory Directly
-
-If you need more control, you can inject the factory service:
-
-```typescript
-import { EavFactoryService } from './module/eav/service/eav-factory.service';
-
-@Injectable()
-export class YourService {
-  constructor(private readonly eavFactory: EavFactoryService) {}
-
-  async customOperation() {
-    // Get the service for a specific type
-    const varcharService = this.eavFactory.getService('varchar');
-    
-    // Use the service directly
-    const result = await varcharService.create({
-      entity_type: 'custom',
-      entity_id: 999,
-      key: 'custom_key',
-      value: 'custom_value',
-    });
-  }
-}
-```
-
-### Type Checking
-
-```typescript
-// Check if a type is supported
-const isSupported = this.eavService.isTypeSupported('varchar'); // true
-const notSupported = this.eavService.isTypeSupported('unknown'); // false
-
-// Get all supported types
-const types = this.eavService.getSupportedTypes();
-console.log(types); // ['varchar', 'string', 'int', 'integer', ...]
-```
-
-## REST API Examples (Using the Controller)
-
-### Create
-```bash
-POST /eav/varchar?modifiedBy=1
-Content-Type: application/json
-
-{
-  "entity_type": "user",
-  "entity_id": 123,
-  "key": "nickname",
-  "value": "JohnDoe"
-}
-```
-
-### Find One
-```bash
-GET /eav/varchar/find-one?entity_type=user&entity_id=123&key=nickname
-```
-
-### Find All
-```bash
-GET /eav/varchar?entity_type=user&entity_id=123
-```
-
-### Update
-```bash
-PUT /eav/varchar?entity_type=user&entity_id=123&key=nickname&modifiedBy=1
-Content-Type: application/json
-
-{
-  "value": "JaneDoe"
-}
-```
-
-### Delete
-```bash
-DELETE /eav/varchar?entity_type=user&entity_id=123&key=nickname
-```
-
-### Upsert
-```bash
-POST /eav/varchar/upsert?modifiedBy=1
-Content-Type: application/json
-
-{
-  "entity_type": "user",
-  "entity_id": 123,
-  "key": "nickname",
-  "value": "UpdatedNickname"
-}
-```
-
-### Get Supported Types
-```bash
-GET /eav/meta/supported-types
-```
-
-## Design Pattern Benefits
-
-### Strategy Pattern
-- Each data type has its own service implementing `IEavStrategy`
-- Easy to add new data types without modifying existing code
-- Each service is independently testable
-
-### Factory Pattern
-- `EavFactoryService` resolves the correct service based on data type
-- Centralizes service selection logic
-- Supports type aliases (e.g., 'string' → 'varchar')
-
-### Facade Pattern
-- `EavService` provides a simple, unified interface
-- Hides complexity of service resolution
-- Makes it easy for consumers to use the module
-
-## Error Handling
-
-The factory will throw a `BadRequestException` if an unsupported data type is provided:
-
-```typescript
-try {
-  await this.eavService.create('unsupported_type', {...});
-} catch (error) {
-  // BadRequestException: Unsupported data type: unsupported_type
-}
-```
-
-## Best Practices
-
-1. **Always specify the correct data type** - Use the appropriate type for your data
-2. **Use upsert when appropriate** - Simplifies create-or-update logic
-3. **Track modifications** - Pass `modifiedBy` to track who made changes
-4. **Validate input** - The DTOs include validation decorators
-5. **Handle errors** - Always wrap calls in try-catch for production code
-
-## Example: Complete User Preferences System
-
-```typescript
-@Injectable()
-export class UserPreferencesService {
-  constructor(private readonly eavService: EavService) {}
-
-  async setPreference(userId: number, key: string, value: any, type: string) {
-    return await this.eavService.upsert(type, {
-      entity_type: 'user_preferences',
-      entity_id: userId,
-      key,
-      value,
-    }, userId);
-  }
-
-  async getPreference(userId: number, key: string, type: string) {
-    return await this.eavService.findOne(type, {
-      entity_type: 'user_preferences',
-      entity_id: userId,
-      key,
-    });
-  }
-
-  async getAllPreferences(userId: number) {
-    // Get preferences from different types
-    const varchars = await this.eavService.findAll('varchar', {
-      entity_type: 'user_preferences',
-      entity_id: userId,
-    });
-
-    const booleans = await this.eavService.findAll('boolean', {
-      entity_type: 'user_preferences',
-      entity_id: userId,
-    });
-
-    const jsons = await this.eavService.findAll('json', {
-      entity_type: 'user_preferences',
-      entity_id: userId,
-    });
-
-    return {
-      strings: varchars,
-      flags: booleans,
-      objects: jsons,
-    };
-  }
-
-  async deletePreference(userId: number, key: string, type: string) {
-    return await this.eavService.delete(type, {
-      entity_type: 'user_preferences',
-      entity_id: userId,
-      key,
-    });
-  }
-}
-```
+# EAV Module Usage Guide
+
+## Overview
+
+The EAV (Entity-Attribute-Value) module provides a flexible way to store dynamic attributes for entities using different data types. It implements the **Strategy Pattern** and **Factory Pattern** for clean, maintainable code.
+
+## Architecture
+
+```mermaid
+graph TD
+    A[EavService - Orchestrator] --> B[EavFactoryService]
+    B --> C[IEavStrategy Interface]
+    C --> D[EavVarcharService]
+    C --> E[EavIntService]
+    C --> F[EavBooleanService]
+    C --> G[EavDecimalService]
+    C --> H[EavTextService]
+    C --> I[EavJsonService]
+    C --> J[EavDateService]
+    C --> K[EavTimeService]
+    C --> L[EavTimestampService]
+```
+
+## Supported Data Types
+
+- `varchar` / `string` - String values
+- `int` / `integer` - Integer values
+- `boolean` / `bool` - Boolean values
+- `decimal` / `float` - Decimal/Float values
+- `text` - Large text values
+- `json` - JSON objects
+- `date` - Date values
+- `time` - Time values
+- `timestamp` / `datetime` - Timestamp values
+
+## Basic Usage
+
+### 1. Import the Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { EavModule } from './module/eav/eav.module';
+
+@Module({
+  imports: [EavModule],
+})
+export class AppModule {}
+```
+
+### 2. Inject the Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { EavService } from './module/eav/service/eav.service';
+
+@Injectable()
+export class YourService {
+  constructor(private readonly eavService: EavService) {}
+}
+```
+
+### 3. Perform CRUD Operations
+
+#### Create a Record
+
+```typescript
+// Create a varchar attribute
+const result = await this.eavService.create('varchar', {
+  entity_type: 'user',
+  entity_id: 123,
+  key: 'nickname',
+  value: 'JohnDoe',
+}, 1); // modifiedBy user ID
+
+// Create an integer attribute
+await this.eavService.create('int', {
+  entity_type: 'product',
+  entity_id: 456,
+  key: 'stock_quantity',
+  value: 100,
+});
+
+// Create a JSON attribute
+await this.eavService.create('json', {
+  entity_type: 'user',
+  entity_id: 123,
+  key: 'preferences',
+  value: { theme: 'dark', language: 'en' },
+});
+```
+
+#### Find One Record
+
+```typescript
+const attribute = await this.eavService.findOne('varchar', {
+  entity_type: 'user',
+  entity_id: 123,
+  key: 'nickname',
+});
+
+console.log(attribute.value); // 'JohnDoe'
+```
+
+#### Find All Records
+
+```typescript
+// Find all attributes for a specific entity
+const userAttributes = await this.eavService.findAll('varchar', {
+  entity_type: 'user',
+  entity_id: 123,
+});
+
+// Find all attributes of a type for an entity type
+const allUserVarchars = await this.eavService.findAll('varchar', {
+  entity_type: 'user',
+});
+```
+
+#### Update a Record
+
+```typescript
+const updated = await this.eavService.update(
+  'varchar',
+  {
+    entity_type: 'user',
+    entity_id: 123,
+    key: 'nickname',
+  },
+  {
+    value: 'JaneDoe',
+  },
+  1, // modifiedBy user ID
+);
+```
+
+#### Delete a Record
+
+```typescript
+const deleted = await this.eavService.delete('varchar', {
+  entity_type: 'user',
+  entity_id: 123,
+  key: 'nickname',
+});
+
+console.log(deleted); // true if deleted, false otherwise
+```
+
+#### Upsert (Create or Update)
+
+```typescript
+// Will create if doesn't exist, update if exists
+const result = await this.eavService.upsert('varchar', {
+  entity_type: 'user',
+  entity_id: 123,
+  key: 'nickname',
+  value: 'UpdatedNickname',
+}, 1);
+```
+
+## Advanced Usage
+
+### Using the Factory Directly
+
+If you need more control, you can inject the factory service:
+
+```typescript
+import { EavFactoryService } from './module/eav/service/eav-factory.service';
+
+@Injectable()
+export class YourService {
+  constructor(private readonly eavFactory: EavFactoryService) {}
+
+  async customOperation() {
+    // Get the service for a specific type
+    const varcharService = this.eavFactory.getService('varchar');
+    
+    // Use the service directly
+    const result = await varcharService.create({
+      entity_type: 'custom',
+      entity_id: 999,
+      key: 'custom_key',
+      value: 'custom_value',
+    });
+  }
+}
+```
+
+### Type Checking
+
+```typescript
+// Check if a type is supported
+const isSupported = this.eavService.isTypeSupported('varchar'); // true
+const notSupported = this.eavService.isTypeSupported('unknown'); // false
+
+// Get all supported types
+const types = this.eavService.getSupportedTypes();
+console.log(types); // ['varchar', 'string', 'int', 'integer', ...]
+```
+
+## REST API Examples (Using the Controller)
+
+### Create
+```bash
+POST /eav/varchar?modifiedBy=1
+Content-Type: application/json
+
+{
+  "entity_type": "user",
+  "entity_id": 123,
+  "key": "nickname",
+  "value": "JohnDoe"
+}
+```
+
+### Find One
+```bash
+GET /eav/varchar/find-one?entity_type=user&entity_id=123&key=nickname
+```
+
+### Find All
+```bash
+GET /eav/varchar?entity_type=user&entity_id=123
+```
+
+### Update
+```bash
+PUT /eav/varchar?entity_type=user&entity_id=123&key=nickname&modifiedBy=1
+Content-Type: application/json
+
+{
+  "value": "JaneDoe"
+}
+```
+
+### Delete
+```bash
+DELETE /eav/varchar?entity_type=user&entity_id=123&key=nickname
+```
+
+### Upsert
+```bash
+POST /eav/varchar/upsert?modifiedBy=1
+Content-Type: application/json
+
+{
+  "entity_type": "user",
+  "entity_id": 123,
+  "key": "nickname",
+  "value": "UpdatedNickname"
+}
+```
+
+### Get Supported Types
+```bash
+GET /eav/meta/supported-types
+```
+
+## Design Pattern Benefits
+
+### Strategy Pattern
+- Each data type has its own service implementing `IEavStrategy`
+- Easy to add new data types without modifying existing code
+- Each service is independently testable
+
+### Factory Pattern
+- `EavFactoryService` resolves the correct service based on data type
+- Centralizes service selection logic
+- Supports type aliases (e.g., 'string' → 'varchar')
+
+### Facade Pattern
+- `EavService` provides a simple, unified interface
+- Hides complexity of service resolution
+- Makes it easy for consumers to use the module
+
+## Error Handling
+
+The factory will throw a `BadRequestException` if an unsupported data type is provided:
+
+```typescript
+try {
+  await this.eavService.create('unsupported_type', {...});
+} catch (error) {
+  // BadRequestException: Unsupported data type: unsupported_type
+}
+```
+
+## Best Practices
+
+1. **Always specify the correct data type** - Use the appropriate type for your data
+2. **Use upsert when appropriate** - Simplifies create-or-update logic
+3. **Track modifications** - Pass `modifiedBy` to track who made changes
+4. **Validate input** - The DTOs include validation decorators
+5. **Handle errors** - Always wrap calls in try-catch for production code
+
+## Example: Complete User Preferences System
+
+```typescript
+@Injectable()
+export class UserPreferencesService {
+  constructor(private readonly eavService: EavService) {}
+
+  async setPreference(userId: number, key: string, value: any, type: string) {
+    return await this.eavService.upsert(type, {
+      entity_type: 'user_preferences',
+      entity_id: userId,
+      key,
+      value,
+    }, userId);
+  }
+
+  async getPreference(userId: number, key: string, type: string) {
+    return await this.eavService.findOne(type, {
+      entity_type: 'user_preferences',
+      entity_id: userId,
+      key,
+    });
+  }
+
+  async getAllPreferences(userId: number) {
+    // Get preferences from different types
+    const varchars = await this.eavService.findAll('varchar', {
+      entity_type: 'user_preferences',
+      entity_id: userId,
+    });
+
+    const booleans = await this.eavService.findAll('boolean', {
+      entity_type: 'user_preferences',
+      entity_id: userId,
+    });
+
+    const jsons = await this.eavService.findAll('json', {
+      entity_type: 'user_preferences',
+      entity_id: userId,
+    });
+
+    return {
+      strings: varchars,
+      flags: booleans,
+      objects: jsons,
+    };
+  }
+
+  async deletePreference(userId: number, key: string, type: string) {
+    return await this.eavService.delete(type, {
+      entity_type: 'user_preferences',
+      entity_id: userId,
+      key,
+    });
+  }
+}
+```