vsrepo 1.2.9 → 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
@@ -30,6 +32,7 @@ O VSRepository permite criar repositories fortemente tipados com:
   - [Merge](#merge)
   - [Configurando os métodos base](#configurando-os-métodos-base)
 - [Select Models](#select-models)
+- [Include Models](#include-models)
 - [Required Where](#requiredwhere)
 - [Default Ordenation](#default-ordenation)
 - [Opção `see`](#opção-see)
@@ -47,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)
@@ -137,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
@@ -230,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");
 
@@ -362,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]
@@ -400,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",
     },
@@ -433,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
@@ -464,6 +519,51 @@ const usuarioCompleto = await usuarioRepository.get(id, { selectModel: false });
 
 ---
 
+## Include Models
+
+`includeModels` funciona de forma parecida com o `selectModels`, mas em vez de receber um `select`, ele recebe um `include` válido do Prisma.
+
+```ts
+const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
+  tableName: "usuario",
+  pkName: "id",
+  selectModels: {
+    public: { id: true, nome: true, email: true },
+  },
+  defaultSelectModel: "public",
+  includeModels: {
+    comPosts: { posts: true },
+    comPostsEPerfil: { posts: true, perfil: true },
+  },
+}).build(prisma);
+```
+
+**Usando um `includeModel` na chamada:**
+
+```ts
+const usuario = await usuarioRepository.get(id, { includeModel: "comPosts" });
+```
+
+Nesse caso, o `select` padrão (`selectModels`/`defaultSelectModel`) é ignorado e apenas o `include` é enviado ao Prisma.
+
+### Diferenças em relação ao `selectModels`
+
+- **Só pode ser passado na chamada do método**, via `options.includeModel`. Não existe `defaultIncludeModel` nem `defaultInclude` — não há como configurar um `includeModel` padrão no repository, diferente do que ocorre com `defaultSelectModel`.
+- **`includeModel` e `selectModel` não podem ser passados juntos** na mesma chamada. Se um `includeModel` for informado, qualquer `selectModel` (incluindo o padrão) é ignorado.
+
+```ts
+// CORRETO ✅ — apenas includeModel
+await usuarioRepository.get(id, { includeModel: "comPosts" });
+
+// CORRETO ✅ — apenas selectModel
+await usuarioRepository.get(id, { selectModel: "public" });
+
+// ERRADO ❌ — não é permitido combinar os dois
+await usuarioRepository.get(id, { selectModel: "public", includeModel: "comPosts" });
+```
+
+---
+
 ## Required Where
 
 `requiredWhere` define filtros aplicados automaticamente em todas as queries do repository.
@@ -528,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                                                 |
 | ----------- | ------------------------------------------------------------- |
@@ -545,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.
@@ -689,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
@@ -738,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
@@ -841,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:
@@ -856,8 +1074,6 @@ relations: {
 }
 ```
 
-> **Nota:** `nullAble` (com A maiúsculo) ainda é aceito por compatibilidade, mas está **obsoleto**. Prefira `nullable`.
-
 ---
 
 ## Transações
@@ -878,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 }
+  );
 });
 ```
 
@@ -924,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)
   }
 }
 ```
@@ -943,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.
 
 ---
 
@@ -973,6 +1193,8 @@ type SeeMode = "active" | "removed" | "all";
 import type {
   SelectModel,
   SelectModels,
+  IncludeModel,
+  IncludeModels,
   WhereModel,
   OrdenationModel,
   PaginationModel,
@@ -986,14 +1208,16 @@ import type {
 ```ts
 import type { MethodOptions, MethodOptionsModel } from "../../generated/vsrepo";
 
-// MethodOptions<S> — opções passadas nos métodos do repository
-type Opts = MethodOptions<"public" | "minimal">;
+// MethodOptions<S, IM> — opções passadas nos métodos do repository
+type Opts = MethodOptions<"public" | "minimal", "comPosts">;
 
 // MethodOptionsModel<TRepo> — derivado de uma instância VSRepository configurada
 const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()(config);
 type OptsModel = MethodOptionsModel<typeof usuarioVSRepo>;
 ```
 
+> O segundo parâmetro de `MethodOptions` (`IM`) representa as chaves válidas de `includeModels`. Quando informado, `selectModel` e `includeModel` tornam-se mutuamente exclusivos no tipo — não é possível passar os dois na mesma chamada.
+
 ### Tipos de configuração
 
 ```ts
@@ -1048,9 +1272,10 @@ 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)
-  selectModels?: SelectModels<M>;                 // Projeções de dados nomeadas
+  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
   requiredWhere?: WhereModel<M>;                  // Filtros sempre aplicados
   defaultOrdenation?: OrdenationModel<M>;         // Ordenação padrão para queries sem Ordered/injectOrdenation
   relations?: RepositoryRelations<T>;             // Configuração de relações
@@ -1099,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)**):
@@ -1144,10 +1391,14 @@ 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.
+
+**`includeModel` não aparece como opção padrão do repository** — Isso é esperado. Diferente de `defaultSelectModel`, não existe `defaultIncludeModel`/`defaultInclude`. Um `includeModel` só pode ser definido na chamada do método, via `options.includeModel`.
 
 **`softRemovekName` lança erro no build** — O campo informado deve ser do tipo `DateTime` no schema do Prisma. Tipos como `Boolean` ou `String` não são aceitos.
 
 **`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/VSRepoError.d.ts

@@ -50,5 +50,5 @@ export declare class VSRepoExtendError extends VSRepoError {
  */
 export declare class VSRepoRuntimeError extends VSRepoError {
     readonly type: 'VSREPO_RUNTIME';
-    constructor(message: string, code?: string);
+    constructor(message: string, code: string);
 }

package/dist/VSRepository.d.ts

@@ -222,14 +222,22 @@ type PrecomputedSelects<M extends Prisma.ModelName, SelectModels> = {
     [S in keyof SelectModels]: Prisma.Result<PrismaDelegate<M>, { select: SelectModels[S] }, 'findMany'> extends Array<infer U> ? U : never
 };
 
-type SelectedModel<M extends Prisma.ModelName, S, SelectModels> = 
-    [S] extends [false] 
-        ? FullModelType<M>
-        : [S] extends [never] 
-            ? FullModelType<M> 
-            : [S] extends [keyof SelectModels] 
-                ? PrecomputedSelects<M, SelectModels>[S]
-                : FullModelType<M>;
+type PrecomputedIncludes<M extends Prisma.ModelName, IncludeModels> = {
+    [I in keyof IncludeModels]: Prisma.Result<PrismaDelegate<M>, { include: IncludeModels[I] }, 'findMany'> extends Array<infer U> ? U : never
+};
+
+type SelectedModel<M extends Prisma.ModelName, S, SelectModels, IM = never, IncludeModels = {}> = 
+    [IM] extends [never]
+        ? [S] extends [false] 
+            ? FullModelType<M>
+            : [S] extends [never] 
+                ? FullModelType<M> 
+                : [S] extends [keyof SelectModels] 
+                    ? PrecomputedSelects<M, SelectModels>[S]
+                    : FullModelType<M>
+        : IM extends keyof IncludeModels
+            ? PrecomputedIncludes<M, IncludeModels>[IM]
+            : FullModelType<M>;
 
 type CleanFields<R extends string> =
     R extends `${infer F}PaginatedAndOrdered` ? F :
@@ -242,17 +250,10 @@ type CleanFields<R extends string> =
  * Additional options accepted by repository methods.
  *
  * @template S Available keys in `selectModels`.
+ * @template IM Available keys in `includeModels`.
  */
-export type MethodOptions<S> = {
-    /**
-     * Select model to apply to the operation.
-     *
-     * @note Use `false` to return the full Prisma payload without a select.
-     */
-    selectModel?: S | false;
-    /**
-     * Prisma client or transaction to use for the operation.
-     */
+export type MethodOptions<S, IM extends PropertyKey = never> = {
+    /** Prisma client or transaction to use for the operation. */
     db?: ClientOrTransaction;
     /**
      * Visibility mode for records with soft-delete.
@@ -264,7 +265,17 @@ export type MethodOptions<S> = {
      * - `"all"` — returns all records, ignoring deletion status.
      */
     see?: SeeMode;
-};
+} & (
+    [IM] extends [never]
+        ? { 
+            /** Select model to apply to the operation. Use `false` to return the full payload. */
+            selectModel?: S | false; 
+            /** Include model to apply to the operation. Cannot be used together with `selectModel`. */
+            includeModel?: never;
+          }
+        : | { selectModel?: S | false; includeModel?: never }
+          | { selectModel?: never; includeModel: IM }
+);
 
 /**
  * Version of `MethodOptions` derived directly from a configured `VSRepository` instance.
@@ -277,11 +288,21 @@ export type MethodOptions<S> = {
  */
 export type MethodOptionsModel<TRepo> =
     TRepo extends VSRepository<any, any, infer Config>
-        ? MethodOptions<keyof ExtractSelectModels<Config> | false>
+        ? MethodOptions<keyof ExtractSelectModels<Config> | false, keyof ExtractIncludeModels<Config>>
         : never;
 
-type MethodFn<MethodName extends string, T, M extends Prisma.ModelName, R extends string, SelectModels, DefaultSelect extends keyof SelectModels | false, I> = 
-    <S extends keyof SelectModels | false = DefaultSelect>(...args: [...ExtractFields<T, CleanFields<R>, I>, ...ExtraArgs<MethodName, R, I>, options?: MethodOptions<S>]) => Promise<ResolveReturnType<MethodName, SelectedModel<M, S, SelectModels>>>;
+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?: MethodOptionsWithInclude<S, IM, IncludeModels>]
+    ) => Promise<ResolveReturnType<MethodName, SelectedModel<M, S, SelectModels, IM, IncludeModels>>>;
 
 type GetMappedMethod<K extends string, MethodConf> = 
     K extends `findBy${string}` ? (MethodConf extends { fbMode: 'one' } ? 'findByOne' : 'findByList') :
@@ -332,13 +353,13 @@ type ExtractPatternBase<K extends string> =
     K extends `updateManyAndReturnWhere${infer R}` ? R :
     K extends `deleteManyWhere${infer R}` ? R : '';
 
-type MethodFactory<T, M extends Prisma.ModelName, K extends string, SelectModels, DefaultSelect extends keyof SelectModels | false, I, MethodConf> = 
+type MethodFactory<T, M extends Prisma.ModelName, K extends string, SelectModels, DefaultSelect extends keyof SelectModels | false, I, MethodConf, IncludeModels> = 
     K extends `findWhere${string}`
         ? {
             /** @deprecated Use findOneWhere instead. */
-            <S extends keyof SelectModels | false = DefaultSelect>(...args: [...ExtractFields<T, CleanFields<ExtractPatternBase<K>>, I>, ...ExtraArgs<GetMappedMethod<K, MethodConf>, ExtractPatternBase<K>, I>, options?: MethodOptions<S>]): Promise<ResolveReturnType<GetMappedMethod<K, MethodConf>, SelectedModel<M, S, SelectModels>>>;
+            <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>;
+        : MethodFn<GetMappedMethod<K, MethodConf>, T, M, ExtractPatternBase<K>, SelectModels, DefaultSelect, I, IncludeModels>;
 
 type ResolveSelectModel<MethodConf, GlobalConf, SelectModels> = 
     MethodConf extends { selectModel: infer S } ? (S extends false ? false : S extends keyof SelectModels ? S : never) : 
@@ -346,6 +367,7 @@ type ResolveSelectModel<MethodConf, GlobalConf, SelectModels> =
 
 type ExtractPkName<T, Config> = Config extends { pkName: infer PK } ? (PK extends keyof T ? PK : never) : never;
 type ExtractSelectModels<Config> = Config extends { selectModels: infer SM } ? SM : {};
+type ExtractIncludeModels<Config> = Config extends { includeModels: infer IM } ? IM : {};
 type ExtractDefaultSelect<Config> = Config extends { defaultSelectModel: infer D } ? D : never;
 type ExtractRelations<Config> = Config extends { relations: infer R } ? (R extends object ? R : {}) : {};
 type ExtractSoftRemovekName<Config> = Config extends { softRemovekName: infer S } ? S : never;
@@ -370,7 +392,7 @@ type DynamicMethods<T, M extends Prisma.ModelName, Config, I> = Config extends {
                       : ResolvedKey extends 'groupBy'
                       ? GroupByMethod<M>
                       : ResolvedKey extends string
-                      ? MethodFactory<T, M, ResolvedKey, ExtractSelectModels<Config>, ResolveSelectModel<Methods[K], Config, ExtractSelectModels<Config>>, I, Methods[K]>
+                      ? MethodFactory<T, M, ResolvedKey, ExtractSelectModels<Config>, ResolveSelectModel<Methods[K], Config, ExtractSelectModels<Config>>, I, Methods[K], ExtractIncludeModels<Config>>
                       : never
                   : never
               : never;
@@ -385,6 +407,8 @@ type DynamicMethods<T, M extends Prisma.ModelName, Config, I> = Config extends {
 export type PrismaModelInputs<M extends Prisma.ModelName> = {
     /** Type of the `select` argument used in model queries. */
     select: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['select'];
+    /** Type of the `include` argument used in model queries. */
+    include: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['include'];
     /** Type of the `data` used in `create`. */
     createInput: Prisma.TypeMap['model'][M]['operations']['create']['args']['data'];
     /** Type of the `data` used in `createMany`. */
@@ -415,6 +439,16 @@ export type SelectModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['sele
  */
 export type SelectModels<M extends Prisma.ModelName> = Record<string, SelectModel<M>>;
 
+/**
+ * Type of the `include` object of a Prisma model.
+ */
+export type IncludeModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['include'];
+
+/**
+ * Map of named, reusable includes for a Prisma model.
+ */
+export type IncludeModels<M extends Prisma.ModelName> = Record<string, IncludeModel<M>>;
+
 /**
  * Type of the `where` object of a Prisma model.
  */
@@ -452,8 +486,7 @@ export type MethodConfig<M extends Prisma.ModelName, SelectModels = any> = {
     readonly proxyTo?: ValidMethodPatterns;
     /** Adds an extra `where` on top of `requiredWhere`. */
     readonly pushWhere?: WhereModel<M>;
-    /** 
-     * Defines whether `findBy` returns a single item (`one`) or a list (`list`).
+    /** * Defines whether `findBy` returns a single item (`one`) or a list (`list`).
      * @deprecated Use `findOneBy` if you want to return a single result.
      */
     readonly fbMode?: 'one' | 'list';
@@ -497,8 +530,12 @@ export type BuildConfig<TSelectKeys extends PropertyKey = string> = {
         remove?: BaseMethodConfig<TSelectKeys>;
         /** Configuration for the `save` method. */
         save?: BaseMethodConfig<TSelectKeys>;
+        /** Configuration for the `saveList` method (batch save via transaction). */
+        saveList?: BaseMethodConfig<TSelectKeys>;
         /** Configuration for the `patch` method. */
         patch?: BaseMethodConfig<TSelectKeys>;
+        /** Configuration for the `patchList` method (batch update via transaction). */
+        patchList?: BaseMethodConfig<TSelectKeys>;
         /** Configuration for the `merge` method. */
         merge?: BaseMethodConfig<TSelectKeys>;
         /** Configuration for the `removeList` method (batch deletion). Does not accept select. */
@@ -509,10 +546,6 @@ export type BuildConfig<TSelectKeys extends PropertyKey = string> = {
         total?: Omit<BaseMethodConfig<TSelectKeys>, 'defaultSelect'>;
         /** Configuration for the `has` method (existence check). Does not accept select. */
         has?: Omit<BaseMethodConfig<TSelectKeys>, 'defaultSelect'>;
-        /** Configuration for the `saveList` method (batch save via transaction). */
-        saveList?: BaseMethodConfig<TSelectKeys>;
-        /** Configuration for the `patchList` method (batch update via transaction). */
-        patchList?: BaseMethodConfig<TSelectKeys>;
         /** Configuration for the `softRemove` method. Only available if `softRemovekName` is configured. */
         softRemove?: BaseMethodConfig<TSelectKeys>;
         /** Configuration for the `softRemoveList` method. Does not accept select. Only available if `softRemovekName` is configured. */
@@ -535,12 +568,16 @@ type ResolveMethodDefaultSelect<Config, C, Method extends keyof NonNullable<Buil
             ? ExtractDefaultSelect<Config> 
             : false;
 
-type ResolveCurrentReturn<M extends Prisma.ModelName, Models, S, D> = 
-    [S] extends [false] 
-        ? FullModelType<M> 
-        : [S] extends [never] 
-            ? ([D] extends [never] ? FullModelType<M> : SelectedModel<M, D, Models>)
-            : SelectedModel<M, S, Models>;
+type ResolveCurrentReturn<M extends Prisma.ModelName, Models, S, D, IM = never, Includes = {}> = 
+    [IM] extends [never]
+        ? [S] extends [false] 
+            ? FullModelType<M> 
+            : [S] extends [never] 
+                ? ([D] extends [never] ? FullModelType<M> : SelectedModel<M, D, Models>)
+                : SelectedModel<M, S, Models>
+        : IM extends keyof Includes
+            ? PrecomputedIncludes<M, Includes>[IM]
+            : FullModelType<M>;
 
 // ─── helpers reused within the mapped type ───────────────────────────────────
 // ─── relation payload types ──────────────────────────────────────────────────
@@ -603,13 +640,21 @@ type RelationUpdatePayload<TField, TRelationConfig, M extends Prisma.ModelName,
       : never;
 
 /**
- * Payload accepted by `patch` when the repository has configured relations.
+ * Payload accepted by `merge` when the repository has configured relations (uses update input).
  */
 type UpdateWithRelations<T, M extends Prisma.ModelName, TRelations> =
     DistributiveOmit<PrismaModelInputs<M>['updateInput'], keyof TRelations> & {
         [K in Extract<keyof TRelations, keyof T>]?: RelationUpdatePayload<T[K], TRelations[K], M, K>;
     };
 
+/**
+ * Payload accepted by `patch` and `patchList` when the repository has configured relations (uses create input).
+ */
+type PatchWithRelations<T, M extends Prisma.ModelName, TRelations> =
+    DistributiveOmit<PrismaModelInputs<M>['updateInput'], keyof TRelations> & {
+        [K in Extract<keyof TRelations, keyof T>]?: RelationPayload<T[K], TRelations[K], M, K>;
+    };
+
 /**
  * Extracts the payload type of the `save` method from a configured VSRepository instance.
  */
@@ -631,17 +676,18 @@ export type PatchObject<TInput, TRepo> =
     TRepo extends VSRepository<infer T, infer M, infer Config>
         ? (Config extends { relations: infer R } ? (R extends object ? R : {}) : {}) extends infer TRelations
             ? DistributiveOmit<TInput, keyof TRelations> & {
-                  [K in Extract<keyof TRelations, keyof T>]?: RelationUpdatePayload<T[K], TRelations[K], M, K>;
+                  [K in Extract<keyof TRelations, keyof T>]?: RelationPayload<T[K], TRelations[K], M, K>;
               }
             : never
         : never;
 
 
 type _Pk<T, Config> = WidenField<T[ExtractPkName<T, Config> extends keyof T ? ExtractPkName<T, Config> : never]>;
-type _Ret<M extends Prisma.ModelName, TSelects, S, TDefault> = ResolveCurrentReturn<M, TSelects, S, TDefault>;
+type _Ret<M extends Prisma.ModelName, TSelects, S, TDefault, IM = never, TIncludes = {}> = ResolveCurrentReturn<M, TSelects, S, TDefault, IM, TIncludes>;
 type _DS<Config, C, Method extends keyof NonNullable<BuildConfig['baseMethods']>, TSelects = ExtractSelectModels<Config>> =
     ResolveMethodDefaultSelect<Config, C, Method, TSelects>;
 type _Sel<Config> = ExtractSelectModels<Config>;
+type _Inc<Config> = ExtractIncludeModels<Config>;
 type _Def<Config> = ExtractDefaultSelect<Config>;
 type _Rel<Config> = ExtractRelations<Config>;
 type _Soft<Config> = ExtractSoftRemovekName<Config>;
@@ -660,59 +706,60 @@ type AllBaseMethods<
     TRelations = _Rel<Config>,
     TSoftKey  = _Soft<Config>,
     I         = PrismaModelInputs<M>,
-    TDefaultOrdenation = _DOrd<Config>
+    TDefaultOrdenation = _DOrd<Config>,
+    TIncludes = _Inc<Config>
 > = {
     /** Fetches a record by its primary key (PK). */
-    get: <S extends keyof TSelects | false = _DS<Config, C, 'get', TSelects>>(
-        pk: _Pk<T, Config>, options?: MethodOptions<S>
-    ) => Promise<_Ret<M, TSelects, S, TDefault> | null>;
+    get: <S extends keyof TSelects | false = _DS<Config, C, 'get', TSelects>, IM extends keyof TIncludes = 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>>(
-        pk: _Pk<T, Config>, options?: MethodOptions<S>
-    ) => Promise<_Ret<M, TSelects, S, TDefault>>;
+    getOrThrow: <S extends keyof TSelects | false = _DS<Config, C, 'getOrThrow', TSelects>, IM extends keyof TIncludes = 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>>(
-        pks: _Pk<T, Config>[], options?: MethodOptions<S>
-    ) => Promise<_Ret<M, TSelects, S, TDefault>[]>;
+    getList: <S extends keyof TSelects | false = _DS<Config, C, 'getList', TSelects>, IM extends keyof TIncludes = 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>>(
-        pk: _Pk<T, Config>, options?: MethodOptions<S>
-    ) => Promise<_Ret<M, TSelects, S, TDefault>>;
+    remove: <S extends keyof TSelects | false = _DS<Config, C, 'remove', TSelects>, IM extends keyof TIncludes = 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>>(
-        obj: UpsertWithRelations<T, M, TRelations>, options?: MethodOptions<S>
-    ) => Promise<_Ret<M, TSelects, S, TDefault>>;
+    save: <S extends keyof TSelects | false = _DS<Config, C, 'save', TSelects>, IM extends keyof TIncludes = 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>>(
-        objs: UpsertWithRelations<T, M, TRelations>[], options?: Omit<MethodOptions<S>, 'db'> & { db?: DbTransaction }
-    ) => Promise<_Ret<M, TSelects, S, TDefault>[]>;
+    saveList: <S extends keyof TSelects | false = _DS<Config, C, 'saveList', TSelects>, IM extends keyof TIncludes = never>(
+        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>>(
-        pk: _Pk<T, Config>, obj: UpdateWithRelations<T, M, TRelations>, options?: MethodOptions<S>
-    ) => Promise<_Ret<M, TSelects, S, TDefault>>;
+    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?: 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>>(
-        tuples: [pk: _Pk<T, Config>, obj: UpdateWithRelations<T, M, TRelations>][], options?: Omit<MethodOptions<S>, 'db'> & { db?: DbTransaction }
-    ) => Promise<_Ret<M, TSelects, S, TDefault>[]>;
+    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?: 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>>(
-        pk: _Pk<T, Config>, obj: UpdateWithRelations<T, M, TRelations>, options?: MethodOptions<S>
-    ) => Promise<_Ret<M, TSelects, S, TDefault> | null>;
+    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?: MethodOptionsWithInclude<S, IM, TIncludes>
+    ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes> | null>;
 
     /** Deletes multiple records by their primary keys. */
     removeList: (pks: _Pk<T, Config>[], options?: { db?: ClientOrTransaction }) => Promise<{ count: number }>;
 
     /** Fetches all records (respects `requiredWhere` when set). */
-    getAll: <S extends keyof TSelects | false = _DS<Config, C, 'getAll', TSelects>>(
-        options?: MethodOptions<S> & {
+    getAll: <S extends keyof TSelects | false = _DS<Config, C, 'getAll', TSelects>, IM extends keyof TIncludes = never>(
+        options?: MethodOptionsWithInclude<S, IM, TIncludes> & {
             pagination?: PaginationOptions<I extends { cursorInput: infer Curs } ? Curs : unknown>;
             /**
              * Ordering to apply to the query.
@@ -721,7 +768,7 @@ type AllBaseMethods<
              */
             order?: I extends { orderByInput: infer OB } ? OB : OrderOptions;
         }
-    ) => Promise<_Ret<M, TSelects, S, TDefault>[]>;
+    ) => Promise<_Ret<M, TSelects, S, TDefault, IM, TIncludes>[]>;
 
     /** Returns the total number of records. */
     total: (options?: { db?: ClientOrTransaction; see?: SeeMode }) => Promise<number>;
@@ -730,17 +777,17 @@ type AllBaseMethods<
     has: (pk: _Pk<T, Config>, options?: { db?: ClientOrTransaction; see?: SeeMode }) => Promise<boolean>;
 
     /** Marks a record as deleted (soft-delete). */
-    softRemove: <S extends keyof TSelects | false = _DS<Config, C, 'softRemove', TSelects>>(
-        pk: _Pk<T, Config>, options?: Omit<MethodOptions<S>, 'see'>
-    ) => Promise<_Ret<M, TSelects, S, TDefault>>;
+    softRemove: <S extends keyof TSelects | false = _DS<Config, C, 'softRemove', TSelects>, IM extends keyof TIncludes = 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. */
     softRemoveList: (pks: _Pk<T, Config>[], options?: { db?: ClientOrTransaction }) => Promise<{ count: number }>;
 
     /** Restores a record previously marked as deleted (soft-delete). */
-    restore: <S extends keyof TSelects | false = _DS<Config, C, 'restore', TSelects>>(
-        pk: _Pk<T, Config>, options?: Omit<MethodOptions<S>, 'see'>
-    ) => Promise<_Ret<M, TSelects, S, TDefault>>;
+    restore: <S extends keyof TSelects | false = _DS<Config, C, 'restore', TSelects>, IM extends keyof TIncludes = 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. */
     restoreList: (pks: _Pk<T, Config>[], options?: { db?: ClientOrTransaction }) => Promise<{ count: number }>;
@@ -757,9 +804,10 @@ type InjectedBaseMethods<
     TRelations = _Rel<Config>,
     TSoftKey  = _Soft<Config>,
     I         = PrismaModelInputs<M>,
-    TDefaultOrdenation = _DOrd<Config>
+    TDefaultOrdenation = _DOrd<Config>,
+    TIncludes = _Inc<Config>
 > = Pick<
-    AllBaseMethods<T, M, Config, C, TSelects, TDefault, TPk, TRelations, TSoftKey, I, TDefaultOrdenation>,
+    AllBaseMethods<T, M, Config, C, TSelects, TDefault, TPk, TRelations, TSoftKey, I, TDefaultOrdenation, TIncludes>,
     | (C extends { baseMethods: { get:          { active: false } } } ? never : 'get')
     | (C extends { baseMethods: { getOrThrow:   { active: false } } } ? never : 'getOrThrow')
     | (C extends { baseMethods: { getList:      { active: false } } } ? never : 'getList')
@@ -861,6 +909,7 @@ export type RepoConfig<T, M extends Prisma.ModelName, SM extends Record<string,
     softRemovekName?: keyof T & string;
     selectModels?: SM;
     defaultSelectModel?: Extract<keyof SM, string>;
+    includeModels?: IncludeModels<M>;
     requiredWhere?: WhereModel<M>;
     defaultOrdenation?: OrdenationModel<M>;
     relations?: RepositoryRelations<T>;
@@ -946,6 +995,12 @@ export type ValidateRepoConfig<T extends object, M extends Prisma.ModelName, Con
      */
     defaultSelectModel?: string;
 
+    /**
+     * Defines named and reusable include projections.
+     * Similar to selectModels, but resolves Prisma `include` clauses.
+     */
+    includeModels?: IncludeModels<M>;
+
     /**
      * Defines global filters that will be automatically applied to all repository queries.
      * Useful for tenant isolation (multi-tenancy) or base restrictions (e.g., `isActive: true`).

package/dist/VSRepository.js

@@ -35,6 +35,7 @@ class VSRepository {
     pkName;
     softRemovekName;
     selectModels;
+    includeModels;
     defaultSelectModel;
     requiredWhere;
     relations;
@@ -47,6 +48,7 @@ class VSRepository {
         this.pkName = validatedConfig.pkName;
         this.softRemovekName = validatedConfig.softRemovekName;
         this.selectModels = validatedConfig.selectModels;
+        this.includeModels = validatedConfig.includeModels;
         this.defaultSelectModel = validatedConfig.defaultSelectModel;
         this.relations = validatedConfig.relations;
         this.requiredWhere = validatedConfig.requiredWhere;
@@ -162,7 +164,7 @@ class VSRepository {
                         const missingParams = dinamicMethodInfo.whereParams
                             .concat(dinamicMethodInfo.otherParams)
                             .slice(args.length);
-                        throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${buildInstance.tableName}: runtime) Missing parameters: ${missingParams.join(", ")}`);
+                        throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${buildInstance.tableName}: runtime) Missing parameters: ${missingParams.join(", ")}`, "48670");
                     }
                     else if (args.length > dinamicMethodInfo.argsCount) {
                         const optionsArg = args[args.length - 1];

package/dist/internal/resolvers/base-methods.resolve.js

@@ -21,7 +21,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.get.active) {
         instance.get = async (pk, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.get,
@@ -41,7 +41,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.getOrThrow.active) {
         instance.getOrThrow = async (pk, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.getOrThrow,
@@ -64,7 +64,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.getList.active) {
         instance.getList = async (pks, options) => {
             if (!Array.isArray(pks) || pks.some(pk => pk == undefined))
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.getList,
@@ -84,7 +84,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.getAll.active) {
         instance.getAll = async (options) => {
             if (options !== undefined && !(0, is_object_validate_1.isObject)(options))
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'options' must be a valid object.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'options' must be a valid object.`, "65706");
             const { pagination, order, ...restOptions } = options ?? {};
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
@@ -107,7 +107,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.remove.active) {
         instance.remove = async (pk, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.remove,
@@ -127,7 +127,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.removeList.active) {
         instance.removeList = async (pks, options) => {
             if (!Array.isArray(pks) || pks.some(pk => pk == undefined))
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.removeList,
@@ -166,7 +166,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.has.active) {
         instance.has = async (pk, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.has,
@@ -187,9 +187,9 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.merge.active) {
         instance.merge = async (pk, obj, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             if (!(0, is_object_validate_1.isObject)(obj)) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'obj' must be a valid object.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'obj' must be a valid object.`, "65706");
             }
             (0, obj_with_relations_validate_1.validateObjWithRelations)(instance, obj, relationsKeys);
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
@@ -273,7 +273,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.softRemove.active && softRemovekName) {
         instance.softRemove = async (pk, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.softRemove,
@@ -295,7 +295,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.softRemoveList.active && softRemovekName) {
         instance.softRemoveList = async (pks, options) => {
             if (!Array.isArray(pks) || pks.some(pk => pk == undefined))
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.softRemoveList,
@@ -318,7 +318,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.restore.active && softRemovekName) {
         instance.restore = async (pk, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.restore,
@@ -340,7 +340,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.restoreList.active && softRemovekName) {
         instance.restoreList = async (pks, options) => {
             if (!Array.isArray(pks) || pks.some(pk => pk == undefined))
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pks' must an array of primary keys.`, "65706");
             const { db, prismaArgs } = (0, dbAndPrismaArgs_resolve_1.resolveDbAndPrismaArgs)({
                 instance,
                 baseConfig: baseMethods.restoreList,
@@ -363,7 +363,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.save.active) {
         instance.save = async (obj, options) => {
             if (!(0, is_object_validate_1.isObject)(obj)) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'obj' must be a valid object.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'obj' must be a valid object.`, "65706");
             }
             (0, obj_with_relations_validate_1.validateObjWithRelations)(instance, obj, relationsKeys);
             const objAny = obj;
@@ -407,7 +407,7 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.saveList.active) {
         instance.saveList = async (objs, options) => {
             if (!Array.isArray(objs) || objs.some(ob => !(0, is_object_validate_1.isObject)(ob))) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'objs' must be an array of valid objects.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'objs' must be an array of valid objects.`, "65706");
             }
             const validatedOptions = (0, method_options_validate_1.validateMethodOptions)(options, instance);
             const argsList = [];
@@ -466,9 +466,9 @@ function resolveBaseMethods(instance, config) {
     if (baseMethods.patch.active) {
         instance.patch = async (pk, obj, options) => {
             if (pk == undefined)
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'pk' must be provided.`, "65706");
             if (!(0, is_object_validate_1.isObject)(obj)) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'obj' must be a valid object.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'obj' must be a valid object.`, "65706");
             }
             (0, obj_with_relations_validate_1.validateObjWithRelations)(instance, obj, relationsKeys);
             const { updatePayload } = (0, create_update_payloads_with_relations_resolve_1.resolveCreateUpdatePayloadsWithRelations)(instance, obj, relationsKeys);
@@ -493,7 +493,7 @@ function resolveBaseMethods(instance, config) {
         instance.patchList = async (tuples, options) => {
             if (!Array.isArray(tuples) ||
                 tuples.some(tuple => tuple[0] == undefined || !(0, is_object_validate_1.isObject)(tuple[1]))) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'tuples' must be a valid array of tuples [pk, obj].`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${tableName}: runtime) 'tuples' must be a valid array of tuples [pk, obj].`, "65706");
             }
             const validatedOptions = (0, method_options_validate_1.validateMethodOptions)(options, instance);
             const argsList = [];

package/dist/internal/resolvers/dbAndPrismaArgs.resolve.js

@@ -6,7 +6,7 @@ const merge_wheres_resolve_1 = require("./merge-wheres.resolve");
 const select_resolve_1 = require("./select.resolve");
 function resolveDbAndPrismaArgs(data) {
     const { baseConfig, instance, options, wherePkValue, withoutSelect, withoutWhere, specificSelect, dataPayload, createPayload, updatePayload, alreadyValidatedOptions, specificWhere, pushWhere, ordenation, pagination, skipDuplicates, forceSeeMode, withOrdenationAndPagination, } = data;
-    const validatedOptions = (alreadyValidatedOptions && options)
+    const validatedOptions = alreadyValidatedOptions && options
         ? options
         : (0, method_options_validate_1.validateMethodOptions)(options, instance);
     const db = validatedOptions.db ?? instance.prisma;
@@ -18,9 +18,15 @@ function resolveDbAndPrismaArgs(data) {
         }, wherePkValue != undefined ? { [instance.pkName]: wherePkValue } : specificWhere, pushWhere, instance.requiredWhere, instance.softRemovekName);
     }
     if (!withoutSelect) {
-        prismaArgs.select =
-            specificSelect ??
-                (0, select_resolve_1.resolveSelect)(instance, validatedOptions.selectModel, baseConfig.defaultSelect);
+        if (specificSelect) {
+            prismaArgs.select = specificSelect;
+        }
+        else if (validatedOptions.includeModel) {
+            prismaArgs.include = instance.includeModels?.[validatedOptions.includeModel];
+        }
+        else {
+            prismaArgs.select = (0, select_resolve_1.resolveSelect)(instance, validatedOptions.selectModel, baseConfig.defaultSelect);
+        }
     }
     if (dataPayload) {
         prismaArgs.data = dataPayload;

package/dist/internal/validation/constructor-config.validate.js

@@ -14,6 +14,7 @@ function validateConstructorConfig(config) {
         pkName: schemas_util_1.stringSchema,
         softRemovekName: schemas_util_1.stringSchema.optional(),
         selectModels: zod_1.default.record(schemas_util_1.stringSchema, schemas_util_1.objectSchema).optional(),
+        includeModels: zod_1.default.record(schemas_util_1.stringSchema, schemas_util_1.objectSchema).optional(),
         defaultSelectModel: schemas_util_1.stringSchema.optional(),
         requiredWhere: schemas_util_1.objectSchema.optional(),
         relations: zod_1.default

package/dist/internal/validation/method-options.validate.js

@@ -8,19 +8,27 @@ const zod_1 = __importDefault(require("zod"));
 const schemas_util_1 = require("../utils/schemas.util");
 const vs_repo_error_1 = require("../errors/vs-repo.error");
 function validateMethodOptions(options, instance) {
-    const optionsSchema = zod_1.default.strictObject({
+    const optionsSchema = zod_1.default
+        .strictObject({
         db: schemas_util_1.objectSchema.optional(),
         selectModel: zod_1.default
             .literal(false)
             .or(zod_1.default.enum(Object.keys(instance.selectModels ?? {})))
             .optional(),
+        includeModel: zod_1.default.enum(Object.keys(instance.includeModels ?? {})).optional(),
         see: zod_1.default.enum(["active", "removed", "all"]).default("active"),
+    })
+        .refine(data => {
+        return !(data.selectModel !== undefined && data.includeModel !== undefined);
+    }, {
+        message: "cannot be provided with 'selectModel'.",
+        path: ["includeModel"],
     });
     const optionsParsed = optionsSchema.safeParse(options ?? {});
     if (!optionsParsed.success) {
         const firstIssue = optionsParsed.error.issues[0];
         const path = firstIssue?.path.length ? firstIssue.path.join(".") : "options";
-        throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) ${path}: ${firstIssue?.message}`);
+        throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) ${path}: ${firstIssue?.message}`, "67542");
     }
     return optionsParsed.data;
 }

package/dist/internal/validation/obj-with-relations.validate.js

@@ -14,23 +14,23 @@ function validateObjWithRelations(instance, obj, relationsKeys) {
         const relation = relations[key];
         if (relation.mode === "mtm" || relation.mode === "otm") {
             if (obj[key] === null) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' cannot be 'null' when relation mode is "mtm" or "otm", use an empty array instead.`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' cannot be 'null' when relation mode is "mtm" or "otm", use an empty array instead.`, "91868");
             }
             else if (!Array.isArray(obj[key]) || obj[key].some(val => !(0, is_object_validate_1.isObject)(val))) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' must be a valid array of objects when relation mode is "mtm" or "otm".`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' must be a valid array of objects when relation mode is "mtm" or "otm".`, "91868");
             }
         }
         else {
             if (obj[key] === null) {
                 if (relation.mode === "oto" && relation.restriction !== "set") {
-                    throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' can be 'null' only if the relation restriction is "set" and mode is "oto".`);
+                    throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' can be 'null' only if the relation restriction is "set" and mode is "oto".`, "91868");
                 }
                 else if (relation.mode === "mto" && !relation.nullable && !relation.nullAble) {
-                    throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' can be 'null' only if the relation 'nullable' is 'true' and mode is "mto".`);
+                    throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' can be 'null' only if the relation 'nullable' is 'true' and mode is "mto".`, "91868");
                 }
             }
             else if (!(0, is_object_validate_1.isObject)(obj[key])) {
-                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' must be a valid object when relation mode is "oto" or "mto".`);
+                throw new vs_repo_error_1.VSRepoRuntimeError(`[VSRepository] (${instance.tableName}: runtime) '${key}' must be a valid object when relation mode is "oto" or "mto".`, "91868");
             }
         }
     }

package/package.json

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