@gennext/lb-infra 0.0.9 → 0.0.11

package/README.md

@@ -0,0 +1,146 @@
+# @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**

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@gennext/lb-infra",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "dependencies": {
-    "@gennext/dev-configs": "^0.0.2",
+    "@gennext/dev-configs": "^0.0.3",
     "@loopback/authentication": "^12.0.6",
     "@loopback/authentication-jwt": "^0.16.6",
     "@loopback/authorization": "^0.16.5",
@@ -28,17 +28,17 @@
     "winston-transport": "^4.9.0"
   },
   "devDependencies": {
-    "@gennext/eslint-node": "^0.0.1",
+    "@gennext/eslint-node": "^0.0.2",
     "@types/lodash": "^4.17.23",
     "@types/multer": "^2.0.0",
-    "@types/node": "^24.7.2",
-    "eslint": "^9.36.0",
+    "@types/node": "25.6.0",
+    "eslint": "10.2.0",
     "prettier": "^3.6.2",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
     "tsc-alias": "^1.8.16",
     "tsconfig-paths": "^4.2.0",
-    "typescript": "~5.9.3"
+    "typescript": "6.0.2"
   },
   "exports": {
     ".": {
@@ -118,6 +118,7 @@
     "clean": "sh ./scripts/clean.sh",
     "rebuild": "sh ./scripts/rebuild.sh",
     "eslint": "eslint --report-unused-disable-directives .",
+    "test": "TS_NODE_PROJECT=tsconfig.test.json node --require ts-node/register/transpile-only --require tsconfig-paths/register --test \"tests/**/*.test.ts\"",
     "lint": "bun run eslint && bun run prettier:cli",
     "lint:fix": "bun run eslint --fix && bun run prettier:fix",
     "prettier:cli": "prettier \"**/*.{js,ts}\" -l",