vsrepo 1.0.3 → 1.0.5

package/README.md

@@ -1,68 +1,142 @@
-# VSRepo
-
-Biblioteca de repository para projetos que usam Prisma. Ela permite criar repositories tipados com métodos base (`get`, `save` e `remove`) e métodos dinâmicos mapeados pelo nome, como `findByEmail`, `findManyPaginated`, `updateById` e `deleteManyByIdIn`.
+# VSRepository
+
+![npm](https://img.shields.io/npm/v/vsrepo?style=flat-square)
+![license](https://img.shields.io/github/license/jaobrabo123/vsrepository?style=flat-square)
+
+Biblioteca de repository pattern para projetos que usam **Prisma**, com suporte completo a **TypeScript** e **type inference** automático.
+
+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
+
+---
+
+## 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)
+
+---
 
 ## Instalação
 
 ```bash
-pnpm add vsrepo @prisma/client
+npm i vsrepo @prisma/client
 ```
 
-O Prisma Client deve estar configurado no projeto:
+Gere o Prisma Client:
 
 ```bash
-pnpm prisma generate
+npx prisma generate
+```
+
+---
+
+## Gerando os tipos
+
+O VSRepository precisa conhecer o caminho real do seu Prisma Client para gerar as tipagens corretamente.
+
+```bash
+npx vsrepo generate
+```
+
+Equivale a:
+
+```bash
+npx vsrepo generate \
+  --output src/generated/vsrepo \
+  --prisma src/generated/prisma
+```
+
+**Flags disponíveis:**
+
+| Flag       | Alias | Padrão                 |
+| ---------- | ----- | ---------------------- |
+| `--output` | `-o`  | `src/generated/vsrepo` |
+| `--prisma` | `-p`  | `src/generated/prisma` |
+
+**Arquivos gerados:**
+
+```
+src/generated/vsrepo/
+├── VSRepoError.ts
+├── VSRepoError.types.d.ts
+├── VSRepository.ts
+├── VSRepository.types.d.ts
+└── index.ts
 ```
 
+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";
+```
+
+---
+
 ## Uso básico
 
-Crie uma instância do 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;
 ```
 
-Depois crie o repository do modelo:
+### Criando um repository
 
 ```ts
 // src/repositories/usuarioRepository.ts
-import prisma from "../db";
-import { setupVSRepo, type SelectModels, type WhereModel } from "vsrepo";
-import type { Prisma } from "@prisma/client";
+import prisma from "../configs/db";
+import { setupVSRepo } from "../generated/vsrepo";
+import type { Usuario } from "../generated/prisma/client";
 
-type Usuario = Prisma.usuarioGetPayload<{
-  include: {
-    perfil: true;
-    postagens: true;
-  };
-}>;
+const usuarioRepository = setupVSRepo<Usuario, "usuario">()({
+  tableName: "usuario",
+  pkName: "id",
 
-const usuarioSelectModels = {
-  public: {
-    id: true,
-    nome: true,
-    email: true,
-  },
-  minimal: {
-    id: true,
+  selectModels: {
+    public: { id: true, nome: true, email: true },
+    minimal: { id: true },
   },
-} satisfies SelectModels<"usuario">;
+  defaultSelectModel: "public",
 
-const usuarioRequiredWhere = {
-  ativo: true,
-} satisfies WhereModel<"usuario">;
+  requiredWhere: { ativo: true },
 
-const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
-  tableName: "usuario",
-  pkName: "id",
-  selectModels: usuarioSelectModels,
-  defaultSelectModel: "public",
-  requiredWhere: usuarioRequiredWhere,
   methods: {
     findByEmail: { map: true, fbMode: "one" },
     findManyPaginated: { map: true },
@@ -70,14 +144,14 @@ const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
     deleteManyByIdIn: { map: true, whereType: "overwrite" },
     count: { map: true },
   },
-});
-
-const usuarioRepository = usuarioVSRepo.build(prisma);
+}).build(prisma);
 
 export default usuarioRepository;
 ```
 
-Use o repository na aplicação:
+> `selectModels` e `requiredWhere` podem ser declarados fora do `setupVSRepo` se você precisar exportá-los para uso em outros arquivos.
+
+### Usando o repository
 
 ```ts
 import usuarioRepository from "./repositories/usuarioRepository";
@@ -88,128 +162,506 @@ 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);
+```
+
+---
+
+## Integração com NestJS
+
+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
+// 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",
+        },
+    },
 });
 
-await usuarioRepository.remove(usuario.id);
+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);
+    },
+};
+```
+
+### Registrando o provider no módulo
+
+```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
+
+```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
+// 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`
+
+---
+
 ## Métodos base
 
-Ao chamar `build(prisma)`, o VSRepo cria três métodos por padrão:
+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        |
 
-| Método | Descrição |
-| --- | --- |
-| `get(pk, options?)` | Busca um registro pela primary key definida em `pkName`. |
-| `save(obj, options?)` | Cria ou atualiza um registro. Se `obj` tiver a primary key, usa `upsert`; se não tiver, usa `create`. |
-| `remove(pk, options?)` | Remove um registro pela primary key. |
+Todos aceitam `options?: { selectModel?, db? }` como último argumento.
 
-Você pode configurar esses métodos no `build`:
+### Configurando os métodos base
 
 ```ts
-const usuarioRepository = usuarioVSRepo.build(prisma, {
-  freeze: true,
-  showWorking: false,
+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
     },
   },
 });
 ```
 
-## Select models
+---
 
-`selectModels` define selects reutilizáveis do Prisma. O `defaultSelectModel` é aplicado quando o método não recebe outro select.
+## Select Models
+
+`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",
+```
 
-const usuarioCompleto = await usuarioRepository.get(id, {
-  selectModel: false,
-});
+`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 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 });
+```
+
+---
+
+## requiredWhere
+
+`requiredWhere` define filtros aplicados automaticamente em todas as queries do repository.
+
+```ts
+requiredWhere: { ativo: true },
 ```
 
-Use `selectModel: false` para não aplicar nenhum select model e deixar o Prisma retornar o payload padrão.
+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 declarados em `methods` com `map: true`. O nome do método informa qual operação do Prisma será usada e quais campos entram no `where`.
+Métodos dinâmicos são definidos na propriedade `methods` e têm seus comportamentos inferidos a partir do nome.
 
-Exemplos:
+```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 },
-  findByNomeContainsInsensitive: { map: true },
-  findManyPaginated: { map: true },
-  findListWhereOrderedAndPaginated: { map: true, whereType: "overwrite" },
-  createManyAndReturn: { map: true },
-  updateById: { map: true },
-  deleteManyByIdIn: { map: true, whereType: "overwrite" },
-  existsByEmail: { map: true },
-  countByPerfil: { map: true },
+  findByIdAndEmail:   { map: true, fbMode: "one" },
+  findByNomeOrEmail:  { map: true },
+  findUniqueByIdOrEmailAndNome: { 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" } ] }
 ```
 
-Uso:
+---
+
+### Filtros de relação
+
+Permitem filtrar por campos de modelos relacionados.
+
+| 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         |
+
+Exemplos:
 
 ```ts
-const usuario = await usuarioRepository.findUniqueByIdAndEmail(id, email);
+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 } }
+}
+```
 
-const usuarios = await usuarioRepository.findByNomeContainsInsensitive("joao");
+---
 
-const pagina = await usuarioRepository.findManyPaginated({
-  take: 10,
-  skip: 0,
-});
+### Sufixos de paginação e ordenação
+
+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.
+
+| Sufixo                | Argumentos adicionais         |
+| --------------------- | ----------------------------- |
+| `Paginated`           | `(pagination)`                |
+| `Ordered`             | `(order)`                     |
+| `OrderedAndPaginated` | `(order, pagination)`         |
+| `PaginatedAndOrdered` | `(pagination, order)`         |
+
+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  |
+
+Exemplos completos:
+
+```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" },
-  { take: 10 }
+  { skip: 0, take: 10 }
 );
 ```
 
-## Filtros pelo nome do método
+`PaginationOptions`:
 
-O VSRepo interpreta sufixos no nome dos métodos para montar o `where`:
+```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" }]
+```
+
+---
+
+### 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`           | `ValidMethodPatterns`           | —            | 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" },
 
-| Padrão | Exemplo |
-| --- | --- |
-| `And` / `Or` | `findByIdAndEmail`, `findByNomeOrEmail` |
-| `In` / `NotIn` | `deleteManyByIdIn` |
-| `Contains` / `StartsWith` / `EndsWith` | `findByNomeContains` |
-| `Insensitive` | `findByNomeContainsInsensitive` |
-| `GreaterThan` / `GreaterThanEqual` | `findByIdadeGreaterThan` |
-| `LessThan` / `LessThanEqual` | `findByIdadeLessThanEqual` |
-| `IsNull` / `IsNotNull` | `findByPerfilIsNotNull` |
-| `IsTrue` / `IsFalse` | `findByAtivoIsTrue` |
-| `Some` / `Every` / `None` | `findByPostagensSomeTituloContains` |
-| `With` / `Without` | `findByPerfilWith`, `findByPerfilWithout` |
+  // Adiciona um where extra além do requiredWhere
+  findManyByPerfil: { map: true, pushWhere: { deletedAt: null } },
 
-## Relações no `save`
+  // Ordenação fixa sem precisar passar como argumento
+  findManyPaginado: { map: true, injectOrdenation: { dataCriacao: "desc" } },
 
-Configure `relations` para que `save` consiga criar, conectar, atualizar ou remover relações junto com o registro principal.
+  // Nome personalizado precisa de proxyTo
+  buscarPorEmailEPerfil: { map: true, proxyTo: "findByEmailAndPerfil" },
+}
+```
+
+---
+
+## 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">()({
+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: {
     perfil: {
       pk: "id",
@@ -222,32 +674,37 @@ const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
       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.
 
-| Modo | Relação |
-| --- | --- |
-| `oto` | one-to-one |
-| `otm` | one-to-many |
-| `mto` | many-to-one |
+**Modos de relação:**
+
+| Modo  | Relação      |
+| ----- | ------------ |
+| `oto` | one-to-one   |
+| `otm` | one-to-many  |
+| `mto` | many-to-one  |
 | `mtm` | many-to-many |
 
-`restriction: "set"` substitui o conjunto atual quando aplicável. `restriction: "add"` adiciona/conecta sem limpar os registros já relacionados.
+**Restrições:**
+
+| Restrição | Comportamento no update                                     |
+| --------- | ----------------------------------------------------------- |
+| `set`     | Substitui completamente (remove os que não foram enviados)  |
+| `add`     | Adiciona/atualiza sem remover os existentes                 |
+
+---
 
 ## Transações
 
-Todos os métodos aceitam `options.db`. Use isso para executar operações dentro de uma transação do Prisma:
+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",
-    },
+    { nome: "Maria", email: "maria@email.com", senha: "password" },
     { db: tx }
   );
 
@@ -259,23 +716,268 @@ await prisma.$transaction(async (tx) => {
 });
 ```
 
-## Estendendo um repository
+---
 
-Use `extend` para adicionar métodos manuais mantendo os métodos gerados:
+## 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 });
+    },
   }));
 ```
 
-## Scripts do projeto
+---
 
-```bash
-pnpm test:usuario
-pnpm test:base-methods:user
+## 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";
+
+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          |
+
+---
+
+## Tipos utilitários
+
+O VSRepository exporta os seguintes tipos para uso nas suas aplicações:
+
+### 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">;
+```
+
+---
+
+## API Reference
+
+### `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
+- TypeScript (opcional, mas fortemente recomendado)
+- `"moduleResolution": "bundler"` ou `"nodenext"` no tsconfig
+
+`tsconfig.json` recomendado:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "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.