npm package: @gennext/lb-infra
Description: Gennex Technology - Loopback 4 Framework
Latest version: 0.0.10

# @gennext/lb-infra

`@gennext/lb-infra` là bộ khung cơ sở (infrastructure framework) được phát triển bởi Gennex Technology dựa trên LoopBack 4. Thư viện này cung cấp các công cụ, tiện ích và các lớp cơ sở giúp tăng tốc độ phát triển các ứng dụng backend một cách nhất quán và bảo mật.

## Tính năng chính

- ✅ **Enhanced Logger**: Hệ thống logging mạnh mẽ hỗ trợ ghi log truy cập HTTP, ẩn thông tin nhạy cảm (data masking), theo dõi Request ID và đo lường hiệu suất.
- ✅ **Base Models & Datasources**: Cung cấp các lớp cơ sở như `BaseEntity`, `BaseDataSource` giúp chuẩn hóa cấu trúc dữ liệu và kết nối DB.
- ✅ **Datasources**: Hỗ trợ sẵn các cấu hình và lớp kết nối cho PostgreSQL và Redis.
- ✅ **Redis Helpers**: Tiện ích giúp tương tác với Redis một cách dễ dàng và hiệu quả.
- ✅ **Common Utilities**: Tập hợp các hàm tiện ích cho Crypto, Date, Error, Promises, Query Builder, URL, v.v.
- ✅ **LoopBack 4 Overrides**: Re-export và tùy chỉnh các module cốt lõi của LoopBack 4 (@lb/auth, @lb/core, @lb/rest, @lb/repo).

---

## Cài đặt

Sử dụng `bun` hoặc `npm`/`yarn`:

```bash
bun add @gennext/lb-infra
```

---

## Hướng dẫn sử dụng

### 1. Cấu hình Logger

Hệ thống logger hỗ trợ hai chế độ: `legacy` (tương thích ngược) và `modern`. Bạn nên cấu hình logger ngay khi khởi tạo ứng dụng.

```typescript
import { LoggerFactory } from '@gennext/lb-infra';

// Cấu hình toàn cục (thực hiện một lần tại entry point)
LoggerFactory.config({
  mode: 'modern',
  defaultDataMasking: {
    useMaskdataLib: true,
    maskdataOptions: {
      genericStrings: [
        {
          config: { maskWith: '*', fixedOutputLength: 8 },
          fields: ['*password', '*secret', '*token'],
        },
      ],
    },
  },
  defaultRequestIDSystem: 'asyncLocalStorage',
  defaultLogFormat: 'modern',
});

const logger = LoggerFactory.getLogger(['UserModule']);
logger.info('Ứng dụng đã khởi chạy thành công');
```

### 2. Sử dụng Base Model

Kế thừa các lớp cơ sở để chuẩn hóa các Entity trong LoopBack 4.

```typescript
import { BaseNumberIdEntity } from '@gennext/lb-infra';
import { property } from '@loopback/repository';

export class User extends BaseNumberIdEntity {
  @property({ type: 'string', required: true })
  username: string;

  @property({ type: 'string' })
  email?: string;
}
```

### 3. Kết nối PostgreSQL

`PostgresDataSource` tự động đọc cấu hình từ biến môi trường.

```typescript
import { PostgresDataSource } from '@gennext/lb-infra';

// Tự động kết nối dựa trên APP_ENV_POSTGRES_* env
const dataSource = new PostgresDataSource();
```

### 4. Sử dụng Redis Helper

```typescript
import { RedisHelper } from '@gennext/lb-infra';

const redis = new RedisHelper({
  name: 'my-redis',
  host: 'localhost',
  port: 6379,
  password: 'your-password'
});

await redis.set('key', 'value');
const val = await redis.get('key');
```

### 5. Sử dụng Common Utilities

```typescript
import { cryptoUtility, dateUtility, queryUtility } from '@gennext/lb-infra';

// Crypto
const hash = cryptoUtility.md5('password');

// Date
const now = dateUtility.now();

// Query Utility
const tableDef = queryUtility.getTableDefinition({ model: User });
```

---

## Cấu hình Biến môi trường (Environment Variables)

Thư viện hỗ trợ các biến môi trường sau để cấu hình Datasource:

### PostgreSQL
- `APP_ENV_POSTGRES_HOST`: Host của DB (mặc định: `0.0.0.0`)
- `APP_ENV_POSTGRES_PORT`: Port (mặc định: `5432`)
- `APP_ENV_POSTGRES_USERNAME`: Username (mặc định: `postgres`)
- `APP_ENV_POSTGRES_PASSWORD`: Password (mặc định: `password`)
- `APP_ENV_POSTGRES_DATABASE`: Database name (mặc định: `postgres`)

### Logger
- `APP_ENV_ENABLE_ACCESS_LOG`: Bật/tắt log truy cập (true/false)
- `APP_ENV_LOG_FORMAT`: Định dạng log (`legacy` hoặc `modern`)

---

## Tài liệu chi tiết

Xem thêm các hướng dẫn chi tiết tại thư mục `docs/`:

- [Cấu hình hệ thống Logger](./docs/CONFIG_USAGE.md)
- [Hướng dẫn Logger nâng cao](./docs/ENHANCED_LOGGER_USAGE.md)
- [Chi tiết về infra](./docs/lb-infra.md)

---

## Liên hệ
**Gennex Technology Team**