vsrepo 2.0.0 → 2.1.0

package/README.md

@@ -15,7 +15,7 @@
 
 > ✅ **Released.** VSRepository v2.0.0 (the ORM-agnostic core) and the [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) are both published and ready to use. Prisma 7 is the first fully supported adapter; other ORMs (TypeORM, Drizzle, etc.) are still in progress — see [Adapter status](#adapter-status). If you need the previous Prisma-only release, use the [`v1`](https://github.com/jaobrabo123/VSRepository/tree/v1) code/docs instead.
 
-**ORM-agnostic** repository pattern library, with full **TypeScript** support and automatic **type inference**. VSRepository v2 is a rewrite of the [v1](./v1) library: instead of talking to Prisma directly, the core now delegates every operation to a pluggable **adapter**, so the same repository API can work against Prisma, TypeORM, or any other ORM/database that implements the adapter contract.
+**ORM-agnostic** repository pattern library, with full **TypeScript** support and automatic **type inference**. VSRepository v2 is a rewrite of the [v1](https://github.com/jaobrabo123/VSRepository/tree/v1) library: instead of talking to Prisma directly, the core now delegates every operation to a pluggable **adapter**, so the same repository API can work against Prisma, TypeORM, or any other ORM/database that implements the adapter contract.
 
 VSRepository lets you create strongly-typed repositories with:
 
@@ -39,6 +39,9 @@ VSRepository lets you create strongly-typed repositories with:
 - [Constructor options](#constructor-options)
 - [Base methods](#base-methods)
 - [Soft-delete](#soft-delete)
+- [Atomic and aggregate methods](#atomic-and-aggregate-methods)
+    - [Which fields are eligible](#which-fields-are-eligible)
+    - [Writing an adapter](#writing-an-adapter)
 - [`select` and `relations`](#select-and-relations)
 - [Dynamic methods](#dynamic-methods)
     - [Available prefixes](#available-prefixes)
@@ -63,7 +66,7 @@ VSRepository lets you create strongly-typed repositories with:
 
 ## What changed from v1
 
-If you're coming from the [v1](./v1) code/docs, here's the short version. See each linked section for details.
+If you're coming from the [v1](https://github.com/jaobrabo123/VSRepository/tree/v1) code/docs, here's the short version. See each linked section for details.
 
 | Area                                         | v1                                                                                                              | v2                                                                                                                                                                                                                                   |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -97,7 +100,7 @@ The Prisma 7 adapter has now been published to npm as `@vsrepo/prisma7-adapter`
 
 | Adapter                                                                                  | Status                                                                                                                                                                                                       |
 | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Prisma 7 (`@vsrepo/prisma7-adapter`)                                                     | 🟢 **Released** — published to npm, implements the entire `VSRepoAdapter` contract (CRUD, relations, transactions, `merge`, logging) with tests; see [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) for source and docs. |
+| Prisma 7 (`@vsrepo/prisma7-adapter`)                                                     | 🟢 **Released** — published to npm, implements the `VSRepoAdapter` contract (CRUD, relations, transactions, `merge`, logging) with tests; see [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) for source and docs. **Note:** the atomic/aggregate methods (`incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max` — see [Atomic and aggregate methods](#atomic-and-aggregate-methods)) were added to the `VSRepoAdapter` contract after this adapter's last release; confirm its changelog/version implements them before relying on `increment`/`sum`/etc. against Prisma 7. |
 | TypeORM (`@vsrepo/typeorm-adapter`)                                                      | 🟡 **Planned, not published yet.** Only a reference `where`-clause parser (`parseVSRepoWhere`) was written to validate the design; it's the planned starting point for the future `@vsrepo/typeorm-adapter` package. Community contributions toward this are welcome. |
 | Other ORMs (Prisma 8, Drizzle, etc.)                                                     | 🟡 **Planned, not published yet.** No official package exists yet — write your own adapter for now (see [Writing your own adapter](#writing-your-own-adapter)), and consider publishing/contributing it back. |
 | Custom adapters                                                                          | 🟢 Fully supported today — implement the [`VSRepoAdapter`](#writing-your-own-adapter) abstract class yourself for any ORM/database you need, in your own project or package, following the same shape as `@vsrepo/*-adapter` is expected to have. |
@@ -231,11 +234,19 @@ Available automatically on every `VSRepository` subclass:
 | `removeList(pks, options?)` | Deletes multiple records by primary key, returning `{ count }`.                                                                      |
 | `total(options?)`           | Returns the total number of records.                                                                                                 |
 | `has(pk, options?)`         | Checks whether a record exists, returning `boolean`.                                                                                 |
+| `increment(pk, field, value, options?)` | Atomically adds `value` to a numeric field. See [Atomic and aggregate methods](#atomic-and-aggregate-methods).           |
+| `decrement(pk, field, value, options?)` | Atomically subtracts `value` from a numeric field.                                                                        |
+| `multiply(pk, field, value, options?)`  | Atomically multiplies a numeric field by `value`.                                                                         |
+| `divide(pk, field, value, options?)`    | Atomically divides a numeric field by `value`.                                                                            |
+| `sum(field, where?, options?)`          | Sums a numeric field across every matching record; `null` if none match.                                                  |
+| `average(field, where?, options?)`      | Arithmetic mean of a numeric field across every matching record; `null` if none match.                                    |
+| `min(field, where?, options?)`          | Minimum value of a numeric field across every matching record; `null` if none match.                                      |
+| `max(field, where?, options?)`          | Maximum value of a numeric field across every matching record; `null` if none match.                                      |
 | `transaction(fn, options?)` | Runs `fn` inside a native transaction of the underlying ORM.                                                                         |
 | `getDbClient()`             | Returns the underlying ORM client instance used outside of transactions.                                                             |
 | `query<T>(query, options?)` | Executes a raw SQL statement directly against the database. See [Ad-hoc raw queries with `query()`](#ad-hoc-raw-queries-with-query). |
 
-All of the above (except `transaction`, `query`, and `getDbClient`, which accept their own options or none at all) accept a `MethodOptions<Entity, OrmTypes>` object as their last argument (`select`, `relations`, `see`, `db`).
+Most of the above accept a `MethodOptions<Entity, OrmTypes>` object as their last argument (`select`, `relations`, `see`, `db`). A few — `total`, `has`, `removeList`, `sum`, `average`, `min`, `max`, and the soft-delete batch methods (`softRemoveList`/`restoreList`) — don't return/shape an `Entity`, so they accept the narrower `RestrictMethodOptions<Entity, OrmTypes>` instead (`see`, `db` only; no `select`/`relations`). `transaction`, `query`, and `getDbClient` accept their own options or none at all.
 
 ---
 
@@ -270,6 +281,62 @@ await userRepository.getAll({ see: "all" }); // everything, ignoring soft-delete
 
 ---
 
+## Atomic and aggregate methods
+
+Every `VSRepository` subclass gets 8 extra methods for working with numeric fields, split into two groups:
+
+**Atomic updates** — evaluated server-side against the row's *current* value (`UPDATE ... SET field = field + value`), not a client-side read-modify-write:
+
+```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
+```
+
+All four return the updated `Entity` and accept the full `MethodOptions<Entity, OrmTypes>` (`select`, `relations`, `see`, `db`) as their last argument, same as `get`/`save`/`patch`.
+
+**Aggregates** — computed across every record matching an (optional) `where`:
+
+```typescript
+await userRepository.sum("balance"); // total balance across every active record
+await userRepository.sum("balance", { active: true }); // ...restricted by a where
+await userRepository.average("balance");
+await userRepository.min("balance");
+await userRepository.max("balance");
+```
+
+All four return `number | null` — `null` when no record matches, mirroring SQL's `SUM()`/`AVG()`/`MIN()`/`MAX()`, which return `NULL` (not `0`) over an empty set. Unlike the atomic methods, they accept the narrower `RestrictMethodOptions<Entity, OrmTypes>` (`see`, `db` only — no `select`/`relations`, since the result is a plain number, not a shaped `Entity`).
+
+Both groups respect `softRemoveKey`/`see` the same way every other base method does — `sum("balance")` only totals non-deleted records by default, pass `{ see: "all" }` or `{ see: "removed" }` to change that.
+
+### Which fields are eligible
+
+`field` is constrained to `NumericKeys<Entity>` — keys whose (non-nullable) value type is a `number`, a `bigint`, or a `DecimalLike` object (anything exposing `toNumber()` and `decimalPlaces()`, matching e.g. Prisma's `Prisma.Decimal`):
+
+```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 — nullable numeric fields are included
+await productRepository.increment(id, "name", 1); // compile error — "name" isn't numeric
+```
+
+`value` is typed as `NonNullable<Entity[Field]>` — it must match the field's own type exactly. A `Decimal` field expects a `Decimal` instance, not a plain `number`/`string`:
+
+```typescript
+await productRepository.increment(id, "price", new Decimal(10.5)); // ok
+await productRepository.increment(id, "price", 10.5); // compile error — wrap it: new Decimal(10.5)
+```
+
+Note that several ORMs (Drizzle, MikroORM, TypeORM) represent `decimal`/`numeric` columns as plain `string` by default, to avoid floating-point precision loss — a `string` field does **not** satisfy `NumericKeys<Entity>` out of the box. Configure the column in a numeric mode (or a transformer) on those ORMs if you want the field to be usable with these 8 methods.
+
+### Writing an adapter
+
+`VSRepoAdapter` mirrors the same 8 operations (`incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max` — see [Writing your own adapter](#writing-your-own-adapter)). Each adapter translates them into whatever its ORM/database considers "native": Prisma has a built-in `{ field: { increment: value } }` update shape and an `aggregate()` call; other ORMs typically need a `QueryBuilder`/raw-`sql` expression (e.g. `SET field = field * :value`, `SELECT SUM(field) ...`) instead. The atomic methods must return the record reflecting the state *after* the write — if the ORM's atomic-update API only returns an affected-row count, issue a follow-up read rather than returning a stale in-memory copy.
+
+---
+
 ## `select` and `relations`
 
 v1's named, reusable `selectModels`/`defaultSelectModel` are gone. In v2 you pass `select` and `relations` directly on each call — there's nothing to pre-register:
@@ -615,6 +682,7 @@ Beyond the entity-shaping types covered above (`VSRepoSelect`, `VSRepoRelations`
 ```typescript
 import type {
     MethodOptions,
+    RestrictMethodOptions,
     Pagination,
     Ordering,
     OrderByField,
@@ -624,6 +692,9 @@ import type {
     CountResult,
     QueryMethodArg,
     KeysOfType,
+    NumericKeys,
+    NumericLike,
+    DecimalLike,
     Primitive,
     VSRepoWhere,
     VSRepoOrmTypes,
@@ -634,7 +705,8 @@ import type {
 
 | Type                                                | Description                                                                                                                                                                                          | Used by                                                                                                                                                       |
 | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MethodOptions<T, K>`                               | Options accepted as the last argument of every base and dynamic method: `select`, `relations`, `see`, `db`.                                                                                          | [Base methods](#base-methods), [Dynamic methods](#dynamic-methods).                                                                                           |
+| `MethodOptions<T, K>`                               | Options accepted as the last argument of most base and dynamic methods: `select`, `relations`, `see`, `db`.                                                                                          | [Base methods](#base-methods), [Dynamic methods](#dynamic-methods).                                                                                           |
+| `RestrictMethodOptions<T, K>`                        | Narrowed `MethodOptions<T, K>` exposing only `see`/`db` — used by methods that don't shape/return an `Entity` (`total`, `has`, `sum`, `average`, `min`, `max`, `removeList`, `softRemoveList`, `restoreList`).           | [Base methods](#base-methods), [Atomic and aggregate methods](#atomic-and-aggregate-methods).                                                                 |
 | `Pagination`                                        | `{ limit?, offset? }` accepted by `getAll` and by `Paginated` dynamic methods.                                                                                                                       | [Base methods](#base-methods), [Ordering, pagination and distinct](#ordering-pagination-and-distinct).                                                        |
 | `Ordering<T>` / `OrderByField<T>` / `SortDirection` | Ordering shape accepted by `getAll`, `defaultOrdering` and `injectOrdering`, and by `Ordered` dynamic methods. A single object or a chained array; nested objects order to-one relations.            | [Constructor options](#constructor-options), [Decorator options](#decorator-options), [Ordering, pagination and distinct](#ordering-pagination-and-distinct). |
 | `SeeMode`                                           | `"active" \| "removed" \| "all"` — controls visibility of soft-deleted records.                                                                                                                      | [Soft-delete](#soft-delete).                                                                                                                                  |
@@ -642,6 +714,9 @@ import type {
 | `CountResult`                                       | `{ count: number }` — the shape returned by batch operations.                                                                                                                                        | `removeList`, `softRemoveList`, `restoreList`, `createManyIgnoreConflicts`.                                                                                   |
 | `QueryMethodArg<T>`                                 | `{ args?: T, db? }` — positional SQL parameters (`$1`, `$2`, ...) and transaction client for `@QueryMethod`.                                                                                         | [Query methods (raw SQL)](#query-methods-raw-sql).                                                                                                            |
 | `KeysOfType<T, K>`                                  | Extracts the keys of `T` whose value type is assignable to `K`.                                                                                                                                      | Constrains `pkName` in [Constructor options](#constructor-options) to fields of the entity matching the configured primary-key type.                          |
+| `NumericKeys<T>`                                    | Extracts the keys of `T` whose (non-nullable) value type is assignable to `NumericLike`. Nullable numeric fields (`number \| null`) are included.                                                   | Constrains `field` in [Atomic and aggregate methods](#atomic-and-aggregate-methods) (`increment`, `sum`, etc).                                                |
+| `NumericLike`                                       | `number \| bigint \| DecimalLike`.                                                                                                                                                                    | [Atomic and aggregate methods](#atomic-and-aggregate-methods).                                                                                                 |
+| `DecimalLike`                                       | Structural shape of an arbitrary-precision decimal value (`{ toNumber(): number; decimalPlaces(): number }`), matching e.g. Prisma's `Prisma.Decimal` without importing it directly.                | [Which fields are eligible](#which-fields-are-eligible).                                                                                                       |
 | `Primitive`                                         | Union of scalar types (`string \| number \| boolean \| bigint \| symbol \| undefined \| null \| Date`) treated as leaves — not relations — when walking an entity's shape.                           | Used by `Ordering<T>` to tell scalar fields apart from relation fields.                                                                                       |
 | `VSRepoWhere<T>`                                    | ORM-agnostic filter type accepted by `*Where` dynamic methods (e.g. `findWhere`, `findOneWhere`, `updateWhere`). Supports field filters, logical operators (`AND`/`OR`/`NOT`), and relation filters. | [`findWhere`, `findOneWhere` and other `*Where` prefixes](#available-prefixes).                                                                               |
 | `VSRepoOrmTypes`                                    | `{ dbClient; dbTransaction }` — describes your ORM's client/transaction types. Passed as the third generic to `VSRepository<Entity, PKType, OrmTypes>` to type `getDbClient()`, `transaction()` and the `db` option instead of `any`. | [Creating a repository](#creating-a-repository).                                                                                                              |
@@ -750,6 +825,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>;
 }
 ```
 
@@ -957,7 +1077,7 @@ npm install ../path/to/vsrepo-1.4.0.tgz
 Notes:
 
 - `pnpm build` runs `tsc -p tsconfig.build.json`, which outputs the compiled JS and generated type declarations into `dist/` with `rootDir: src`.
-- The published package contains **only** the `dist/` folder plus the READMEs and `LICENSE` (see `files` in `package.json`). Source, tests, the `v1/` folder and `generated/` are **not** shipped — the adapters will live in their own `@vsrepo/*-adapter` packages.
+- The published package contains **only** the `dist/` folder plus the READMEs and `LICENSE` (see `files` in `package.json`). The adapters will live in their own `@vsrepo/*-adapter` packages.
 - The core is ORM-agnostic and has no `@prisma/client` peer dependency.
 
 ---

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)
@@ -63,7 +66,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 +100,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 +234,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 +281,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:
@@ -618,6 +685,7 @@ Além dos tipos que descrevem o formato da entidade já vistos acima (`VSRepoSel
 ```typescript
 import type {
     MethodOptions,
+    RestrictMethodOptions,
     Pagination,
     Ordering,
     OrderByField,
@@ -627,6 +695,9 @@ import type {
     CountResult,
     QueryMethodArg,
     KeysOfType,
+    NumericKeys,
+    NumericLike,
+    DecimalLike,
     Primitive,
     VSRepoWhere,
     VSRepoOrmTypes,
@@ -637,7 +708,8 @@ 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).                                                                                                                                        |
@@ -645,6 +717,9 @@ import type {
 | `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).                                                                                                                  |
 | `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 +828,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>;
 }
 ```
 
@@ -960,7 +1080,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`
@@ -111,7 +114,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 +124,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>;
 }

package/dist/VSRepository.js

@@ -102,10 +102,12 @@ class VSRepository {
     wherePkIn(pks) {
         return { [this.pkName]: { in: pks } };
     }
-    async execBaseMethod(fn, methodName, optionsUnchecked) {
-        const optionsChecked = methodName === "getAll"
-            ? this.validator.validateGetAllMethodOptions(optionsUnchecked)
-            : this.validator.validateMethodOptions(optionsUnchecked);
+    async execBaseMethod(fn, methodName, optionsUnchecked, opsType = "common") {
+        const optionsChecked = opsType === "common"
+            ? this.validator.validateMethodOptions(optionsUnchecked)
+            : opsType === "restrict"
+                ? this.validator.validateRestrictMethodOptions(optionsUnchecked)
+                : this.validator.validateGetAllMethodOptions(optionsUnchecked);
         optionsChecked.db ??= this.getDbClient();
         const start = this.logger.startPerformLog("run " + methodName);
         try {
@@ -195,7 +197,7 @@ class VSRepository {
         return this.execBaseMethod((opt) => this.adapter.findMany(this.mergeWheresResolver.resolve(opt.see, {}), {
             ...opt,
             order: opt.order ?? this.defaultOrdering,
-        }), "getAll", options);
+        }), "getAll", options, "getAll");
     }
     /** Creates or updates (upsert) a record. */
     async save(obj, options) {
@@ -217,7 +219,7 @@ class VSRepository {
         if (!Array.isArray(pks)) {
             this.fail("'pks' must be a valid array", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
         }
-        return this.execBaseMethod(opt => this.adapter.deleteMany(this.mergeWheresResolver.resolve(opt.see, this.wherePkIn(pks)), opt), "removeList", options);
+        return this.execBaseMethod(opt => this.adapter.deleteMany(this.mergeWheresResolver.resolve(opt.see, this.wherePkIn(pks)), opt), "removeList", options, "restrict");
     }
     /** Partially updates an existing record by its primary key (PK). */
     async patch(pk, obj, options) {
@@ -233,11 +235,11 @@ class VSRepository {
     }
     /** Returns the total number of records. */
     async total(options) {
-        return this.execBaseMethod(opt => this.adapter.count(this.mergeWheresResolver.resolve(opt.see, {}), opt), "total", options);
+        return this.execBaseMethod(opt => this.adapter.count(this.mergeWheresResolver.resolve(opt.see, {}), opt), "total", options, "restrict");
     }
     /** Checks whether a record exists by its primary key (PK). */
     async has(pk, options) {
-        return this.execBaseMethod(opt => this.adapter.exists(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "has", options);
+        return this.execBaseMethod(opt => this.adapter.exists(this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "has", options, "restrict");
     }
     /** Marks a record as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
     async softRemove(pk, options) {
@@ -256,7 +258,7 @@ class VSRepository {
             this.fail("'pks' must be a valid array", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
         }
         const key = this.softRemoveKey;
-        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: new Date() }, opt), "softRemoveList", options);
+        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: new Date() }, opt), "softRemoveList", options, "restrict");
     }
     /** Restores a record previously marked as deleted (soft-delete). Requires `softRemoveKey` to be configured on the repository. */
     async restore(pk, options) {
@@ -275,7 +277,59 @@ class VSRepository {
             this.fail("'pks' must be a valid array", vsrepo_error_type_enum_1.VSRepoErrorType.BASE);
         }
         const key = this.softRemoveKey;
-        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: null }, opt), "restoreList", options);
+        return this.execBaseMethod(opt => this.adapter.updateMany(this.mergeWheresResolver.resolve(opt.see ?? "all", this.wherePkIn(pks)), { [key]: null }, opt), "restoreList", options, "restrict");
+    }
+    /**
+     * 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.
+     */
+    async increment(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.incrementOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "increment", options);
+    }
+    /** Same as {@link VSRepository.increment}, subtracting `value` instead of adding it. */
+    async decrement(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.decrementOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "decrement", options);
+    }
+    /** Same as {@link VSRepository.increment}, multiplying the field's current value by `value`. */
+    async multiply(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.multiplyOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "multiply", options);
+    }
+    /**
+     * 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}).
+     */
+    async divide(pk, field, value, options) {
+        this.validator.assertIsNumericLike(value);
+        return this.execBaseMethod(opt => this.adapter.divideOne(field, value, this.mergeWheresResolver.resolve(opt.see, this.wherePk(pk)), opt), "divide", options);
+    }
+    /**
+     * 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.
+     */
+    async sum(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.sum(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "sum", options, "restrict");
+    }
+    /** Same as {@link VSRepository.sum}, but the arithmetic mean instead of the total. */
+    async average(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.average(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "average", options, "restrict");
+    }
+    /** Same as {@link VSRepository.sum}, but the minimum value instead of the total. */
+    async min(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.min(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "min", options, "restrict");
+    }
+    /** Same as {@link VSRepository.sum}, but the maximum value instead of the total. */
+    async max(field, where, options) {
+        const validatedWhere = this.validator.validateWhere(where ?? {});
+        return this.execBaseMethod(opt => this.adapter.max(field, this.mergeWheresResolver.resolve(opt.see, validatedWhere), opt), "max", options, "restrict");
     }
 }
 exports.VSRepository = VSRepository;

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export type { VSRepoOptions } from "./types/vsrepo/vsrepo-options.type.js";
 export type { VSRepoOrmTypes } from "./types/vsrepo/vsrepo-orm-types.type.js";
 export type { VSRepoArgs } from "./types/vsrepo/vsrepo-args.type.js";
 export type { VSRepoMethod } from "./types/vsrepo/vsrepo-method.type.js";
-export type { VSRepoWhere, VSRepoWherePlain, VSRepoFieldWhere, VSRepoFieldOperators } from "./types/vsrepo/vsrepo-where.type.js";
+export type { VSRepoWhere, VSRepoWherePlain, VSRepoFieldWhere, VSRepoFieldOperators, } from "./types/vsrepo/vsrepo-where.type.js";
 export type { VSRepoRelations, RelationKeys } from "./types/vsrepo/vsrepo-relations.type.js";
 export type { VSRepoSelect } from "./types/vsrepo/vsrepo-select.type.js";
 export type { VSRepoTransactionOptions } from "./types/vsrepo/vsrepo-transaction-options.type.js";
@@ -31,4 +31,8 @@ export type { Pagination } from "./types/utils/pagination.type.js";
 export type { Primitive } from "./types/utils/primitive.type.js";
 export type { SeeMode } from "./types/utils/see-mode.type.js";
 export type { VSRepoQueryOptions } from "./types/vsrepo/vsrepo-query-options.type";
+export type { DecimalLike } from "./types/utils/decimal-like.type.js";
+export type { NumericKeys } from "./types/utils/numeric-keys.type.js";
+export type { NumericLike } from "./types/utils/numeric-like.type.js";
+export type { RestrictMethodOptions } from "./types/utils/restrict-method-options.type.js";
 export { VSLogger } from "./internal/utils/vs-logger.util.js";

package/dist/internal/validators/vsrepo.validator.d.ts

@@ -8,6 +8,8 @@ import { Ordering } from "../../types/utils/ordering.type";
 import { VSLogger } from "../utils/vs-logger.util";
 import { VSRepoWhere } from "../../types/vsrepo/vsrepo-where.type";
 import { VSRepoQueryOptions } from "../../types/vsrepo/vsrepo-query-options.type";
+import { NumericLike } from "../../types/utils/numeric-like.type";
+import { RestrictMethodOptions } from "../../types/utils/restrict-method-options.type";
 export declare class VSRepoValidator<T, K, O extends VSRepoOrmTypes = VSRepoOrmTypes> {
     private logger?;
     setLogger(logger: VSLogger): void;
@@ -16,6 +18,8 @@ export declare class VSRepoValidator<T, K, O extends VSRepoOrmTypes = VSRepoOrmT
     validateConstructorOptions(options: unknown): VSRepoOptions<T, K>;
     private readonly methodOptionsSchema;
     validateMethodOptions(options?: unknown): MethodOptions<T, O>;
+    private readonly restrictMethodOptionsSchema;
+    validateRestrictMethodOptions(options?: unknown): RestrictMethodOptions<T, O>;
     private readonly getAllMethodOptionsSchema;
     validateGetAllMethodOptions(options?: unknown): MethodOptions<T, O> & {
         pagination?: Pagination;
@@ -30,4 +34,7 @@ export declare class VSRepoValidator<T, K, O extends VSRepoOrmTypes = VSRepoOrmT
     validateOrdering(value: unknown): Ordering<T>;
     validatePagination(value: unknown): Pagination;
     validateWhere(value: unknown): VSRepoWhere<T>;
+    private decimalLikeSchema;
+    private numericLikeSchema;
+    assertIsNumericLike(value: unknown): asserts value is NumericLike;
 }

package/dist/internal/validators/vsrepo.validator.js

@@ -89,6 +89,17 @@ class VSRepoValidator {
         }
         return parsed.output;
     }
+    restrictMethodOptionsSchema = v.object({
+        db: v.optional(v.any()),
+        see: v.optional(v.picklist(["active", "removed", "all"])),
+    });
+    validateRestrictMethodOptions(options) {
+        const parsed = v.safeParse(this.restrictMethodOptionsSchema, options ?? {});
+        if (!parsed.success) {
+            this.failValidation(parsed.issues[0], vsrepo_error_type_enum_1.VSRepoErrorType.VALIDATOR);
+        }
+        return parsed.output;
+    }
     getAllMethodOptionsSchema = v.object({
         ...this.methodOptionsSchema.entries,
         order: v.optional(ordering_schema_1.default),
@@ -156,5 +167,16 @@ class VSRepoValidator {
         }
         return parsed.output;
     }
+    decimalLikeSchema = v.looseObject({
+        toNumber: v.function(),
+        decimalPlaces: v.function(),
+    });
+    numericLikeSchema = v.union([v.number(), v.bigint(), this.decimalLikeSchema]);
+    assertIsNumericLike(value) {
+        const parsed = v.safeParse(this.numericLikeSchema, value);
+        if (!parsed.success) {
+            this.failValidation(parsed.issues[0], vsrepo_error_type_enum_1.VSRepoErrorType.VALIDATOR);
+        }
+    }
 }
 exports.VSRepoValidator = VSRepoValidator;

package/dist/types/utils/decimal-like.type.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Structural shape of an arbitrary-precision "Decimal" value, as commonly
+ * returned by ORMs for `decimal`/`numeric` columns (e.g. Prisma's
+ * `Prisma.Decimal`, built on top of `decimal.js`).
+ *
+ * Matched structurally (duck-typed) instead of importing a concrete class,
+ * so the core stays ORM-agnostic — any object exposing both `toNumber()`
+ * and `decimalPlaces()` is treated as Decimal-like by {@link NumericLike}
+ * and, transitively, by {@link NumericKeys}.
+ *
+ * Note that several ORMs (e.g. Drizzle, MikroORM, TypeORM) represent
+ * `decimal`/`numeric` columns as plain `string` by default, to avoid
+ * floating-point precision loss — a `string` value does **not** satisfy
+ * `DecimalLike`. Configure the column in a numeric mode (or provide a
+ * transformer) on those ORMs if you want the field to be eligible for
+ * `increment`/`decrement`/`multiply`/`divide`/`sum`/`average`/`min`/`max`.
+ *
+ * @publicApi
+ */
+export type DecimalLike = {
+    toNumber(): number;
+    decimalPlaces(): number;
+};

package/dist/types/utils/decimal-like.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/utils/numeric-keys.type.d.ts

@@ -0,0 +1,24 @@
+import { NumericLike } from "./numeric-like.type";
+/**
+ * Extracts the keys of `T` whose (non-nullable) value type is assignable to
+ * {@link NumericLike} — i.e. the fields eligible as the `field` argument of
+ * `increment`/`decrement`/`multiply`/`divide`/`sum`/`average`/`min`/`max`.
+ *
+ * Nullable/optional numeric fields (e.g. `number | null`) ARE included —
+ * the `null`/`undefined` part is stripped before the check, it isn't a
+ * reason to exclude the field. This means a field that is currently `NULL`
+ * in the database can be targeted; be aware that in standard SQL, arithmetic
+ * against a `NULL` value (`NULL + 5`) itself stays `NULL` — this type only
+ * governs what compiles, not the row's runtime value.
+ *
+ * @example
+ * ```typescript
+ * type Product = { id: string; price: Decimal; stock: number | null; name: string };
+ * type Numeric = NumericKeys<Product>; // "price" | "stock"
+ * ```
+ *
+ * @publicApi
+ */
+export type NumericKeys<T> = {
+    [P in keyof T]: NonNullable<T[P]> extends NumericLike ? P : never;
+}[keyof T];

package/dist/types/utils/numeric-keys.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/utils/numeric-like.type.d.ts

@@ -0,0 +1,10 @@
+import { DecimalLike } from "./decimal-like.type";
+/**
+ * Union of value types accepted as "numeric" by the atomic
+ * (`increment`/`decrement`/`multiply`/`divide`) and aggregate
+ * (`sum`/`average`/`min`/`max`) operations: a native `number`, a native
+ * `bigint`, or a {@link DecimalLike} object.
+ *
+ * @publicApi
+ */
+export type NumericLike = number | bigint | DecimalLike;

package/dist/types/utils/numeric-like.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/utils/primitive.type.d.ts

@@ -1,6 +1,7 @@
+import { DecimalLike } from "./decimal-like.type";
 /**
  * Types treated as scalar (non-relation) values when walking an entity's shape.
  *
  * @publicApi
  */
-export type Primitive = string | number | boolean | bigint | symbol | undefined | null | Date;
+export type Primitive = string | number | boolean | bigint | symbol | undefined | null | Date | DecimalLike;

package/dist/types/utils/restrict-method-options.type.d.ts

@@ -0,0 +1,14 @@
+import { VSRepoOrmTypes } from "../vsrepo/vsrepo-orm-types.type";
+import { MethodOptions } from "./methods-options.type";
+/**
+ * Narrowed variant of {@link MethodOptions} exposing only `db` and `see`.
+ *
+ * Used by base methods that don't shape/return an `Entity` — count-like
+ * operations (`total`, `has`, `sum`, `average`, `min`, `max`) and
+ * batch-delete-like operations (`removeList`, `softRemoveList`,
+ * `restoreList`) — where `select`/`relations` (which only make sense when
+ * an `Entity` is being returned) don't apply.
+ *
+ * @publicApi
+ */
+export type RestrictMethodOptions<T, O extends VSRepoOrmTypes = VSRepoOrmTypes> = Pick<MethodOptions<T, O>, "db" | "see">;

package/dist/types/utils/restrict-method-options.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vsrepo",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "ORM-agnostic repository pattern library with full TypeScript support and automatic type inference.",
   "homepage": "https://github.com/jaobrabo123/VSRepository#readme",
   "repository": {