@gravito/scaffold 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -24,6 +24,8 @@ interface ProfileConfig {
     };
     /** List of enabled features and orbits. */
     features: string[];
+    /** Workers configuration level for job queue system */
+    workers?: 'basic' | 'advanced' | 'production';
 }
 /**
  * ProfileResolver manages the resolution of project profiles and feature add-ons.
@@ -204,6 +206,8 @@ interface ScaffoldOptions {
     targetDir: string;
     /** The primary architectural pattern to apply. */
     architecture: ArchitectureType;
+    /** For DDD architecture: the module template type. @default 'simple' */
+    dddModuleType?: 'simple' | 'advanced' | 'cqrs-query';
     /** Preferred package manager for dependency installation. @default 'bun' */
     packageManager?: 'bun' | 'npm' | 'yarn' | 'pnpm';
     /** Whether to run `git init` in the target directory. @default true */
@@ -374,6 +378,13 @@ declare class CleanArchitectureGenerator extends BaseGenerator {
  * - Each context has Domain, Application, Infrastructure, UserInterface layers
  */
 
+/**
+ * DDD Module Type options
+ * - simple: Basic CRUD structure
+ * - advanced: Complete Event Sourcing with Aggregates, Events, EventStore, and EventApplier
+ * - cqrs-query: CQRS Query Side with Read Models, Event Projectors, Query Services
+ */
+type DddModuleType = 'simple' | 'advanced' | 'cqrs-query';
 /**
  * DddGenerator implements the full Domain-Driven Design (DDD) architectural pattern.
  *
@@ -381,18 +392,36 @@ declare class CleanArchitectureGenerator extends BaseGenerator {
  * Value Objects, Domain Events, and a Shared Kernel. It is ideal for complex
  * enterprise applications with rich business logic.
  *
+ * Supports multiple module templates:
+ * - **simple**: Basic DDD structure with CRUD operations
+ * - **advanced**: Complete Event Sourcing with Aggregate Roots, Domain Events, EventStore
+ * - **cqrs-query**: CQRS read-side with Event Projectors and denormalized Read Models
+ *
  * @public
  * @since 3.0.0
  */
 declare class DddGenerator extends BaseGenerator {
     private moduleGenerator;
+    private advancedModuleGenerator;
+    private cqrsQueryModuleGenerator;
     private sharedKernelGenerator;
     private bootstrapGenerator;
+    private moduleType;
     constructor(config: GeneratorConfig);
+    /**
+     * Set the module type for generated modules
+     * @param type - 'simple' for basic CRUD, 'advanced' for Event Sourcing, 'cqrs-query' for CQRS Read Side
+     * @default 'simple'
+     */
+    setModuleType(type: DddModuleType): void;
     get architectureType(): "ddd";
     get displayName(): string;
     get description(): string;
     getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
+    /**
+     * Get the active module generator type
+     */
+    private getModuleGenerator;
     /**
      * Override package.json for DDD architecture (uses main.ts instead of bootstrap.ts)
      */
@@ -400,6 +429,207 @@ declare class DddGenerator extends BaseGenerator {
     protected generateArchitectureDoc(context: GeneratorContext): string;
 }
 
+/**
+ * AdvancedModuleGenerator - 進階 DDD 模組生成器（Event Sourcing）
+ *
+ * 為 Bounded Context 生成完整的 Event Sourcing 架構：
+ * - Aggregate Root（聚合根）
+ * - Domain Events（領域事件，支援版本管理）
+ * - Event Store（InMemory + Database 實現）
+ * - EventApplier（純函式事件應用）
+ * - EventDeserializer（事件反序列化）
+ * - 自動化的測試框架
+ *
+ * 使用場景：
+ * ```bash
+ * bun run scaffold Payment --type advanced
+ * # 生成完整的 Payment 模組，包含 Event Sourcing 支援
+ * ```
+ */
+
+declare class AdvancedModuleGenerator {
+    /**
+     * 生成進階 DDD 模組結構（Event Sourcing）
+     *
+     * 生成檔案：
+     * - Domain/AggregateRoots/{Name}.ts
+     * - Domain/Events/{Name}*Event.ts（3 個事件示例）
+     * - Domain/Services/{Name}EventApplier.ts
+     * - Domain/Repositories/I{Name}EventStore.ts
+     * - Domain/ValueObjects/{Name}Status.ts
+     * - Infrastructure/EventStore/InMemory{Name}EventStore.ts
+     * - Infrastructure/EventStore/Database{Name}EventStore.ts
+     * - Infrastructure/EventStore/{Name}EventDeserializer.ts
+     * - Application/Services/Create{Name}Service.ts
+     * - 完整的測試框架
+     */
+    generate(moduleName: string, _context: GeneratorContext): DirectoryNode;
+    private generateAggregateRoot;
+    private generateEvent;
+    private generateStatusValueObject;
+    private generateIdValueObject;
+    private generateEventApplier;
+    private generateEventStoreInterface;
+    private generateInMemoryEventStore;
+    private generateDatabaseEventStore;
+    private generateEventDeserializer;
+    private generateApplicationService;
+    private generateDTO;
+    private generateController;
+    private generateRoutes;
+    private generateModuleIndex;
+    private toKebabCase;
+    private toSnakeCase;
+}
+
+/**
+ * CQRSQueryModuleGenerator - CQRS 查詢側模組生成器
+ *
+ * 為查詢側（讀端）生成完整的 CQRS 架構：
+ * - Read Model（讀模型，查詢優化的數據結構）
+ * - Event Projector（事件投影器，將事件轉化為讀模型）
+ * - Query Service（查詢服務，提供查詢接口）
+ * - Event Subscriber（事件訂閱器，監聽並投影事件）
+ * - HTTP Controllers（查詢端點）
+ *
+ * 與 Phase 2a AdvancedModuleGenerator 配合使用：
+ * - Phase 2a: 寫側（事件溯源）
+ * - Phase 2b: 讀側（CQRS 投影） ← 本生成器
+ *
+ * 使用場景：
+ * ```bash
+ * bun run scaffold WalletBalance --type cqrs-query
+ * # 生成完整的查詢模組，訂閱來自 PSC 模組的事件
+ *
+ * bun run scaffold MemberStats --type cqrs-query
+ * # 生成會員統計查詢模組，訂閱來自 MOC 模組的事件
+ * ```
+ */
+
+interface CQRSQueryConfig {
+    moduleName: string;
+    modulePrefix?: string;
+    description?: string;
+    readModel: {
+        fields: FieldDefinition[];
+        primaryKey: string;
+        indexes?: string[];
+    };
+    events: {
+        subscribedEvents: EventMapping[];
+    };
+    queries?: {
+        methods: QueryMethodDefinition[];
+    };
+    cache?: {
+        enabled: boolean;
+        ttl?: number;
+    };
+}
+interface FieldDefinition {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'date' | 'decimal';
+    description?: string;
+    indexed?: boolean;
+}
+interface EventMapping {
+    eventType: string;
+    eventClass: string;
+    handlerMethod: string;
+    updates: FieldUpdate[];
+}
+interface FieldUpdate {
+    fieldName: string;
+    operation: 'set' | 'add' | 'increment';
+}
+interface QueryMethodDefinition {
+    name: string;
+    parameters: QueryParameter[];
+    returnType: string;
+    description?: string;
+}
+interface QueryParameter {
+    name: string;
+    type: string;
+    required?: boolean;
+}
+/**
+ * CQRS 查詢側模組生成器
+ * 生成完整的查詢端（讀側）模組架構
+ */
+declare class CQRSQueryModuleGenerator {
+    /**
+     * 生成 CQRS 查詢側模組結構
+     *
+     * 生成檔案：
+     * - Domain/ReadModels/{Name}ReadModel.ts
+     * - Domain/Projectors/{Name}EventProjector.ts
+     * - Application/Services/Query{Name}Service.ts
+     * - Application/DTOs/{Name}ReadDTO.ts
+     * - Infrastructure/Subscribers/{Name}ProjectionSubscriber.ts
+     * - Infrastructure/Cache/{Name}ReadModelCache.ts
+     * - Presentation/Controllers/{Name}QueryController.ts
+     * - index.ts
+     *
+     * @param moduleName - 模組名稱（例：'Wallet'）
+     * @param _context - 生成器上下文（當前未使用，預留供未來擴展）
+     * @returns 模組目錄結構
+     */
+    generate(moduleName: string, _context: GeneratorContext): DirectoryNode;
+    /**
+     * 生成讀模型檔案
+     */
+    private generateReadModel;
+    /**
+     * 生成事件投影器檔案
+     */
+    private generateProjector;
+    /**
+     * 生成查詢服務檔案
+     */
+    private generateQueryService;
+    /**
+     * 生成查詢 DTO 檔案
+     */
+    private generateQueryDTO;
+    /**
+     * 生成倉庫介面
+     */
+    private generateRepositoryInterface;
+    /**
+     * 生成倉庫實現
+     */
+    private generateRepositoryImplementation;
+    /**
+     * 生成事件訂閱器
+     */
+    private generateSubscriber;
+    /**
+     * 生成快取層
+     */
+    private generateCache;
+    /**
+     * 生成 HTTP 控制器
+     */
+    private generateController;
+    /**
+     * 生成路由檔案
+     */
+    private generateRoutes;
+    /**
+     * 生成模組索引檔案
+     */
+    private generateIndex;
+    /**
+     * 將字符串轉換為 kebab-case
+     */
+    private toKebabCase;
+    /**
+     * 將字符串轉換為 snake_case
+     */
+    private toSnakeCase;
+}
+
 /**
  * EnterpriseMvcGenerator - Enterprise MVC Architecture Generator
  *
@@ -466,10 +696,15 @@ declare class SatelliteGenerator extends BaseGenerator {
     get displayName(): string;
     get description(): string;
     getDirectoryStructure(context: GeneratorContext): DirectoryNode[];
-    private generateEntity;
+    private generateIdValueObject;
+    private generateAggregate;
+    private generateCreatedEvent;
     private generateRepositoryInterface;
     private generateUseCase;
     private generateAtlasRepository;
+    private generateUnitTest;
+    private generateIntegrationTest;
+    private generateController;
     private generateEntryPoint;
     private generateManifest;
     protected generatePackageJson(context: GeneratorContext): string;
@@ -669,7 +904,8 @@ declare class Scaffold {
      */
     create(options: ScaffoldOptions): Promise<ScaffoldResult>;
     /**
-     * Create a generator for the specified architecture.
+     * Create a generator for the specified architecture with options.
+     * @param options - Scaffold options including architecture type and module type for DDD
      */
     private createGenerator;
     /**
@@ -684,4 +920,4 @@ declare class Scaffold {
     generateProvider(_targetDir: string, _providerName: string): Promise<ScaffoldResult>;
 }
 
-export { type ArchitectureType, BaseGenerator, CleanArchitectureGenerator, DddGenerator, DependencyValidator, type DetectedEnvironment, EnterpriseMvcGenerator, EnvironmentDetector, FileMerger, type GeneratorConfig, type GeneratorContext, type LockFile, LockGenerator, type PackageJson, type ProfileConfig, ProfileResolver, type ProfileType, SatelliteGenerator, Scaffold, type ScaffoldOptions, type StubConfig, StubGenerator, type StubVariables, type ValidationResult };
+export { AdvancedModuleGenerator, type ArchitectureType, BaseGenerator, type CQRSQueryConfig, CQRSQueryModuleGenerator, CleanArchitectureGenerator, DddGenerator, type DddModuleType, DependencyValidator, type DetectedEnvironment, EnterpriseMvcGenerator, EnvironmentDetector, FileMerger, type GeneratorConfig, type GeneratorContext, type LockFile, LockGenerator, type PackageJson, type ProfileConfig, ProfileResolver, type ProfileType, SatelliteGenerator, Scaffold, type ScaffoldOptions, type StubConfig, StubGenerator, type StubVariables, type ValidationResult };