nodejs-quickstart-structure 1.15.1 → 1.16.0

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);
+    });
+});

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

@@ -0,0 +1,31 @@
+const BaseConsumer = require('../../baseConsumer');
+const logger = require('<% if (architecture === "Clean Architecture") { %>../../../../infrastructure/log/logger<% } else { %>../../../utils/logger<% } %>');
+const { UserEventSchema } = require('../../schemas/userEventSchema');
+
+class WelcomeEmailConsumer extends BaseConsumer {
+  constructor() {
+    super();
+  }
+
+  get topic() { return 'user-topic'; }
+  get groupId() { return 'welcome-email-group'; }
+
+  async handle(data) {
+    const result = UserEventSchema.safeParse(data);
+    
+    if (!result.success) {
+      logger.error('[Kafka] Invalid user event data:', result.error.format());
+      return;
+    }
+
+    const { action, payload } = result.data;
+
+    if (action === 'USER_CREATED') {
+      logger.info(`[Kafka] Consumer: Received USER_CREATED.`);
+      logger.info(`[Kafka] Consumer: 📧 Sending welcome email to '${payload.email}'... Done!`);
+      // In a real app, you would call an EmailService here
+    }
+  }
+}
+
+module.exports = WelcomeEmailConsumer;

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

@@ -0,0 +1,49 @@
+const WelcomeEmailConsumer = require('<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>@/messaging/consumers/instances/welcomeEmailConsumer<% } %>');
+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<% } %>');
+
+describe('WelcomeEmailConsumer', () => {
+    let consumer;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        consumer = new WelcomeEmailConsumer();
+    });
+
+    it('should log welcome email simulation for USER_CREATED action', async () => {
+        const data = {
+            action: 'USER_CREATED',
+            payload: {
+                id: 1,
+                email: 'test@example.com'
+            }
+        };
+
+        await consumer.handle(data);
+
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('[Kafka] Consumer: Received USER_CREATED.')
+        );
+        expect(logger.info).toHaveBeenCalledWith(
+            expect.stringContaining('📧 Sending welcome email to \'test@example.com\'... Done!')
+        );
+    });
+
+    it('should log error for invalid data', async () => {
+        const data = {
+            action: 'USER_CREATED',
+            payload: {
+                id: 1,
+                email: 'invalid-email'
+            }
+        };
+
+        await consumer.handle(data);
+
+        expect(logger.error).toHaveBeenCalledWith(
+            expect.stringContaining('[Kafka] Invalid user event data:'),
+            expect.anything()
+        );
+    });
+});

package/templates/common/kafka/js/services/kafkaService.js.ejs

@@ -1,34 +1,86 @@
 const { kafka } = require('../config/kafka');
-const logger = require('<%= loggerPath %>');
+const logger = require('<% if (architecture === "Clean Architecture") { %>../log/logger<% } else { %>../utils/logger<% } %>');
 
 let producer = null;
 let consumer = null;
+let isConnected = false;
+let connectionPromise = null;
 
-const connectKafka = async () => {
-    if (!producer) producer = kafka.producer();
-    if (!consumer) consumer = kafka.consumer({ groupId: 'test-group' });
-
-    await producer.connect();
-    await consumer.connect();
-    await consumer.subscribe({ topic: 'test-topic', fromBeginning: true });
-
-    await consumer.run({
-        eachMessage: async ({ _topic, _partition, message }) => {
-            logger.info({
-                value: message.value.toString(),
-            });
-        },
-    });
+const connectKafka = async (retries = 10) => {
+    if (connectionPromise) return connectionPromise;
+
+    connectionPromise = (async () => {
+        if (!producer) producer = kafka.producer();
+        if (!consumer) consumer = kafka.consumer({ groupId: 'test-group' });
+
+        let attempt = 0;
+        while (attempt < retries) {
+            try {
+                await producer.connect();
+                await consumer.connect();
+                logger.info('[Kafka] Producer connected successfully');
+                logger.info('[Kafka] Consumer connected successfully');
+                isConnected = true;
+
+                // Auto-register WelcomeEmailConsumer if it exists
+                try {
+                    const WelcomeEmailConsumer = require('<% if (architecture === "Clean Architecture") { %>../../interfaces/messaging/consumers/instances/welcomeEmailConsumer<% } else { %>../messaging/consumers/instances/welcomeEmailConsumer<% } %>');
+                    const welcomeConsumer = new WelcomeEmailConsumer();
+                    await consumer.subscribe({ topic: welcomeConsumer.topic, fromBeginning: true });
+                    logger.info(`[Kafka] Registered consumer for topic: ${welcomeConsumer.topic}`);
+
+                    await consumer.run({
+                        eachMessage: async (payload) => welcomeConsumer.onMessage(payload),
+                    });
+                } catch (error) {
+                    // Fallback or no consumers found
+                    await consumer.subscribe({ topic: 'user-topic', fromBeginning: true });
+                    await consumer.run({
+                        eachMessage: async ({ message }) => {
+                            logger.info({ value: message.value.toString() });
+                        },
+                    });
+                }
+                return; // Success
+            } catch (error) {
+                attempt++;
+                logger.error(`[Kafka] Connection attempt ${attempt} failed:`, error.message);
+                if (attempt >= retries) {
+                    throw error; // Rethrow after final attempt
+                }
+                await new Promise(res => setTimeout(res, 3000)); // Wait 3s between retries
+            }
+        }
+    })();
+
+    return connectionPromise;
 };
 
 const sendMessage = async (topic, message) => {
-    if (!producer) producer = kafka.producer();
-    await producer.send({
-        topic,
-        messages: [
-            { value: message },
-        ],
-    });
+    if (connectionPromise) {
+        await connectionPromise;
+    }
+
+    if (!isConnected) {
+        throw new Error('[Kafka] Producer not connected. Check logs for connection errors.');
+    }
+    
+    try {
+        await producer.send({
+            topic,
+            messages: [{ value: message }],
+        });
+        
+        try {
+            const parsed = JSON.parse(message);
+            logger.info(`[Kafka] Producer: Sent ${parsed.action} event for '${parsed.payload?.email || 'unknown'}'`);
+        } catch (error) {
+            logger.info(`[Kafka] Producer: Sent message to ${topic}`, error);
+        }
+    } catch (error) {
+        logger.error(`[Kafka] Failed to send message to ${topic}:`, error.message);
+        throw error;
+    }
 };
 
 const disconnectKafka = async () => {

package/templates/common/kafka/js/services/kafkaService.spec.js.ejs

@@ -1,7 +1,7 @@
 let kafka;
 let connectKafka, sendMessage, disconnectKafka;
 
-jest.mock('<%= configPath %>', () => ({
+jest.mock('<% if (architecture === "Clean Architecture") { %>@/infrastructure/config/kafka<% } else { %>@/config/kafka<% } %>', () => ({
     kafka: {
         producer: jest.fn().mockReturnValue({
             connect: jest.fn().mockResolvedValue(undefined),
@@ -17,15 +17,16 @@ jest.mock('<%= configPath %>', () => ({
     },
 }));
 
-jest.mock('<%= loggerPath %>');
+jest.mock('<% if (architecture === "Clean Architecture") { %>@/infrastructure/log/logger<% } else { %>@/utils/logger<% } %>');
 
 describe('Kafka Client', () => {
     beforeEach(async () => {
         jest.resetModules();
         jest.clearAllMocks();
-        kafka = require('<%= configPath %>').kafka;
-        ({ connectKafka, sendMessage, disconnectKafka } = require('<%= servicePath %>'));
-        await connectKafka();
+        jest.useFakeTimers();
+        jest.spyOn(global, 'setTimeout');
+        kafka = require('<% if (architecture === "Clean Architecture") { %>@/infrastructure/config/kafka<% } else { %>@/config/kafka<% } %>').kafka;
+        ({ connectKafka, sendMessage, disconnectKafka } = require('<% if (architecture === "Clean Architecture") { %>@/infrastructure/messaging/kafkaClient<% } else { %>@/services/kafkaService<% } %>'));
     });
 
     it('should connect producer and consumer', async () => {
@@ -35,11 +36,15 @@ describe('Kafka Client', () => {
 
         expect(producer.connect).toHaveBeenCalled();
         expect(consumer.connect).toHaveBeenCalled();
+        expect(consumer.subscribe).toHaveBeenCalledWith(expect.objectContaining({ fromBeginning: true }));
+        const subscribeCall = consumer.subscribe.mock.calls.find(call => call[0].topic === 'user-topic' || call[0].topic === 'test-topic');
+        expect(subscribeCall).toBeDefined();
     });
 
     it('should send a message', async () => {
+        await connectKafka();
         const topic = 'test-topic';
-        const message = 'test-message';
+        const message = JSON.stringify({ action: 'TEST', payload: { email: 'test@example.com' } });
         await sendMessage(topic, message);
         const producer = kafka.producer.mock.results[0].value;
 
@@ -49,12 +54,53 @@ describe('Kafka Client', () => {
         });
     });
 
+    it('should retry connection on failure', async () => {
+        // We need to re-require to get a fresh state
+        jest.resetModules();
+        const { connectKafka: retryConnectKafka } = require('<% if (architecture === "Clean Architecture") { %>@/infrastructure/messaging/kafkaClient<% } else { %>@/services/kafkaService<% } %>');
+        const kafkaConfig = require('<% if (architecture === "Clean Architecture") { %>@/infrastructure/config/kafka<% } else { %>@/config/kafka<% } %>');
+        
+        const newProducer = kafkaConfig.kafka.producer();
+        // Mock the next producer creation to return our controlled producer
+        kafkaConfig.kafka.producer.mockReturnValueOnce(newProducer);
+
+        newProducer.connect
+            .mockRejectedValueOnce(new Error('Connection failed'))
+            .mockResolvedValueOnce(undefined);
+        
+        const connectPromise = retryConnectKafka(2);
+        
+        await jest.advanceTimersByTimeAsync(10000); 
+        await connectPromise;
+        expect(newProducer.connect).toHaveBeenCalledTimes(2);
+    });
+
+    it('should throw error if producer not connected', async () => {
+        await expect(sendMessage('topic', 'msg')).rejects.toThrow('[Kafka] Producer not connected');
+    });
+
+    it('should log error when sendMessage fails', async () => {
+        await connectKafka();
+        const producer = kafka.producer.mock.results[0].value;
+        producer.send.mockRejectedValue(new Error('Send failed'));
+        
+        await expect(sendMessage('test-topic', 'msg')).rejects.toThrow('Send failed');
+    });
+
     it('should disconnect Kafka', async () => {
-        await disconnectKafka();
+        await connectKafka();
         const producer = kafka.producer.mock.results[0].value;
         const consumer = kafka.consumer.mock.results[0].value;
 
+        await disconnectKafka();
+
         expect(producer.disconnect).toHaveBeenCalled();
         expect(consumer.disconnect).toHaveBeenCalled();
     });
+
+    it('should allow connecting with custom retries', async () => {
+        await connectKafka(5);
+        // This is mainly for coverage of the retries parameter
+        expect(kafka.producer).toHaveBeenCalled();
+    });
 });

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

@@ -0,0 +1,50 @@
+import { BaseConsumer } from '<% if (architecture === "Clean Architecture") { %>@/interfaces/messaging/baseConsumer<% } else { %>@/messaging/baseConsumer<% } %>';
+import logger from '<%= loggerPath %>';
+
+jest.mock('<%= loggerPath %>');
+
+class TestConsumer extends BaseConsumer {
+    constructor() {
+        super();
+    }
+    get topic() { return 'test-topic'; }
+    get groupId() { return 'test-group'; }
+    async handle(data: any) {
+        logger.info('Handled', data);
+    }
+}
+
+describe('BaseConsumer', () => {
+    let consumer: TestConsumer;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        consumer = new TestConsumer();
+    });
+
+    it('should throw error if instantiated directly', () => {
+        // @ts-expect-error: Abstract class cannot be instantiated
+        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 } as any);
+        expect(logger.info).toHaveBeenCalledWith('Handled', { test: 'data' });
+    });
+
+    it('should handle invalid JSON', async () => {
+        const message = { value: Buffer.from('invalid-json') };
+        await consumer.onMessage({ message } as any);
+        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 } as any);
+        expect(logger.info).not.toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1,27 @@
+import { EachMessagePayload } from 'kafkajs';
+import logger from '<%= loggerPath %>';
+
+export abstract class BaseConsumer {
+  abstract topic: string;
+  abstract groupId: string;
+
+  public constructor() {
+    if (new.target === BaseConsumer) {
+      throw new Error("Abstract class 'BaseConsumer' cannot be instantiated.");
+    }
+  }
+
+  async onMessage({ message }: EachMessagePayload) {
+    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);
+    }
+  }
+
+  abstract handle(data: unknown): Promise<void>;
+}

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

@@ -0,0 +1,51 @@
+import { UserEventSchema } from '<% 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 validate a correct UPDATE_USER event', () => {
+        const validEvent = {
+            action: 'UPDATE_USER',
+            payload: {
+                id: 'abc-123',
+                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);
+    });
+
+    it('should fail validation for invalid action', () => {
+        const invalidEvent = {
+            action: 'INVALID_ACTION',
+            payload: {
+                id: 1,
+                email: 'test@example.com'
+            }
+        };
+        const result = UserEventSchema.safeParse(invalidEvent);
+        expect(result.success).toBe(false);
+    });
+});

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

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+
+export 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(),
+  }),
+});
+
+export type UserEvent = z.infer<typeof UserEventSchema>;