vsrepo 1.0.4 → 1.0.6

package/README.md

@@ -1,60 +1,88 @@
-# VSRepo
+# VSRepository
 
-Biblioteca de repository para projetos que usam Prisma.  
-O VSRepo permite criar repositories tipados com métodos base (`get`, `save` e `remove`) e métodos dinâmicos inferidos pelo nome, como:
+![npm](https://img.shields.io/npm/v/vsrepo?style=flat-square)
+![license](https://img.shields.io/github/license/jaobrabo123/vsrepository?style=flat-square)
 
-- `findByEmail`
-- `findManyPaginated`
-- `updateById`
-- `deleteManyByIdIn`
+Biblioteca de repository pattern para projetos que usam **Prisma**, com suporte completo a **TypeScript** e **type inference** automático.
 
-Tudo com inferência automática baseada no Prisma Client do próprio projeto.
+O VSRepository permite criar repositories fortemente tipados com:
+
+- **Métodos base** automáticos: `get`, `save`, `remove`
+- **Métodos dinâmicos** inferidos pelo nome: `findByEmail`, `findManyPaginated`, `updateById`, `deleteManyByIdIn`
+- **Select models** reutilizáveis para diferentes projeções de dados
+- **Type safety** em 100% das operações
+- **Transações** nativas do Prisma
+- **Extensibilidade** com métodos personalizados
 
 ---
 
-# Instalação
+## Sumário
+
+- [Instalação](#instalação)
+- [Gerando os tipos](#gerando-os-tipos)
+- [Uso básico](#uso-básico)
+- [Integração com NestJS](#integração-com-nestjs)
+- [Métodos base](#métodos-base)
+- [Select Models](#select-models)
+- [requiredWhere](#requiredwhere)
+- [Métodos dinâmicos](#métodos-dinâmicos)
+  - [Prefixos disponíveis](#prefixos-disponíveis)
+  - [Filtros de campo](#filtros-de-campo)
+  - [Operadores lógicos](#operadores-lógicos)
+  - [Filtros de relação](#filtros-de-relação)
+  - [Sufixos de paginação e ordenação](#sufixos-de-paginação-e-ordenação)
+  - [Configuração de métodos](#configuração-de-métodos)
+- [Relações no save](#relações-no-save)
+- [Transações](#transações)
+- [Extendendo um repository](#extendendo-um-repository)
+- [Tratamento de erros](#tratamento-de-erros)
+- [Tipos utilitários](#tipos-utilitários)
+- [API Reference](#api-reference)
+- [Requisitos](#requisitos)
+- [Troubleshooting](#troubleshooting)
+
+---
 
-Instale o VSRepo e o Prisma Client:
+## Instalação
 
 ```bash
-pnpm add vsrepo @prisma/client
+npm i vsrepo @prisma/client
 ```
 
 Gere o Prisma Client:
 
 ```bash
-pnpm prisma generate
+npx prisma generate
 ```
 
 ---
 
-# Gerando os tipos do VSRepo
+## Gerando os tipos
 
-O VSRepo precisa conhecer o caminho real do seu Prisma Client para gerar as tipagens corretamente.
-
-Execute:
+O VSRepository precisa conhecer o caminho real do seu Prisma Client para gerar as tipagens corretamente.
 
 ```bash
-pnpm vsrepo generate --output src/generated/vsrepo --prisma src/generated/prisma/client
+npx vsrepo generate
 ```
 
-ou:
+Equivale a:
 
 ```bash
-pnpm vsrepo generate -o src/generated/vsrepo -p src/generated/prisma/client
+npx vsrepo generate \
+  --output src/generated/vsrepo \
+  --prisma src/generated/prisma
 ```
 
-## O que esse comando faz
+**Flags disponíveis:**
 
-O script:
+| Flag       | Alias | Padrão                 |
+| ---------- | ----- | ---------------------- |
+| `--output` | `-o`  | `src/generated/vsrepo` |
+| `--prisma` | `-p`  | `src/generated/prisma` |
 
-1. Lê os arquivos de tipagem internos do VSRepo
-2. Substitui o import do Prisma pelo caminho informado em `--prisma`
-3. Gera uma façade tipada dentro da pasta definida em `--output`
+**Arquivos gerados:**
 
-Arquivos gerados:
-
-```txt
+```
 src/generated/vsrepo/
 ├── VSRepoError.ts
 ├── VSRepoError.types.d.ts
@@ -63,125 +91,67 @@ src/generated/vsrepo/
 └── index.ts
 ```
 
----
-
-# Como importar depois
-
-Após gerar os arquivos:
+Após gerar, importe sempre a partir da pasta gerada:
 
 ```ts
 import { setupVSRepo } from "../generated/vsrepo";
+// ou
+import { setupVSRepo, type SelectModels, type WhereModel } from "../generated/vsrepo";
 ```
 
-ou:
-
-```ts
-import {
-  setupVSRepo,
-  type SelectModels,
-  type WhereModel,
-} from "../generated/vsrepo";
-```
-
-Você NÃO deve mais importar diretamente de `vsrepo`.
-
 ---
 
-# Uso básico
+## Uso básico
 
-## Criando o Prisma Client
+### Configurando o Prisma Client
 
 ```ts
-// src/db.ts
-import { PrismaClient } from "@prisma/client";
+// src/configs/db.ts
+import { PrismaClient } from '../generated/prisma/client';
+import { PrismaPg } from '@prisma/adapter-pg';
+import 'dotenv/config';
 
-const prisma = new PrismaClient();
+const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
+const prisma = new PrismaClient({ adapter });
 
 export default prisma;
 ```
 
----
-
-# Criando um repository
+### Criando um repository
 
 ```ts
 // src/repositories/usuarioRepository.ts
+import prisma from "../configs/db";
+import { setupVSRepo } from "../generated/vsrepo";
+import type { Usuario } from "../generated/prisma/client";
 
-import prisma from "../db";
-
-import {
-  setupVSRepo,
-  type SelectModels,
-  type WhereModel,
-} from "../generated/vsrepo";
-
-import type { Prisma } from "@prisma/client";
-
-type Usuario = Prisma.usuarioGetPayload<{
-  include: {
-    perfil: true;
-    postagens: true;
-  };
-}>;
-
-const usuarioSelectModels = {
-  public: {
-    id: true,
-    nome: true,
-    email: true,
-  },
-
-  minimal: {
-    id: true,
-  },
-} satisfies SelectModels<"usuario">;
-
-const usuarioRequiredWhere = {
-  ativo: true,
-} satisfies WhereModel<"usuario">;
-
-const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
+const usuarioRepository = setupVSRepo<Usuario, "usuario">()({
   tableName: "usuario",
   pkName: "id",
 
-  selectModels: usuarioSelectModels,
+  selectModels: {
+    public: { id: true, nome: true, email: true },
+    minimal: { id: true },
+  },
   defaultSelectModel: "public",
 
-  requiredWhere: usuarioRequiredWhere,
+  requiredWhere: { ativo: true },
 
   methods: {
-    findByEmail: {
-      map: true,
-      fbMode: "one",
-    },
-
-    findManyPaginated: {
-      map: true,
-    },
-
-    updateById: {
-      map: true,
-    },
-
-    deleteManyByIdIn: {
-      map: true,
-      whereType: "overwrite",
-    },
-
-    count: {
-      map: true,
-    },
+    findByEmail: { map: true, fbMode: "one" },
+    findManyPaginated: { map: true },
+    updateById: { map: true },
+    deleteManyByIdIn: { map: true, whereType: "overwrite" },
+    count: { map: true },
   },
-});
-
-const usuarioRepository = usuarioVSRepo.build(prisma);
+}).build(prisma);
 
 export default usuarioRepository;
 ```
 
----
+> `selectModels` e `requiredWhere` podem ser declarados fora do `setupVSRepo` se você precisar exportá-los para uso em outros arquivos.
 
-# Usando o repository
+### Usando o repository
 
 ```ts
 import usuarioRepository from "./repositories/usuarioRepository";
@@ -192,57 +162,196 @@ const usuario = await usuarioRepository.save({
   senha: "password",
 });
 
-const usuarioEncontrado = await usuarioRepository.get(usuario.id);
-
+const encontrado = await usuarioRepository.get(usuario.id);
 const porEmail = await usuarioRepository.findByEmail("joao@email.com");
 
-await usuarioRepository.updateById(usuario.id, {
-  nome: "Joao Pedro",
-});
-
+await usuarioRepository.updateById(usuario.id, { nome: "Joao Pedro" });
 await usuarioRepository.remove(usuario.id);
 ```
 
 ---
 
-# Métodos base
+## Integração com NestJS
 
-Ao executar:
+O VSRepository pode ser facilmente integrado em projetos NestJS através de providers. Abaixo está um exemplo completo usando o padrão de injeção de dependência do NestJS.
+
+### Configurando o repository como provider
 
 ```ts
-.build(prisma)
+// src/repositories/user.repository.ts
+import { Provider } from "@nestjs/common";
+import { PrismaService } from "../../database/prisma.service";
+import { UserGetPayload } from "../../generated/prisma/models";
+import { RepositoryOf, setupVSRepo } from "../../generated/vsrepo";
+
+const userVSRepo = setupVSRepo<
+    UserGetPayload<{ include: { profile: true } }>,
+    "User"
+>()({
+    tableName: "user",
+    pkName: "id",
+    selectModels: {
+        public: {
+            id: true,
+            email: true,
+            createdAt: true,
+            updatedAt: true,
+        },
+        auth: {
+            id: true,
+            email: true,
+            password: true,
+        },
+    },
+    defaultSelectModel: "public",
+    requiredWhere: {
+        deletedAt: null,
+    },
+    relations: {
+        profile: {
+            mode: "oto",
+            pk: "id",
+            restriction: "add",
+        },
+    },
+    methods: {
+        findAuthByEmail: {
+            map: true,
+            proxyTo: "findUniqueByEmail",
+            selectModel: "auth",
+        },
+    },
+});
+
+export type UserRepository = RepositoryOf<typeof userVSRepo>;
+
+export const USER_REPOSITORY = Symbol("USER_REPOSITORY");
+
+export const UserRepositoryProvider: Provider = {
+    provide: USER_REPOSITORY,
+    inject: [PrismaService],
+    useFactory: (prisma: PrismaService) => {
+        return userVSRepo.build(prisma);
+    },
+};
 ```
 
-o VSRepo cria automaticamente:
+### Registrando o provider no módulo
 
-| Método       | Descrição               |
-| ------------ | ----------------------- |
-| `get(pk)`    | Busca pela primary key  |
-| `save(obj)`  | Cria ou atualiza        |
-| `remove(pk)` | Remove pela primary key |
+```ts
+// src/modules/user/user.module.ts
+import { Module } from "@nestjs/common";
+import { UserRepositoryProvider } from "../../repositories/user.repository";
+import { UserService } from "./user.service";
+import { UserController } from "./user.controller";
+
+@Module({
+    imports: [DatabaseModule],
+    providers: [UserRepositoryProvider, UserService],
+    controllers: [UserController],
+    exports: [UserService],
+})
+export class UserModule {}
+```
 
----
+### Utilizando o repository em um serviço
 
-# Configurando métodos base
+```ts
+// src/modules/user/user.service.ts
+import { Injectable, Inject } from "@nestjs/common";
+import { USER_REPOSITORY, UserRepository } from "../../repositories/user.repository";
+
+@Injectable()
+export class UserService {
+    constructor(
+        @Inject(USER_REPOSITORY)
+        private readonly userRepository: UserRepository,
+    ) {}
+
+    async getUserById(id: string) {
+        return this.userRepository.get(id);
+    }
+
+    async getUserAuthByEmail(email: string) {
+        return this.userRepository.findAuthByEmail(email);
+    }
+
+    async createUser(data: { email: string; password: string; name: string }) {
+        return this.userRepository.save({
+            email: data.email,
+            password: data.password,
+            name: data.name,
+        });
+    }
+}
+```
+
+### Usando em um controller
 
 ```ts
-const usuarioRepository = usuarioVSRepo.build(prisma, {
-  freeze: true,
+// src/modules/user/user.controller.ts
+import { Controller, Get, Post, Body, Param, Patch, Delete } from "@nestjs/common";
+import { UserService } from "./user.service";
+
+@Controller("users")
+export class UserController {
+    constructor(private readonly userService: UserService) {}
+
+    @Get(":id")
+    async getUser(@Param("id") id: string) {
+        return this.userService.getUserById(id);
+    }
+
+    @Post()
+    async createUser(
+        @Body() data: { email: string; password: string; name: string }
+    ) {
+        return this.userService.createUser(data);
+    }
+}
+```
+
+**Benefícios desta abordagem:**
+
+- ✅ Type-safe repositories com injeção de dependência
+- ✅ Fácil de testar (mock do `USER_REPOSITORY`)
+- ✅ Isolamento da lógica de persistência
+- ✅ Reutilização do repository em múltiplos serviços
+- ✅ Suporte a transações via `PrismaService`
+
+---
 
-  showWorking: false,
+## Métodos base
+
+Ao chamar `.build(prisma)`, três métodos são automaticamente disponibilizados:
+
+| Método       | Descrição                                  |
+| ------------ | ------------------------------------------ |
+| `get(pk)`    | Busca um registro pela primary key         |
+| `save(obj)`  | Cria ou atualiza (upsert pela primary key) |
+| `remove(pk)` | Remove um registro pela primary key        |
+
+Todos aceitam `options?: { selectModel?, db? }` como último argumento.
+
+### Configurando os métodos base
+
+```ts
+usuarioVSRepo.build(prisma, {
+  freeze: true,        // Congela o objeto (padrão: true)
+  showWorking: false,  // Exibe logs internos no console
 
   baseMethods: {
     get: {
       active: true,
       defaultSelect: "public",
     },
-
     remove: {
+      active: true,
       defaultSelect: "minimal",
     },
-
     save: {
       active: true,
+      ignoreRequiredWhere: true, // Não aplica requiredWhere no upsert
     },
   },
 });
@@ -250,135 +359,307 @@ const usuarioRepository = usuarioVSRepo.build(prisma, {
 
 ---
 
-# Select models
+## Select Models
 
-`selectModels` cria selects reutilizáveis.
+`selectModels` define projeções de dados nomeadas e reutilizáveis.
 
 ```ts
-const usuario = await usuarioRepository.get(id, {
-  selectModel: "minimal",
-});
+selectModels: {
+  public:   { id: true, nome: true, email: true },
+  internal: { id: true, nome: true, email: true, senha: true },
+  minimal:  { id: true },
+},
+defaultSelectModel: "public",
 ```
 
-Para retornar o payload padrão do Prisma:
+`defaultSelectModel` define qual select é usado automaticamente quando nenhum é especificado na chamada. É recomendado sempre definí-lo junto com `selectModels`.
+
+**Usando um select específico na chamada:**
 
 ```ts
-const usuarioCompleto = await usuarioRepository.get(id, {
-  selectModel: false,
-});
+const usuario = await usuarioRepository.get(id, { selectModel: "minimal" });
+```
+
+**Retornando o payload padrão do Prisma (sem select):**
+
+```ts
+const usuarioCompleto = await usuarioRepository.get(id, { selectModel: false });
 ```
 
 ---
 
-# Métodos dinâmicos
+## requiredWhere
 
-Métodos dinâmicos são definidos em:
+`requiredWhere` define filtros aplicados automaticamente em todas as queries do repository.
+
+```ts
+requiredWhere: { ativo: true },
+```
+
+Agora toda query incluirá `ativo: true` automaticamente:
+
+```ts
+// Internamente: WHERE ativo = true
+const usuarios = await usuarioRepository.findMany();
+
+// Internamente: WHERE email = 'joao@email.com' AND ativo = true
+const usuario = await usuarioRepository.findByEmail("joao@email.com");
+```
+
+Útil para soft-deletes, multi-tenancy e filtros globais de qualquer natureza.
+
+---
+
+## Métodos dinâmicos
+
+Métodos dinâmicos são definidos na propriedade `methods` e têm seus comportamentos inferidos a partir do nome.
 
 ```ts
 methods: {
+  findByEmail:           { map: true, fbMode: "one" },
+  findManyPaginated:     { map: true },
+  updateById:            { map: true },
+  deleteManyByIdIn:      { map: true, whereType: "overwrite" },
 }
 ```
 
+---
+
+### Prefixos disponíveis
+
+O prefixo do nome do método determina qual operação Prisma será chamada e quais argumentos serão esperados.
+
+| Prefixo                   | Operação Prisma          | Retorno                | Observações                                              |
+| ------------------------- | ------------------------ | ---------------------- | -------------------------------------------------------- |
+| `findBy`                  | `findMany` / `findFirst` | `T[]` ou `T \| null`   | Padrão é lista; use `fbMode: "one"` para retorno único   |
+| `findUniqueBy`            | `findUnique`             | `T \| null`            |                                                          |
+| `findFirstBy`             | `findFirst`              | `T \| null`            | Aceita campos como filtro                                |
+| `findFirst`               | `findFirst`              | `T \| null`            | Sem filtros de campo; aplica só `requiredWhere` e `pushWhere`          |
+| `findManyBy`              | `findMany`               | `T[]`                  | Aceita campos como filtro                                |
+| `findMany`                | `findMany`               | `T[]`                  | Sem filtros de campo; aplica só `requiredWhere` e `pushWhere`           |
+| `findWhere`               | `findFirst`              | `T \| null`            | Recebe um objeto `where` explícito como argumento        |
+| `findListWhere`           | `findMany`               | `T[]`                  | Recebe um objeto `where` explícito como argumento        |
+| `existsBy`                | `findFirst`              | `boolean`              | Retorna `true` se encontrar, `false` caso contrário      |
+| `countBy`                 | `count`                  | `number`               | Aceita campos como filtro                                |
+| `count`                   | `count`                  | `number`               | Sem filtros de campo; aplica só `requiredWhere` e `pushWhere`           |
+| `create`                  | `create`                 | `T`                    | Recebe `data` como argumento                             |
+| `createMany`              | `createMany`             | `{ count: number }`    | Recebe `data` como argumento; suporta `SkipDuplicates`                            |
+| `createManyAndReturn`     | `createManyAndReturn`    | `T[]`                  | Recebe `data` como argumento; suporta `SkipDuplicates`   |
+| `updateBy`                | `update`                 | `T`                    | Recebe `data` como argumento                             |
+| `updateManyBy`            | `updateMany`             | `{ count: number }`    | Recebe `data` como argumento                             |
+| `updateManyAndReturnBy`   | `updateManyAndReturn`    | `T[]`                  | Recebe `data` como argumento                             |
+| `upsertBy`                | `upsert`                 | `T`                    | Recebe `update` e `create` como argumentos               |
+| `deleteBy`                | `delete`                 | `T`                    |                                                          |
+| `deleteManyBy`            | `deleteMany`             | `{ count: number }`    |                                                          |
+
+---
+
+### Filtros de campo
+
+Os filtros são sufixos aplicados ao nome do campo dentro do método. O campo em si vem capitalizado logo após o prefixo (ou após `By`).
+
+| Sufixo             | Operador Prisma       | Argumento necessário |
+| ------------------ | --------------------- | -------------------- |
+| *(sem sufixo)*     | igualdade (`=`)       | sim                  |
+| `Not`              | `not`                 | sim                  |
+| `In`               | `in`                  | sim (array)          |
+| `NotIn`            | `notIn`               | sim (array)          |
+| `Contains`         | `contains`            | sim                  |
+| `NotContains`      | `not.contains`        | sim                  |
+| `StartsWith`       | `startsWith`          | sim                  |
+| `NotStartsWith`    | `not.startsWith`      | sim                  |
+| `EndsWith`         | `endsWith`            | sim                  |
+| `NotEndsWith`      | `not.endsWith`        | sim                  |
+| `GreaterThan`      | `gt`                  | sim                  |
+| `GreaterThanEqual` | `gte`                 | sim                  |
+| `LessThan`         | `lt`                  | sim                  |
+| `LessThanEqual`    | `lte`                 | sim                  |
+| `IsNull`           | `null`                | não (zero-arg)       |
+| `IsNotNull`        | `not: null`           | não (zero-arg)       |
+| `IsTrue`           | `true`                | não (zero-arg)       |
+| `IsFalse`          | `false`               | não (zero-arg)       |
+| `Insensitive`      | `mode: 'insensitive'` | combinador           |
+
+`Insensitive` é um combinador e pode ser usado junto com outro filtro de texto:
+
+```ts
+findByNomeContainsInsensitive    // { nome: { contains: valor, mode: 'insensitive' } }
+findByEmailStartsWithInsensitive // { email: { startsWith: valor, mode: 'insensitive' } }
+findByNomeInsensitive            // { nome: { equals: valor, mode: 'insensitive' } }
+```
+
+O sufixo `Optional` pode ser adicionado a qualquer campo para tornar o argumento opcional:
+
+```ts
+findByNomeOptionalAndEmail // nome é opcional, email é obrigatório
+```
+
+---
+
+### Operadores lógicos
+
+| Operador  | Uso no nome                  | Exemplo                          |
+| --------- | ---------------------------- | -------------------------------- |
+| `And`     | entre dois campos            | `findByIdAndEmail`               |
+| `Or`      | entre dois campos            | `findByNomeOrEmail`              |
+
 Exemplo:
 
 ```ts
 methods: {
-  findUniqueByIdAndEmail: { map: true },
+  findByIdAndEmail:   { map: true, fbMode: "one" },
+  findByNomeOrEmail:  { map: true },
+  findUniqueByIdOrEmailAndNome: { map: true }
+}
 
-  findByNomeContainsInsensitive: {
-    map: true,
-  },
+// Uso
+await usuarioRepository.findByIdAndEmail(1, "joao@email.com");
+await usuarioRepository.findByNomeOrEmail("Joao", "joao@email.com");
+await usuarioRepository.findUniqueByIdOrEmailAndNome(1, "joao@email.com", "Joao") // { OR: [ { id: 1 }, { email: "joao@email.com", nome: "Joao" } ] }
+```
 
-  findManyPaginated: {
-    map: true,
-  },
+---
 
-  findListWhereOrderedAndPaginated: {
-    map: true,
-    whereType: 'overwrite',
-  },
+### Filtros de relação
 
-  createManyAndReturn: {
-    map: true,
-  },
+Permitem filtrar por campos de modelos relacionados.
 
-  updateById: {
-    map: true,
-  },
+| Sufixo de relação      | Operador Prisma | Observação                                         |
+| ---------------------- | --------------- | -------------------------------------------------- |
+| `Some`                 | `some: {}`      | Relação tem *algum* registro                       |
+| `SomeField`            | `some.field`    | Filtra dentro dos registros da relação             |
+| `EveryField`           | `every.field`   | Filtra dentro dos registros da relação             |
+| `None`                 | `none: {}`      | Relação não tem *nenhum* registro                  |
+| `NoneField`            | `none.field`    | Filtra dentro dos registros da relação             |
+| `With`                 | `is: {}`        | Relação existe (não é null)                        |
+| `WithField`            | `is.field`      | Filtra campo dentro da relação                     |
+| `Without`              | `isNot: {}`     | Relação não existe (é null)                        |
+| `WithoutField`         | `isNot.field`   | Filtra campo dentro da relação com negação         |
 
-  deleteManyByIdIn: {
-    map: true,
-    whereType: 'overwrite',
-  },
+Exemplos:
 
-  existsByEmail: {
-    map: true,
-  },
-
-  countByPerfil: {
-    map: true,
-  },
+```ts
+methods: {
+  findByPostagensSomeTituloContains:  { map: true },   // postagens: { some: { titulo: { contains: valor } } }
+  findByPerfilWith:                   { map: true },   // perfil: { is: {} }
+  findByPerfilWithout:                { map: true },   // perfil: { isNot: {} }
+  findByPostagensSome:                { map: true },   // postagens: { some: {} }
+  findByPostagensEveryAtivoIsTrue:    { map: true },   // postagens: { every: { ativo: true } }
 }
 ```
 
 ---
 
-# Exemplos de uso
+### Sufixos de paginação e ordenação
 
-```ts
-const usuario = await usuarioRepository.findUniqueByIdAndEmail(id, email);
+Aplicados ao **final** do nome do método (após os filtros de campo), eles injetam automaticamente os argumentos de paginação e ordenação.
 
-const usuarios = await usuarioRepository.findByNomeContainsInsensitive("joao");
+| Sufixo                | Argumentos adicionais         |
+| --------------------- | ----------------------------- |
+| `Paginated`           | `(pagination)`                |
+| `Ordered`             | `(order)`                     |
+| `OrderedAndPaginated` | `(order, pagination)`         |
+| `PaginatedAndOrdered` | `(pagination, order)`         |
 
-const pagina = await usuarioRepository.findManyPaginated({
-  take: 10,
-  skip: 0,
-});
+Para `createMany` e `createManyAndReturn`, o sufixo `SkipDuplicates` está disponível:
 
-const ordenado = await usuarioRepository.findListWhereOrderedAndPaginated(
-  {
-    nome: {
-      startsWith: "A",
-    },
-  },
+| Sufixo            | Efeito                                   |
+| ----------------- | ---------------------------------------- |
+| `SkipDuplicates`  | Ignora registros duplicados na inserção  |
 
-  {
-    dataCriacao: "desc",
-  },
+Exemplos completos:
 
-  {
-    take: 10,
-  },
+```ts
+methods: {
+  findManyPaginated:                    { map: true },
+  findManyByAtivoOrderedAndPaginated:   { map: true },
+  findByEmailOrderedAndPaginated:       { map: true },
+  createManyAndReturnSkipDuplicates:    { map: true },
+}
+
+// Uso
+await usuarioRepository.findManyPaginated({ skip: 0, take: 10 });
+
+await usuarioRepository.findManyByAtivoOrderedAndPaginated(
+  true,
+  { dataCriacao: "desc" },
+  { skip: 0, take: 10 }
 );
 ```
 
+`PaginationOptions`:
+
+```ts
+type PaginationOptions<TCursor = unknown> = {
+  skip?: number;
+  take?: number;
+  cursor?: TCursor;
+};
+```
+
+`OrderOptions`:
+
+```ts
+type OrderOptions = OrderPattern | OrderPattern[];
+// Exemplo: { dataCriacao: "desc" } ou [{ dataCriacao: "desc" }, { nome: "asc" }]
+```
+
 ---
 
-# Filtros suportados
-
-| Padrão             | Exemplo                             |
-| ------------------ | ----------------------------------- |
-| `And` / `Or`       | `findByIdAndEmail`                  |
-| `In` / `NotIn`     | `deleteManyByIdIn`                  |
-| `Contains`         | `findByNomeContains`                |
-| `StartsWith`       | `findByNomeStartsWith`              |
-| `EndsWith`         | `findByEmailEndsWith`               |
-| `Insensitive`      | `findByNomeContainsInsensitive`     |
-| `GreaterThan`      | `findByIdadeGreaterThan`            |
-| `LessThanEqual`    | `findByIdadeLessThanEqual`          |
-| `IsNull`           | `findByPerfilIsNull`                |
-| `IsTrue`           | `findByAtivoIsTrue`                 |
-| `Some`             | `findByPostagensSomeTituloContains` |
-| `With` / `Without` | `findByPerfilWith`                  |
+### Configuração de métodos
+
+Cada entrada em `methods` aceita as seguintes opções:
+
+| Opção               | Tipo                            | Padrão       | Descrição                                                                                                    |
+| ------------------- | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
+| `map`               | `boolean`                       | —            | **Obrigatório.** Define se o método será exposto no repository.                                             |
+| `whereType`         | `'extending'` \| `'overwrite'`  | `extending`  | `extending` combina com `requiredWhere`. `overwrite` ignora o `requiredWhere`.                      |
+| `selectModel`       | `keyof SelectModels \| false`   | —            | Sobrescreve o `defaultSelectModel` para este método.                                                        |
+| `fbMode`            | `'one'` \| `'list'`             | `'list'`     | Somente para `findBy`. `'one'` retorna `T \| null`; `'list'` retorna `T[]`.                                 |
+| `proxyTo`           | `Padrão de método válido`           | —            | Delega a lógica para outro padrão de método válido. Útil para methods com nomes personalizados.       |
+| `pushWhere`         | `WhereModel<M>`                 | —            | Where extra adicionado à query além do `requiredWhere`.                                                     |
+| `injectOrdenation`  | `OrdenationModel<M>`            | —            | Ordenação fixa injetada automaticamente na query.                                                           |
+| `injectPagination`  | `PaginationModel<M>`            | —            | Paginação fixa injetada automaticamente na query.                                                           |
+
+Exemplos:
+
+```ts
+methods: {
+  // Retorna um único resultado em vez de array
+  findByEmail: { map: true, fbMode: "one" },
+
+  // Ignora o requiredWhere
+  deleteManyByIdIn: { map: true, whereType: "overwrite" },
+
+  // Usa um select model específico neste método
+  findManyByAtivo: { map: true, selectModel: "minimal" },
+
+  // Adiciona um where extra além do requiredWhere
+  findManyByPerfil: { map: true, pushWhere: { deletedAt: null } },
+
+  // Ordenação fixa sem precisar passar como argumento
+  findManyPaginado: { map: true, injectOrdenation: { dataCriacao: "desc" } },
+
+  // Nome personalizado precisa de proxyTo
+  buscarPorEmailEPerfil: { map: true, proxyTo: "findByEmailAndPerfil" },
+}
+```
 
 ---
 
-# Relações no save
+## Relações no save
+
+Configure relações para que o `save` as gerencie automaticamente. Para que as relações apareçam no autocomplete, o tipo genérico deve incluir as relações usando `GetPayload`:
 
 ```ts
-const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
-  tableName: "usuario",
+import type { Prisma } from "../generated/prisma/client";
+
+type Usuario = Prisma.usuarioGetPayload<{
+  include: { perfil: true; postagens: true };
+}>;
 
+const usuarioRepository = setupVSRepo<Usuario, "usuario">()({
+  tableName: "usuario",
   pkName: "id",
 
   relations: {
@@ -387,17 +668,18 @@ const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
       mode: "oto",
       restriction: "set",
     },
-
     postagens: {
       pk: "id",
       mode: "otm",
       restriction: "set",
     },
   },
-});
+}).build(prisma);
 ```
 
-## Modos disponíveis
+> **Dica:** Se o tipo genérico não incluir `include: { relação: true }`, o VSRepository ainda funcionará, mas o autocomplete não sugerirá as relações no `save`. O tipo recomendado é sempre `GetPayload<{ include: { /* suas relações */ } }>` para melhor experiência de desenvolvimento.
+
+**Modos de relação:**
 
 | Modo  | Relação      |
 | ----- | ------------ |
@@ -406,103 +688,296 @@ const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
 | `mto` | many-to-one  |
 | `mtm` | many-to-many |
 
----
+**Restrições:**
 
-# Transações
+| Restrição | Comportamento no update                                     |
+| --------- | ----------------------------------------------------------- |
+| `set`     | Substitui completamente (remove os que não foram enviados)  |
+| `add`     | Adiciona/atualiza sem remover os existentes                 |
 
-Todos os métodos aceitam:
+---
 
-```ts
-options.db;
-```
+## Transações
 
-Exemplo:
+Todos os métodos aceitam `options.db` para participar de uma transação:
 
 ```ts
 await prisma.$transaction(async (tx) => {
   const usuario = await usuarioRepository.save(
-    {
-      nome: "Maria",
-      email: "maria@email.com",
-      senha: "password",
-    },
-
-    {
-      db: tx,
-    },
+    { nome: "Maria", email: "maria@email.com", senha: "password" },
+    { db: tx }
   );
 
   await usuarioRepository.updateById(
     usuario.id,
-
-    {
-      ativo: true,
-    },
-
-    {
-      db: tx,
-    },
+    { ativo: true },
+    { db: tx }
   );
 });
 ```
 
 ---
 
-# Extendendo um repository
+## Extendendo um repository
 
 ```ts
-const repository = usuarioVSRepo
+const usuarioRepository = setupVSRepo<Usuario, "usuario">()({
+  tableName: "usuario",
+  pkName: "id",
+  methods: {
+    findByEmailEndsWith: { map: true, fbMode: "one" },
+  },
+})
   .build(prisma)
-
   .extend((repo) => ({
-    async buscarAtivosPorDominio(dominio: string) {
+    buscarAtivosPorDominio: async (dominio: string) => {
       return repo.findByEmailEndsWith(`@${dominio}`);
     },
+
+    ativarMultiplos: async (ids: string[]) => {
+      return repo.updateManyByIdIn(ids, { ativo: true });
+    },
   }));
 ```
 
 ---
 
-# Estrutura recomendada
+## Tratamento de erros
+
+O VSRepository lança `VSRepoError` e suas subclasses em situações específicas (OBS: Erros do Prisma não são sobrescritos como `VSRepoError`):
+
+```ts
+import { VSRepoError } from "../generated/vsrepo";
 
-```txt
-src/
-├── db.ts
-├── generated/
-│   ├── prisma/
-│   └── vsrepo/
-├── repositories/
-└── services/
+try {
+  const usuario = await usuarioRepository.get();
+} catch (error) {
+  if (error instanceof VSRepoError) {
+    console.error("Erro no repository:", error.message);
+  }
+}
 ```
 
+**Subclasses disponíveis:**
+
+| Classe               | Quando é lançada                                        |
+| -------------------- | ------------------------------------------------------- |
+| `VSRepoConfigError`  | Configuração inválida em `setupVSRepo` ou `build`       |
+| `VSRepoBuildError`   | Nome de método inválido ou desconhecido no `build`      |
+| `VSRepoExtendError`  | Argumento inválido em `extend`                          |
+| `VSRepoRuntimeError` | Erro em tempo de execução durante uma operação          |
+
 ---
 
-# Scripts úteis
+## Tipos utilitários
 
-```bash
-pnpm prisma generate
+O VSRepository exporta os seguintes tipos para uso nas suas aplicações:
 
-pnpm vsrepo generate \
-  --output src/generated/vsrepo \
-  --prisma src/generated/prisma/client
+### Tipos de cliente
+
+```ts
+import type { DbClient, DbTransaction, ClientOrTransaction } from "../generated/vsrepo";
+
+type DbClient           = PrismaClient;
+type DbTransaction      = Prisma.TransactionClient;
+type ClientOrTransaction = DbClient | DbTransaction;
+```
+
+### Tipos derivados do modelo Prisma
+
+```ts
+import type {
+  SelectModel,
+  SelectModels,
+  WhereModel,
+  OrdenationModel,
+  PaginationModel,
+  ModelUpsertInput,
+} from "../generated/vsrepo";
+
+// Select de um campo específico
+type UsuarioSelect = SelectModel<"usuario">;
+
+// Mapa de selects nomeados
+type UsuarioSelectModels = SelectModels<"usuario">;
+
+// Where clause do modelo
+type UsuarioWhere = WhereModel<"usuario">;
+
+// OrderBy do modelo
+type UsuarioOrder = OrdenationModel<"usuario">;
+
+// Opções de paginação com cursor tipado
+type UsuarioPagination = PaginationModel<"usuario">;
+
+// Payload de criação do modelo (para upsert)
+type UsuarioUpsertInput = ModelUpsertInput<"usuario">;
+```
+
+### Todos os inputs do modelo
+
+```ts
+import type { PrismaModelInputs } from "../generated/vsrepo";
+
+type UsuarioInputs = PrismaModelInputs<"usuario">;
+// Contém:
+//   select, createInput, createManyInput, updateInput, updateManyInput,
+//   whereInput, orderByInput, cursorInput, upsertCreateInput, upsertUpdateInput
+```
+
+### Tipos de opções de método
+
+```ts
+import type { MethodOptions, MethodOptionsModel } from "../generated/vsrepo";
+
+// MethodOptions<S> — opções passadas nos métodos do repository
+// S = chave do select model ou false
+type Opts = MethodOptions<"public" | "minimal">;
+
+// MethodOptionsModel<T> — versão derivada do tipo do repository
+type OptsModel = MethodOptionsModel<typeof usuarioSelectModels>;
+```
+
+### Tipos de configuração
+
+```ts
+import type {
+  MethodConfig,
+  RepoConfig,
+  BuildConfig,
+  RepositoryRelations,
+  ExtractRelationConfig,
+  UpsertWithRelations,
+} from "../generated/vsrepo";
+
+// Configuração de um método dinâmico
+type MeuMethodConfig = MethodConfig<"usuario", typeof meuSelectModels>;
+
+// Configuração completa do repository
+type MeuRepoConfig = RepoConfig<Usuario, "usuario">;
+
+// Configuração do build
+type MeuBuildConfig = BuildConfig<"public" | "minimal">;
+
+// Tipo de relações inferidas automaticamente
+type UsuarioRelations = RepositoryRelations<Usuario>;
+
+// Configuração de relação inferida a partir de um campo
+type PerfilRelationConfig = ExtractRelationConfig<Usuario["perfil"]>;
+
+// Payload do save com relações
+type UsuarioComRelacoes = UpsertWithRelations<Usuario, "usuario", typeof relations>;
+```
+
+### Tipo do repository construído
+
+```ts
+import type { BuiltRepository, RepositoryOf } from "../generated/vsrepo";
+
+// Tipo completo de um repository construído
+type MeuRepo = BuiltRepository<Usuario, "usuario", typeof config, typeof buildConfig>;
+
+// Inferência a partir de uma instância VSRepository (útil para injeção de dependência)
+const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({ ... });
+type UsuarioRepository = RepositoryOf<typeof usuarioVSRepo>;
+```
+
+`RepositoryOf` aceita três parâmetros:
+
+```ts
+type RepositoryOf<TRepo, C extends BuildConfig | undefined = undefined, E = unknown>
+//                        ^ BuildConfig (opcional)                       ^ tipo do extend (opcional)
+```
+
+Exemplo com extend tipado:
+
+```ts
+const extension = { buscarPorDominio: (dominio: string) => Promise<Usuario[]> };
+type UsuarioRepositoryExtended = RepositoryOf<typeof usuarioVSRepo, undefined, typeof extension>;
+```
+
+### Tipo auxiliar
+
+```ts
+import type { DistributiveOmit } from "../generated/vsrepo";
+
+// Omit distributivo — preserva unions ao omitir propriedades
+type SemEmail = DistributiveOmit<Usuario | Perfil, "email">;
 ```
 
 ---
 
-# Requisitos
+## API Reference
 
-- TypeScript
+### `setupVSRepo<T, M>()(config)`
+
+```ts
+setupVSRepo<TPayload, TTableName>()({
+  tableName: Uncapitalize<M>;         // Nome da tabela no Prisma
+  pkName: keyof T;                    // Nome da primary key
+  selectModels?: SelectModels<M>;     // Projeções de dados nomeadas
+  defaultSelectModel?: keyof SM;      // Select aplicado por padrão
+  requiredWhere?: WhereModel<M>;      // Filtros sempre aplicados
+  relations?: RepositoryRelations<T>; // Configuração de relações
+  methods?: Record<string, MethodConfig<M, SM>>; // Métodos dinâmicos
+});
+```
+
+### `.build(prisma, config?)`
+
+```ts
+vsRepo.build(prisma, {
+  freeze?: boolean;        // Congela o objeto (padrão: true)
+  showWorking?: boolean;   // Exibe logs internos no console
+
+  baseMethods?: {
+    get?:    { active?: boolean; defaultSelect?: string };
+    remove?: { active?: boolean; defaultSelect?: string };
+    save?:   { active?: boolean; ignoreRequiredWhere?: boolean };
+  };
+});
+```
+
+### `.extend(fn)`
+
+```ts
+repo.extend((repo) => ({
+  meuMetodo() { ... }
+}));
+```
+
+---
+
+## Requisitos
+
+- Node.js 16+ (ESM)
 - Prisma
-- Node.js ESM
-- `"moduleResolution": "bundler"` ou `"nodenext"`
+- TypeScript (opcional, mas fortemente recomendado)
+- `"moduleResolution": "bundler"` ou `"nodenext"` no tsconfig
 
-Exemplo:
+`tsconfig.json` recomendado:
 
 ```json
 {
   "compilerOptions": {
+    "target": "ES2020",
     "module": "NodeNext",
-    "moduleResolution": "NodeNext"
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ES2020"]
   }
 }
 ```
+
+---
+
+## Troubleshooting
+
+**Tipos genéricos não inferidos** — Verifique se `strict: true` e `moduleResolution: "bundler"` ou `"nodenext"` estão no `tsconfig.json`.
+
+**Método dinâmico não existe em runtime** — O campo referenciado no nome do método deve existir no modelo Prisma. Ex.: `findByEmail` exige que o modelo tenha um campo `email`.
+
+**`proxyTo` obrigatório** — Nomes fora dos moldes (ex.: `buscarPorEmail`) não são parseados diretamente. Use `proxyTo: "findByEmail"` nesses casos.
+
+**Select model retorna campos inesperados** — Verifique se o select model define exatamente os campos que o seu tipo TypeScript espera. Campos com `false` não serão retornados pelo Prisma.