{"_id":"@2bbelmiro/typeorm-query-buider-helper","_rev":"5-0df05e4299c4ef24c609789567a272c2","name":"@2bbelmiro/typeorm-query-buider-helper","dist-tags":{"latest":"1.0.7"},"versions":{"1.0.0":{"name":"@2bbelmiro/typeorm-query-buider-helper","version":"1.0.0","keywords":["typeorm","helper","query-builder","filter","parser","orm","database","typescript","javascript","express","nestjs","querybuilder","enterprise"],"author":{"name":"Belmiro Miguel"},"license":"MIT","_id":"@2bbelmiro/typeorm-query-buider-helper@1.0.0","maintainers":[{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"}],"dist":{"shasum":"60f82d96f9918aea41f3ee18a6b1197c394e66a4","tarball":"https://registry.npmjs.org/@2bbelmiro/typeorm-query-buider-helper/-/typeorm-query-buider-helper-1.0.0.tgz","fileCount":33,"integrity":"sha512-ge+LXlRqH9vVlHYh0iPqX5iblu/TOEH6gf8HuZL+4mZT2BMrzyVaR1BmDAWpJxTlQKUF+HmW4bT3jiieKAsaTA==","signatures":[{"sig":"MEQCIEz9T//yPEMM3punH5ka0XB8xl6+1dJ5QWb/qXIeV6hvAiAkOm3EgTGTtJTCpwdMq5K8OiA1PFDqxQuWeluNRbrSdw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71227},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"},"_npmVersion":"11.17.0","description":"Utilitário fluente e seguro para construção de consultas complexas no TypeORM sem exposição direta de operadores SQL manuais.","directories":{},"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typeorm":"^0.3.30","typescript":"^5.0.0","@types/node":"^20.19.43","reflect-metadata":"^0.2.2"},"peerDependencies":{"typeorm":"^0.3.0"},"_npmOperationalInternal":{"tmp":"tmp/typeorm-query-buider-helper_1.0.0_1783074542234_0.3723105140306442","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@2bbelmiro/typeorm-query-buider-helper","version":"1.0.1","keywords":["typeorm","helper","query-builder","filter","parser","orm","database","typescript","javascript","express","nestjs","querybuilder","enterprise"],"author":{"name":"Belmiro Miguel"},"license":"MIT","_id":"@2bbelmiro/typeorm-query-buider-helper@1.0.1","maintainers":[{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"}],"dist":{"shasum":"c343243aabd5bc5251342ca4aecc4152c9f361cb","tarball":"https://registry.npmjs.org/@2bbelmiro/typeorm-query-buider-helper/-/typeorm-query-buider-helper-1.0.1.tgz","fileCount":33,"integrity":"sha512-Cjt6lp0hbtDdVHbWTyR+WHktYkj9PxcLbQhJ/8BmKFne/6DmNAIKD5eneaLHvDiNceK9dWYYlAP+wfVl5ztlsw==","signatures":[{"sig":"MEUCIHRDqtkUdZgcic0NZx/N6H7K0yGYzDPM/3eBJ3ZI+Z2UAiEAg6pgu8U68oNDWJqQGBcQz8mVsxfe2z9V6f+BljYYDcU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81729},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"},"_npmVersion":"11.17.0","description":"Utilitário fluente e seguro para construção de consultas complexas no TypeORM sem exposição direta de operadores SQL manuais.","directories":{},"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typeorm":"^0.3.30","typescript":"^5.0.0","@types/node":"^20.19.43","reflect-metadata":"^0.2.2"},"peerDependencies":{"typeorm":"^0.3.0"},"_npmOperationalInternal":{"tmp":"tmp/typeorm-query-buider-helper_1.0.1_1783082799056_0.5978530459828035","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@2bbelmiro/typeorm-query-buider-helper","version":"1.0.2","keywords":["typeorm","helper","query-builder","filter","parser","orm","database","typescript","javascript","express","nestjs","querybuilder","enterprise"],"author":{"name":"Belmiro Miguel"},"license":"MIT","_id":"@2bbelmiro/typeorm-query-buider-helper@1.0.2","maintainers":[{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"}],"dist":{"shasum":"11b3add00ec152446f8f8f09157c866051587489","tarball":"https://registry.npmjs.org/@2bbelmiro/typeorm-query-buider-helper/-/typeorm-query-buider-helper-1.0.2.tgz","fileCount":35,"integrity":"sha512-FJtqexzkENert8dxBvUrpauOZ3CyxjqwyL3aC7ibJ7vKMOAL8B9qyPXbhqGXGoYLqH7xuXSNRZ+zJH1yQgduxQ==","signatures":[{"sig":"MEYCIQDKhOeEtKAOd/ZRodMaFe9sEaOE9fNJUcTAnaH1HEAI4QIhAMawSavs+0vDVuqk3fClGG9iTMm4VWylQzcwVIBniuNt","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":88026},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"},"_npmVersion":"11.17.0","description":"Utilitário fluente e seguro para construção de consultas complexas no TypeORM sem exposição direta de operadores SQL manuais.","directories":{},"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typeorm":"^0.3.30","typescript":"^5.0.0","@types/node":"^20.19.43","reflect-metadata":"^0.2.2"},"peerDependencies":{"typeorm":"^0.3.0"},"_npmOperationalInternal":{"tmp":"tmp/typeorm-query-buider-helper_1.0.2_1783097163318_0.24140930879291522","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@2bbelmiro/typeorm-query-buider-helper","version":"1.0.3","keywords":["typeorm","helper","query-builder","filter","parser","orm","database","typescript","javascript","express","nestjs","querybuilder","enterprise"],"author":{"name":"Belmiro Miguel"},"license":"MIT","_id":"@2bbelmiro/typeorm-query-buider-helper@1.0.3","maintainers":[{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"}],"dist":{"shasum":"c84a14dd0fd41243005d64670afc7388f18b679f","tarball":"https://registry.npmjs.org/@2bbelmiro/typeorm-query-buider-helper/-/typeorm-query-buider-helper-1.0.3.tgz","fileCount":35,"integrity":"sha512-OQCViWHf0Ey0HH4wbTiF8iS3iPFzQgcCTiqttFjGAjdiAfDz7Uc5A1oYilqOjePL0qSjRW/bA6mDO8p3lj/5IQ==","signatures":[{"sig":"MEYCIQCi1R/G/Ub3c1M8BZlMc0Dhx89DG5NYfvM6lCv2fI1fNwIhAPBAgGkLLsi/pmtN2FkHnNL9IIVUBPzPuQI2K35NHg3r","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":89225},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","gitHead":"d7fa9048d2698a3d50f4e4c91613feee3b892c9e","scripts":{"test":"vitest run","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"},"_npmVersion":"11.17.0","description":"Utilitário fluente e seguro para construção de consultas complexas no TypeORM sem exposição direta de operadores SQL manuais.","directories":{},"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typeorm":"^0.3.30","typescript":"^5.0.0","@types/node":"^20.19.43","reflect-metadata":"^0.2.2"},"peerDependencies":{"typeorm":"^0.3.0 || ^1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/typeorm-query-buider-helper_1.0.3_1783105385496_0.4347850871834098","host":"s3://npm-registry-packages-npm-production"}},"1.0.7":{"name":"@2bbelmiro/typeorm-query-buider-helper","version":"1.0.7","description":"Utilitário fluente e seguro para construção de consultas complexas no TypeORM sem exposição direta de operadores SQL manuais.","keywords":["typeorm","helper","query-builder","filter","parser","orm","database","typescript","javascript","express","nestjs","querybuilder","enterprise"],"license":"MIT","author":{"name":"Belmiro Miguel"},"type":"commonjs","main":"dist/index.js","types":"dist/index.d.ts","publishConfig":{"registry":"http://localhost:4873"},"scripts":{"build":"tsc","test":"vitest run","test:package":"npm run build && node -e \"import('./dist/index.js').then(() => console.log('package import ok'))\" && npm pack --dry-run --cache /tmp/npm-cache-web-provider","test:watch":"vitest","prepublishOnly":"npm run build","deploy":"npm version patch && npm run build && npm publish --access public","deploy:ngv":"npm version patch --no-git-tag-version && npm run build && npm publish --access public","deploy:npm":"npm publish --registry=https://npmjs.org  --access public"},"peerDependencies":{"typeorm":"^0.3.0 || ^1.0.0"},"devDependencies":{"@types/node":"^20.19.43","reflect-metadata":"^0.2.2","typeorm":"^0.3.30","typescript":"^5.0.0","vitest":"^1.0.0"},"gitHead":"a5d95e9c2d0ce0aa776d33ce9ece15e4a6f7d82f","_id":"@2bbelmiro/typeorm-query-buider-helper@1.0.7","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-Pl+N6fIJQ9Si1mK/fjZmA8LZ9tEU/ikteoAdnMRTyicGIPMSSEytfRi0UtRInakSnx9C32f8PgaFE03IEobyyA==","shasum":"d28ded666823ab8197f0182838754cfb263a8e20","tarball":"https://registry.npmjs.org/@2bbelmiro/typeorm-query-buider-helper/-/typeorm-query-buider-helper-1.0.7.tgz","fileCount":37,"unpackedSize":121199,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDB81T8m6mTI/ZijDK++xmcltewJ9iiec9d+0eSrtIcCQIgHFbY9Heil9fEd/h+bZL6AhhBLAiou8a7AWr6Y1Es+Bw="}]},"_npmUser":{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"},"directories":{},"maintainers":[{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/typeorm-query-buider-helper_1.0.7_1786586086993_0.20342019368585684"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T10:29:02.124Z","modified":"2026-08-13T01:54:47.301Z","1.0.0":"2026-07-03T10:29:02.364Z","1.0.1":"2026-07-03T12:46:39.200Z","1.0.2":"2026-07-03T16:46:03.461Z","1.0.3":"2026-07-03T19:03:05.710Z","1.0.7":"2026-08-13T01:54:47.134Z"},"author":{"name":"Belmiro Miguel"},"license":"MIT","keywords":["typeorm","helper","query-builder","filter","parser","orm","database","typescript","javascript","express","nestjs","querybuilder","enterprise"],"description":"Utilitário fluente e seguro para construção de consultas complexas no TypeORM sem exposição direta de operadores SQL manuais.","maintainers":[{"name":"2bbelmiro","email":"belmirofranciscomiguel@gmail.com"}],"readme":"# Enterprise TypeORM Helpers\n\nUtilitários de engenharia de software desenvolvidos para encapsular e estender as capacidades do TypeORM. Este ecossistema abstrai a complexidade operacional da manipulação de dados em bancos relacionais por meio de duas ferramentas principais: o **`EntityManagerHelper`** (focado no gerenciamento transacional e no ciclo de vida de persistência) e o **`QueryBuilderHelper`** (focado na construção dinâmica e segura de consultas SQL complexas, georreferenciamento e extração de atributos JSON).\n\n---\n\n## 📋 Pré-requisitos e Dependências\n\nPara garantir a correta integração e funcionamento dos utilitários, verifique se o seu ambiente atende aos seguintes requisitos:\n\n*   **Node.js**: Versão `18.x` ou superior.\n*   **TypeScript**: Versão `4.5` ou superior.\n*   **TypeORM**: Versão `0.3.x` instalada localmente no projeto.\n*   **NestJS** (Opcional): Necessário para a inicialização e injeção do `EntityManagerHelper` como um provider `@Injectable()`.\n*   **Drivers de Banco de Dados**: Compatível com PostgreSQL (para recursos de `ILIKE` e operadores JSON `->>`) ou MySQL/MariaDB (para funções JSON nativas).\n\n---\n\n## ⚖️ Matriz de Decisão Arquitetural: EntityManagerHelper vs. QueryBuilderHelper\n\nPara estruturar suas regras de negócio de maneira eficiente, utilize o guia abaixo para decidir qual ferramenta invocar em cada cenário de persistência:\n\n```\n                  ┌─────────────────────────────────────────┐\n                  │           REQUISITO DE DADOS            │\n                  └────────────────────┬────────────────────┘\n                                       │\n                ┌──────────────────────┴──────────────────────┐\n                ▼                                             ▼\n     [ Operação de Escrita, ]                      [ Operação de Leitura ]\n     [ Transação ou CRUD Simples]                  [ Dinâmica ou Complexa]\n                │                                             │\n                ▼                                             ▼\n   ┌─────────────────────────┐                   ┌─────────────────────────┐\n   │  EntityManagerHelper    │                   │   QueryBuilderHelper    │\n   │                         │                   │                         │\n   │  * .save(), .update()   │                   │  * Filtros opcionais    │\n   │  * .transaction()       │                   │  * .leftJoinAndSelect() │\n   │  * .sql`SELECT ...`     │                   │  * .paginate()          │\n   │  * .findOneBy()         │                   │  * Georreferenciamento  │\n   └─────────────────────────┘                   └─────────────────────────┘\n```\n\n### Análise Comparativa Detalhada\n\n1.  **Escritas e Gerenciamento de Estado**: \n    Sempre utilize o **`EntityManagerHelper`**. Operações como salvar, atualizar, remover ou executar inserções em massa (`insert`, `upsert`, `update`, `delete`) devem ser concentradas nele. Ele gerencia o estado da entidade no TypeORM de forma mais limpa do que gerar queries brutas de escrita no QueryBuilder.\n2.  **Garantia de Atomicidade (Transações)**: \n    Use o **`EntityManagerHelper`**. O método `transaction` cria um contexto isolado e seguro de execução, garantindo que se uma operação falhar, todo o bloco transacional sofra rollback.\n3.  **Leituras Diretas por Identificador ou Critérios Simples**: \n    Use o **`EntityManagerHelper`** (`findOne`, `findOneBy`, `find`). Estes métodos utilizam caminhos otimizados do ORM sem a sobrecarga de compilar blocos de consulta dinâmicos.\n4.  **Projeções Customizadas (`SELECT`) e Joins Complexos**: \n    Utilize o **`QueryBuilderHelper`**. Quando houver necessidade de selecionar colunas específicas de tabelas associadas, mapear subconsultas agregadas (como soma condicional com `.sum()`), ou aplicar filtros baseados em parâmetros dinâmicos enviados na requisição, o `QueryBuilderHelper` fornece uma API fluente e limpa que impede vazamento de lógica SQL para as camadas de serviço.\n\n---\n\n## 🛠️ Guia de Uso: EntityManagerHelper\n\nO `EntityManagerHelper` abstrai o `EntityManager` original do TypeORM e adiciona o comportamento de injeção automática e encapsulamento de transações.\n\n### Injeção de Dependência no NestJS\n\nRegistre o `EntityManagerHelper` no módulo correspondente para torná-lo disponível em seus serviços de domínio:\n\n```typescript\nimport { Module } from \"@nestjs/common\";\nimport { TypeOrmModule } from \"@nestjs/typeorm\";\nimport { EntityManagerHelper } from \"./entity-manager-helper\";\nimport { UsuarioEntity } from \"./usuario.entity\";\nimport { UsuarioService } from \"./usuario.service\";\n\n@Module({\n  imports: [TypeOrmModule.forFeature([UsuarioEntity])],\n  providers: [EntityManagerHelper, UsuarioService],\n  exports: [UsuarioService],\n})\nexport class UsuarioModule {}\n```\n\n### Implementação de Transações com Propagação de Contexto\n\nAo abrir uma transação, o `EntityManagerHelper` garante que todas as operações executadas no escopo do callback utilizem a mesma conexão física ativa do banco de dados, propagando um novo helper transacional (`tx`):\n\n```typescript\nimport { Injectable } from \"@nestjs/common\";\nimport { EntityManagerHelper } from \"./entity-manager-helper\";\nimport { UsuarioEntity } from \"./usuario.entity\";\nimport { LogAcessoEntity } from \"./log-acesso.entity\";\n\n@Injectable()\nexport class UsuarioService {\n  constructor(private readonly db: EntityManagerHelper) {}\n\n  public async desativarUsuario(usuarioId: number, justificativa: string): Promise<UsuarioEntity> {\n    return this.db.transaction(async (tx) => {\n      const usuario = await tx.findOne(UsuarioEntity, {\n        where: { id: usuarioId },\n      });\n\n      if (!usuario) {\n        throw new Error(\"O usuário informado não existe no sistema.\");\n      }\n\n      usuario.ativo = false;\n      await tx.save(UsuarioEntity, usuario);\n\n      const log = tx.create(LogAcessoEntity, {\n        usuarioId: usuario.id,\n        acao: \"DESATIVACAO_CONTA\",\n        detalhes: justificativa,\n        criadoEm: new Date(),\n      });\n      await tx.save(LogAcessoEntity, log);\n\n      return usuario;\n    });\n  }\n}\n```\n\n### Consultas Customizadas via Tagged Templates (`.sql`)\n\nPara cenários onde instruções SQL nativas são necessárias por questões de performance ou sintaxe específica do banco, o `EntityManagerHelper` expõe o método `.sql` usando tagged templates de forma segura:\n\n```typescript\nimport { Injectable } from \"@nestjs/common\";\nimport { EntityManagerHelper } from \"./entity-manager-helper\";\n\ninterface RelatorioResultado {\n  total_vendas: number;\n  mes_referencia: string;\n}\n\n@Injectable()\nexport class RelatorioService {\n  constructor(private readonly db: EntityManagerHelper) {}\n\n  public async obterFaturamentoAnual(ano: number): Promise<RelatorioResultado[]> {\n    return this.db.sql<RelatorioResultado[]>`\n      SELECT \n        SUM(valor) as total_vendas, \n        TO_CHAR(data_venda, 'YYYY-MM') as mes_referencia\n      FROM vendas\n      WHERE EXTRACT(YEAR FROM data_venda) = ${ano}\n      GROUP BY TO_CHAR(data_venda, 'YYYY-MM')\n      ORDER BY mes_referencia ASC\n    `;\n  }\n}\n```\n\n---\n\n## 🛠️ Guia de Uso: QueryBuilderHelper\n\nO `QueryBuilderHelper` gerencia a composição de consultas, limpando parâmetros especiais, removendo valores nulos/indefinidos automaticamente e traduzindo chamadas para SQL parametrizado seguro contra SQL Injection.\n\n### Inicialização e Filtros Combinados\n\nAbaixo está uma implementação completa de uma consulta complexa que combina agrupamento lógico de condições (`AND NOT`, `OR`), junções de tabelas, paginação e ordenação de nulos.\n\n```typescript\nimport { Injectable } from \"@nestjs/common\";\nimport { EntityManagerHelper } from \"./entity-manager-helper\";\nimport { QueryBuilderHelper } from \"./query-builder-helper\";\nimport { ContratoEntity } from \"./contrato.entity\";\nimport { PaginationResult } from \"./types\";\n\n@Injectable()\nexport class ContratoConsultaService {\n  constructor(private readonly db: EntityManagerHelper) {}\n\n  public async buscarContratosComplexos(filtros: {\n    empresaId?: number;\n    statusList?: string[];\n    buscaGlobal?: string;\n    valorMinimo?: number;\n    limite?: number;\n    pagina?: number;\n  }): Promise<PaginationResult<ContratoEntity>> {\n    const qb = this.db.createQueryBuilder(ContratoEntity, \"contrato\");\n\n    qb.leftJoinAndSelect(\"contrato.empresa\", \"empresa\")\n      .whereEqual(\"contrato.empresaId\", filtros.empresaId)\n      .whereIn(\"contrato.status\", filtros.statusList)\n      .whereGreaterThanOrEqual(\"contrato.valorTotal\", filtros.valorMinimo)\n      .andGroup((subQb) => {\n        subQb.whereLike(\"contrato.codigo\", filtros.buscaGlobal)\n             .orWhereLike(\"empresa.nomeFantasia\", filtros.buscaGlobal);\n      })\n      .orderBy(\"contrato.dataCriacao\", \"DESC\", \"NULLS LAST\");\n\n    return qb.paginate({\n      page: filtros.pagina,\n      limit: filtros.limite,\n    });\n  }\n}\n```\n\n### Consultas de Geolocalização e Campos JSON\n\nO código abaixo exemplifica buscas espaciais utilizando raio de distância e validação de chaves internas em colunas do tipo JSON:\n\n```typescript\nimport { Injectable } from \"@nestjs/common\";\nimport { EntityManagerHelper } from \"./entity-manager-helper\";\nimport { PontoColetaEntity } from \"./ponto-coleta.entity\";\n\n@Injectable()\nexport class GeoBuscaService {\n  constructor(private readonly db: EntityManagerHelper) {}\n\n  public async buscarPontosDisponiveis(\n    longitude: number,\n    latitude: number,\n    distanciaMaxMetros: number,\n    tipoResiduo?: string,\n  ): Promise<PontoColetaEntity[]> {\n    const qb = this.db.createQueryBuilder(PontoColetaEntity, \"ponto\");\n\n    // Limita a busca ao raio geográfico definido por coordenadas polares\n    qb.distanciaRaio(\"ponto.longitude\", \"ponto.latitude\", longitude, latitude, distanciaMaxMetros);\n\n    // Valida se a propriedade 'tipo' dentro do JSON 'meta_config' possui o valor desejado\n    if (tipoResiduo) {\n      qb.whereJsonContains(\"ponto.meta_config\", \"tipo\", tipoResiduo);\n    }\n\n    return qb.getMany();\n  }\n}\n```\n\n---\n\n## 📖 Referência Completa de APIs\n\n### 1. Métodos do EntityManagerHelper\n\n| Assinatura do Método | Tipo de Retorno | Descrição |\n| :--- | :--- | :--- |\n| `createQueryBuilder(entity, alias)` | `QueryBuilderHelper<Entity>` | Cria e retorna um encapsulador `QueryBuilderHelper` associado ao contexto do manager. |\n| `transaction(runInTx)` | `Promise<Result>` | Abre uma transação isolada e passa uma nova instância transacional do helper. |\n| `query(query, parameters)` | `Promise<T>` | Executa uma consulta SQL bruta com parâmetros posicionais. |\n| `sql(strings, ...values)` | `Promise<T>` | Executa queries SQL brutas parametrizadas por meio de Tagged Templates. |\n| `create(entityClass, plainObject)` | `Entity \\| Entity[]` | Instancia um novo objeto de entidade a partir de um objeto JavaScript puro. |\n| `save(targetOrEntity, entityOrOptions, options)` | `Promise<any>` | Insere ou atualiza registros na base de dados gerenciando o ciclo de vida da entidade. |\n| `remove(targetOrEntity, entityOrOptions, options)` | `Promise<any>` | Remove registros específicos do banco de dados. |\n| `insert(target, entity)` | `Promise<InsertResult>` | Executa uma instrução SQL de inserção direta, ignorando eventos do ciclo de vida do ORM. |\n| `upsert(target, entityOrEntities, conflictPathsOrOptions)` | `Promise<InsertResult>` | Insere novos registros ou atualiza existentes em caso de colisão de chaves únicas. |\n| `update(target, criteria, partialEntity, options)` | `Promise<UpdateResult>` | Executa uma atualização em massa de registros correspondentes aos critérios de busca. |\n| `delete(targetOrEntity, criteria)` | `Promise<DeleteResult>` | Executa a deleção física de registros conforme os critérios fornecidos. |\n| `find(entityClass, options)` | `Promise<Entity[]>` | Retorna uma lista de registros correspondentes às opções de busca do TypeORM. |\n| `findOne(entityClass, options)` | `Promise<Entity \\| null>` | Retorna o primeiro registro correspondente às opções de busca fornecidas. |\n| `findOneBy(entityClass, where)` | `Promise<Entity \\| null>` | Atalho otimizado para encontrar um registro através de correspondências diretas. |\n| `count(entityClass, options)` | `Promise<number>` | Retorna o número de registros na tabela com base nos filtros especificados. |\n| `getRepository(target)` | `Repository<Entity>` | Retorna a instância padrão do repositório TypeORM da entidade informada. |\n| `getManager()` | `EntityManager` | Retorna o `EntityManager` puro subjacente. |\n\n### 2. Métodos do QueryBuilderHelper\n\n#### Parâmetros e Filtros de Atributo\n*   `setParameter(key, value)`: Define um parâmetro isolado no contexto da query.\n*   `setParameters(parameters)`: Define um lote de parâmetros utilizando um dicionário de chave/valor.\n*   `where(field, value, op)`: Aplica uma cláusula genérica `andWhere` com o operador especificado (padrão: `=`).\n*   `whereEqual(field, value)` / `orWhereEqual(field, value)`: Compara igualdade de atributo com `AND` ou `OR`.\n*   `whereNotEqual(field, value)` / `orWhereNotEqual(field, value)`: Compara desigualdade de atributo com `AND` ou `OR`.\n*   `whereGreaterThan(field, value)` / `orWhereGreaterThan(field, value)`: Condicional de maior que (`>`).\n*   `whereGreaterThanOrEqual(field, value)`: Condicional de maior ou igual (`>=`).\n*   `whereLessThan(field, value)` / `orWhereLessThan(field, value)`: Condicional de menor que (`<`).\n*   `whereLessThanOrEqual(field, value)`: Condicional de menor ou igual (`<=`).\n\n#### Operações de Lista e Intervalo\n*   `whereIn(field, values)` / `orWhereIn(field, values)`: Filtra se o valor pertence a uma lista (`IN (:...param)`).\n*   `whereNotIn(field, values)` / `orWhereNotIn(field, values)`: Filtra se o valor não pertence a uma lista (`NOT IN (:...param)`).\n*   `whereBetween(field, min, max)` / `orWhereBetween(field, min, max)`: Filtra registros dentro de uma faixa inclusiva (`BETWEEN`).\n*   `whereNotBetween(field, min, max)` / `orWhereNotBetween(field, min, max)`: Filtra registros fora de uma faixa inclusiva (`NOT BETWEEN`).\n\n#### Busca de Texto (Like/Search)\n*   `whereLike(field, value)` / `orWhereLike(field, value)`: Busca parcial não-case-sensitive usando `ILIKE %valor%`.\n*   `whereNotLike(field, value)` / `orWhereNotLike(field, value)`: Busca parcial excludente usando `NOT ILIKE %valor%`.\n*   `whereSearch(fields, term)` / `orWhereSearch(fields, term)`: Aplica agrupamentos de busca em múltiplas colunas para o mesmo termo de pesquisa.\n*   `whereNotSearch(fields, term)` / `orWhereNotSearch(fields, term)`: Aplica exclusão de busca multi-colunas para o termo.\n\n#### Operações de JSON\n*   `whereJsonContains(field, jsonPath, value)` / `orWhereJsonContains(field, jsonPath, value)`: Verifica igualdade em atributos aninhados em campos JSON (PostgreSQL `->>` ou MySQL `JSON_EXTRACT`).\n*   `whereNotJsonContains(field, jsonPath, value)` / `orWhereNotJsonContains(field, jsonPath, value)`: Verifica desigualdade em campos JSON aninhados.\n\n#### Operações de Datas\n*   `whereDate(field, date)` / `orWhereDate(field, date)`: Compara apenas a parte da data de um atributo de data e hora (`DATE(field) = DATE(valor)`).\n*   `whereNotDate(field, date)` / `orWhereNotDate(field, date)`: Compara a desigualdade da data.\n*   `whereDateRange(field, startDate, endDate)` / `orWhereDateRange(field, startDate, endDate)`: Filtra registros em um intervalo de datas arredondando as horas (`00:00:00.000` para início e `23:59:59.999` para término).\n*   `whereNotDateRange(field, startDate, endDate)` / `orWhereNotDateRange(field, startDate, endDate)`: Filtra a exclusão do intervalo de datas.\n\n#### Associações (Joins)\n*   `leftJoin(relation, alias, condition, parameters)`: Adiciona uma junção externa esquerda sem carregar as propriedades na projeção final.\n*   `innerJoin(relation, alias, condition, parameters)`: Adiciona uma junção interna.\n*   `leftJoinAndSelect(relation, alias, condition, parameters)`: Adiciona uma junção externa esquerda e inclui as colunas associadas no mapeamento final do TypeORM.\n*   `innerJoinAndSelect(relation, alias, condition, parameters)`: Adiciona uma junção interna e seleciona as colunas.\n*   `leftJoinAndMapOne(mapToProperty, relation, alias, condition, parameters)`: Mapeia o resultado de um join esquerdo para um atributo singular da entidade de origem.\n*   `leftJoinAndMapMany(mapToProperty, relation, alias, condition, parameters)`: Mapeia o resultado de um join esquerdo para uma lista de atributos da entidade de origem.\n\n#### Agrupamentos Lógicos, Paginação e Ordenação\n*   `andGroup(callback)` / `orGroup(callback)`: Encapsula filtros internos em blocos com parênteses lógicos (`Brackets`).\n*   `andNotGroup(callback)` / `orNotGroup(callback)`: Encapsula e inverte a lógica de filtros internos (`NOT (condições)`).\n*   `orderBy(sort, order, nulls)` / `addOrderBy(sort, order, nulls)`: Configura ordenações de colunas e define a prioridade de nulos (`NULLS FIRST` ou `NULLS LAST`).\n*   `limit(value)` / `offset(value)`: Aplica limites e offsets numéricos puros na query SQL.\n*   `take(value)` / `skip(value)`: Aplica limites e offsets considerando a integridade de relações um-para-muitos do ORM.\n*   `groupBy(fields)`: Agrupa resultados da query de acordo com uma ou mais propriedades.\n*   `having(condition, parameters)`: Aplica condições de agregação pós-agrupamento.\n*   `whereNull(field)` / `orWhereNull(field)`: Filtra registros nulos (`IS NULL`).\n*   `whereNotNull(field)` / `orWhereNotNull(field)`: Filtra registros não nulos (`IS NOT NULL`).\n*   `withDeleted()`: Inclui registros marcados como excluídos via exclusão lógica (soft delete).\n*   `whereCustom(sql, params)` / `orWhereCustom(sql, params)`: Insere condições SQL livres parametrizadas diretamente na query.\n*   `sum(fun, alias)`: Realiza uma contagem de agregação condicional no escopo de um sub-select.\n*   `paginate(options)`: Executa a consulta, calcula os totais e retorna o padrão `PaginationResult<T>` com metadados para controle do front-end.\n\n#### Métodos de Execução e Inspeção\n*   `getMany()`: Executa e retorna uma lista de instâncias da entidade.\n*   `getOne()`: Executa e retorna uma instância ou `null`.\n*   `getOneOrFail()`: Executa e lança um erro caso nenhum registro satisfaça a query.\n*   `getManyAndCount()`: Executa a query de listagem e retorna um array contendo a lista de entidades e o total absoluto de registros.\n*   `getRawMany()`: Retorna os registros mapeados de forma plana diretamente do driver de banco.\n*   `getRawOne()`: Retorna um único registro plano mapeado.\n*   `getCount()`: Executa a consulta retornando somente a contagem total de registros do filtro.\n*   `getSql()`: Retorna o SQL bruto gerado pelo compilador do TypeORM e seus parâmetros nomeados associados.\n*   `getSqlCompiled()`: Retorna uma representação legível e compilada do SQL, substituindo marcadores de parâmetros pelos valores reais correspondentes.\n*   `build()`: Retorna a instância do `SelectQueryBuilder` puro subjacente.\n\n---\n\n## 📁 Estrutura de Diretórios do Projeto\n\n```text\n/\n├── src/\n│   ├── index.ts                             # Arquivo de barril (exportações públicas)\n│   ├── types.ts                             # Definição de contratos, interfaces e enums\n│   ├── entity-manager-helper.ts             # Facade injetável e gerenciador de transação\n│   ├── query-builder-helper.ts              # Orquestrador central de composição de queries\n│   ├── query-builder-helper-conditions.ts   # Utilitários de comparadores matemáticos e igualdade\n│   ├── query-builder-helper-custom.ts       # Suporte para injeção de trechos SQL dinâmicos\n│   ├── query-builder-helper-geo.ts          # Cálculos de polígonos, bounding box e raios espaciais\n│   ├── query-builder-helper-grouping.ts     # Gerenciamento de blocos de decisão agrupados (Brackets)\n│   ├── query-builder-helper-joins.ts        # Métodos de junção, mapeamentos um-para-um e muitos\n│   ├── query-builder-helper-json.ts         # Adaptadores para tratamento de queries em campos JSON\n│   ├── query-builder-helper-like-search.ts  # Gerenciamento de filtros parciais e busca em lote\n│   ├── query-builder-helper-null.ts         # Abstrações para validação de nulos e exclusão lógica\n│   ├── query-builder-helper-order-pagination.ts # Utilitários para ordenação, agrupamentos e agrupamentos HAVING\n│   ├── query-builder-helper-parameters.ts   # Métodos de atribuição de variáveis de escopo\n│   ├── query-builder-helper-range-date.ts   # Abstração de tratamento de datas e períodos temporais\n│   └── query-builder-helper-utils.ts        # Compiladores de depuração e motor de paginação\n├── package.json                             # Configuração de dependências do módulo\n├── tsconfig.json                            # Configuração de compilação TypeScript\n└── README.md                                # Documentação técnica de consumo do ecossistema\n```\n\n---\n\n## 🧪 Suíte de Testes e Validação\n\nPara executar as suítes de testes automatizados e validar o correto funcionamento de todos os helpers de banco de dados, execute os comandos descritos abaixo:\n\n1. Instale as dependências de desenvolvimento necessárias para testes (como Jest e drivers de mock):\n```bash\nnpm install\n```\n\n2. Execute todos os testes unitários e integrados:\n```bash\nnpm run test\n```\n\n3. Execute a validação de cobertura (Coverage) para verificar o índice de cobertura das linhas dos arquivos utilitários:\n```bash\nnpm run test:cov\n```","readmeFilename":"README.md"}