vsrepo 1.3.0 → 1.3.1

package/README.md

@@ -1,7 +1,7 @@
 # VSRepository
 
 ![npm](https://img.shields.io/npm/v/vsrepo?style=flat-square)
-![NPM License](https://img.shields.io/npm/l/vsrepo)
+![NPM License](https://img.shields.io/npm/l/vsrepo?style=flat-square)
 ![NPM Downloads](https://img.shields.io/npm/dt/vsrepo?style=flat-square)
 
 Biblioteca de repository pattern para projetos que usam **Prisma**, com suporte completo a **TypeScript** e **type inference** automático.
@@ -10,12 +10,14 @@ O VSRepository permite criar repositories fortemente tipados com:
 
 - **Métodos base** automáticos: `get`, `getOrThrow`, `getList`, `save`, `saveList`, `remove`, `removeList`, `patch`, `patchList`, `merge`, `getAll`, `total`, `has`
 - **Soft-delete nativo**: `softRemove`, `softRemoveList`, `restore`, `restoreList`
-- **Métodos dinâmicos** inferidos pelo nome: `findByEmail`, `findManyPaginated`, `updateById`, `deleteManyByIdIn`
+- **Métodos dinâmicos** inferidos pelo nome: `findOneByEmail`, `findManyPaginated`, `updateById`, `deleteManyByNameStartsWith`
 - **Select models** reutilizáveis para diferentes projeções de dados
 - **Type safety** em 100% das operações
 - **Transações** nativas do Prisma (automáticas em `saveList` e `patchList`)
 - **Extensibilidade** com métodos personalizados
 
+> 💡 Quer ver tudo isso funcionando na prática? A pasta [`examples/`](https://github.com/jaobrabo123/VSRepository/tree/main/examples) do repositório tem exemplos comentados e executáveis para cada funcionalidade — veja a seção [Exemplos práticos](#exemplos-práticos) abaixo.
+
 ---
 
 ## Sumário
@@ -48,6 +50,7 @@ O VSRepository permite criar repositories fortemente tipados com:
 - [Tratamento de erros](#tratamento-de-erros)
 - [Tipos utilitários](#tipos-utilitários)
 - [API Reference](#api-reference)
+- [Exemplos práticos](#exemplos-práticos)
 - [Contribuindo](#contribuindo)
 - [Requisitos](#requisitos)
 - [Troubleshooting](#troubleshooting)
@@ -138,21 +141,18 @@ import prisma from "../configs/db";
 import { setupVSRepo } from "../../generated/vsrepo";
 import type { Usuario } from "../../generated/prisma/client";
 
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
+const usuarioRepository = setupVSRepo<Usuario, "Usuario">()(({
   tableName: "usuario",
   pkName: "id",
   selectModels: {
     public: { id: true, nome: true, email: true },
   },
   defaultSelectModel: "public",
-  requiredWhere: { ativo: true },
 }).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
 
 ```ts
@@ -231,14 +231,18 @@ const userVSRepo = setupVSRepo<
 });
 
 const setupUserRepository = (prisma: PrismaService) => {
-    return userVSRepo.build(prisma).extend((repo) => ({
-        buscarPorDominio: async (dominio: string) => {
-            return repo.findByEmailEndsWith(`@${dominio}`);
-        },
-    }));
+    return userVSRepo.build(prisma);
 };
 
 export type UserRepository = ReturnType<typeof setupUserRepository>;
+/* 
+A tipagem também pode ser inferida usando o `RepositoryOf` do VSRepository, passando o tipo do `userVSRepo`:
+
+export type UserRepository = RepositoryOf<typeof userVSRepo>;
+
+OBS: Caso você use o `.extend` para estender o repository ou configure os métodos base, recomenda-se 
+usar o `ReturnType` por ser mais simples de inferir a tipagem
+*/
 
 export const USER_REPOSITORY = Symbol("USER_REPOSITORY");
 
@@ -363,7 +367,7 @@ await usuarioRepository.restore(1);
 // saveList — cria ou atualiza múltiplos objetos em transação automática
 const usuarios = await usuarioRepository.saveList([
   { nome: "Maria", email: "maria@email.com" },
-  { id: 2, nome: "João Atualizado" },
+  { id: 2, nome: "João Atualizado", email: "joao@email.com" },
 ]);
 
 // patchList — atualiza parcialmente múltiplos registros via tuplas [pk, obj]
@@ -401,32 +405,80 @@ await usuarioRepository.save(mesclado);
 
 Retorna `null` se o registro não for encontrado.
 
+**Merge de relações to-many (`otm`/`mtm`) é feito por PK, não por concatenação simples.** Para relações to-one (`oto`/`mto`), o `merge` faz um deepmerge comum do objeto. Já para relações to-many, cada item do array enviado é casado com o item existente que tem a mesma PK (definida em `relations[chave].pk`): se a PK bate, os dois objetos são mesclados entre si; se não bate (item novo, sem correspondente), ele é apenas adicionado à lista. Itens existentes que não aparecem no array enviado são mantidos.
+
+```ts
+const existente = await usuarioRepository.get(1);
+// existente: {
+//   id: 1,
+//   postagens: [
+//     { id: 10, titulo: "Post A", publicada: false },
+//     { id: 11, titulo: "Post B", publicada: true },
+//   ],
+// }
+
+const mesclado = await usuarioRepository.merge(1, {
+  postagens: [
+    { id: 10, publicada: true },  // mesma PK (id: 10) → mescla com o item existente
+    { titulo: "Post C" },         // sem PK → é adicionado como um novo item
+  ],
+});
+// mesclado: {
+//   id: 1,
+//   postagens: [
+//     { id: 10, titulo: "Post A", publicada: true },  // mesclado
+//     { id: 11, titulo: "Post B", publicada: true },  // mantido, não veio no array enviado
+//     { titulo: "Post C" },                           // adicionado
+//   ],
+// }
+```
+
+> Note que o `merge` nunca remove itens de uma relação to-many — ele só mescla os que casam por PK e adiciona os que não casam. Para remover itens de uma relação, use `save`/`patch` com `restriction: "set"` na configuração da relação.
+
 ### Configurando os métodos base
 
+O segundo argumento de `.build(prisma, config)` permite ajustar o comportamento global do repository e customizar cada método base individualmente através de `baseMethods`.
+
 ```ts
 usuarioVSRepo.build(prisma, {
-  showWorking: true,  // Exibe logs do VSRepository no console, ótimo para debugar
+  // Exibe logs internos do VSRepository no console (queries montadas, prefixo detectado,
+  // filtros aplicados etc). Ótimo para debugar métodos dinâmicos. Padrão = false.
+  showWorking: true,
 
   baseMethods: {
     get: {
+      // Habilita/desabilita o método no repository final. Se `false`, o método
+      // sequer aparece no tipo do repository (não é só um erro em runtime). Padrão = true.
       active: true,
+
+      // Select model aplicado por padrão quando o método é chamado sem `options.selectModel`.
+      // Sobrescreve o `defaultSelectModel` do setupVSRepo apenas para este método.
       defaultSelect: "public",
     },
     remove: {
       active: true,
       defaultSelect: "minimal",
+
+      // Quando `true`, ignora o `requiredWhere` configurado no setupVSRepo para
+      // este método específico — útil quando um método precisa "furar" um filtro
+      // global (ex.: multi-tenancy) em um caso pontual. Padrão = false.
       ignoreRequiredWhere: false,
     },
     save: {
+      // Aqui só `ignoreRequiredWhere` é definido — `active` e `defaultSelect`
+      // continuam com seus padrões (true e o `defaultSelectModel` global).
       ignoreRequiredWhere: true,
     },
     patch: {
+      // Somente o select é sobrescrito; o método continua ativo normalmente.
       defaultSelect: "minimal",
     },
     has: {
-      active: false, // Desativa o 'has' (padrão = true)
+      active: false, // Desativa o 'has' (padrão = true) — o método some do repository
     },
     softRemove: {
+      // Métodos de soft-delete seguem as mesmas opções (`active`, `defaultSelect`,
+      // `ignoreRequiredWhere`). Só ficam disponíveis se `softRemovekName` estiver configurado.
       active: true,
       defaultSelect: "minimal",
     },
@@ -434,6 +486,8 @@ usuarioVSRepo.build(prisma, {
 });
 ```
 
+> Métodos em lote/agregados como `removeList`, `softRemoveList`, `restoreList`, `total` e `has` **não** aceitam `defaultSelect` (não retornam um registro selecionável — retornam `{ count }` ou `boolean`). Nesses casos `BaseMethodConfig` fica restrito a `active` e `ignoreRequiredWhere`.
+
 ---
 
 ## Select Models
@@ -574,7 +628,9 @@ methods: {
 
 ---
 
-Quando `softRemovekName` está configurado, todos os métodos base aceitam a opção `see` para controlar a visibilidade de registros soft-deletados:
+## Opção `see`
+
+Quando `softRemovekName` está configurado, todos os métodos aceitam a opção `see` para controlar a visibilidade de registros soft-deletados:
 
 | Valor       | Comportamento                                                 |
 | ----------- | ------------------------------------------------------------- |
@@ -591,10 +647,6 @@ const removidos = await usuarioRepository.getAll({ see: "removed" });
 
 // Retorna todos
 const todos = await usuarioRepository.getAll({ see: "all" });
-
-// Funciona em qualquer método base
-const usuario = await usuarioRepository.get(id, { see: "all" });
-const existe = await usuarioRepository.has(id, { see: "removed" });
 ```
 
 > A opção `see` funciona independentemente do `requiredWhere` — ela é aplicada em cima do filtro de soft-delete, não o substitui.
@@ -735,16 +787,50 @@ Exemplo:
 methods: {
   findOneByIdAndEmail:   { map: true },
   findByNomeOrEmail:  { map: true },
-  findUniqueByIdOrEmailAndNome: { map: true },
+  findFirstByIdOrEmailAndNome: { map: true },
   findByEmailOrNameANDActiveStatusAndIdadeGreaterThan: { map: true }
 }
 
 await usuarioRepository.findOneByIdAndEmail(1, "joao@email.com");
 await usuarioRepository.findByNomeOrEmail("Joao", "joao@email.com");
-await usuarioRepository.findUniqueByIdOrEmailAndNome(1, "joao@email.com", "Joao");
+await usuarioRepository.findFirstByIdOrEmailAndNome(1, "joao@email.com", "Joao");
 await usuarioRepository.findByEmailOrNameANDActiveStatusAndIdadeGreaterThan("joao@email.com", "Joao", true, 17)
 ```
 
+Gera (`findOneByIdAndEmail`):
+
+```ts
+{
+  id: 1,
+  email: "joao@email.com"
+}
+```
+
+Gera (`findByNomeOrEmail`):
+
+```ts
+{
+  OR: [
+    { nome: "Joao" },
+    { email: "joao@email.com" }
+  ]
+}
+```
+
+Gera (`findFirstByIdOrEmailAndNome`):
+
+```ts
+{
+  OR: [
+    { id: 1 },
+    {
+      email: "joao@email.com",
+      nome: "Joao"
+    }
+  ]
+}
+```
+
 Gera (`findByEmailOrNameANDActiveStatusAndIdadeGreaterThan`):
 
 ```ts
@@ -784,6 +870,78 @@ Permitem filtrar por campos de modelos relacionados.
 | `Without`              | `isNot: {}`     | Relação não existe (é null)                        |
 | `WithoutField`         | `isNot.field`   | Filtra campo dentro da relação com negação         |
 
+Considerando `usuario` com uma relação to-one `perfil` e uma relação to-many `postagens`:
+
+```ts
+methods: {
+  // to-many (postagens)
+  findByPostagensSome:          { map: true }, // tem ao menos uma postagem
+  findByPostagensSomeTitulo:    { map: true }, // tem ao menos uma postagem com esse título
+  findByPostagensEveryPublicada:{ map: true }, // todas as postagens estão publicadas
+  findByPostagensNone:          { map: true }, // não tem nenhuma postagem
+  findByPostagensNoneTitulo:    { map: true }, // nenhuma postagem tem esse título
+
+  // to-one (perfil)
+  findByPerfilWith:             { map: true }, // possui perfil (não é null)
+  findByPerfilWithBio:          { map: true }, // possui perfil com essa bio
+  findByPerfilWithout:          { map: true }, // não possui perfil (é null)
+  findByPerfilWithoutBio:       { map: true }, // possui perfil, mas com bio diferente da informada
+}
+
+await usuarioRepository.findByPostagensSome();
+await usuarioRepository.findByPostagensSomeTitulo("Meu primeiro post");
+await usuarioRepository.findByPostagensEveryPublicada(true);
+await usuarioRepository.findByPostagensNone();
+await usuarioRepository.findByPostagensNoneTitulo("Rascunho");
+
+await usuarioRepository.findByPerfilWith();
+await usuarioRepository.findByPerfilWithBio("Olá, mundo!");
+await usuarioRepository.findByPerfilWithout();
+await usuarioRepository.findByPerfilWithoutBio("Bio antiga");
+```
+
+Gera (`findByPostagensSomeTitulo`):
+
+```ts
+{
+  postagens: {
+    some: { titulo: "Meu primeiro post" }
+  }
+}
+```
+
+Gera (`findByPostagensEveryPublicada`):
+
+```ts
+{
+  postagens: {
+    every: { publicada: true }
+  }
+}
+```
+
+Gera (`findByPerfilWithBio`):
+
+```ts
+{
+  perfil: {
+    is: { bio: "Olá, mundo!" }
+  }
+}
+```
+
+Gera (`findByPerfilWithout`):
+
+```ts
+{
+  perfil: {
+    isNot: {}
+  }
+}
+```
+
+> `Some`, `None`, `With` e `Without` (sem campo) não recebem argumento — a relação inteira é testada quanto à existência de registros (`some`/`none`) ou a ser `null`/não-`null` (`is`/`isNot`). Já as variantes `SomeField`, `EveryField`, `NoneField`, `WithField` e `WithoutField` recebem o valor do campo filtrado como argumento.
+
 ---
 
 ### Sufixos de paginação e ordenação
@@ -887,6 +1045,20 @@ const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
 | `set`     | Substitui completamente (remove os que não foram enviados)  |
 | `add`     | Adiciona/atualiza sem remover os existentes                 |
 
+> [!WARNING]
+> **`set` significa coisas diferentes dependendo do `mode` da relação — e isso pode causar perda de dados se você não prestar atenção.**
+>
+> Em relações onde o registro relacionado **pertence** ao registro pai (`oto` e `otm`), "remover os que não foram enviados" significa **deletar o registro do banco** (`delete`/`deleteMany`). Já em relações onde o registro relacionado é **independente** (`mto` e `mtm`), "remover" significa apenas **desvincular** (`disconnect`/`set: []`) — o registro relacionado continua existindo no banco, só deixa de apontar para o pai (ou de estar na tabela de junção).
+>
+> | Modo  | `restriction: "set"` ao omitir um item | O item continua existindo no banco? |
+> | ----- | ---------------------------------------- | ------------------------------------ |
+> | `oto` | Passar `null` no campo → **deleta** o registro relacionado (`delete: true`) | Não |
+> | `otm` | Itens fora da lista enviada → **deletados** (`deleteMany` com `notIn`)      | Não |
+> | `mto` | Passar `null` no campo (com `nullable: true`) → **desvincula** (`disconnect: true`) | Sim |
+> | `mtm` | Itens fora da lista enviada → **desvinculados** da tabela de junção (`set: []`) | Sim |
+>
+> Exemplo prático: se `postagens` é `otm` com `restriction: "set"`, um `save`/`patch` que envie o usuário com apenas 2 das 5 postagens existentes vai **apagar as outras 3 postagens do banco**, não apenas desvinculá-las do usuário. Se o comportamento esperado é só desvincular sem apagar, use `restriction: "add"` (que nunca remove nada) e gerencie a remoção manualmente.
+
 **Relação `mto` com nullable:**
 
 Use `nullable` (letra minúscula) para permitir a desvinculação de uma relação many-to-one:
@@ -902,8 +1074,6 @@ relations: {
 }
 ```
 
-> **Nota:** `nullAble` (com A maiúsculo) ainda é aceito por compatibilidade, mas está **obsoleto**. Prefira `nullable`.
-
 ---
 
 ## Transações
@@ -924,15 +1094,17 @@ await usuarioRepository.prisma.$transaction(async (tx) => {
 });
 ```
 
-Para `saveList` e `patchList`, o campo `db` deve ser um `DbTransaction` (não o cliente principal):
+Para `saveList` e `patchList`, o campo `db` deve ser um `DbTransaction`:
 
 ```ts
 await prisma.$transaction(async (tx) => {
   // CORRETO: tx é uma DbTransaction
-  await usuarioRepository.saveList([{ nome: "Maria" }], { db: tx });
+  const usuariosCadastrados = await usuarioRepository.saveList([{ nome: "Maria" }, { nome: "Lucas" }], { db: tx });
 
-  // ERRADO: não passe o prisma diretamente
-  // await usuarioRepository.saveList([{ nome: "Maria" }], { db: prisma });
+  await usuarioLogsRepository.save(
+    { acao: "Cadastro de usuários", data: { usuariosCadastrados: usuariosCadastrados.map(u => u.id) } },
+    { db: tx }
+  );
 });
 ```
 
@@ -970,12 +1142,14 @@ O VSRepository lança `VSRepoError` e suas subclasses em situações específica
 import { VSRepoError, VSRepoRuntimeError } from "../../generated/vsrepo";
 
 try {
-  const usuario = await usuarioRepository.getOrThrow(id);
+  const usuario = await usuarioRepository.getOrThrow("id-que-nao-existe");
 } catch (error) {
   if (error instanceof VSRepoRuntimeError && error.code === "20727") {
-    // Registro não encontrado pelo getOrThrow
+    console.error("Registro não encontrado");
   } else if (error instanceof VSRepoError) {
     console.error("Erro no repository:", error.message);
+  } else {
+    console.error("Erro:", error.message)
   }
 }
 ```
@@ -989,7 +1163,7 @@ try {
 | `VSRepoExtendError`  | Argumento inválido em `extend`                                    |
 | `VSRepoRuntimeError` | Erro em tempo de execução durante uma operação                    |
 
-`VSRepoRuntimeError` possui a propriedade `code` para identificação programática. O código `"20727"` é lançado pelo `getOrThrow` quando o registro não é encontrado.
+`VSRepoRuntimeError` possui a propriedade `code` para identificação programática. O código `"20727"` é lançado pelo `getOrThrow` quando o registro não é encontrado, por exemplo.
 
 ---
 
@@ -1098,7 +1272,7 @@ type UsuarioPatchPayload = PatchObject<Prisma.UsuarioUpdateInput, typeof usuario
 setupVSRepo<TPayload, TTableName>()({
   tableName: Uncapitalize<M>;                     // Nome da tabela no Prisma
   pkName: keyof T;                                // Nome da primary key
-  softRemovekName?: keyof T & string;             // Campo DateTime para soft-delete (opcional)
+  softRemovekName?: keyof T & string;             // Campo DateTime para soft-delete
   selectModels?: SelectModels<M>;                 // Projeções de dados nomeadas (select)
   defaultSelectModel?: keyof SM;                  // Select aplicado por padrão
   includeModels?: IncludeModels<M>;               // Projeções de dados nomeadas (include) — sem default, só na chamada
@@ -1150,6 +1324,28 @@ repo.extend((repo) => ({
 
 ---
 
+## Exemplos práticos
+
+Além deste README, o repositório tem uma pasta **[`examples/`](https://github.com/jaobrabo123/VSRepository/tree/main/examples)** com exemplos práticos e comentados, prontos para rodar — é o melhor lugar para ver o VSRepository sendo usado em cenários reais.
+
+```
+examples/
+├── prisma.ts             # Instância do PrismaClient usada pelos exemplos
+├── repositories.ts       # Configuração dos repositories (User, Address, Product) com setupVSRepo
+└── tests/
+    ├── base-methods.test.ts       # Métodos base: get, save, patch, remove, getAll, total, has...
+    ├── relations.test.ts          # Como configurar e usar relations no save/patch e em filtros
+    ├── required-where.test.ts     # Como o requiredWhere é aplicado automaticamente nas queries
+    ├── dynamic-methods.test.ts    # Prefixos, filtros de campo, operadores lógicos e paginação/ordenação
+    ├── transactions.test.ts       # Transactions com options.db e acesso à instância via repository.prisma
+    ├── soft-delete.test.ts        # Soft-delete: softRemove, softRemoveList, restore, restoreList e SeeMode
+    └── batch-methods.test.ts      # Operações em lote: getList, saveList, patchList e merge
+```
+
+Cada arquivo em `tests/` é um script independente e executável (via `tsx`) que demonstra um conjunto específico de funcionalidades, com `console.log` em cada passo para você acompanhar o resultado no terminal. A própria pasta tem um [README](https://github.com/jaobrabo123/VSRepository/blob/main/examples/README.md) explicando a ordem sugerida de leitura, como configurar o ambiente e como rodar os testes.
+
+---
+
 ## Contribuindo
 
 Contribuições são bem-vindas! Se você encontrou um bug, tem uma ideia de melhoria ou quer ajudar com a documentação, sinta-se à vontade para participar (**[Repositório do GitHub](https://github.com/jaobrabo123/VSRepository)**):
@@ -1195,7 +1391,7 @@ Para reportar problemas ou sugerir novas funcionalidades, abra uma **Issue**.
 
 **`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.
+**Select model retorna campos inesperados** — Verifique se o select model define exatamente os campos que o seu tipo TypeScript espera.
 
 **`selectModel` e `includeModel` juntos na mesma chamada** — Não é permitido. Escolha um ou outro: se `includeModel` for informado, o `select` (incluindo o `defaultSelectModel`) é ignorado e apenas o `include` é enviado ao Prisma.
 
@@ -1205,4 +1401,4 @@ Para reportar problemas ou sugerir novas funcionalidades, abra uma **Issue**.
 
 **`defaultOrdenation` não está sendo aplicada** — Verifique se o método não usa o sufixo `Ordered`, `OrderedAndPaginated` ou `PaginatedAndOrdered`, e se não possui `injectOrdenation` configurado. Ambos têm prioridade sobre a ordenação padrão.
 
-**`saveList`/`patchList` com `db` inválido** — O campo `db` nestes métodos aceita apenas `DbTransaction` (retorno de `prisma.$transaction`), não o cliente principal. Passar o `PrismaClient` diretamente causará comportamento inesperado.
+**`saveList`/`patchList` com `db` inválido** — O campo `db` nestes métodos aceita apenas `DbTransaction` (retorno de `prisma.$transaction`), não o cliente principal. Passar o `PrismaClient` diretamente causará comportamento inesperado.

package/dist/VSRepository.d.ts

@@ -291,9 +291,17 @@ export type MethodOptionsModel<TRepo> =
         ? MethodOptions<keyof ExtractSelectModels<Config> | false, keyof ExtractIncludeModels<Config>>
         : never;
 
+type MethodOptionsWithInclude<
+    S,
+    IM extends PropertyKey,
+    TIncludes,
+    Excluded extends keyof MethodOptions<S, keyof TIncludes> = never
+> = Omit<MethodOptions<S, keyof TIncludes>, Excluded>
+    & ({ includeModel: IM } | { includeModel?: never });
+
 type MethodFn<MethodName extends string, T, M extends Prisma.ModelName, R extends string, SelectModels, DefaultSelect extends keyof SelectModels | false, I, IncludeModels> = 
     <S extends keyof SelectModels | false = DefaultSelect, IM extends keyof IncludeModels = never>(
-        ...args: [...ExtractFields<T, CleanFields<R>, I>, ...ExtraArgs<MethodName, R, I>, options?: MethodOptions<S, keyof IncludeModels> & ({ includeModel: IM } | { includeModel?: never })]
+        ...args: [...ExtractFields<T, CleanFields<R>, I>, ...ExtraArgs<MethodName, R, I>, options?: MethodOptionsWithInclude<S, IM, IncludeModels>]
     ) => Promise<ResolveReturnType<MethodName, SelectedModel<M, S, SelectModels, IM, IncludeModels>>>;
 
 type GetMappedMethod<K extends string, MethodConf> = 
@@ -349,7 +357,7 @@ type MethodFactory<T, M extends Prisma.ModelName, K extends string, SelectModels
     K extends `findWhere${string}`
         ? {
             /** @deprecated Use findOneWhere instead. */
-            <S extends keyof SelectModels | false = DefaultSelect, IM extends keyof IncludeModels = never>(...args: [...ExtractFields<T, CleanFields<ExtractPatternBase<K>>, I>, ...ExtraArgs<GetMappedMethod<K, MethodConf>, ExtractPatternBase<K>, I>, options?: MethodOptions<S, keyof IncludeModels> & ({ includeModel: IM } | { includeModel?: never })]): Promise<ResolveReturnType<GetMappedMethod<K, MethodConf>, SelectedModel<M, S, SelectModels, IM, IncludeModels>>>;
+            <S extends keyof SelectModels | false = DefaultSelect, IM extends keyof IncludeModels = never>(...args: [...ExtractFields<T, CleanFields<ExtractPatternBase<K>>, I>, ...ExtraArgs<GetMappedMethod<K, MethodConf>, ExtractPatternBase<K>, I>, options?: MethodOptionsWithInclude<S, IM, IncludeModels>]): Promise<ResolveReturnType<GetMappedMethod<K, MethodConf>, SelectedModel<M, S, SelectModels, IM, IncludeModels>>>;
           }
         : MethodFn<GetMappedMethod<K, MethodConf>, T, M, ExtractPatternBase<K>, SelectModels, DefaultSelect, I, IncludeModels>;
 
@@ -703,47 +711,47 @@ type AllBaseMethods<
 > = {
     /** Fetches a record by its primary key (PK). */
     get: <S extends keyof TSelects | false = _DS<Config, C, 'get', TSelects>, IM extends keyof TIncludes = never>(
-        pk: _Pk<T, Config>, options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never })
+        pk: _Pk<T, Config>, options?: MethodOptionsWithInclude<S, IM, TIncludes>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes> | null>;
 
     /** Fetches a record by PK and throws `VSRepoRuntimeError` if not found. */
     getOrThrow: <S extends keyof TSelects | false = _DS<Config, C, 'getOrThrow', TSelects>, IM extends keyof TIncludes = never>(
-        pk: _Pk<T, Config>, options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never })
+        pk: _Pk<T, Config>, options?: MethodOptionsWithInclude<S, IM, TIncludes>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>>;
 
     /** Fetches multiple records by a list of primary keys (PKs). */
     getList: <S extends keyof TSelects | false = _DS<Config, C, 'getList', TSelects>, IM extends keyof TIncludes = never>(
-        pks: _Pk<T, Config>[], options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never })
+        pks: _Pk<T, Config>[], options?: MethodOptionsWithInclude<S, IM, TIncludes>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>[]>;
 
     /** Deletes a record identified by its primary key (PK). */
     remove: <S extends keyof TSelects | false = _DS<Config, C, 'remove', TSelects>, IM extends keyof TIncludes = never>(
-        pk: _Pk<T, Config>, options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never })
+        pk: _Pk<T, Config>, options?: MethodOptionsWithInclude<S, IM, TIncludes>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>>;
 
     /** Inserts or updates (upsert) a record. */
     save: <S extends keyof TSelects | false = _DS<Config, C, 'save', TSelects>, IM extends keyof TIncludes = never>(
-        obj: UpsertWithRelations<T, M, TRelations>, options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never })
+        obj: UpsertWithRelations<T, M, TRelations>, options?: MethodOptionsWithInclude<S, IM, TIncludes>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>>;
 
     /** Saves an array of objects in a single automatic transaction. */
     saveList: <S extends keyof TSelects | false = _DS<Config, C, 'saveList', TSelects>, IM extends keyof TIncludes = never>(
-        objs: UpsertWithRelations<T, M, TRelations>[], options?: Omit<MethodOptions<S, keyof TIncludes>, 'db'> & ({ includeModel: IM } | { includeModel?: never }) & { db?: DbTransaction }
+        objs: UpsertWithRelations<T, M, TRelations>[], options?: MethodOptionsWithInclude<S, IM, TIncludes, 'db'> & { db?: DbTransaction }
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>[]>;
 
     /** Partially updates (patch) an existing record by its primary key (PK). */
     patch: <S extends keyof TSelects | false = _DS<Config, C, 'patch', TSelects>, IM extends keyof TIncludes = never>(
-        pk: _Pk<T, Config>, obj: PatchWithRelations<T, M, TRelations>, options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never })
+        pk: _Pk<T, Config>, obj: PatchWithRelations<T, M, TRelations>, options?: MethodOptionsWithInclude<S, IM, TIncludes>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>>;
 
     /** Partially updates multiple records via `[pk, obj]` tuples in an automatic transaction. */
     patchList: <S extends keyof TSelects | false = _DS<Config, C, 'patchList', TSelects>, IM extends keyof TIncludes = never>(
-        tuples: [pk: _Pk<T, Config>, obj: PatchWithRelations<T, M, TRelations>][], options?: Omit<MethodOptions<S, keyof TIncludes>, 'db'> & ({ includeModel: IM } | { includeModel?: never }) & { db?: DbTransaction }
+        tuples: [pk: _Pk<T, Config>, obj: PatchWithRelations<T, M, TRelations>][], options?: MethodOptionsWithInclude<S, IM, TIncludes, 'db'> & { db?: DbTransaction }
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>[]>;
 
     /** Fetches a record by PK and deep-merges it with the provided object **in memory**. */
     merge: <S extends keyof TSelects | false = _DS<Config, C, 'merge', TSelects>, IM extends keyof TIncludes = never>(
-        pk: _Pk<T, Config>, obj: UpdateWithRelations<T, M, TRelations>, options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never })
+        pk: _Pk<T, Config>, obj: UpdateWithRelations<T, M, TRelations>, options?: MethodOptionsWithInclude<S, IM, TIncludes>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes> | null>;
 
     /** Deletes multiple records by their primary keys. */
@@ -751,7 +759,7 @@ type AllBaseMethods<
 
     /** Fetches all records (respects `requiredWhere` when set). */
     getAll: <S extends keyof TSelects | false = _DS<Config, C, 'getAll', TSelects>, IM extends keyof TIncludes = never>(
-        options?: MethodOptions<S, keyof TIncludes> & ({ includeModel: IM } | { includeModel?: never }) & {
+        options?: MethodOptionsWithInclude<S, IM, TIncludes> & {
             pagination?: PaginationOptions<I extends { cursorInput: infer Curs } ? Curs : unknown>;
             /**
              * Ordering to apply to the query.
@@ -770,7 +778,7 @@ type AllBaseMethods<
 
     /** Marks a record as deleted (soft-delete). */
     softRemove: <S extends keyof TSelects | false = _DS<Config, C, 'softRemove', TSelects>, IM extends keyof TIncludes = never>(
-        pk: _Pk<T, Config>, options?: Omit<MethodOptions<S, keyof TIncludes>, 'see'> & ({ includeModel: IM } | { includeModel?: never })
+        pk: _Pk<T, Config>, options?: MethodOptionsWithInclude<S, IM, TIncludes, 'see'>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>>;
 
     /** Marks multiple records as deleted (soft-delete) in batch. */
@@ -778,7 +786,7 @@ type AllBaseMethods<
 
     /** Restores a record previously marked as deleted (soft-delete). */
     restore: <S extends keyof TSelects | false = _DS<Config, C, 'restore', TSelects>, IM extends keyof TIncludes = never>(
-        pk: _Pk<T, Config>, options?: Omit<MethodOptions<S, keyof TIncludes>, 'see'> & ({ includeModel: IM } | { includeModel?: never })
+        pk: _Pk<T, Config>, options?: MethodOptionsWithInclude<S, IM, TIncludes, 'see'>
     ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>>;
 
     /** Restores multiple records previously marked as deleted (soft-delete) in batch. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vsrepo",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Uma biblioteca de repository pattern para Prisma",
   "homepage": "https://github.com/jaobrabo123/VSRepository#readme",
   "repository": {