create-hest-app 0.1.0

package/templates/cqrs_scalar/.vscode/settings.json

@@ -0,0 +1,70 @@
+{
+  "prettier.enable": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+
+  // i18n-ally
+  "i18n-ally.enabledParsers": ["json"],
+  "i18n-ally.displayLanguage": "zh-CN",
+  "i18n-ally.localesPaths": ["i18n", "public/messages", "script/i18n"],
+  "i18n-ally.keystyle": "nested",
+
+  // 文件嵌套
+  "explorer.fileNesting.enabled": true,
+  "explorer.fileNesting.expand": true,
+  "explorer.fileNesting.patterns": {
+    "*.ts": "${basename}.md, ${basename}.d.ts, ${basename}.test.ts, ${basename}.spec.ts, ${basename}.stories.ts, ${basename}.stories.tsx",
+    "*.tsx": "${basename}.md, ${basename}.d.ts, ${basename}.test.tsx, ${basename}.spec.tsx, ${basename}.stories.ts, ${basename}.stories.tsx",
+    "*.js": "${basename}.md, ${basename}.d.ts, ${basename}.test.js, ${basename}.spec.js, ${basename}.stories.js, ${basename}.stories.jsx",
+    "*.jsx": "${basename}.md, ${basename}.d.ts, ${basename}.test.jsx, ${basename}.spec.jsx, ${basename}.stories.js, ${basename}.stories.jsx",
+    "*.env": ".env.local, .env.development, .env.production, .env.test",
+    "package.json": "package-lock.json, yarn.lock, pnpm-lock.yaml, .gitignore, .prettierrc, eslint.config.mjs, i18n.ts, components.json, postcss.config.mjs, tsconfig.json, eslint.config.ts, .prettierignore, bun.lock, .dockerignore",
+    "eslint.config.mjs": "eslint.config.cjs, eslint.config.jsx, eslint.config.ts, eslint.config.tsx",
+    "tsconfig.json": "tsconfig.cjs.json, tsconfig.jsx.json, tsconfig.ts.json, tsconfig.tsx.json",
+    "tailwind.config.mjs": "tailwind.config.cjs, tailwind.config.jsx, tailwind.config.ts, tailwind.config.tsx",
+    "next.config.ts": "next.config.cjs, next.config.jsx, next.config.tsx, next-env.d.ts"
+  },
+
+  // ESLint 配置
+  "eslint.enable": true,
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact"
+  ],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "explicit"
+  },
+  "eslint.alwaysShowStatus": true,
+
+  // TypeScript 配置
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.suggest.autoImports": true,
+
+  // 额外的文件排除
+  "files.exclude": {
+    "**/.git": true,
+    "**/.svn": true,
+    "**/.hg": true,
+    "**/CVS": true,
+    "**/.DS_Store": true,
+    "**/Thumbs.db": true
+    // "**/node_modules": true,
+    // "**/.next": true
+  },
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/bower_components": true,
+    "**/*.code-search": true,
+    "**/.next": true,
+    "**/dist": true
+  }
+}

package/templates/cqrs_scalar/README.md

@@ -0,0 +1,234 @@
+# @hestjs/cqrs
+
+HestJS CQRS - Command Query Responsibility Segregation module for HestJS
+
+## 安装
+
+```bash
+npm install @hestjs/cqrs
+```
+
+## 基本用法
+
+### 1. 初始化CQRS模块
+
+```typescript
+import { CqrsModule } from "@hestjs/cqrs";
+
+// 基本初始化
+CqrsModule.forRoot();
+
+// 或者使用选项
+CqrsModule.forRoot({
+  // 自定义配置
+});
+```
+
+### 2. 创建Command
+
+```typescript
+import { Command } from "@hestjs/cqrs";
+
+export class CreateUserCommand extends Command<string> {
+  constructor(
+    public readonly name: string,
+    public readonly email: string
+  ) {
+    super();
+  }
+}
+```
+
+### 3. 创建Command Handler
+
+```typescript
+import { CommandHandler, ICommandHandler } from "@hestjs/cqrs";
+import { CreateUserCommand } from "./create-user.command";
+
+@CommandHandler(CreateUserCommand)
+export class CreateUserHandler
+  implements ICommandHandler<CreateUserCommand, string>
+{
+  async execute(command: CreateUserCommand): Promise<string> {
+    // 处理命令逻辑
+    console.log(`Creating user: ${command.name} (${command.email})`);
+    return "user-id-123";
+  }
+}
+```
+
+### 4. 创建Query
+
+```typescript
+import { Query, IQueryResult } from "@hestjs/cqrs";
+
+export class GetUserQuery extends Query<GetUserResult> {
+  constructor(public readonly userId: string) {
+    super();
+  }
+}
+
+export class GetUserResult implements IQueryResult {
+  constructor(
+    public readonly id: string,
+    public readonly name: string,
+    public readonly email: string
+  ) {}
+}
+```
+
+### 5. 创建Query Handler
+
+```typescript
+import { QueryHandler, IQueryHandler } from "@hestjs/cqrs";
+import { GetUserQuery, GetUserResult } from "./get-user.query";
+
+@QueryHandler(GetUserQuery)
+export class GetUserHandler
+  implements IQueryHandler<GetUserQuery, GetUserResult>
+{
+  async execute(query: GetUserQuery): Promise<GetUserResult> {
+    // 查询逻辑
+    return new GetUserResult(query.userId, "John Doe", "john@example.com");
+  }
+}
+```
+
+### 6. 创建Event
+
+```typescript
+import { Event } from "@hestjs/cqrs";
+
+export class UserCreatedEvent extends Event {
+  constructor(
+    public readonly userId: string,
+    public readonly name: string,
+    public readonly email: string
+  ) {
+    super(userId);
+  }
+}
+```
+
+### 7. 创建Event Handler
+
+```typescript
+import { EventsHandler, IEventHandler } from "@hestjs/cqrs";
+import { UserCreatedEvent } from "./user-created.event";
+
+@EventsHandler(UserCreatedEvent)
+export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
+  async handle(event: UserCreatedEvent): Promise<void> {
+    // 处理事件逻辑
+    console.log(`User created: ${event.name} (${event.email})`);
+  }
+}
+```
+
+### 8. 在控制器中使用
+
+```typescript
+import { Controller, Post } from "@hestjs/core";
+import { CommandBus, QueryBus, EventBus } from "@hestjs/cqrs";
+import { CreateUserCommand } from "./commands/create-user.command";
+import { GetUserQuery } from "./queries/get-user.query";
+import { UserCreatedEvent } from "./events/user-created.event";
+
+@Controller("/users")
+export class UserController {
+  constructor(
+    private readonly commandBus: CommandBus,
+    private readonly queryBus: QueryBus,
+    private readonly eventBus: EventBus
+  ) {}
+
+  @Post()
+  async createUser(data: { name: string; email: string }) {
+    const command = new CreateUserCommand(data.name, data.email);
+    const userId = await this.commandBus.execute(command);
+
+    // 发布事件
+    const event = new UserCreatedEvent(userId, data.name, data.email);
+    await this.eventBus.publish(event);
+
+    return { userId };
+  }
+
+  @Get("/:id")
+  async getUser(id: string) {
+    const query = new GetUserQuery(id);
+    return await this.queryBus.execute(query);
+  }
+}
+```
+
+### 9. 注册处理器
+
+```typescript
+import { CqrsModule } from "@hestjs/cqrs";
+import { CreateUserHandler } from "./handlers/create-user.handler";
+import { GetUserHandler } from "./handlers/get-user.handler";
+import { UserCreatedHandler } from "./handlers/user-created.handler";
+
+// 初始化CQRS模块
+CqrsModule.forRoot();
+
+// 获取CQRS模块实例
+const cqrsModule = CqrsModule.getInstance();
+
+// 注册处理器
+cqrsModule.registerHandler(CreateUserHandler);
+cqrsModule.registerHandler(GetUserHandler);
+cqrsModule.registerHandler(UserCreatedHandler);
+
+// 启动应用时调用
+await cqrsModule.onApplicationBootstrap();
+```
+
+### 10. Saga (长期运行的流程)
+
+```typescript
+import { Saga, ICommand } from "@hestjs/cqrs";
+import { UserCreatedEvent } from "./events/user-created.event";
+import { SendWelcomeEmailCommand } from "./commands/send-welcome-email.command";
+
+@Saga()
+export class UserSaga {
+  // 当用户创建事件发生时，发送欢迎邮件
+  async onUserCreatedEvent(event: UserCreatedEvent): Promise<ICommand[]> {
+    return [new SendWelcomeEmailCommand(event.userId, event.email)];
+  }
+}
+```
+
+## API 参考
+
+### 装饰器
+
+- `@CommandHandler(command)` - 标记命令处理器
+- `@QueryHandler(query)` - 标记查询处理器
+- `@EventsHandler(...events)` - 标记事件处理器
+- `@Saga()` - 标记Saga
+
+### 基类
+
+- `Command<T>` - 命令基类，T为返回类型
+- `Query<T>` - 查询基类，T为结果类型
+- `Event` - 事件基类
+
+### 总线
+
+- `CommandBus` - 命令总线
+- `QueryBus` - 查询总线
+- `EventBus` - 事件总线
+
+### 接口
+
+- `ICommandHandler<TCommand, TResult>` - 命令处理器接口
+- `IQueryHandler<TQuery, TResult>` - 查询处理器接口
+- `IEventHandler<TEvent>` - 事件处理器接口
+- `ISaga<TEvent>` - Saga接口
+
+## 许可证
+
+MIT

package/templates/cqrs_scalar/eslint.config.ts

@@ -0,0 +1,26 @@
+import wfConfig from '@hestjs/eslint-config';
+
+export default [
+  ...wfConfig,
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    rules: {
+      'no-console': 'error', // Demo 应用允许使用 console 进行调试
+    },
+  },
+  {
+    // 忽略构建产物和临时文件
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'build/**',
+      '*.d.ts',
+      '.bun/**',
+      'bun.lockb',
+      // shadcn 目录
+      'src/components/ui/**',
+      // scripts 目录
+      'scripts/**',
+    ],
+  },
+];

package/templates/cqrs_scalar/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_scalar/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_scalar/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_scalar/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_scalar/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_scalar/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_scalar/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();