@bts-soft/core 2.4.6 → 2.4.8

package/README.md

@@ -1,5 +1,10 @@
 # @bts-soft/core
 
+![NestJS](https://img.shields.io/badge/NestJS-%3E%3D11.0.0-E0234E?style=flat-square&logo=nestjs)
+![Node](https://img.shields.io/badge/Node-%3E%3D20.17.0-339933?style=flat-square&logo=node.js)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.5-3178C6?style=flat-square&logo=typescript)
+![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)
+
 ## The Definitive Enterprise Meta-Framework for NestJS
 
 `@bts-soft/core` is not just a package; it is the architectural backbone of the BTS Soft enterprise ecosystem. It streamlines the development of high-performance, secure, and scalable NestJS applications by consolidating five specialized packages into a unified, high-level API.
@@ -8,6 +13,82 @@ This documentation serves as the comprehensive technical manual for the entire c
 
 ---
 
+## Table of Contents
+- [Installation \& Quick Start](#installation--quick-start)
+- [Core Vision \& Architecture](#core-vision--architecture)
+- [Module Index](#module-index)
+- [Deep Dive: @bts-soft/validation](#deep-dive-bts-softvalidation)
+- [Deep Dive: @bts-soft/cache](#deep-dive-bts-softcache)
+- [Deep Dive: @bts-soft/notifications](#deep-dive-bts-softnotifications)
+- [Deep Dive: @bts-soft/upload](#deep-dive-bts-softupload)
+- [Deep Dive: @bts-soft/common](#deep-dive-bts-softcommon)
+- [Security Audit \& Hardening Guide](#security-audit--hardening-guide)
+- [Deployment, CI/CD, and Operations](#deployment-cicd-and-operations)
+- [The Giant Book of Usage Examples](#the-giant-book-of-usage-examples)
+- [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
+- [Exhaustive Redis API Guide](#exhaustive-redis-api-guide)
+
+---
+
+## Installation & Quick Start
+
+### 1. Install the Package
+
+```bash
+npm install @bts-soft/core
+```
+
+*Note: `@bts-soft/core` requires `Node.js >= 20.17.0` and has peer dependencies on `@nestjs/common` and `@nestjs/core` (v11+).*
+
+### 2. Basic Integration
+
+Import the individual modules provided by `@bts-soft/core` into your `AppModule` or use them as needed:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { 
+  ConfigModule, 
+  GraphqlModule, 
+  ThrottlingModule 
+} from '@bts-soft/core';
+
+@Module({
+  imports: [
+    ConfigModule,
+    ThrottlingModule,
+    GraphqlModule,
+    // Add other core modules like RedisModule, UploadModule, etc. as needed
+  ],
+})
+export class AppModule {}
+```
+
+### 3. Bootstrap Utilities
+
+In your `main.ts`, utilize the core infrastructure to set up global interceptors and launch banners:
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { setupInterceptors, displayAppBanner } from '@bts-soft/core';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  
+  // Apply standard BTS-Soft global interceptors (Serialization, SQLi Protection, Formatting)
+  setupInterceptors(app);
+  
+  const port = process.env.PORT || 3000;
+  await app.listen(port);
+  
+  // Display the professional terminal banner
+  displayAppBanner('My Service', port);
+}
+bootstrap();
+```
+
+---
+
 ## Core Vision & Architecture
 
 The primary objective of `@bts-soft/core` is to eliminate "infrastructure boilerplate." Instead of configuring Redis, Cloudinary, BullMQ, and Nodemailer repeatedly for every microservice, developers can import a single module that provides pre-validated, secure, and performant implementations of these essential services.
@@ -299,10 +380,10 @@ By calling `setupInterceptors(app)` in your `main.ts`, you enable a powerful sui
     Uses `class-transformer` to filter out sensitive fields (marked with `@Exclude()`) and include computed properties (marked with `@Expose()`).
     
 2.  **`SqlInjectionInterceptor`**: 
-    A global scanner that intercepts all incoming request payloads (Body, Query, Params) and checks every string against the `SQL_INJECTION_REGEX`. If a violation is caught, it automatically throws a `400 Bad Request` before the controller logic is executed.
+    A global scanner that intercepts all incoming request payloads (Body, Query, Params) and checks every string against a predefined regex. If a violation is caught, it automatically throws a `400 Bad Request` before the controller logic is executed.
 
 3.  **`GeneralResponseInterceptor`**: 
-    The most visible part of the common module. It ensures that every response, whether it's a single entity, a list, or an error, follows the exact same JSON structure.
+    Ensures that every REST response follows the exact same JSON structure. For GraphQL, it automatically skips formatting to preserve schema integrity while still allowing for global error handling.
 
 #### The Standard Response Envelope
 ```json
@@ -326,25 +407,37 @@ By calling `setupInterceptors(app)` in your `main.ts`, you enable a powerful sui
 ### Shared Base Classes
 
 #### 1. `BaseEntity` (The Persistence Foundation)
-All database entities in the system should extend `BaseEntity`. 
+All database entities in the system should extend a specialized base class. 
 
-- **ULID Integration**: Instead of predictable numeric IDs, it uses **ULIDs** (Universally Unique Lexicographically Sortable Identifiers). These are 26-character strings that are both unique and sortable by creation time.
+- **ULID Integration**: Instead of predictable numeric IDs, it uses ULIDs (Universally Unique Lexicographically Sortable Identifiers) which are both unique and sortable.
 - **Audit Trails**: Automatically generates `createdAt` and `updatedAt` timestamps.
-- **Lifecycle Hooks**: Includes pre-configured `AfterInsert`, `AfterUpdate`, and `BeforeRemove` logging to help with debugging database interactions in production.
+- **Multi-ORM Support**: Includes dedicated bases for TypeORM, Sequelize, Mongoose, Prisma, and GraphQL.
 
 #### 2. `BaseResponse` (The API Contract)
-Used as a base class for DTOs and GraphQL Object Types to ensure consistency in manual response construction.
+Used as a base class for DTOs and GraphQL Object Types to ensure consistency in response construction.
 
 ---
 
 ### Infrastructure Modules
 
-The common package also provides pre-configured NestJS modules:
+The common package provides pre-configured NestJS modules:
 
 - **`ConfigModule`**: A wrapper around `@nestjs/config` with built-in validation.
-- **`ThrottlingModule`**: Pre-configured rate limiting to prevent Brute-Force and DDoS attacks.
+- **`ThrottlingModule`**: Robust rate limiting that automatically handles both HTTP and GraphQL contexts.
 - **`TranslationModule`**: Integrated `nestjs-i18n` support for multi-language applications (Arabic/English).
-- **`GraphqlModule`**: The standard Apollo Server setup with custom error filters that bridge the gap between GraphQL and HTTP status codes.
+- **`GraphqlModule`**: Standard Apollo Server setup with custom error filters and a context that includes both request and response objects.
+
+---
+
+### Production & CLI Utilities
+
+The common package exposes tools to manage environment-specific behaviors:
+
+- **`disableConsoleInProduction()`**: A safety utility to mute all `console` outputs when running in production.
+- **`displayAppBanner(appName, port)`**: Displays a clean, professional banner in the terminal when the server starts.
+
+---
+
 
 ---
 
@@ -503,6 +596,12 @@ The Upload module provides:
 - Size caps to prevent Disk Exhaustion attacks.
 - Strategy-level validation to ensure the cloud provider is reputable and secure.
 
+### 5. Production Optimization & Information Leakage Prevention
+
+To prevent sensitive data from leaking into server logs (such as tokens, passwords, or PII mistakenly logged during development), the `@bts-soft/core` meta-package **automatically disables all `console.*` methods** (e.g., `console.log`, `console.error`) the moment it is imported, provided that `process.env.NODE_ENV === "production"`.
+
+If your production environment requires structured logging, you should use the NestJS `Logger` class or a dedicated logging transport instead of native `console` methods.
+
 ---
 
 ## Deployment, CI/CD, and Operations

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export * from '@bts-soft/notifications';
-export * from '@bts-soft/cache';
-export * from '@bts-soft/upload';
-export * from '@bts-soft/validation';
-export * from '@bts-soft/common';
+export * from "@bts-soft/notifications";
+export * from "@bts-soft/cache";
+export * from "@bts-soft/upload";
+export * from "@bts-soft/validation";
+export * from "@bts-soft/common";

package/dist/index.js

@@ -19,4 +19,12 @@ __exportStar(require("@bts-soft/cache"), exports);
 __exportStar(require("@bts-soft/upload"), exports);
 __exportStar(require("@bts-soft/validation"), exports);
 __exportStar(require("@bts-soft/common"), exports);
+if (process.env.NODE_ENV === "production") {
+    const noop = () => { };
+    console.log = noop;
+    console.error = noop;
+    console.warn = noop;
+    console.info = noop;
+    console.debug = noop;
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,0DAAwC;AAGxC,kDAAgC;AAGhC,mDAAiC;AAGjC,uDAAqC;AAGrC,mDAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AACA,0DAAwC;AAGxC,kDAAgC;AAGhC,mDAAiC;AAGjC,uDAAqC;AAGrC,mDAAiC;AAEjC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IACnB,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IACpB,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IACpB,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;AACvB,CAAC"}