@bts-soft/core 1.0.3 → 1.1.4
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.
- package/README.md +159 -59
- package/license +19 -0
- package/package.json +6 -2
- package/src/index.ts +4 -3
package/README.md
CHANGED
|
@@ -1,29 +1,24 @@
|
|
|
1
|
+
# @bts-soft/core | The BTS Software Core Toolkit
|
|
1
2
|
|
|
2
|
-
|
|
3
|
+
The **`@bts-soft/core`** package serves as the unified entry point for all high-quality, pre-configured modules developed by **BTS Software**.
|
|
3
4
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
This package simplifies development by bundling essential backend components (like email queuing, security guards, and utilities) into one dependency, ensuring a consistent and robust NestJS architecture out-of-the-box.
|
|
7
|
-
|
|
8
|
-
---
|
|
5
|
+
This package simplifies development by bundling essential backend components (like email queuing, configuration management, and validation utilities) into one dependency, ensuring a consistent and robust **NestJS** architecture out-of-the-box.
|
|
9
6
|
|
|
10
7
|
## Features and Included Modules
|
|
11
8
|
|
|
12
|
-
By installing `@bts-soft/core`, you automatically gain access to
|
|
13
|
-
|
|
14
|
-
| Module | NPM Package (Internal) | Description |
|
|
15
|
-
| --------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
|
|
16
|
-
| **Email Queue** | `@bts-soft/mail-queue` | Reliable, asynchronous email sending using BullMQ and Nodemailer, preventing request blocking. |
|
|
17
|
-
|
|
9
|
+
By installing `@bts-soft/core`, you automatically gain access to the following specialized modules and services:
|
|
18
10
|
|
|
19
|
-
|
|
11
|
+
|Module|NPM Package (Internal)|Description|
|
|
12
|
+
|---|---|---|
|
|
13
|
+
|**Email Queue**|`@bts-soft/mail-queue`|Reliable, asynchronous email sending using **BullMQ** and **Nodemailer**, preventing request blocking.|
|
|
14
|
+
|**Validation Toolkit**|`@bts-soft/validation`|Powerful, region-aware decorators for secure, consistent DTO validation.|
|
|
15
|
+
|**Config Module**|`@bts-soft/config`|Global, cached, and environment-based configuration loading.|
|
|
20
16
|
|
|
21
17
|
## Getting Started
|
|
22
18
|
|
|
23
19
|
### 1. Installation
|
|
24
20
|
|
|
25
|
-
Install the core package and its
|
|
26
|
-
|
|
21
|
+
Install the core package and its peer dependencies:
|
|
27
22
|
|
|
28
23
|
```
|
|
29
24
|
npm install @bts-soft/core
|
|
@@ -31,86 +26,191 @@ npm install @bts-soft/core
|
|
|
31
26
|
|
|
32
27
|
### 2. Configuration (Environment Variables)
|
|
33
28
|
|
|
34
|
-
Your application must define the following environment variables (required
|
|
29
|
+
Your application must define the following environment variables (required by mail-queue and config modules):
|
|
35
30
|
|
|
36
31
|
|Variable|Usage|
|
|
37
32
|
|---|---|
|
|
38
33
|
|`REDIS_HOST`, `REDIS_PORT`|Required for BullMQ queue management.|
|
|
39
34
|
|`MAIL_HOST`, `MAIL_USER`, `MAIL_PASS`|Required for Nodemailer SMTP connection.|
|
|
35
|
+
|`NODE_ENV`|Used by ConfigModule to determine which `.env` file to load.|
|
|
40
36
|
|
|
41
|
-
### 3. Usage in
|
|
42
|
-
|
|
43
|
-
All modules are designed to be imported directly from the `@bts-soft/core` package.
|
|
37
|
+
### 3. Usage in AppModule
|
|
44
38
|
|
|
39
|
+
All modules are designed to be imported directly from `@bts-soft/core`.
|
|
45
40
|
|
|
46
41
|
```
|
|
47
42
|
// app.module.ts
|
|
48
43
|
import { Module } from '@nestjs/common';
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
44
|
+
import { EmailModule, ConfigModule } from '@bts-soft/core';
|
|
45
|
+
|
|
52
46
|
@Module({
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
],
|
|
60
|
-
// ...
|
|
47
|
+
imports: [
|
|
48
|
+
ConfigModule, // Global environment loader
|
|
49
|
+
EmailModule.register({
|
|
50
|
+
// Optional: Custom configuration overrides
|
|
51
|
+
}),
|
|
52
|
+
],
|
|
61
53
|
})
|
|
62
54
|
export class AppModule {}
|
|
63
55
|
```
|
|
64
56
|
|
|
65
|
-
### 4. Injecting Services
|
|
57
|
+
### 4. Injecting and Using Services
|
|
66
58
|
|
|
67
|
-
Access
|
|
68
|
-
|
|
69
|
-
TypeScript
|
|
59
|
+
Access any service directly from the core package:
|
|
70
60
|
|
|
71
61
|
```
|
|
72
62
|
// my.service.ts
|
|
73
63
|
import { Injectable } from '@nestjs/common';
|
|
74
|
-
import { SendEmailService } from '@bts-soft/core';
|
|
75
|
-
|
|
64
|
+
import { SendEmailService } from '@bts-soft/core';
|
|
65
|
+
|
|
76
66
|
@Injectable()
|
|
77
67
|
export class MyService {
|
|
78
|
-
|
|
68
|
+
constructor(private readonly emailService: SendEmailService) {}
|
|
69
|
+
|
|
70
|
+
async handleSignup(user: any) {
|
|
71
|
+
await this.emailService.sendEmail(
|
|
72
|
+
user.email,
|
|
73
|
+
'Welcome!',
|
|
74
|
+
'Thanks for signing up to our platform.'
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Architecture Overview
|
|
81
|
+
|
|
82
|
+
The **`@bts-soft/core`** package follows a **modular and scalable monorepo architecture**, designed to unify all backend modules under one shared entry point.
|
|
79
83
|
|
|
80
|
-
|
|
81
|
-
|
|
84
|
+
This approach ensures:
|
|
85
|
+
|
|
86
|
+
- **Consistency** across projects
|
|
82
87
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
88
|
+
- **Reusability** of core modules
|
|
89
|
+
|
|
90
|
+
- **Encapsulation** and clean module separation
|
|
91
|
+
|
|
92
|
+
- **Ease of expansion** for future internal packages
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
### Folder Structure
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
bts-soft/
|
|
99
|
+
├── packages/
|
|
100
|
+
│ ├── core/ # Main Core package (unified entry point)
|
|
101
|
+
│ │ ├── src/
|
|
102
|
+
│ │ │ ├── modules/
|
|
103
|
+
│ │ │ │ ├── email/ # Email Queue Module
|
|
104
|
+
│ │ │ │ ├── validation/ # Validation Module
|
|
105
|
+
│ │ │ │ ├── config/ # Config Loader
|
|
106
|
+
│ │ │ │ └── index.ts # Re-exports all submodules
|
|
107
|
+
│ │ │ ├── utils/ # Shared utilities
|
|
108
|
+
│ │ │ └── index.ts # Unified Core export
|
|
109
|
+
│ │ └── package.json
|
|
110
|
+
│ ├── mail-queue/ # BullMQ + Nodemailer integration
|
|
111
|
+
│ ├── validation/ # DTO and field decorators
|
|
112
|
+
│ └── config/ # Environment management
|
|
91
113
|
```
|
|
92
114
|
|
|
115
|
+
### Modular Design Philosophy
|
|
93
116
|
|
|
94
|
-
|
|
117
|
+
Each module in `@bts-soft/core` is designed to be:
|
|
95
118
|
|
|
96
|
-
|
|
119
|
+
|Principle|Description|
|
|
120
|
+
|---|---|
|
|
121
|
+
|**Isolated**|Each submodule (email, validation, config) is self-contained.|
|
|
122
|
+
|**Composable**|Modules can be imported individually or all together via Core.|
|
|
123
|
+
|**Extensible**|New modules (e.g. logger, cache) can be added easily.|
|
|
124
|
+
|**Global-ready**|Config and Validation can be registered globally.|
|
|
97
125
|
|
|
98
|
-
|
|
126
|
+
### Example: Unified Export (`index.ts`)
|
|
99
127
|
|
|
100
|
-
|
|
128
|
+
```
|
|
129
|
+
// packages/core/src/index.ts
|
|
130
|
+
export * from './modules/email';
|
|
131
|
+
export * from './modules/validation';
|
|
132
|
+
export * from './modules/config';
|
|
133
|
+
```
|
|
101
134
|
|
|
102
|
-
|
|
135
|
+
Then you can access everything from one place:
|
|
103
136
|
|
|
104
|
-
|
|
137
|
+
```
|
|
138
|
+
import {
|
|
139
|
+
EmailModule,
|
|
140
|
+
SendEmailService,
|
|
141
|
+
ConfigModule,
|
|
142
|
+
ValidationModule,
|
|
143
|
+
IdField,
|
|
144
|
+
TextField,
|
|
145
|
+
} from '@bts-soft/core';
|
|
146
|
+
```
|
|
105
147
|
|
|
106
|
-
|
|
148
|
+
### Internal Interaction Diagram
|
|
107
149
|
|
|
108
|
-
|
|
150
|
+
```
|
|
151
|
+
graph TD
|
|
152
|
+
A[@bts-soft/config] -->|Loads .env based on NODE_ENV| B
|
|
153
|
+
B[@bts-soft/mail-queue] -->|Uses Redis + SMTP configs| C
|
|
154
|
+
C[@bts-soft/validation] -->|Provides decorators and validators| D
|
|
155
|
+
D[Core Package: @bts-soft/core]
|
|
156
|
+
A --> D
|
|
157
|
+
B --> D
|
|
158
|
+
C --> D
|
|
159
|
+
style D fill:#f9f,stroke:#333,stroke-width:2px
|
|
160
|
+
```
|
|
109
161
|
|
|
110
|
-
|
|
162
|
+
The **Core package** (`@bts-soft/core`) re-exports them all, providing a **single point of access** for developers.
|
|
111
163
|
|
|
112
|
-
|
|
164
|
+
### Developer Workflow Example
|
|
113
165
|
|
|
114
|
-
|
|
166
|
+
1. Install one package: `npm install @bts-soft/core`
|
|
167
|
+
|
|
168
|
+
2. Import what you need: `import { ConfigModule, EmailModule, IdField } from '@bts-soft/core';`
|
|
169
|
+
|
|
170
|
+
3. Configure via `.env`: `NODE_ENV=development REDIS_HOST=localhost MAIL_USER=myapp@gmail.com`
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
Everything else works automatically
|
|
174
|
+
|
|
175
|
+
## Example: Config Module
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
import { Module } from '@nestjs/common';
|
|
179
|
+
import { ConfigModule as config } from '@nestjs/config';
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* @Module ConfigModule
|
|
183
|
+
* Handles environment variable management for consistent configuration
|
|
184
|
+
* across the entire monorepo.
|
|
185
|
+
*/
|
|
186
|
+
@Module({
|
|
187
|
+
imports: [
|
|
188
|
+
config.forRoot({
|
|
189
|
+
cache: true, // Cache .env values for better performance
|
|
190
|
+
isGlobal: true, // Makes it globally available across modules
|
|
191
|
+
envFilePath: `.env.${process.env.NODE_ENV || 'development'}`, // Dynamic file loading
|
|
192
|
+
}),
|
|
193
|
+
],
|
|
194
|
+
})
|
|
195
|
+
export class ConfigModule {}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
This ensures:
|
|
199
|
+
|
|
200
|
+
- All modules share the same `.env` configuration.
|
|
201
|
+
|
|
202
|
+
- The correct file is loaded automatically (`.env.development`, `.env.production`, etc).
|
|
203
|
+
|
|
204
|
+
- Performance is improved with caching.
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
## Contact
|
|
208
|
+
|
|
209
|
+
**Author:** Omar Sabry </br>
|
|
210
|
+
**Email:** [omar.sabry.dev@gmail.com](mailto:omar.sabry.dev@gmail.com "null") </br>
|
|
211
|
+
**LinkedIn:** [Omar Sabry | LinkedIn](https://www.linkedin.com/in/omarsa6ry/ "null") </br>
|
|
212
|
+
**Portfolio:** [Portfolio](https://omarsabry.netlify.app/ "null") </br>
|
|
213
|
+
|
|
214
|
+
## Repository
|
|
115
215
|
|
|
116
|
-
**GitHub:** [bts-soft/packages/core
|
|
216
|
+
**GitHub:** [bts-soft/packages/core · Omar-Sa6ry/bts-soft](https://github.com/Omar-Sa6ry/bts-soft/tree/main/packages/core "null")
|
package/license
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
Copyright (c) [2025] [BTS Software]
|
|
2
|
+
|
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
4
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
5
|
+
in the Software without restriction, including without limitation the rights
|
|
6
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
7
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
8
|
+
furnished to do so, subject to the following conditions:
|
|
9
|
+
|
|
10
|
+
The above copyright notice and this permission notice shall be included in all
|
|
11
|
+
copies or substantial portions of the Software.
|
|
12
|
+
|
|
13
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
14
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
15
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
16
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
17
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
18
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
19
|
+
SOFTWARE.
|
package/package.json
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bts-soft/core",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.4",
|
|
4
|
+
"author": "Omar Sabry",
|
|
5
|
+
"description": "All bts-soft packages",
|
|
4
6
|
"main": "dist/index.js",
|
|
5
7
|
"types": "dist/index.d.ts",
|
|
8
|
+
"license": "MIT",
|
|
6
9
|
"dependencies": {
|
|
7
|
-
"@bts-soft/mail-queue": "^1.0.
|
|
10
|
+
"@bts-soft/mail-queue": "^1.0.5",
|
|
11
|
+
"@bts-soft/validation":"^1.0.0"
|
|
8
12
|
},
|
|
9
13
|
"peerDependencies": {
|
|
10
14
|
"@nestjs/common": "^10.0.0",
|
package/src/index.ts
CHANGED