rez_core 7.1.21 → 7.1.22

package/src/module/entity/eav/EAV_USAGE_GUIDE.md

@@ -0,0 +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,
+    });
+  }
+}
+```

package/src/module/entity/eav/controller/eav.controller.ts

@@ -0,0 +1,119 @@
+import {
+    Controller,
+    Get,
+    Post,
+    Put,
+    Delete,
+    Body,
+    Param,
+    Query,
+    HttpCode,
+    HttpStatus,
+} from '@nestjs/common';
+import { EAVService } from '../service/eav.service';
+import { CreateEAVDto, UpdateEAVDto, EAVQueryDto } from '../dto/eav-operation.dto';
+
+/**
+ * Example EAV Controller
+ * Demonstrates how to use the EAV service for CRUD operations
+ */
+@Controller('eav')
+export class EavController {
+    constructor(private readonly eavService: EAVService) { }
+
+    /**
+     * Create a new EAV record
+     * POST /eav/:dataType
+     * Body: { entity_type, entity_id, key, value }
+     */
+    @Post(':dataType')
+    @HttpCode(HttpStatus.CREATED)
+    async create(
+        @Param('dataType') dataType: string,
+        @Body() createDto: CreateEAVDto,
+        @Query('modifiedBy') modifiedBy?: number,
+    ) {
+        return await this.eavService.create(dataType, createDto, modifiedBy);
+    }
+
+    /**
+     * Find a single EAV record
+     * GET /eav/:dataType/find-one?entity_type=xxx&entity_id=xxx&key=xxx
+     */
+    @Get(':dataType/find-one')
+    async findOne(@Param('dataType') dataType: string, @Query() query: EAVQueryDto) {
+        return await this.eavService.findOne(dataType, query);
+    }
+
+    /**
+     * Find all EAV records matching the query
+     * GET /eav/:dataType?entity_type=xxx&entity_id=xxx
+     */
+    @Get(':dataType')
+    async findAll(@Param('dataType') dataType: string, @Query() query: Partial<EAVQueryDto>) {
+        return await this.eavService.findAll(dataType, query);
+    }
+
+    /**
+     * Update an existing EAV record
+     * PUT /eav/:dataType?entity_type=xxx&entity_id=xxx&key=xxx
+     * Body: { value }
+     */
+    @Put(':dataType')
+    async update(
+        @Param('dataType') dataType: string,
+        @Query() query: EAVQueryDto,
+        @Body() updateDto: UpdateEAVDto,
+        @Query('modifiedBy') modifiedBy?: number,
+    ) {
+        return await this.eavService.update(dataType, query, updateDto, modifiedBy);
+    }
+
+    /**
+     * Delete an EAV record
+     * DELETE /eav/:dataType?entity_type=xxx&entity_id=xxx&key=xxx
+     */
+    @Delete(':dataType')
+    @HttpCode(HttpStatus.NO_CONTENT)
+    async delete(@Param('dataType') dataType: string, @Query() query: EAVQueryDto) {
+        const deleted = await this.eavService.delete(dataType, query);
+        return { deleted };
+    }
+
+    /**
+     * Upsert (create or update) an EAV record
+     * POST /eav/:dataType/upsert
+     * Body: { entity_type, entity_id, key, value }
+     */
+    @Post(':dataType/upsert')
+    async upsert(
+        @Param('dataType') dataType: string,
+        @Body() createDto: CreateEAVDto,
+        @Query('modifiedBy') modifiedBy?: number,
+    ) {
+        return await this.eavService.upsert(dataType, createDto, modifiedBy);
+    }
+
+    /**
+     * Get all supported data types
+     * GET /eav/meta/supported-types
+     */
+    @Get('meta/supported-types')
+    getSupportedTypes() {
+        return {
+            supportedTypes: this.eavService.getSupportedTypes(),
+        };
+    }
+
+    /**
+     * Check if a data type is supported
+     * GET /eav/meta/is-supported/:dataType
+     */
+    @Get('meta/is-supported/:dataType')
+    isTypeSupported(@Param('dataType') dataType: string) {
+        return {
+            dataType,
+            isSupported: this.eavService.isTypeSupported(dataType),
+        };
+    }
+}

package/src/module/entity/eav/dto/eav-operation.dto.ts

@@ -0,0 +1,62 @@
+import { IsNotEmpty, IsString, IsOptional, IsNumber } from 'class-validator';
+
+/**
+ * DTO for creating EAV records
+ */
+export class CreateEAVDto {
+    @IsNotEmpty()
+    @IsString()
+    entity_type: string;
+
+    @IsNotEmpty()
+    entity_id: string | number;
+
+    @IsNotEmpty()
+    @IsString()
+    key: string;
+
+    @IsNotEmpty()
+    value: any;
+}
+
+/**
+ * DTO for updating EAV records
+ */
+export class UpdateEAVDto {
+    @IsNotEmpty()
+    value: any;
+}
+
+/**
+ * DTO for querying EAV records
+ */
+export class EAVQueryDto {
+    @IsNotEmpty()
+    @IsString()
+    entity_type: string;
+
+    @IsNotEmpty()
+    entity_id: string | number;
+
+    @IsNotEmpty()
+    @IsString()
+    key: string;
+}
+
+/**
+ * DTO for EAV operations with data type
+ */
+export class EavOperationDto extends CreateEAVDto {
+    @IsNotEmpty()
+    @IsString()
+    data_type: string;
+}
+
+/**
+ * DTO for EAV query with data type
+ */
+export class EavQueryWithTypeDto extends EAVQueryDto {
+    @IsNotEmpty()
+    @IsString()
+    data_type: string;
+}

package/src/module/entity/eav/eav.module.ts

@@ -0,0 +1,80 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { EAVDate } from './entity/eav-date.entity';
+import { EAVBoolean } from './entity/eav-boolean.entity';
+import { EAVTime } from './entity/eav-time.entity';
+import { EAVTimeStamp } from './entity/eav-timestamp.entity';
+import { EAVInt } from './entity/eav-int.entity';
+import { EAVDecimal } from './entity/eav-decimal.entity';
+import { EAVJson } from './entity/eav-json.entity';
+import { EAVText } from './entity/eav-text.entity';
+import { EAVVarchar } from './entity/eav-varchar.entity';
+
+// Services
+import { EAVService } from './service/eav.service';
+import { EAVFactoryService } from './service/eav-factory.service';
+import { EAVVarcharService } from './service/eav-varchar.service';
+import { EAVIntService } from './service/eav-int.service';
+import { EAVBooleanService } from './service/eav-boolean.service';
+import { EAVDecimalService } from './service/eav-decimal.service';
+import { EAVTextService } from './service/eav-text.service';
+import { EAVJsonService } from './service/eav-json.service';
+import { EAVDateService } from './service/eav-date.service';
+import { EAVTimeService } from './service/eav-time.service';
+import { EAVTimestampService } from './service/eav-timestamp.service';
+
+// Repositories
+import { EAVVarcharRepository } from './repository/eav-varchar.repository';
+import { EAVIntRepository } from './repository/eav-int.repository';
+import { EAVBooleanRepository } from './repository/eav-boolean.repository';
+import { EAVDecimalRepository } from './repository/eav-decimal.repository';
+import { EAVTextRepository } from './repository/eav-text.repository';
+import { EAVJsonRepository } from './repository/eav-json.repository';
+import { EAVDateRepository } from './repository/eav-date.repository';
+import { EAVTimeRepository } from './repository/eav-time.repository';
+import { EAVTimestampRepository } from './repository/eav-timestamp.repository';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+      EAVVarchar,
+      EAVInt,
+      EAVBoolean,
+      EAVDecimal,
+      EAVText,
+      EAVJson,
+      EAVDate,
+      EAVTime,
+      EAVTimeStamp,
+    ]),
+  ],
+  providers: [
+    // Repositories
+    EAVVarcharRepository,
+    EAVIntRepository,
+    EAVBooleanRepository,
+    EAVDecimalRepository,
+    EAVTextRepository,
+    EAVJsonRepository,
+    EAVDateRepository,
+    EAVTimeRepository,
+    EAVTimestampRepository,
+    // Type-specific services
+    EAVVarcharService,
+    EAVIntService,
+    EAVBooleanService,
+    EAVDecimalService,
+    EAVTextService,
+    EAVJsonService,
+    EAVDateService,
+    EAVTimeService,
+    EAVTimestampService,
+    // Factory service
+    EAVFactoryService,
+    // Main orchestrator service
+    EAVService,
+  ],
+  exports: [EAVService],
+})
+export class EAVModule {
+}

package/src/module/entity/eav/entity/eav-boolean.entity.ts

@@ -0,0 +1,26 @@
+import { Column, Entity, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm';
+
+@Entity({ name: 'frm_eav_boolean' })
+export class EAVBoolean {
+
+  @PrimaryGeneratedColumn({ type: 'bigint' })
+  id: number;
+
+  @Column({ type: 'varchar', length: 50, name: 'entity_type' })
+  entity_type: string;
+
+  @Column({ type: 'bigint', name: 'entity_id' })
+  entity_id: string;
+
+  @UpdateDateColumn()
+  modified_date: Date;
+
+  @Column({ type: 'bigint', nullable: true, name: 'modified_by' })
+  modified_by: number;
+
+  @Column({ type: 'varchar', length: 100 })
+  key: string;
+
+  @Column({ type: 'boolean' })
+  value: any;
+}

package/src/module/entity/eav/entity/eav-date.entity.ts

@@ -0,0 +1,25 @@
+import { Column, Entity, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm';
+
+@Entity({name: 'frm_eav_date'})
+export class EAVDate {
+  @PrimaryGeneratedColumn({ type: 'bigint' })
+  id: number;
+
+  @Column({ type: 'varchar', length: 50, name: 'entity_type' })
+  entity_type: string;
+
+  @Column({ type: 'bigint', name: 'entity_id' })
+  entity_id: string;
+
+  @UpdateDateColumn()
+  modified_date: Date;
+
+  @Column({type: 'bigint', nullable: true, name: 'modified_by'})
+  modified_by: number;
+
+  @Column({type: 'varchar', length: 100})
+  key: string;
+
+  @Column({type: 'date'})
+  value: any;
+}

package/src/module/entity/eav/entity/eav-decimal.entity.ts

@@ -0,0 +1,25 @@
+import { Column, Entity, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm';
+
+@Entity({name: 'frm_eav_decimal'})
+export class EAVDecimal {
+  @PrimaryGeneratedColumn({ type: 'bigint' })
+  id: number;
+
+  @Column({ type: 'varchar', length: 50, name: 'entity_type' })
+  entity_type: string;
+
+  @Column({ type: 'bigint', name: 'entity_id' })
+  entity_id: string;
+
+  @UpdateDateColumn()
+  modified_date: Date;
+
+  @Column({type: 'bigint', nullable: true, name: 'modified_by'})
+  modified_by: number;
+
+  @Column({type: 'varchar', length: 100})
+  key: string;
+
+  @Column({type: 'decimal'})
+  value: any;
+}