@koalarx/nest 4.0.6 → 4.1.0

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

@@ -3,12 +3,36 @@ import { MappingStore } from './mapping-store';
 
 interface AutoMapConfig<T> {
   type?: () => Type<T>;
+  isArray?: boolean;
 }
 
 export function AutoMap<T>(config?: AutoMapConfig<T>) {
-  return function (target: any, propertyKey: string) {
-    const compositionType: (() => any) | undefined = config?.type;
+  return function (target: object, propertyKey: string) {
+    const designType = Reflect.getMetadata('design:type', target, propertyKey);
+    const isArray = config?.isArray ?? designType === Array;
 
-    MappingStore.setProp(target.constructor, propertyKey, compositionType);
+    if (config?.type) {
+      if (isArray) {
+        Reflect.defineMetadata(
+          'composition:type',
+          config.type,
+          target,
+          propertyKey,
+        );
+      } else if (!designType) {
+        Reflect.defineMetadata(
+          'design:type',
+          config.type(),
+          target,
+          propertyKey,
+        );
+      }
+    }
+
+    MappingStore.setProp(
+      (target as { constructor: Type<unknown> }).constructor,
+      propertyKey,
+      config?.type,
+    );
   };
 }

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

@@ -1,3 +1,4 @@
+import { initializeUndefinedArrayProps } from '@/core/utils/initialize-undefined-array-props';
 import { Type } from '@nestjs/common';
 import { MappingStore } from './mapping-store';
 
@@ -25,7 +26,6 @@ export class AutoMapper {
 
   static map<S, R>(data: any, source: Type<S>, target: Type<R>): R {
     const mapping = MappingStore.getMapping(source, target);
-
     const targetInstance = new target();
 
     if (!mapping) {
@@ -70,9 +70,14 @@ export class AutoMapper {
         }
 
         const targetClass: Type<any> = this.toClass(targetPropType);
+        const sourceValue = data[sourceProp.name];
+
+        if (sourceValue === undefined) {
+          continue;
+        }
 
         targetInstance[targetPropName] = this.map(
-          data[sourceProp.name],
+          sourceValue,
           sourcePropTypeClass,
           targetClass,
         );
@@ -80,17 +85,21 @@ export class AutoMapper {
       }
 
       if (sourceProp.isArray) {
-        targetInstance[targetPropName] = data[sourceProp.name].map(
-          (item: unknown) => {
-            const targetItemType = targetProps.find(
-              (p) => p.name === targetPropName,
-            )!.type;
+        const sourceArray = data[sourceProp.name];
 
-            const targetClassType = this.toClass(targetItemType);
+        if (sourceArray === undefined) {
+          continue;
+        }
 
-            return this.map(item, sourcePropTypeClass, targetClassType);
-          },
-        );
+        targetInstance[targetPropName] = sourceArray.map((item: unknown) => {
+          const targetItemType = targetProps.find(
+            (p) => p.name === targetPropName,
+          )!.type;
+
+          const targetClassType = this.toClass(targetItemType);
+
+          return this.map(item, sourcePropTypeClass, targetClassType);
+        });
         continue;
       }
 
@@ -101,6 +110,11 @@ export class AutoMapper {
       }
     }
 
+    initializeUndefinedArrayProps(
+      targetInstance as Record<string, unknown>,
+      target,
+    );
+
     return targetInstance;
   }
 }

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

@@ -30,8 +30,15 @@ export class MappingStore {
       entity.prototype,
       propName,
     );
-    const isArray = propType === Array;
-    const type = isArray ? (compositionType ?? propType) : propType;
+    const explicitComposition = Reflect.getMetadata(
+      'composition:type',
+      entity.prototype,
+      propName,
+    );
+    const isArray = propType === Array || explicitComposition != null;
+    const type = isArray
+      ? (compositionType ?? explicitComposition ?? propType)
+      : propType;
 
     const props = this._entities.get(entity) || [];
 
@@ -64,6 +71,10 @@ export class MappingStore {
     return props;
   }
 
+  static getAllProps(entity: Type<any>) {
+    return this.getProps(entity);
+  }
+
   static getPropType(entity: Type<any>, propName: string) {
     let current: Type<any> | null = entity;
 
@@ -113,17 +124,4 @@ export class MappingStore {
   static getMapping(source: Type<any>, target: Type<any>) {
     return this._mappings.get(source)?.get(target) ?? null;
   }
-
-  /** Compatibilidade com chave legada usada em testes. */
-  static getMappingByName(mapName: string) {
-    for (const targetMappings of this._mappings.values()) {
-      for (const mapping of targetMappings.values()) {
-        if (`${mapping.source.name}To${mapping.target.name}` === mapName) {
-          return mapping;
-        }
-      }
-    }
-
-    return null;
-  }
 }

package/koala-nest/src/core/utils/cron-expression-to-boolean.ts

@@ -1,5 +1,36 @@
 import { CronExpressionParser } from 'cron-parser';
 
+/**
+ * Retorna uma chave única do tick cron atual, ou null se o instante não coincide.
+ */
+export function getCronExecutionKey(
+  cronExpression: string,
+  now: Date = new Date(),
+): string | null {
+  try {
+    const interval = CronExpressionParser.parse(cronExpression, {
+      currentDate: now,
+    });
+    const prev = interval.prev();
+
+    const matches =
+      prev.getFullYear() === now.getFullYear() &&
+      prev.getMonth() === now.getMonth() &&
+      prev.getDate() === now.getDate() &&
+      prev.getHours() === now.getHours() &&
+      prev.getMinutes() === now.getMinutes() &&
+      prev.getSeconds() === now.getSeconds();
+
+    if (!matches) {
+      return null;
+    }
+
+    return prev.toISOString();
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Verifica se a expressão cron corresponde ao momento atual.
  *
@@ -45,21 +76,5 @@ export function cronExpressionToBoolean(
   cronExpression: string,
   now: Date = new Date(),
 ): boolean {
-  try {
-    const interval = CronExpressionParser.parse(cronExpression, {
-      currentDate: now,
-    });
-    const prev = interval.prev();
-
-    return (
-      prev.getFullYear() === now.getFullYear() &&
-      prev.getMonth() === now.getMonth() &&
-      prev.getDate() === now.getDate() &&
-      prev.getHours() === now.getHours() &&
-      prev.getMinutes() === now.getMinutes() &&
-      prev.getSeconds() === now.getSeconds()
-    );
-  } catch {
-    return false;
-  }
+  return getCronExecutionKey(cronExpression, now) !== null;
 }

package/koala-nest/src/core/utils/hash-password.ts

@@ -1,5 +1,10 @@
 import { hash } from 'bcrypt';
 
-export function hashPassword(password: string): Promise<string> {
-  return hash(password, 6);
+const DEFAULT_BCRYPT_ROUNDS = 10;
+
+export function hashPassword(
+  password: string,
+  rounds = Number(process.env.BCRYPT_ROUNDS) || DEFAULT_BCRYPT_ROUNDS,
+): Promise<string> {
+  return hash(password, rounds);
 }

package/koala-nest/src/core/utils/initialize-undefined-array-props.ts

@@ -0,0 +1,20 @@
+import type { Type } from '@nestjs/common';
+import { MappingStore } from '@/core/tools/mapping/mapping-store';
+
+export function initializeUndefinedArrayProps(
+  target: Record<string, unknown>,
+  entity: Type<unknown>,
+  onlyProps?: string[],
+): void {
+  MappingStore.getAllProps(entity).forEach((prop) => {
+    if (onlyProps && !onlyProps.includes(prop.name)) {
+      return;
+    }
+
+    if (target[prop.name] !== undefined || !prop.isArray) {
+      return;
+    }
+
+    target[prop.name] = [];
+  });
+}

package/koala-nest/src/core/utils/resolve-cors-origins.ts

@@ -0,0 +1,24 @@
+/**
+ * CORS aberto por padrão (`true` = reflete a origin da requisição).
+ * Defina `CORS_ORIGINS` apenas quando quiser restringir a origens específicas.
+ */
+export function resolveCorsOrigin(
+  origins: string | undefined,
+): boolean | string | string[] {
+  const normalized = origins?.trim();
+
+  if (!normalized) {
+    return true;
+  }
+
+  const list = normalized
+    .split(',')
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+
+  if (list.length === 1) {
+    return list[0];
+  }
+
+  return list;
+}

package/koala-nest/src/domain/dtos/pagination.dto.ts

@@ -1,6 +1,61 @@
 import { QUERY_FILTER_PARAMS } from '@/core/constants/query-params';
 import { AutoMap } from '@/core/tools/mapping';
 import type { QueryDirectionType } from '@/core/types';
+import type {
+  FindOptionsOrder,
+  ObjectLiteral,
+  SelectQueryBuilder,
+} from 'typeorm';
+
+type OrderDirection = 'ASC' | 'DESC';
+
+function normalizeDirection(
+  direction?: QueryDirectionType | string,
+): OrderDirection {
+  return String(direction ?? 'asc').toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+}
+
+function flattenOrderBy(
+  order: Record<string, unknown>,
+  prefix = '',
+): Array<{ path: string; direction: OrderDirection }> {
+  const entries: Array<{ path: string; direction: OrderDirection }> = [];
+
+  for (const [key, value] of Object.entries(order)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+
+    if (typeof value === 'string') {
+      entries.push({ path, direction: normalizeDirection(value) });
+      continue;
+    }
+
+    if (value && typeof value === 'object') {
+      entries.push(...flattenOrderBy(value as Record<string, unknown>, path));
+    }
+  }
+
+  return entries;
+}
+
+function normalizeFindOptionsOrder(
+  order: Record<string, unknown>,
+): FindOptionsOrder<ObjectLiteral> {
+  const normalized: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(order)) {
+    if (typeof value === 'string') {
+      normalized[key] = normalizeDirection(value);
+    } else if (value && typeof value === 'object') {
+      normalized[key] = normalizeFindOptionsOrder(
+        value as Record<string, unknown>,
+      );
+    } else {
+      normalized[key] = value;
+    }
+  }
+
+  return normalized as FindOptionsOrder<ObjectLiteral>;
+}
 
 export class PaginationDto {
   @AutoMap()
@@ -19,17 +74,47 @@ export class PaginationDto {
     return (this.limit ?? 0) * (this.page ?? QUERY_FILTER_PARAMS.page);
   }
 
-  generateOrderBy() {
+  generateOrderBy(): Record<string, unknown> | undefined {
     if (this.orderBy) {
       const orderByField = this.orderBy.split('.');
       return orderByField.reduceRight(
         (acc, item, index) => ({
           [item]: index === orderByField.length - 1 ? this.direction : acc,
         }),
-        {},
+        {} as Record<string, unknown>,
       );
     }
 
     return undefined;
   }
+
+  toFindOptionsOrder(): FindOptionsOrder<ObjectLiteral> | undefined {
+    const order = this.generateOrderBy();
+
+    if (!order) {
+      return undefined;
+    }
+
+    return normalizeFindOptionsOrder(order);
+  }
+
+  applyQueryBuilderPagination<T extends ObjectLiteral>(
+    qb: SelectQueryBuilder<T>,
+    alias: string,
+  ): SelectQueryBuilder<T> {
+    const order = this.generateOrderBy();
+
+    if (order) {
+      for (const { path, direction } of flattenOrderBy(order)) {
+        const sortPath = path.includes('.') ? path : `${alias}.${path}`;
+        qb.addOrderBy(sortPath, direction);
+      }
+    }
+
+    return qb.skip(this.skip()).take(this.limit);
+  }
+
+  static from<T extends PaginationDto>(this: new () => T, props: Partial<T>): T {
+    return Object.assign(new this(), props);
+  }
 }

package/koala-nest/src/domain/dtos/person-query.dto.ts

@@ -7,4 +7,12 @@ export class PersonQueryDto extends PaginationDto {
 
   @AutoMap()
   active?: boolean;
+
+  override generateOrderBy() {
+    if (this.orderBy) {
+      return super.generateOrderBy();
+    }
+
+    return { id: 'asc' };
+  }
 }

package/koala-nest/src/domain/entities/person/person-address.ts

@@ -1,6 +1,7 @@
 import { EntityBase } from '@/core/base/entity.base';
+import { Entity } from '@/core/database/entity';
 import { AutoMap } from '@/core/tools/mapping';
-import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';
+import { Column, PrimaryGeneratedColumn } from 'typeorm';
 
 @Entity('person_address')
 export class PersonAddress extends EntityBase<PersonAddress> {

package/koala-nest/src/domain/entities/person/person-contact.ts

@@ -1,13 +1,13 @@
+import { EntityBase } from '@/core/base/entity.base';
+import { Entity } from '@/core/database/entity';
 import { AutoMap } from '@/core/tools/mapping';
 import {
   Column,
-  Entity,
   ManyToOne,
   PrimaryGeneratedColumn,
   type Relation,
 } from 'typeorm';
 import type { Person } from './person';
-import { EntityBase } from '@/core/base/entity.base';
 
 @Entity('person_contact')
 export class PersonContact extends EntityBase<PersonContact> {

package/koala-nest/src/domain/entities/person/person.ts

@@ -1,7 +1,8 @@
+import { EntityBase } from '@/core/base/entity.base';
+import { Entity } from '@/core/database/entity';
 import { AutoMap } from '@/core/tools/mapping';
 import {
   Column,
-  Entity,
   JoinColumn,
   OneToMany,
   OneToOne,
@@ -9,7 +10,6 @@ import {
 } from 'typeorm';
 import { PersonAddress } from './person-address';
 import { PersonContact } from './person-contact';
-import { EntityBase } from '@/core/base/entity.base';
 
 @Entity('person')
 export class Person extends EntityBase<Person> {
@@ -27,7 +27,6 @@ export class Person extends EntityBase<Person> {
 
   @OneToOne(() => PersonAddress, {
     cascade: true,
-    eager: true,
     onDelete: 'CASCADE',
   })
   @JoinColumn()
@@ -36,7 +35,6 @@ export class Person extends EntityBase<Person> {
 
   @OneToMany(() => PersonContact, (contact) => contact.person, {
     cascade: true,
-    eager: true,
     onDelete: 'CASCADE',
   })
   @AutoMap({ type: () => PersonContact })

package/koala-nest/src/domain/entities/user/user.ts

@@ -1,11 +1,11 @@
 import { AuthProfile } from '@/core/auth/auth-profile.enum';
 import { EntityBase } from '@/core/base/entity.base';
+import { Entity } from '@/core/database/entity';
 import { AutoMap } from '@/core/tools/mapping';
 import { UserStatus } from '@/domain/entities/user/enums/user-status.enum';
 import {
   Column,
   CreateDateColumn,
-  Entity,
   PrimaryGeneratedColumn,
   UpdateDateColumn,
 } from 'typeorm';

package/koala-nest/src/host/bootstrap/apply-http-middleware.ts

@@ -0,0 +1,22 @@
+import { createRateLimitMiddleware } from '@/core/http/rate-limit.middleware';
+import { resolveCorsOrigin } from '@/core/utils/resolve-cors-origins';
+import { EnvService } from '@/infra/common/env.service';
+import type { INestApplication } from '@nestjs/common';
+import cookieParser from 'cookie-parser';
+
+export function applyHttpMiddleware(app: INestApplication) {
+  const env = app.get(EnvService);
+
+  app.use(cookieParser());
+  app.use(
+    createRateLimitMiddleware({
+      windowMs: env.get('RATE_LIMIT_WINDOW_MS'),
+      maxRequests: env.get('RATE_LIMIT_MAX'),
+    }),
+  );
+  app.enableCors({
+    credentials: true,
+    origin: resolveCorsOrigin(env.get('CORS_ORIGINS')),
+    optionsSuccessStatus: 200,
+  });
+}

package/koala-nest/src/host/main.ts

@@ -1,7 +1,8 @@
 import 'dotenv/config';
 
+import { applyHttpMiddleware } from '@/host/bootstrap/apply-http-middleware';
+import { resolveApiHost } from '@/core/utils/resolve-api-host';
 import { NestFactory } from '@nestjs/core';
-import cookieParser from 'cookie-parser';
 import { AppModule } from './app.module';
 import { defineDocumentation } from './open-api/define-documentation';
 import { ErrorsFilter } from './filters/errors.filter';
@@ -13,13 +14,7 @@ import { ILoggingService } from '@/domain/common/ilogging.service';
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
 
-  app.use(cookieParser());
-
-  app.enableCors({
-    credentials: true,
-    origin: true,
-    optionsSuccessStatus: 200,
-  });
+  applyHttpMiddleware(app);
 
   await defineDocumentation(app);
 
@@ -32,12 +27,17 @@ async function bootstrap() {
     await app.resolve(ProfilesGuard),
   );
 
-  await app.listen(process.env.PORT || 3000);
+  const port = Number(process.env.PORT) || 3000;
+  const bindHost = process.env.HOST ?? '0.0.0.0';
+  const publicHost = resolveApiHost(process.env.API_HOST, port);
 
-  console.log(`Server is running on port ${process.env.PORT || 3000}`);
-  console.log(
-    `Documentation is available at http://localhost:${process.env.PORT || 3000}/doc`,
-  );
+  await app.listen(port, bindHost);
+
+  console.log(`Server is running on ${publicHost}`);
+  console.log(`Documentation is available at ${publicHost}/doc`);
 }
 
-bootstrap();
+bootstrap().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/koala-nest/src/infra/common/redis-cache.service.ts

@@ -59,11 +59,22 @@ export class RedisCacheService implements ICacheService {
 
   async invalidateByPrefix(prefix: string): Promise<void> {
     const pattern = `${this.buildKey(prefix)}*`;
-    const keys = await this.client.keys(pattern);
+    let cursor = '0';
 
-    if (keys.length > 0) {
-      await this.client.del(...keys);
-    }
+    do {
+      const [nextCursor, keys] = await this.client.scan(
+        cursor,
+        'MATCH',
+        pattern,
+        'COUNT',
+        100,
+      );
+      cursor = nextCursor;
+
+      if (keys.length > 0) {
+        await this.client.del(...keys);
+      }
+    } while (cursor !== '0');
   }
 
   onModuleDestroy() {

package/koala-nest/src/infra/database/data-source-factory.ts

@@ -1,9 +1,6 @@
-import { Person } from '@/domain/entities/person/person';
-import { PersonAddress } from '@/domain/entities/person/person-address';
-import { PersonContact } from '@/domain/entities/person/person-contact';
-import { User } from '@/domain/entities/user/user';
-import { DataSource } from 'typeorm';
+import { DbContext } from '@/core/database/db-context';
 import { EnvService } from '@/infra/common/env.service';
+import { DataSource } from 'typeorm';
 
 export const DATA_SOURCE_PROVIDER_TOKEN = 'DATA_SOURCE';
 
@@ -11,7 +8,8 @@ export async function dataSourceFactory(env: EnvService) {
   const dataSource = new DataSource({
     type: 'postgres',
     url: env.get('DATABASE_URL'),
-    entities: [Person, PersonAddress, PersonContact, User],
+    schema: env.get('DATABASE_SCHEMA'),
+    entities: Array.from(DbContext.entities.values()),
     invalidWhereValuesBehavior: {
       undefined: 'ignore',
     },

package/koala-nest/src/infra/database/migrations/migration-datasource.ts

@@ -3,10 +3,17 @@ import path from 'node:path';
 import { DataSource } from 'typeorm';
 
 const root = process.cwd();
+const schema = process.env.DATABASE_SCHEMA;
 
 export default new DataSource({
   type: 'postgres',
   url: process.env.DATABASE_URL,
+  ...(schema
+    ? {
+        schema,
+        extra: { options: `-c search_path=${schema},public` },
+      }
+    : {}),
   entities: [path.join(root, 'src/domain/entities/**/*.{js,ts}')],
   migrations: [path.join(root, 'src/infra/database/migrations/[0-9]*.{js,ts}')],
   migrationsTableName: 'migrations',

package/koala-nest/src/infra/repositories/person.repository.ts

@@ -30,18 +30,18 @@ export class PersonRepository
     return this.repository
       .findAndCount({
         where,
-        order: query.generateOrderBy(),
+        order: query.toFindOptionsOrder(),
         skip: query.skip(),
         take: query.limit,
       })
       .then(([items, count]) => ({
-        items,
+        items: this.normalizeEntities(items),
         count,
       }));
   }
 
   findById(id: number): Promise<Person | null> {
-    return this.repository.findOne({
+    return this.findOneNormalized({
       where: { id },
       relations: { address: true, contacts: true },
     });