nodejs-quickstart-structure 1.14.0 → 1.16.0

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

@@ -4,6 +4,12 @@ const GetAllUsers = require('@/usecases/GetAllUsers');
 
 jest.mock('@/usecases/CreateUser');
 jest.mock('@/usecases/GetAllUsers');
+<%_ if (communication === 'Kafka') { -%>
+jest.mock('@/infrastructure/messaging/kafkaClient', () => ({
+    sendMessage: jest.fn().mockResolvedValue(undefined)
+}));
+<%_ } -%>
+
 
 describe('UserController (Clean Architecture)', () => {
     let userController;
@@ -81,7 +87,12 @@ describe('UserController (Clean Architecture)', () => {
             expect(result).toEqual(expectedUser);
 <%_ } else { -%>
             await userController.createUser(mockRequest, mockResponse, mockNext);
+<%_ if (communication === 'Kafka') { -%>
+            const { sendMessage } = require('@/infrastructure/messaging/kafkaClient');
+            expect(sendMessage).toHaveBeenCalled();
+<%_ } -%>
             expect(mockResponse.status).toHaveBeenCalledWith(201);
+
             expect(mockResponse.json).toHaveBeenCalledWith(expectedUser);
 <%_ } -%>
             expect(mockCreateUserUseCase.execute).toHaveBeenCalledWith(payload.name, payload.email);
@@ -98,5 +109,30 @@ describe('UserController (Clean Architecture)', () => {
             expect(mockNext).toHaveBeenCalledWith(error);
 <%_ } -%>
         });
+
+<%_ if (communication === 'Kafka') { -%>
+        it('should successfully create a new user with _id for Kafka (Happy Path)', async () => {
+            const payload = { name: 'Bob', email: 'bob@example.com' };
+<% if (communication === 'GraphQL') { -%>
+            const dataArg = payload;
+<% } else { -%>
+            mockRequest.body = payload;
+<% } -%>
+            const expectedUser = { _id: '2', ...payload };
+            
+            mockCreateUserUseCase.execute.mockResolvedValue(expectedUser);
+
+<% if (communication === 'GraphQL') { -%>
+            await userController.createUser(dataArg);
+<% } else { -%>
+            await userController.createUser(mockRequest, mockResponse, mockNext);
+<% } -%>
+            const { sendMessage } = require('@/infrastructure/messaging/kafkaClient');
+            expect(sendMessage).toHaveBeenCalledWith(
+                'user-topic',
+                expect.stringContaining('"id":"2"')
+            );
+        });
+<%_ } -%>
     });
 });

package/templates/clean-architecture/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/clean-architecture/ts/src/index.ts.ejs

@@ -8,11 +8,11 @@ import morgan from 'morgan';
 import { errorMiddleware } from '@/utils/errorMiddleware';
 import { setupGracefulShutdown } from '@/utils/gracefulShutdown';
 import healthRoutes from '@/interfaces/routes/healthRoute';
-<% if (communication === 'REST APIs') { -%>
+<% if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 import userRoutes from '@/interfaces/routes/userRoutes';
 import swaggerUi from 'swagger-ui-express';
-import swaggerSpecs from '@/config/swagger';<% } -%>
-<%_ if (communication === 'Kafka') { -%>import { KafkaService } from '@/infrastructure/messaging/kafkaClient';<%_ } -%>
+import swaggerSpecs from '@/config/swagger';<% } %>
+<%_ if (communication === 'Kafka') { -%>import { kafkaService } from '@/infrastructure/messaging/kafkaClient';<%_ } -%>
 <%_ if (communication === 'GraphQL') { -%>
 import { ApolloServer } from '@apollo/server';
 import { expressMiddleware } from '@apollo/server/express4';
@@ -52,10 +52,10 @@ 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/users', userRoutes);
 <%_ } -%>
-<%_ if (communication === 'REST APIs') { -%>
+<%_ if (communication === 'REST APIs' || communication === 'Kafka') { -%>
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpecs));
 <%_ } -%>
 app.use('/health', healthRoutes);
@@ -92,18 +92,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 Clean Arch 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/clean-architecture/ts/src/infrastructure/log/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';

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

@@ -11,6 +11,20 @@ jest.mock('@/infrastructure/repositories/UserRepository');
 jest.mock('@/usecases/createUser');
 jest.mock('@/usecases/getAllUsers');
 jest.mock('@/infrastructure/log/logger');
+<%_ if (communication === 'Kafka') { -%>
+jest.mock('@/infrastructure/messaging/kafkaClient', () => {
+    const mockSendMessage = jest.fn().mockResolvedValue(undefined);
+    return {
+        kafkaService: {
+            sendMessage: mockSendMessage
+        },
+        KafkaService: jest.fn().mockImplementation(() => ({
+            sendMessage: mockSendMessage
+        }))
+    };
+});
+<%_ } -%>
+
 
 describe('UserController (Clean Architecture)', () => {
     let userController: UserController;
@@ -115,7 +129,12 @@ describe('UserController (Clean Architecture)', () => {
             await userController.createUser(mockRequest as Request, mockResponse as Response, mockNext);
 
             // Assert
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = require('@/infrastructure/messaging/kafkaClient');
+            expect(kafkaService.sendMessage).toHaveBeenCalled();
+<%_ } -%>
             expect(mockResponse.status).toHaveBeenCalledWith(HTTP_STATUS.CREATED);
+
             expect(mockResponse.json).toHaveBeenCalledWith(expectedUser);
 <% } -%>
             expect(mockCreateUserUseCase.execute).toHaveBeenCalledWith(payload.name, payload.email);

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

@@ -22,6 +22,14 @@ export class UserController {
         try {
             const { name, email } = data;
             const user = await this.createUserUseCase.execute(name, email);
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = await import('@/infrastructure/messaging/kafkaClient');
+            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: unknown) {
             const message = error instanceof Error ? error.message : 'Unknown error';
@@ -45,6 +53,14 @@ export class UserController {
         try {
             const { name, email } = req.body;
             const user = await this.createUserUseCase.execute(name, email);
+<%_ if (communication === 'Kafka') { -%>
+            const { kafkaService } = await import('@/infrastructure/messaging/kafkaClient');
+            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: unknown) {
             const message = error instanceof Error ? error.message : 'Unknown error';

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/Dockerfile

@@ -4,6 +4,7 @@
 FROM node:22-alpine AS builder
 
 WORKDIR /app
+ENV NPM_CONFIG_UPDATE_NOTIFIER=false
 
 COPY package*.json ./
 COPY tsconfig*.json ./
@@ -24,6 +25,7 @@ FROM node:22-alpine AS production
 WORKDIR /app
 
 ENV NODE_ENV=production
+ENV NPM_CONFIG_UPDATE_NOTIFIER=false
 
 COPY package*.json ./
 

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

@@ -115,6 +115,29 @@ mutation CreateUser {
 API is exposed via **REST**.
 A Swagger UI for API documentation is available at:
 - **URL**: `http://localhost:3000/api-docs` (Dynamic based on PORT)
+<%_ } -%>
+
+<% if (communication === 'Kafka') { -%>
+## 📡 Testing Kafka Asynchronous Flow
+This project demonstrates a production-ready Kafka flow:
+1. **Producer**: When a user is created via the API, a `USER_CREATED` event is sent to `user-topic`.
+2. **Consumer**: `WelcomeEmailConsumer` listens to `user-topic` and simulates sending an email.
+
+### How to verify:
+1. Ensure infrastructure is running: `docker-compose up -d<% if (database !== 'None') { %> db<% } %><% if (caching === 'Redis') { %> redis<% } %><% if (communication === 'Kafka') { %> zookeeper kafka<% } %>`
+2. Start the app: `npm run dev`
+3. Trigger an event by creating a user (via Postman or curl):
+   ```bash
+   curl -X POST http://localhost:3000/api/users \
+     -H "Content-Type: application/json" \
+     -d '{"name": "Kafka Tester", "email": "kafka@example.com"}'
+   ```
+4. Observe the logs:
+   ```text
+   [Kafka] Producer: Sent USER_CREATED event for 'kafka@example.com'
+   [Kafka] Consumer: Received USER_CREATED. 
+   [Kafka] Consumer: 📧 Sending welcome email to 'kafka@example.com'... Done!
+   ```
 <% } -%>
 
 <% if (caching === 'Redis') { -%>
@@ -217,4 +240,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

package/templates/common/database/js/models/User.js.ejs

@@ -11,7 +11,8 @@ class UserModel {
   }
 
   static async create(data) {
-    const newUser = { id: String(this.mockData.length + 1), ...data };
+    const { id, ...rest } = data;
+    const newUser = { id: String(this.mockData.length + 1), ...rest };
     this.mockData.push(newUser);
     return newUser;
   }

package/templates/common/database/ts/models/User.ts.ejs

@@ -16,10 +16,11 @@ export default class UserModel {
     return this.mockData;
   }
 
-  static async create(data: Omit<User, 'id'>) {
-    const newUser = { id: String(this.mockData.length + 1), ...data };
+  static async create(data: Omit<User, 'id'> & { id?: string | number | null }) {
+    const { id, ...rest } = data;
+    const newUser: User = { id: String(this.mockData.length + 1), ...rest };
     this.mockData.push(newUser);
-    return newUser as User;
+    return newUser;
   }
 }
 <% } else { -%>

package/templates/common/eslint.config.mjs.ejs

@@ -1,6 +1,7 @@
 import eslint from '@eslint/js';
 import eslintConfigPrettier from 'eslint-config-prettier';
 import globals from 'globals';
+import importPlugin from 'eslint-plugin-import-x';
 <% if (language === 'TypeScript') { %>import tseslint from 'typescript-eslint';
 
 export default tseslint.config(
@@ -8,6 +9,15 @@ export default tseslint.config(
   ...tseslint.configs.recommended,
   eslintConfigPrettier,
   {
+    plugins: {
+      import: importPlugin,
+    },
+    settings: {
+      'import-x/resolver': {
+        typescript: true,
+        node: true,
+      },
+    },
     languageOptions: {
       globals: {
         ...globals.node,
@@ -17,16 +27,24 @@ export default tseslint.config(
     rules: {
       "no-console": "warn",
       "no-unused-vars": "off",
-      "@typescript-eslint/no-unused-vars": "warn",
+      "@typescript-eslint/no-unused-vars": ["warn", { 
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }],
       "@typescript-eslint/no-require-imports": "error",
+      "import/no-unresolved": [2, { "caseSensitive": false }]
     },
   },
   {
     files: ["**/*.test.ts", "**/*.spec.ts", "tests/**/*.ts"],
     rules: {
       "@typescript-eslint/no-require-imports": "off",
-      "@typescript-eslint/no-unused-vars": "warn",
+      "@typescript-eslint/no-unused-vars": ["warn", { 
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }],
       "@typescript-eslint/no-explicit-any": "off",
+      "import/no-unresolved": [2, { "caseSensitive": false }]
     },
   }
 );<% } else { %>
@@ -34,6 +52,14 @@ export default [
   eslint.configs.recommended,
   eslintConfigPrettier,
   {
+    plugins: {
+      import: importPlugin,
+    },
+    settings: {
+      'import-x/resolver': {
+        node: true,
+      },
+    },
     languageOptions: {
       ecmaVersion: 'latest',
       sourceType: 'module',
@@ -44,7 +70,8 @@ export default [
     },
     rules: {
       "no-console": "warn",
-      "no-unused-vars": "warn"
+      "no-unused-vars": "warn",
+      "import/no-unresolved": [2, { "caseSensitive": false }]
     }
   }
 ];<% } %>

package/templates/common/jest.config.js.ejs

@@ -13,9 +13,12 @@ module.exports = {
     "src/index",
     "src/app",
     "src/config/env",
+    "src/infrastructure/config/env",
     "src/config/swagger",
     "src/infrastructure/webserver/swagger",
-    "src/infrastructure/webserver/server"
+    "src/infrastructure/webserver/server",
+    "src/utils/logger",
+    "src/infrastructure/log/logger"
   ],
   coverageThreshold: {
     global: {

package/templates/common/kafka/js/messaging/baseConsumer.js.ejs

@@ -0,0 +1,30 @@
+const logger = require('<% if (architecture === "Clean Architecture") { %>../../infrastructure/log/logger<% } else { %>../utils/logger<% } %>');
+
+class BaseConsumer {
+  constructor() {
+    if (this.constructor === BaseConsumer) {
+      throw new Error("Abstract class 'BaseConsumer' cannot be instantiated.");
+    }
+  }
+
+  get topic() { throw new Error("Property 'topic' must be implemented"); }
+  get groupId() { throw new Error("Property 'groupId' must be implemented"); }
+
+  async onMessage({ message }) {
+    try {
+      const rawValue = message.value?.toString();
+      if (!rawValue) return;
+      
+      const data = JSON.parse(rawValue);
+      await this.handle(data);
+    } catch (error) {
+      logger.error(`[Kafka] Error processing message on topic ${this.topic}:`, error);
+    }
+  }
+
+  async handle(data) {
+    throw new Error("Method 'handle()' must be implemented");
+  }
+}
+
+module.exports = BaseConsumer;

package/templates/common/kafka/js/messaging/baseConsumer.spec.js.ejs

@@ -0,0 +1,58 @@
+const BaseConsumer = require('<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/baseConsumer<% } else { %>@/messaging/baseConsumer<% } %>');
+const logger = require('<% if (architecture === "Clean Architecture") { %>@/infrastructure/log/logger<% } else { %>@/utils/logger<% } %>');
+
+jest.mock('<% if (architecture === "Clean Architecture") { %>@/infrastructure/log/logger<% } else { %>@/utils/logger<% } %>');
+
+class TestConsumer extends BaseConsumer {
+    constructor() {
+        super();
+        this._topic = 'test-topic';
+    }
+    get topic() { return this._topic; }
+    get groupId() { return 'test-group'; }
+    async handle(data) {
+        logger.info('Handled', data);
+    }
+}
+
+describe('BaseConsumer', () => {
+    let consumer;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        consumer = new TestConsumer();
+    });
+
+    it('should throw error if instantiated directly', () => {
+        expect(() => new BaseConsumer()).toThrow("Abstract class 'BaseConsumer' cannot be instantiated.");
+    });
+
+    it('should process a valid message', async () => {
+        const message = { value: Buffer.from(JSON.stringify({ test: 'data' })) };
+        await consumer.onMessage({ message });
+        expect(logger.info).toHaveBeenCalledWith('Handled', { test: 'data' });
+    });
+
+    it('should handle invalid JSON', async () => {
+        const message = { value: Buffer.from('invalid-json') };
+        await consumer.onMessage({ message });
+        expect(logger.error).toHaveBeenCalledWith(
+            expect.stringContaining('[Kafka] Error processing message on topic test-topic:'),
+            expect.anything()
+        );
+    });
+
+    it('should skip empty messages', async () => {
+        const message = { value: null };
+        await consumer.onMessage({ message });
+        expect(logger.info).not.toHaveBeenCalled();
+    });
+
+    it('should throw if topic, groupId or handle are not implemented', async () => {
+        class IncompleteConsumer extends BaseConsumer {}
+        const incomplete = new IncompleteConsumer();
+        expect(() => incomplete.topic).toThrow("Property 'topic' must be implemented");
+        expect(() => incomplete.groupId).toThrow("Property 'groupId' must be implemented");
+        await expect(incomplete.handle({})).rejects.toThrow("Method 'handle()' must be implemented");
+    });
+});

package/templates/common/kafka/js/messaging/userEventSchema.js.ejs

@@ -0,0 +1,11 @@
+const { z } = require('zod');
+
+const UserEventSchema = z.object({
+  action: z.enum(['USER_CREATED', 'UPDATE_USER', 'DELETE_USER']),
+  payload: z.object({
+    id: z.union([z.string(), z.number()]),
+    email: z.string().email(),
+  }),
+});
+
+module.exports = { UserEventSchema };

package/templates/common/kafka/js/messaging/userEventSchema.spec.js.ejs

@@ -0,0 +1,27 @@
+const { UserEventSchema } = require('<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/schemas/userEventSchema<% } else { %>@/messaging/schemas/userEventSchema<% } %>');
+
+describe('UserEventSchema', () => {
+    it('should validate a correct USER_CREATED event', () => {
+        const validEvent = {
+            action: 'USER_CREATED',
+            payload: {
+                id: 1,
+                email: 'test@example.com'
+            }
+        };
+        const result = UserEventSchema.safeParse(validEvent);
+        expect(result.success).toBe(true);
+    });
+
+    it('should fail validation for invalid email', () => {
+        const invalidEvent = {
+            action: 'USER_CREATED',
+            payload: {
+                id: 1,
+                email: 'invalid-email'
+            }
+        };
+        const result = UserEventSchema.safeParse(invalidEvent);
+        expect(result.success).toBe(false);
+    });
+});