feat: new features, reusable schema validator, DTO implementation and update template generation

.github/workflows/deploy.yml

@@ -20,7 +20,7 @@ jobs:
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
 
       - name: 📥 Install pnpm
         run: npm install -g pnpm
@@ -44,7 +44,7 @@ jobs:
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
 
       - name: 📥 Install pnpm
         run: npm install -g pnpm
@@ -68,7 +68,7 @@ jobs:
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
 
       - name: 📥 Install pnpm
         run: npm install -g pnpm

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "pavittarx.moleculer-snippets"
+    ]
+}

README.md

@@ -1,6 +1,6 @@
 # Welcome to moleculer-typescript-template 👋
 
-![Version](https://img.shields.io/badge/version-0.1.1-blue.svg?cacheSeconds=2592000)
+![Version](https://img.shields.io/badge/version-0.3.0-blue.svg?cacheSeconds=2592000)
 ![Prerequisite](https://img.shields.io/badge/node-%3E%3D%2014.x.x-blue.svg)
 [![Twitter: jellydn](https://img.shields.io/twitter/follow/jellydn.svg?style=social)](https://twitter.com/jellydn)
 
@@ -18,7 +18,7 @@
 
 ## Prerequisites
 
-- node >= 18.17.x
+- node >= 20.0.0
 
 ## Init new project
 
@@ -36,6 +36,10 @@ npx degit jellydn/moleculer-typescript-template [PROJECT-NAME]
 - ✨ [moleculer-zod-validator](https://github.com/TheAppleFreak/moleculer-zod-validator) - A validator for the Moleculer microservice framework to allow the use of [Zod](https://zod.dev/).
 - 🔏 [asteasolutions/zod-to-openapi](https://github.com/asteasolutions/zod-to-openapi#defining-schemas) - A library that generates OpenAPI (Swagger) docs from Zod schemas.
 - 🪄 [hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) - Turn your OpenAPI specification into a beautiful TypeScript client.
+- 🔐 **Enhanced Validation** - Shared validation utilities with Zod schemas for consistent parameter validation across all services.
+- 📝 **Comprehensive Documentation** - Auto-generated Swagger documentation with complete error handling (200, 422, 500 responses).
+- 🎯 **Type Safety** - Strong TypeScript typing throughout the application with proper service interfaces.
+- 📊 **Structured Responses** - Consistent JSON response format with `success`, `message`, and `data` fields.
 
 ## Install
 
@@ -51,7 +55,7 @@ cp .env.example .env
 pnpm dev
 ```
 
-After starting, open the http://localhost:3000/ URL in your browser.
+After starting, open the <http://localhost:3000/> URL in your browser.
 On the welcome page you can test the generated services via API Gateway and check the nodes & services.
 ![https://gyazo.com/c8a8c8b05319504d36922458d9807db2.gif](https://gyazo.com/c8a8c8b05319504d36922458d9807db2.gif)
 
@@ -72,6 +76,17 @@ In the terminal, try the following commands:
 
 This project uses [hygen](http://www.hygen.io/) to generate code templates, saving you time and ensuring consistency across your codebase.
 
+## Code Generation
+
+All generated templates include modern best practices:
+
+- ✅ **Automatic validation** with shared `validateParams` utility
+- ✅ **Complete Swagger documentation** with error responses
+- ✅ **Strong TypeScript typing** with proper service interfaces
+- ✅ **Structured JSON responses** with consistent format
+- ✅ **Validation hooks** for all actions
+- ✅ **Comprehensive logging** throughout the application
+
 ### Adding a New Service
 
 To add a new service to your project, use the following command:
@@ -80,6 +95,14 @@ To add a new service to your project, use the following command:
 pnpm generate:service [service-name]
 ```
 
+This generates a basic service with:
+
+- Two sample actions (`hello` and `welcome`)
+- Validation hooks with `validateParams` integration
+- Complete Swagger documentation
+- Strong TypeScript typing
+- Structured error handling
+
 ### Adding a New Action to a Service
 
 To add a new action to an existing service, use the following command:
@@ -88,6 +111,13 @@ To add a new action to an existing service, use the following command:
 pnpm generate:action [action-name] --service [service-name]
 ```
 
+Generated actions include:
+
+- Parameter validation with Zod schemas
+- Complete Swagger documentation with error codes
+- Structured JSON response format
+- TypeScript interfaces for parameters and responses
+
 ### Generating CRUD Services
 
 To generate a service with Create, Read, Update, and Delete (CRUD) operations, use the following command:
@@ -96,6 +126,150 @@ To generate a service with Create, Read, Update, and Delete (CRUD) operations, u
 pnpm generate:crud [service-name]
 ```
 
+This creates a complete CRUD service with:
+
+- **5 actions**: `create`, `list`, `view`, `update`, `delete`
+- **Pagination support** in list actions
+- **Validation hooks** in all actions
+- **Complete Swagger documentation** for all endpoints
+- **Structured responses** with success/error handling
+- **Authentication** and **authorization** ready
+
+### Generating Data Transfer Objects (DTOs)
+
+To generate Zod schemas with OpenAPI documentation, use:
+
+```sh
+pnpm generate:dto [dto-name]
+```
+
+This generates:
+
+- **Zod schemas** with OpenAPI annotations
+- **Automatic YAML generation** for Swagger integration
+- **Type-safe validation** for request/response data
+- **Reusable schemas** across services
+
+## Enhanced Template Features
+
+### 🔐 Automatic Parameter Validation
+
+All generated actions include automatic parameter validation using Zod schemas:
+
+```typescript
+// Generated validation hook in every action
+hooks: {
+  before(ctx) {
+    this.logger.info('Validating parameters for [action] action');
+    validateParams(ctx, yourSchema); // Automatically included
+  },
+}
+```
+
+### 📖 Complete Swagger Documentation
+
+Every generated action includes comprehensive Swagger documentation:
+
+- **Request/Response schemas** with examples
+- **Error response codes** (422 for validation, 500 for server errors)
+- **Parameter descriptions** and constraints
+- **Security requirements** for protected endpoints
+
+### 🎯 Type-Safe Development
+
+All templates generate strongly-typed TypeScript code:
+
+- **Service interfaces** with proper method signatures
+- **Context typing** for action parameters
+- **Response type definitions** for consistent returns
+- **Generic repository interfaces** for data access
+
+### 📊 Structured JSON Responses
+
+Consistent response format across all services:
+
+```json
+{
+  "success": true,
+  "message": "Operation completed successfully",
+  "data": {},
+  "pagination": {
+    "page": 1,
+    "limit": 10,
+    "total": 0
+  }
+}
+```
+
+## Architecture & Patterns
+
+This template implements several architectural patterns and best practices:
+
+### Shared Validation Utilities
+
+All services use a shared validation utility (`services/common/validation.utils.ts`) that provides:
+
+- **Consistent validation** across all services
+- **Zod schema integration** with Moleculer context
+- **Automatic error handling** with structured error responses
+- **TypeScript type safety** for validation parameters
+
+```typescript
+// Usage in any service action
+hooks: {
+  before(ctx) {
+    validateParams(ctx, yourZodSchema);
+  },
+}
+```
+
+### Structured Response Format
+
+All actions return a consistent JSON structure:
+
+```typescript
+// Success Response
+{
+  "success": true,
+  "message": "Operation completed successfully",
+  "data": { /* your data here */ }
+}
+
+// Error Response
+{
+  "error": "Parameters validation error!",
+  "code": "VALIDATION_ERROR"
+}
+```
+
+### Repository Pattern
+
+The template includes an example repository pattern implementation for data access:
+
+- **Interface-based design** for easy testing and swapping implementations
+- **Type-safe operations** with TypeScript
+- **Separation of concerns** between business logic and data access
+
+### Service Organization
+
+Services are organized with a clear structure:
+
+```text
+services/
+├── common/           # Shared utilities and interfaces
+│   ├── index.ts
+│   ├── validation.utils.ts
+│   └── repository.interface.ts
+├── dtos/            # Data Transfer Objects with Zod schemas
+│   ├── [name].dto.ts
+│   └── [name]-dto.swagger.yaml
+└── [service]/       # Individual service folders
+    ├── [service].service.ts
+    ├── [service].repository.ts
+    └── actions/     # Action implementations
+        └── [action].action.ts
+```
+
 ## API Documentation
 
 This template also reads your [JSDoc-annotated](https://github.com/Surnet/swagger-jsdoc/blob/v6/docs/README.md) source code and generates an OpenAPI (Swagger) specification.
@@ -106,7 +280,7 @@ Run the following command to generate the Swagger documentation:
 pnpm generate:swagger
 ```
 
-Open the http://localhost:3000/docs URL in your browser, you will see the Swagger UI as
+Open the <http://localhost:3000/docs> URL in your browser, you will see the Swagger UI as
 
 ![https://gyazo.com/a4fe2413414c94dde636a531eee1a4a0.gif](https://gyazo.com/a4fe2413414c94dde636a531eee1a4a0.gif)
 
@@ -149,8 +323,8 @@ We use GitHub Actions for continuous integration and deployment. Anything that g
 
 ## Useful links
 
-- Moleculer website: https://moleculer.services/
-- Moleculer Documentation: https://moleculer.services/docs/0.14/
+- Moleculer website: <https://moleculer.services/>
+- Moleculer Documentation: <https://moleculer.services/docs/0.14/>
 
 ## NPM scripts
 
@@ -162,6 +336,15 @@ We use GitHub Actions for continuous integration and deployment. Anything that g
 - `pnpm dc:up`: Start the stack with Docker Compose
 - `pnpm dc:down`: Stop the stack with Docker Compose
 
+### Code Generation Scripts
+
+- `pnpm generate:service [name]`: Generate a new basic service with validation and documentation
+- `pnpm generate:crud [name]`: Generate a complete CRUD service with all operations
+- `pnpm generate:action [name] --service [service]`: Add a new action to an existing service
+- `pnpm generate:dto [name]`: Generate Zod schemas with OpenAPI documentation
+- `pnpm generate:swagger`: Generate OpenAPI documentation from JSDoc comments
+- `pnpm generate:sdk`: Generate TypeScript client from OpenAPI specification
+
 ## Pre-commit hooks
 
 This template uses [Pre-commit](https://pre-commit.com/) to run checks before you commit your code. This ensures that your code is formatted correctly and passes all tests before you push it to your repository.
@@ -180,7 +363,7 @@ pre-commit run --all-files
 
 👤 **Dung Huynh**
 
-- Website: https://productsway.com/
+- Website: <https://productsway.com/>
 - Twitter: [@jellydn](https://twitter.com/jellydn)
 - Github: [@jellydn](https://github.com/jellydn)
 

_templates/action/new/hello.ejs.t

@@ -2,14 +2,17 @@
 to: services/<%= service %>/actions/<%= name %>.action.ts
 ---
 import type { Context, ServiceActionsSchema } from "moleculer";
+import { validateParams } from "../../common";
 
 /**
  * The <%= name %> action.
  *
  * @swagger
- * /welcome:
+ * /api/<%= service %>/<%= name %>:
  *   get:
  *     summary: Returns a greeting and calculates the age in days.
+ *     tags:
+ *       - <%= service %>
  *     parameters:
  *       - in: query
  *         name: name
@@ -27,20 +30,43 @@ import type { Context, ServiceActionsSchema } from "moleculer";
  *       200:
  *         description: A greeting message and the age in days.
  *         content:
- *           text/plain:
+ *           application/json:
  *             schema:
- *               type: string
- *               example: "Hello John, you are 10950 days old!"
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: "Hello John, you are 10950 days old!"
+ *                 success:
+ *                   type: boolean
+ *                   example: true
+ *       422:
+ *         description: Validation error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 error:
+ *                   type: string
+ *                   example: Parameters validation error!
  */
 const <%= name %>Action: ServiceActionsSchema = {
 	rest: {
 		method: "GET",
-		path: "/welcome",
+		path: "/<%= name %>",
 	},
 	params: {
 		name: "string",
 		age: "number",
 	},
+	hooks: {
+		before(ctx) {
+			this.logger.info('Validating parameters for <%= name %> action');
+			// Add your validation schema here
+			// validateParams(ctx, your<%= h.capitalize(name) %>Schema);
+		},
+	},
 	handler: <%= name %>Handler,
 };
 
@@ -52,11 +78,14 @@ function <%= name %>Handler(
 		name: string;
 		age: number;
 	}>,
-): string {
+): { message: string; success: boolean } {
 	// Calculate the age in days
 	const ageInDays = ctx.params.age * 365;
 
-	return `Hello ${ctx.params.name}, you are ${ageInDays} days old!`;
+	return {
+		message: `Hello ${ctx.params.name}, you are ${ageInDays} days old!`,
+		success: true,
+	};
 }
 
 export default <%= name %>Action;