prisma-entity-gen 0.1.0

package/README.md

@@ -0,0 +1,368 @@
+# prisma-entity-gen
+
+Gerador de entities TypeScript a partir do `schema.prisma` via AST.
+
+Resolve o problema de lentidão do TypeScript em projetos com muitos modelos Prisma — cada model é gerado em um arquivo isolado com tipos explícitos, eliminando a inferência pesada do `@prisma/client`.
+
+---
+
+## Instalação
+
+```bash
+npm install -D prisma-entity-gen
+# ou
+pnpm add -D prisma-entity-gen
+```
+
+---
+
+## Uso rápido
+
+```bash
+npx prisma-entity-gen
+```
+
+Por padrão lê `prisma/schema.prisma` e gera em `src/entities`.
+
+---
+
+## Configuração
+
+Crie um `.entitygenrc.json` na raiz do projeto:
+
+```json
+{
+  "schemaPath": "prisma/schema.prisma",
+  "outputDir": "src/entities",
+  "mode": "type",
+  "relations": "optional",
+  "enumOutput": "enum",
+  "barrel": true,
+  "suffix": "entity",
+  "exclude": [],
+  "include": [],
+  "classValidator": false,
+  "classTransformer": false,
+  "dryRun": false,
+  "logLevel": "info"
+}
+```
+
+---
+
+## Opções de configuração
+
+### `schemaPath`
+**Tipo:** `string` — **Padrão:** `"prisma/schema.prisma"`
+
+Caminho para o arquivo `schema.prisma`. Aceita caminhos relativos e absolutos.
+
+Se seu projeto usa Prisma multi-file schema, aponte para o schema consolidado:
+
+```json
+{
+  "schemaPath": "node_modules/.prisma/client/schema.prisma"
+}
+```
+
+---
+
+### `outputDir`
+**Tipo:** `string` — **Padrão:** `"src/entities"`
+
+Diretório onde os arquivos de entity serão gerados. Criado automaticamente se não existir.
+
+---
+
+### `mode`
+**Tipo:** `"type" | "class" | "both"` — **Padrão:** `"type"`
+
+Define o formato de saída das entities.
+
+| Valor | Saída | Uso indicado |
+|---|---|---|
+| `"type"` | `export interface UserEntity` | Projetos TypeScript puros, melhor performance de compilação |
+| `"class"` | `export class UserEntity` | NestJS com `class-validator` / `class-transformer` |
+| `"both"` | Ambos em subpastas `/types` e `/classes` | Projetos que precisam dos dois formatos |
+
+```json
+{ "mode": "class" }
+```
+
+---
+
+### `relations`
+**Tipo:** `"optional" | "required"` — **Padrão:** `"optional"`
+
+Controla se campos de relação são opcionais ou obrigatórios na entity gerada.
+
+| Valor | Comportamento | Quando usar |
+|---|---|---|
+| `"optional"` | `Company?: CompanyEntity` | Queries sem `include` — o campo pode não existir |
+| `"required"` | `Company: CompanyEntity` | Sempre usa `include` nas queries que retornam o tipo |
+
+**`"optional"` (padrão):**
+```ts
+export interface UserEntity {
+  id: bigint;
+  Company?: CompanyEntity;  // só existe se vier com include
+}
+
+// funciona sem include
+const user = await prisma.user.findUnique({ where: { id } });
+// user.Company → undefined (sem erro de tipo)
+```
+
+**`"required"`:**
+```ts
+export interface UserEntity {
+  id: bigint;
+  Company: CompanyEntity;  // sempre obrigatório
+}
+
+// requer include em toda query que retornar UserEntity
+const user = await prisma.user.findUnique({
+  where: { id },
+  include: { Company: true },
+});
+```
+
+```json
+{ "relations": "required" }
+```
+
+---
+
+### `enumOutput`
+**Tipo:** `"enum" | "union"` — **Padrão:** `"enum"`
+
+Define o formato de saída dos enums.
+
+| Valor | Saída |
+|---|---|
+| `"enum"` | `export enum Role { ADMIN = "ADMIN" }` |
+| `"union"` | `export type Role = "ADMIN" \| "USER"` |
+
+Use `"union"` para evitar conflitos de tipo nominal com enums gerados pelo `@prisma/client`.
+Enums são nominais no TypeScript — dois enums com o mesmo nome e valores são tipos incompatíveis.
+`union` usa tipagem estrutural, aceitando qualquer string que corresponda ao valor.
+
+```json
+{ "enumOutput": "union" }
+```
+
+---
+
+### `barrel`
+**Tipo:** `boolean` — **Padrão:** `true`
+
+Gera um arquivo `index.ts` na raiz do `outputDir` que re-exporta todas as entities.
+
+```ts
+// src/entities/index.ts — gerado automaticamente
+export * from "./user.entity.js";
+export * from "./post.entity.js";
+export * from "./role.enum.js";
+// ...
+```
+
+Permite imports limpos no projeto:
+```ts
+import { UserEntity, PostEntity } from '@/entities';
+```
+
+---
+
+### `suffix`
+**Tipo:** `string` — **Padrão:** `"entity"`
+
+Sufixo dos arquivos gerados. O nome do model é convertido para kebab-case.
+
+```json
+{ "suffix": "entity" }
+```
+
+Resulta em: `user.entity.ts`, `post.entity.ts`, etc.
+
+---
+
+### `exclude`
+**Tipo:** `string[]` — **Padrão:** `[]`
+
+Lista de models a ignorar na geração. Útil para models internos ou de auditoria.
+
+```json
+{ "exclude": ["AuditLog", "Session", "MigrationHistory"] }
+```
+
+---
+
+### `include`
+**Tipo:** `string[]` — **Padrão:** `[]` (todos)
+
+Quando preenchido, gera apenas os models listados. Ignora todos os outros.
+
+```json
+{ "include": ["User", "Post", "Company"] }
+```
+
+---
+
+### `classValidator`
+**Tipo:** `boolean` — **Padrão:** `false`
+
+Quando `mode` é `"class"` ou `"both"`, adiciona decorators do `class-validator`.
+
+Requer instalação: `npm install class-validator`
+
+```ts
+// gerado com classValidator: true
+import { IsString, IsOptional, IsDate } from 'class-validator';
+
+export class UserEntity {
+  @IsString()
+  email!: string;
+
+  @IsOptional()
+  @IsString()
+  name?: string | null;
+}
+```
+
+---
+
+### `classTransformer`
+**Tipo:** `boolean` — **Padrão:** `false`
+
+Quando `mode` é `"class"` ou `"both"`, adiciona decorators do `class-transformer`.
+
+Requer instalação: `npm install class-transformer`
+
+```ts
+// gerado com classTransformer: true
+import { Type } from 'class-transformer';
+
+export class UserEntity {
+  @Type(() => PostEntity)
+  posts?: PostEntity[];
+}
+```
+
+---
+
+### `dryRun`
+**Tipo:** `boolean` — **Padrão:** `false`
+
+Simula a geração sem escrever arquivos no disco. Útil para visualizar o que seria gerado.
+
+```bash
+npx prisma-entity-gen --dry-run
+```
+
+---
+
+### `logLevel`
+**Tipo:** `"silent" | "info" | "verbose"` — **Padrão:** `"info"`
+
+| Valor | Comportamento |
+|---|---|
+| `"silent"` | Sem output |
+| `"info"` | Mostra arquivos gerados e resumo |
+| `"verbose"` | Mostra detalhes de cada etapa |
+
+---
+
+## Flags CLI
+
+Todas as opções do `.entitygenrc.json` podem ser passadas via CLI. Flags sobrescrevem o arquivo de configuração.
+
+```bash
+npx prisma-entity-gen [opções]
+
+Opções:
+  -s, --schema <path>        Caminho para o schema.prisma
+  -o, --output <dir>         Diretório de saída
+  -m, --mode <mode>          type | class | both
+  --relations <mode>         optional | required
+  --enum-output <format>     enum | union
+  --dry-run                  Simula sem escrever arquivos
+  --log-level <level>        silent | info | verbose
+  -V, --version              Exibe a versão
+  -h, --help                 Exibe ajuda
+```
+
+---
+
+## Integração com Prisma generate
+
+Adicione no `package.json` para rodar automaticamente após `prisma generate`:
+
+```json
+{
+  "scripts": {
+    "generate": "prisma generate && prisma-entity-gen"
+  }
+}
+```
+
+---
+
+## Uso com BaseRepository
+
+A lib gera apenas as entities. O `BaseRepository` do seu projeto usa o `T` genérico:
+
+```ts
+// antes — tipo do Prisma
+export class UserRepository extends BaseRepository<User> {}
+
+// depois — entity gerada
+export class UserRepository extends BaseRepository<UserEntity> {}
+```
+
+Os métodos do `BaseRepository` continuam funcionando com `Partial<T>` nos filtros:
+
+```ts
+// where tipado pela entity
+const users = await userRepository.findMany({ email: 'test@test.com' });
+// → UserEntity[]
+
+const user = await userRepository.getById(id);
+// → UserEntity
+```
+
+---
+
+## Comportamento dos tipos
+
+| Campo no schema | Entity gerada |
+|---|---|
+| `field String` | `field: string` |
+| `field String?` | `field?: string \| null` |
+| `field String @default(...)` | `field: string` |
+| `field Model` (relação) com `relations: "optional"` | `field?: ModelEntity` |
+| `field Model` (relação) com `relations: "required"` | `field: ModelEntity` |
+| `field Model?` (relação opcional) | `field?: ModelEntity \| null` |
+
+### Tipos escalares Prisma → TypeScript
+
+| Prisma | TypeScript |
+|---|---|
+| `String` | `string` |
+| `Boolean` | `boolean` |
+| `Int` | `number` |
+| `Float` | `number` |
+| `BigInt` | `bigint` |
+| `Decimal` | `string` |
+| `DateTime` | `Date` |
+| `Json` | `Record<string, unknown>` |
+| `Bytes` | `Buffer` |
+
+---
+
+## Arquivos de configuração suportados
+
+O gerador procura por arquivos de configuração nesta ordem:
+
+1. `.entitygenrc.json`
+2. `entitygen.config.json`
+3. `.entitygenrc`