@cristian-israel/giganet_lib_conecta 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Israel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,318 @@
+Perfeito! Aqui está a documentação atualizada, removendo completamente qualquer referência a `relations.ts` e refletindo que as relações agora são aplicadas automaticamente no `initModels` gerado pelo `sequelize-auto` ou no Service:
+
+---
+
+# 📚 Documentação Atualizada — Lib de Conexões (MySQL + Mongo + IXC)
+
+## 🎯 Objetivo
+
+Criar uma biblioteca desacoplada, escalável e tipada para:
+
+- Conexões com bancos MySQL e MongoDB
+- Reuso entre projetos
+- Padronização com logger
+- Estrutura modular e evolutiva
+- Singleton + Service pattern para acesso a dados
+
+---
+
+# 🧱 Estrutura Geral
+
+```
+/core
+  ├── mysql.connection.ts
+  ├── mongo.connection.ts
+  ├── database.factory.ts
+  ├── logger.ts
+  ├── retry.ts
+  ├── types.ts
+
+/databases
+  └── ixc-soft
+        ├── ixc-soft.service.ts
+        ├── ixc-soft.connection.ts
+        ├── ixc-soft.types.ts
+        └── models/
+              └── init-models.ts (gerado via sequelize-auto)
+
+/index.ts
+```
+
+---
+
+# ✅ 1. Conexões Base
+
+## 1.1 MySQL Connection
+
+```ts
+createMysqlConnection(config: MysqlConfig): Promise<Sequelize>
+```
+
+- Validação de dados
+- Logger padronizado
+- Tratamento de erro
+- Timeout / timezone
+- Retorna instância Sequelize
+
+---
+
+## 1.2 Mongo Connection
+
+```ts
+createMongoConnection(config: MongoConfig): Promise<Connection>
+```
+
+- URI dinâmica
+- Suporte a authSource
+- Logger
+- Tratamento de erro
+
+---
+
+# ✅ 2. Retry Pattern (Resiliência)
+
+```ts
+retry(fn, { retries: number, delay: number, onRetry?: (error, attempt) => void })
+```
+
+- Evita falha por instabilidade temporária
+- Reutilizável
+- Centralizado
+
+Exemplo com Mongo:
+
+```ts
+const conn = await retry(async () => {
+  const connection = createConnection(uri);
+  return await new Promise((resolve, reject) => {
+    connection.once("connected", () => resolve(connection));
+    connection.once("error", reject);
+  });
+});
+```
+
+---
+
+# ✅ 3. Factory de Conexões
+
+```ts
+createConnectionFactory(factoryFn);
+```
+
+- Singleton automático
+- Evita múltiplas instâncias
+- Centraliza criação de conexões
+
+---
+
+# ✅ 4. Logger
+
+```ts
+logger({
+  level?: "INFO" | "WARN" | "ERROR",
+  database: "MYSQL" | "MONGO",
+  context: string,
+  message: string
+});
+```
+
+- Padronização
+- Observabilidade
+- Fácil debug
+
+---
+
+# ✅ 5. Tipos Base
+
+```ts
+type MysqlConfig
+type MongoConfig
+type ConfigCreationConnection
+```
+
+- Tipagem das entradas
+- Segurança
+- Reuso
+
+---
+
+# ✅ 6. Implementação IXC (MySQL)
+
+## 6.1 Estrutura da conexão IXC
+
+```ts
+async function createIXCConnection(): Promise<IXCSoftConnection>;
+```
+
+Fluxo:
+
+1. Cria conexão MySQL via `createMysqlConnection`
+2. Inicializa models gerados via `sequelize-auto` (`initModels`)
+3. Retorna conexão tipada (`IXCSoftConnection`)
+
+> Relações são aplicadas dentro de `initModels` automaticamente; **não há mais arquivo separado de relations**.
+
+---
+
+## 6.2 Tipagem dos Models (forte)
+
+```ts
+export class IXCSoftCliente extends Model<
+  InferAttributes<IXCSoftCliente>,
+  InferCreationAttributes<IXCSoftCliente>
+> {
+  declare id: CreationOptional<number>;
+  declare razao: string;
+  declare fantasia: string | null;
+  declare ativo: string;
+}
+```
+
+- Autocomplete real
+- Segurança no `create`/`update`
+- Menos bugs
+- Tipagem apenas dos campos relevantes
+
+---
+
+## 6.3 Geração automática de Models
+
+### Ferramenta:
+
+```bash
+sequelize-auto
+```
+
+### Comando Exemplo:
+
+```bash
+npx sequelize-auto \
+  -h HOST \
+  -d DATABASE \
+  -u USER \
+  -p PORT \
+  -x PASSWORD \
+  -e mysql \
+  -o "./src/databases/ixc-soft/models" \
+  --lang ts
+```
+
+- Não editar arquivos gerados
+- Sempre regenerar quando schema mudar
+- Estrutura final acessível via `initModels(sequelize)`
+
+---
+
+# ✅ 7. Service Pattern (Singleton + acesso aos models)
+
+## 7.1 IXCSoftService
+
+```ts
+const ixcs = IXCSoftService.getInstance();
+await ixcs.init();
+const { Cliente, ClienteContrato } = ixcs.models;
+```
+
+### Principais decisões:
+
+1. **Singleton**: garante uma única instância por app
+2. **Init obrigatório**: chama `ixcs.init()` antes de usar os models
+3. **Models tipados**: `ixcs.models` retorna apenas os models do IXC
+4. **Static vs Getter**:
+   - `ixcs.models` (getter) → uso normal por instância
+   - `IXCSoftService.getModels()` → conveniência estática (chama o singleton internamente)
+
+---
+
+### 7.2 Vantagens do Service
+
+- Protege acesso direto à connection
+- Abstrai inicialização e relações
+- Permite apenas usar models e fazer queries
+- Facilita testes e refatorações futuras
+
+---
+
+# ✅ 8. Uso da lib no projeto
+
+```ts
+import { IXCSoftService } from "giganet_conecta";
+
+async function main() {
+  const ixcs = IXCSoftService.getInstance();
+  await ixcs.init();
+
+  const { Cliente, ClienteContrato } = ixcs.models;
+
+  const clientesAtivos = await Cliente.findAll({ where: { ativo: "S" } });
+}
+```
+
+- Não é necessário instanciar `connection` manualmente
+- O Service controla inicialização e singleton
+- Queries podem ser feitas diretamente nos models
+
+---
+
+# ✅ 9. Exportação da lib
+
+**Index da lib (`src/index.ts`)**:
+
+```ts
+export { IXCSoftService } from "./databases/ixc-soft/ixc-soft.service";
+export { OPAService } from "./databases/opa-suite/opa.service";
+// outros services que quiser expor
+```
+
+- Expor apenas Services
+- Conexões internas (`connection`, `initModels`) ficam encapsuladas
+
+---
+
+# 🧠 Arquitetura Atualizada (até 3.4)
+
+```
+core/
+  conexão + retry + logger
+
+databases/
+  ixc-soft/
+    service.ts (singleton + init + models)
+    connection.ts (interna)
+    types.ts
+    models/ (gerados via sequelize-auto, com relations aplicadas)
+
+index.ts
+  └── exporta apenas services
+```
+
+---
+
+# 📍 Status Atual
+
+| Etapa                    | Status                                      |
+| ------------------------ | ------------------------------------------- |
+| 1 — Conexões base        | ✅ Concluído                                |
+| 2 — Retry pattern        | ✅ Concluído                                |
+| 3.1 — Estrutura IXC      | ✅ Concluído                                |
+| 3.2 — Relations          | ❌ Removido (agora integrado no initModels) |
+| 3.3 — Tipagem Models     | ✅ Concluído                                |
+| 3.3.2 — Auto geração     | ✅ Definido                                 |
+| 3.4 — Service + Includes | ✅ Definido                                 |
+
+---
+
+# ⚡ Conclusão
+
+- Lib modular, escalável e tipada
+- Singleton + Service pattern protege inicialização
+- Geração automática de models via `sequelize-auto`
+- Queries podem ser feitas diretamente nos Services
+- Relações aplicadas automaticamente nos models
+- Base pronta para produção e fácil manutenção
+
+---
+
+Se quiser, posso complementar a documentação com **exemplos práticos de queries tipadas com includes**, mostrando como usar `cliente.contratos` com autocomplete seguro e filtros avançados.
+
+Quer que eu faça isso agora?