@bts-soft/core 1.0.4 → 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.
Files changed (3) hide show
  1. package/README.md +159 -59
  2. package/package.json +3 -2
  3. 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
- ## @bts-soft/core | The BTS Software Core Toolkit
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
- The **`@bts-soft/core`** package serves as the unified entry point for all high-quality, pre-configured modules developed by BTS Software.
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 all the following specialized modules and services:
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 required peer dependencies (BullMQ, Nodemailer, etc. are installed automatically as dependencies of `@bts-soft/mail-queue`):
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 primarily by the `mail-queue` module):
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 `AppModule`
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
- // Import all modules and services from the unified Core package
50
- import { EmailModule } from '@bts-soft/core';
51
-
44
+ import { EmailModule, ConfigModule } from '@bts-soft/core';
45
+
52
46
  @Module({
53
-   imports: [
54
-     // Example: Registering the Email Module
55
-     EmailModule.register({ 
56
-       // Optional: Custom connection settings can be passed here
57
-     }),
58
-     // ... Other application modules
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 services (like the email sender) by importing them directly from the core package:
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'; // Imported from @bts-soft/core
75
-
64
+ import { SendEmailService } from '@bts-soft/core';
65
+
76
66
  @Injectable()
77
67
  export class MyService {
78
- constructor(private readonly emailService: SendEmailService) {}
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
- async handleSignup(user: any) {
81
- // Logic...
84
+ This approach ensures:
85
+
86
+ - **Consistency** across projects     
82
87
 
83
- // Queue the email job
84
- await this.emailService.sendEmail(
85
- user.email,
86
- 'Welcome!',
87
- 'Thanks for signing up to our platform.'
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
- ## Contact
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
- **Author:** Omar Sabry  
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
- **Email:** omar.sabry.dev@gmail.com  
135
+ Then you can access everything from one place:
103
136
 
104
- **LinkedIn:** [(1) Omar Sabry | LinkedIn](https://www.linkedin.com/in/omarsa6ry/)
137
+ ```
138
+ import {
139
+   EmailModule,
140
+   SendEmailService,
141
+   ConfigModule,
142
+   ValidationModule,
143
+   IdField,
144
+   TextField,
145
+ } from '@bts-soft/core';
146
+ ```
105
147
 
106
- Portfolio: https://omarsabry.netlify.app/
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
- ## Repository
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 at main · Omar-Sa6ry/bts-soft](https://github.com/Omar-Sa6ry/bts-soft/tree/main/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/package.json CHANGED
@@ -1,13 +1,14 @@
1
1
  {
2
2
  "name": "@bts-soft/core",
3
- "version": "1.0.4",
3
+ "version": "1.1.4",
4
4
  "author": "Omar Sabry",
5
5
  "description": "All bts-soft packages",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
8
8
  "license": "MIT",
9
9
  "dependencies": {
10
- "@bts-soft/mail-queue": "^1.0.5"
10
+ "@bts-soft/mail-queue": "^1.0.5",
11
+ "@bts-soft/validation":"^1.0.0"
11
12
  },
12
13
  "peerDependencies": {
13
14
  "@nestjs/common": "^10.0.0",
package/src/index.ts CHANGED
@@ -1,4 +1,5 @@
1
- // packages/nestjs-core/src/index.ts
1
+ // Mail Queue Module
2
+ export * from '@bts-soft/mail-queue';
2
3
 
3
- // Mail Queue Module)
4
- export * from '@bts-soft/mail-queue';
4
+ // Validation Decorators
5
+ export * from '@bts-soft/validation';