@gennext/lb-infra 0.0.11 → 0.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +73 -82
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,146 +1,137 @@
1
1
  # @gennext/lb-infra
2
2
 
3
- `@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.
3
+ Thư viện hạ tầng dùng chung cho các dự án backend LoopBack 4 tại Gennex.
4
+ Package này gom các thành phần cốt lõi để chuẩn hóa cách viết service:
4
5
 
5
- ## Tính năng chính
6
+ - Base model và base datasource
7
+ - Datasource cho PostgreSQL và Redis
8
+ - Logger mở rộng (masking, request id, access log)
9
+ - Redis helpers
10
+ - Utility functions dùng chung
11
+ - Re-export các module LoopBack thường dùng
6
12
 
7
- - ✅ **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.
8
- - ✅ **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.
9
- - ✅ **Datasources**: Hỗ trợ sẵn các cấu hình và lớp kết nối cho PostgreSQL và Redis.
10
- - ✅ **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ả.
11
- - ✅ **Common Utilities**: Tập hợp các hàm tiện ích cho Crypto, Date, Error, Promises, Query Builder, URL, v.v.
12
- - ✅ **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).
13
+ ## Yêu cầu
13
14
 
14
- ---
15
+ - Node.js >= 18
15
16
 
16
17
  ## Cài đặt
17
18
 
18
- Sử dụng `bun` hoặc `npm`/`yarn`:
19
-
20
19
  ```bash
21
20
  bun add @gennext/lb-infra
22
21
  ```
23
22
 
24
- ---
23
+ Hoặc:
25
24
 
26
- ## Hướng dẫn sử dụng
25
+ ```bash
26
+ npm install @gennext/lb-infra
27
+ ```
27
28
 
28
- ### 1. Cấu hình Logger
29
+ ## Sử dụng nhanh
29
30
 
30
- 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.
31
+ ### 1. Logger
31
32
 
32
- ```typescript
33
+ ```ts
33
34
  import { LoggerFactory } from '@gennext/lb-infra';
34
35
 
35
- // Cấu hình toàn cục (thực hiện một lần tại entry point)
36
36
  LoggerFactory.config({
37
37
  mode: 'modern',
38
+ defaultRequestIDSystem: 'asyncLocalStorage',
39
+ defaultLogFormat: 'modern',
38
40
  defaultDataMasking: {
39
41
  useMaskdataLib: true,
40
- maskdataOptions: {
41
- genericStrings: [
42
- {
43
- config: { maskWith: '*', fixedOutputLength: 8 },
44
- fields: ['*password', '*secret', '*token'],
45
- },
46
- ],
47
- },
48
42
  },
49
- defaultRequestIDSystem: 'asyncLocalStorage',
50
- defaultLogFormat: 'modern',
51
43
  });
52
44
 
53
- const logger = LoggerFactory.getLogger(['UserModule']);
54
- logger.info('Ứng dụng đã khởi chạy thành công');
45
+ const logger = LoggerFactory.getLogger(['user-service']);
46
+ logger.info('Service started');
55
47
  ```
56
48
 
57
- ### 2. Sử dụng Base Model
49
+ ### 2. Base model
58
50
 
59
- Kế thừa các lớp cơ sở để chuẩn hóa các Entity trong LoopBack 4.
60
-
61
- ```typescript
51
+ ```ts
62
52
  import { BaseNumberIdEntity } from '@gennext/lb-infra';
63
53
  import { property } from '@loopback/repository';
64
54
 
65
55
  export class User extends BaseNumberIdEntity {
66
56
  @property({ type: 'string', required: true })
67
57
  username: string;
68
-
69
- @property({ type: 'string' })
70
- email?: string;
71
58
  }
72
59
  ```
73
60
 
74
- ### 3. Kết nối PostgreSQL
75
-
76
- `PostgresDataSource` tự động đọc cấu hình từ biến môi trường.
61
+ ### 3. Datasource
77
62
 
78
- ```typescript
79
- import { PostgresDataSource } from '@gennext/lb-infra';
63
+ ```ts
64
+ import { PostgresDataSource, RedisDataSource } from '@gennext/lb-infra';
80
65
 
81
- // Tự động kết nối dựa trên APP_ENV_POSTGRES_* env
82
- const dataSource = new PostgresDataSource();
66
+ const postgres = new PostgresDataSource();
67
+ const redis = new RedisDataSource();
83
68
  ```
84
69
 
85
- ### 4. Sử dụng Redis Helper
70
+ ### 4. Redis helper
86
71
 
87
- ```typescript
72
+ ```ts
88
73
  import { RedisHelper } from '@gennext/lb-infra';
89
74
 
90
- const redis = new RedisHelper({
91
- name: 'my-redis',
92
- host: 'localhost',
75
+ const cache = new RedisHelper({
76
+ name: 'cache',
77
+ host: '127.0.0.1',
93
78
  port: 6379,
94
- password: 'your-password'
95
79
  });
96
80
 
97
- await redis.set('key', 'value');
98
- const val = await redis.get('key');
81
+ await cache.set('health', 'ok');
99
82
  ```
100
83
 
101
- ### 5. Sử dụng Common Utilities
84
+ ## Environment variables
102
85
 
103
- ```typescript
104
- import { cryptoUtility, dateUtility, queryUtility } from '@gennext/lb-infra';
86
+ ### PostgreSQL datasource
105
87
 
106
- // Crypto
107
- const hash = cryptoUtility.md5('password');
88
+ - APP_ENV_DATASOURCE_NAME (default: postgres)
89
+ - APP_ENV_POSTGRES_HOST (default: 0.0.0.0)
90
+ - APP_ENV_POSTGRES_PORT (default: 5432)
91
+ - APP_ENV_POSTGRES_USERNAME (default: postgres)
92
+ - APP_ENV_POSTGRES_PASSWORD (default: password)
93
+ - APP_ENV_POSTGRES_DATABASE (default: postgres)
108
94
 
109
- // Date
110
- const now = dateUtility.now();
95
+ ### Redis datasource
111
96
 
112
- // Query Utility
113
- const tableDef = queryUtility.getTableDefinition({ model: User });
114
- ```
115
-
116
- ---
97
+ - APP_ENV_REDIS_DATASOURCE_NAME (default: redis)
98
+ - APP_ENV_REDIS_DATASOURCE_HOST (default: 0.0.0.0)
99
+ - APP_ENV_REDIS_DATASOURCE_PORT (default: 6379)
100
+ - APP_ENV_REDIS_DATASOURCE_PASSWORD (default: password)
117
101
 
118
- ## Cấu hình Biến môi trường (Environment Variables)
102
+ ## Cấu trúc module export
119
103
 
120
- Thư viện hỗ trợ các biến môi trường sau để cấu hình Datasource:
104
+ Package root export các nhóm sau:
121
105
 
122
- ### PostgreSQL
123
- - `APP_ENV_POSTGRES_HOST`: Host của DB (mặc định: `0.0.0.0`)
124
- - `APP_ENV_POSTGRES_PORT`: Port (mặc định: `5432`)
125
- - `APP_ENV_POSTGRES_USERNAME`: Username (mặc định: `postgres`)
126
- - `APP_ENV_POSTGRES_PASSWORD`: Password (mặc định: `password`)
127
- - `APP_ENV_POSTGRES_DATABASE`: Database name (mặc định: `postgres`)
106
+ - base
107
+ - common
108
+ - datasources
109
+ - helpers
110
+ - utilities
128
111
 
129
- ### Logger
130
- - `APP_ENV_ENABLE_ACCESS_LOG`: Bật/tắt log truy cập (true/false)
131
- - `APP_ENV_LOG_FORMAT`: Định dạng log (`legacy` hoặc `modern`)
112
+ Ngoài ra package còn export các alias cho LoopBack modules qua package exports:
132
113
 
133
- ---
114
+ - ./lb-auth và ./@lb/auth
115
+ - ./lb-core và ./@lb/core
116
+ - ./lb-rest và ./@lb/rest
117
+ - ./lb-repo và ./@lb/repo
134
118
 
135
119
  ## Tài liệu chi tiết
136
120
 
137
- Xem thêm các hướng dẫn chi tiết tại thư mục `docs/`:
121
+ - [docs/README.md](docs/README.md)
122
+ - [docs/lb-infra.md](docs/lb-infra.md)
123
+ - [docs/infra.md](docs/infra.md)
124
+ - [docs/CONFIG_USAGE.md](docs/CONFIG_USAGE.md)
125
+ - [docs/ENHANCED_LOGGER_USAGE.md](docs/ENHANCED_LOGGER_USAGE.md)
126
+
127
+ ## Scripts cho maintainer
138
128
 
139
- - [Cấu hình hệ thống Logger](./docs/CONFIG_USAGE.md)
140
- - [Hướng dẫn Logger nâng cao](./docs/ENHANCED_LOGGER_USAGE.md)
141
- - [Chi tiết về infra](./docs/lb-infra.md)
129
+ - bun run build
130
+ - bun run clean
131
+ - bun run rebuild
132
+ - bun run test
133
+ - bun run lint
142
134
 
143
- ---
135
+ ## License
144
136
 
145
- ## Liên hệ
146
- **Gennex Technology Team**
137
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gennext/lb-infra",
3
- "version": "0.0.11",
3
+ "version": "0.0.12",
4
4
  "dependencies": {
5
5
  "@gennext/dev-configs": "^0.0.3",
6
6
  "@loopback/authentication": "^12.0.6",