vsrepo 2.0.0 → 2.2.0

package/README.pt-BR.md

@@ -15,7 +15,7 @@
 
 > ✅ **Lançado.** O VSRepository v2.0.0 (o core agnóstico de ORM) e o [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) já foram publicados e estão prontos para uso. O Prisma 7 é o primeiro adapter totalmente suportado; outros ORMs (TypeORM, Drizzle, etc.) ainda estão em desenvolvimento — veja [Status dos adapters](#status-dos-adapters). Se você precisa da versão anterior, somente Prisma, use o código/docs da [`v1`](https://github.com/jaobrabo123/VSRepository/tree/v1).
 
-Biblioteca de repository pattern **agnóstica de ORM**, com suporte completo a **TypeScript** e **type inference** automático. O VSRepository v2 é uma reescrita da biblioteca [v1](./v1): em vez de falar diretamente com o Prisma, o núcleo agora delega toda operação a um **adapter** plugável, permitindo que a mesma API de repository funcione com Prisma, TypeORM ou qualquer outro ORM/banco que implemente o contrato de adapter.
+Biblioteca de repository pattern **agnóstica de ORM**, com suporte completo a **TypeScript** e **type inference** automático. O VSRepository v2 é uma reescrita da biblioteca [v1](https://github.com/jaobrabo123/VSRepository/tree/v1): em vez de falar diretamente com o Prisma, o núcleo agora delega toda operação a um **adapter** plugável, permitindo que a mesma API de repository funcione com Prisma, TypeORM ou qualquer outro ORM/banco que implemente o contrato de adapter.
 
 O VSRepository permite criar repositories fortemente tipados com:
 
@@ -39,6 +39,9 @@ O VSRepository permite criar repositories fortemente tipados com:
 - [Options do construtor](#options-do-construtor)
 - [Métodos base](#métodos-base)
 - [Soft-delete](#soft-delete)
+- [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação)
+    - [Quais campos são elegíveis](#quais-campos-são-elegíveis)
+    - [Escrevendo um adapter](#escrevendo-um-adapter)
 - [`select` e `relations`](#select-e-relations)
 - [Métodos dinâmicos](#métodos-dinâmicos)
     - [Prefixos disponíveis](#prefixos-disponíveis)
@@ -48,6 +51,7 @@ O VSRepository permite criar repositories fortemente tipados com:
     - [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct)
     - [Options do decorador](#options-do-decorador)
 - [Query methods (SQL raw)](#query-methods-sql-raw)
+    - [Argumentos via spread com `spreadArgs`](#argumentos-via-spread-com-spreadargs)
     - [Queries raw pontuais com `query()`](#queries-raw-pontuais-com-query)
 - [Transações](#transações)
 - [Tipos utilitários](#tipos-utilitários)
@@ -63,7 +67,7 @@ O VSRepository permite criar repositories fortemente tipados com:
 
 ## O que mudou da v1
 
-Se você vem do código/docs da [v1](./v1), aqui está o resumo. Veja cada seção linkada para detalhes.
+Se você vem do código/docs da [v1](https://github.com/jaobrabo123/VSRepository/tree/v1), aqui está o resumo. Veja cada seção linkada para detalhes.
 
 | Área                                              | v1                                                                                                              | v2                                                                                                                                                                                                                                             |
 | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -97,7 +101,7 @@ O adapter do Prisma 7 já foi publicado no npm como `@vsrepo/prisma7-adapter`
 
 | Adapter                                                                                  | Status                                                                                                                                                                                                                          |
 | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Prisma 7 (`@vsrepo/prisma7-adapter`)                                                     | 🟢 **Lançado** — publicado no npm, implementa todo o contrato de `VSRepoAdapter` (CRUD, relations, transactions, `merge`, logging) com testes; veja o [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) para o código-fonte e docs. |
+| Prisma 7 (`@vsrepo/prisma7-adapter`)                                                     | 🟢 **Lançado** — publicado no npm, implementa o contrato de `VSRepoAdapter` (CRUD, relations, transactions, `merge`, logging) com testes; veja o [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) para o código-fonte e docs. **Nota:** os métodos atômicos/de agregação (`incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max` — veja [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação)) foram adicionados ao contrato do `VSRepoAdapter` depois do último release desse adapter; confirme no changelog/versão dele se já implementam esses métodos antes de depender de `increment`/`sum`/etc. contra o Prisma 7. |
 | TypeORM (`@vsrepo/typeorm-adapter`)                                                      | 🟡 **Planejado, ainda não publicado.** Só foi escrito um parser de referência da cláusula `where` (`parseVSRepoWhere`) para validar o design; é o ponto de partida planejado do futuro pacote `@vsrepo/typeorm-adapter`. Contribuições da comunidade nessa frente são bem-vindas. |
 | Outros ORMs (Prisma 8, Drizzle, etc.)                                                    | 🟡 **Planejados, ainda não publicados.** Nenhum pacote oficial existe ainda — por enquanto, escreva o seu próprio adapter (veja [Escrevendo seu próprio adapter](#escrevendo-seu-próprio-adapter)) e considere publicá-lo/contribuir de volta com o projeto. |
 | Adapters customizados                                                                    | 🟢 Totalmente suportados hoje — implemente você mesmo a classe abstrata [`VSRepoAdapter`](#escrevendo-seu-próprio-adapter) para qualquer ORM/banco que precisar, no seu próprio projeto ou pacote, seguindo o mesmo formato esperado dos `@vsrepo/*-adapter`. |
@@ -231,11 +235,19 @@ Disponíveis automaticamente em toda subclasse de `VSRepository`:
 | `removeList(pks, options?)` | Remove vários registros pela primary key, retornando `{ count }`.                                                                     |
 | `total(options?)`           | Retorna o total de registros.                                                                                                         |
 | `has(pk, options?)`         | Verifica se um registro existe, retornando `boolean`.                                                                                 |
+| `increment(pk, field, value, options?)` | Adiciona `value` a um campo numérico de forma atômica. Veja [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação). |
+| `decrement(pk, field, value, options?)` | Subtrai `value` de um campo numérico de forma atômica.                                                                    |
+| `multiply(pk, field, value, options?)`  | Multiplica um campo numérico por `value` de forma atômica.                                                                |
+| `divide(pk, field, value, options?)`    | Divide um campo numérico por `value` de forma atômica.                                                                    |
+| `sum(field, where?, options?)`          | Soma um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.                               |
+| `average(field, where?, options?)`      | Média aritmética de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.                |
+| `min(field, where?, options?)`          | Valor mínimo de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.                    |
+| `max(field, where?, options?)`          | Valor máximo de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.                    |
 | `transaction(fn, options?)` | Executa `fn` dentro de uma transação nativa do ORM.                                                                                   |
 | `getDbClient()`             | Retorna a instância do client do ORM usada fora de transações.                                                                        |
 | `query<T>(query, options?)` | Executa uma instrução SQL raw diretamente contra o banco. Veja [Queries raw pontuais com `query()`](#queries-raw-pontuais-com-query). |
 
-Todos os métodos acima (exceto `transaction`, `query` e `getDbClient`, que recebem options proprias ou nenhuma) aceitam um objeto `MethodOptions<Entity, OrmTypes>` como último argumento (`select`, `relations`, `see`, `db`).
+A maioria dos métodos acima aceita um objeto `MethodOptions<Entity, OrmTypes>` como último argumento (`select`, `relations`, `see`, `db`). Alguns — `total`, `has`, `removeList`, `sum`, `average`, `min`, `max`, e os métodos em lote de soft-delete (`softRemoveList`/`restoreList`) — não retornam/moldam uma `Entity`, então aceitam o tipo mais restrito `RestrictMethodOptions<Entity, OrmTypes>` (só `see`, `db`; sem `select`/`relations`). `transaction`, `query` e `getDbClient` recebem options próprias ou nenhuma.
 
 ---
 
@@ -270,6 +282,62 @@ await userRepository.getAll({ see: "all" }); // todos, ignorando o soft-delete
 
 ---
 
+## Métodos atômicos e de agregação
+
+Toda subclasse de `VSRepository` ganha 8 métodos extras para trabalhar com campos numéricos, divididos em dois grupos:
+
+**Updates atômicos** — avaliados no servidor contra o valor *atual* da linha (`UPDATE ... SET field = field + value`), não um read-modify-write feito no client:
+
+```typescript
+await userRepository.increment("user-1", "balance", 50); // balance = balance + 50
+await userRepository.decrement("user-1", "balance", 50); // balance = balance - 50
+await userRepository.multiply("user-1", "balance", 2); // balance = balance * 2
+await userRepository.divide("user-1", "balance", 4); // balance = balance / 4
+```
+
+Os quatro retornam a `Entity` atualizada e aceitam o `MethodOptions<Entity, OrmTypes>` completo (`select`, `relations`, `see`, `db`) como último argumento, igual `get`/`save`/`patch`.
+
+**Agregações** — calculadas sobre todos os registros que baterem num `where` (opcional):
+
+```typescript
+await userRepository.sum("balance"); // soma do saldo de todos os registros ativos
+await userRepository.sum("balance", { active: true }); // ...restrito por um where
+await userRepository.average("balance");
+await userRepository.min("balance");
+await userRepository.max("balance");
+```
+
+Os quatro retornam `number | null` — `null` quando nenhum registro bate no filtro, espelhando o comportamento de `SUM()`/`AVG()`/`MIN()`/`MAX()` do SQL, que retornam `NULL` (não `0`) sobre um conjunto vazio. Diferente dos métodos atômicos, eles aceitam o tipo mais restrito `RestrictMethodOptions<Entity, OrmTypes>` (só `see`, `db` — sem `select`/`relations`, já que o resultado é um número simples, não uma `Entity` moldada).
+
+Os dois grupos respeitam `softRemoveKey`/`see` do mesmo jeito que todo outro método base — `sum("balance")` só soma registros não removidos por padrão; passe `{ see: "all" }` ou `{ see: "removed" }` para mudar isso.
+
+### Quais campos são elegíveis
+
+`field` é restrito a `NumericKeys<Entity>` — chaves cujo valor (ignorando `null`/`undefined`) é um `number`, um `bigint`, ou um objeto `DecimalLike` (qualquer coisa que exponha `toNumber()` e `decimalPlaces()`, como o `Prisma.Decimal` do Prisma):
+
+```typescript
+type Product = { id: string; name: string; price: Decimal; stock: number | null };
+
+await productRepository.increment(id, "price", new Decimal(10.5)); // ok — Decimal-like
+await productRepository.increment(id, "stock", 5); // ok — campos numéricos nullable são incluídos
+await productRepository.increment(id, "name", 1); // erro de compilação — "name" não é numérico
+```
+
+`value` é tipado como `NonNullable<Entity[Field]>` — precisa bater exatamente com o tipo do próprio campo. Um campo `Decimal` espera uma instância de `Decimal`, não um `number`/`string` puro:
+
+```typescript
+await productRepository.increment(id, "price", new Decimal(10.5)); // ok
+await productRepository.increment(id, "price", 10.5); // erro de compilação — envolva: new Decimal(10.5)
+```
+
+Vale notar que vários ORMs (Drizzle, MikroORM, TypeORM) representam colunas `decimal`/`numeric` como `string` pura por padrão, para evitar perda de precisão de ponto flutuante — um campo `string` **não** satisfaz `NumericKeys<Entity>` por padrão. Configure a coluna em modo numérico (ou um transformer) nesses ORMs se quiser que o campo fique disponível para esses 8 métodos.
+
+### Escrevendo um adapter
+
+O `VSRepoAdapter` espelha as mesmas 8 operações (`incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max` — veja [Escrevendo seu próprio adapter](#escrevendo-seu-próprio-adapter)). Cada adapter traduz isso para o que o ORM/banco considera "nativo": o Prisma tem um formato de update embutido (`{ field: { increment: value } }`) e uma chamada `aggregate()`; outros ORMs em geral precisam de um `QueryBuilder`/expressão `sql` raw (ex.: `SET field = field * :value`, `SELECT SUM(field) ...`). Os métodos atômicos precisam retornar o registro refletindo o estado *depois* do write — se a API de update atômico do ORM só retorna a quantidade de linhas afetadas, faça uma leitura extra em vez de devolver uma cópia desatualizada que já estava em memória.
+
+---
+
 ## `select` e `relations`
 
 Os `selectModels`/`defaultSelectModel` nomeados e reutilizáveis da v1 não existem mais. Na v2 você passa `select` e `relations` diretamente em cada chamada — não há nada para pré-registrar:
@@ -531,21 +599,54 @@ class UserRepository extends VSRepository<User, string> {
 
     @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
     declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+
+    // Aqui só se espera uma linha, então `singleResult` transforma o array
+    // em um único objeto (ou `null` quando nenhuma linha corresponde).
+    @QueryMethod('SELECT * FROM "user" WHERE id = $1 LIMIT 1', { singleResult: true })
+    declare findByIdRaw: (arg: QueryMethodArg<[id: string]>) => Promise<User | null>;
 }
 ```
 
-| Option      | Tipo      | Padrão  | Descrição                                                                                                                                                                                             |
-| ----------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `modifying` | `boolean` | `false` | Quando `true`, executa como `INSERT`/`UPDATE`/`DELETE` e o método resolve para o número de linhas afetadas. Quando `false`, executa como query de leitura e resolve para o tipo de retorno declarado. |
+| Option         | Tipo      | Padrão  | Descrição                                                                                                                                                                                             |
+| -------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modifying`    | `boolean` | `false` | Quando `true`, executa como `INSERT`/`UPDATE`/`DELETE` e o método resolve para o número de linhas afetadas. Quando `false`, executa como query de leitura e resolve para o tipo de retorno declarado. |
+| `singleResult` | `boolean` | `false` | Quando `true`, transforma um resultado em array no seu primeiro elemento (`null` se vazio), permitindo declarar o tipo de retorno como um objeto único em vez de array. Não tem efeito em resultados que não são array (ex.: o número de linhas afetadas de uma query `modifying`). |
 
 Query methods aceitam `{ args, db? }` na chamada — `db` permite que participem de um bloco `transaction()`, assim como os métodos base e dinâmicos.
 
+### Argumentos via spread com `spreadArgs`
+
+Por padrão, um `@QueryMethod` recebe seus valores de placeholder através de um único objeto `QueryMethodArg` (`method({ args: [...] })`). Defina `spreadArgs: true` para recebê-los como argumentos posicionais separados, no estilo do JpaRepository:
+
+```typescript
+class UserRepository extends VSRepository<User, string> {
+    @QueryMethod('SELECT * FROM "user" WHERE email = $1 AND "userType" = $2', {
+        spreadArgs: true,
+    })
+    declare findByEmailAndType: (
+        ...args: QueryArgs<[email: string, userType: string]>
+    ) => Promise<User[]>;
+}
+
+const admins = await userRepository.findByEmailAndType("joao@email.com", "admin");
+```
+
+Para rodar a query com um client ou transação específico em vez do client padrão do repository, passe `withDb(tx)` como argumento final — ele embrulha `tx` em um `DbArg`, que o resolver reconhece via `instanceof`, então nunca é confundido com um argumento posicional comum, mesmo que esse argumento seja um objeto:
+
+```typescript
+await userRepository.transaction(async (tx) => {
+    await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
+});
+```
+
+`spreadArgs` afeta apenas campos declarados com `@QueryMethod` — o padrão é `false`, e chamar um método declarado sem essa opção usando mais de um argumento lança erro, já que se espera o estilo de chamada com um único `QueryMethodArg`. Não tem efeito sobre `query()`, que sempre aceita `{ args, db? }`.
+
 ### Queries raw pontuais com `query()`
 
 Para SQL raw pontual que não justifica declarar um `@QueryMethod` na classe do repository, chame `query()` diretamente — ele está disponível em toda instância de `VSRepository` e passa pela mesma implementação de `query()` do adapter por baixo dos panos:
 
 ```typescript
-query<T = any>(query: string, options?: { args?: any[]; db?: any; modifying?: boolean }): Promise<T>;
+query<T = any>(query: string, options?: { args?: any[]; db?: any; modifying?: boolean; singleResult?: boolean }): Promise<T>;
 ```
 
 ```typescript
@@ -557,13 +658,21 @@ const linhasAfetadas = await userRepository.query<number>(
     'UPDATE "user" SET active = true WHERE id = $1',
     { args: ["123"], modifying: true },
 );
+
+// Aqui só se espera uma linha, então `singleResult` transforma o array
+// em um único objeto (ou `null` quando nenhuma linha corresponde).
+const user = await userRepository.query<User | null>(
+    'SELECT * FROM "user" WHERE id = $1 LIMIT 1',
+    { args: ["123"], singleResult: true },
+);
 ```
 
-| Option      | Tipo      | Padrão                      | Descrição                                                                                                            |
-| ----------- | --------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `args`      | `any[]`   | `undefined`                 | Parâmetros posicionais injetados nos placeholders `$1`, `$2`, ... Nunca interpole valores diretamente na string SQL. |
-| `db`        | `any`     | Client padrão do repository | Client ou transação do banco em que essa query deve rodar.                                                           |
-| `modifying` | `boolean` | `false`                     | Quando `true`, trata a instrução como `INSERT`/`UPDATE`/`DELETE`.                                                    |
+| Option         | Tipo      | Padrão                      | Descrição                                                                                                                                             |
+| -------------- | --------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `args`         | `any[]`   | `undefined`                  | Parâmetros posicionais injetados nos placeholders `$1`, `$2`, ... Nunca interpole valores diretamente na string SQL.                                  |
+| `db`           | `any`     | Client padrão do repository  | Client ou transação do banco em que essa query deve rodar.                                                                                             |
+| `modifying`    | `boolean` | `false`                      | Quando `true`, trata a instrução como `INSERT`/`UPDATE`/`DELETE`.                                                                                      |
+| `singleResult` | `boolean` | `false`                      | Quando `true`, transforma um resultado em array no seu primeiro elemento (`null` se vazio). Não tem efeito em resultados que não são array (ex.: o número de linhas afetadas de uma query `modifying`). |
 
 Assim como os métodos base, dinâmicos e query, `query()` aceita `db` em `options` para participar de um bloco `transaction()`.
 
@@ -618,6 +727,7 @@ Além dos tipos que descrevem o formato da entidade já vistos acima (`VSRepoSel
 ```typescript
 import type {
     MethodOptions,
+    RestrictMethodOptions,
     Pagination,
     Ordering,
     OrderByField,
@@ -626,7 +736,11 @@ import type {
     DeepPartial,
     CountResult,
     QueryMethodArg,
+    QueryArgs,
     KeysOfType,
+    NumericKeys,
+    NumericLike,
+    DecimalLike,
     Primitive,
     VSRepoWhere,
     VSRepoOrmTypes,
@@ -637,14 +751,19 @@ import type {
 
 | Tipo                                                | Descrição                                                                                                                                                                                                           | Usado por                                                                                                                                                           |
 | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MethodOptions<T, K>`                               | Options aceitas como último argumento por todo método base e dinâmico: `select`, `relations`, `see`, `db`.                                                                                                          | [Métodos base](#métodos-base), [Métodos Dinâmicos](#métodos-dinâmicos).                                                                                             |
+| `MethodOptions<T, K>`                               | Options aceitas como último argumento pela maioria dos métodos base e dinâmicos: `select`, `relations`, `see`, `db`.                                                                                                | [Métodos base](#métodos-base), [Métodos Dinâmicos](#métodos-dinâmicos).                                                                                             |
+| `RestrictMethodOptions<T, K>`                       | `MethodOptions<T, K>` restrito, expondo só `see`/`db` — usado pelos métodos que não retornam/moldam uma `Entity` (`total`, `has`, `sum`, `average`, `min`, `max`, `removeList`, `softRemoveList`, `restoreList`). | [Métodos base](#métodos-base), [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação).                                                                 |
 | `Pagination`                                        | `{ limit?, offset? }` aceito por `getAll` e pelos métodos dinâmicos com `Paginated`.                                                                                                                                | [Métodos base](#métodos-base), [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct).                                                                  |
 | `Ordering<T>` / `OrderByField<T>` / `SortDirection` | Formato de ordenação aceito por `getAll`, `defaultOrdering` e `injectOrdering`, e pelos métodos dinâmicos com `Ordered`. Pode ser um único objeto ou um array encadeado; objetos aninhados ordenam relações to-one. | [Options do construtor](#options-do-construtor), [Options do decorador](#options-do-decorador), [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct). |
 | `SeeMode`                                           | `"active" \| "removed" \| "all"` — controla a visibilidade de registros com soft-delete.                                                                                                                            | [Soft-delete](#soft-delete).                                                                                                                                        |
 | `DeepPartial<T>`                                    | Torna todas as propriedades de `T` opcionais recursivamente, incluindo objetos aninhados e elementos de array.                                                                                                      | `save`, `saveList`, `patch`, `merge`, e todo método de escrita do `VSRepoAdapter`.                                                                                  |
 | `CountResult`                                       | `{ count: number }` — o formato retornado por operações em lote.                                                                                                                                                    | `removeList`, `softRemoveList`, `restoreList`, `createManyIgnoreConflicts`.                                                                                         |
 | `QueryMethodArg<T>`                                 | `{ args?: T, db? }` — parâmetros posicionais do SQL (`$1`, `$2`, ...) e cliente de transação para o `@QueryMethod`.                                                                                                 | [Query methods (SQL raw)](#query-methods-sql-raw).                                                                                                                  |
+| `QueryArgs<T, O>`                                   | Tipa a lista de parâmetros via spread de um `@QueryMethod` declarado com `{ spreadArgs: true }`: os valores de `T`, em ordem, seguidos de um `DbArg<O>` opcional construído via `withDb()`.                       | [Argumentos via spread com `spreadArgs`](#argumentos-via-spread-com-spreadargs).                                                                                    |
 | `KeysOfType<T, K>`                                  | Extrai as chaves de `T` cujo tipo de valor é atribuível a `K`.                                                                                                                                                      | Restringe `pkName`, em [Options do construtor](#options-do-construtor), aos campos da entidade compatíveis com o tipo de chave primária configurado.                |
+| `NumericKeys<T>`                                    | Extrai as chaves de `T` cujo tipo de valor (ignorando `null`/`undefined`) é atribuível a `NumericLike`. Campos numéricos nullable (`number \| null`) são incluídos.                                                | Restringe `field` em [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação) (`increment`, `sum`, etc).                                                 |
+| `NumericLike`                                       | `number \| bigint \| DecimalLike`.                                                                                                                                                                                   | [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação).                                                                                                 |
+| `DecimalLike`                                       | Formato estrutural de um valor decimal de precisão arbitrária (`{ toNumber(): number; decimalPlaces(): number }`), compatível com o `Prisma.Decimal` do Prisma sem precisar importá-lo diretamente.                | [Quais campos são elegíveis](#quais-campos-são-elegíveis).                                                                                                           |
 | `Primitive`                                         | União de tipos escalares (`string \| number \| boolean \| bigint \| symbol \| undefined \| null \| Date`) tratados como valores-folha — e não relações — ao percorrer o formato de uma entidade.                    | Usado por `Ordering<T>` para distinguir campos escalares de campos de relação.                                                                                      |
 | `VSRepoWhere<T>`                                    | Tipo de filtro agnóstico de ORM aceito pelos métodos dinâmicos `*Where` (ex.: `findWhere`, `findOneWhere`, `updateWhere`). Suporta filtros de campo, operadores lógicos (`AND`/`OR`/`NOT`) e filtros de relação.    | [Prefixos `findWhere`, `findOneWhere` e demais `*Where`](#prefixos-disponíveis).                                                                                    |
 | `VSRepoOrmTypes`                                    | `{ dbClient; dbTransaction }` — descreve os tipos de client/transaction do seu ORM. Passado como terceiro generic de `VSRepository<Entity, PKType, OrmTypes>` para tipar `getDbClient()`, `transaction()` e a option `db` em vez de `any`. | [Criando um repository](#criando-um-repository).                                                                                                                    |
@@ -753,6 +872,51 @@ export abstract class VSRepoAdapter<T> {
         update: DeepPartial<T>,
         options?: AdapterMethodOptions<T>,
     ): Promise<T>;
+
+    abstract incrementOne<K extends NumericKeys<T>>(
+        field: K,
+        value: NonNullable<T[K]>,
+        where: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T>;
+    abstract decrementOne<K extends NumericKeys<T>>(
+        field: K,
+        value: NonNullable<T[K]>,
+        where: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T>;
+    abstract multiplyOne<K extends NumericKeys<T>>(
+        field: K,
+        value: NonNullable<T[K]>,
+        where: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T>;
+    abstract divideOne<K extends NumericKeys<T>>(
+        field: K,
+        value: NonNullable<T[K]>,
+        where: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T>;
+    abstract sum(
+        field: NumericKeys<T>,
+        where?: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<number | null>;
+    abstract average(
+        field: NumericKeys<T>,
+        where?: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<number | null>;
+    abstract min(
+        field: NumericKeys<T>,
+        where?: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<number | null>;
+    abstract max(
+        field: NumericKeys<T>,
+        where?: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<number | null>;
 }
 ```
 
@@ -815,7 +979,7 @@ try {
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | `DECORATOR`       | Argumentos inválidos foram passados para `@DynamicMethod` ou `@QueryMethod`.                                                               |
 | `RESOLVER`        | A biblioteca falhou ao resolver a configuração de um método dinâmico/de query em um método chamável (ex.: um nome de método desconhecido). |
-| `DYNAMIC`         | Um método dinâmico já resolvido falhou em tempo de execução (ex.: argumentos faltando).                                                    |
+| `DYNAMIC`         | Um dynamic/query method já resolvido falhou em tempo de execução (ex.: argumentos faltando).                                                    |
 | `VALIDATOR`       | Options ou argumentos de método inválidos foram detectados durante a validação.                                                            |
 | `BASE`            | Uso inválido de um método base (`get`, `save`, `remove`, etc).                                                                             |
 | `ADAPTER`         | Um `VSRepoAdapter` falhou ao falar com o ORM/banco subjacente — sempre é lançado como `VSRepoAdapterError`.                                |
@@ -960,7 +1124,7 @@ npm install ../caminho/vsrepo-1.4.0.tgz
 Observações:
 
 - `pnpm build` executa `tsc -p tsconfig.build.json`, que gera o JS compilado e as declarações de tipo em `dist/` com `rootDir: src`.
-- O pacote publicado contém **apenas** a pasta `dist/` além dos READMEs e da `LICENSE` (veja `files` no `package.json`). Fontes, testes, a pasta `v1/` e `generated/` **não** são enviados — os adapters viverão em seus próprios pacotes `@vsrepo/*-adapter`.
+- O pacote publicado contém **apenas** a pasta `dist/` além dos READMEs e da `LICENSE` (veja `files` no `package.json`). Os adapters viverão em seus próprios pacotes `@vsrepo/*-adapter`.
 - O core é ORM-agnóstico e não tem dependência peer de `@prisma/client`.
 
 ---

package/dist/VSRepoAdapter.d.ts

@@ -2,6 +2,7 @@ import { AdapterMethodOptions } from "./types/adapter/adapter-method-options.typ
 import { AdapterQueryOptions } from "./types/adapter/adapter-query-options.type";
 import { CountResult } from "./types/utils/count-result.type";
 import { DeepPartial } from "./types/utils/deep-partial.type";
+import { NumericKeys } from "./types/utils/numeric-keys.type";
 import { VSRepoTransactionOptions } from "./types/vsrepo/vsrepo-transaction-options.type";
 import { VSRepoWhere } from "./types/vsrepo/vsrepo-where.type";
 /**
@@ -68,4 +69,41 @@ export declare abstract class VSRepoAdapter<T> {
     abstract merge<K>(where: VSRepoWhere<T>, obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<K & T>;
     /** Creates a record if none matches `where`, otherwise updates it. */
     abstract upsert(where: VSRepoWhere<T>, create: DeepPartial<T>, update: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Atomically adds `value` to `field` on the single record matching
+     * `where` — equivalent to `UPDATE ... SET field = field + value WHERE
+     * ...`, evaluated server-side against the row's current value (not a
+     * client-side read-modify-write).
+     *
+     * Implementations must return the record reflecting the state *after*
+     * the write. If the underlying ORM's atomic-update API doesn't already
+     * return the updated row (e.g. it only returns an affected-row count),
+     * issue a follow-up read instead of returning a stale in-memory copy.
+     */
+    abstract incrementOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Same as {@link VSRepoAdapter.incrementOne}, subtracting `value` instead of adding it. */
+    abstract decrementOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Same as {@link VSRepoAdapter.incrementOne}, multiplying the field's current value by `value`. */
+    abstract multiplyOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Same as {@link VSRepoAdapter.incrementOne}, dividing the field's
+     * current value by `value`. Division-by-zero behavior is not
+     * standardized by this contract — it is whatever the underlying
+     * database/driver does natively (e.g. Postgres raises a
+     * `division_by_zero` error); document your adapter's actual behavior.
+     */
+    abstract divideOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Returns the sum of `field` across every record matching `where` (all
+     * records if `where` is omitted/empty), or `null` if no record
+     * matches — mirroring SQL's `SUM()`, which returns `NULL` (not `0`)
+     * over an empty set.
+     */
+    abstract sum(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoAdapter.sum}, but the arithmetic mean (`AVG()`) instead of the total. */
+    abstract average(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoAdapter.sum}, but the minimum value (`MIN()`) instead of the total. */
+    abstract min(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoAdapter.sum}, but the maximum value (`MAX()`) instead of the total. */
+    abstract max(field: NumericKeys<T>, where?: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
 }

package/dist/VSRepository.d.ts

@@ -3,6 +3,7 @@ import { VSRepoOptions } from "./types/vsrepo/vsrepo-options.type";
 import { CountResult } from "./types/utils/count-result.type";
 import { DeepPartial } from "./types/utils/deep-partial.type";
 import { KeysOfType } from "./types/utils/keys-of-type.type";
+import { VSRepoWhere } from "./types/vsrepo/vsrepo-where.type";
 import { VSRepoOrmTypes } from "./types/vsrepo/vsrepo-orm-types.type";
 import { VSRepoTransactionOptions } from "./types/vsrepo/vsrepo-transaction-options.type";
 import { MethodOptions } from "./types/utils/methods-options.type";
@@ -10,6 +11,8 @@ import { Ordering } from "./types/utils/ordering.type";
 import { Pagination } from "./types/utils/pagination.type";
 import { VSRepoArgs } from "./types/vsrepo/vsrepo-args.type";
 import { VSRepoQueryOptions } from "./types/vsrepo/vsrepo-query-options.type";
+import { NumericKeys } from "./types/utils/numeric-keys.type";
+import { RestrictMethodOptions } from "./types/utils/restrict-method-options.type";
 /**
  * ORM-agnostic base repository, exposing a complete set of ready-to-use CRUD
  * and soft-delete methods around an entity, plus any `@DynamicMethod`/`@QueryMethod`
@@ -76,6 +79,8 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
      * Use `$1`, `$2`, ... placeholders for values passed via `options.args` —
      * never interpolate values directly into `query`, to avoid SQL injection.
      * Set `options.modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements.
+     * Set `options.singleResult: true` to collapse an array result into its
+     * first element (`null` if empty) — see {@link VSRepoQueryOptions.singleResult}.
      *
      * @example
      * ```typescript
@@ -88,6 +93,13 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
      *     'UPDATE "user" SET active = true WHERE id = $1',
      *     { args: ["123"], modifying: true },
      * );
+     *
+     * // Only one row is ever expected here, so `singleResult` collapses the
+     * // array into a single object (or `null` when no row matches).
+     * const user = await userRepository.query<User | null>(
+     *     'SELECT * FROM "user" WHERE id = $1 LIMIT 1',
+     *     { args: ["123"], singleResult: true },
+     * );
      * ```
      */
     query<T = any>(query: string, options?: VSRepoQueryOptions<OrmTypes>): Promise<T>;
@@ -111,7 +123,7 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
     /** Deletes a record identified by its primary key (PK). */
     remove(pk: PKType, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
     /** Deletes multiple records by their primary keys, returning the count of affected rows. */
-    removeList(pks: PKType[], options?: MethodOptions<Entity, OrmTypes>): Promise<CountResult>;
+    removeList(pks: PKType[], options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<CountResult>;
     /** Partially updates an existing record by its primary key (PK). */
     patch(pk: PKType, obj: DeepPartial<Entity>, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
     /**
@@ -121,15 +133,43 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
      */
     merge<U extends DeepPartial<Entity>>(pk: PKType, obj: U, options?: MethodOptions<Entity, OrmTypes>): Promise<(U & Entity) | null>;
     /** Returns the total number of records. */
-    total(options?: MethodOptions<Entity, OrmTypes>): Promise<number>;
+    total(options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<number>;
     /** Checks whether a record exists by its primary key (PK). */
-    has(pk: PKType, options?: MethodOptions<Entity, OrmTypes>): Promise<boolean>;
+    has(pk: PKType, options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<boolean>;
     /** Marks a record as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
     softRemove(pk: PKType, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
     /** Marks multiple records as deleted (soft-delete) in batch. Requires `softRemoveKey` to be configured on the repository. */
-    softRemoveList(pks: PKType[], options?: MethodOptions<Entity, OrmTypes>): Promise<CountResult>;
+    softRemoveList(pks: PKType[], options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<CountResult>;
     /** Restores a record previously marked as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
     restore(pk: PKType, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
     /** Restores multiple records previously marked as deleted (soft-delete) in batch. Requires `softRemoveKey` to be configured on the repository. */
-    restoreList(pks: PKType[], options?: MethodOptions<Entity, OrmTypes>): Promise<CountResult>;
+    restoreList(pks: PKType[], options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<CountResult>;
+    /**
+     * Atomically adds `value` to a numeric field of the record identified
+     * by `pk`, evaluated server-side against the row's current value (e.g.
+     * `saldo = saldo + value`) — not a fetch-then-save round trip.
+     */
+    increment<Field extends NumericKeys<Entity>>(pk: PKType, field: Field, value: NonNullable<Entity[Field]>, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
+    /** Same as {@link VSRepository.increment}, subtracting `value` instead of adding it. */
+    decrement<Field extends NumericKeys<Entity>>(pk: PKType, field: Field, value: NonNullable<Entity[Field]>, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
+    /** Same as {@link VSRepository.increment}, multiplying the field's current value by `value`. */
+    multiply<Field extends NumericKeys<Entity>>(pk: PKType, field: Field, value: NonNullable<Entity[Field]>, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
+    /**
+     * Same as {@link VSRepository.increment}, dividing the field's current
+     * value by `value`. Division-by-zero behavior depends on the adapter/
+     * underlying database (see {@link VSRepoAdapter.divideOne}).
+     */
+    divide<Field extends NumericKeys<Entity>>(pk: PKType, field: Field, value: NonNullable<Entity[Field]>, options?: MethodOptions<Entity, OrmTypes>): Promise<Entity>;
+    /**
+     * Returns the sum of a numeric field across every record matching
+     * `where` (all records if omitted), or `null` if none match — mirrors
+     * SQL's `SUM()`, which returns `NULL` (not `0`) over an empty set.
+     */
+    sum(field: NumericKeys<Entity>, where?: VSRepoWhere<Entity>, options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<number | null>;
+    /** Same as {@link VSRepository.sum}, but the arithmetic mean instead of the total. */
+    average(field: NumericKeys<Entity>, where?: VSRepoWhere<Entity>, options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<number | null>;
+    /** Same as {@link VSRepository.sum}, but the minimum value instead of the total. */
+    min(field: NumericKeys<Entity>, where?: VSRepoWhere<Entity>, options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<number | null>;
+    /** Same as {@link VSRepository.sum}, but the maximum value instead of the total. */
+    max(field: NumericKeys<Entity>, where?: VSRepoWhere<Entity>, options?: RestrictMethodOptions<Entity, OrmTypes>): Promise<number | null>;
 }