create-easy-stack 1.0.3

package/templates/nest-ddd/files/plop-templates/module/presentation/mappers/{{kebab}}.mapper.ts.hbs

@@ -0,0 +1,13 @@
+import { {{Pascal}} } from '../../domain/index.js';
+import { {{Pascal}}ResponseDto } from '../dtos/{{kebab}}-response.dto.js';
+
+export class {{Pascal}}Mapper {
+  static toResponse(entity: {{Pascal}}): {{Pascal}}ResponseDto {
+    return {
+      id: entity.id,
+      name: entity.name,
+      createdAt: entity.createdAt,
+      updatedAt: entity.updatedAt,
+    };
+  }
+}

package/templates/nest-ddd/files/plop-templates/module/{{kebab}}.module.ts.hbs

@@ -0,0 +1,40 @@
+import { Module } from '@nestjs/common';
+import { CqrsModule } from '@nestjs/cqrs';
+
+// Controllers
+import { {{Pascal}}Controller } from './presentation/index.js';
+
+// Handlers
+import {
+  Create{{Pascal}}Handler,
+  Get{{Pascal}}ByIdHandler,
+  // @plop:handler-imports
+} from './application/index.js';
+
+// Repositories
+import { {{#if prisma}}Prisma{{else}}InMemory{{/if}}{{Pascal}}Repository } from './infrastructure/index.js';
+
+const CommandHandlers = [
+  Create{{Pascal}}Handler,
+  // @plop:command-handlers
+];
+const QueryHandlers = [
+  Get{{Pascal}}ByIdHandler,
+  // @plop:query-handlers
+];
+
+@Module({
+  imports: [CqrsModule],
+  controllers: [{{Pascal}}Controller],
+  providers: [
+    // Repositories
+    {
+      provide: 'I{{Pascal}}Repository',
+      useClass: {{#if prisma}}Prisma{{else}}InMemory{{/if}}{{Pascal}}Repository,
+    },
+    // Handlers
+    ...CommandHandlers,
+    ...QueryHandlers,
+  ],
+})
+export class {{Pascal}}Module {}

package/templates/nest-ddd/files/plop-templates/persistence-memory/infrastructure/database/repositories/in-memory-{{kebab}}.repository.ts.hbs

@@ -0,0 +1,17 @@
+import { Injectable } from '@nestjs/common';
+import { I{{Pascal}}Repository, {{Pascal}} } from '../../../domain/index.js';
+
+/** Non-persistent adapter (data is lost on restart). Replace it with a real adapter, e.g. Prisma. */
+@Injectable()
+export class InMemory{{Pascal}}Repository implements I{{Pascal}}Repository {
+  private readonly items = new Map<string, {{Pascal}}>();
+
+  async findById(id: string): Promise<{{Pascal}} | null> {
+    return this.items.get(id) ?? null;
+  }
+
+  async save(entity: {{Pascal}}): Promise<void> {
+    this.items.set(entity.id, entity);
+    entity.clearEvents();
+  }
+}

package/templates/nest-ddd/files/plop-templates/persistence-memory/infrastructure/index.ts.hbs

@@ -0,0 +1 @@
+export * from './database/repositories/in-memory-{{kebab}}.repository.js';

package/templates/nest-ddd/files/plop-templates/persistence-prisma/infrastructure/database/mappers/{{kebab}}.mapper.ts.hbs

@@ -0,0 +1,29 @@
+import type { {{Pascal}} as Prisma{{Pascal}} } from '@prisma/client';
+import { {{Pascal}} } from '../../../domain/index.js';
+
+type MutableEntity<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+
+/**
+ * Data mapper: translates between the database row (Prisma) and the domain entity, so the
+ * domain never depends on the ORM.
+ */
+export class {{Pascal}}PersistenceMapper {
+  static toDomain(row: Prisma{{Pascal}}): {{Pascal}} {
+    const entity = new {{Pascal}}({ name: row.name }, row.id);
+
+    // Hydrate the read-only audit fields. Wrapped in `new Date(...)` so it also works when the
+    // row came back from a JSON cache (dates arrive as ISO strings there).
+    const mutable = entity as MutableEntity<{{Pascal}}>;
+    mutable.createdAt = new Date(row.createdAt);
+    mutable.updatedAt = new Date(row.updatedAt);
+    return entity;
+  }
+
+  static toPersistence(
+    entity: {{Pascal}},
+  ): Omit<Prisma{{Pascal}}, 'createdAt' | 'updatedAt'> {
+    return { id: entity.id, name: entity.name };
+  }
+}

package/templates/nest-ddd/files/plop-templates/persistence-prisma/infrastructure/database/repositories/prisma-{{kebab}}.repository.ts.hbs

@@ -0,0 +1,28 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { PrismaService } from '@/core/index.js';
+import { I{{Pascal}}Repository, {{Pascal}} } from '../../../domain/index.js';
+import { {{Pascal}}PersistenceMapper } from '../mappers/{{kebab}}.mapper.js';
+
+@Injectable()
+export class Prisma{{Pascal}}Repository implements I{{Pascal}}Repository {
+  private readonly logger = new Logger(Prisma{{Pascal}}Repository.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findById(id: string): Promise<{{Pascal}} | null> {
+    this.logger.debug(`Finding {{kebab}} by ID: ${id}`);
+    const row = await this.prisma.{{camel}}.findUnique({ where: { id } });
+    return row ? {{Pascal}}PersistenceMapper.toDomain(row) : null;
+  }
+
+  async save(entity: {{Pascal}}): Promise<void> {
+    this.logger.debug(`Saving {{kebab}}: ${entity.id}`);
+    const data = {{Pascal}}PersistenceMapper.toPersistence(entity);
+    await this.prisma.{{camel}}.upsert({
+      where: { id: data.id },
+      create: data,
+      update: data,
+    });
+    entity.clearEvents();
+  }
+}

package/templates/nest-ddd/files/plop-templates/persistence-prisma/infrastructure/index.ts.hbs

@@ -0,0 +1,2 @@
+export * from './database/mappers/{{kebab}}.mapper.js';
+export * from './database/repositories/prisma-{{kebab}}.repository.js';

package/templates/nest-ddd/files/plop-templates/query/handler.ts.hbs

@@ -0,0 +1,28 @@
+import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
+import { Inject, Logger } from '@nestjs/common';
+import { {{Pascal}}Query } from './{{kebab}}.query.js';
+import { {{ModulePascal}}, {{ModulePascal}}DomainException } from '../../domain/index.js';
+import type { I{{ModulePascal}}Repository } from '../../domain/index.js';
+import { {{ModulePascal}}ErrorCodes } from '@/core/index.js';
+
+@QueryHandler({{Pascal}}Query)
+export class {{Pascal}}Handler implements IQueryHandler<{{Pascal}}Query> {
+  private readonly logger = new Logger({{Pascal}}Handler.name);
+
+  constructor(
+    @Inject('I{{ModulePascal}}Repository')
+    private readonly repo: I{{ModulePascal}}Repository,
+  ) {}
+
+  async execute(query: {{Pascal}}Query): Promise<{{ModulePascal}}> {
+    this.logger.debug(`Executing {{Pascal}}Query for ${query.id}`);
+
+    const entity = await this.repo.findById(query.id);
+    if (!entity) {
+      throw new {{ModulePascal}}DomainException(
+        {{ModulePascal}}ErrorCodes.{{ModuleConstant}}_NOT_FOUND,
+      );
+    }
+    return entity;
+  }
+}

package/templates/nest-ddd/files/plop-templates/query/query.ts.hbs

@@ -0,0 +1,5 @@
+import { IQuery } from '@nestjs/cqrs';
+
+export class {{Pascal}}Query implements IQuery {
+  constructor(public readonly id: string) {}
+}

package/templates/nest-ddd/files/plop-templates/snippets/error-codes.hbs

@@ -0,0 +1,14 @@
+export const {{Pascal}}ErrorCodes = {
+  {{CONSTANT}}_NOT_FOUND: {
+    code: '{{CODE}}-001',
+    message: '{{Pascal}} not found',
+    status: HttpStatus.NOT_FOUND,
+  },
+  {{CONSTANT}}_INVALID_NAME: {
+    code: '{{CODE}}-002',
+    message: '{{Pascal}} name must not be empty',
+    status: HttpStatus.BAD_REQUEST,
+  },
+};
+
+// @plop:error-codes

package/templates/nest-ddd/files/plop-templates/snippets/prisma-model.hbs

@@ -0,0 +1,7 @@
+
+model {{Pascal}} {
+  id        String   @id
+  name      String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}

package/templates/nest-ddd/files/plopfile.mjs

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+
+/**
+ * Generators for the NestJS DDD + CQRS structure.
+ *
+ *   pnpm gen module     a whole bounded context (domain / application / infrastructure / presentation)
+ *   pnpm gen command    a command + handler inside an existing module (auto-registered)
+ *   pnpm gen query      a query + handler inside an existing module (auto-registered)
+ *
+ * Templates live in plop-templates/. The `// @plop:*` comments in the generated files are
+ * the anchors these generators write into — keep them.
+ */
+
+const MODULES_DIR = 'src/modules';
+const hasPrisma = fs.existsSync('prisma/schema.prisma');
+
+const listModules = () =>
+  fs.existsSync(MODULES_DIR)
+    ? fs
+        .readdirSync(MODULES_DIR, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+    : [];
+
+const pluralize = (word) => {
+  if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/.test(word)) return `${word}es`;
+  return `${word}s`;
+};
+
+const requiredKebab = (label) => (value) =>
+  /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(value) ||
+  `${label} must be kebab-case, e.g. "order-item"`;
+
+export default function (plop) {
+  const pascal = plop.getHelper('pascalCase');
+  const camel = plop.getHelper('camelCase');
+  const constant = plop.getHelper('constantCase');
+  const kebab = plop.getHelper('kebabCase');
+
+  // ── module ────────────────────────────────────────────────────────────────
+  plop.setGenerator('module', {
+    description: 'Bounded context: entity, repository port, CQRS handlers, controller, module',
+    prompts: [
+      {
+        type: 'input',
+        name: 'name',
+        message: 'Module name (singular, kebab-case, e.g. "order" or "order-item"):',
+        validate: requiredKebab('Name'),
+      },
+      {
+        type: 'list',
+        name: 'persistence',
+        message: 'Persistence adapter:',
+        choices: [
+          { name: 'Prisma (adds a model to prisma/schema.prisma)', value: 'prisma' },
+          { name: 'In-memory (swap for a real adapter later)', value: 'memory' },
+        ],
+        default: hasPrisma ? 'prisma' : 'memory',
+      },
+    ],
+    actions: (answers) => {
+      Object.assign(answers, {
+        kebab: kebab(answers.name),
+        Pascal: pascal(answers.name),
+        camel: camel(answers.name),
+        CONSTANT: constant(answers.name),
+        CODE: answers.name.replace(/[^a-z]/g, '').slice(0, 3).toUpperCase().padEnd(3, 'X'),
+        plural: pluralize(kebab(answers.name)),
+      });
+      const target = 'src/modules/{{kebab}}';
+      const actions = [
+        {
+          type: 'addMany',
+          destination: target,
+          base: 'plop-templates/module',
+          templateFiles: 'plop-templates/module/**/*',
+          globOptions: { dot: true },
+          abortOnFail: true,
+        },
+        {
+          type: 'addMany',
+          destination: target,
+          base: `plop-templates/persistence-${answers.persistence}`,
+          templateFiles: `plop-templates/persistence-${answers.persistence}/**/*`,
+          abortOnFail: true,
+        },
+        {
+          type: 'modify',
+          path: 'src/app.module.ts',
+          pattern: /\/\/ @plop:module-imports/,
+          template:
+            "import { {{Pascal}}Module } from './modules/{{kebab}}/{{kebab}}.module.js';\n// @plop:module-imports",
+        },
+        {
+          type: 'modify',
+          path: 'src/app.module.ts',
+          pattern: /\/\/ @plop:modules/,
+          template: '{{Pascal}}Module,\n    // @plop:modules',
+        },
+        {
+          type: 'modify',
+          path: 'src/core/domain/exceptions/error-codes.ts',
+          pattern: /\/\/ @plop:error-codes/,
+          templateFile: 'plop-templates/snippets/error-codes.hbs',
+        },
+      ];
+      if (answers.persistence === 'prisma' && hasPrisma) {
+        actions.push({
+          type: 'append',
+          path: 'prisma/schema.prisma',
+          templateFile: 'plop-templates/snippets/prisma-model.hbs',
+        });
+      }
+      return actions;
+    },
+  });
+
+  // ── command / query ───────────────────────────────────────────────────────
+  for (const kind of ['command', 'query']) {
+    const isCommand = kind === 'command';
+    plop.setGenerator(kind, {
+      description: isCommand
+        ? 'Command + handler in an existing module (a write use case)'
+        : 'Query + handler in an existing module (a read use case)',
+      prompts: [
+        {
+          type: 'list',
+          name: 'module',
+          message: 'Which module?',
+          choices: listModules,
+        },
+        {
+          type: 'input',
+          name: 'name',
+          message: isCommand
+            ? 'Command name in kebab-case (e.g. "publish-order"):'
+            : 'Query name in kebab-case (e.g. "get-order-by-id"):',
+          validate: requiredKebab('Name'),
+        },
+      ],
+      actions: (answers) => {
+        Object.assign(answers, {
+          kebab: kebab(answers.name),
+          Pascal: pascal(answers.name),
+          ModulePascal: pascal(answers.module),
+          moduleKebab: kebab(answers.module),
+        });
+        const dir = isCommand ? 'commands' : 'queries';
+        const base = `src/modules/{{module}}/application/${dir}`;
+        const array = isCommand ? 'command-handlers' : 'query-handlers';
+        const modulePath = 'src/modules/{{module}}/{{module}}.module.ts';
+        return [
+          {
+            type: 'add',
+            path: `${base}/{{kebab}}.${kind}.ts`,
+            templateFile: `plop-templates/${kind}/${kind}.ts.hbs`,
+          },
+          {
+            type: 'add',
+            path: `${base}/{{kebab}}.handler.ts`,
+            templateFile: `plop-templates/${kind}/handler.ts.hbs`,
+          },
+          {
+            type: 'modify',
+            path: 'src/modules/{{module}}/application/index.ts',
+            pattern: /\/\/ @plop:exports/,
+            template: `export * from './${dir}/{{kebab}}.${kind}.js';\nexport * from './${dir}/{{kebab}}.handler.js';\n// @plop:exports`,
+          },
+          {
+            type: 'modify',
+            path: modulePath,
+            pattern: /\/\/ @plop:handler-imports/,
+            template: '{{Pascal}}Handler,\n  // @plop:handler-imports',
+          },
+          {
+            type: 'modify',
+            path: modulePath,
+            pattern: new RegExp(`// @plop:${array}`),
+            template: `{{Pascal}}Handler,\n  // @plop:${array}`,
+          },
+        ];
+      },
+    });
+  }
+}

package/templates/nest-ddd/files/src/app.controller.ts

@@ -0,0 +1,13 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
+
+@ApiTags('System')
+@Controller()
+export class AppController {
+  @Get('health')
+  @ApiOperation({ summary: 'Check API health' })
+  @ApiResponse({ status: 200, description: 'API is healthy' })
+  health() {
+    return { status: 'ok', timestamp: new Date().toISOString() };
+  }
+}

package/templates/nest-ddd/files/src/app.module.ts

@@ -0,0 +1,26 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { ClsModule } from 'nestjs-cls';
+import { AppController } from './app.controller.js';
+import { validateEnv } from './core/config/env.validation.js';
+import { resolveCorrelationId } from './core/utils/correlation-id.util.js';
+// @infra:imports
+// @plop:module-imports
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true, validate: validateEnv }),
+    ClsModule.forRoot({
+      global: true,
+      middleware: {
+        mount: true,
+        generateId: true,
+        idGenerator: resolveCorrelationId,
+      },
+    }),
+    // @infra:modules
+    // @plop:modules
+  ],
+  controllers: [AppController],
+})
+export class AppModule {}

package/templates/nest-ddd/files/src/core/config/app.config.ts

@@ -0,0 +1,9 @@
+import { registerAs, type ConfigType } from '@nestjs/config';
+
+/** Settings about the application itself, parsed once at boot. */
+export const appConfig = registerAs('app', () => ({
+  /** The application's name (shown in emails, docs, ...). */
+  name: process.env.APP_NAME?.trim() || '{{PROJECT_NAME}}',
+}));
+
+export type AppConfig = ConfigType<typeof appConfig>;

package/templates/nest-ddd/files/src/core/config/env.validation.ts

@@ -0,0 +1,30 @@
+// @infra:env-imports
+
+/**
+ * Fails fast at boot when a required environment variable is missing or malformed,
+ * instead of letting a service crash later the first time it actually uses it.
+ *
+ * Infra modules add their own checks at the marker below (`create-my-stack add <infra>`).
+ */
+export function validateEnv(
+  config: Record<string, unknown>,
+): Record<string, unknown> {
+  const errors: string[] = [];
+
+  if (config.PORT !== undefined) {
+    const port = Number(config.PORT);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      errors.push('PORT must be a valid integer between 1 and 65535');
+    }
+  }
+
+  // @infra:env-checks
+
+  if (errors.length > 0) {
+    throw new Error(
+      `Invalid environment configuration:\n- ${errors.join('\n- ')}`,
+    );
+  }
+
+  return config;
+}

package/templates/nest-ddd/files/src/core/domain/base/aggregate-root.base.ts

@@ -0,0 +1,18 @@
+import { Entity } from './entity.base.js';
+import { DomainEvent } from './domain-event.base.js';
+
+export abstract class AggregateRoot<T> extends Entity<T> {
+  private _domainEvents: DomainEvent[] = [];
+
+  get domainEvents(): DomainEvent[] {
+    return this._domainEvents;
+  }
+
+  protected addDomainEvent(domainEvent: DomainEvent): void {
+    this._domainEvents.push(domainEvent);
+  }
+
+  public clearEvents(): void {
+    this._domainEvents = [];
+  }
+}

package/templates/nest-ddd/files/src/core/domain/base/domain-event.base.ts

@@ -0,0 +1,7 @@
+export abstract class DomainEvent {
+  public readonly occurredAt: Date;
+
+  constructor(public readonly aggregateId: string) {
+    this.occurredAt = new Date();
+  }
+}

package/templates/nest-ddd/files/src/core/domain/base/entity.base.ts

@@ -0,0 +1,36 @@
+import { snowflake } from '../../utils/snowflake.util.js';
+
+export abstract class Entity<EntityProps> {
+  protected readonly _id: string;
+  protected props: EntityProps;
+  public readonly createdAt: Date;
+  public updatedAt: Date;
+
+  constructor(props: EntityProps, id?: string) {
+    this._id = id ? id : snowflake.nextId();
+    this.createdAt = new Date();
+    this.updatedAt = new Date();
+    this.props = props;
+  }
+
+  get id(): string {
+    return this._id;
+  }
+
+  getProps(): EntityProps {
+    return this.props;
+  }
+
+  public equals(object?: Entity<EntityProps>): boolean {
+    if (object == null || object == undefined) {
+      return false;
+    }
+    if (this === object) {
+      return true;
+    }
+    if (!(object instanceof Entity)) {
+      return false;
+    }
+    return this._id === object._id;
+  }
+}

package/templates/nest-ddd/files/src/core/domain/base/value-object.base.ts

@@ -0,0 +1,17 @@
+export abstract class ValueObject<T> {
+  protected readonly props: T;
+
+  constructor(props: T) {
+    this.props = Object.freeze(props);
+  }
+
+  public equals(vo?: ValueObject<T>): boolean {
+    if (vo === null || vo === undefined) {
+      return false;
+    }
+    if (vo.props === undefined) {
+      return false;
+    }
+    return JSON.stringify(this.props) === JSON.stringify(vo.props);
+  }
+}

package/templates/nest-ddd/files/src/core/domain/exceptions/domain.exception.ts

@@ -0,0 +1,16 @@
+import { HttpStatus } from '@nestjs/common';
+import { ErrorCode } from './error-codes.js';
+
+export class DomainException extends Error {
+  public readonly code: string;
+  public readonly status: HttpStatus;
+  public readonly details?: unknown;
+
+  constructor(errorCode: ErrorCode, details?: unknown) {
+    super(errorCode.message);
+    this.name = 'DomainException';
+    this.code = errorCode.code;
+    this.status = errorCode.status;
+    this.details = details;
+  }
+}

package/templates/nest-ddd/files/src/core/domain/exceptions/error-codes.ts

@@ -0,0 +1,28 @@
+import { HttpStatus } from '@nestjs/common';
+
+export interface ErrorCode {
+  code: string;
+  message: string;
+  status: HttpStatus;
+}
+
+export const CoreErrorCodes = {
+  SYSTEM_ERROR: {
+    code: 'SYS-001',
+    message: 'Internal server error',
+    status: HttpStatus.INTERNAL_SERVER_ERROR,
+  },
+  VALIDATION_ERROR: {
+    code: 'VAL-001',
+    message: 'Validation failed',
+    status: HttpStatus.BAD_REQUEST,
+  },
+  RESOURCE_BUSY: {
+    code: 'SYS-002',
+    message: 'Another request is changing this right now, please try again',
+    status: HttpStatus.CONFLICT,
+  },
+};
+
+// @infra:error-codes
+// @plop:error-codes

package/templates/nest-ddd/files/src/core/domain/types/pagination.ts

@@ -0,0 +1,9 @@
+export interface PaginatedMeta {
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  meta: PaginatedMeta;
+}

package/templates/nest-ddd/files/src/core/http/decorators/client-info.decorator.ts

@@ -0,0 +1,24 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+import type { Request } from 'express';
+
+export interface IClientInfo {
+  /** Client IP as Express resolves it (`request.ip`). */
+  ip: string;
+  /** Raw `User-Agent` header, empty when the client sends none. */
+  userAgent: string;
+}
+
+/**
+ * The calling client's IP and User-Agent, for recording which device a session
+ * belongs to. Both are client-controlled input: use them for display, never
+ * for an access decision.
+ */
+export const ClientInfo = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): IClientInfo => {
+    const request = ctx.switchToHttp().getRequest<Request>();
+    return {
+      ip: request.ip ?? '',
+      userAgent: request.headers['user-agent'] ?? '',
+    };
+  },
+);

package/templates/nest-ddd/files/src/core/http/decorators/current-user.decorator.ts

@@ -0,0 +1,19 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export interface ICurrentUser {
+  id: string;
+  role: string;
+  /** Session the access token belongs to. */
+  sid?: string;
+}
+
+/**
+ * Reads `request.user`, which an auth guard (JwtAuthGuard) is expected to populate.
+ * The auth guard itself is intentionally not part of the boilerplate.
+ */
+export const CurrentUser = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): ICurrentUser => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.user;
+  },
+);