nodejs-quickstart-structure 1.13.0 → 1.15.1

package/templates/clean-architecture/ts/src/interfaces/controllers/userController.spec.ts.ejs

@@ -0,0 +1,166 @@
+<% if (communication !== 'GraphQL') { -%>
+import { Request, Response, NextFunction } from 'express';
+import { HTTP_STATUS } from '@/utils/httpCodes';
+<% } -%>
+import { UserController } from '@/interfaces/controllers/userController';
+import CreateUser from '@/usecases/createUser';
+import GetAllUsers from '@/usecases/getAllUsers';
+
+// Mock dependencies
+jest.mock('@/infrastructure/repositories/UserRepository');
+jest.mock('@/usecases/createUser');
+jest.mock('@/usecases/getAllUsers');
+jest.mock('@/infrastructure/log/logger');
+
+describe('UserController (Clean Architecture)', () => {
+    let userController: UserController;
+    let mockCreateUserUseCase: jest.Mocked<CreateUser>;
+    let mockGetAllUsersUseCase: jest.Mocked<GetAllUsers>;
+<% if (communication !== 'GraphQL') { -%>
+    let mockRequest: Partial<Request>;
+    let mockResponse: Partial<Response>;
+    let mockNext: NextFunction;
+<% } -%>
+
+    beforeEach(() => {
+        // Clear all mocks
+        jest.clearAllMocks();
+
+        userController = new UserController();
+
+        // Retrieve the mocked instances created inside UserController constructor
+        mockCreateUserUseCase = (CreateUser as jest.Mock).mock.instances[0] as jest.Mocked<CreateUser>;
+        mockGetAllUsersUseCase = (GetAllUsers as jest.Mock).mock.instances[0] as jest.Mocked<GetAllUsers>;
+
+<% if (communication !== 'GraphQL') { -%>
+        mockRequest = {};
+        mockResponse = {
+            json: jest.fn(),
+            status: jest.fn().mockReturnThis(),
+        };
+        mockNext = jest.fn();
+<% } -%>
+    });
+
+    describe('getUsers', () => {
+        it('should return successfully (Happy Path)', async () => {
+            // Arrange
+            const usersMock = [{ id: '1', name: 'Test', email: 'test@example.com' }];
+            mockGetAllUsersUseCase.execute.mockResolvedValue(usersMock);
+
+            // Act
+<% if (communication === 'GraphQL') { -%>
+            const result = await userController.getUsers();
+
+            // Assert
+            expect(result).toEqual(usersMock);
+<% } else { -%>
+            await userController.getUsers(mockRequest as Request, mockResponse as Response, mockNext);
+
+            // Assert
+            expect(mockResponse.json).toHaveBeenCalledWith(usersMock);
+<% } -%>
+            expect(mockGetAllUsersUseCase.execute).toHaveBeenCalled();
+        });
+
+        it('should handle errors correctly (Error Handling)', async () => {
+            // Arrange
+            const error = new Error('UseCase Error');
+            mockGetAllUsersUseCase.execute.mockRejectedValue(error);
+
+            // Act & Assert
+<% if (communication === 'GraphQL') { -%>
+            await expect(userController.getUsers()).rejects.toThrow(error);
+<% } else { -%>
+            await userController.getUsers(mockRequest as Request, mockResponse as Response, mockNext);
+            expect(mockNext).toHaveBeenCalledWith(error);
+<% } -%>
+        });
+
+        it('should handle non-Error objects in catch block', async () => {
+            // Arrange
+            const error = 'String Error';
+            mockGetAllUsersUseCase.execute.mockRejectedValue(error);
+
+            // Act & Assert
+<% if (communication === 'GraphQL') { -%>
+            await expect(userController.getUsers()).rejects.toEqual(error);
+<% } else { -%>
+            await userController.getUsers(mockRequest as Request, mockResponse as Response, mockNext);
+            expect(mockNext).toHaveBeenCalledWith(error);
+<% } -%>
+        });
+    });
+
+    describe('createUser', () => {
+        it('should successfully create a new user (Happy Path)', async () => {
+            // Arrange
+            const payload = { name: 'Alice', email: 'alice@example.com' };
+<% if (communication === 'GraphQL') { -%>
+            const dataArg = payload;
+<% } else { -%>
+            mockRequest.body = payload;
+<% } -%>
+            const expectedUser = { id: '1', ...payload };
+            
+            mockCreateUserUseCase.execute.mockResolvedValue(expectedUser);
+
+            // Act
+<% if (communication === 'GraphQL') { -%>
+            const result = await userController.createUser(dataArg);
+
+            // Assert
+            expect(result).toEqual(expectedUser);
+<% } else { -%>
+            await userController.createUser(mockRequest as Request, mockResponse as Response, mockNext);
+
+            // Assert
+            expect(mockResponse.status).toHaveBeenCalledWith(HTTP_STATUS.CREATED);
+            expect(mockResponse.json).toHaveBeenCalledWith(expectedUser);
+<% } -%>
+            expect(mockCreateUserUseCase.execute).toHaveBeenCalledWith(payload.name, payload.email);
+        });
+
+        it('should handle errors when creation fails (Error Handling)', async () => {
+            // Arrange
+            const error = new Error('Creation Error');
+            const payload = { name: 'Bob', email: 'bob@example.com' };
+<% if (communication === 'GraphQL') { -%>
+            const dataArg = payload;
+<% } else { -%>
+            mockRequest.body = payload;
+<% } -%>
+
+            mockCreateUserUseCase.execute.mockRejectedValue(error);
+
+            // Act & Assert
+<% if (communication === 'GraphQL') { -%>
+            await expect(userController.createUser(dataArg)).rejects.toThrow(error);
+<% } else { -%>
+            await userController.createUser(mockRequest as Request, mockResponse as Response, mockNext);
+            expect(mockNext).toHaveBeenCalledWith(error);
+<% } -%>
+        });
+
+        it('should handle non-Error objects in catch block when creation fails', async () => {
+            // Arrange
+            const error = 'Creation String Error';
+            const payload = { name: 'Bob', email: 'bob@example.com' };
+<% if (communication === 'GraphQL') { -%>
+            const dataArg = payload;
+<% } else { -%>
+            mockRequest.body = payload;
+<% } -%>
+
+            mockCreateUserUseCase.execute.mockRejectedValue(error);
+
+            // Act & Assert
+<% if (communication === 'GraphQL') { -%>
+            await expect(userController.createUser(dataArg)).rejects.toEqual(error);
+<% } else { -%>
+            await userController.createUser(mockRequest as Request, mockResponse as Response, mockNext);
+            expect(mockNext).toHaveBeenCalledWith(error);
+<% } -%>
+        });
+    });
+});

package/templates/clean-architecture/ts/src/interfaces/graphql/context.spec.ts.ejs

@@ -0,0 +1,32 @@
+import { gqlContext } from '@/interfaces/graphql/context';
+import { Request } from 'express';
+import { resolvers } from '@/interfaces/graphql/resolvers';
+import { typeDefs } from '@/interfaces/graphql/typeDefs';
+
+jest.mock('@/infrastructure/repositories/UserRepository');
+
+describe('GraphQL Context', () => {
+  it('should exercise GraphQL index entry points', () => {
+    expect(resolvers).toBeDefined();
+    expect(typeDefs).toBeDefined();
+  });
+  it('should return context with token when authorization header is present', async () => {
+    const mockRequest = {
+      headers: {
+        authorization: 'Bearer token123',
+      },
+    } as Request;
+
+    const context = await gqlContext({ req: mockRequest });
+    expect(context.token).toBe('Bearer token123');
+  });
+
+  it('should return context with empty token when authorization header is missing', async () => {
+    const mockRequest = {
+      headers: {},
+    } as Request;
+
+    const context = await gqlContext({ req: mockRequest });
+    expect(context.token).toBe('');
+  });
+});

package/templates/clean-architecture/ts/src/interfaces/graphql/resolvers/user.resolvers.spec.ts.ejs

@@ -0,0 +1,51 @@
+import { userResolvers } from '@/interfaces/graphql/resolvers/user.resolvers';
+
+const mockGetUsers = jest.fn().mockResolvedValue([{ id: '1', name: 'John Doe', email: 'john@example.com' }]);
+const mockCreateUser = jest.fn().mockResolvedValue({ id: '1', name: 'Jane', email: 'jane@example.com' });
+
+jest.mock('@/interfaces/controllers/userController', () => {
+  return {
+    UserController: jest.fn().mockImplementation(() => ({
+      getUsers: (...args: unknown[]) => mockGetUsers(...args),
+      createUser: (...args: unknown[]) => mockCreateUser(...args)
+    }))
+  };
+});
+
+describe('User Resolvers', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('Query.getAllUsers', () => {
+    it('should return all users', async () => {
+      const result = await userResolvers.Query.getAllUsers();
+      expect(result).toEqual([{ id: '1', name: 'John Doe', email: 'john@example.com' }]);
+      expect(mockGetUsers).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('Mutation.createUser', () => {
+    it('should create and return a new user', async () => {
+      const result = await userResolvers.Mutation.createUser(null, { name: 'Jane', email: 'jane@example.com' });
+      expect(result).toEqual({ id: '1', name: 'Jane', email: 'jane@example.com' });
+      expect(mockCreateUser).toHaveBeenCalledWith({ name: 'Jane', email: 'jane@example.com' });
+      expect(mockCreateUser).toHaveBeenCalledTimes(1);
+    });
+  });
+<%_ if (database === 'MongoDB') { -%>
+  describe('User.id', () => {
+    it('should return parent.id if available', () => {
+      const parent = { id: '123' };
+      const result = userResolvers.User.id(parent as { id?: string; _id?: unknown });
+      expect(result).toBe('123');
+    });
+
+    it('should fallback to parent._id if id is not available', () => {
+      const parent = { _id: '456' };
+      const result = userResolvers.User.id(parent as { id?: string; _id?: unknown });
+      expect(result).toBe('456');
+    });
+  });
+<%_ } -%>
+});

package/templates/clean-architecture/ts/src/interfaces/routes/userRoutes.spec.ts.ejs

@@ -0,0 +1,40 @@
+import request from 'supertest';
+import express, { Express } from 'express';
+import router from '@/interfaces/routes/userRoutes';
+
+const mockGetUsers = jest.fn().mockImplementation((req, res) => res.status(200).json([{ id: '1', name: 'John Doe' }]));
+const mockCreateUser = jest.fn().mockImplementation((req, res) => res.status(201).json({ id: '1', name: 'Test' }));
+
+jest.mock('@/interfaces/controllers/userController', () => {
+  return {
+    UserController: jest.fn().mockImplementation(() => ({
+      getUsers: (...args: unknown[]) => mockGetUsers(...args),
+      createUser: (...args: unknown[]) => mockCreateUser(...args)
+    }))
+  };
+});
+
+describe('UserRoutes', () => {
+    let app: Express;
+
+    beforeEach(() => {
+        app = express();
+        app.use(express.json());
+        app.use('/users', router);
+    });
+
+    it('POST /users should call controller.createUser', async () => {
+        await request(app)
+            .post('/users')
+            .send({ name: 'Test', email: 'test@example.com' });
+
+        expect(mockCreateUser).toHaveBeenCalledTimes(1);
+    });
+
+    it('GET /users should call controller.getUsers', async () => {
+        await request(app)
+            .get('/users');
+
+        expect(mockGetUsers).toHaveBeenCalledTimes(1);
+    });
+});

package/templates/clean-architecture/ts/src/usecases/createUser.spec.ts.ejs

@@ -0,0 +1,51 @@
+import CreateUser from '@/usecases/createUser';
+import { UserRepository } from '@/infrastructure/repositories/UserRepository';
+<%_ if (caching !== 'None') { -%>
+import cacheService from '<% if (caching === "Redis") { %>@/infrastructure/caching/redisClient<% } else { %>@/infrastructure/caching/memoryCache<% } %>';
+<%_ } -%>
+
+jest.mock('@/infrastructure/repositories/UserRepository');
+<%_ if (caching !== 'None') { -%>
+jest.mock('<% if (caching === "Redis") { %>@/infrastructure/caching/redisClient<% } else { %>@/infrastructure/caching/memoryCache<% } %>', () => ({
+    get: jest.fn(),
+    set: jest.fn(),
+    del: jest.fn()
+}));
+<%_ } -%>
+
+describe('CreateUser UseCase', () => {
+    let createUser: CreateUser;
+    let mockUserRepository: jest.Mocked<UserRepository>;
+
+    beforeEach(() => {
+        mockUserRepository = new UserRepository() as jest.Mocked<UserRepository>;
+        createUser = new CreateUser(mockUserRepository);
+        jest.clearAllMocks();
+    });
+
+    it('should create and save a new user', async () => {
+        const name = 'Test User';
+        const email = 'test@example.com';
+        const expectedResult = { id: 1, name, email };
+
+        mockUserRepository.save.mockResolvedValue(expectedResult as any);
+
+        const result = await createUser.execute(name, email);
+
+        expect(mockUserRepository.save).toHaveBeenCalledTimes(1);
+        const savedUser = mockUserRepository.save.mock.calls[0][0];
+        expect(savedUser.name).toBe(name);
+        expect(savedUser.email).toBe(email);
+        expect(result).toEqual(expectedResult);
+<%_ if (caching !== 'None') { -%>
+        expect(cacheService.del).toHaveBeenCalledWith('users:all');
+<%_ } %>
+    });
+
+    it('should throw an error if repository fails', async () => {
+        const error = new Error('Database error');
+        mockUserRepository.save.mockRejectedValue(error);
+
+        await expect(createUser.execute('Test', 'test@test.com')).rejects.toThrow(error);
+    });
+});

package/templates/clean-architecture/ts/src/usecases/getAllUsers.spec.ts.ejs

@@ -0,0 +1,63 @@
+import GetAllUsers from '@/usecases/getAllUsers';
+import { UserRepository } from '@/infrastructure/repositories/UserRepository';
+<%_ if (caching !== 'None') { -%>
+import cacheService from '<% if (caching === "Redis") { %>@/infrastructure/caching/redisClient<% } else { %>@/infrastructure/caching/memoryCache<% } %>';
+<%_ } -%>
+
+jest.mock('@/infrastructure/repositories/UserRepository');
+<%_ if (caching !== 'None') { -%>
+jest.mock('<% if (caching === "Redis") { %>@/infrastructure/caching/redisClient<% } else { %>@/infrastructure/caching/memoryCache<% } %>', () => ({
+    get: jest.fn(),
+    set: jest.fn(),
+    del: jest.fn()
+}));
+<%_ } -%>
+
+describe('GetAllUsers UseCase', () => {
+    let getAllUsers: GetAllUsers;
+    let mockUserRepository: jest.Mocked<UserRepository>;
+
+    beforeEach(() => {
+        mockUserRepository = new UserRepository() as jest.Mocked<UserRepository>;
+        getAllUsers = new GetAllUsers(mockUserRepository);
+        jest.clearAllMocks();
+    });
+
+    it('should retrieve all users', async () => {
+        const expectedUsers = [{ id: 1, name: 'Alice', email: 'alice@example.com' }];
+        mockUserRepository.getUsers.mockResolvedValue(expectedUsers as any);
+<%_ if (caching !== 'None') { -%>
+        (cacheService.get as jest.Mock).mockResolvedValue(null);
+<%_ } %>
+
+        const result = await getAllUsers.execute();
+
+        expect(mockUserRepository.getUsers).toHaveBeenCalledTimes(1);
+        expect(result).toEqual(expectedUsers);
+<%_ if (caching !== 'None') { -%>
+        expect(cacheService.set).toHaveBeenCalled();
+<%_ } %>
+    });
+
+<%_ if (caching !== 'None') { -%>
+    it('should return from cache if available', async () => {
+        const cachedUsers = [{ id: 1, name: 'Cached', email: 'cached@example.com' }];
+        (cacheService.get as jest.Mock).mockResolvedValue(cachedUsers);
+
+        const result = await getAllUsers.execute();
+
+        expect(mockUserRepository.getUsers).not.toHaveBeenCalled();
+        expect(result).toEqual(cachedUsers);
+    });
+<%_ } -%>
+
+    it('should throw an error if repository fails', async () => {
+        const error = new Error('Database error');
+        mockUserRepository.getUsers.mockRejectedValue(error);
+<%_ if (caching !== 'None') { -%>
+        (cacheService.get as jest.Mock).mockResolvedValue(null);
+<%_ } -%>
+
+        await expect(getAllUsers.execute()).rejects.toThrow(error);
+    });
+});

package/templates/clean-architecture/ts/src/utils/errorMiddleware.ts.ejs

@@ -3,8 +3,7 @@ import logger from '@/infrastructure/log/logger';
 import { ApiError } from '@/errors/ApiError';
 import { HTTP_STATUS } from '@/utils/httpCodes';
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export const errorMiddleware = (err: Error, req: Request, res: Response, next: unknown) => {
+export const errorMiddleware = (err: Error, req: Request, res: Response, _next: unknown) => {
   let error = err;
 
   if (!(error instanceof ApiError)) {

package/templates/common/.cursorrules.ejs

@@ -0,0 +1,60 @@
+# Cursor AI Coding Rules for <%= projectName %>
+
+## Project Context
+You are an expert working on **<%= projectName %>**.
+- **Project Goal**: [Replace this with your business logic, e.g., E-commerce API]
+- **Language**: <%= language %>
+- **Architecture**: <%= architecture %>
+- **Database**: <%= database %>
+- **Communication**: <%= communication %>
+
+## Excluded Files/Folders
+When indexing or searching the workspace, ignore the following paths to prevent context pollution:
+- `node_modules/`
+- `dist/`
+- `build/`
+- `coverage/`
+- `.git/`
+
+## Strict Rules
+
+### 1. Testing First
+- Every new service or controller method MUST have a test file in `tests/`.
+- **Coverage Gate**: Aim for > 70% coverage (Statement/Line/Function/Branch).
+- **Format**: Use Jest with the AAA (Arrange, Act, Assert) pattern.
+- **Isolation**: Mock external dependencies (DB, Redis, etc.) using `jest.mock()`.
+
+### 2. Error Handling
+- Do NOT use generic `Error`.
+- Use custom classes from `src/errors/` (e.g., `ApiError`, `NotFoundError`, `BadRequestError`).
+<% if (language === 'TypeScript') { -%>
+- Use `HTTP_STATUS` constants from `@/utils/httpCodes` for status codes.
+<% } else { -%>
+- Use `HTTP_STATUS` constants from `../utils/httpCodes.js` for status codes.
+<% } -%>
+
+### 3. File Naming & Style
+- **Controllers**: camelCase (e.g., `userController.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+- **Services**: camelCase (e.g., `userService.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+- **Routes**: camelCase (e.g., `userRoutes.<% if (language === 'TypeScript') { %>ts<% } else { %>js<% } %>`).
+<% if (language === 'TypeScript') { -%>
+- **Imports**: Use path aliases (e.g., `@/services/...`) instead of relative paths.
+- **Typing**: Ensure strong typing for interfaces and DTOs. Do not use `any` unless absolutely necessary.
+<% } else { -%>
+- **Imports**: Use relative paths as dictated by the directory structure.
+<% } -%>
+
+### 4. Architecture Standards
+<% if (architecture === 'Clean Architecture') { -%>
+- Enforce strict separation of concerns:
+  - `domain`: Entities and enterprise business rules.
+  - `usecases`: Application business rules.
+  - `interfaces`: Controllers and Routes.
+  - `infrastructure`: Frameworks, Database, Caching, and Web Server.
+- Dependencies point inward toward the `domain`.
+<% } else { -%>
+- Enforce MVC standards:
+  - `models`: Data layer.
+  - `controllers`: Request handlers and business logic.
+  - `routes`: Define endpoints routing to controllers.
+<% } -%>

package/templates/common/.dockerignore

@@ -8,3 +8,5 @@ README.md
 docker-compose.yml
 test_results.log
 flyway/sql
+.cursorrules
+prompts

package/templates/common/.gitlab-ci.yml.ejs

@@ -12,24 +12,24 @@ cache:
 
 install_dependencies:
   stage: .pre
-  image: node:18-alpine
+  image: node:22-alpine
   script:
     - npm ci
 
 lint_code:
   stage: lint
-  image: node:18-alpine
+  image: node:22-alpine
   script:
     - npm run lint
 
 run_tests:
   stage: test
-  image: node:18-alpine
+  image: node:22-alpine
   script:
-    - npm test
+    - npm run test:coverage
 
 build_app:
   stage: build
-  image: node:18-alpine
+  image: node:22-alpine
   script:
     - npm run build --if-present

package/templates/common/Jenkinsfile.ejs

@@ -21,7 +21,7 @@ pipeline {
 
         stage('Test') {
             steps {
-                sh 'npm test'
+                sh 'npm run test:coverage'
             }
         }
 

package/templates/common/README.md.ejs

@@ -217,4 +217,14 @@ docker-compose down
 -   **Helmet**: Sets secure HTTP headers.
 -   **CORS**: Configured for cross-origin requests.
 -   **Rate Limiting**: Protects against DDoS / Brute-force.
--   **HPP**: Prevents HTTP Parameter Pollution attacks.
+-   **HPP**: Prevents HTTP Parameter Pollution attacks.
+
+
+## 🤖 AI-Native Development
+
+This project is "AI-Ready" out of the box. We have pre-configured industry-leading AI context files to bridge the gap between "Generated Code" and "AI-Assisted Development."
+
+- **Magic Defaults**: We've automatically tailored your AI context to focus on **<%= projectName %>** and its specific architectural stack (<%= architecture %>, <%= database %>, etc.).
+- **Use Cursor?** We've configured **`.cursorrules`** at the root. It enforces project standards (70% coverage, MVC/Clean) directly within the editor. 
+  - *Pro-tip*: You can customize the `Project Goal` placeholder in `.cursorrules` to help the AI understand your specific business logic!
+- **Use ChatGPT/Gemini/Claude?** Check the **`prompts/`** directory. It contains highly-specialized Agent Skill templates. You can copy-paste these into any LLM to give it a "Senior Developer" understanding of your codebase immediately.

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

@@ -1,5 +1,8 @@
 name: Node.js CI
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+
 on:
   push:
     branches: [ "main" ]
@@ -13,13 +16,13 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x]
+        node-version: [20.x, 22.x]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
         cache: 'npm'
@@ -31,7 +34,7 @@ jobs:
       run: npm run lint
       
     - name: Run Tests
-      run: npm test
+      run: npm run test:coverage
       
     - name: Build
       run: npm run build --if-present