@koalarx/nest 1.18.21 → 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @koalarx/nest
+
+## 3.0.1
+
+### Patch Changes
+
+- 3532e0d: Nova tentativa de publish
+- 276bc25: Teste de publicação do koala-nest
+- 9f4d18c: Adicionado link da dock no README inicial
+
+## 3.0.0
+
+### Major Changes
+
+- 9c3cdf1: CLI migrada para este repositório em estrutura de monorepo, atualizações de eslint e ajustes na documentação

package/package.json

@@ -1,41 +1,10 @@
 {
   "name": "@koalarx/nest",
-  "version": "1.18.21",
+  "version": "3.0.1",
   "description": "",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/igordrangel/koala-nest.git"
-  },
   "author": "Igor D. Rangel",
-  "license": "UNLICENSED",
-  "bugs": {
-    "url": "https://github.com/igordrangel/koala-nest/issues"
-  },
-  "homepage": "https://github.com/igordrangel/koala-nest#readme",
-  "types": "./koala-nest.d.ts",
-  "peerDependencies": {
-    "@koalarx/utils": "^4.2.1",
-    "@modelcontextprotocol/sdk": "^1.25.2",
-    "@nestjs/common": "^11.0.12",
-    "@nestjs/config": "^4.0.1",
-    "@nestjs/core": "^11.0.12",
-    "@nestjs/mapped-types": "^2.1.0",
-    "@nestjs/passport": "^11.0.5",
-    "@nestjs/platform-express": "^11.0.12",
-    "@nestjs/swagger": "^11.0.7",
-    "@prisma/adapter-pg": "^7.2.0",
-    "@prisma/client": "^7.2.0",
-    "@scalar/nestjs-api-reference": "^0.4.3",
-    "consola": "^3.4.2",
-    "dotenv": "^16.0.3",
-    "express-basic-auth": "^1.2.1",
-    "ioredis": "^5.3.2",
-    "ngrok": "^5.0.0-beta.2",
-    "passport": "^0.7.0",
-    "passport-custom": "^1.1.1",
-    "reflect-metadata": "^0.1.13",
-    "rimraf": "^3.0.2",
-    "zod": "^3.22.4",
-    "zod-validation-error": "^1.5.0"
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.0.0"
   }
-}
+}

package/src/core/backgroud-services/cron-service/cron-job.handler.base.ts

@@ -0,0 +1,66 @@
+import { delay } from '@koalarx/utils/KlDelay'
+import { ILoggingService } from '../../../services/logging/ilogging.service'
+import { IRedLockService } from '../../../services/redlock/ired-lock.service'
+import { KoalaGlobalVars } from '../../koala-global-vars'
+import { RequestResult } from '../../request-overflow/request-result'
+
+export type CronJobResponse = RequestResult<Error, null>
+export interface CronJobSettings {
+  isActive: boolean
+  timeInMinutes: number
+}
+
+export abstract class CronJobHandlerBase {
+  constructor(
+    private readonly redlockService: IRedLockService,
+    private readonly loggingService: ILoggingService,
+  ) {}
+
+  protected abstract run(): Promise<CronJobResponse>
+
+  protected abstract settings(): Promise<CronJobSettings>
+
+  async start(): Promise<void> {
+    const name = this.constructor.name
+
+    while (true) {
+      const settings = await this.settings()
+      const timeout = settings.timeInMinutes * 60 * 1000
+
+      if (settings.isActive) {
+        const ttlSecondsLock = timeout / 1000
+        const acquiredLock = await this.redlockService.acquiredLock(
+          name,
+          ttlSecondsLock,
+        )
+
+        if (acquiredLock) {
+          const error = await this.run()
+            .then((result) => {
+              if (result.isFailure()) {
+                return result.value
+              }
+              return null
+            })
+            .catch((error) => error)
+
+          if (error) {
+            try {
+              await this.loggingService.report({
+                error,
+                packageName: KoalaGlobalVars.appName,
+                loggedUsername: KoalaGlobalVars.internalUserName,
+              })
+            } catch {
+              console.error(error)
+            }
+          }
+        }
+      }
+
+      await delay(timeout)
+
+      await this.redlockService.releaseLock(name)
+    }
+  }
+}

package/src/core/backgroud-services/cron-service/cron-job.handler.spec.ts

@@ -0,0 +1,38 @@
+import { delay } from '@koalarx/utils/KlDelay'
+import { expect, spyOn, test } from 'bun:test'
+import { FakeLoggingService } from '../../../test/services/fake-logging.service'
+import { FakeRedLockService } from '../../../test/services/fake-red-lock.service'
+import { ok } from '../../request-overflow/request-result'
+import {
+  CronJobHandlerBase,
+  CronJobResponse,
+  CronJobSettings,
+} from './cron-job.handler.base'
+
+export class CronJobTest extends CronJobHandlerBase {
+  constructor() {
+    super(new FakeRedLockService(), new FakeLoggingService())
+  }
+
+  protected async settings(): Promise<CronJobSettings> {
+    return { isActive: true, timeInMinutes: 0.01 }
+  }
+
+  static async isCalled(): Promise<CronJobResponse> {
+    return ok(null)
+  }
+
+  protected run(): Promise<CronJobResponse> {
+    return CronJobTest.isCalled()
+  }
+}
+
+test('cron job', async () => {
+  const callbackSpy = spyOn(CronJobTest, 'isCalled')
+
+  new CronJobTest().start()
+
+  await delay(100)
+
+  expect(callbackSpy).toHaveBeenCalled()
+})

package/src/core/backgroud-services/event-service/event-class.ts

@@ -0,0 +1,5 @@
+export abstract class EventClass<TEntity = any> {
+  ocurredAt: Date = new Date()
+
+  constructor(public data?: TEntity) {}
+}

package/src/core/backgroud-services/event-service/event-handler.base.ts

@@ -0,0 +1,17 @@
+import { Type } from '@nestjs/common'
+import { EventClass } from './event-class'
+import { EventQueue } from './event-queue'
+
+export abstract class EventHandlerBase {
+  constructor(public readonly event: Type<EventClass>) {}
+
+  setupSubscriptions() {
+    EventQueue.register(
+      this.handleEvent.bind(this),
+      this.constructor.name,
+      this.event.name,
+    )
+  }
+
+  abstract handleEvent(event: InstanceType<this['event']>): Promise<void>
+}

package/src/core/backgroud-services/event-service/event-is-trigger.ts

@@ -0,0 +1,3 @@
+export class EventIsTrigger {
+  isTrigger() {}
+}

package/src/core/backgroud-services/event-service/event-job.ts

@@ -0,0 +1,28 @@
+import { Type } from '@nestjs/common'
+import { EventClass } from './event-class'
+import { EventHandlerBase } from './event-handler.base'
+import { EventQueue } from './event-queue'
+import { randomUUID } from 'node:crypto'
+
+export abstract class EventJob<TEntity> {
+  _id = randomUUID()
+
+  private _eventQueue: EventQueue[] = []
+
+  constructor() {}
+
+  abstract defineHandlers(): Array<Type<EventHandlerBase>>
+
+  get eventQueue(): EventQueue[] {
+    return this._eventQueue
+  }
+
+  public clearQueue() {
+    this._eventQueue = []
+  }
+
+  public addEvent(event: EventClass<TEntity>): void {
+    this.eventQueue.push(event)
+    EventQueue.markAggregateForDispatch(this)
+  }
+}

package/src/core/backgroud-services/event-service/event-queue.spec.ts

@@ -0,0 +1,47 @@
+import { Type } from '@nestjs/common'
+import { describe, expect, it, spyOn } from 'bun:test'
+import { EventClass } from './event-class'
+import { EventHandlerBase } from './event-handler.base'
+import { EventJob } from './event-job'
+import { EventQueue } from './event-queue'
+
+class CustomEvent extends EventClass {}
+
+class CustomEventHandler extends EventHandlerBase {
+  constructor() {
+    super(CustomEvent)
+  }
+
+  static async isCalled(): Promise<null> {
+    return null
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async handleEvent(event: CustomEvent): Promise<void> {
+    await CustomEventHandler.isCalled()
+  }
+}
+
+class CustomEventJob extends EventJob<any> {
+  defineHandlers(): Array<Type<EventHandlerBase>> {
+    return [CustomEventHandler]
+  }
+}
+
+describe('event queue', () => {
+  it('should be able to dispatch and listen to events', () => {
+    const callbackSpy = spyOn(CustomEventHandler, 'isCalled')
+
+    new CustomEventHandler().setupSubscriptions()
+
+    const jobs = new CustomEventJob()
+    jobs.addEvent(new CustomEvent())
+
+    expect(jobs.eventQueue).toHaveLength(1)
+
+    EventQueue.dispatchEventsForAggregate(jobs._id)
+
+    expect(callbackSpy).toHaveBeenCalled()
+    expect(jobs.eventQueue).toHaveLength(0)
+  })
+})

package/src/core/backgroud-services/event-service/event-queue.ts

@@ -0,0 +1,107 @@
+import { IComparableId } from '../../../core/utils/interfaces/icomparable'
+import { EventClass } from './event-class'
+import { EventJob } from './event-job'
+
+type EventJobCallback = (event: any) => void
+interface EventQueueJobItem {
+  eventClassName: string
+  callback: EventJobCallback
+}
+
+export class EventQueue {
+  private static handlersMap: Record<string, EventQueueJobItem[]> = {}
+
+  private static markedAggregates: EventJob<any>[] = []
+
+  public static markAggregateForDispatch(aggregate: EventJob<any>) {
+    const aggregateFound = !!this.findMarkedAggregateByID(aggregate._id)
+
+    if (!aggregateFound) {
+      this.markedAggregates.push(aggregate)
+    }
+  }
+
+  public static dispatchEventsForAggregate(id: IComparableId) {
+    const aggregate = this.findMarkedAggregateByID(id)
+
+    if (aggregate) {
+      this.dispatchAggregateEvents(aggregate)
+      aggregate.clearQueue()
+      this.removeAggregateFromMarkedDispatchList(aggregate)
+    }
+  }
+
+  public static register(
+    callback: EventJobCallback,
+    handlerClassName: string,
+    eventClassName: string,
+  ) {
+    const wasEventRegisteredBefore = handlerClassName in this.handlersMap
+
+    if (!wasEventRegisteredBefore) {
+      this.handlersMap[handlerClassName] = []
+    }
+
+    this.handlersMap[handlerClassName].push({
+      eventClassName,
+      callback,
+    })
+  }
+
+  public static clearHandlers() {
+    this.handlersMap = {}
+  }
+
+  public static clearMarkedAggregates() {
+    this.markedAggregates = []
+  }
+
+  private static dispatchAggregateEvents(aggregate: EventJob<any>) {
+    aggregate.eventQueue.forEach((event: EventClass<any>) =>
+      this.dispatch(event),
+    )
+  }
+
+  private static removeAggregateFromMarkedDispatchList(
+    aggregate: EventJob<any>,
+  ) {
+    const index = this.markedAggregates.findIndex(
+      (a) => a._id === aggregate._id,
+    )
+
+    this.markedAggregates.splice(index, 1)
+  }
+
+  private static findMarkedAggregateByID(
+    id: IComparableId,
+  ): EventJob<any> | undefined {
+    return this.markedAggregates.find((aggregate) => aggregate._id === id)
+  }
+
+  private static dispatch(event: EventClass<any>) {
+    const eventJobHandlers = this.markedAggregates.find((a) =>
+      a.eventQueue.find((e) => e === event),
+    )
+    const eventHandler = Object.keys(this.handlersMap).find((handlerName) =>
+      eventJobHandlers
+        ?.defineHandlers()
+        .find(
+          (handler) =>
+            handler.name === handlerName &&
+            this.handlersMap[handler.name].some(
+              (job) => job.eventClassName === event.constructor.name,
+            ),
+        ),
+    )
+
+    const isEventRegistered = !!eventHandler
+
+    if (isEventRegistered) {
+      const jobs = this.handlersMap[eventHandler]
+
+      for (const job of jobs) {
+        job.callback(event)
+      }
+    }
+  }
+}

package/src/core/constants/query-params.ts

@@ -0,0 +1,7 @@
+import type { QueryDirectionType } from '..'
+
+export const QUERY_FILTER_PARAMS = {
+  direction: 'asc' as QueryDirectionType,
+  page: 0,
+  limit: 30,
+}

package/src/core/controllers/base.controller.ts

@@ -0,0 +1,9 @@
+import { Response as HttpResponse } from 'express'
+
+export abstract class IController<Request, Response, Params = any> {
+  abstract handle(
+    request: Request,
+    params?: Params,
+    response?: HttpResponse,
+  ): Promise<Response>
+}

package/src/core/controllers/controller.decorator.ts

@@ -0,0 +1,10 @@
+import { RouterConfigBase } from './router-config.base'
+import { Controller as NestController } from '@nestjs/common'
+import { ApiTags } from '@nestjs/swagger'
+
+export function Controller(config: RouterConfigBase) {
+  return function (target: any) {
+    NestController(config.group)(target)
+    ApiTags(config.tag)(target)
+  }
+}

package/src/core/controllers/created-registre-response.base.ts

@@ -0,0 +1,17 @@
+import { ApiProperty } from '@nestjs/swagger'
+import { IComparableId } from '../../core/utils/interfaces/icomparable'
+
+export abstract class CreatedRegistreResponseBase<TId = IComparableId> {
+  @ApiProperty()
+  id: TId
+}
+
+export abstract class CreatedRegistreWithUUIDResponse extends CreatedRegistreResponseBase<string> {
+  @ApiProperty({ type: 'string', format: 'uuid' })
+  declare id: string
+}
+
+export abstract class CreatedRegistreWithIdResponse extends CreatedRegistreResponseBase<number> {
+  @ApiProperty({ type: 'integer', format: 'int32' })
+  declare id: number
+}

package/src/core/controllers/list-response.base.ts

@@ -0,0 +1,8 @@
+import { ApiProperty } from '@nestjs/swagger'
+
+export abstract class ListResponseBase<TResponse> {
+  abstract items: Array<TResponse>
+
+  @ApiProperty()
+  count: number
+}

package/src/core/controllers/pagination.request.ts

@@ -0,0 +1,41 @@
+import { ApiProperty } from '@nestjs/swagger'
+import { AutoMap } from '../mapping/auto-mapping.decorator'
+import { QUERY_FILTER_PARAMS } from '../constants/query-params'
+import type { QueryDirectionType } from '..'
+
+export type PaginatedRequestProps<T extends PaginationRequest> = Omit<
+  { [K in keyof T as T[K] extends Function ? never : K]: T[K] },
+  '_id'
+>
+
+export class PaginationRequest {
+  @ApiProperty({
+    required: false,
+    format: 'int32',
+    default: QUERY_FILTER_PARAMS.page,
+  })
+  @AutoMap()
+  page?: number = QUERY_FILTER_PARAMS.page
+
+  @ApiProperty({
+    required: false,
+    format: 'int32',
+    default: QUERY_FILTER_PARAMS.limit,
+  })
+  @AutoMap()
+  limit?: number = QUERY_FILTER_PARAMS.limit
+
+  @ApiProperty({
+    required: false,
+  })
+  @AutoMap()
+  orderBy?: string
+
+  @ApiProperty({
+    required: false,
+    enum: ['asc', 'desc'],
+    default: QUERY_FILTER_PARAMS.direction,
+  })
+  @AutoMap()
+  direction?: QueryDirectionType = QUERY_FILTER_PARAMS.direction
+}

package/src/core/controllers/router-config.base.ts

@@ -0,0 +1,14 @@
+export abstract class RouterConfigBase {
+  protected constructor(
+    private readonly _tag: string,
+    private readonly _group: string,
+  ) {}
+
+  get group() {
+    return this._group
+  }
+
+  get tag() {
+    return this._tag
+  }
+}

package/src/core/controllers/schemas/boolean.schema.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+
+export function booleanSchema() {
+  return z.coerce.string().transform((value) => {
+    if (value !== undefined) {
+      return value === 'true'
+    }
+    return undefined
+  })
+}

package/src/core/controllers/schemas/document-number.schema.ts

@@ -0,0 +1,23 @@
+import { validateCnpj, validateCpf } from '@koalarx/utils/KlString'
+
+export function documentNumberSchema(value: string) {
+  if (value !== '' && value !== 'undefined' && value !== 'null') {
+    if (value.includes('.')) {
+      if (value.length === 14) {
+        return validateCpf(value)
+      } else if (value.length === 18) {
+        return validateCnpj(value)
+      }
+    } else {
+      if (value.length === 11) {
+        return validateCpf(value)
+      } else if (value.length === 14) {
+        return validateCnpj(value)
+      }
+    }
+
+    return false
+  }
+
+  return true
+}

package/src/core/controllers/schemas/email.schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+export function emailSchema(email?: string, isRequired: boolean = false) {
+  if (isRequired && !email) {
+    return false
+  }
+
+  if (!email) {
+    return true
+  }
+
+  return z.coerce.string().max(50).email().parse(email)
+}

package/src/core/controllers/schemas/list-query.schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+import { QUERY_FILTER_PARAMS } from '../../constants/query-params'
+
+export const LIST_QUERY_SCHEMA = z.object({
+  page: z.coerce
+    .number()
+    .transform((value) => {
+      if (value) {
+        return value - 1
+      }
+      return QUERY_FILTER_PARAMS.page
+    })
+    .optional(),
+  limit: z.coerce.number().default(QUERY_FILTER_PARAMS.limit).optional(),
+  orderBy: z.string().optional(),
+  direction: z.enum(['asc', 'desc']).default('asc').optional(),
+})

package/src/core/controllers/schemas/native-enum.schema.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod'
+
+interface NativeEnumInterface<TEnum> {
+  isOptional: (value: string) => TEnum[keyof TEnum] | undefined
+  isRequired: (value: string) => TEnum[keyof TEnum]
+}
+
+export function nativeEnumSchema<TEnum extends z.EnumLike>(
+  nativeEnum: TEnum,
+): NativeEnumInterface<TEnum> {
+  return {
+    isOptional: (value: string) => {
+      if (value === 'null' || value === '') {
+        return undefined
+      }
+
+      return z.coerce
+        .number()
+        .transform((value) => {
+          if (value !== undefined) {
+            return z.nativeEnum(nativeEnum).parse(value)
+          }
+          return undefined
+        })
+        .parse(value)
+    },
+    isRequired: (value: string) => {
+      return z.coerce
+        .number()
+        .transform((value) => z.nativeEnum(nativeEnum).parse(value))
+        .parse(value)
+    },
+  }
+}

package/src/core/controllers/schemas/set-mask-document-number.schema.ts

@@ -0,0 +1,13 @@
+import { maskCnpj, maskCpf } from '@koalarx/utils'
+
+export function setMaskDocumentNumber(document?: string) {
+  if (!document) {
+    return ''
+  }
+
+  const documentWithoutMask = document.replace(/[^0-9]/g, '')
+
+  return documentWithoutMask.length === 11
+    ? maskCpf(documentWithoutMask)
+    : maskCnpj(documentWithoutMask)
+}