create-hest-app 0.1.0

package/templates/cqrs/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@hestjs/cqrs-demo",
+  "version": "0.1.1",
+  "description": "HestJS Demo Application - A demonstration of HestJS framework capabilities",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run --hot src/index.ts",
+    "build": "bun build src/index.ts --outdir=dist --target=bun --format=esm --splitting --external pino --external pino-pretty --external sonic-boom --external thread-stream",
+    "build:external": "bun build src/index.ts --outdir=dist --target=bun --format=esm --external reflect-metadata --external pino --external pino-pretty --external sonic-boom --external thread-stream",
+    "build:binary": "bun build src/index.ts --compile --outfile=dist/hest-demo --external pino-pretty",
+    "start": "bun run dist/index.js | pino-pretty",
+    "start:binary": "./dist/hest-demo | pino-pretty",
+    "start:prod": "NODE_ENV=production bun run dist/index.js | pino-pretty",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aqz236/hestjs-cqrs-demo.git"
+  },
+  "homepage": "https://github.com/aqz236/hestjs-cqrs-demo#readme",
+  "bugs": {
+    "url": "https://github.com/aqz236/hestjs-cqrs-demo/issues"
+  },
+  "author": "aqz236",
+  "license": "MIT",
+  "dependencies": {
+    "@hestjs/core": "^0.1.8",
+    "@hestjs/validation": "^0.1.5",
+    "@hestjs/cqrs": "^0.1.2",
+    "hono": "^4.8.9",
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@hestjs/eslint-config": "^0.1.1",
+    "@hestjs/typescript-config": "^0.1.0",
+    "@types/bun": "^1.2.19",
+    "jiti": "^2.5.1",
+    "typescript": "5.8.3"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "hestjs",
+    "demo",
+    "framework",
+    "typescript",
+    "bun",
+    "hono",
+    "validation"
+  ]
+}

package/templates/cqrs/src/app.controller.ts

@@ -0,0 +1,28 @@
+import { Controller, Get } from '@hestjs/core';
+import { AppService } from './app.service';
+
+@Controller('/')
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get('/')
+  getHello() {
+    return {
+      message: this.appService.getHello(),
+      description: 'HestJS CQRS Demo - A demonstration of CQRS pattern using HestJS framework',
+      endpoints: {
+        users: {
+          getAll: 'GET /users',
+          getById: 'GET /users/:id',
+          create: 'POST /users',
+          update: 'PUT /users/:id',
+        },
+      },
+    };
+  }
+
+  @Get('/error')
+  throwError() {
+    throw new Error('This is a test error for exception handling');
+  }
+}

package/templates/cqrs/src/app.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@hestjs/core';
+import { CqrsModule } from '@hestjs/cqrs';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { UserModule } from './users';
+
+@Module({
+  imports: [CqrsModule.forRoot(), UserModule],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}

package/templates/cqrs/src/app.service.ts

@@ -0,0 +1,8 @@
+import { Injectable } from '@hestjs/core';
+
+@Injectable()
+export class AppService {
+  getHello(): string {
+    return 'Welcome to HestJS CQRS Demo! 🚀';
+  }
+}

package/templates/cqrs/src/common/filters/http-exception.filter.ts

@@ -0,0 +1,34 @@
+import type {
+  ArgumentsHost,
+  ExceptionFilter,
+  HttpException,
+} from '@hestjs/core';
+import { createLogger } from '@hestjs/core';
+
+const logger = createLogger('HttpExceptionFilter');
+
+/**
+ * 自定义 HTTP 异常过滤器
+ */
+export class HttpExceptionFilter implements ExceptionFilter<HttpException> {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const ctx = host.getContext();
+    const request = host.getRequest();
+
+    const status = exception.status;
+    const response = {
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      message: exception.message,
+      error: exception.error || 'Http Exception',
+    };
+
+    logger.error(`🔥 HTTP Exception [${status}]: ${exception.message}`, {
+      requestUrl: request.url,
+      stack: exception.stack,
+    });
+
+    return ctx.json(response, status);
+  }
+}

package/templates/cqrs/src/common/interceptors/response.interceptor.ts

@@ -0,0 +1,38 @@
+import type { CallHandler, ExecutionContext, Interceptor } from '@hestjs/core';
+import { createLogger } from '@hestjs/core';
+
+const logger = createLogger('ResponseInterceptor');
+
+/**
+ * 响应转换拦截器
+ */
+export class ResponseInterceptor implements Interceptor {
+  async intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Promise<{
+    success: boolean;
+    data: unknown;
+    timestamp: string;
+    duration: string;
+  }> {
+    const startTime = Date.now();
+    const request = context.switchToHttp().getRequest();
+
+    logger.info(`🚀  Request: ${request.method} ${request.url}`);
+
+    const result = await next.handle();
+
+    const duration = Date.now() - startTime;
+    logger.info(
+      `✅ Response: ${request.method} ${request.url} - ${duration}ms`,
+    );
+
+    return {
+      success: true,
+      data: result,
+      timestamp: new Date().toISOString(),
+      duration: `${duration}ms`,
+    };
+  }
+}

package/templates/cqrs/src/index.ts

@@ -0,0 +1,38 @@
+import { HestFactory, logger } from '@hestjs/core';
+import { ValidationInterceptor } from '@hestjs/validation';
+import { cors } from 'hono/cors';
+import { logger as log } from 'hono/logger';
+import { AppModule } from './app.module';
+import { HttpExceptionFilter } from './common/filters/http-exception.filter';
+import { ResponseInterceptor } from './common/interceptors/response.interceptor';
+
+async function bootstrap() {
+  try {
+    logger.info('🚀 Starting HestJS application...');
+
+    const app = await HestFactory.create(AppModule);
+    app.hono().use(cors()); // 使用 Hono 的 CORS 中间件
+    app.hono().use('*', log()); // 使用 Hono 的日志中间件
+
+    // 全局拦截器 - 验证拦截器应该在响应拦截器之前
+    app.useGlobalInterceptors(new ValidationInterceptor());
+    app.useGlobalInterceptors(new ResponseInterceptor());
+
+    // 全局异常过滤器
+    app.useGlobalFilters(new HttpExceptionFilter());
+
+    const server = Bun.serve({
+      port: 3002,
+      fetch: app.hono().fetch,
+      reusePort: true, // 启用端口复用
+    });
+
+    logger.info(`🎉 Server is running on http://localhost:${server.port}`);
+  } catch (error) {
+    // 使用新的简化语法直接传递错误对象
+    logger.error('❌ Failed to start application:', error);
+    process.exit(1);
+  }
+}
+
+bootstrap();

package/templates/cqrs/src/modules/custom-validation/custom-validation.controller.ts

@@ -0,0 +1,146 @@
+import { Controller, Get, Post } from '@hestjs/core';
+import { Body } from '@hestjs/validation';
+import { CustomValidationDto, SearchQueryDto } from './dto/custom-validation.dto';
+import { CustomValidationService } from './custom-validation.service';
+
+/**
+ * 自定义验证控制器 - 展示 TypeBox 自定义验证功能
+ */
+@Controller('/api/custom')
+export class CustomValidationController {
+  constructor(
+    private readonly customValidationService: CustomValidationService,
+  ) {}
+
+  @Get('/')
+  async getInfo() {
+    return {
+      success: true,
+      message: 'HestJS 自定义验证功能示例',
+      features: [
+        '🔧 TypeBox 自定义 Schema 验证',
+        '🏗️ SchemaFactory 便捷构建器',
+        '📦 CommonValidators 常用验证',
+        '🔗 联合类型验证',
+        '📐 嵌套对象验证',
+        '📱 中国手机号验证',
+        '🔗 UUID 验证',
+        '📍 地理坐标验证',
+      ],
+      endpoints: {
+        'POST /api/custom/validate': '测试自定义验证',
+        'POST /api/custom/search': '测试搜索参数验证',
+        'GET /api/custom/examples': '获取验证示例',
+      },
+    };
+  }
+
+  @Post('/validate')
+  async validateCustomData(
+    @Body(CustomValidationDto) data: CustomValidationDto,
+  ) {
+    const result = this.customValidationService.processCustomData(data);
+    return {
+      success: true,
+      message: '自定义验证通过！',
+      result,
+      validationInfo: {
+        username: `用户名 "${data.username}" 通过正则验证`,
+        role: `角色 "${data.role}" 通过联合类型验证`,
+        userId: `UUID "${data.userId}" 格式验证通过`,
+        phoneNumber: data.phoneNumber
+          ? `手机号 "${data.phoneNumber}" 通过中国手机号验证`
+          : '未提供手机号',
+        location: data.location
+          ? `坐标 (${data.location.lat}, ${data.location.lng}) 验证通过`
+          : '未提供坐标',
+        emails: data.emails
+          ? `邮箱列表包含 ${data.emails.length} 个地址`
+          : '未提供邮箱',
+      },
+    };
+  }
+
+  @Post('/search')
+  async searchWithValidation(@Body(SearchQueryDto) query: SearchQueryDto) {
+    const result = this.customValidationService.processSearch(query);
+    return {
+      success: true,
+      message: '搜索参数验证通过！',
+      result,
+      validationInfo: {
+        query: query.q || '无搜索关键词',
+        pagination: query.pagination || '使用默认分页',
+      },
+    };
+  }
+
+  @Get('/examples')
+  async getValidationExamples() {
+    return {
+      success: true,
+      message: '自定义验证示例',
+      examples: {
+        customValidation: {
+          description: 'POST /api/custom/validate',
+          validExample: {
+            username: 'john_doe123',
+            role: 'user',
+            userId: '123e4567-e89b-12d3-a456-426614174000',
+            phoneNumber: '13812345678',
+            location: { lat: 39.9042, lng: 116.4074 },
+            emails: ['john@example.com', 'john.doe@company.com'],
+          },
+          invalidExample: {
+            username: 'a', // 太短
+            role: 'invalid_role', // 不在联合类型中
+            userId: 'not-a-uuid', // 无效 UUID
+            phoneNumber: '123456', // 无效手机号
+            location: { lat: 200, lng: 200 }, // 超出范围
+            emails: ['invalid-email', 'another@invalid'], // 无效邮箱
+          },
+        },
+        searchValidation: {
+          description: 'POST /api/custom/search',
+          validExample: {
+            q: 'TypeScript',
+            pagination: {
+              page: 1,
+              limit: 10,
+              sort: 'createdAt',
+              order: 'desc',
+            },
+          },
+          invalidExample: {
+            q: 123, // 应该是字符串
+            pagination: {
+              page: 0, // 应该 >= 1
+              limit: 1000, // 应该 <= 100
+              order: 'invalid', // 应该是 'asc' 或 'desc'
+            },
+          },
+        },
+      },
+      typeboxFeatures: {
+        basicTypes: [
+          'Type.String()',
+          'Type.Number()',
+          'Type.Boolean()',
+          'Type.Array()',
+        ],
+        advancedTypes: [
+          'Type.Union()',
+          'Type.Object()',
+          'Type.Intersect()',
+          'Type.Optional()',
+        ],
+        formats: ['email', 'date', 'date-time', 'uri', 'uuid'],
+        patterns: ['正则表达式验证', '长度限制', '数值范围', '枚举值'],
+        customValidators: [
+          'SchemaFactory 便捷方法',
+          'CommonValidators 常用验证',
+        ],
+      },
+    };
+  }
+}

package/templates/cqrs/src/modules/custom-validation/custom-validation.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@hestjs/core';
+import { CustomValidationController } from './custom-validation.controller';
+import { CustomValidationService } from './custom-validation.service';
+
+@Module({
+  controllers: [CustomValidationController],
+  providers: [CustomValidationService],
+  exports: [CustomValidationService],
+})
+export class CustomValidationModule {}

package/templates/cqrs/src/modules/custom-validation/custom-validation.service.ts

@@ -0,0 +1,33 @@
+import { Injectable } from '@hestjs/core';
+import type { CustomValidationDto, SearchQueryDto } from './dto/custom-validation.dto';
+
+/**
+ * 自定义验证服务
+ */
+@Injectable()
+export class CustomValidationService {
+  processCustomData(data: CustomValidationDto) {
+    // 模拟处理逻辑
+    return {
+      processed: true,
+      data: {
+        ...data,
+        processedAt: new Date().toISOString(),
+        validation: 'TypeBox 自定义验证通过',
+      },
+    };
+  }
+
+  processSearch(query: SearchQueryDto) {
+    // 模拟搜索逻辑
+    return {
+      results: [
+        { id: 1, title: '搜索结果 1', relevance: 0.95 },
+        { id: 2, title: '搜索结果 2', relevance: 0.87 },
+      ],
+      query,
+      total: 2,
+      searchedAt: new Date().toISOString(),
+    };
+  }
+}

package/templates/cqrs/src/modules/custom-validation/dto/custom-validation.dto.ts

@@ -0,0 +1,132 @@
+import {
+  CommonValidators,
+  Custom,
+  IsOptional,
+  IsString,
+  SchemaFactory,
+} from '@hestjs/validation';
+import { Type } from '@sinclair/typebox';
+
+/**
+ * 展示自定义验证功能的简化 DTO
+ */
+export class CustomValidationDto {
+  // 使用基础的 TypeBox API
+  @Custom(
+    Type.String({ minLength: 3, maxLength: 20, pattern: '^[a-zA-Z0-9_]+$' }),
+    {
+      message: '用户名必须是3-20位字母、数字或下划线',
+    },
+  )
+  username!: string;
+
+  // 使用联合类型
+  @Custom(
+    Type.Union([
+      Type.Literal('admin'),
+      Type.Literal('user'),
+      Type.Literal('guest'),
+    ]),
+    {
+      message: '角色必须是 admin、user 或 guest',
+    },
+  )
+  role!: 'admin' | 'user' | 'guest';
+
+  // 使用 CommonValidators 的便捷方法
+  @CommonValidators.UUID({ message: '必须是有效的 UUID' })
+  userId!: string;
+
+  // 使用 SchemaFactory 的便捷方法
+  @Custom(SchemaFactory.chinesePhoneNumber(), {
+    message: '必须是有效的中国手机号',
+    optional: true,
+  })
+  phoneNumber?: string;
+
+  // 自定义对象验证
+  @Custom(
+    Type.Object({
+      lat: Type.Number({ minimum: -90, maximum: 90 }),
+      lng: Type.Number({ minimum: -180, maximum: 180 }),
+    }),
+    { optional: true, message: '坐标必须在有效范围内' },
+  )
+  location?: {
+    lat: number;
+    lng: number;
+  };
+
+  // 数组验证
+  @Custom(Type.Array(Type.String({ format: 'email' })), {
+    optional: true,
+    message: '邮箱列表必须是有效的邮箱地址数组',
+  })
+  emails?: string[];
+}
+
+/**
+ * 搜索查询 DTO - 展示复杂对象验证
+ */
+export class SearchQueryDto {
+  @IsOptional()
+  @IsString({ message: '搜索关键词必须是字符串' })
+  q?: string;
+
+  // 使用 SchemaFactory 构建复杂的分页对象
+  @Custom(
+    Type.Object({
+      page: Type.Number({ minimum: 1 }),
+      limit: Type.Number({ minimum: 1, maximum: 100 }),
+      sort: Type.Optional(Type.String()),
+      order: Type.Optional(
+        Type.Union([Type.Literal('asc'), Type.Literal('desc')]),
+      ),
+    }),
+    {
+      optional: true,
+      message: '分页参数格式错误',
+    },
+  )
+  pagination?: {
+    page: number;
+    limit: number;
+    sort?: string;
+    order?: 'asc' | 'desc';
+  };
+
+  // 使用联合类型进行复杂验证
+  @Custom(
+    Type.Union([
+      Type.Array(Type.String()),
+      Type.String(),
+      Type.Null(),
+      Type.Undefined(),
+    ]),
+    {
+      optional: true,
+      message: '标签可以是字符串、字符串数组或空值',
+    },
+  )
+  tags?: string | string[] | null;
+
+  // 使用数值范围验证
+  @Custom(Type.Number({ minimum: 0, maximum: 100 }), {
+    optional: true,
+    message: '评分必须在 0-100 之间',
+  })
+  score?: number;
+
+  // 使用日期字符串验证
+  @Custom(Type.String({ format: 'date' }), {
+    optional: true,
+    message: '开始日期格式必须是 YYYY-MM-DD',
+  })
+  startDate?: string;
+
+  @Custom(Type.String({ format: 'date' }), {
+    optional: true,
+    message: '结束日期格式必须是 YYYY-MM-DD',
+  })
+  endDate?: string;
+}

package/templates/cqrs/src/modules/users/dto/user.dto.ts

@@ -0,0 +1,64 @@
+import {
+  IsEmail,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Length,
+  Max,
+  Min,
+} from '@hestjs/validation';
+
+/**
+ * 创建用户 DTO
+ */
+export class CreateUserDto {
+  @IsString({
+    minLength: 2,
+    maxLength: 50,
+    message: '用户名长度必须在2-50字符之间',
+  })
+  name!: string;
+
+  @IsEmail({ message: '请输入有效的邮箱地址' })
+  email!: string;
+
+  @IsNumber({ message: '年龄必须是数字' })
+  @Min(0, { message: '年龄不能小于0' })
+  @Max(120, { message: '年龄不能大于120' })
+  age!: number;
+
+  @IsString({ message: '密码必须是字符串' })
+  @Length(8, 100, { message: '密码长度必须在8-100字符之间' })
+  password!: string;
+
+  @IsOptional()
+  @IsString({ message: '个人简介必须是字符串' })
+  bio?: string;
+}
+
+/**
+ * 更新用户 DTO
+ */
+export class UpdateUserDto {
+  @IsOptional()
+  @IsString({
+    minLength: 2,
+    maxLength: 50,
+    message: '用户名长度必须在2-50字符之间',
+  })
+  name?: string;
+
+  @IsOptional()
+  @IsEmail({ message: '请输入有效的邮箱地址' })
+  email?: string;
+
+  @IsOptional()
+  @IsNumber({ message: '年龄必须是数字' })
+  @Min(0, { message: '年龄不能小于0' })
+  @Max(120, { message: '年龄不能大于120' })
+  age?: number;
+
+  @IsOptional()
+  @IsString({ message: '个人简介必须是字符串' })
+  bio?: string;
+}

package/templates/cqrs/src/modules/users/entities/user.entity.ts

@@ -0,0 +1,9 @@
+// 定义用户类型
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+  age: number;
+  password?: string;
+  bio?: string;
+}

package/templates/cqrs/src/modules/users/users.controller.ts

@@ -0,0 +1,68 @@
+import type { HestContext } from '@hestjs/core';
+import { Context, Controller, Get, Post } from '@hestjs/core';
+import { Body } from '@hestjs/validation';
+import { CreateUserDto, UpdateUserDto } from './dto/user.dto';
+import { UsersService } from './users.service';
+
+/**
+ * 用户控制器 - 展示验证功能
+ */
+@Controller('/users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get('/')
+  async getAllUsers() {
+    return {
+      success: true,
+      data: this.usersService.findAll(),
+      message: 'Users retrieved successfully',
+    };
+  }
+
+  @Get('/:id')
+  async getUser(@Context() c: HestContext) {
+    const id = parseInt(c.req.param('id'));
+    const user = this.usersService.findOne(id);
+
+    if (!user) {
+      return c.json(
+        {
+          success: false,
+          message: 'User not found',
+        },
+        404,
+      );
+    }
+
+    return {
+      success: true,
+      data: user,
+      message: 'User retrieved successfully',
+    };
+  }
+
+  @Post('/')
+  async createUser(@Body(CreateUserDto) createUserDto: CreateUserDto) {
+    const newUser = this.usersService.create(createUserDto);
+    return {
+      success: true,
+      data: newUser,
+      message: 'User created successfully',
+    };
+  }
+
+  @Post('/:id')
+  async updateUser(
+    @Context() c: HestContext,
+    @Body(UpdateUserDto) updateUserDto: UpdateUserDto,
+  ) {
+    const id = parseInt(c.req.param('id'));
+    const updatedUser = this.usersService.update(id, updateUserDto);
+    return {
+      success: true,
+      data: updatedUser,
+      message: 'User updated successfully',
+    };
+  }
+}