nodejs-structure-cli 1.0.0

package/templates/common/README.md.ejs

@@ -0,0 +1,148 @@
+# <%= projectName %>
+
+![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)
+![License](https://img.shields.io/badge/License-ISC-blue.svg)
+<% if (language === 'TypeScript') { %>![TypeScript](https://img.shields.io/badge/Language-TypeScript-blue.svg)<% } else { %>![JavaScript](https://img.shields.io/badge/Language-JavaScript-yellow.svg)<% } %>
+<% if (includeSecurity) { %>
+[![Snyk Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/github/yourusername/<%= projectName %>?style=flat-square)](https://snyk.io/)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=<%= projectName %>&metric=alert_status)](https://sonarcloud.io/)
+<% } %>
+
+A production-ready Node.js microservice generated with **<%= architecture %>** and **<%= database %>**. 
+This project follows a strict **7-Step Production-Ready Process** to ensure quality and scalability from day one.
+
+---
+
+## 🚀 7-Step Production-Ready Process
+
+1.  **Initialize Git**: `git init` (Required for Husky hooks and security gates).
+2.  **Install Dependencies**: `npm install`.
+3.  **Configure Environment**: Copy `.env.example` to `.env`.
+4.  **Start Infrastructure**: `docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> kafka<% } %>`.
+5.  **Run Development**: `npm run dev`.
+6.  **Verify Standards**: `npm run lint` and `npm test` (Enforce 80% coverage).
+7.  **Build & Deploy**: `npm run build` followed by `npm run deploy` (via PM2).
+
+---
+
+## 🚀 Key Features
+
+-   **Architecture**: <%= architecture %> (<% if (architecture === 'Clean Architecture') { %>Domain, UseCases, Infrastructure<% } else { %>MVC Pattern<% } %>).
+-   **Database**: <%= database %> <% if (database !== 'None') { %>(via <%= database === 'MongoDB' ? 'Mongoose' : 'Sequelize' %>)<% } %>.
+-   **Security**: Helmet, CORS, Rate Limiting, HPP, Snyk SCA.
+-   **Quality**: 80%+ Test Coverage, Eslint, Prettier, Husky.
+-   **DevOps**: Multi-stage Docker, CI/CD ready (GitHub/GitLab/Jenkins).
+<% if (includeSecurity) { %>-   **Enterprise Hardening**: SonarCloud SAST, Security Policies.<% } %>
+
+## 📂 Project Structure
+
+The project follows **<%= architecture %>** principles.
+<% if (architecture === 'Clean Architecture') { -%>
+- **Domain**: Pure business logic (Entities/Interfaces).
+- **Use Case**: Application-specific business rules.
+- **Infrastructure**: External concerns (DB, Messaging, Caching).
+<% } else { -%>
+- **Model**: Database schemas and data logic.
+- **View**: Template engines or API responders.
+- **Controller**: Orchestrates flow between Model and View.
+<% } -%>
+
+---
+
+## 🛠️ Detailed Getting Started
+
+Follow the **🚀 7-Step Production-Ready Process** summary at the top, or follow these detailed instructions:
+
+### 1. Prerequisites
+-   Node.js (v18+)
+-   Docker & Docker Compose
+
+### 2. Environment Setup
+Copy the example environment file and adjust the values as needed:
+```bash
+cp .env.example .env
+```
+
+### 3. Infrastructure & App Launch
+```bash
+# Initialize Git for security hooks
+git init
+
+# Install dependencies
+npm install
+
+# Start required services
+docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> kafka<% } %>
+
+# Run the app in development mode
+npm run dev
+```
+
+### 4. Quality & Standards
+```bash
+# Lint & Format
+npm run lint
+npm run format
+
+# Run Unit/Integration Tests
+npm test
+npm run test:coverage
+```
+
+<% if (communication === 'Kafka') { -%>
+Microservices communication handled via **Kafka**.
+<% } else if (communication === 'GraphQL') { -%>
+API is exposed via **GraphQL**.
+The Apollo Sandbox UI for API exploration and documentation is available natively, fully embedded for offline development:
+- **URL**: `http://localhost:3000/graphql` (Dynamic based on PORT)
+If you are opening `http://localhost:3000/graphql` in your browser, you can directly run the following in the Apollo Sandbox UI:
+
+**Query to get all users:**
+```graphql
+query GetAllUsers {
+  getAllUsers {
+    id
+    name
+    email
+  }
+}
+```
+
+**Mutation to create a user:**
+```graphql
+mutation CreateUser {
+  createUser(name: "John Doe", email: "john@example.com") {
+    id
+    name
+    email
+  }
+}
+```
+<% } else { -%>
+API is exposed via **REST**.
+A Swagger UI for API documentation is available at:
+- **URL**: `http://localhost:3000/api-docs` (Dynamic based on PORT)
+
+### 🛣️ User Endpoints:
+- `GET /api/users`: List all users.
+- `POST /api/users`: Create a new user.
+- `PATCH /api/users/:id`: Partially update a user.
+- `DELETE /api/users/:id`: Delete a user (Soft Delete).
+<%_ } -%>
+
+## 🐳 Docker Deployment
+This project uses a **Multi-Stage Dockerfile** for optimized production images.
+
+<% if (database !== 'None' || caching === 'Redis' || communication === 'Kafka') { -%>
+### 1. Running Locally (Development)
+To run the Node.js application locally while using Docker for the infrastructure (Database, Redis, Kafka, etc.):
+
+```bash
+# Start infrastructure
+docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> kafka<% } %>
+
+# Start the application
+npm run dev
+```
+<% } -%>
+

package/templates/common/_github/workflows/ci.yml.ejs

@@ -0,0 +1,46 @@
+name: Node.js CI
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Use Node.js 22.x
+      uses: actions/setup-node@v4
+      with:
+        node-version: 22.x
+        cache: 'npm'
+        
+    - name: Install Dependencies
+      run: npm ci
+      
+    - name: Lint Code
+      run: npm run lint
+      
+    - name: Run Unit Tests
+      run: npm run test:coverage
+      
+    - name: Run E2E Tests
+      run: npm run test:e2e
+      
+    - name: Build
+      run: npm run build --if-present
+<% if (includeSecurity) { %>
+    - name: SonarQube Scan
+      uses: SonarSource/sonarqube-scan-action@master
+      env:
+        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+<% } %>

package/templates/common/_github/workflows/security.yml.ejs

@@ -0,0 +1,36 @@
+name: Enterprise Security Scan
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '0 0 * * 1' # Weekly scan
+
+jobs:
+  node-security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Snyk to check for vulnerabilities
+        uses: snyk/actions/node@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          args: --severity-threshold=high
+
+  container-security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        run: docker build -t <%= projectName %>:latest .
+      - name: Run Snyk to check Docker image for vulnerabilities
+        uses: snyk/actions/docker@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          image: <%= projectName %>:latest
+          args: --file=Dockerfile --severity-threshold=high --skip-unused-projects

package/templates/common/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.DS_Store
+coverage

package/templates/common/_husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged

package/templates/common/caching/clean/js/CreateUser.js.ejs

@@ -0,0 +1,29 @@
+const User = require('../domain/models/User');
+<%_ if (caching === 'Redis') { -%>
+const cacheService = require('../infrastructure/caching/redisClient');
+<%_ } else if (caching === 'Memory Cache') { -%>
+const cacheService = require('../infrastructure/caching/memoryCache');
+<%_ } -%>
+const logger = require('../infrastructure/log/logger');
+
+class CreateUser {
+    constructor(userRepository) {
+        this.userRepository = userRepository;
+    }
+
+    async execute(name, email) {
+        const user = new User(null, name, email);
+        const savedUser = await this.userRepository.save(user);
+
+        try {
+            await cacheService.del('users:all');
+            logger.info('Invalidated users:all cache');
+        } catch (error) {
+            logger.error('Cache error (del):', error);
+        }
+
+        return savedUser;
+    }
+}
+
+module.exports = CreateUser;

package/templates/common/caching/clean/js/DeleteUser.js.ejs

@@ -0,0 +1,27 @@
+<%_ if (caching === 'Redis') { -%>
+const cacheService = require('../infrastructure/caching/redisClient');
+<%_ } else if (caching === 'Memory Cache') { -%>
+const cacheService = require('../infrastructure/caching/memoryCache');
+<%_ } -%>
+const logger = require('../infrastructure/log/logger');
+
+class DeleteUser {
+    constructor(userRepository) {
+        this.userRepository = userRepository;
+    }
+
+    async execute(id) {
+        const result = await this.userRepository.delete(id);
+
+        try {
+            await cacheService.del('users:all');
+            logger.info('Invalidated users:all cache');
+        } catch (error) {
+             logger.error('Cache error (del):', error);
+        }
+
+        return result;
+    }
+}
+
+module.exports = DeleteUser;

package/templates/common/caching/clean/js/GetAllUsers.js.ejs

@@ -0,0 +1,37 @@
+<%_ if (caching === 'Redis') { -%>
+const cacheService = require('../infrastructure/caching/redisClient');
+<%_ } else if (caching === 'Memory Cache') { -%>
+const cacheService = require('../infrastructure/caching/memoryCache');
+<%_ } -%>
+const logger = require('../infrastructure/log/logger');
+
+class GetAllUsers {
+    constructor(userRepository) {
+        this.userRepository = userRepository;
+    }
+
+    async execute() {
+        const cacheKey = 'users:all';
+        try {
+            const cachedUsers = await cacheService.get(cacheKey);
+            if (cachedUsers) {
+                logger.info('Serving users from cache');
+                return cachedUsers;
+            }
+        } catch (error) {
+            logger.error('Cache error (get):', error);
+        }
+
+        const users = await this.userRepository.getUsers();
+
+        try {
+            await cacheService.set(cacheKey, users, 60);
+        } catch (error) {
+            logger.error('Cache error (set):', error);
+        }
+
+        return users;
+    }
+}
+
+module.exports = GetAllUsers;

package/templates/common/caching/clean/js/UpdateUser.js.ejs

@@ -0,0 +1,27 @@
+<%_ if (caching === 'Redis') { -%>
+const cacheService = require('../infrastructure/caching/redisClient');
+<%_ } else if (caching === 'Memory Cache') { -%>
+const cacheService = require('../infrastructure/caching/memoryCache');
+<%_ } -%>
+const logger = require('../infrastructure/log/logger');
+
+class UpdateUser {
+    constructor(userRepository) {
+        this.userRepository = userRepository;
+    }
+
+    async execute(id, data) {
+        const updatedUser = await this.userRepository.update(id, data);
+
+        try {
+            await cacheService.del('users:all');
+            logger.info('Invalidated users:all cache');
+        } catch (error) {
+            logger.error('Cache error (del):', error);
+        }
+
+        return updatedUser;
+    }
+}
+
+module.exports = UpdateUser;

package/templates/common/caching/clean/ts/createUser.ts.ejs

@@ -0,0 +1,27 @@
+import { User } from '@/domain/user';
+
+import { UserRepository } from '@/infrastructure/repositories/UserRepository';
+<%_ if (caching === 'Redis') { -%>
+import cacheService from '@/infrastructure/caching/redisClient';
+<%_ } else if (caching === 'Memory Cache') { -%>
+import cacheService from '@/infrastructure/caching/memoryCache';
+<%_ } -%>
+import logger from '@/infrastructure/log/logger';
+
+export default class CreateUser {
+    constructor(private userRepository: UserRepository) {}
+
+    async execute(name: string, email: string) {
+        const user = new User(null, name, email);
+        const savedUser = await this.userRepository.save(user);
+
+        try {
+            await cacheService.del('users:all');
+            logger.info('Invalidated users:all cache');
+        } catch (error) {
+            logger.error('Cache error (del):', error);
+        }
+
+        return savedUser;
+    }
+}

package/templates/common/caching/clean/ts/deleteUser.ts.ejs

@@ -0,0 +1,24 @@
+import { UserRepository } from '@/infrastructure/repositories/UserRepository';
+<%_ if (caching === 'Redis') { -%>
+import cacheService from '@/infrastructure/caching/redisClient';
+<%_ } else if (caching === 'Memory Cache') { -%>
+import cacheService from '@/infrastructure/caching/memoryCache';
+<%_ } -%>
+import logger from '@/infrastructure/log/logger';
+
+export default class DeleteUser {
+    constructor(private userRepository: UserRepository) {}
+
+    async execute(id: number | string) {
+        const result = await this.userRepository.delete(id);
+
+        try {
+            await cacheService.del('users:all');
+            logger.info('Invalidated users:all cache');
+        } catch (error) {
+            logger.error('Cache error (del):', error);
+        }
+
+        return result;
+    }
+}

package/templates/common/caching/clean/ts/getAllUsers.ts.ejs

@@ -0,0 +1,34 @@
+import { UserRepository } from '@/infrastructure/repositories/UserRepository';
+<%_ if (caching === 'Redis') { -%>
+import cacheService from '@/infrastructure/caching/redisClient';
+<%_ } else if (caching === 'Memory Cache') { -%>
+import cacheService from '@/infrastructure/caching/memoryCache';
+<%_ } -%>
+import logger from '@/infrastructure/log/logger';
+
+export default class GetAllUsers {
+    constructor(private userRepository: UserRepository) {}
+
+    async execute() {
+        const cacheKey = 'users:all';
+        try {
+            const cachedUsers = await cacheService.get(cacheKey);
+            if (cachedUsers) {
+                logger.info('Serving users from cache');
+                return cachedUsers;
+            }
+        } catch (error) {
+            logger.error('Cache error (get):', error);
+        }
+
+        const users = await this.userRepository.getUsers();
+
+        try {
+            await cacheService.set(cacheKey, users, 60);
+        } catch (error) {
+            logger.error('Cache error (set):', error);
+        }
+
+        return users;
+    }
+}

package/templates/common/caching/clean/ts/updateUser.ts.ejs

@@ -0,0 +1,25 @@
+import { User } from '@/domain/user';
+import { UserRepository } from '@/infrastructure/repositories/UserRepository';
+<%_ if (caching === 'Redis') { -%>
+import cacheService from '@/infrastructure/caching/redisClient';
+<%_ } else if (caching === 'Memory Cache') { -%>
+import cacheService from '@/infrastructure/caching/memoryCache';
+<%_ } -%>
+import logger from '@/infrastructure/log/logger';
+
+export default class UpdateUser {
+    constructor(private userRepository: UserRepository) {}
+
+    async execute(id: number | string, data: { name?: string, email?: string }) {
+        const updatedUser = await this.userRepository.update(id, data);
+
+        try {
+            await cacheService.del('users:all');
+            logger.info('Invalidated users:all cache');
+        } catch (error) {
+            logger.error('Cache error (del):', error);
+        }
+
+        return updatedUser;
+    }
+}

package/templates/common/caching/js/memoryCache.js.ejs

@@ -0,0 +1,60 @@
+const NodeCache = require('node-cache');
+const logger = require('<%- loggerPath %>');
+
+class MemoryCacheService {
+    constructor() {
+        // Default TTL of 0 (unlimited), check period of 120s
+        this.cache = new NodeCache({ stdTTL: 0, checkperiod: 120 });
+        logger.info('Memory Cache initialized');
+    }
+
+    static getInstance() {
+        if (!MemoryCacheService.instance) {
+            MemoryCacheService.instance = new MemoryCacheService();
+        }
+        return MemoryCacheService.instance;
+    }
+
+    async get(key) {
+        try {
+            const data = this.cache.get(key);
+            if (data === undefined) return null;
+            return typeof data === 'string' ? JSON.parse(data) : data;
+        } catch (error) {
+            logger.error(`Memory Cache get error for key ${key}:`, error);
+            return null;
+        }
+    }
+
+    async set(key, value, ttl) {
+        try {
+            const data = JSON.stringify(value);
+            if (ttl) {
+                this.cache.set(key, data, ttl);
+            } else {
+                this.cache.set(key, data);
+            }
+        } catch (error) {
+            logger.error(`Memory Cache set error for key ${key}:`, error);
+        }
+    }
+
+    async del(key) {
+        try {
+            this.cache.del(key);
+        } catch (error) {
+            logger.error(`Memory Cache del error for key ${key}:`, error);
+        }
+    }
+
+    async getOrSet(key, fetcher, ttl = 3600) {
+        const cached = await this.get(key);
+        if (cached) return cached;
+
+        const data = await fetcher();
+        if (data) await this.set(key, data, ttl);
+        return data;
+    }
+}
+
+module.exports = MemoryCacheService.getInstance();

package/templates/common/caching/js/memoryCache.spec.js.ejs

@@ -0,0 +1,101 @@
+jest.mock('node-cache', () => {
+    return jest.fn().mockImplementation(() => ({
+        get: jest.fn(),
+        set: jest.fn(),
+        del: jest.fn(),
+    }));
+});
+
+jest.mock('<%- loggerPath %>', () => ({
+    info: jest.fn(),
+    error: jest.fn(),
+}));
+
+describe('Memory Cache Client', () => {
+    let memoryCacheService;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        jest.resetModules();
+        memoryCacheService = require('<% if (architecture === "MVC") { %>@/config/memoryCache<% } else { %>@/infrastructure/caching/memoryCache<% } %>');
+    });
+
+    it('should get data from memory cache', async () => {
+        const mockData = { test: 'data' };
+        memoryCacheService.cache.get.mockReturnValue(JSON.stringify(mockData));
+        
+        const data = await memoryCacheService.get('test-key');
+        expect(data).toEqual(mockData);
+        expect(memoryCacheService.cache.get).toHaveBeenCalledWith('test-key');
+    });
+
+    it('should return null when key is not found', async () => {
+        memoryCacheService.cache.get.mockReturnValue(undefined);
+        const data = await memoryCacheService.get('non-existent');
+        expect(data).toBeNull();
+    });
+
+    it('should return data as is if not a string', async () => {
+        const mockData = { test: 'data' };
+        memoryCacheService.cache.get.mockReturnValue(mockData);
+        const data = await memoryCacheService.get('binary-key');
+        expect(data).toEqual(mockData);
+    });
+
+    it('should handle errors in get', async () => {
+        memoryCacheService.cache.get.mockImplementation(() => { throw new Error('Cache Error'); });
+        const data = await memoryCacheService.get('error-key');
+        expect(data).toBeNull();
+    });
+
+    it('should set data to memory cache without TTL', async () => {
+        const mockData = { test: 'data' };
+        await memoryCacheService.set('test-key', mockData);
+        expect(memoryCacheService.cache.set).toHaveBeenCalledWith('test-key', JSON.stringify(mockData));
+    });
+
+    it('should handle errors in set', async () => {
+        memoryCacheService.cache.set.mockImplementation(() => { throw new Error('Cache Error'); });
+        await memoryCacheService.set('test-key', 'value');
+    });
+
+    it('should handle errors in del', async () => {
+        memoryCacheService.cache.del.mockImplementation(() => { throw new Error('Cache Error'); });
+        await memoryCacheService.del('test-key');
+    });
+
+    it('should use getOrSet and call fetcher if not cached', async () => {
+        memoryCacheService.get = jest.fn().mockResolvedValue(null);
+        memoryCacheService.set = jest.fn();
+        const fetcher = jest.fn().mockResolvedValue({ new: 'data' });
+
+        const result = await memoryCacheService.getOrSet('new-key', fetcher);
+        
+        expect(result).toEqual({ new: 'data' });
+        expect(fetcher).toHaveBeenCalled();
+        // Result should be cached
+        expect(memoryCacheService.set).toHaveBeenCalledWith('new-key', { new: 'data' }, 3600);
+    });
+
+    it('should return cached data in getOrSet', async () => {
+        const cachedData = { cached: 'data' };
+        memoryCacheService.get = jest.fn().mockResolvedValue(cachedData);
+        const fetcher = jest.fn();
+
+        const result = await memoryCacheService.getOrSet('cached-key', fetcher);
+        
+        expect(result).toEqual(cachedData);
+        expect(fetcher).not.toHaveBeenCalled();
+    });
+
+    it('should handle falsy data from fetcher in getOrSet', async () => {
+        memoryCacheService.get = jest.fn().mockResolvedValue(null);
+        memoryCacheService.set = jest.fn();
+        const fetcher = jest.fn().mockResolvedValue(null);
+
+        const result = await memoryCacheService.getOrSet('empty-key', fetcher);
+        
+        expect(result).toBeNull();
+        expect(memoryCacheService.set).not.toHaveBeenCalled();
+    });
+});