@koalarx/nest 4.0.3 → 4.0.6

package/cli/commands/new/configure-test-runner.js

@@ -6,8 +6,19 @@ export function configureTestRunner(packageJson, packageManager) {
     scripts["test:watch"] = "bun test --watch";
     return;
   }
-  scripts.test = "vitest run";
-  scripts["test:watch"] = "vitest";
+  scripts.test = "vitest run --config vitest.config.ts";
+  scripts["test:watch"] = "vitest --config vitest.config.ts";
   devDependencies.vitest = "^4.1.8";
   devDependencies["vite-tsconfig-paths"] = "^5.1.4";
 }
+export function configureE2ETestRunner(packageJson, packageManager) {
+  const scripts = packageJson.scripts;
+  const devDependencies = packageJson.devDependencies;
+  devDependencies.supertest ??= "^7.1.0";
+  devDependencies["@types/supertest"] ??= "^6.0.2";
+  if (packageManager === "bun") {
+    scripts["test:e2e"] = "bun test --preload ./src/test/setup-e2e.ts src/test/host/controllers/";
+    return;
+  }
+  scripts["test:e2e"] = "vitest run --config vitest.config.e2e.ts";
+}

package/cli/commands/new/create-ddd-structure.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { DDD_LAYER_FOLDERS } from "../../constants/domain.js";
 import { patchGeneratedProjectConfig } from "../../utils/patch-generated-project.js";
 import { runCommand } from "../../utils/run-command.js";
-import { configureTestRunner } from "./configure-test-runner.js";
+import { configureE2ETestRunner, configureTestRunner } from "./configure-test-runner.js";
 export async function createDDDStructure(projectName, packageManager) {
   const folders = [...DDD_LAYER_FOLDERS];
   for (const folder of folders) {
@@ -38,14 +38,12 @@ export async function createDDDStructure(projectName, packageManager) {
   packageJson.scripts["migration:revert"] = `${migrationRunner} ${typeormCli} migration:revert ${migrationDatasource}`;
   packageJson.devDependencies ??= {};
   configureTestRunner(packageJson, packageManager);
+  configureE2ETestRunner(packageJson, packageManager);
   delete packageJson.scripts["test:cov"];
   delete packageJson.scripts["test:debug"];
-  delete packageJson.scripts["test:e2e"];
   delete packageJson.jest;
   delete packageJson.devDependencies["@types/jest"];
-  delete packageJson.devDependencies["@types/supertest"];
   delete packageJson.devDependencies["ts-jest"];
-  delete packageJson.devDependencies["supertest"];
   writeFileSync(path.join(process.cwd(), projectName, "package.json"), JSON.stringify(packageJson, null, 2));
   patchGeneratedProjectConfig(path.join(process.cwd(), projectName));
   await runCommand([packageManager, "install"], path.join(process.cwd(), projectName));

package/cli/commands/new/index.js

@@ -26,6 +26,7 @@ import {
   resolveProjectFeatures
 } from "../../utils/install-module.js";
 import { fixLintConfig } from "./fix-lint-config.js";
+import { finalizeNewProjectSetup } from "../../utils/install-workspace-config.js";
 async function promptAuthStrategies(template) {
   const isCrud = template === Template.CRUD_SAMPLE;
   return assertNotCancel(await p.multiselect({
@@ -180,6 +181,8 @@ export async function runNew(args = []) {
     auth: authStrategies,
     features
   });
+  spinner.message("Configurando workspace (.vscode e .env)...");
+  finalizeNewProjectSetup(project.name, project.packageManager);
   spinner.stop("Projeto criado com sucesso!");
   const projectFeatures = resolveProjectFeatures(features, authStrategies);
   const extrasSummary = [
@@ -196,7 +199,8 @@ export async function runNew(args = []) {
     `${color.bold("Gerenciador:")} ${project.packageManager}`,
     `${color.bold("Autenticação:")} ${formatAuthStrategies(authStrategies)}`,
     `${color.bold("Extras:")} ${extrasSummary || color.dim("nenhum")}`,
-    `${color.dim("Depois:")} cd ${project.name} && kl-nest add <feature>`
+    `${color.dim("Depois:")} cd ${project.name} && ${project.packageManager} start`,
+    `${color.dim("Extras:")} kl-nest add <feature>`
   ].join(`
 `), "Resumo");
 }

package/cli/constants/cli-project-checklist.js

@@ -5,6 +5,28 @@ import {
   resolveNewProjectOptions
 } from "./domain.js";
 import { resolveProjectFeatures } from "../utils/install-module.js";
+export const E2E_INFRA_PATHS = [
+  "src/test/setup-e2e.ts",
+  "src/test/create-e2e-test-app.ts",
+  "src/test/e2e-context.ts",
+  "src/test/utils/create-e2e-database.ts",
+  "src/test/utils/e2e-database-client.ts",
+  "src/test/host/controllers/app/app.e2e.spec.ts"
+];
+export const CRUD_E2E_EXAMPLE_PATHS = [
+  "src/test/host/controllers/person/person.controller.e2e.spec.ts",
+  "src/test/host/controllers/person/lazy-loading.e2e.spec.ts",
+  "src/test/host/controllers/auth/auth.controller.e2e.spec.ts",
+  "src/test/app-auth-test.module.ts",
+  "src/test/create-auth-e2e-test-app.ts"
+];
+export const WORKSPACE_SETUP_PATHS = [
+  ".vscode/launch.json",
+  ".vscode/settings.json",
+  ".vscode/tasks.json",
+  ".vscode/extensions.json",
+  ".env"
+];
 export const CORE_REQUIRED_PATHS = [
   "src/core/env.ts",
   "src/host/main.ts",
@@ -165,9 +187,13 @@ export function buildProjectExpectation(template, auth, features) {
   };
 }
 export function requiredPathsForExpectation(expectation) {
-  const paths = [...CORE_REQUIRED_PATHS];
+  const paths = [
+    ...CORE_REQUIRED_PATHS,
+    ...WORKSPACE_SETUP_PATHS,
+    ...E2E_INFRA_PATHS
+  ];
   if (expectation.template === Template.CRUD_SAMPLE) {
-    paths.push(...CRUD_TEMPLATE_REQUIRED_PATHS);
+    paths.push(...CRUD_TEMPLATE_REQUIRED_PATHS, ...CRUD_E2E_EXAMPLE_PATHS);
   }
   if (expectation.cache === "redis") {
     paths.push(...CACHE_REDIS_REQUIRED_PATHS);
@@ -189,7 +215,7 @@ export function requiredPathsForExpectation(expectation) {
 export function forbiddenPathsForExpectation(expectation) {
   const paths = [];
   if (expectation.template === Template.DEFAULT) {
-    paths.push(...DEFAULT_TEMPLATE_FORBIDDEN_PATHS);
+    paths.push(...DEFAULT_TEMPLATE_FORBIDDEN_PATHS, ...CRUD_E2E_EXAMPLE_PATHS);
   } else {
     paths.push(...CRUD_TEMPLATE_FORBIDDEN_PATHS);
   }

package/cli/utils/install-module.js

@@ -153,6 +153,11 @@ export async function installModule(module, template, projectName = "", options
       for (const configFile of ["tsconfig.build.json", ".env.example"]) {
         cpSync(path.join(getSourceCodePath(), configFile), path.join(projectPath, configFile));
       }
+      if (packageManager !== "bun") {
+        for (const configFile of ["vitest.config.ts", "vitest.config.e2e.ts"]) {
+          cpSync(path.join(getSourceCodePath(), configFile), path.join(projectPath, configFile));
+        }
+      }
       patchInfraModuleFile(projectName, false);
       patchMainFile(projectName, stripMainOptionalFeatures);
       if (!options.skipPackages) {

package/cli/utils/install-workspace-config.js

@@ -0,0 +1,81 @@
+import { cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { getSourceCodePath } from "./get-source-code-path.js";
+import { resolveProjectPath } from "./resolve-project-path.js";
+const PACKAGE_MANAGER_COMMAND = {
+  bun: "bun",
+  npm: "npm",
+  pnpm: "pnpm"
+};
+export function projectNameToSnakeCase(projectName) {
+  const baseName = path.isAbsolute(projectName) ? path.basename(projectName) : projectName;
+  return baseName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[\s-]+/g, "_").replace(/__+/g, "_").toLowerCase().replace(/^_+|_+$/g, "");
+}
+function patchDatabaseUrl(content, databaseName) {
+  if (!/^DATABASE_URL=/m.test(content)) {
+    return content;
+  }
+  return content.replace(/^(DATABASE_URL=.+\/)([^/\r\n]+)(\s*)$/m, `$1${databaseName}$3`);
+}
+function patchJsonFile(filePath, patch) {
+  const content = readFileSync(filePath, "utf8");
+  const json = JSON.parse(content);
+  patch(json);
+  writeFileSync(filePath, `${JSON.stringify(json, null, 2)}
+`);
+}
+function runScriptCommand(packageManager, script) {
+  return `${PACKAGE_MANAGER_COMMAND[packageManager]} run ${script}`;
+}
+export function installWorkspaceConfig(projectName, packageManager) {
+  const projectRoot = resolveProjectPath(projectName);
+  const sourceVscode = path.join(getSourceCodePath(), ".vscode");
+  const targetVscode = path.join(projectRoot, ".vscode");
+  cpSync(sourceVscode, targetVscode, { recursive: true });
+  const pmCommand = PACKAGE_MANAGER_COMMAND[packageManager];
+  patchJsonFile(path.join(targetVscode, "launch.json"), (launch) => {
+    const config = launch.configurations[0];
+    config.runtimeExecutable = pmCommand;
+    config.runtimeArgs = ["run", "start:debug"];
+    config.cwd = "${workspaceFolder}";
+  });
+  patchJsonFile(path.join(targetVscode, "tasks.json"), (tasks) => {
+    for (const task of tasks.tasks) {
+      if (task.command.includes("start:dev")) {
+        task.command = runScriptCommand(packageManager, "start:dev");
+      } else if (task.command.includes("test")) {
+        task.command = runScriptCommand(packageManager, "test");
+      } else if (task.command.includes("test:e2e")) {
+        task.command = runScriptCommand(packageManager, "test:e2e");
+      } else if (task.command.includes("migration:run")) {
+        task.command = runScriptCommand(packageManager, "migration:run");
+      }
+      task.options = { cwd: "${workspaceFolder}" };
+    }
+  });
+  patchJsonFile(path.join(targetVscode, "settings.json"), (settings) => {
+    settings["npm.packageManager"] = packageManager;
+  });
+  const gitignoreSource = path.join(getSourceCodePath(), ".gitignore");
+  if (existsSync(gitignoreSource)) {
+    cpSync(gitignoreSource, path.join(projectRoot, ".gitignore"), {
+      force: true
+    });
+  }
+}
+export function createEnvFromExample(projectName) {
+  const projectRoot = resolveProjectPath(projectName);
+  const examplePath = path.join(projectRoot, ".env.example");
+  const envPath = path.join(projectRoot, ".env");
+  if (!existsSync(examplePath)) {
+    return;
+  }
+  const databaseName = projectNameToSnakeCase(projectName);
+  const envContent = patchDatabaseUrl(readFileSync(examplePath, "utf8"), databaseName);
+  writeFileSync(examplePath, envContent);
+  writeFileSync(envPath, envContent);
+}
+export function finalizeNewProjectSetup(projectName, packageManager) {
+  installWorkspaceConfig(projectName, packageManager);
+  createEnvFromExample(projectName);
+}

package/cli/utils/patch-app-test-module.js

@@ -0,0 +1,29 @@
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { resolveProjectPath } from "./resolve-project-path.js";
+const defaultAppTestModule = `import { envSchema } from '@/core/env';
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { InfraModule } from '@/infra/infra.module';
+import { e2eDatabaseUrl } from '@/test/e2e-context';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      ignoreEnvFile: true,
+      validate: () =>
+        envSchema.parse({
+          PORT: 3000,
+          NODE_ENV: 'test',
+          DATABASE_URL: e2eDatabaseUrl,
+        }),
+    }),
+    InfraModule,
+  ],
+})
+export class AppTestModule {}
+`;
+export function patchAppTestModuleForDefault(projectName) {
+  writeFileSync(path.join(resolveProjectPath(projectName), "src/test/app-test.module.ts"), defaultAppTestModule);
+}

package/cli/utils/remove-sample-parts.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { removeImportLines } from "./project-files.js";
 import { patchAppModuleJobs } from "./patch-jobs-module.js";
+import { patchAppTestModuleForDefault } from "./patch-app-test-module.js";
 import { resolveProjectPath } from "./resolve-project-path.js";
 import { stripMainOptionalFeatures } from "./patch-main.js";
 import { stripDefineDocumentationAuth } from "./patch-define-documentation.js";
@@ -85,11 +86,13 @@ const partsToRemove = [
     replace: [{ from: "PersonMapper.createMap();", to: "" }]
   }
 ];
-const defaultTemplatePathsToRemove = [
+const defaultSampleTestPathsToRemove = [
   "src/test/application",
   "src/test/mockup/person",
   "src/test/host/controllers/person/person.controller.e2e.spec.ts",
-  "src/test/host/controllers/person/lazy-loading.e2e.spec.ts",
+  "src/test/host/controllers/person/lazy-loading.e2e.spec.ts"
+];
+const defaultAuthE2ePathsToRemove = [
   "src/test/host/controllers/auth/auth.controller.e2e.spec.ts",
   "src/test/app-auth-test.module.ts",
   "src/test/create-auth-e2e-test-app.ts"
@@ -154,7 +157,11 @@ export async function removeSampleParts(projectName) {
     writeFileSync(partPath, content, "utf8");
   }
   patchAppModuleJobs(projectName, { eventHandlers: [], cronJobs: [] });
-  removePaths(projectName, defaultTemplatePathsToRemove);
+  patchAppTestModuleForDefault(projectName);
+  removePaths(projectName, [
+    ...defaultSampleTestPathsToRemove,
+    ...defaultAuthE2ePathsToRemove
+  ]);
 }
 export async function cleanDefaultTemplateWithoutAuth(projectName) {
   stripDefaultProjectAuth(projectName);

package/koala-nest/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "PKief.material-icon-theme"
+  ]
+}

package/koala-nest/.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "NestJS Debug",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "start:debug"],
+      "cwd": "${workspaceFolder}",
+      "autoAttachChildProcesses": true,
+      "restart": true,
+      "console": "integratedTerminal"
+    }
+  ]
+}

package/koala-nest/.vscode/settings.json

@@ -0,0 +1,77 @@
+{
+  "material-icon-theme.activeIconPack": "nest",
+  "editor.fontFamily": "Fira Code",
+  "editor.fontSize": 15,
+  "editor.fontLigatures": true,
+  "workbench.startupEditor": "newUntitledFile",
+  "js/ts.suggest.autoImports": true,
+  "js/ts.updateImportsOnFileMove.enabled": "always",
+  "editor.rulers": [80, 120],
+  "extensions.ignoreRecommendations": true,
+  "files.associations": {
+    ".env.*": "dotenv",
+    ".prettierrc": "json"
+  },
+  "editor.parameterHints.enabled": false,
+  "editor.renderLineHighlight": "gutter",
+  "editor.lineHeight": 26,
+  "editor.suggestSelection": "first",
+  "explorer.confirmDelete": false,
+  "workbench.editor.labelFormat": "short",
+  "editor.acceptSuggestionOnCommitCharacter": false,
+  "explorer.compactFolders": false,
+  "git.enableSmartCommit": true,
+  "explorer.confirmDragAndDrop": false,
+  "terminal.integrated.fontSize": 14,
+  "breadcrumbs.enabled": true,
+  "editor.tabSize": 2,
+  "workbench.iconTheme": "material-icon-theme",
+  "material-icon-theme.languages.associations": {
+    "dotenv": "tune"
+  },
+  "material-icon-theme.files.associations": {
+    "*.e2e-spec.ts": "test-js",
+    "*.dto.ts": "diff",
+    "*.handler.ts": "esbuild",
+    "*.request.ts": "log",
+    "*.schema.ts": "scheme",
+    "*.response.ts": "conduct",
+    "*.validator.ts": "commitlint"
+  },
+  "material-icon-theme.folders.associations": {
+    "entities": "class",
+    "migrations": "tools",
+    "schemas": "class",
+    "domain": "class",
+    "infra": "app",
+    "dtos": "typescript",
+    "repositories": "mappings"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit"
+    }
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit"
+    }
+  },
+  "prettier.documentSelectors": ["**/*.ts", "**/*.tsx", "**/*.js"],
+  "npm.scriptExplorerAction": "run",
+  "npm.packageManager": "bun",
+  "editor.wordWrap": "on",
+  "editor.wrappingIndent": "indent",
+  "eslint.workingDirectories": [{ "mode": "auto" }],
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact"
+  ],
+  "files.eol": "\n"
+}

package/koala-nest/.vscode/tasks.json

@@ -0,0 +1,46 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "shell",
+      "command": "bun run start:dev",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "isBackground": true,
+      "problemMatcher": [],
+      "label": "Start API (dev)",
+      "detail": "nest start --watch"
+    },
+    {
+      "type": "shell",
+      "command": "bun run test",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "group": "test",
+      "label": "Run tests"
+    },
+    {
+      "type": "shell",
+      "command": "bun run test:e2e",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "group": "test",
+      "label": "Run E2E tests"
+    },
+    {
+      "type": "shell",
+      "command": "bun run migration:run",
+      "options": {
+        "cwd": "${workspaceFolder}"
+      },
+      "label": "Run migrations"
+    }
+  ]
+}

package/koala-nest/src/application/common/request-validator.base.ts

@@ -6,7 +6,7 @@ export abstract class RequestValidatorBase<
   protected _request: Record<string, any>;
 
   constructor(request: TRequest) {
-    this._request = { ...request };
+    this._request = RequestValidatorBase.toValidationInput(request);
   }
 
   validate(): TRequest {
@@ -30,4 +30,39 @@ export abstract class RequestValidatorBase<
   }
 
   protected abstract get schema(): ZodType;
+
+  /**
+   * Objetos plain (query HTTP) passam direto. Instâncias de classe carregam
+   * defaults nos fields — removemos os que não foram alterados para o Zod
+   * aplicar defaults/transforms sem sobrescrever query params explícitos.
+   */
+  private static toValidationInput<T extends Record<string, unknown>>(
+    request: T,
+  ): Record<string, unknown> {
+    if (request === null || typeof request !== 'object') {
+      return {};
+    }
+
+    const prototype = Object.getPrototypeOf(request);
+    const isClassInstance =
+      prototype !== null &&
+      prototype !== Object.prototype &&
+      typeof prototype.constructor === 'function';
+
+    if (!isClassInstance) {
+      return { ...request };
+    }
+
+    const Constructor = prototype.constructor as new () => T;
+    const defaultValues = new Constructor() as Record<string, unknown>;
+    const input: Record<string, unknown> = { ...request };
+
+    for (const key of Object.keys(defaultValues)) {
+      if (Object.is(input[key], defaultValues[key])) {
+        delete input[key];
+      }
+    }
+
+    return input;
+  }
 }

package/koala-nest/src/core/tools/mapping/auto-mapper.ts

@@ -94,7 +94,11 @@ export class AutoMapper {
         continue;
       }
 
-      targetInstance[targetPropName] = data[sourceProp.name];
+      const sourceValue = data[sourceProp.name];
+
+      if (sourceValue !== undefined) {
+        targetInstance[targetPropName] = sourceValue;
+      }
     }
 
     return targetInstance;

package/koala-nest/src/core/tools/mapping/mapping-store.ts

@@ -57,32 +57,40 @@ export class MappingStore {
         }
       }
 
-      current = Object.getPrototypeOf(current) as Type<any> | null;
+      const parentPrototype = Object.getPrototypeOf(current.prototype);
+      current = (parentPrototype?.constructor as Type<any> | undefined) ?? null;
     }
 
     return props;
   }
 
   static getPropType(entity: Type<any>, propName: string) {
-    const prop = this._entities.get(entity)?.find((p) => p.name === propName);
+    let current: Type<any> | null = entity;
 
-    if (!prop) {
-      throw new Error(
-        `Property ${propName} not found in entity ${entity.name}`,
-      );
-    }
+    while (current?.prototype) {
+      const prop = this._entities.get(current)?.find((p) => p.name === propName);
 
-    const { type, isArray } = prop;
+      if (prop) {
+        const { type, isArray } = prop;
 
-    if (!type) {
-      return null;
-    }
+        if (!type) {
+          return null;
+        }
 
-    if (isArray && type instanceof Function) {
-      return (type as () => Type<any>)();
+        if (isArray && type instanceof Function) {
+          return (type as () => Type<any>)();
+        }
+
+        return type;
+      }
+
+      const parentPrototype = Object.getPrototypeOf(current.prototype);
+      current = (parentPrototype?.constructor as Type<any> | undefined) ?? null;
     }
 
-    return type;
+    throw new Error(
+      `Property ${propName} not found in entity ${entity.name}`,
+    );
   }
 
   static add(

package/koala-nest/src/infra/services/database.indicator.service.ts

@@ -1,17 +1,34 @@
 import { DATA_SOURCE_PROVIDER_TOKEN } from '@/infra/database/data-source-factory';
 import { Inject, Injectable } from '@nestjs/common';
-import { TypeOrmHealthIndicator } from '@nestjs/terminus';
+import {
+  HealthIndicatorResult,
+  HealthIndicatorService,
+} from '@nestjs/terminus';
 import { DataSource } from 'typeorm';
 
 @Injectable()
 export class DatabaseIndicator {
   constructor(
-    private readonly typeOrm: TypeOrmHealthIndicator,
+    private readonly healthIndicatorService: HealthIndicatorService,
     @Inject(DATA_SOURCE_PROVIDER_TOKEN)
     private readonly dataSource: DataSource,
   ) {}
 
-  isHealthy() {
-    return this.typeOrm.pingCheck('db', { connection: this.dataSource });
+  async isHealthy(): Promise<HealthIndicatorResult> {
+    const indicator = this.healthIndicatorService.check('db');
+
+    try {
+      if (!this.dataSource.isInitialized) {
+        return indicator.down({ message: 'DataSource not initialized' });
+      }
+
+      await this.dataSource.query('SELECT 1');
+
+      return indicator.up();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+
+      return indicator.down({ message });
+    }
   }
 }

package/koala-nest/src/test/application/read-many-person.handler.spec.ts

@@ -21,18 +21,58 @@ describe('ReadManyPersonHandler', () => {
       contacts: [],
     });
 
+    let capturedPage: number | undefined;
     const repository = {
-      findMany: async () => ({ items: [person], count: 1 }),
+      findMany: async (query: { page?: number; skip: () => number }) => {
+        capturedPage = query.page;
+        return { items: [person], count: 1 };
+      },
     } as unknown as IPersonRepository;
 
     const handler = new ReadManyPersonHandler(repository, new CacheStub());
-    const result = await handler.handle(new ReadManyPersonRequest());
+    const result = await handler.handle({ page: '2', limit: '5' } as never);
 
+    expect(capturedPage).toBe(1);
     expect(result.count).toBe(1);
     expect(result.items).toHaveLength(1);
     expect(result.items[0].name).toBe('Jane');
   });
 
+  it('preserva paginação ao receber instância de ReadManyPersonRequest', async () => {
+    let capturedPage: number | undefined;
+    const repository = {
+      findMany: async (query: { page?: number }) => {
+        capturedPage = query.page;
+        return { items: [], count: 0 };
+      },
+    } as unknown as IPersonRepository;
+
+    const handler = new ReadManyPersonHandler(repository, new CacheStub());
+    const request = Object.assign(new ReadManyPersonRequest(), {
+      page: '2',
+      limit: '5',
+    });
+
+    await handler.handle(request);
+
+    expect(capturedPage).toBe(1);
+  });
+
+  it('aplica defaults de paginação quando a request não informa page', async () => {
+    let capturedPage: number | undefined;
+    const repository = {
+      findMany: async (query: { page?: number }) => {
+        capturedPage = query.page;
+        return { items: [], count: 0 };
+      },
+    } as unknown as IPersonRepository;
+
+    const handler = new ReadManyPersonHandler(repository, new CacheStub());
+    await handler.handle(new ReadManyPersonRequest());
+
+    expect(capturedPage).toBe(0);
+  });
+
   it('reutiliza cache para a mesma consulta de listagem', async () => {
     const person = Person.from({
       id: 1,

package/koala-nest/src/test/core/mapping.spec.ts

@@ -137,6 +137,67 @@ describe('AutoMapper', () => {
     expect(target.fullName).toBe('John Doe');
   });
 
+  it('should map inherited properties from parent classes', () => {
+    class BaseRequest {
+      @AutoMap()
+      page?: number;
+
+      @AutoMap()
+      limit?: number;
+    }
+
+    class ChildRequest extends BaseRequest {
+      @AutoMap()
+      name?: string;
+    }
+
+    class BaseDto {
+      @AutoMap()
+      page?: number = 0;
+
+      @AutoMap()
+      limit?: number = 10;
+    }
+
+    class ChildDto extends BaseDto {
+      @AutoMap()
+      name?: string;
+    }
+
+    createMap(ChildRequest, ChildDto);
+
+    const source = Object.assign(new ChildRequest(), {
+      page: 2,
+      limit: 25,
+      name: 'John',
+    });
+
+    const target = AutoMapper.map(source, ChildRequest, ChildDto);
+
+    expect(target.page).toBe(2);
+    expect(target.limit).toBe(25);
+    expect(target.name).toBe('John');
+  });
+
+  it('should resolve inherited property types via getProps and getPropType', () => {
+    class BaseRequest {
+      @AutoMap()
+      page?: number;
+    }
+
+    class ChildRequest extends BaseRequest {
+      @AutoMap()
+      name?: string;
+    }
+
+    const props = MappingStore.getProps(ChildRequest).map((p) => p.name);
+
+    expect(props).toContain('page');
+    expect(props).toContain('name');
+    expect(MappingStore.getPropType(ChildRequest, 'page')).toBe(Number);
+    expect(MappingStore.getPropType(ChildRequest, 'name')).toBe(String);
+  });
+
   it('should map nested objects using the target property name', () => {
     class SourceChild {
       @AutoMap()

package/koala-nest/src/test/host/controllers/app/app.e2e.spec.ts

@@ -0,0 +1,24 @@
+/// <reference types="bun-types/test-globals" />
+
+import { createE2ETestApp } from '@/test/create-e2e-test-app';
+import type { INestApplication } from '@nestjs/common';
+
+/**
+ * Estrutura mínima de E2E — use como ponto de partida no template Padrão.
+ * No exemplo CRUD, veja `person.controller.e2e.spec.ts` e `auth.controller.e2e.spec.ts`.
+ */
+describe('App (E2E)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    app = await createE2ETestApp();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('should bootstrap the application', () => {
+    expect(app.getHttpServer()).toBeDefined();
+  });
+});

package/koala-nest/src/test/utils/create-e2e-database.ts

@@ -1,9 +1,24 @@
 import { Type } from '@nestjs/common';
 import { execSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import { setE2EDatabaseUrl } from '../e2e-context';
 import { E2EDatabaseClient } from './e2e-database-client';
 
+function resolveMigrationRunner(): string {
+  const packageJson = JSON.parse(readFileSync('package.json', 'utf8')) as {
+    packageManager?: string;
+  };
+
+  const packageManager = packageJson.packageManager ?? 'bun';
+
+  if (packageManager === 'bun') {
+    return 'bun';
+  }
+
+  return 'node --import ts-node/register/transpile-only';
+}
+
 function generateUniqueDatabaseURL() {
   const schemaId = randomUUID();
 
@@ -33,8 +48,9 @@ export async function createE2EDatabase<T extends E2EDatabaseClient>(
     await client.createDatabase(schemaId);
 
     const env = { ...process.env, DATABASE_URL: url, NODE_ENV: 'test' };
+    const migrationRunner = resolveMigrationRunner();
     execSync(
-      'bun ./node_modules/typeorm/cli.js migration:run -d ./src/infra/database/migrations/migration-datasource.ts',
+      `${migrationRunner} ./node_modules/typeorm/cli.js migration:run -d ./src/infra/database/migrations/migration-datasource.ts`,
       {
         cwd: process.cwd(),
         env,

package/koala-nest/vitest.config.e2e.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  test: {
+    include: ['src/test/**/*.e2e.spec.ts'],
+    setupFiles: ['src/test/setup-e2e.ts'],
+    environment: 'node',
+    testTimeout: 60_000,
+    hookTimeout: 60_000,
+  },
+});

package/koala-nest/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [tsconfigPaths()],
+  test: {
+    include: ['src/test/**/*.spec.ts'],
+    exclude: ['src/test/**/*.e2e.spec.ts'],
+    setupFiles: ['src/test/setup.ts'],
+    environment: 'node',
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koalarx/nest",
-  "version": "4.0.3",
+  "version": "4.0.6",
   "description": "CLI para criar APIs NestJS com arquitetura DDD — copia módulos prontos para o seu repositório.",
   "license": "MIT",
   "type": "module",