@gennext/lb-infra 0.2.1 → 0.2.2

package/README.md

@@ -1,340 +1,200 @@
-# @gennext/lb-infra
+# 📘 Cẩm nang Kĩ thuật: @gennext/lb-infra
 
-Hệ thống thư viện hạ tầng (infrastructure) backend dựa trên TypeScript, tối ưu cho hiệu năng và tính chuẩn hóa.
-
-## 1. Giới thiệu
-`@gennext/lb-infra` là nền tảng xây dựng backend hiện đại tại Gennex, kết hợp các công nghệ:
-- **Hono**: Web framework siêu nhẹ, hỗ trợ TypeScript và OpenAPI native.
-- **Drizzle ORM**: ORM thế hệ mới, type-safe tuyệt đối cho PostgreSQL.
-- **Zod**: Thư viện validation và định nghĩa schema mạnh mẽ.
-- **Winston**: Hệ thống logging đa kênh (Console, File, UDP).
-
-**Khi nào nên dùng:** Phù hợp cho các dự án yêu cầu tốc độ phản hồi cao, cấu trúc mã nguồn tường minh (Controller-Service-Repository) và tự động hóa tài liệu API (Swagger/OpenAPI).
-
----
-
-## 2. Cài đặt
-
-Cài đặt package chính:
-```bash
-bun add @gennext/lb-infra
-```
-
-Các peer dependency cần thiết:
-```bash
-bun add hono @hono/zod-openapi zod drizzle-orm pg winston
-# Nếu dùng Auth/Authorization
-bun add jose casbin
-```
-
----
-
-## 3. Khởi tạo ứng dụng
-Sử dụng `BaseApplication` kết hợp với `bootMixin` để tự động quét và đăng ký các thành phần.
-
-```typescript
-import { BaseApplication, bootMixin, bootStrapApplication, IApplicationConfigs } from '@gennext/lb-infra';
-
-class OrderApplication extends bootMixin(BaseApplication) {
-  getAppInfo() {
-    return {
-      name: 'Order Service',
-      version: '1.0.0',
-    };
-  }
-}
-
-const configs: IApplicationConfigs = {
-  port: Number(process.env.PORT) || 3000,
-  path: { base: '/api' }
-};
-
-bootStrapApplication(OrderApplication, configs);
-```
+Hạ tầng Backend Hybrid chuẩn Gennex: Kết hợp sức mạnh kiến trúc của **LoopBack 4** và hiệu năng của **Hono/Drizzle**.
 
 ---
 
-## 4. Data layer
-Sử dụng Drizzle để định nghĩa schema và các Repository để thao tác dữ liệu.
-
-### Khai báo Drizzle Schema
-Sử dụng các helper trong `column-defs.ts` để chuẩn hóa cấu trúc bảng.
-
-```typescript
-import { pgTable, text, integer } from 'drizzle-orm/pg-core';
-import { generateIdColumnDefs, generateSoftDeleteColumnDefs, generateTzColumnDefs } from '@gennext/lb-infra';
-
-export const orders = pgTable('orders', {
-  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-  orderNumber: text('order_number').notNull(),
-  amount: integer('amount'),
-  ...generateTzColumnDefs(),
-  ...generateSoftDeleteColumnDefs(),
-});
-```
+## 🏗 1. Tổng quan kiến trúc & Cài đặt
 
-### Repositories
-Sử dụng `DefaultCrudRepository` hoặc `SoftDeletableRepository` để có sẵn các hàm CRUD.
+### 1.1 Hybrid Platform
+Thư viện cung cấp hai lộ trình phát triển:
+- **Hono Path (Modern):** Cho các service yêu cầu tốc độ cao, hỗ trợ OpenAPI native qua Zod.
+- **LoopBack Path (Standard):** Cho các ứng dụng phức tạp cần DI (Dependency Injection) và tính tương thích ngược.
 
-```typescript
-import { SoftDeletableRepository } from '@gennext/lb-infra';
-import { orders } from '../models/order.schema';
+### 1.2 Cấu trúc Export (Sub-paths)
+Được cấu hình trong `package.json`, giúp developer import sạch sẽ:
+- `@gennext/lb-infra`: Entry chính (Hono, Drizzle, Utilities).
+- `@gennext/lb-infra/lb-core`: LoopBack Core (Binding, Context, Metadata).
+- `@gennext/lb-infra/lb-rest`: LoopBack Rest (Decorators, Sequence).
+- `@gennext/lb-infra/lb-repo`: LoopBack Repository (Juggler, Filter).
+- `@gennext/lb-infra/socket-io`: WebSocket component.
+- `@gennext/lb-infra/grpc`: gRPC component.
 
-export class OrderRepository extends SoftDeletableRepository<typeof orders> {
-  constructor() {
-    super(orders);
-  }
-}
-```
+### 1.3 Pin Dependencies (Không cần cài thêm)
+Thư viện đã đóng gói sẵn và re-export các "vũ khí" sau:
+- **Framework:** `Hono`, `@hono/zod-openapi`, `zod`.
+- **Database:** `Drizzle ORM` (core + pg), `pg` (node-postgres).
+- **Utilities:** `axios`, `lodash`, `dayjs` (thông qua `date.utility`).
 
 ---
 
-## 5. Service layer
-Các service kế thừa `BaseService` và sử dụng `this.logger` (HFLogger pattern) để ghi log theo phương thức.
+## 🚀 2. Application Kernel
 
-```typescript
-import { BaseService } from '@gennext/lb-infra';
-
-export class OrderService extends BaseService {
-  async processOrder(orderId: string) {
-    const logger = this.logger.for('processOrder');
-    logger.info('Starting process', { orderId });
-    
-    try {
-      // Logic xử lý đơn hàng...
-    } catch (error) {
-      logger.error('Failed to process', error);
-      throw error;
-    }
-  }
-}
-```
-
----
-
-## 6. Controller & Routing
-Controller quản lý các route và tích hợp Zod để tự động tạo tài liệu OpenAPI qua `defineRoute` hoặc `bindRoute`.
+### 2.1 Khởi tạo với `BaseApplication`
+Mọi ứng dụng phải kế thừa từ class này.
 
-```typescript
-import { BaseController, controller } from '@gennext/lb-infra';
-import { z } from 'zod';
+**Interface `IApplicationConfigs`:**
+- `port`: (Bắt buộc) Cổng chạy server.
+- `host?`: Hostname (Mặc định `0.0.0.0`).
+- `path?`: `{ base: string, isStrict?: boolean }` - Prefix cho API.
+- `debug?`: `{ shouldShowRoutes?: boolean }` - In ra danh sách route khi startup.
 
-const OrderSchema = z.object({ 
-  id: z.string().uuid(), 
-  amount: z.number().min(1) 
-});
+**Vòng đời (Lifecycle) trong `start()`:**
+1. `preConfigure()`: Thiết lập biến môi trường, kết nối DB sớm.
+2. `setupMiddlewares()`: Đăng ký Logger, CORS, v.v.
+3. `boot()`: Tự động đăng ký Controllers/Services (khi dùng `bootMixin`).
+4. `postConfigure()`: Chạy các tác vụ sau khi server đã lắng nghe.
 
-@controller({ path: '/orders' })
-export class OrderController extends BaseController {
-  async binding() {
-    this.bindRoute({
-      configs: {
-        path: '/',
-        method: 'post',
-        request: { 
-          body: { content: { 'application/json': { schema: OrderSchema } } } 
-        },
-        responses: {
-          200: { 
-            description: 'Order created', 
-            content: { 'application/json': { schema: OrderSchema } } 
-          }
-        }
-      }
-    }).to({
-      handler: async (c) => {
-        const body = await c.req.json();
-        return c.json(body);
-      }
-    });
-  }
-}
-```
+### 2.2 Dependency Injection (DI)
+Hệ thống sử dụng Map-based Binding:
+- **Bind:** `app.bind({ key: 'services.UserService' }).toClass(UserService)`
+- **Get:** `const service = app.get<UserService>({ key: 'services.UserService' })`
+- **Namespaces:** Nên dùng `BindingNamespaces.SERVICE`, `.CONTROLLER`, `.REPOSITORY`, `.DATASOURCE`.
 
 ---
 
-## 7. DataSources
-Cấu hình kết nối cơ sở dữ liệu qua các class kế thừa.
+## 🪵 3. Hệ thống Logger & Context
 
-```typescript
-import { PostgresDataSource, RedisDataSource } from '@gennext/lb-infra/datasources';
+### 3.1 Logger nâng cao
+Được xây dựng trên Winston, hỗ trợ ghi log đa kênh.
 
-export class DbDataSource extends PostgresDataSource {
-  static dataSourceName = 'db';
-}
+**Các Method:**
+- `debug(msg, ...args)`: ⚠️ Chỉ hoạt động nếu `NODE_ENV` là local/dev/alpha... **VÀ** biến `DEBUG=true`.
+- `withScope(scope)`: Gắn prefix cho log.
+- `for(method)`: Child logger cho từng hàm cụ thể (có cache để tối ưu).
 
-export class CacheDataSource extends RedisDataSource {
-  static dataSourceName = 'redis';
-}
-```
+**UDP Logging (`DgramTransport`):**
+Gửi log qua socket UDP (ví dụ đến Logstash/Graylog).
+Cấu hình qua `IDgramTransportOptions`: `host`, `port`, `levels` (các mức log muốn gửi đi).
 
----
-
-## 8. Logger helper
-Hệ thống log mạnh mẽ hỗ trợ `RequestContext` để theo vết Request ID xuyên suốt các layer.
-
-```typescript
-import { LoggerFactory, RequestContext } from '@gennext/lb-infra';
-
-const logger = LoggerFactory.getLogger(['OrderModule']);
-
-// Sử dụng RequestContext để gắn ID tự động
-RequestContext.run({ requestId: 'req-123' }, () => {
-  logger.info('User action log'); // Log sẽ có prefix [req-123]
-});
-```
+### 3.2 RequestContext & HttpAccessLogger
+Dùng để theo vết request ID xuyên suốt các tầng.
+- **Tự động hóa:** Middleware tự lấy `x-request-id` từ header hoặc tự sinh mới.
+- **Data Masking:** Tự động ẩn thông tin nhạy cảm trong log: `authorization`, `cookie`, `session`, `password`.
 
 ---
 
-## 9. Redis helper
-Bộ công cụ hỗ trợ Redis String, Hash, JSON và Pub/Sub.
-
-```typescript
-import { RedisHelper } from '@gennext/lb-infra/helpers/redis';
-
-const redis = new RedisHelper({ host: 'localhost', port: 6379 });
+## 🗄️ 4. Data Layer (Drizzle ORM)
 
-await redis.set({ key: 'config', value: { theme: 'dark' } });
+### 4.1 Schema Helpers (`column-defs.ts`)
+Giúp định nghĩa bảng chuẩn Gennex:
+- `generateIdColumnDefs()`: Cột `id` (Serial hoặc UUID).
+- `generateTzColumnDefs()`: Cột `created_at`, `modified_at` tự động cập nhật.
+- `generateSoftDeleteColumnDefs()`: Cột `deleted_at`.
 
-// Thao tác với RedisJSON
-await redis.jSet({ 
-  key: 'user:data', 
-  path: '$', 
-  value: { settings: { lang: 'vi' } } 
-});
-
-const lang = await redis.jGet({ key: 'user:data', path: '$.settings.lang' });
-```
+### 4.2 Tầng Repository (Tiering)
+- **ReadableRepository**: Tìm kiếm cơ bản.
+- **DefaultCRUDRepository**: Thao tác Thêm/Sửa/Xóa.
+- **SoftDeletableRepository**: 💡 Tự động thêm điều kiện `deleted_at IS NULL` vào mọi câu query.
+  - `hardDeleteById()`: Xóa vĩnh viễn.
+  - `restore()`: Khôi phục bản ghi đã xóa.
 
 ---
 
-## 10. Authentication
-Tích hợp sẵn các chiến lược xác thực phổ biến.
+## ⚡ 5. Redis & Caching
 
-```typescript
-import { AuthenticateComponent, JwtStrategy } from '@gennext/lb-infra';
+### 5.1 RedisManager
+Quản lý tập trung các instance Redis. Hỗ trợ cả **Standalone** và **Cluster mode**.
 
-// Trong BaseApplication
-this.component(AuthenticateComponent);
-this.bind('authentication.strategies.jwt').toClass(JwtStrategy);
-```
+### 5.2 DefaultRedisHelper API
+- `set({ key, value, options: { ttl } })`: Lưu object (tự serialize JSON).
+- `getObject({ key })`: Lấy và tự parse JSON.
+- `publish({ topics, payload, useCompress })`: Pub/Sub có hỗ trợ nén zlib để tiết kiệm băng thông.
 
 ---
 
-## 11. Authorization
-Phân quyền dựa trên thuộc tính (RBAC/ABAC) sử dụng Casbin.
-
-```typescript
-import { AuthorizeComponent, DrizzleCasbinAdapter } from '@gennext/lb-infra';
-
-this.component(AuthorizeComponent);
-// Dùng DrizzleCasbinAdapter để lưu policy vào PostgreSQL
-```
-
----
+## 🌐 6. HTTP Layer (Hono + OpenAPI)
 
-## 12. Components tùy chọn
+### 6.1 BaseController
+Sử dụng `bindRoute` để có được sự hỗ trợ tuyệt đối từ TypeScript và tự sinh Swagger.
 
-### gRPC
 ```typescript
-import { BaseGrpcController } from '@gennext/lb-infra/components/grpc';
-
-export class UserGrpcController extends BaseGrpcController {
-  // Implement gRPC methods defined in proto
-}
+this.bindRoute({
+  configs: {
+    path: '/:id',
+    method: 'get',
+    request: { params: zod.object({ id: zod.string() }) },
+    responses: { 200: jsonResponse({ schema: UserSchema, description: 'User info' }) }
+  }
+}).to({
+  handler: async (c) => {
+    const id = c.req.param('id');
+    // ... logic
+  }
+});
 ```
 
-### Socket.IO
-Sử dụng `SocketIOServerHelper` để quản lý kết nối thời gian thực.
-
-### Health Check
-Tích hợp sẵn endpoint `/health` để monitor trạng thái hệ thống.
-
 ---
 
-## 13. Utilities
-Các hàm tiện ích tối ưu trong `src/utilities`:
+## 🧰 7. Bộ tiện ích (Utilities Deep Dive)
 
-- `getError(opts)`: Tạo error object chuẩn kèm `statusCode`.
-- `hash(text, opts)`: Hỗ trợ MD5, SHA256...
-- `safeParseJson(str)`: Parse JSON không lo crash.
-- `executePromiseWithLimit({ tasks, limit })`: Chạy batch tasks có giới hạn số lượng chạy song song.
-- `getDateTz()`: Lấy thời gian hiện tại theo múi giờ cấu hình.
-- `buildBatchUpdateQuery(table, data)`: Helper tạo câu lệnh cập nhật hàng loạt cho Drizzle.
+| Utility | Method tiêu biểu | Mô tả |
+| :--- | :--- | :--- |
+| **parse** | `getUID()`, `keysToCamel()`, `toBoolean()`, `int()`, `float()` | Xử lý kiểu dữ liệu và format key. |
+| **crypto** | `hashPassword()`, `comparePassword()`, `encrypt()`, `decrypt()` | Bảo mật mật khẩu và mã hóa AES. |
+| **error** | `getError()`, `ValidationError()`, `NotImplementedError()` | Tạo lỗi chuẩn hóa có Status Code. |
+| **model** | `buildRequestBody()`, `buildPaginationResponse()` | Tự động sinh OpenAPI schema từ Model. |
+| **promise** | `delay(ms)` | Hàm ngủ async. |
+| **axios** | `get()`, `post()`, `put()`, `del()` | Wrapper axios kèm xử lý lỗi chuẩn. |
 
 ---
 
-## 14. Base classes
-
-| Class | Thuộc tính/Phương thức có sẵn |
-| :--- | :--- |
-| `BaseHelper` | `this.logger` |
-| `BaseService` | `this.logger` (HFLogger), `this.get(key)` (DI) |
-| `BaseController` | `this.logger`, `this.bindRoute()`, `this.defineRoute()` |
-| `BaseDataSource` | `this.name`, `this.connector` |
-
----
+## 🔑 8. Auth & Security
 
-## 15. Biến môi trường
+### 8.1 Authentication
+- Đăng ký `AuthenticateComponent`.
+- Hỗ trợ `JwtStrategy` (đọc secret từ `APP_ENV_APPLICATION_SECRET`).
 
-| Tên biến | Mô tả | Giá trị mặc định |
-| :--- | :--- | :--- |
-| `APP_ENV_APPLICATION_NAME` | Tên ứng dụng xuất hiện trong log | `APP` |
-| `APP_ENV_POSTGRES_HOST` | Địa chỉ PostgreSQL | `localhost` |
-| `APP_ENV_POSTGRES_PORT` | Cổng PostgreSQL | `5432` |
-| `APP_ENV_POSTGRES_USERNAME` | Username DB | `postgres` |
-| `APP_ENV_POSTGRES_PASSWORD` | Password DB | `password` |
-| `APP_ENV_POSTGRES_DATABASE` | Tên Database | `postgres` |
-| `APP_ENV_REDIS_DATASOURCE_HOST` | Địa chỉ Redis | `0.0.0.0` |
-| `APP_ENV_REDIS_DATASOURCE_PORT` | Cổng Redis | `6379` |
-| `APP_ENV_LOGGER_FOLDER_PATH` | Đường dẫn lưu file log | `./logs` |
-| `DEBUG` | Kích hoạt log debug | `false` |
+### 8.2 Authorization (Casbin)
+⚠️ Cần cài `casbin`.
+- `CasbinDrizzleAdapter`: Lưu Policy vào bảng DB do Drizzle quản lý.
+- `CasbinEnforcer`: Check quyền bằng cú pháp: `enforcer.enforce(user, object, action)`.
 
 ---
 
-## 16. Ví dụ end-to-end: Order Service
+## 🧪 9. Ví dụ: Full User Flow
 
 ```typescript
-// --- 1. Model (order.schema.ts) ---
-export const orders = pgTable('orders', {
+// --- 1. Model ---
+export const users = pgTable('users', {
   ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-  item: text('item').notNull(),
-  ...generateTzColumnDefs()
+  email: text('email').notNull().unique(),
+  ...generateTzColumnDefs(),
+  ...generateSoftDeleteColumnDefs()
 });
 
-// --- 2. Repository (order.repository.ts) ---
-export class OrderRepository extends DefaultCrudRepository<typeof orders> {
-  constructor() { super(orders); }
+// --- 2. Repository ---
+export class UserRepository extends SoftDeletableRepository<typeof users> {
+  constructor() { super(users); }
 }
 
-// --- 3. Service (order.service.ts) ---
-export class OrderService extends BaseService {
-  async create(item: string) {
-    const repo = this.get<OrderRepository>('repositories.OrderRepository');
-    return repo.create({ item });
-  }
-}
-
-// --- 4. Controller (order.controller.ts) ---
-@controller({ path: '/orders' })
-export class OrderController extends BaseController {
+// --- 3. Controller ---
+@controller({ path: '/users' })
+export class UserController extends BaseController {
   async binding() {
     this.bindRoute({
-      path: '/', method: 'post',
-      responses: { 200: { description: 'Success' } }
+      configs: {
+        path: '/',
+        method: 'get',
+        responses: { 200: { description: 'List' } }
+      }
     }).to({
       handler: async (c) => {
-        const service = this.get<OrderService>('services.OrderService');
-        return c.json(await service.create('Product A'));
+        const repo = app.get<UserRepository>({ key: 'repositories.UserRepository' });
+        return c.json(await repo.findAll());
       }
     });
   }
 }
+```
 
-// --- 5. Application (main.ts) ---
-class OrderApp extends bootMixin(BaseApplication) {
-  getAppInfo() { return { name: 'OrderAPI', version: '1.0' }; }
-}
+---
 
-bootStrapApplication(OrderApp, { port: 8080 });
-```
+## 🛠️ 10. Scripts
+
+- `bun run build`: Build project (TSC + tsc-alias).
+- `bun run migrate:push`: Đẩy schema Drizzle lên Database.
+- `bun run lint`: Kiểm tra code style các file mới thay đổi.
+
+---
+© 2024 Gennex Technology. Toàn quyền bảo lưu.

package/dist/base/index.js

@@ -45,7 +45,7 @@ __exportStar(require("./drizzle"), exports);
 exports.drizzlePg = __importStar(require("./drizzle/pg"));
 // pg
 __exportStar(require("./pg"), exports);
-// ... existing exports
+// exports
 __exportStar(require("./base.helper"), exports);
 __exportStar(require("./datasources"), exports);
 __exportStar(require("./models"), exports);

package/dist/base/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/base/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO;AACP,+CAA+B;AAC/B,qDAAmC;AAEnC,UAAU;AACV,4CAA0B;AAC1B,0DAA0C;AAE1C,KAAK;AACL,uCAAqB;AAErB,uBAAuB;AACvB,gDAA8B;AAC9B,gDAA8B;AAC9B,2CAAyB;AACzB,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/base/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,OAAO;AACP,+CAA+B;AAC/B,qDAAmC;AAEnC,UAAU;AACV,4CAA0B;AAC1B,0DAA0C;AAE1C,KAAK;AACL,uCAAqB;AAErB,UAAU;AACV,gDAA8B;AAC9B,gDAA8B;AAC9B,2CAAyB;AACzB,+CAA6B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gennext/lb-infra",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "dependencies": {
     "@gennext/dev-configs": "^0.0.6",
     "@loopback/authentication": "^12.0.6",

package/dist/base/loopback/filter/index.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/base/loopback/filter/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/loopback/filter/index.ts"],"names":[],"mappings":""}

package/dist/base/loopback/filter/index.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-// export * from '@loopback/filter';
-// export type * from '@loopback/filter';
-//# sourceMappingURL=index.js.map

package/dist/base/loopback/filter/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/loopback/filter/index.ts"],"names":[],"mappings":";;AAAA,oCAAoC;AACpC,yCAAyC"}

package/dist/base/loopback/http-server/index.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/base/loopback/http-server/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/loopback/http-server/index.ts"],"names":[],"mappings":""}

package/dist/base/loopback/http-server/index.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-// export * from '@loopback/http-server';
-// export type * from '@loopback/http-server';
-//# sourceMappingURL=index.js.map

package/dist/base/loopback/http-server/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/loopback/http-server/index.ts"],"names":[],"mappings":";;AAAA,yCAAyC;AACzC,8CAA8C"}