nodejs-quickstart-structure 1.14.0 → 1.16.0

package/templates/common/package.json.ejs

@@ -6,7 +6,7 @@
   "scripts": {
     "start": "<% if (language === 'TypeScript') { %>node dist/index.js<% } else { %>node src/index.js<% } %>",
     "dev": "<% if (language === 'TypeScript') { %>nodemon --exec ts-node -r tsconfig-paths/register src/index.ts<% } else { %>nodemon src/index.js<% } %>"<% if (language === 'TypeScript') { %>,
-    "build": "rimraf dist && tsc && tsc-alias<% if (viewEngine && viewEngine !== 'None') { %> && cpx \"src/views/**/*\" dist/views<% } %><% if (communication === 'REST APIs') { %> && cpx \"src/**/*.yml\" dist/<% } %>"<% } %>,
+    "build": "rimraf dist && tsc && tsc-alias<% if (viewEngine && viewEngine !== 'None') { %> && cpx \"src/views/**/*\" dist/views<% } %><% if (communication === 'REST APIs' || communication === 'Kafka') { %> && cpx \"src/**/*.yml\" dist/<% } %>"<% } %>,
     "deploy": "npx pm2 start ecosystem.config.js --env production",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -47,7 +47,7 @@
     "express-rate-limit": "^7.1.5",
     "winston": "^3.11.0",
     "winston-daily-rotate-file": "^5.0.0",
-    "morgan": "^1.10.0"<% if (communication === 'REST APIs') { %>,
+    "morgan": "^1.10.0"<% if (communication === 'REST APIs' || communication === 'Kafka') { %>,
     "swagger-ui-express": "^5.0.0",
     "yamljs": "^0.3.0"<% } %><% if (communication === 'GraphQL') { %>,
     "@apollo/server": "^4.10.0",
@@ -72,16 +72,18 @@
     "@types/sequelize": "^4.28.19",
 <%_ } -%>
     "@types/morgan": "^1.9.9",
-    "rimraf": "^6.0.1"<% if ((viewEngine && viewEngine !== 'None') || communication === 'REST APIs') { %>,
+    "rimraf": "^6.0.1"<% if ((viewEngine && viewEngine !== 'None') || communication === 'REST APIs' || communication === 'Kafka') { %>,
     "cpx2": "^8.0.0"<% } %><% } %>,
     "eslint": "^9.20.1",
     "@eslint/js": "^9.20.0",
     "globals": "^15.14.0",
     "prettier": "^3.5.1",
     "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-import-x": "^4.6.1",
+    "eslint-import-resolver-typescript": "^3.7.0",
     "husky": "^8.0.3",
     "lint-staged": "^15.4.3"<% if (language === 'TypeScript') { %>,
-    "typescript-eslint": "^8.24.1",<%_ if (communication === 'REST APIs') { %>
+    "typescript-eslint": "^8.24.1",<%_ if (communication === 'REST APIs' || communication === 'Kafka') { %>
     "@types/swagger-ui-express": "^4.1.6",
     "@types/yamljs": "^0.2.34",<%_ } %>
     "jest": "^29.7.0",

package/templates/common/prompts/add-feature.md.ejs

@@ -0,0 +1,26 @@
+# Add New Feature
+
+I want to add a new feature to the existing application. 
+Please follow the strict standards defined in the project context.
+
+## Feature Description
+[INSERT EXPLANATION OF WHAT YOU WANT TO ADD HERE]
+
+## Implementation Guidelines
+
+Please provide the code implementation following these steps:
+
+1. **Plan first**: Outline the files you need to create/modify and the logic they'll contain.
+<% if (architecture === 'Clean Architecture') { -%>
+2. **Domain/Entity**: Define the core entity structure or interfaces if applicable.
+3. **Use Case**: Implement the business logic handling the feature.
+4. **Adapter (Controller & Route)**: Create the necessary endpoints and validate input.
+5. **Infrastructure (Repository)**: Implement database queries or external service calls.
+<% } else { -%>
+2. **Model**: Define the database schema/model if applicable.
+3. **Controller**: Implement the business logic and request handling.
+4. **Route**: Create the API endpoints and wire them to the controller.
+<% } -%>
+6. **Testing**: Write comprehensive Jest unit tests covering the "Happy Path" and "Edge Cases/Errors" (AAA pattern). Remember, our coverage requirement is > 70%!
+
+Please provide the plan first so I can review it before we write the code.

package/templates/common/prompts/project-context.md.ejs

@@ -0,0 +1,43 @@
+# Project Context
+
+Hello AI! I am working on a Node.js project. Here is the context to help you understand the architecture, domain, and standards.
+
+## Domain Overview
+**Project Name**: <%= projectName %>
+You are an expert working on **<%= projectName %>**.
+**Project Goal**: [Replace this with your business logic, e.g., E-commerce API]
+*(Keep this goal in mind when writing business logic, proposing data schemas, or considering edge cases like security and performance.)*
+
+## Tech Stack
+- **Language**: <%= language %>
+- **Architecture**: <%= architecture %>
+- **Database**: <%= database %>
+- **Communication Protocol**: <%= communication %>
+<% if (caching !== 'None') { -%>
+- **Caching**: <%= caching %>
+<% } -%>
+
+## High-Level Architecture
+<% if (architecture === 'Clean Architecture') { -%>
+We use Clean Architecture. The project separates concerns into:
+- `src/domain`: Core entities and rules. No external dependencies.
+- `src/usecases`: Application business logic.
+- `src/interfaces`: Adapters (Controllers, Routes) that mediate between the outside world and use cases.
+- `src/infrastructure`: External tools (Database, Web Server, Config, Caching).
+<% } else { -%>
+We use the MVC (Model-View-Controller) pattern.
+- `src/models`: Database schemas/models.
+- `src/controllers`: Handling incoming requests and implementing business logic.
+- `src/routes`: API endpoints mapped to controllers.
+<% } -%>
+
+## Core Standards
+1. **Testing**: We enforce > 70% coverage. Tests use Jest and the AAA (Arrange, Act, Assert) pattern.
+2. **Error Handling**: We use centralized custom errors (e.g., `ApiError`) and global error middleware. Status codes come from standard constants, not hardcoded numbers.
+3. **Paths & Naming**:
+<% if (language === 'TypeScript') { -%>
+   - We use `@/` path aliases for internal imports.
+<% } -%>
+   - Files are mostly `camelCase`.
+
+Please acknowledge you understand this context by saying "Context loaded successfully! How can I help you build the <%= projectName %>?"

package/templates/common/prompts/troubleshoot.md.ejs

@@ -0,0 +1,28 @@
+# Troubleshoot Error
+
+I am encountering an error in the <%= projectName %> application. Please help me diagnose and fix it based on our architectural standards.
+
+## The Error Log / Issue Description
+\`\`\`
+[PASTE YOUR ERROR LOG OR DESCRIBE THE ISSUE HERE]
+\`\`\`
+
+## Context Variables
+- **Architecture**: <%= architecture %>
+- **Language**: <%= language %>
+
+## Guidelines for Fixing
+
+When analyzing this error, please keep these project standards in mind:
+
+1. **Centralized Error Handling**: 
+   - Ensure the error uses the standard custom error classes from `src/errors/` (e.g., `ApiError`, `NotFoundError`, `BadRequestError`).
+   - If an error occurs in a controller, it should be passed to the global error middleware via `throw` (for async handlers, or `next(error)` in MVC).
+2. **Standard Status Codes**:
+   - Verify that appropriate status codes from `httpCodes` are being used correctly, rather than generic 500s unless unexpected.
+3. **Dependencies**:
+   - Check if this is a connection issue (e.g., Database, Kafka, Redis) and see if our standard configuration or health checks provide hints.
+4. **Fix Suggestion**:
+   - Explain *why* the error happened.
+   - Provide a targeted code fix matching our coding style (<%= language %>, <%= architecture %>).
+   - Only modify what is strictly necessary to solve the issue.

package/templates/mvc/js/src/controllers/userController.js.ejs

@@ -40,6 +40,13 @@ const createUser = async (data) => {
     const user = await User.create({ name, email });
 <%_ if (caching === 'Redis' || caching === 'Memory Cache') { -%>
     await cacheService.del('users:all');
+<%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+    const { sendMessage } = require('../services/kafkaService');
+    await sendMessage('user-topic', JSON.stringify({
+      action: 'USER_CREATED',
+      payload: { id: user.id || user._id, email: user.email }
+    }));
 <%_ } -%>
     return user;
   } catch (error) {
@@ -78,6 +85,13 @@ const createUser = async (req, res, next) => {
     const user = await User.create({ name, email });
 <%_ if (caching === 'Redis' || caching === 'Memory Cache') { -%>
     await cacheService.del('users:all');
+<%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+    const { sendMessage } = require('../services/kafkaService');
+    await sendMessage('user-topic', JSON.stringify({
+      action: 'USER_CREATED',
+      payload: { id: user.id || user._id, email: user.email }
+    }));
 <%_ } -%>
     res.status(HTTP_STATUS.CREATED).json(user);
   } catch (error) {

package/templates/mvc/js/src/controllers/userController.spec.js.ejs

@@ -23,6 +23,14 @@ jest.mock('@/config/memoryCache', () => ({
 }));
 <%_ } -%>
 jest.mock('@/utils/logger');
+<%_ if (communication === 'Kafka') { -%>
+const { sendMessage } = require('@/services/kafkaService');
+jest.mock('@/services/kafkaService', () => ({
+    sendMessage: jest.fn().mockResolvedValue(undefined),
+    connectKafka: jest.fn().mockResolvedValue(undefined)
+}));
+<%_ } -%>
+
 
 describe('UserController', () => {
 <% if (communication !== 'GraphQL') { -%>
@@ -143,6 +151,9 @@ describe('UserController', () => {
 <% } -%>
 <%_ if (caching === 'Redis' || caching === 'Memory Cache') { -%>
             expect(cacheService.del).toHaveBeenCalledWith('users:all');
+<%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+            expect(sendMessage).toHaveBeenCalled();
 <%_ } -%>
         });
 
@@ -166,5 +177,33 @@ describe('UserController', () => {
             expect(mockNext).toHaveBeenCalledWith(error);
 <% } -%>
         });
+
+<%_ if (communication === 'Kafka') { -%>
+        it('should successfully create a new user with _id for Kafka (Happy Path)', async () => {
+            // Arrange
+            const payload = { name: 'Bob', email: 'bob@example.com' };
+<% if (communication === 'GraphQL') { -%>
+            const dataArg = payload;
+<% } else { -%>
+            mockRequest.body = payload;
+<% } -%>
+            
+            const expectedUser = { _id: '2', ...payload };
+            User.create.mockResolvedValue(expectedUser);
+
+            // Act
+<% if (communication === 'GraphQL') { -%>
+            await createUser(dataArg);
+<% } else { -%>
+            await createUser(mockRequest, mockResponse, mockNext);
+<% } -%>
+
+            // Assert
+            expect(sendMessage).toHaveBeenCalledWith(
+                'user-topic',
+                expect.stringContaining('"id":"2"')
+            );
+        });
+<%_ } -%>
     });
 });

package/templates/mvc/js/src/index.js.ejs

@@ -1,6 +1,6 @@
 const express = require('express');
 const cors = require('cors');
-<%_ if (communication === 'REST APIs') { -%>const apiRoutes = require('./routes/api');<%_ } %>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>const apiRoutes = require('./routes/api');<%_ } %>
 const healthRoutes = require('./routes/healthRoute');
 <%_ if (communication === 'Kafka') { -%>const { connectKafka, sendMessage } = require('./services/kafkaService');<%_ } -%>
 <%_ if (communication === 'GraphQL') { -%>
@@ -11,8 +11,8 @@ const { unwrapResolverError } = require('@apollo/server/errors');
 const { ApiError } = require('./errors/ApiError');
 const { typeDefs, resolvers } = require('./graphql');
 const { gqlContext } = require('./graphql/context');
-<% } -%>
-<%_ if (communication === 'REST APIs') { -%>
+<% } %>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 const swaggerUi = require('swagger-ui-express');
 const swaggerSpecs = require('./config/swagger');
 <%_ } -%>
@@ -28,7 +28,7 @@ app.use(cors());
 app.use(express.json());
 app.use(morgan('combined', { stream: { write: message => logger.info(message.trim()) } }));
 
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecs));
 <%_ } -%>
 <%_ if (viewEngine === 'EJS' || viewEngine === 'Pug') { -%>
@@ -37,7 +37,7 @@ const path = require('path');
 app.set('views', path.join(__dirname, 'views'));
 app.set('view engine', '<%= viewEngine.toLowerCase() %>');
 app.use(express.static(path.join(__dirname, '../public')));<%_ } %>
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 app.use('/api', apiRoutes);
 <%_ } -%><% if (viewEngine && viewEngine !== 'None') { -%>
 app.get('/', (req, res) => {
@@ -86,12 +86,13 @@ const startServer = async () => {
     const server = app.listen(PORT, () => {
         logger.info(`Server running on port ${PORT}`);
 <%_ if (communication === 'Kafka') { -%>
-        connectKafka().then(() => {
-          logger.info('Kafka connected');
-          sendMessage('test-topic', 'Hello Kafka from MVC JS!');
-        }).catch(err => {
-          logger.error('Failed to connect to Kafka:', err);
-        });
+        connectKafka()
+            .then(async () => {
+                logger.info('Kafka connected');
+            })
+            .catch(err => {
+                logger.error('Failed to connect to Kafka after retries:', err.message);
+            });
 <%_ } -%>
     });
 

package/templates/mvc/ts/src/config/swagger.ts.ejs

@@ -1,4 +1,4 @@
-<% if (communication === 'REST APIs') { %>import path from 'path';
+<% if (communication === 'REST APIs' || communication === 'Kafka') { %>import path from 'path';
 import YAML from 'yamljs';
 
 const swaggerDocument = YAML.load(path.join(__dirname, 'swagger.yml'));

package/templates/mvc/ts/src/controllers/userController.spec.ts.ejs

@@ -24,6 +24,20 @@ jest.mock('@/config/memoryCache', () => ({
 }));
 <%_ } -%>
 jest.mock('@/utils/logger');
+<%_ if (communication === 'Kafka') { -%>
+jest.mock('@/services/kafkaService', () => {
+    const mockSendMessage = jest.fn().mockResolvedValue(undefined);
+    return {
+        kafkaService: {
+            sendMessage: mockSendMessage
+        },
+        KafkaService: jest.fn().mockImplementation(() => ({
+            sendMessage: mockSendMessage
+        }))
+    };
+});
+<%_ } -%>
+
 
 describe('UserController', () => {
     let userController: UserController;
@@ -158,6 +172,10 @@ describe('UserController', () => {
 <% } -%>
 <%_ if (caching === 'Redis' || caching === 'Memory Cache') { -%>
             expect(cacheService.del).toHaveBeenCalledWith('users:all');
+<%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = require('@/services/kafkaService');
+            expect(kafkaService.sendMessage).toHaveBeenCalled();
 <%_ } -%>
         });
 

package/templates/mvc/ts/src/controllers/userController.ts.ejs

@@ -42,6 +42,14 @@ export class UserController {
             const user = await User.create({ name, email });
 <%_ if (caching === 'Redis' || caching === 'Memory Cache') { -%>
             await cacheService.del('users:all');
+<%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = await import('@/services/kafkaService');
+            await kafkaService.sendMessage('user-topic', JSON.stringify({
+                action: 'USER_CREATED',
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                payload: { id: (user as any).id || (user as any)._id, email: user.email }
+            }));
 <%_ } -%>
             return user;
         } catch (error) {
@@ -80,6 +88,14 @@ export class UserController {
             const user = await User.create({ name, email });
 <%_ if (caching === 'Redis' || caching === 'Memory Cache') { -%>
             await cacheService.del('users:all');
+<%_ } -%>
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = await import('@/services/kafkaService');
+            await kafkaService.sendMessage('user-topic', JSON.stringify({
+                action: 'USER_CREATED',
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                payload: { id: (user as any).id || (user as any)._id, email: user.email }
+            }));
 <%_ } -%>
             res.status(HTTP_STATUS.CREATED).json(user);
         } catch (error) {

package/templates/mvc/ts/src/index.ts.ejs

@@ -9,12 +9,11 @@ import morgan from 'morgan';
 import { errorMiddleware } from '@/utils/errorMiddleware';
 import { setupGracefulShutdown } from '@/utils/gracefulShutdown';
 import healthRoutes from '@/routes/healthRoute';
-<%_ if (communication === 'REST APIs') { -%>
-import apiRoutes from '@/routes/api';<%_ } -%>
-<% if (communication === 'REST APIs') { %>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
+import apiRoutes from '@/routes/api';
 import swaggerUi from 'swagger-ui-express';
-import swaggerSpecs from '@/config/swagger';<% } -%>
-<%_ if (communication === 'Kafka') { -%>import { KafkaService } from '@/services/kafkaService';<%_ } -%>
+import swaggerSpecs from '@/config/swagger';<%_ } %>
+<%_ if (communication === 'Kafka') { -%>import { kafkaService } from '@/services/kafkaService';<%_ } -%>
 <%_ if (communication === 'GraphQL') { -%>
 import { ApolloServer } from '@apollo/server';
 import { expressMiddleware } from '@apollo/server/express4';
@@ -51,7 +50,7 @@ app.use(limiter);
 
 app.use(express.json());
 app.use(morgan('combined', { stream: { write: (message) => logger.info(message.trim()) } }));
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecs));
 <%_ } -%>
 <%_ if (viewEngine === 'EJS' || viewEngine === 'Pug') { -%>
@@ -60,7 +59,7 @@ import path from 'path';
 app.set('views', path.join(__dirname, 'views'));
 app.set('view engine', '<%= viewEngine.toLowerCase() %>');
 app.use(express.static(path.join(__dirname, '../public')));<%_ } %>
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 app.use('/api', apiRoutes);
 <%_ } -%><% if (viewEngine && viewEngine !== 'None') { -%>
 app.get('/', (req: Request, res: Response) => {
@@ -106,18 +105,16 @@ const startServer = async () => {
     app.use('/graphql', expressMiddleware(apolloServer, { context: gqlContext }));
 <%_ } -%>
     app.use(errorMiddleware);
-<%_ if (communication === 'Kafka') { -%>
-    const kafkaService = new KafkaService();
-<%_ } -%>
     const server = app.listen(port, () => {
         logger.info(`Server running on port ${port}`);
 <%_ if (communication === 'Kafka') { -%>
-        kafkaService.connect().then(() => {
-          logger.info('Kafka connected');
-          kafkaService.sendMessage('test-topic', 'Hello Kafka from MVC TS!');
-        }).catch(err => {
-          logger.error('Failed to connect to Kafka:', err);
-        });
+        kafkaService.connect()
+            .then(async () => {
+                logger.info('Kafka connected');
+            })
+            .catch(err => {
+                logger.error('Failed to connect to Kafka after retries:', (err as Error).message);
+            });
 <%_ } -%>
     });
 

package/templates/mvc/ts/src/utils/logger.spec.ts.ejs

@@ -56,7 +56,6 @@ describe('Logger', () => {
         const winston = require('winston');
         jest.resetModules();
         process.env.NODE_ENV = 'production';
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
         require('<% if (architecture === "MVC") { %>@/utils/logger<% } else { %>@/infrastructure/log/logger<% } %>');
         expect(winston.format.json).toHaveBeenCalled();
         process.env.NODE_ENV = 'test';