@koalarx/nest 1.19.0 → 3.0.1

package/src/core/index.ts

@@ -0,0 +1,56 @@
+import { Multer } from 'multer'
+import { Express } from 'express'
+
+export type FileType = Express.Multer.File
+
+/**
+ * Make some property optional on type
+ *
+ * @example
+ * ```typescript
+ * type Post {
+ *  id: string;
+ *  name: string;
+ *  email: string;
+ * }
+ *
+ * Optional<Post, 'id' | 'email' >
+ * ```
+ */
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+/**
+ * Override props on type
+ *
+ * @example
+ * ```typescript
+ * type Post {
+ *  id: string;
+ *  name: string;
+ *  email: string;
+ * }
+ *
+ * Overwrite<Post, { id: number }>
+ * ```
+ */
+export type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U
+
+export type CreatedRegister<TypeId = string> = {
+  id: TypeId
+}
+
+export type ListResponse<TItem = any> = {
+  items: Array<TItem>
+  count: number
+}
+
+export type FileResponse = {
+  filename: string
+  type: string
+  base64: string
+}
+
+export type QueryDirectionType = 'asc' | 'desc'
+// Exportar funções para resolver Prisma
+export { setPrismaClient } from './database/prisma-resolver'
+export { setPrismaClientOptions } from './database/prisma.service'

package/src/core/koala-app.ts

@@ -0,0 +1,379 @@
+import {
+  CanActivate,
+  INestApplication,
+  InternalServerErrorException,
+  Type,
+} from '@nestjs/common'
+import { BaseExceptionFilter } from '@nestjs/core'
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
+import { SecuritySchemeObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface'
+import { apiReference } from '@scalar/nestjs-api-reference'
+import * as consola from 'consola'
+import * as expressBasicAuth from 'express-basic-auth'
+import * as ngrok from 'ngrok'
+import { EnvService } from '../env/env.service'
+import { DomainErrorsFilter } from '../filters/domain-errors.filter'
+import { GlobalExceptionsFilter } from '../filters/global-exception.filter'
+import { PrismaValidationExceptionFilter } from '../filters/prisma-validation-exception.filter'
+import { ZodErrorsFilter } from '../filters/zod-errors.filter'
+import { ILoggingService } from '../services/logging/ilogging.service'
+import { CronJobHandlerBase } from './backgroud-services/cron-service/cron-job.handler.base'
+import { EventHandlerBase } from './backgroud-services/event-service/event-handler.base'
+import { PrismaTransactionalClient } from './database/prisma-transactional-client'
+import { KoalaGlobalVars } from './koala-global-vars'
+import { EnvConfig } from './utils/env.config'
+import { instanciateClassWithDependenciesInjection } from './utils/instanciate-class-with-dependencies-injection'
+import { delay } from '@koalarx/utils'
+
+interface ApiDocAuthorizationConfig {
+  name: string
+  config: SecuritySchemeObject
+}
+
+interface ApiDocServerConfig {
+  url: string
+  description: string
+}
+
+type ScalarTheme =
+  | 'alternate'
+  | 'default'
+  | 'moon'
+  | 'purple'
+  | 'solarized'
+  | 'bluePlanet'
+  | 'saturn'
+  | 'kepler'
+  | 'mars'
+  | 'deepSpace'
+  | 'none'
+
+interface ApiDocConfig {
+  endpoint: string
+  title: string
+  ui?: 'swagger' | 'scalar'
+  theme?: ScalarTheme
+  description?: string
+  externalDoc?: {
+    message: string
+    url: string
+  }
+  servers?: ApiDocServerConfig[]
+  version: string
+  authorizations?: boolean | ApiDocAuthorizationConfig[]
+}
+
+type CronJobClass = string | symbol | Function | Type<CronJobHandlerBase>
+type EventJobClass = string | symbol | Function | Type<EventHandlerBase>
+
+export class KoalaApp {
+  private _globalExceptionFilter: BaseExceptionFilter
+  private _prismaValidationExceptionFilter: BaseExceptionFilter
+  private _domainExceptionFilter: BaseExceptionFilter
+  private _zodExceptionFilter: BaseExceptionFilter
+
+  private _guards: CanActivate[] = []
+  private _cronJobs: CronJobClass[] = []
+  private _eventJobs: EventJobClass[] = []
+  private _apiReferenceEndpoint: string
+  private _ngrokKey: string
+  private _ngrokUrl: string
+
+  constructor(private readonly app: INestApplication<any>) {
+    let loggingService = this.app.get(ILoggingService)
+
+    if (!loggingService.report) {
+      loggingService = instanciateClassWithDependenciesInjection(
+        this.app,
+        loggingService,
+      )
+    }
+
+    this._globalExceptionFilter = new GlobalExceptionsFilter(loggingService)
+    this._prismaValidationExceptionFilter = new PrismaValidationExceptionFilter(
+      loggingService,
+    )
+    this._domainExceptionFilter = new DomainErrorsFilter(loggingService)
+    this._zodExceptionFilter = new ZodErrorsFilter(loggingService)
+  }
+
+  private showListeningMessage(port: number, host: string = 'localhost') {
+    const envService = this.app.get(EnvService)
+
+    console.log('------------------------------')
+
+    if (this._apiReferenceEndpoint) {
+      consola.info(
+        'API Reference:',
+        `http://${host}:${port}${this._apiReferenceEndpoint}`,
+      )
+    }
+
+    consola.info('Health Check:', `http://${host}:${port}/health`)
+    consola.info('Internal Host:', `http://${host}:${port}`)
+
+    if (this._ngrokUrl) {
+      consola.info('External Host:', this._ngrokUrl)
+      consola.info('External Inspect:', `http://${host}:4040/inspect/http`)
+    }
+
+    consola.box('Environment:', envService.get('NODE_ENV'))
+
+    console.log('------------------------------')
+  }
+
+  private async startJobs() {
+    await delay(5000) // Aguarda 5 segundos para garantir que a aplicação esteja totalmente inicializada
+
+    const cronJobs = await Promise.all(
+      this._cronJobs.map((job) => this.app.resolve(job)),
+    )
+
+    for (const cronJob of cronJobs) {
+      cronJob.start()
+    }
+
+    const eventJobs = await Promise.all(
+      this._eventJobs.map((job) => this.app.resolve(job)),
+    )
+
+    for (const eventJob of eventJobs) {
+      eventJob.setupSubscriptions()
+    }
+  }
+
+  addGlobalGuard(Guard: Type<CanActivate>) {
+    this._guards.push(
+      instanciateClassWithDependenciesInjection(this.app, Guard),
+    )
+    return this
+  }
+
+  addCronJob(job: CronJobClass) {
+    this._cronJobs.push(job)
+    return this
+  }
+
+  addEventJob(eventJob: EventJobClass) {
+    this._eventJobs.push(eventJob)
+    return this
+  }
+
+  addCustomGlobalExceptionFilter(filter: BaseExceptionFilter) {
+    this._globalExceptionFilter = filter
+    return this
+  }
+
+  addCustomPrismaValidationExceptionFilter(filter: BaseExceptionFilter) {
+    this._prismaValidationExceptionFilter = filter
+    return this
+  }
+
+  addCustomDomainExceptionFilter(filter: BaseExceptionFilter) {
+    this._domainExceptionFilter = filter
+    return this
+  }
+
+  addCustomZodExceptionFilter(filter: BaseExceptionFilter) {
+    this._zodExceptionFilter = filter
+    return this
+  }
+
+  useDoc(config: ApiDocConfig) {
+    const credentials = {
+      username: process.env.SWAGGER_USERNAME ?? '',
+      password: process.env.SWAGGER_PASSWORD ?? '',
+    }
+
+    if (
+      EnvConfig.isEnvDevelop &&
+      credentials.username &&
+      credentials.password
+    ) {
+      this.app.use(
+        [config.endpoint],
+        expressBasicAuth({
+          challenge: true,
+          users: {
+            [credentials.username]: credentials.password,
+          },
+        }),
+      )
+    }
+
+    const documentBuilder = new DocumentBuilder()
+      .setTitle(config.title)
+      .setVersion(config.version)
+
+    if (config.description) {
+      if (config.externalDoc) {
+        documentBuilder.setDescription(
+          `${config.description}\n\n[${config.externalDoc.message}](${config.externalDoc.url})`,
+        )
+      } else {
+        documentBuilder.setDescription(config.description)
+      }
+    }
+
+    if (config.authorizations) {
+      if (Array.isArray(config.authorizations)) {
+        for (const auth of config.authorizations) {
+          documentBuilder.addBearerAuth(auth.config, auth.name)
+          documentBuilder.addSecurityRequirements(auth.name)
+        }
+      } else {
+        documentBuilder.addBearerAuth()
+      }
+    }
+
+    if (config.servers) {
+      for (const server of config.servers) {
+        documentBuilder.addServer(server.url, server.description)
+      }
+    }
+
+    const document = SwaggerModule.createDocument(
+      this.app,
+      documentBuilder.build(),
+    )
+    const swaggerEndpoint = config.endpoint
+    this._apiReferenceEndpoint = swaggerEndpoint
+
+    if (config.ui === 'scalar' && swaggerEndpoint === '/') {
+      throw new InternalServerErrorException(
+        "O endpoint de documentação não pode ser '/' para UI Scalar.",
+      )
+    }
+
+    SwaggerModule.setup(swaggerEndpoint, this.app, document, {
+      swaggerUiEnabled: config.ui !== 'scalar',
+    })
+
+    if (config.ui === 'scalar') {
+      this.app.use(
+        swaggerEndpoint,
+        apiReference({
+          spec: {
+            content: document,
+          },
+          hideModels: true,
+          hideDownloadButton: true,
+          hideClientButton: true,
+          theme: config.theme ?? 'default',
+          hiddenClients: [
+            'libcurl',
+            'clj_http',
+            'restsharp',
+            'native',
+            'http1.1',
+            'asynchttp',
+            'nethttp',
+            'okhttp',
+            'unirest',
+            'xhr',
+            'okhttp',
+            'native',
+            'request',
+            'unirest',
+            'nsurlsession',
+            'cohttp',
+            'guzzle',
+            'http1',
+            'http2',
+            'webrequest',
+            'restmethod',
+            'requests',
+            'httr',
+            'native',
+            'httpie',
+            'wget',
+            'nsurlsession',
+            'undici',
+          ],
+          metaData: {
+            title: config.title,
+            description: config.description,
+          },
+        }),
+      )
+    }
+
+    return this
+  }
+
+  useNgrok(key: string) {
+    this._ngrokKey = key
+    return this
+  }
+
+  enableCors() {
+    this.app.enableCors({
+      credentials: true,
+      origin: true,
+      optionsSuccessStatus: 200,
+    })
+
+    return this
+  }
+
+  setAppName(name: string) {
+    KoalaGlobalVars.appName = name
+    return this
+  }
+
+  setInternalUserName(name: string) {
+    KoalaGlobalVars.internalUserName = name
+    return this
+  }
+
+  setDbTransactionContext(transactionContext: Type<PrismaTransactionalClient>) {
+    KoalaGlobalVars.dbTransactionContext = transactionContext
+    return this
+  }
+
+  async build() {
+    if (KoalaGlobalVars.dbTransactionContext) {
+      this.app.useGlobalFilters(this._prismaValidationExceptionFilter)
+    }
+
+    this.app.useGlobalFilters(
+      this._globalExceptionFilter,
+      this._domainExceptionFilter,
+      this._zodExceptionFilter,
+    )
+
+    for (const guard of this._guards) {
+      this.app.useGlobalGuards(guard)
+    }
+
+    if (this._ngrokKey) {
+      const envService = this.app.get(EnvService)
+      const port = envService.get('PORT') ?? 3000
+
+      await ngrok
+        .connect({
+          authtoken: this._ngrokKey,
+          addr: port,
+        })
+        .then((url) => {
+          this._ngrokUrl = url
+        })
+    }
+
+    this.startJobs()
+
+    return this.app
+  }
+
+  async serve(host?: string) {
+    const envService = this.app.get(EnvService)
+    const port = envService.get('PORT') ?? 3000
+
+    this.app.listen(port).then(() => this.showListeningMessage(port, host))
+  }
+
+  async buildAndServe(host?: string) {
+    await this.build()
+    await this.serve(host)
+  }
+}

package/src/core/koala-global-vars.ts

@@ -0,0 +1,8 @@
+import { Type } from '@nestjs/common'
+import { PrismaTransactionalClient } from './database/prisma-transactional-client'
+
+export class KoalaGlobalVars {
+  static appName: string = 'koala-nest'
+  static internalUserName: string = 'internal'
+  static dbTransactionContext?: Type<PrismaTransactionalClient>
+}

package/src/core/koala-nest-database.module.ts

@@ -0,0 +1,65 @@
+import {
+  DynamicModule,
+  ForwardReference,
+  InjectionToken,
+  Module,
+  Type,
+} from '@nestjs/common'
+import { RepositoryBase } from '../core/database/repository.base'
+import { EnvService } from '../env/env.service'
+import { PrismaService } from './database/prisma.service'
+
+export const PRISMA_TOKEN = 'PRISMA_SERVICE_TOKEN'
+
+export interface KoalaNestDatabaseProviderConfig<T> {
+  interface: InjectionToken
+  class: Type<T>
+}
+
+interface KoalaNestDatabaseModuleConfig {
+  repositories: KoalaNestDatabaseProviderConfig<RepositoryBase<any>>[]
+  services: KoalaNestDatabaseProviderConfig<any>[]
+  imports?: Array<Type<any> | DynamicModule | ForwardReference<any>>
+}
+
+@Module({})
+export class KoalaNestDatabaseModule {
+  static register(config: KoalaNestDatabaseModuleConfig): DynamicModule {
+    const imports = config.imports ?? []
+    const repositoriesToExport =
+      config.repositories?.map((repository) => repository.interface) ?? []
+    const repositoriesToProvide =
+      config.repositories?.map((repository) => ({
+        provide: repository.interface,
+        useClass: repository.class,
+      })) ?? []
+
+    const servicesToExport =
+      config.services?.map((service) => service.interface) ?? []
+    const servicesToProvide =
+      config.services?.map((service) => ({
+        provide: service.interface,
+        useClass: service.class,
+      })) ?? []
+
+    return {
+      module: KoalaNestDatabaseModule,
+      imports,
+      providers: [
+        {
+          provide: PRISMA_TOKEN,
+          useClass: PrismaService,
+        },
+        ...repositoriesToProvide,
+        ...servicesToProvide,
+        EnvService,
+      ],
+      exports: [
+        PRISMA_TOKEN,
+        ...repositoriesToExport,
+        ...servicesToExport,
+        ...imports,
+      ],
+    }
+  }
+}

package/src/core/koala-nest-http.module.ts

@@ -0,0 +1,44 @@
+import {
+  DynamicModule,
+  ForwardReference,
+  MiddlewareConsumer,
+  Module,
+  NestMiddleware,
+  NestModule,
+  Type,
+} from '@nestjs/common'
+import { EnvService } from '../env/env.service'
+import { AutoMappingProfile } from './mapping/auto-mapping-profile'
+import { AutoMappingModule } from './mapping/auto-mapping.module'
+
+interface KoalaNestHttpModuleConfig {
+  imports?: Array<Type<any> | DynamicModule | ForwardReference<any>>
+  automapperProfile: Type<AutoMappingProfile>
+  middlewares?: Type<NestMiddleware>[]
+}
+
+@Module({})
+export class KoalaNestHttpModule implements NestModule {
+  private static _config: KoalaNestHttpModuleConfig
+
+  static register(config: KoalaNestHttpModuleConfig): DynamicModule {
+    this._config = config
+    const imports = config.imports ?? []
+
+    return {
+      module: KoalaNestHttpModule,
+      imports: [
+        ...imports,
+        AutoMappingModule.register(config.automapperProfile),
+      ],
+      providers: [EnvService],
+      exports: [AutoMappingModule, ...imports],
+    }
+  }
+
+  configure(consumer: MiddlewareConsumer) {
+    KoalaNestHttpModule._config.middlewares?.forEach((middleware) =>
+      consumer.apply(middleware).forRoutes('*'),
+    )
+  }
+}

package/src/core/koala-nest.module.ts

@@ -0,0 +1,67 @@
+import { DynamicModule, Module, Provider, Type } from '@nestjs/common'
+import { ConfigModule } from '@nestjs/config'
+import { ZodType } from 'zod'
+import { envSchema } from '../env/env'
+import { EnvModule } from '../env/env.module'
+import { EnvService } from '../env/env.service'
+import { ILoggingService } from '../services/logging/ilogging.service'
+import { LoggingService } from '../services/logging/logging.service'
+import { IRedisService } from '../services/redis/iredis.service'
+import { RedisService } from '../services/redis/redis.service'
+import { IRedLockService } from '../services/redlock/ired-lock.service'
+import { RedLockService } from '../services/redlock/red-lock.service'
+import { CronJobHandlerBase } from './backgroud-services/cron-service/cron-job.handler.base'
+import { EventHandlerBase } from './backgroud-services/event-service/event-handler.base'
+import { HealthCheckModule } from './health-check/health-check.module'
+
+interface KoalaNestModuleConfig {
+  logging?: Provider<ILoggingService>
+  env?: ZodType
+  controllers?: Type<any>[]
+  healthCheck?: Type<any>
+  cronJobs?: Type<CronJobHandlerBase>[]
+  eventJobs?: Type<EventHandlerBase>[]
+}
+
+@Module({})
+export class KoalaNestModule {
+  static register(config?: KoalaNestModuleConfig): DynamicModule {
+    const controllers = config?.controllers ?? []
+    const healthCheck = config?.healthCheck ?? HealthCheckModule
+    const cronJobsProviders = config?.cronJobs ?? []
+    const eventJobsProviders = config?.eventJobs ?? []
+    const loggingServiceClass = config?.logging ?? LoggingService
+
+    return {
+      module: KoalaNestModule,
+      imports: [
+        ConfigModule.forRoot({
+          validate: (envData) => (config?.env ?? envSchema).parse(envData),
+          isGlobal: true,
+        }),
+        EnvModule,
+        healthCheck,
+        ...controllers,
+      ],
+      providers: [
+        ...cronJobsProviders,
+        ...eventJobsProviders,
+        {
+          provide: ILoggingService,
+          useValue: loggingServiceClass,
+        },
+        { provide: IRedisService, useClass: RedisService },
+        { provide: IRedLockService, useClass: RedLockService },
+        EnvService,
+      ],
+      exports: [
+        ...cronJobsProviders,
+        ...eventJobsProviders,
+        ILoggingService,
+        IRedisService,
+        IRedLockService,
+        EnvService,
+      ],
+    }
+  }
+}

package/src/core/mapping/auto-mapping-class-context.ts

@@ -0,0 +1,28 @@
+import { Type } from '@nestjs/common'
+import { IComparable, IComparableId } from '../utils/interfaces/icomparable'
+import { List } from '../utils/list'
+import { randomUUID } from 'crypto'
+
+export interface AutoMappingClassProp {
+  name: string
+  type: () => Type<any> | ArrayConstructor
+  compositionType?: () => Type<any> | ArrayConstructor
+  compositionAction?: 'onlySet' | 'addTo'
+}
+
+export class AutoMappingClassContext
+  implements IComparable<AutoMappingClassContext>
+{
+  _id: IComparableId
+  source: Type<any>
+  props = new List<AutoMappingClassProp>()
+
+  constructor(source: Type<any>) {
+    this._id = randomUUID()
+    this.source = source
+  }
+
+  equals(obj: AutoMappingClassContext): boolean {
+    return obj._id === this._id && this.source instanceof obj.source
+  }
+}

package/src/core/mapping/auto-mapping-context.ts

@@ -0,0 +1,26 @@
+import { Type } from '@nestjs/common'
+import { randomUUID } from 'node:crypto'
+import { IComparable, IComparableId } from '../utils/interfaces/icomparable'
+import { ForMemberDefinition } from './for-member'
+
+export class AutoMappingContext implements IComparable<AutoMappingContext> {
+  _id: IComparableId
+
+  constructor(
+    public source: Type<any>,
+    public target: Type<any>,
+    public forMemberDifinitions: ForMemberDefinition<any, any>,
+  ) {
+    this._id = randomUUID()
+    this.source = source
+    this.target = target
+  }
+
+  equals(obj: AutoMappingContext): boolean {
+    return (
+      obj._id === this._id &&
+      this.source instanceof obj.source &&
+      this.target instanceof obj.target
+    )
+  }
+}