vsrepo 1.3.0 → 1.3.2

package/README.md

@@ -1,66 +1,70 @@
 # 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.
+Repository pattern library for projects using **Prisma**, with full **TypeScript** support and automatic **type inference**.
 
-O VSRepository permite criar repositories fortemente tipados com:
+VSRepository lets you create strongly-typed repositories with:
 
-- **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`
-- **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
+- Automatic **base methods**: `get`, `getOrThrow`, `getList`, `save`, `saveList`, `remove`, `removeList`, `patch`, `patchList`, `merge`, `getAll`, `total`, `has`
+- **Native soft-delete**: `softRemove`, `softRemoveList`, `restore`, `restoreList`
+- **Dynamic methods** inferred from their name: `findOneByEmail`, `findManyPaginated`, `updateById`, `deleteManyByNameStartsWith`
+- Reusable **select models** for different data projections
+- **Type safety** across 100% of operations
+- Native Prisma **transactions** (automatic in `saveList` and `patchList`)
+- **Extensibility** with custom methods
+
+> 💡 Want to see all of this in practice? The repository's [`examples/`](https://github.com/jaobrabo123/VSRepository/tree/main/examples) folder has commented, runnable examples for every feature — see the [Practical examples](#practical-examples) section below.
 
 ---
 
-## Sumário
+## Table of contents
 
-- [Instalação](#instalação)
-- [Gerando os tipos](#gerando-os-tipos)
-- [Uso básico](#uso-básico)
-- [Integração com NestJS](#integração-com-nestjs)
-- [Métodos base](#métodos-base)
+- [Installation](#installation)
+- [Generating the types](#generating-the-types)
+- [Basic usage](#basic-usage)
+- [NestJS integration](#nestjs-integration)
+- [Base methods](#base-methods)
   - [Soft-delete](#soft-delete)
-  - [Operações em lote](#operações-em-lote)
+  - [Batch operations](#batch-operations)
   - [Merge](#merge)
-  - [Configurando os métodos base](#configurando-os-métodos-base)
+  - [Configuring the base methods](#configuring-the-base-methods)
 - [Select Models](#select-models)
 - [Include Models](#include-models)
-- [Required Where](#requiredwhere)
+- [Required Where](#required-where)
 - [Default Ordenation](#default-ordenation)
-- [Opção `see`](#opção-see)
-- [Métodos dinâmicos](#métodos-dinâmicos)
-  - [Prefixos disponíveis](#prefixos-disponíveis)
-  - [Filtros de campo](#filtros-de-campo)
-  - [Operadores lógicos](#operadores-lógicos)
-  - [Filtros de relação](#filtros-de-relação)
-  - [Sufixos de paginação e ordenação](#sufixos-de-paginação-e-ordenação)
-  - [Configuração de métodos](#configuração-de-métodos)
-  - [Aggregate e GroupBy](#aggregate-e-groupby)
-- [Relações no save](#relações-no-save)
-- [Transações](#transações)
-- [Estendendo um repository](#estendendo-um-repository)
-- [Tratamento de erros](#tratamento-de-erros)
-- [Tipos utilitários](#tipos-utilitários)
+- [`see` option](#see-option)
+- [Dynamic methods](#dynamic-methods)
+  - [Available prefixes](#available-prefixes)
+  - [Field filters](#field-filters)
+  - [Logical operators](#logical-operators)
+  - [Relation filters](#relation-filters)
+  - [Pagination and ordering suffixes](#pagination-and-ordering-suffixes)
+  - [Distinct](#distinct)
+  - [Method configuration](#method-configuration)
+  - [Aggregate and GroupBy](#aggregate-and-groupby)
+- [Relations in save](#relations-in-save)
+- [Transactions](#transactions)
+- [Extending a repository](#extending-a-repository)
+- [Error handling](#error-handling)
+- [Utility types](#utility-types)
 - [API Reference](#api-reference)
-- [Contribuindo](#contribuindo)
-- [Requisitos](#requisitos)
+- [Practical examples](#practical-examples)
+- [Contributing](#contributing)
+- [Requirements](#requirements)
 - [Troubleshooting](#troubleshooting)
 
 ---
 
-## Instalação
+## Installation
 
 ```bash
 npm i vsrepo @prisma/client
 ```
 
-Gere o Prisma Client:
+Generate the Prisma Client:
 
 ```bash
 npx prisma generate
@@ -68,15 +72,15 @@ npx prisma generate
 
 ---
 
-## Gerando os tipos
+## Generating the types
 
-O VSRepository precisa conhecer o caminho real do seu Prisma Client para gerar as tipagens corretamente.
+VSRepository needs to know the real path of your Prisma Client to generate the typings correctly.
 
 ```bash
 npx vsrepo generate
 ```
 
-Equivale a:
+Equivalent to:
 
 ```bash
 npx vsrepo generate \
@@ -84,14 +88,14 @@ npx vsrepo generate \
   --prisma generated/prisma
 ```
 
-**Flags disponíveis:**
+**Available flags:**
 
-| Flag       | Alias | Padrão                 |
-| ---------- | ----- | ---------------------- |
-| `--output` | `-o`  | `generated/vsrepo` |
-| `--prisma` | `-p`  | `generated/prisma` |
+| Flag       | Alias | Default             |
+| ---------- | ----- | -------------------- |
+| `--output` | `-o`  | `generated/vsrepo`   |
+| `--prisma` | `-p`  | `generated/prisma`   |
 
-**Arquivos gerados:**
+**Generated files:**
 
 ```
 generated/vsrepo/
@@ -102,21 +106,21 @@ generated/vsrepo/
 └── index.ts
 ```
 
-Após gerar, importe sempre a partir da pasta gerada:
+After generating, always import from the generated folder:
 
 ```ts
-// CORRETO ✅
+// CORRECT ✅
 import { setupVSRepo } from "../../generated/vsrepo";
 
-// ERRADO ❌
+// WRONG ❌
 import { setupVSRepo } from "vsrepo";
 ```
 
 ---
 
-## Uso básico
+## Basic usage
 
-### Configurando o Prisma Client
+### Configuring the Prisma Client
 
 ```ts
 // src/configs/db.ts
@@ -130,59 +134,56 @@ const prisma = new PrismaClient({ adapter });
 export default prisma;
 ```
 
-### Criando um repository
+### Creating a repository
 
 ```ts
-// src/repositories/usuarioRepository.ts
+// src/repositories/userRepository.ts
 import prisma from "../configs/db";
 import { setupVSRepo } from "../../generated/vsrepo";
-import type { Usuario } from "../../generated/prisma/client";
+import type { User } from "../../generated/prisma/client";
 
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userRepository = setupVSRepo<User, "User">()(({
+  tableName: "user",
   pkName: "id",
   selectModels: {
-    public: { id: true, nome: true, email: true },
+    public: { id: true, name: true, email: true },
   },
   defaultSelectModel: "public",
-  requiredWhere: { ativo: true },
 }).build(prisma);
 
-export default usuarioRepository;
+export default userRepository;
 ```
 
-> `selectModels` e `requiredWhere` podem ser declarados fora do `setupVSRepo` se você precisar exportá-los para uso em outros arquivos.
-
-### Usando o repository
+### Using the repository
 
 ```ts
-import usuarioRepository from "./repositories/usuarioRepository";
+import userRepository from "./repositories/userRepository";
 
-const usuario = await usuarioRepository.save({
-  nome: "Joao",
-  email: "joao@email.com",
-  senha: "password",
+const user = await userRepository.save({
+  name: "John",
+  email: "john@email.com",
+  password: "password",
 });
 
-const encontrado = await usuarioRepository.get(usuario.id);
-const todos = await usuarioRepository.getAll();
+const found = await userRepository.get(user.id);
+const all = await userRepository.getAll();
 
-usuario.nome = "Joao Pedro";
+user.name = "John Smith";
 
-await usuarioRepository.save(usuario);
-await usuarioRepository.remove(usuario.id);
+await userRepository.save(user);
+await userRepository.remove(user.id);
 ```
 
 ---
 
-## Integração com NestJS
+## NestJS integration
 
-O VSRepository pode ser facilmente integrado em projetos NestJS através de providers. Abaixo está um exemplo completo usando o padrão de injeção de dependência do NestJS.
+VSRepository can be easily integrated into NestJS projects through providers. Below is a complete example using NestJS's dependency injection pattern.
 
-### Configurando o repository como provider
+### Configuring the repository as a provider
 
 ```ts
-// src/resources/user/user.repository.ts
+// src/modules/user/user.repository.ts
 import { Provider } from "@nestjs/common";
 import { PrismaService } from "../../database/prisma.service";
 import { UserGetPayload } from "../../../generated/prisma/models";
@@ -231,14 +232,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>;
+/* 
+The type can also be inferred using VSRepository's `RepositoryOf`, passing the `userVSRepo` type:
+
+export type UserRepository = RepositoryOf<typeof userVSRepo>;
+
+NOTE: If you use `.extend` to extend the repository or configure the base methods,
+using `ReturnType` is recommended since it's simpler to infer the type
+*/
 
 export const USER_REPOSITORY = Symbol("USER_REPOSITORY");
 
@@ -249,10 +254,10 @@ export const UserRepositoryProvider: Provider = {
 };
 ```
 
-### Registrando o provider no módulo
+### Registering the provider in the module
 
 ```ts
-// src/resources/user/user.module.ts
+// src/modules/user/user.module.ts
 import { Module } from "@nestjs/common";
 import { UserRepositoryProvider } from "./user.repository";
 import { UserService } from "./user.service";
@@ -267,12 +272,12 @@ import { UserController } from "./user.controller";
 export class UserModule {}
 ```
 
-### Utilizando o repository em um serviço
+### Using the repository in a service
 
 ```ts
-// src/resources/user/user.service.ts
+// src/modules/user/user.service.ts
 import { Injectable, Inject } from "@nestjs/common";
-import { USER_REPOSITORY, UserRepository } from "./user.repository";
+import { USER_REPOSITORY, type UserRepository } from "./user.repository";
 
 @Injectable()
 export class UserService {
@@ -299,134 +304,182 @@ export class UserService {
 }
 ```
 
-**Benefícios desta abordagem:**
+**Benefits of this approach:**
 
-- ✅ Type-safe repositories com injeção de dependência
-- ✅ Fácil de testar (mock do `USER_REPOSITORY`)
-- ✅ Isolamento da lógica de persistência
-- ✅ Reutilização do repository em múltiplos serviços
-- ✅ Suporte a transações via `PrismaService`
+- ✅ Type-safe repositories with dependency injection
+- ✅ Easy to test (mock the `USER_REPOSITORY`)
+- ✅ Isolation of persistence logic
+- ✅ Repository reuse across multiple services
+- ✅ Transaction support via `PrismaService`
 
 ---
 
-## Métodos base
+## Base methods
 
-Ao chamar `.build(prisma)` os métodos base abaixo são automaticamente disponibilizados:
+When calling `.build(prisma)`, the base methods below are automatically made available:
 
-| Método                   | Descrição                                                                                                   |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
-| `get(pk)`                | Busca um registro pela primary key                                                                          |
-| `getOrThrow(pk)`         | Busca um registro pela primary key; lança `VSRepoRuntimeError` (code `"20727"`) se não encontrado          |
-| `getList(pks)`           | Busca múltiplos registros por uma lista de primary keys                                                     |
-| `save(obj)`              | Cria ou atualiza — se o objeto tiver a `pk` faz `upsert`, caso contrário faz `create`                      |
-| `saveList(objs)`         | Salva um array de objetos em uma única transação automática                                                 |
-| `patch(pk, obj)`         | Atualiza parcialmente um registro pela primary key                                                          |
-| `patchList(tuples)`      | Atualiza parcialmente múltiplos registros via array de tuplas `[pk, obj]` em transação automática          |
-| `merge(pk, obj)`         | Busca um registro e faz um deep merge em memória — **não persiste**, retorna o objeto mesclado             |
-| `remove(pk)`             | Remove um registro pela primary key                                                                         |
-| `removeList(pks)`        | Remove vários registros pela lista de primary keys — retorna `{ count }`                                   |
-| `getAll()`               | Retorna todos os registros (aceita `pagination` e `order` no `options`)                                     |
-| `total()`                | Retorna o total de registros                                                                                |
-| `has(pk)`                | Verifica existência de um registro pela primary key — retorna `boolean`                                    |
+| Method                   | Description                                                                                                  |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------|
+| `get(pk)`                | Fetches a record by its primary key                                                                          |
+| `getOrThrow(pk)`         | Fetches a record by its primary key; throws `VSRepoRuntimeError` (code `"20727"`) if not found                |
+| `getList(pks)`           | Fetches multiple records from a list of primary keys                                                          |
+| `save(obj)`              | Creates or updates — if the object has a `pk` it performs an `upsert`, otherwise a `create`                  |
+| `saveList(objs)`         | Saves an array of objects in a single automatic transaction                                                   |
+| `patch(pk, obj)`         | Partially updates a record by its primary key                                                                 |
+| `patchList(tuples)`      | Partially updates multiple records via an array of `[pk, obj]` tuples in an automatic transaction             |
+| `merge(pk, obj)`         | Fetches a record and deep merges it in memory — **does not persist**, returns the merged object              |
+| `remove(pk)`             | Removes a record by its primary key                                                                           |
+| `removeList(pks)`        | Removes several records by a list of primary keys — returns `{ count }`                                       |
+| `getAll()`               | Returns all records (accepts `pagination` and `order` in `options`)                                           |
+| `total()`                | Returns the total number of records                                                                           |
+| `has(pk)`                | Checks whether a record exists by its primary key — returns `boolean`                                         |
 
-Todos aceitam `options` como último argumento.
+All of them accept `options` as the last argument.
 
 ### Soft-delete
 
-Quando `softRemovekName` está configurado no repository, os seguintes métodos adicionais ficam disponíveis:
+When `softRemovekName` is configured on the repository, the following additional methods become available:
 
-| Método                     | Descrição                                                                         |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| `softRemove(pk)`           | Marca um registro como removido preenchendo `softRemovekName` com a data atual    |
-| `softRemoveList(pks)`      | Marca múltiplos registros como removidos em lote — retorna `{ count }`            |
-| `restore(pk)`              | Restaura um registro soft-deletado, limpando o campo `softRemovekName`            |
-| `restoreList(pks)`         | Restaura múltiplos registros soft-deletados em lote — retorna `{ count }`         |
+| Method                     | Description                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------|
+| `softRemove(pk)`           | Marks a record as removed by filling `softRemovekName` with the current date       |
+| `softRemoveList(pks)`      | Marks multiple records as removed in batch — returns `{ count }`                    |
+| `restore(pk)`              | Restores a soft-deleted record, clearing the `softRemovekName` field                |
+| `restoreList(pks)`         | Restores multiple soft-deleted records in batch — returns `{ count }`               |
 
 ```ts
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userRepository = setupVSRepo<User, "user">()(({
+  tableName: "user",
   pkName: "id",
-  softRemovekName: "deletedAt", // deve ser um campo DateTime no schema do Prisma
+  softRemovekName: "deletedAt", // must be a DateTime field in the Prisma schema
 }).build(prisma);
 
-await usuarioRepository.softRemove(1);
-await usuarioRepository.restore(1);
+await userRepository.softRemove(1);
+await userRepository.restore(1);
 ```
 
-> O campo informado em `softRemovekName` **deve** ser do tipo `DateTime` no schema do Prisma. O VSRepository valida isso no momento do `build` e lança `VSRepoBuildError` se o tipo for incorreto.
+> The field provided in `softRemovekName` **must** be of type `DateTime` in the Prisma schema. VSRepository validates this at `build` time and throws `VSRepoBuildError` if the type is incorrect.
 
-### Operações em lote
+### Batch operations
 
-`saveList` e `patchList` executam todas as operações automaticamente dentro de uma única transação do Prisma. Se alguma falhar, todas as anteriores são revertidas.
+`saveList` and `patchList` automatically run all operations inside a single Prisma transaction. If any operation fails, all previous ones are rolled back.
 
 ```ts
-// 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" },
+// saveList — creates or updates multiple objects in an automatic transaction
+const users = await userRepository.saveList([
+  { name: "Mary", email: "mary@email.com" },
+  { id: 2, name: "John Updated", email: "john@email.com" },
 ]);
 
-// patchList — atualiza parcialmente múltiplos registros via tuplas [pk, obj]
-const atualizados = await usuarioRepository.patchList([
-  [1, { ativo: false }],
-  [2, { nome: "Novo Nome" }],
+// patchList — partially updates multiple records via [pk, obj] tuples
+const updated = await userRepository.patchList([
+  [1, { active: false }],
+  [2, { name: "New Name" }],
 ]);
 ```
 
-Quando você já está dentro de uma transação existente, passe-a em `options.db`. Nesse caso, o `db` deve ser um `DbTransaction` (não o cliente principal), pois o método não cria uma transação própria:
+When you're already inside an existing transaction, pass it in `options.db`. In this case, `db` must be a `DbTransaction` (not the main client):
 
 ```ts
 await prisma.$transaction(async (tx) => {
-  await usuarioRepository.saveList([{ nome: "Maria" }], { db: tx });
-  await usuarioRepository.patchList([[1, { ativo: false }]], { db: tx });
+  await userRepository.saveList([{ name: "Mary" }, { name: "Gus" }], { db: tx });
+  await userRepository.patchList([[1, { active: false }], [2, { active: true }]], { db: tx });
 });
 ```
 
 ### Merge
 
-O método `merge` busca um registro pela PK e mescla profundamente (`deepmerge`) o objeto fornecido com os dados existentes **em memória**. Ele **não persiste** as alterações — retorna o resultado mesclado para que você decida o que fazer com ele.
+The `merge` method fetches a record by its PK and deeply merges (`deepmerge`) the provided object with the existing data **in memory**. It **does not persist** the changes — it returns the merged result so you can decide what to do with it.
 
 ```ts
-const existente = await usuarioRepository.get(1);
-// existente: { id: 1, nome: "Maria", perfil: { bio: "Olá", idade: 25 } }
+const existing = await userRepository.get(1);
+// existing: { id: 1, name: "Mary", profile: { bio: "Hi", age: 25 } }
 
-const mesclado = await usuarioRepository.merge(1, {
-  perfil: { bio: "Bio atualizada" },
+const merged = await userRepository.merge(1, {
+  profile: { bio: "Updated bio" },
 });
-// mesclado: { id: 1, nome: "Maria", perfil: { bio: "Bio atualizada", idade: 25 } }
+// merged: { id: 1, name: "Mary", profile: { bio: "Updated bio", age: 25 } }
+
+// To persist, pass it to save or patch:
+await userRepository.save(merged);
+```
 
-// Para persistir, passe para save ou patch:
-await usuarioRepository.save(mesclado);
+Returns `null` if the record is not found.
+
+**Merging to-many relations (`otm`/`mtm`) is done by PK, not by simple concatenation.** For to-one relations (`oto`/`mto`), `merge` performs a regular deep merge of the object. For to-many relations, each item in the sent array is matched against the existing item that has the same PK (defined in `relations[key].pk`): if the PK matches, the two objects are merged together; if it doesn't match (a new item with no counterpart), it's simply added to the list. Existing items that don't appear in the sent array are kept.
+
+```ts
+const existing = await userRepository.get(1);
+// existing: {
+//   id: 1,
+//   posts: [
+//     { id: 10, title: "Post A", published: false },
+//     { id: 11, title: "Post B", published: true },
+//   ],
+// }
+
+const merged = await userRepository.merge(1, {
+  posts: [
+    { id: 10, published: true },  // same PK (id: 10) → merges with the existing item
+    { title: "Post C" },          // no PK → added as a new item
+  ],
+});
+// merged: {
+//   id: 1,
+//   posts: [
+//     { id: 10, title: "Post A", published: true },  // merged
+//     { id: 11, title: "Post B", published: true },  // kept, wasn't in the sent array
+//     { title: "Post C" },                            // added
+//   ],
+// }
 ```
 
-Retorna `null` se o registro não for encontrado.
+> Note that `merge` never removes items from a to-many relation — it only merges the ones that match by PK and adds the ones that don't. To remove items from a relation, use `save`/`patch` with `restriction: "set"` in the relation configuration.
+
+### Configuring the base methods
 
-### Configurando os métodos base
+The second argument of `.build(prisma, config)` lets you adjust the repository's global behavior and customize each base method individually through `baseMethods`.
 
 ```ts
-usuarioVSRepo.build(prisma, {
-  showWorking: true,  // Exibe logs do VSRepository no console, ótimo para debugar
+userVSRepo.build(prisma, {
+  // Shows VSRepository's internal logs on the console (built queries, detected prefix,
+  // applied filters, etc). Great for debugging dynamic methods. Default = false.
+  showWorking: true,
 
   baseMethods: {
     get: {
+      // Enables/disables the method on the final repository. If `false`, the method
+      // doesn't even appear in the repository's type (it's not just a runtime error). Default = true.
       active: true,
+
+      // Select model applied by default when the method is called without `options.selectModel`.
+      // Overrides the `defaultSelectModel` from setupVSRepo for this method only.
       defaultSelect: "public",
     },
     remove: {
       active: true,
       defaultSelect: "minimal",
+
+      // When `true`, ignores the `requiredWhere` configured in setupVSRepo for
+      // this specific method — useful when a method needs to "punch through" a
+      // global filter (e.g. multi-tenancy) in a specific case. Default = false.
       ignoreRequiredWhere: false,
     },
     save: {
+      // Here only `ignoreRequiredWhere` is set — `active` and `defaultSelect`
+      // keep their defaults (true and the global `defaultSelectModel`).
       ignoreRequiredWhere: true,
     },
     patch: {
+      // Only the select is overridden; the method stays active normally.
       defaultSelect: "minimal",
     },
     has: {
-      active: false, // Desativa o 'has' (padrão = true)
+      active: false, // Disables 'has' (default = true) — the method disappears from the repository
     },
     softRemove: {
+      // Soft-delete methods follow the same options (`active`, `defaultSelect`,
+      // `ignoreRequiredWhere`). They're only available if `softRemovekName` is configured.
       active: true,
       defaultSelect: "minimal",
     },
@@ -434,176 +487,176 @@ usuarioVSRepo.build(prisma, {
 });
 ```
 
+> Batch/aggregate methods like `removeList`, `softRemoveList`, `restoreList`, `total`, and `has` **do not** accept `defaultSelect` (they don't return a selectable record — they return `{ count }` or `boolean`). In these cases `BaseMethodConfig` is restricted to `active` and `ignoreRequiredWhere`.
+
 ---
 
 ## Select Models
 
-`selectModels` define projeções de dados nomeadas e reutilizáveis.
+`selectModels` defines named, reusable data projections.
 
 ```ts
 selectModels: {
-  public:   { id: true, nome: true, email: true },
-  internal: { id: true, nome: true, email: true, senha: true },
+  public:   { id: true, name: true, email: true },
+  internal: { id: true, name: true, email: true, password: true },
   minimal:  { id: true },
 },
 defaultSelectModel: "public",
 ```
 
-`defaultSelectModel` define qual select é usado automaticamente quando nenhum é especificado na chamada. É recomendado sempre definí-lo junto com `selectModels`.
+`defaultSelectModel` defines which select is used automatically when none is specified in the call. It's recommended to always define it together with `selectModels`.
 
-**Usando um select específico na chamada:**
+**Using a specific select in the call:**
 
 ```ts
-const usuario = await usuarioRepository.get(id, { selectModel: "minimal" });
+const user = await userRepository.get(id, { selectModel: "minimal" });
 ```
 
-**Retornando o payload padrão do Prisma (sem select):**
+**Returning Prisma's default payload (without select):**
 
 ```ts
-const usuarioCompleto = await usuarioRepository.get(id, { selectModel: false });
+const fullUser = await userRepository.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.
+`includeModels` works similarly to `selectModels`, but instead of receiving a `select`, it receives a valid Prisma `include`.
 
 ```ts
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userRepository = setupVSRepo<User, "user">()(({
+  tableName: "user",
   pkName: "id",
   selectModels: {
-    public: { id: true, nome: true, email: true },
+    public: { id: true, name: true, email: true },
   },
   defaultSelectModel: "public",
   includeModels: {
-    comPosts: { posts: true },
-    comPostsEPerfil: { posts: true, perfil: true },
+    withPosts: { posts: true },
+    withPostsAndProfile: { posts: true, profile: true },
   },
 }).build(prisma);
 ```
 
-**Usando um `includeModel` na chamada:**
+**Using an `includeModel` in the call:**
 
 ```ts
-const usuario = await usuarioRepository.get(id, { includeModel: "comPosts" });
+const user = await userRepository.get(id, { includeModel: "withPosts" });
 ```
 
-Nesse caso, o `select` padrão (`selectModels`/`defaultSelectModel`) é ignorado e apenas o `include` é enviado ao Prisma.
+In this case, the default `select` (`selectModels`/`defaultSelectModel`) is ignored and only the `include` is sent to Prisma.
 
-### Diferenças em relação ao `selectModels`
+### Differences from `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.
+- **Can only be passed in the method call**, via `options.includeModel`. There's no `defaultIncludeModel` or `defaultInclude` — there's no way to configure a default `includeModel` on the repository, unlike what happens with `defaultSelectModel`.
+- **`includeModel` and `selectModel` cannot be passed together** in the same call. If an `includeModel` is provided, any `selectModel` (including the default one) is ignored.
 
 ```ts
-// CORRETO ✅ — apenas includeModel
-await usuarioRepository.get(id, { includeModel: "comPosts" });
+// CORRECT ✅ — includeModel only
+await userRepository.get(id, { includeModel: "withPosts" });
 
-// CORRETO ✅ — apenas selectModel
-await usuarioRepository.get(id, { selectModel: "public" });
+// CORRECT ✅ — selectModel only
+await userRepository.get(id, { selectModel: "public" });
 
-// ERRADO ❌ — não é permitido combinar os dois
-await usuarioRepository.get(id, { selectModel: "public", includeModel: "comPosts" });
+// WRONG ❌ — combining both is not allowed
+await userRepository.get(id, { selectModel: "public", includeModel: "withPosts" });
 ```
 
 ---
 
 ## Required Where
 
-`requiredWhere` define filtros aplicados automaticamente em todas as queries do repository.
+`requiredWhere` defines filters that are automatically applied to every query on the repository.
 
 ```ts
-requiredWhere: { ativo: true },
+requiredWhere: { active: true },
 ```
 
-Agora toda query incluirá `ativo: true` automaticamente:
+Now every query will automatically include `active: true`:
 
 ```ts
-// Internamente: WHERE ativo = true
-const usuarios = await usuarioRepository.findMany();
+// Internally: WHERE active = true
+const users = await userRepository.findMany();
 
-// Internamente: WHERE email = 'joao@email.com' AND ativo = true
-const usuario = await usuarioRepository.findByEmail("joao@email.com");
+// Internally: WHERE email = 'john@email.com' AND active = true
+const user = await userRepository.findByEmail("john@email.com");
 ```
 
-Útil para soft-deletes manuais, multi-tenancy e filtros globais de qualquer natureza.
+Useful for manual soft-deletes, multi-tenancy, and global filters of any kind.
 
 ---
 
 ## Default Ordenation
 
-`defaultOrdenation` define uma ordenação padrão aplicada automaticamente em todas as queries que aceitam `orderBy`, sem precisar repetir o argumento `order` em cada chamada.
+`defaultOrdenation` defines a default ordering that's automatically applied to every query that accepts `orderBy`, without needing to repeat the `order` argument on every call.
 
 ```ts
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userRepository = setupVSRepo<User, "user">()(({
+  tableName: "user",
   pkName: "id",
-  defaultOrdenation: { criadoEm: "desc" },
+  defaultOrdenation: { createdAt: "desc" },
 }).build(prisma);
 ```
 
-Com isso, toda query de listagem já virá ordenada por `criadoEm` decrescente:
+With this, every listing query will already come ordered by `createdAt` descending:
 
 ```ts
-// Internamente: ORDER BY criadoEm DESC
-const usuarios = await usuarioRepository.getAll();
+// Internally: ORDER BY createdAt DESC
+const users = await userRepository.getAll();
 
-// Também aplica ao getAll com pagination
-const paginados = await usuarioRepository.getAll({ pagination: { take: 10 } });
+// Also applies to getAll with pagination
+const paginated = await userRepository.getAll({ pagination: { take: 10 } });
 ```
 
-**A `defaultOrdenation` é ignorada quando:**
+**`defaultOrdenation` is ignored when:**
 
-- O método usa o sufixo `Ordered`, `OrderedAndPaginated` ou `PaginatedAndOrdered` — nesses casos o argumento `order` passado na chamada tem prioridade.
-- O método dinâmico tem `injectOrdenation` configurado — a ordenação fixa do método prevalece.
+- The method uses the `Ordered`, `OrderedAndPaginated`, or `PaginatedAndOrdered` suffix — in these cases the `order` argument passed in the call takes priority.
+- The dynamic method has `injectOrdenation` configured — the method's fixed ordering takes precedence.
 
 ```ts
 methods: {
-  findManyPaginatedAndOrdered: { map: true },         // ordem vem do argumento → defaultOrdenation ignorada
-  findManyByAtivo:             { map: true },         // sem Ordered → defaultOrdenation aplicada
+  findManyPaginatedAndOrdered: { map: true },         // order comes from the argument → defaultOrdenation ignored
+  findManyByActive:            { map: true },         // no Ordered → defaultOrdenation applied
   findManyByStatus: {
     map: true,
-    injectOrdenation: { nome: "asc" },                // injectOrdenation → defaultOrdenation ignorada
+    injectOrdenation: { name: "asc" },                // injectOrdenation → defaultOrdenation ignored
   },
 }
 ```
 
-> `defaultOrdenation` aceita o mesmo tipo que o `orderBy` nativo do Prisma para o modelo — incluindo arrays de ordenações encadeadas.
+> `defaultOrdenation` accepts the same type as Prisma's native `orderBy` for the model — including arrays of chained orderings.
 
 ---
 
-Quando `softRemovekName` está configurado, todos os métodos base aceitam a opção `see` para controlar a visibilidade de registros soft-deletados:
+## `see` option
 
-| Valor       | Comportamento                                                 |
-| ----------- | ------------------------------------------------------------- |
-| `"active"`  | Retorna apenas registros **não** removidos (padrão)           |
-| `"removed"` | Retorna apenas registros removidos                            |
-| `"all"`     | Retorna todos os registros, independentemente do status       |
+When `softRemovekName` is configured, every method accepts the `see` option to control the visibility of soft-deleted records:
 
-```ts
-// Retorna apenas usuários ativos (padrão)
-const ativos = await usuarioRepository.getAll();
+| Value       | Behavior                                                     |
+| ----------- | --------------------------------------------------------------|
+| `"active"`  | Returns only records that are **not** removed (default)      |
+| `"removed"` | Returns only removed records                                  |
+| `"all"`     | Returns all records, regardless of status                     |
 
-// Retorna apenas usuários removidos
-const removidos = await usuarioRepository.getAll({ see: "removed" });
+```ts
+// Returns only active users (default)
+const active = await userRepository.getAll();
 
-// Retorna todos
-const todos = await usuarioRepository.getAll({ see: "all" });
+// Returns only removed users
+const removed = await userRepository.getAll({ see: "removed" });
 
-// Funciona em qualquer método base
-const usuario = await usuarioRepository.get(id, { see: "all" });
-const existe = await usuarioRepository.has(id, { see: "removed" });
+// Returns all
+const all = await userRepository.getAll({ see: "all" });
 ```
 
-> A opção `see` funciona independentemente do `requiredWhere` — ela é aplicada em cima do filtro de soft-delete, não o substitui.
+> The `see` option works independently of `requiredWhere` — it's applied on top of the soft-delete filter, not as a replacement for it.
 
 ---
 
-## Métodos dinâmicos
+## Dynamic methods
 
-Métodos dinâmicos são definidos na propriedade `methods` e têm seus comportamentos inferidos a partir do nome.
+Dynamic methods are defined in the `methods` property and have their behavior inferred from their name.
 
 ```ts
 methods: {
@@ -616,217 +669,358 @@ methods: {
 
 ---
 
-### Prefixos disponíveis
-
-O prefixo do nome do método determina qual operação Prisma será chamada e quais argumentos serão esperados.
-
-| Prefixo                    | Operação Prisma           | Retorno                | Observações                                                              |
-| -------------------------- | ------------------------- | ---------------------- | ------------------------------------------------------------------------ |
-| `findOneBy`                | `findFirst`               | `T \| null`            | Retorno único.                                                           |
-| `findBy`                   | `findMany` / `findFirst`  | `T[]` ou `T \| null`   | Padrão é lista; use `fbMode: "one"` para retorno único (**obsoleto**, use `findOneBy`)      |
-| `findUniqueBy`             | `findUnique`              | `T \| null`            |                                                                          |
-| `findUniqueOrThrowBy`      | `findUniqueOrThrow`       | `T`                    | Lança erro se não encontrar                                              |
-| `findFirstBy`              | `findFirst`               | `T \| null`            | Aceita campos como filtro                                                |
-| `findFirstOrThrowBy`       | `findFirstOrThrow`        | `T`                    | Aceita campos como filtro; lança erro se não encontrar                   |
-| `findFirst`                | `findFirst`               | `T \| null`            | Sem filtros de campo; aplica só `requiredWhere` e `pushWhere`            |
-| `findFirstOrThrow`         | `findFirstOrThrow`        | `T`                    | Sem filtros de campo; aplica só `requiredWhere` e `pushWhere`; lança erro se não encontrar |
-| `findManyBy`               | `findMany`                | `T[]`                  | Aceita campos como filtro                                                |
-| `findMany`                 | `findMany`                | `T[]`                  | Sem filtros de campo; aplica só `requiredWhere` e `pushWhere`            |
-| `findOneWhere`             | `findFirst`               | `T \| null`            | Recebe um objeto `where` explícito como argumento                        |
-| `findWhere`                | `findFirst`               | `T \| null`            | (**Obsoleto, use `findOneWhere`**) Recebe um objeto `where` explícito    |
-| `findListWhere`            | `findMany`                | `T[]`                  | Recebe um objeto `where` explícito como argumento                        |
-| `existsBy`                 | `findFirst`               | `boolean`              | Retorna `true` se encontrar, `false` caso contrário                      |
-| `existsWhere`              | `findFirst`               | `boolean`              | Recebe um objeto `where` explícito e retorna se existe                   |
-| `countBy`                  | `count`                   | `number`               | Aceita campos como filtro                                                |
-| `countWhere`               | `count`                   | `number`               | Recebe um objeto `where` explícito como argumento                        |
-| `count`                    | `count`                   | `number`               | Sem filtros de campo; aplica só `requiredWhere` e `pushWhere`            |
-| `create`                   | `create`                  | `T`                    | Recebe `data` como argumento                                             |
-| `createMany`               | `createMany`              | `{ count: number }`    | Recebe `data` como argumento; suporta `SkipDuplicates`                   |
-| `createManyAndReturn`      | `createManyAndReturn`     | `T[]`                  | Recebe `data` como argumento; suporta `SkipDuplicates`                   |
-| `updateBy`                 | `update`                  | `T`                    | Recebe `data` como argumento                                             |
-| `updateManyBy`             | `updateMany`              | `{ count: number }`    | Recebe `data` como argumento                                             |
-| `updateManyWhere`          | `updateMany`              | `{ count: number }`    | Recebe um objeto `where` e um objeto `data` como argumentos              |
-| `updateManyAndReturnBy`    | `updateManyAndReturn`     | `T[]`                  | Recebe `data` como argumento                                             |
-| `updateManyAndReturnWhere` | `updateManyAndReturn`     | `T[]`                  | Recebe um objeto `where` e um objeto `data` como argumentos              |
-| `upsertBy`                 | `upsert`                  | `T`                    | Recebe `update` e `create` como argumentos                               |
-| `deleteBy`                 | `delete`                  | `T`                    |                                                                          |
-| `deleteManyBy`             | `deleteMany`              | `{ count: number }`    |                                                                          |
-| `deleteManyWhere`          | `deleteMany`              | `{ count: number }`    | Recebe um objeto `where` explícito como argumento                        |
-| `aggregate`                | `aggregate`               | `Dinâmico`             | Nome deve ser exato; recebe args nativos do Prisma; ignora `selectModels`, `pushWhere` e `requiredWhere` |
-| `groupBy`                  | `groupBy`                 | `Dinâmico[]`           | Nome deve ser exato; recebe args nativos do Prisma; ignora `selectModels`, `pushWhere` e `requiredWhere` |
+### Available prefixes
+
+The method name's prefix determines which Prisma operation will be called and which arguments are expected.
+
+| Prefix                      | Prisma operation           | Return                  | Notes                                                                     |
+| ---------------------------- | -------------------------- | ------------------------ | ---------------------------------------------------------------------------|
+| `findOneBy`                 | `findFirst`                 | `T \| null`              | Single return.                                                             |
+| `findBy`                    | `findMany` / `findFirst`   | `T[]` or `T \| null`     | Default is list; use `fbMode: "one"` for a single return (**deprecated**, use `findOneBy`) |
+| `findUniqueBy`               | `findUnique`                | `T \| null`              |                                                                             |
+| `findUniqueOrThrowBy`        | `findUniqueOrThrow`         | `T`                       | Throws an error if not found                                               |
+| `findFirstBy`                | `findFirst`                 | `T \| null`              | Accepts fields as filter                                                   |
+| `findFirstOrThrowBy`         | `findFirstOrThrow`          | `T`                       | Accepts fields as filter; throws an error if not found                     |
+| `findFirst`                  | `findFirst`                 | `T \| null`              | No field filters; applies only `requiredWhere` and `pushWhere`             |
+| `findFirstOrThrow`           | `findFirstOrThrow`          | `T`                       | No field filters; applies only `requiredWhere` and `pushWhere`; throws an error if not found |
+| `findManyBy`                 | `findMany`                  | `T[]`                     | Accepts fields as filter                                                   |
+| `findMany`                   | `findMany`                  | `T[]`                     | No field filters; applies only `requiredWhere` and `pushWhere`             |
+| `findOneWhere`                | `findFirst`                 | `T \| null`              | Receives an explicit `where` object as argument                            |
+| `findListWhere`               | `findMany`                  | `T[]`                     | Receives an explicit `where` object as argument                            |
+| `existsBy`                    | `findFirst`                 | `boolean`                 | Returns `true` if found, `false` otherwise                                 |
+| `existsWhere`                 | `findFirst`                 | `boolean`                 | Receives an explicit `where` object and returns whether it exists          |
+| `countBy`                     | `count`                      | `number`                  | Accepts fields as filter                                                   |
+| `countWhere`                  | `count`                      | `number`                  | Receives an explicit `where` object as argument                            |
+| `count`                       | `count`                      | `number`                  | No field filters; applies only `requiredWhere` and `pushWhere`             |
+| `create`                      | `create`                     | `T`                        | Receives `data` as argument                                                |
+| `createMany`                  | `createMany`                 | `{ count: number }`       | Receives `data` as argument; supports `SkipDuplicates`                     |
+| `createManyAndReturn`         | `createManyAndReturn`        | `T[]`                      | Receives `data` as argument; supports `SkipDuplicates`                     |
+| `updateBy`                    | `update`                      | `T`                        | Receives `data` as argument                                                |
+| `updateManyBy`                | `updateMany`                  | `{ count: number }`       | Receives `data` as argument                                                |
+| `updateManyWhere`             | `updateMany`                  | `{ count: number }`       | Receives a `where` object and a `data` object as arguments                 |
+| `updateManyAndReturnBy`       | `updateManyAndReturn`         | `T[]`                      | Receives `data` as argument                                                |
+| `updateManyAndReturnWhere`    | `updateManyAndReturn`         | `T[]`                      | Receives a `where` object and a `data` object as arguments                 |
+| `upsertBy`                    | `upsert`                       | `T`                        | Receives `update` and `create` as arguments                                |
+| `deleteBy`                    | `delete`                       | `T`                        |                                                                             |
+| `deleteManyBy`                | `deleteMany`                   | `{ count: number }`       |                                                                             |
+| `deleteManyWhere`             | `deleteMany`                   | `{ count: number }`       | Receives an explicit `where` object as argument                            |
+| `aggregate`                   | `aggregate`                     | `Dynamic`                  | Name must be exact; receives native Prisma args; ignores `selectModels`, `pushWhere`, and `requiredWhere` |
+| `groupBy`                     | `groupBy`                       | `Dynamic[]`                | Name must be exact; receives native Prisma args; ignores `selectModels`, `pushWhere`, and `requiredWhere` |
 
 ---
 
-### Filtros de campo
-
-Os filtros são sufixos aplicados ao nome do campo dentro do método. O campo em si vem capitalizado logo após o prefixo (ou após `By`).
-
-| Sufixo             | Operador Prisma       | Argumento necessário      |
-| ------------------ | --------------------- | ------------------------- |
-| *(sem sufixo)*     | igualdade (`=`)       | sim                       |
-| `Not`              | `not`                 | sim                       |
-| `In`               | `in`                  | sim (array)               |
-| `NotIn`            | `notIn`               | sim (array)               |
-| `Contains`         | `contains`            | sim                       |
-| `NotContains`      | `not.contains`        | sim                       |
-| `StartsWith`       | `startsWith`          | sim                       |
-| `NotStartsWith`    | `not.startsWith`      | sim                       |
-| `EndsWith`         | `endsWith`            | sim                       |
-| `NotEndsWith`      | `not.endsWith`        | sim                       |
-| `GreaterThan`      | `gt`                  | sim                       |
-| `GreaterThanEqual` | `gte`                 | sim                       |
-| `LessThan`         | `lt`                  | sim                       |
-| `LessThanEqual`    | `lte`                 | sim                       |
-| `Between`          | `gte` + `lte`         | sim (tupla `[min, max]`)  |
-| `NotBetween`       | `not.gte` + `not.lte` | sim (tupla `[min, max]`)  |
-| `IsNull`           | `null`                | não                       |
-| `IsNotNull`        | `not: null`           | não                       |
-| `IsTrue`           | `true`                | não                       |
-| `IsFalse`          | `false`               | não                       |
-| `Insensitive`      | `mode: 'insensitive'` | combinador                |
-
-`Insensitive` é um combinador e pode ser usado junto com outro filtro de texto:
+### Field filters
+
+Filters are suffixes applied to the field name inside the method. The field itself comes capitalized right after the prefix (or after `By`).
+
+| Suffix              | Prisma operator       | Argument required          |
+| -------------------- | ---------------------- | ---------------------------|
+| *(no suffix)*        | equality (`=`)          | yes                        |
+| `Not`                | `not`                    | yes                        |
+| `In`                 | `in`                     | yes (array)                 |
+| `NotIn`              | `notIn`                  | yes (array)                 |
+| `Contains`           | `contains`               | yes                         |
+| `NotContains`        | `not.contains`           | yes                         |
+| `StartsWith`         | `startsWith`             | yes                         |
+| `NotStartsWith`      | `not.startsWith`         | yes                         |
+| `EndsWith`           | `endsWith`               | yes                         |
+| `NotEndsWith`        | `not.endsWith`           | yes                         |
+| `GreaterThan`        | `gt`                      | yes                         |
+| `GreaterThanEqual`   | `gte`                     | yes                         |
+| `LessThan`           | `lt`                      | yes                         |
+| `LessThanEqual`      | `lte`                     | yes                         |
+| `Between`            | `gte` + `lte`             | yes (tuple `[min, max]`)     |
+| `NotBetween`         | `not.gte` + `not.lte`     | yes (tuple `[min, max]`)     |
+| `IsNull`             | `null`                    | no                          |
+| `IsNotNull`          | `not: null`               | no                          |
+| `IsTrue`             | `true`                    | no                          |
+| `IsFalse`            | `false`                   | no                          |
+| `Insensitive`        | `mode: 'insensitive'`     | combinator                  |
+
+`Insensitive` is a combinator and can be used together with another text filter:
 
 ```ts
-findByNomeContainsInsensitive    // { nome: { contains: valor, mode: 'insensitive' } }
-findByEmailStartsWithInsensitive // { email: { startsWith: valor, mode: 'insensitive' } }
-findByNomeInsensitive            // { nome: { equals: valor, mode: 'insensitive' } }
+findByNameContainsInsensitive    // { name: { contains: value, mode: 'insensitive' } }
+findByEmailStartsWithInsensitive // { email: { startsWith: value, mode: 'insensitive' } }
+findByNameInsensitive            // { name: { equals: value, mode: 'insensitive' } }
 ```
 
-`Between` e `NotBetween` recebem uma **tupla `[minValue, maxValue]`**:
+`Between` and `NotBetween` receive a **tuple `[minValue, maxValue]`**:
 
 ```ts
 methods: {
-  findManyByIdadeBetween:      { map: true },
-  findManyBySalarioNotBetween: { map: true },
-  findManyByCriadoEmBetween:   { map: true },
+  findManyByAgeBetween:      { map: true },
+  findManyBySalaryNotBetween: { map: true },
+  findManyByCreatedAtBetween: { map: true },
 }
 
-await usuarioRepository.findManyByIdadeBetween([18, 65]);
-await usuarioRepository.findManyBySalarioNotBetween([1000, 5000]);
-await usuarioRepository.findManyByCriadoEmBetween([new Date("2024-01-01"), new Date("2024-12-31")]);
+await userRepository.findManyByAgeBetween([18, 65]);
+await userRepository.findManyBySalaryNotBetween([1000, 5000]);
+await userRepository.findManyByCreatedAtBetween([new Date("2024-01-01"), new Date("2024-12-31")]);
 ```
 
-O sufixo `Optional` pode ser adicionado a qualquer campo para tornar o argumento opcional:
+The `Optional` suffix can be added to any field to make the argument optional:
 
 ```ts
-findByNomeOptionalAndEmail // nome é opcional, email é obrigatório
+findByNameOptionalAndEmail // name is optional, email is required
 ```
 
 ---
 
-### Operadores lógicos
+### Logical operators
 
-| Operador  | Uso no nome                  | Exemplo                          |
-| --------- | ---------------------------- | -------------------------------- |
-| `And`     | entre dois campos            | `findOneByIdAndEmail`            |
-| `Or`      | entre dois campos            | `findByNomeOrEmail`              |
-| `AND`     | separa bloco final em `AND`  | `findByEmailOrNameANDActiveStatus` |
+| Operator  | Usage in the name             | Example                          |
+| --------- | ------------------------------ | -----------------------------------|
+| `And`     | between two fields              | `findOneByIdAndEmail`              |
+| `Or`      | between two fields              | `findByNameOrEmail`                |
+| `AND`     | separates a final `AND` block   | `findByEmailOrNameANDActiveStatus` |
 
-`AND` (em capslock) tem uma regra específica:
+`AND` (in caps) has a specific rule:
 
-- Só pode existir **um** `AND` por método.
-- Todos os campos depois de `AND` são injetados dentro de `AND: []`.
-- Depois de um `AND` não pode ter `Or`.
+- Only **one** `AND` can exist per method.
+- All fields after `AND` are injected inside `AND: []`.
+- After an `AND`, there can't be an `Or`.
 
-Exemplo:
+Example:
 
 ```ts
 methods: {
   findOneByIdAndEmail:   { map: true },
-  findByNomeOrEmail:  { map: true },
-  findUniqueByIdOrEmailAndNome: { map: true },
-  findByEmailOrNameANDActiveStatusAndIdadeGreaterThan: { map: true }
+  findByNameOrEmail:  { map: true },
+  findFirstByIdOrEmailAndName: { map: true },
+  findByEmailOrNameANDActiveStatusAndAgeGreaterThan: { 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.findByEmailOrNameANDActiveStatusAndIdadeGreaterThan("joao@email.com", "Joao", true, 17)
+await userRepository.findOneByIdAndEmail(1, "john@email.com");
+await userRepository.findByNameOrEmail("John", "john@email.com");
+await userRepository.findFirstByIdOrEmailAndName(1, "john@email.com", "John");
+await userRepository.findByEmailOrNameANDActiveStatusAndAgeGreaterThan("john@email.com", "John", true, 17)
+```
+
+Generates (`findOneByIdAndEmail`):
+
+```ts
+{
+  id: 1,
+  email: "john@email.com"
+}
 ```
 
-Gera (`findByEmailOrNameANDActiveStatusAndIdadeGreaterThan`):
+Generates (`findByNameOrEmail`):
 
 ```ts
 {
   OR: [
-    { email: "joao@email.com" },
-    { name: "Joao" }
+    { name: "John" },
+    { email: "john@email.com" }
+  ]
+}
+```
+
+Generates (`findFirstByIdOrEmailAndName`):
+
+```ts
+{
+  OR: [
+    { id: 1 },
+    {
+      email: "john@email.com",
+      name: "John"
+    }
+  ]
+}
+```
+
+Generates (`findByEmailOrNameANDActiveStatusAndAgeGreaterThan`):
+
+```ts
+{
+  OR: [
+    { email: "john@email.com" },
+    { name: "John" }
   ],
   AND: [
     { activeStatus: true },
-    { idade: { gt: 17 } }
+    { age: { gt: 17 } }
   ]
 }
 ```
 
 ---
 
-### Filtros de relação
+### Relation filters
 
-Permitem filtrar por campos de modelos relacionados.
+Allow filtering by fields of related models.
 
 > [!IMPORTANT]
-> - **Tipagem de relação**: Para que o TypeScript reconheça os tipos dos campos de relação nos métodos dinâmicos, o tipo genérico da entidade passado no `setupVSRepo` deve incluir as relações estruturadas (ex: usando `UsuarioGetPayload<{ include: { perfil: true, postagens: true } }>` do Prisma).
-> - **Compatibilidade de sufixos**:
->   - Os sufixos `Some`, `Every` e `None` só funcionam para relações **to-many** (`many-to-many` e `one-to-many`).
->   - Os sufixos `With` e `Without` só funcionam para relações **to-one** (`one-to-one` e `many-to-one`).
-
-| Sufixo de relação      | Operador Prisma | Observação                                         |
-| ---------------------- | --------------- | -------------------------------------------------- |
-| `Some`                 | `some: {}`      | Relação tem *algum* registro                       |
-| `SomeField`            | `some.field`    | Filtra dentro dos registros da relação             |
-| `EveryField`           | `every.field`   | Filtra dentro dos registros da relação             |
-| `None`                 | `none: {}`      | Relação não tem *nenhum* registro                  |
-| `NoneField`            | `none.field`    | Filtra dentro dos registros da relação             |
-| `With`                 | `is: {}`        | Relação existe (não é null)                        |
-| `WithField`            | `is.field`      | Filtra campo dentro da relação                     |
-| `Without`              | `isNot: {}`     | Relação não existe (é null)                        |
-| `WithoutField`         | `isNot.field`   | Filtra campo dentro da relação com negação         |
+> - **Relation typing**: For TypeScript to recognize the types of relation fields in dynamic methods, the generic entity type passed to `setupVSRepo` must include the structured relations (e.g. using Prisma's `UserGetPayload<{ include: { profile: true, posts: true } }>`).
+> - **Suffix compatibility**:
+>   - The `Some`, `Every`, and `None` suffixes only work for **to-many** relations (`many-to-many` and `one-to-many`).
+>   - The `With` and `Without` suffixes only work for **to-one** relations (`one-to-one` and `many-to-one`).
+
+| Relation suffix         | Prisma operator  | Note                                                  |
+| ------------------------ | ----------------- | -------------------------------------------------------|
+| `Some`                    | `some: {}`         | Relation has *some* record                             |
+| `SomeField`               | `some.field`       | Filters within the relation's records                  |
+| `EveryField`              | `every.field`      | Filters within the relation's records                  |
+| `None`                    | `none: {}`         | Relation has *no* records                               |
+| `NoneField`               | `none.field`       | Filters within the relation's records                  |
+| `With`                    | `is: {}`           | Relation exists (not null)                              |
+| `WithField`               | `is.field`         | Filters a field within the relation                     |
+| `Without`                 | `isNot: {}`        | Relation doesn't exist (is null)                        |
+| `WithoutField`            | `isNot.field`      | Filters a field within the relation with negation       |
+
+Considering `user` with a to-one relation `profile` and a to-many relation `posts`:
+
+```ts
+methods: {
+  // to-many (posts)
+  findByPostsSome:                { map: true }, // has at least one post
+  findByPostsSomeTitle:           { map: true }, // has at least one post with that title
+  findByPostsEveryPublishedIsTrue:{ map: true }, // all posts are published
+  findByPostsNone:                { map: true }, // has no posts
+  findByPostsNoneTitle:           { map: true }, // no post has that title
+
+  // to-one (profile)
+  findByProfileWith:             { map: true }, // has a profile (not null)
+  findByProfileWithBio:          { map: true }, // has a profile with that bio
+  findByProfileWithout:          { map: true }, // has no profile (is null)
+  findByProfileWithoutBio:       { map: true }, // has a profile, but with a different bio than the one provided
+}
+
+await userRepository.findByPostsSome();
+await userRepository.findByPostsSomeTitle("My first post");
+await userRepository.findByPostsEveryPublishedIsTrue();
+await userRepository.findByPostsNone();
+await userRepository.findByPostsNoneTitle("Draft");
+
+await userRepository.findByProfileWith();
+await userRepository.findByProfileWithBio("Hello, world!");
+await userRepository.findByProfileWithout();
+await userRepository.findByProfileWithoutBio("Old bio");
+```
+
+Generates (`findByPostsSomeTitle`):
+
+```ts
+{
+  posts: {
+    some: { title: "My first post" }
+  }
+}
+```
+
+Generates (`findByPostsEveryPublishedIsTrue`):
+
+```ts
+{
+  posts: {
+    every: { published: true }
+  }
+}
+```
+
+Generates (`findByProfileWithBio`):
+
+```ts
+{
+  profile: {
+    is: { bio: "Hello, world!" }
+  }
+}
+```
+
+Generates (`findByProfileWithout`):
+
+```ts
+{
+  profile: {
+    isNot: {}
+  }
+}
+```
+
+> `Some`, `None`, `With`, and `Without` (without a field) don't receive an argument — the whole relation is tested for the existence of records (`some`/`none`) or for being `null`/not `null` (`is`/`isNot`). The `SomeField`, `EveryField`, `NoneField`, `WithField`, and `WithoutField` variants receive the filtered field's value as an argument.
+
+---
+
+### Pagination and ordering suffixes
+
+Applied at the **end** of the method name, they automatically inject the pagination and ordering arguments.
+
+| Suffix                 | Additional arguments           |
+| ------------------------ | -------------------------------|
+| `Paginated`               | `(pagination)`                  |
+| `Ordered`                 | `(order)`                       |
+| `OrderedAndPaginated`     | `(order, pagination)`           |
+| `PaginatedAndOrdered`     | `(pagination, order)`           |
+
+For `createMany` and `createManyAndReturn`, the `SkipDuplicates` suffix is available:
+
+| Suffix              | Effect                                     |
+| --------------------- | ---------------------------------------------|
+| `SkipDuplicates`       | Skips duplicate records during insertion      |
 
 ---
 
-### Sufixos de paginação e ordenação
+### Distinct
+
+The `Distinct` suffix lets you get only unique records based on one or more fields, equivalent to Prisma's `distinct` option.
+
+To use it, put `Distinct` in the method name (after the field filters, if any) followed by the desired fields separated by `And`. The first character of each field must be uppercase, just like in regular field filters.
+
+```ts
+methods: {
+    // Returns unique users combining "age" and "role" (no field filter)
+    findManyDistinctAgeAndRole: { map: true },
+
+    // Distinct combined with the Paginated suffix
+    findManyDistinctNamePaginated: { map: true },
 
-Aplicados ao **final** do nome do método, eles injetam automaticamente os argumentos de paginação e ordenação.
+    // Distinct combined with a field filter (name) — filters by name and then applies distinct on role
+    findManyByNameDistinctRole: { map: true },
+},
+```
 
-| Sufixo                | Argumentos adicionais         |
-| --------------------- | ----------------------------- |
-| `Paginated`           | `(pagination)`                |
-| `Ordered`             | `(order)`                     |
-| `OrderedAndPaginated` | `(order, pagination)`         |
-| `PaginatedAndOrdered` | `(pagination, order)`         |
+```ts
+// No arguments: the distinct fields are already fixed in the method name
+await userRepository.findManyDistinctAgeAndRole();
+
+// The pagination argument still works normally
+await userRepository.findManyDistinctNamePaginated({ take: 10, skip: 0 });
+
+// The "name" field filter is still passed normally as an argument
+await userRepository.findManyByNameDistinctRole("John");
+```
 
-Para `createMany` e `createManyAndReturn`, o sufixo `SkipDuplicates` está disponível:
+> The fields specified after `Distinct` are resolved from the method name at build time — they **don't** become runtime arguments, unlike regular field filters.
 
-| Sufixo            | Efeito                                   |
-| ----------------- | ---------------------------------------- |
-| `SkipDuplicates`  | Ignora registros duplicados na inserção  |
+`Distinct` is available on prefixes that read multiple or single records: `findMany`, `findManyBy`, `findFirst`, `findFirstBy`, `findFirstOrThrow`, `findFirstOrThrowBy`, `findBy`, `findOneBy`, `findWhere`, `findOneWhere`, `findListWhere`, `existsBy`, and `existsWhere`.
 
 ---
 
-### Configuração de métodos
+### Method configuration
 
-Cada entrada em `methods` aceita as seguintes opções:
+Each entry in `methods` accepts the following options:
 
-| Opção               | Tipo                            | Padrão       | Descrição                                                                                                    |
-| ------------------- | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
-| `map`               | `boolean`                       | —            | **Obrigatório.** Define se o método será exposto no repository.                                             |
-| `whereType`         | `'extending'` \| `'overwrite'`  | `extending`  | `extending` combina com `requiredWhere`. `overwrite` ignora o `requiredWhere`.                               |
-| `selectModel`       | `keyof SelectModels \| false`   | —            | Sobrescreve o `defaultSelectModel` para este método.                                                        |
-| `fbMode`            | `'one'` \| `'list'`             | `'list'`     | (**Obsoleto. Use `findOneBy`**) Somente para `findBy`. `'one'` retorna `T \| null`; `'list'` retorna `T[]`. |
-| `proxyTo`           | `Padrão de método válido`       | —            | Delega a lógica para outro padrão de método válido.                                                         |
-| `pushWhere`         | `WhereModel<M>`                 | —            | Where extra adicionado à query além do `requiredWhere`.                                                     |
-| `injectOrdenation`  | `OrdenationModel<M>`            | —            | Ordenação fixa injetada automaticamente na query.                                                           |
-| `injectPagination`  | `PaginationModel<M>`            | —            | Paginação fixa injetada automaticamente na query.                                                           |
+| Option               | Type                             | Default       | Description                                                                                                     |
+| --------------------- | --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------|
+| `map`                 | `boolean`                          | —              | **Required.** Defines whether the method will be exposed on the repository.                                       |
+| `whereType`           | `'extending'` \| `'overwrite'`    | `extending`    | `extending` combines with `requiredWhere`. `overwrite` ignores `requiredWhere`.                                    |
+| `selectModel`         | `keyof SelectModels \| false`     | —              | Overrides `defaultSelectModel` for this method.                                                                    |
+| `fbMode`              | `'one'` \| `'list'`                | `'list'`       | (**Deprecated. Use `findOneBy`**) Only for `findBy`. `'one'` returns `T \| null`; `'list'` returns `T[]`.          |
+| `proxyTo`             | `Valid method pattern`             | —              | Delegates the logic to another valid method pattern.                                                               |
+| `pushWhere`           | `WhereModel<M>`                    | —              | Extra `where` added to the query in addition to `requiredWhere`.                                                   |
+| `injectOrdenation`    | `OrdenationModel<M>`               | —              | Fixed ordering automatically injected into the query.                                                              |
+| `injectPagination`    | `PaginationModel<M>`               | —              | Fixed pagination automatically injected into the query.                                                            |
 
 ---
 
-### Aggregate e GroupBy
+### Aggregate and GroupBy
 
 ```ts
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userRepository = setupVSRepo<User, "user">()(({
+  tableName: "user",
   pkName: "id",
   methods: {
     aggregate: { map: true },
@@ -836,33 +1030,33 @@ const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
 ```
 
 > [!NOTE]
-> Estes métodos devem ter exatamente esses nomes (`aggregate` e `groupBy`).
-> Ao contrário dos outros métodos dinâmicos, eles recebem argumentos nativos do Prisma e **ignoram** as configurações de `selectModels`, `pushWhere` e `requiredWhere`.
+> These methods must have exactly these names (`aggregate` and `groupBy`).
+> Unlike the other dynamic methods, they receive native Prisma arguments and **ignore** the `selectModels`, `pushWhere`, and `requiredWhere` configurations.
 
 ---
 
-## Relações no save
+## Relations in save
 
-Configure relações para que o `save` e o `patch` as gerenciem automaticamente (`saveList` e `pacthList` também gerenciam as relations automaticamente).
+Configure relations so that `save` and `patch` manage them automatically (`saveList` and `patchList` also manage relations automatically).
 
 ```ts
 import type { Prisma } from "../../generated/prisma/client";
 
-type Usuario = Prisma.usuarioGetPayload<{
-  include: { perfil: true; postagens: true };
+type User = Prisma.userGetPayload<{
+  include: { profile: true; posts: true };
 }>;
 
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userRepository = setupVSRepo<User, "user">()(({
+  tableName: "user",
   pkName: "id",
 
   relations: {
-    perfil: {
+    profile: {
       pk: "id",
       mode: "oto",
       restriction: "set",
     },
-    postagens: {
+    posts: {
       pk: "id",
       mode: "otm",
       restriction: "add",
@@ -871,78 +1065,92 @@ const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
 }).build(prisma);
 ```
 
-**Modos de relação:**
+**Relation modes:**
 
-| Modo  | Relação      |
-| ----- | ------------ |
-| `oto` | one-to-one   |
-| `otm` | one-to-many  |
-| `mto` | many-to-one  |
-| `mtm` | many-to-many |
+| Mode  | Relation      |
+| ----- | -------------- |
+| `oto` | one-to-one     |
+| `otm` | one-to-many    |
+| `mto` | many-to-one    |
+| `mtm` | many-to-many   |
 
-**Restrições:**
+**Restrictions:**
 
-| Restrição | Comportamento no update                                     |
-| --------- | ----------------------------------------------------------- |
-| `set`     | Substitui completamente (remove os que não foram enviados)  |
-| `add`     | Adiciona/atualiza sem remover os existentes                 |
+| Restriction | Behavior on update                                             |
+| ------------ | ----------------------------------------------------------------|
+| `set`         | Fully replaces (removes the ones that weren't sent)             |
+| `add`         | Adds/updates without removing existing ones                      |
 
-**Relação `mto` com nullable:**
+> [!WARNING]
+> **`set` means different things depending on the relation's `mode` — and this can cause data loss if you're not careful.**
+>
+> In relations where the related record **belongs** to the parent record (`oto` and `otm`), "removing the ones that weren't sent" means **deleting the record from the database** (`delete`/`deleteMany`). In relations where the related record is **independent** (`mto` and `mtm`), "removing" just means **unlinking** (`disconnect`/`set: []`) — the related record continues to exist in the database, it just stops pointing to the parent (or being in the join table).
+>
+> | Mode  | `restriction: "set"` when an item is omitted | Does the item continue to exist in the database? |
+> | ----- | ------------------------------------------------ | -----------------------------------------------------|
+> | `oto` | Passing `null` in the field → **deletes** the related record (`delete: true`) | No |
+> | `otm` | Items outside the sent list → **deleted** (`deleteMany` with `notIn`)          | No |
+> | `mto` | Passing `null` in the field (with `nullable: true`) → **unlinks** (`disconnect: true`) | Yes |
+> | `mtm` | Items outside the sent list → **unlinked** from the join table (`set: []`)     | Yes |
+>
+> Practical example: if `posts` is `otm` with `restriction: "set"`, a `save`/`patch` that sends the user with only 2 of the 5 existing posts will **delete the other 3 posts from the database**, not just unlink them from the user. If the expected behavior is just to unlink without deleting, use `restriction: "add"` (which never removes anything) and handle removal manually.
 
-Use `nullable` (letra minúscula) para permitir a desvinculação de uma relação many-to-one:
+**`mto` relation with nullable:**
+
+Use `nullable` (lowercase) to allow unlinking a many-to-one relation:
 
 ```ts
 relations: {
-  categoria: {
+  category: {
     pk: "id",
     mode: "mto",
     restriction: "set",
-    nullable: true, // permite passar null para desvincular
+    nullable: true, // allows passing null to unlink
   },
 }
 ```
 
-> **Nota:** `nullAble` (com A maiúsculo) ainda é aceito por compatibilidade, mas está **obsoleto**. Prefira `nullable`.
-
 ---
 
-## Transações
+## Transactions
 
-Todos os métodos aceitam `options.db` para participar de uma transação:
+All methods accept `options.db` to participate in a transaction:
 
 ```ts
-await usuarioRepository.prisma.$transaction(async (tx) => {
-  const usuario = await usuarioRepository.save(
-    { nome: "Maria", email: "maria@email.com", senha: "password" },
+await userRepository.prisma.$transaction(async (tx) => {
+  const user = await userRepository.save(
+    { name: "Mary", email: "mary@email.com", password: "password" },
     { db: tx }
   );
 
-  await usuarioLogsRepository.save(
-    { acao: "Cadastro de usuário", data: { usuarioCadastrado: usuario.id } },
+  await userLogsRepository.save(
+    { action: "User registration", data: { registeredUser: user.id } },
     { db: tx }
   );
 });
 ```
 
-Para `saveList` e `patchList`, o campo `db` deve ser um `DbTransaction` (não o cliente principal):
+For `saveList` and `patchList`, the `db` field must be a `DbTransaction`:
 
 ```ts
 await prisma.$transaction(async (tx) => {
-  // CORRETO: tx é uma DbTransaction
-  await usuarioRepository.saveList([{ nome: "Maria" }], { db: tx });
+  // CORRECT: tx is a DbTransaction
+  const registeredUsers = await userRepository.saveList([{ name: "Mary" }, { name: "Lucas" }], { db: tx });
 
-  // ERRADO: não passe o prisma diretamente
-  // await usuarioRepository.saveList([{ nome: "Maria" }], { db: prisma });
+  await userLogsRepository.save(
+    { action: "User registration", data: { registeredUsers: registeredUsers.map(u => u.id) } },
+    { db: tx }
+  );
 });
 ```
 
 ---
 
-## Estendendo um repository
+## Extending a repository
 
 ```ts
-const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userRepository = setupVSRepo<User, "user">()(({
+  tableName: "user",
   pkName: "id",
   methods: {
     findOneByEmailEndsWith: { map: true },
@@ -950,52 +1158,54 @@ const usuarioRepository = setupVSRepo<Usuario, "usuario">()(({
 })
   .build(prisma)
   .extend((repo) => ({
-    buscarAtivosPorDominio: async (dominio: string) => {
-      return repo.findOneByEmailEndsWith(`@${dominio}`);
+    findActiveByDomain: async (domain: string) => {
+      return repo.findOneByEmailEndsWith(`@${domain}`);
     },
 
-    ativarMultiplos: async (ids: string[]) => {
-      return repo.patchList(ids.map(id => [id, { ativo: true }]));
+    activateMultiple: async (ids: string[]) => {
+      return repo.patchList(ids.map(id => [id, { active: true }]));
     },
   }));
 ```
 
 ---
 
-## Tratamento de erros
+## Error handling
 
-O VSRepository lança `VSRepoError` e suas subclasses em situações específicas (erros do Prisma não são sobrescritos):
+VSRepository throws `VSRepoError` and its subclasses in specific situations (Prisma errors are not overridden):
 
 ```ts
 import { VSRepoError, VSRepoRuntimeError } from "../../generated/vsrepo";
 
 try {
-  const usuario = await usuarioRepository.getOrThrow(id);
+  const user = await userRepository.getOrThrow("id-that-does-not-exist");
 } catch (error) {
   if (error instanceof VSRepoRuntimeError && error.code === "20727") {
-    // Registro não encontrado pelo getOrThrow
+    console.error("Record not found");
   } else if (error instanceof VSRepoError) {
-    console.error("Erro no repository:", error.message);
+    console.error("Repository error:", error.message);
+  } else {
+    console.error("Error:", error.message)
   }
 }
 ```
 
-**Subclasses disponíveis:**
+**Available subclasses:**
 
-| Classe               | Quando é lançada                                                  |
-| -------------------- | ----------------------------------------------------------------- |
-| `VSRepoConfigError`  | Configuração inválida em `setupVSRepo`                            |
-| `VSRepoBuildError`   | Nome de método, tipo de campo ou configuração inválida no `build` |
-| `VSRepoExtendError`  | Argumento inválido em `extend`                                    |
-| `VSRepoRuntimeError` | Erro em tempo de execução durante uma operação                    |
+| Class                 | When it's thrown                                                    |
+| ---------------------- | ------------------------------------------------------------------------|
+| `VSRepoConfigError`     | Invalid configuration in `setupVSRepo`                                   |
+| `VSRepoBuildError`      | Invalid method name, field type, or configuration in `build`             |
+| `VSRepoExtendError`     | Invalid argument in `extend`                                             |
+| `VSRepoRuntimeError`    | Runtime error during an operation                                        |
 
-`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` has a `code` property for programmatic identification. Code `"20727"` is thrown by `getOrThrow` when the record is not found, for example.
 
 ---
 
-## Tipos utilitários
+## Utility types
 
-### Tipos de cliente
+### Client types
 
 ```ts
 import type { DbClient, DbTransaction, ClientOrTransaction } from "../../generated/vsrepo";
@@ -1005,7 +1215,7 @@ type DbTransaction       = Prisma.TransactionClient;
 type ClientOrTransaction = DbClient | DbTransaction;
 ```
 
-### Tipo de visibilidade soft-delete
+### Soft-delete visibility type
 
 ```ts
 import type { SeeMode } from "../../generated/vsrepo";
@@ -1013,7 +1223,7 @@ import type { SeeMode } from "../../generated/vsrepo";
 type SeeMode = "active" | "removed" | "all";
 ```
 
-### Tipos derivados do modelo Prisma
+### Types derived from the Prisma model
 
 ```ts
 import type {
@@ -1029,22 +1239,22 @@ import type {
 } from "../../generated/vsrepo";
 ```
 
-### Tipos de opções de método
+### Method options types
 
 ```ts
 import type { MethodOptions, MethodOptionsModel } from "../../generated/vsrepo";
 
-// MethodOptions<S, IM> — opções passadas nos métodos do repository
-type Opts = MethodOptions<"public" | "minimal", "comPosts">;
+// MethodOptions<S, IM> — options passed into the repository's methods
+type Opts = MethodOptions<"public" | "minimal", "withPosts">;
 
-// MethodOptionsModel<TRepo> — derivado de uma instância VSRepository configurada
-const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()(config);
-type OptsModel = MethodOptionsModel<typeof usuarioVSRepo>;
+// MethodOptionsModel<TRepo> — derived from a configured VSRepository instance
+const userVSRepo = setupVSRepo<User, "user">()(config);
+type OptsModel = MethodOptionsModel<typeof userVSRepo>;
 ```
 
-> 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.
+> The second parameter of `MethodOptions` (`IM`) represents the valid keys of `includeModels`. When provided, `selectModel` and `includeModel` become mutually exclusive in the type — it's not possible to pass both in the same call.
 
-### Tipos de configuração
+### Configuration types
 
 ```ts
 import type {
@@ -1056,36 +1266,36 @@ import type {
 } from "../../generated/vsrepo";
 ```
 
-### Tipo do repository construído
+### Built repository type
 
 ```ts
 import type { RepositoryOf } from "../../generated/vsrepo";
 
-const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({ ... });
-type UsuarioRepository = RepositoryOf<typeof usuarioVSRepo>;
+const userVSRepo = setupVSRepo<User, "user">()({ ... });
+type UserRepository = RepositoryOf<typeof userVSRepo>;
 ```
 
-`RepositoryOf` aceita três parâmetros:
+`RepositoryOf` accepts three parameters:
 
 ```ts
 type RepositoryOf<TRepo, C extends BuildConfig | undefined = undefined, E = unknown>
 ```
 
-### Tipos do payload de `save` e `patch`
+### `save` and `patch` payload types
 
 ```ts
 import type { SaveObject, PatchObject } from "../../generated/vsrepo";
 
-const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()(({
-  tableName: "usuario",
+const userVSRepo = setupVSRepo<User, "user">()(({
+  tableName: "user",
   pkName: "id",
   relations: {
-    perfil: { pk: "id", mode: "oto", restriction: "set" },
+    profile: { pk: "id", mode: "oto", restriction: "set" },
   },
 });
 
-type UsuarioSavePayload  = SaveObject<Prisma.UsuarioCreateInput, typeof usuarioVSRepo>;
-type UsuarioPatchPayload = PatchObject<Prisma.UsuarioUpdateInput, typeof usuarioVSRepo>;
+type UserSavePayload  = SaveObject<Prisma.UserCreateInput, typeof userVSRepo>;
+type UserPatchPayload = PatchObject<Prisma.UserUpdateInput, typeof userVSRepo>;
 ```
 
 ---
@@ -1096,16 +1306,16 @@ type UsuarioPatchPayload = PatchObject<Prisma.UsuarioUpdateInput, typeof usuario
 
 ```ts
 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 (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
-  methods?: Record<string, MethodConfig<M, SM>>;  // Métodos dinâmicos
+  tableName: Uncapitalize<M>;                     // Table name in Prisma
+  pkName: keyof T;                                // Primary key name
+  softRemovekName?: keyof T & string;             // DateTime field for soft-delete
+  selectModels?: SelectModels<M>;                 // Named data projections (select)
+  defaultSelectModel?: keyof SM;                  // Select applied by default
+  includeModels?: IncludeModels<M>;               // Named data projections (include) — no default, only in the call
+  requiredWhere?: WhereModel<M>;                  // Always-applied filters
+  defaultOrdenation?: OrdenationModel<M>;         // Default ordering for queries without Ordered/injectOrdenation
+  relations?: RepositoryRelations<T>;             // Relation configuration
+  methods?: Record<string, MethodConfig<M, SM>>;  // Dynamic methods
 });
 ```
 
@@ -1113,10 +1323,10 @@ setupVSRepo<TPayload, TTableName>()({
 
 ```ts
 vsRepo.build(prisma, {
-  showWorking?: boolean;   // Exibe logs internos no console (default = false)
+  showWorking?: boolean;   // Shows internal logs on the console (default = false)
 
   baseMethods?: {
-    // Métodos que podem utilizar um defaultSelect
+    // Methods that can use a defaultSelect
     get?:             { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
     getOrThrow?:      { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
     getList?:         { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
@@ -1130,7 +1340,7 @@ vsRepo.build(prisma, {
     softRemove?:      { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
     restore?:         { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
 
-    // Métodos que NÃO aceitam defaultSelect
+    // Methods that do NOT accept defaultSelect
     removeList?:      { active?: boolean; ignoreRequiredWhere?: boolean };
     softRemoveList?:  { active?: boolean; ignoreRequiredWhere?: boolean };
     restoreList?:     { active?: boolean; ignoreRequiredWhere?: boolean };
@@ -1144,33 +1354,55 @@ vsRepo.build(prisma, {
 
 ```ts
 repo.extend((repo) => ({
-  meuMetodo: () => { ... }
+  myMethod: () => { ... }
 }));
 ```
 
 ---
 
-## Contribuindo
+## Practical examples
 
-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)**):
+Besides this README, the repository has an **[`examples/`](https://github.com/jaobrabo123/VSRepository/tree/main/examples)** folder with practical, commented, ready-to-run examples — it's the best place to see VSRepository being used in real scenarios.
 
-1. Faça um **Fork** do projeto.
-2. Crie uma nova branch com a sua alteração: `git checkout -b corrigindo-bug`.
-3. Faça o push para a sua branch: `git push origin corrigindo-bug`.
-4. Abra um **Pull Request**.
+```
+examples/
+├── prisma.ts             # PrismaClient instance used by the examples
+├── repositories.ts       # Repository configuration (User, Address, Product) with setupVSRepo
+└── tests/
+    ├── base-methods.test.ts       # Base methods: get, save, patch, remove, getAll, total, has...
+    ├── relations.test.ts          # How to configure and use relations in save/patch and in filters
+    ├── required-where.test.ts     # How requiredWhere is automatically applied to queries
+    ├── dynamic-methods.test.ts    # Prefixes, field filters, logical operators, and pagination/ordering
+    ├── transactions.test.ts       # Transactions with options.db and instance access via repository.prisma
+    ├── soft-delete.test.ts        # Soft-delete: softRemove, softRemoveList, restore, restoreList and SeeMode
+    └── batch-methods.test.ts      # Batch operations: getList, saveList, patchList and merge
+```
 
-Para reportar problemas ou sugerir novas funcionalidades, abra uma **Issue**.
+Each file in `tests/` is an independent, runnable script (via `tsx`) that demonstrates a specific set of features, with `console.log` at each step so you can follow the result in the terminal. The folder itself has a [README](https://github.com/jaobrabo123/VSRepository/blob/main/examples/README.md) explaining the suggested reading order, how to set up the environment, and how to run the tests.
 
 ---
 
-## Requisitos
+## Contributing
+
+Contributions are welcome! If you found a bug, have an improvement idea, or want to help with the documentation, feel free to get involved (**[GitHub Repository](https://github.com/jaobrabo123/VSRepository)**):
+
+1. **Fork** the project.
+2. Create a new branch with your change: `git checkout -b fixing-bug`.
+3. Push to your branch: `git push origin fixing-bug`.
+4. Open a **Pull Request**.
+
+To report issues or suggest new features, open an **Issue**.
+
+---
+
+## Requirements
 
 - Node.js 18+ (ESM)
 - Prisma
-- TypeScript (opcional, mas fortemente recomendado)
-- `"moduleResolution": "bundler"` ou `"nodenext"` no tsconfig
+- TypeScript (optional, but strongly recommended)
+- `"moduleResolution": "bundler"` or `"nodenext"` in tsconfig
 
-`tsconfig.json` recomendado:
+Recommended `tsconfig.json`:
 
 ```json
 {
@@ -1189,20 +1421,22 @@ Para reportar problemas ou sugerir novas funcionalidades, abra uma **Issue**.
 
 ## Troubleshooting
 
-**Tipos genéricos não inferidos** — Verifique se `strict: true` e `moduleResolution: "bundler"` ou `"nodenext"` estão no `tsconfig.json`.
+**Generic types not inferred** — Check that `strict: true` and `moduleResolution: "bundler"` or `"nodenext"` are set in `tsconfig.json`.
+
+**Dynamic method doesn't exist at runtime** — The field referenced in the method name must exist in the Prisma model. E.g.: `findByEmail` requires the model to have an `email` field.
 
-**Método dinâmico não existe em runtime** — O campo referenciado no nome do método deve existir no modelo Prisma. Ex.: `findByEmail` exige que o modelo tenha um campo `email`.
+**`proxyTo` required** — Names outside the standard patterns (e.g. `searchByEmail`) aren't parsed directly. Use `proxyTo: "findByEmail"` in these cases.
 
-**`proxyTo` obrigatório** — Nomes fora dos moldes (ex.: `buscarPorEmail`) não são parseados diretamente. Use `proxyTo: "findByEmail"` nesses casos.
+**Select model returns unexpected fields** — Check that the select model defines exactly the fields your TypeScript type expects.
 
-**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.
+**`selectModel` and `includeModel` together in the same call** — Not allowed. Choose one or the other: if `includeModel` is provided, the `select` (including `defaultSelectModel`) is ignored and only the `include` is sent to Prisma.
 
-**`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` doesn't appear as a default repository option** — This is expected. Unlike `defaultSelectModel`, there's no `defaultIncludeModel`/`defaultInclude`. An `includeModel` can only be set in the method call, via `options.includeModel`.
 
-**`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` throws an error at build** — The provided field must be of type `DateTime` in the Prisma schema. Types like `Boolean` or `String` are not accepted.
 
-**`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` isn't being applied** — Check whether the method uses the `Ordered`, `OrderedAndPaginated`, or `PaginatedAndOrdered` suffix, and whether it has `injectOrdenation` configured. Both take priority over the default ordering.
 
-**`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.
+**`Distinct` suffix not recognized** — `Distinct` is only resolved on read prefixes (`findMany`, `findFirst`, `findBy`, `existsBy`, etc). In methods like `count`, `createMany`, `updateMany`, or `deleteMany` the suffix is ignored.
 
-**`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` with invalid `db`** — The `db` field in these methods only accepts a `DbTransaction` (the return of `prisma.$transaction`), not the main client. Passing the `PrismaClient` directly will cause unexpected behavior.