@cargolift-cdi/lib-nest-adapters

Adaptadores NestJS para integração com bibliotecas agnósticas de framework do ecossistema Middleware.

📌 Objetivo

Este repositório fornece uma camada de adaptação para uso de bibliotecas internas em aplicações NestJS, reduzindo boilerplate de integração e padronizando bootstrap de serviços transversais.

No contexto do Middleware Cargolift, a lib facilita a adoção de componentes críticos como Business Rule Engine (BRE) e Cache com foco em resiliência, segurança, escalabilidade, performance e disponibilidade.

Público-alvo: Desenvolvedores de serviços NestJS do monorepo Middleware.

✨ Funcionalidades

• BusinessRuleEngineModule (global): registra um RuleEngine singleton com provider TypeormLookupProvider e expõe serviço de execução de regras.
• BusinessRuleEngineService: abstrai a execução de regras via método run(config, payload).
• CacheModule (global): registra CacheManager com configuração centralizada via ConfigService.
• CacheService: inicializa/encerra cache automaticamente no ciclo de vida do módulo e oferece API get/set com fallback.
• Feature flag por ambiente: suporta desativação de cache por DISABLE_CACHE=true.

Diferenciais técnicos:

• Integração nativa com ciclo de vida do NestJS (OnModuleInit / OnModuleDestroy).
• Providers globais para reduzir repetição em múltiplos módulos.
• Compatibilidade com arquitetura orientada a módulos e princípios S.O.L.I.D. do monorepo.

🔍 Detalhamento

Business Rule Engine Adapter

O BusinessRuleEngineModule cria uma instância singleton de RuleEngine usando configuração bre fornecida por ConfigService. O provider de lookup é resolvido por TypeormLookupProvider.fromEnv(), permitindo carregamento de dados auxiliares para regras sem acoplamento ao framework consumidor.

Exemplo de uso

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import {
  BusinessRuleEngineModule,
  BusinessRuleEngineService,
} from '@cargolift-cdi/lib-nest-adapters';

@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true }), BusinessRuleEngineModule],
})
export class AppModule {}

export class ExampleUseCase {
  constructor(private readonly breService: BusinessRuleEngineService) {}

  async execute() {
    const result = await this.breService.run(
      {
        defaultOnError: false,
        rules: [],
      },
      { documentType: 'CTE', value: 1200 },
    );

    return result;
  }
}

Parâmetros:

• config: RulesConfiguration com regras e opções de execução.
• payload: unknown (objeto de entrada para avaliação das regras).

Retorno:

• Promise<ExecutionResult> com resultado da execução da engine.

Cache Adapter

O CacheModule injeta CacheManager com configuração cache vinda de ConfigService e adiciona logger NestJS. O CacheService inicia automaticamente o cache no bootstrap e encerra de forma segura no shutdown. Quando DISABLE_CACHE=true, a camada de cache é bypassada.

Exemplo de uso

import { Injectable } from '@nestjs/common';
import { CacheService } from '@cargolift-cdi/lib-nest-adapters';

@Injectable()
export class ProductService {
  constructor(private readonly cacheService: CacheService) {}

  async findById(id: string) {
    return this.cacheService.get(
      `product:${id}`,
      async () => {
        return { id, name: 'Produto de Exemplo' };
      },
      { ttl: 60 },
    );
  }
}

Parâmetros:

• key: string chave de cache.
• valueSetFunction?: () => Promise<T> função de fallback para popular cache em miss.
• options?: CacheStoreOptions opções como TTL e comportamento de armazenamento.

Retorno:

• get: Promise<T | undefined>.
• set: Promise<void>.

🛠 Tecnologias e Dependências

Dependências internas:

• @cargolift-cdi/business-rules-engine
• @cargolift-cdi/lib-cache

🚀 Instalação

Pré-requisitos

• Node.js: >= 18
• pnpm: versão compatível com workspace (recomendado >= 9)

Passos de instalação (monorepo)

1. Na raiz do workspace, instale dependências:

pnpm install

2. Build da lib:

pnpm --filter @cargolift-cdi/lib-nest-adapters build

3. Build de validação de tipagem:

pnpm --filter @cargolift-cdi/lib-nest-adapters build:smoke

Variáveis de ambiente

Além disso, a aplicação consumidora deve prover configurações para:

• bre (ex.: defaultOnError)
• cache (opções aceitas pelo CacheManager)

💡 Como Usar

Quickstart (em um serviço NestJS)

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import {
  BusinessRuleEngineModule,
  CacheModule,
} from '@cargolift-cdi/lib-nest-adapters';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    BusinessRuleEngineModule,
    CacheModule,
  ],
})
export class AppModule {}

Casos de uso avançados

• Bypass de cache em ambientes específicos: configure DISABLE_CACHE=true para troubleshooting e testes de fluxo sem camada de cache.
• BRE com lookup externo: configure ambiente para TypeormLookupProvider e centralize regras de negócio fora dos serviços de domínio.

📁 Estrutura do Projeto

.
├── src/
│   ├── index.ts
│   ├── bre/
│   │   ├── business-rule-engine.module.ts
│   │   └── business-rule-engine.service.ts
│   └── cache/
│       ├── cache.module.ts
│       └── cache.service.ts
├── package.json
├── tsconfig.json
└── README.md

• src/bre/: adapter NestJS para engine de regras de negócio.
• src/cache/: adapter NestJS para gerenciamento de cache.
• src/index.ts: ponto de export público da biblioteca.

🧪 Testes e Qualidade

Atualmente a lib possui scripts de build e smoke check de tipagem.

pnpm --filter @cargolift-cdi/lib-nest-adapters build
pnpm --filter @cargolift-cdi/lib-nest-adapters build:smoke

🤝 Contribuindo

Padrão de branches:

• main: branch principal.
• feature/*: novas funcionalidades.
• bugfix/*: correções.

Padrão de commits:

• Conventional Commits, por exemplo:
  • feat(cache): adiciona suporte a fallback assíncrono
  • fix(bre): corrige leitura de configuração defaultOnError

Processo de PR:

1. Crie branch a partir de main.
2. Implemente alteração com foco em baixo acoplamento.
3. Rode build/smoke localmente.
4. Abra PR descrevendo impacto técnico e operacional.

📄 Licença

Este projeto é distribuído sob a licença MIT.