@vsrepo/prisma7-adapter 1.0.3 → 1.1.0

package/README.md

@@ -33,6 +33,7 @@
     - [How each write method resolves relations](#how-each-write-method-resolves-relations)
   - [`relations` in method options (read)](#relations-in-method-options-read)
 - [`merge`](#merge)
+- [Atomic and aggregation methods](#atomic-and-aggregation-methods)
 - [`createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` don't support nested writes](#createmanycreatemanyreturningupdatemanyupdatemanyreturning-dont-support-nested-writes)
 - [Provider-specific limitations](#provider-specific-limitations)
 - [Transactions](#transactions)
@@ -197,6 +198,31 @@ const prismaInclude = prismaSelect
 
 For to-many relations (`otm`/`mtm`), items in the stored record and items in `obj` are matched by the configured `pk`: a match merges the two items, a new `pk` (or no `pk`) is appended. Nothing is ever removed by `merge`.
 
+## Atomic and aggregation methods
+
+> Requires `vsrepo` **2.1.0+** — these methods were added to the `VSRepoAdapter` contract in that release (see the [VSRepository CHANGELOG](https://github.com/jaobrabo123/VSRepository/blob/main/CHANGELOG.md#210---2026-09-04)).
+
+The adapter implements the 8 abstract methods `VSRepository`'s `increment`/`decrement`/`multiply`/`divide`/`sum`/`average`/`min`/`max` delegate to: `incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max`.
+
+- `incrementOne`/`decrementOne`/`multiplyOne`/`divideOne` translate directly into Prisma's native single-field atomic write — `data: { [field]: { increment: value } }` (and `decrement`/`multiply`/`divide`) — so the operation is evaluated **server-side** against the row's *current* value (`UPDATE ... SET field = field + value`), not as a fetch-then-save round trip on the client. Prisma's `update()` already returns the row reflecting the state *after* the write, so the adapter never issues a follow-up read.
+- `sum`/`average`/`min`/`max` translate into Prisma's `aggregate()` with `_sum`/`_avg`/`_min`/`_max: { [field]: true }`. The raw result (`number`, `bigint`, a `Decimal` instance, or `null`) is normalized to `number | null` — `null` is returned as-is (mirroring SQL's `SUM()`/`AVG()`/`MIN()`/`MAX()`, which return `NULL`, not `0`, over an empty set), and a `Decimal`/`DecimalLike` value is converted via its `.toNumber()`.
+
+```typescript
+// Atomic — evaluated server-side, no read-modify-write:
+await productRepository.increment(productId, "stock", 10);
+await accountRepository.decrement(accountId, "balance", 50);
+await productRepository.multiply(productId, "price", 1.1); // e.g. a 10% price bump
+await productRepository.divide(productId, "price", 2);
+
+// Aggregation — across every record matching an optional `where` (all if omitted):
+const total = await productRepository.sum("price"); // number | null
+const avgPrice = await productRepository.average("price", { active: true });
+const cheapest = await productRepository.min("price");
+const mostExpensive = await productRepository.max("price");
+```
+
+**Decimal fields** (`Prisma.Decimal`) are fully supported as the `field` for all 8 methods — `value` for the atomic methods is passed straight through to Prisma (which accepts a `number`, `string`, or `Decimal`/`DecimalJsLike`), and the aggregate methods always normalize the result to a `number`, never a `Decimal` instance.
+
 ## `createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` don't support nested writes
 
 `createMany`, `createManyReturning`, `updateMany` and `updateManyReturning` only accept scalar fields in their `data`. If your payload includes a field configured in `relations` (regardless of its value), the adapter throws a `VSRepoPrisma7AdapterError` naming the offending field. For a full nested write, use `create`/`update`/`save` one record at a time, or wrap several `save` calls in a `saveMany`/`transaction`.
@@ -272,5 +298,5 @@ The adapter uses `VSLogger` (from `vsrepo`) internally: every method logs a `DEB
 
 ## Requirements
 
-- `vsrepo` v2
+- `vsrepo` ^2.1.0
 - `@prisma/client` ^7.10.0

package/README.pt-BR.md

@@ -33,6 +33,7 @@ Implementação de `VSRepoAdapter` para o [VSRepository v2](https://github.com/j
     - [Como cada método de escrita resolve relations](#como-cada-método-de-escrita-resolve-relations)
   - [`relations` nas options (leitura)](#relations-nas-options-leitura)
 - [`merge`](#merge)
+- [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação)
 - [`createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` não suportam nested writes](#createmanycreatemanyreturningupdatemanyupdatemanyreturning-não-suportam-nested-writes)
 - [Limitações por provider](#limitações-por-provider)
 - [Transactions](#transactions)
@@ -197,6 +198,31 @@ const prismaInclude = prismaSelect
 
 Pra relations to-many (`otm`/`mtm`), os itens do registro salvo e os itens de `obj` são casados pela `pk` configurada: um match faz merge dos dois itens, uma `pk` nova (ou sem `pk`) é apenas adicionada. `merge` nunca remove nada.
 
+## Métodos atômicos e de agregação
+
+> Requer `vsrepo` **2.1.0+** — esses métodos foram adicionados ao contrato do `VSRepoAdapter` nessa versão (veja o [CHANGELOG do VSRepository](https://github.com/jaobrabo123/VSRepository/blob/main/CHANGELOG.md#210---2026-09-04-português)).
+
+O adapter implementa os 8 métodos abstratos pros quais `increment`/`decrement`/`multiply`/`divide`/`sum`/`average`/`min`/`max` do `VSRepository` delegam: `incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max`.
+
+- `incrementOne`/`decrementOne`/`multiplyOne`/`divideOne` traduzem direto pra escrita atômica nativa de campo único do Prisma — `data: { [field]: { increment: value } }` (e `decrement`/`multiply`/`divide`) — então a operação é avaliada **server-side** contra o valor *atual* do registro (`UPDATE ... SET field = field + value`), e não como um fetch-then-save no cliente. O `update()` do Prisma já retorna a linha refletindo o estado *após* a escrita, então o adapter nunca precisa fazer uma leitura extra.
+- `sum`/`average`/`min`/`max` traduzem pro `aggregate()` do Prisma, com `_sum`/`_avg`/`_min`/`_max: { [field]: true }`. O resultado bruto (`number`, `bigint`, uma instância de `Decimal`, ou `null`) é normalizado pra `number | null` — `null` é repassado como está (espelhando o `SUM()`/`AVG()`/`MIN()`/`MAX()` do SQL, que retornam `NULL`, não `0`, sobre um conjunto vazio), e um valor `Decimal`/`DecimalLike` é convertido via seu `.toNumber()`.
+
+```typescript
+// Atômico — avaliado server-side, sem read-modify-write:
+await productRepository.increment(productId, "stock", 10);
+await accountRepository.decrement(accountId, "balance", 50);
+await productRepository.multiply(productId, "price", 1.1); // ex: um reajuste de 10% no preço
+await productRepository.divide(productId, "price", 2);
+
+// Agregação — entre todos os registros que casam com um `where` opcional (todos se omitido):
+const total = await productRepository.sum("price"); // number | null
+const avgPrice = await productRepository.average("price", { active: true });
+const cheapest = await productRepository.min("price");
+const mostExpensive = await productRepository.max("price");
+```
+
+**Campos Decimal** (`Prisma.Decimal`) são totalmente suportados como o `field` dos 8 métodos — o `value` dos métodos atômicos é repassado direto pro Prisma (que aceita `number`, `string`, ou `Decimal`/`DecimalJsLike`), e os métodos de agregação sempre normalizam o resultado pra `number`, nunca uma instância de `Decimal`.
+
 ## `createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` não suportam nested writes
 
 `createMany`, `createManyReturning`, `updateMany` e `updateManyReturning` só aceitam campos escalares no `data`. Se seu payload incluir um campo configurado em `relations` (independente do valor), o adapter lança um `VSRepoPrisma7AdapterError` apontando o campo problemático. Pra um nested write completo, use `create`/`update`/`save` registro por registro, ou envolva várias chamadas de `save` num `saveMany`/`transaction`.
@@ -272,5 +298,5 @@ O adapter usa o `VSLogger` (de `vsrepo`) internamente: todo método loga uma lin
 
 ## Requisitos
 
-- `vsrepo` v2
+- `vsrepo` ^2.1.0
 - `@prisma/client` ^7.10.0

package/dist/prisma7.adapter.d.ts

@@ -1,4 +1,4 @@
-import { AdapterMethodOptions, AdapterQueryOptions, CountResult, DeepPartial, VSRepoAdapter, VSRepoWhere } from "vsrepo";
+import { AdapterMethodOptions, AdapterQueryOptions, CountResult, DeepPartial, NumericKeys, VSRepoAdapter, VSRepoWhere } from "vsrepo";
 import { VSRepoPrisma7AdapterConfig } from "./types/adapter-config.type";
 /**
  * `VSRepoAdapter` implementation for Prisma 7. Translates every method of the
@@ -50,6 +50,35 @@ export declare class VSRepoPrisma7Adapter<T> extends VSRepoAdapter<T> {
      * started on it (or on `this.prisma` when `db` isn't provided at all).
      */
     private runTransactional;
+    /**
+     * Runs a single-field atomic update (`increment`/`decrement`/`multiply`/
+     * `divide`) via Prisma's native `{ field: { <op>: value } }` write —
+     * evaluated server-side against the row's current value, never as a
+     * client-side read-modify-write. `value` is passed through as-is:
+     * Prisma accepts a `number`, `bigint`, or any `Decimal`/`DecimalJsLike`
+     * value (which covers a {@link DecimalLike} like `Prisma.Decimal`)
+     * depending on the target column's type.
+     *
+     * Prisma's `update()` already returns the row reflecting the state
+     * *after* the write, so no follow-up read is needed here.
+     */
+    private atomicUpdate;
+    /**
+     * Converts a raw value returned by Prisma's `aggregate()` (`number`,
+     * `bigint`, a `Decimal` instance, or `null` when no record matches)
+     * into the `number | null` shape required by the `VSRepoAdapter`
+     * aggregate contract.
+     */
+    private toNullableNumber;
+    /**
+     * Runs a single-field aggregation (`sum`/`avg`/`min`/`max`) via Prisma's
+     * `aggregate()`, across every record matching `where` (all records if
+     * empty). Returns `null` when no record matches — mirroring SQL's
+     * `SUM()`/`AVG()`/`MIN()`/`MAX()`, which return `NULL` (not `0`) over an
+     * empty set — instead of Prisma's own `_sum`/`_avg`/`_min`/`_max: null`
+     * shape.
+     */
+    private aggregate;
     /** Returns the underlying ORM client instance used outside of transactions. */
     getDbClient(): any;
     /** Runs `fn` inside a native transaction of the underlying ORM/database. */
@@ -130,4 +159,32 @@ export declare class VSRepoPrisma7Adapter<T> extends VSRepoAdapter<T> {
     merge<K>(where: VSRepoWhere<T>, obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<K & T>;
     /** Creates a record if none matches `where`, otherwise updates it. */
     upsert(where: VSRepoWhere<T>, create: DeepPartial<T>, update: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Atomically adds `value` to `field` on the record matching `where`,
+     * via Prisma's native `{ field: { increment: value } }` write.
+     */
+    incrementOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Same as {@link VSRepoPrisma7Adapter.incrementOne}, subtracting `value` instead of adding it. */
+    decrementOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /** Same as {@link VSRepoPrisma7Adapter.incrementOne}, multiplying the field's current value by `value`. */
+    multiplyOne<K extends NumericKeys<T>>(field: K, value: NonNullable<T[K]>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    /**
+     * Same as {@link VSRepoPrisma7Adapter.incrementOne}, dividing the
+     * field's current value by `value`. Division-by-zero is not handled by
+     * the adapter — it's whatever Postgres does natively (raises a
+     * `division_by_zero` error for integer columns; `Infinity`/`NaN` are not
+     * representable in a numeric/decimal column, so those also error).
+     */
+    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 empty), or `null` if no record matches.
+     */
+    sum(field: NumericKeys<T>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoPrisma7Adapter.sum}, but the arithmetic mean instead of the total. */
+    average(field: NumericKeys<T>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoPrisma7Adapter.sum}, but the minimum value instead of the total. */
+    min(field: NumericKeys<T>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
+    /** Same as {@link VSRepoPrisma7Adapter.sum}, but the maximum value instead of the total. */
+    max(field: NumericKeys<T>, where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number | null>;
 }

package/dist/prisma7.adapter.js

@@ -106,6 +106,79 @@ class VSRepoPrisma7Adapter extends vsrepo_1.VSRepoAdapter {
         }
         return (db ?? this.prisma).$transaction(fn);
     }
+    /**
+     * Runs a single-field atomic update (`increment`/`decrement`/`multiply`/
+     * `divide`) via Prisma's native `{ field: { <op>: value } }` write —
+     * evaluated server-side against the row's current value, never as a
+     * client-side read-modify-write. `value` is passed through as-is:
+     * Prisma accepts a `number`, `bigint`, or any `Decimal`/`DecimalJsLike`
+     * value (which covers a {@link DecimalLike} like `Prisma.Decimal`)
+     * depending on the target column's type.
+     *
+     * Prisma's `update()` already returns the row reflecting the state
+     * *after* the write, so no follow-up read is needed here.
+     */
+    async atomicUpdate(operation, field, value, where, options) {
+        const start = this.logger.startPerformLog(`run ${operation}One`);
+        try {
+            const arg = {
+                ...this.resolveReadArg(options),
+                where: (0, where_parser_1.parsePrismaWhere)(where),
+                data: { [field]: { [operation]: value } },
+            };
+            this.logger.logDebug(`Resolved Prisma arg for '${operation}One'`, arg);
+            return await this.getPrismaRepository(options?.db).update(arg);
+        }
+        catch (error) {
+            throw (0, map_prisma_error_resolver_1.mapPrismaError)(error, `${operation}One`);
+        }
+        finally {
+            this.logger.endPerformLog(start);
+        }
+    }
+    /**
+     * Converts a raw value returned by Prisma's `aggregate()` (`number`,
+     * `bigint`, a `Decimal` instance, or `null` when no record matches)
+     * into the `number | null` shape required by the `VSRepoAdapter`
+     * aggregate contract.
+     */
+    toNullableNumber(value) {
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value === "bigint")
+            return Number(value);
+        if (typeof value?.toNumber === "function") {
+            return value.toNumber();
+        }
+        return Number(value);
+    }
+    /**
+     * Runs a single-field aggregation (`sum`/`avg`/`min`/`max`) via Prisma's
+     * `aggregate()`, across every record matching `where` (all records if
+     * empty). Returns `null` when no record matches — mirroring SQL's
+     * `SUM()`/`AVG()`/`MIN()`/`MAX()`, which return `NULL` (not `0`) over an
+     * empty set — instead of Prisma's own `_sum`/`_avg`/`_min`/`_max: null`
+     * shape.
+     */
+    async aggregate(operation, field, where, options) {
+        const start = this.logger.startPerformLog(`run ${operation}`);
+        const aggKey = `_${operation}`;
+        try {
+            const arg = {
+                where: (0, where_parser_1.parsePrismaWhere)(where),
+                [aggKey]: { [field]: true },
+            };
+            this.logger.logDebug(`Resolved Prisma arg for '${operation}'`, arg);
+            const result = await this.getPrismaRepository(options?.db).aggregate(arg);
+            return this.toNullableNumber(result?.[aggKey]?.[field]);
+        }
+        catch (error) {
+            throw (0, map_prisma_error_resolver_1.mapPrismaError)(error, operation);
+        }
+        finally {
+            this.logger.endPerformLog(start);
+        }
+    }
     /** Returns the underlying ORM client instance used outside of transactions. */
     getDbClient() {
         return this.prisma;
@@ -509,5 +582,49 @@ class VSRepoPrisma7Adapter extends vsrepo_1.VSRepoAdapter {
             this.logger.endPerformLog(start);
         }
     }
+    /**
+     * Atomically adds `value` to `field` on the record matching `where`,
+     * via Prisma's native `{ field: { increment: value } }` write.
+     */
+    async incrementOne(field, value, where, options) {
+        return this.atomicUpdate("increment", field, value, where, options);
+    }
+    /** Same as {@link VSRepoPrisma7Adapter.incrementOne}, subtracting `value` instead of adding it. */
+    async decrementOne(field, value, where, options) {
+        return this.atomicUpdate("decrement", field, value, where, options);
+    }
+    /** Same as {@link VSRepoPrisma7Adapter.incrementOne}, multiplying the field's current value by `value`. */
+    async multiplyOne(field, value, where, options) {
+        return this.atomicUpdate("multiply", field, value, where, options);
+    }
+    /**
+     * Same as {@link VSRepoPrisma7Adapter.incrementOne}, dividing the
+     * field's current value by `value`. Division-by-zero is not handled by
+     * the adapter — it's whatever Postgres does natively (raises a
+     * `division_by_zero` error for integer columns; `Infinity`/`NaN` are not
+     * representable in a numeric/decimal column, so those also error).
+     */
+    async divideOne(field, value, where, options) {
+        return this.atomicUpdate("divide", field, value, where, options);
+    }
+    /**
+     * Returns the sum of `field` across every record matching `where` (all
+     * records if `where` is empty), or `null` if no record matches.
+     */
+    async sum(field, where, options) {
+        return this.aggregate("sum", field, where, options);
+    }
+    /** Same as {@link VSRepoPrisma7Adapter.sum}, but the arithmetic mean instead of the total. */
+    async average(field, where, options) {
+        return this.aggregate("avg", field, where, options);
+    }
+    /** Same as {@link VSRepoPrisma7Adapter.sum}, but the minimum value instead of the total. */
+    async min(field, where, options) {
+        return this.aggregate("min", field, where, options);
+    }
+    /** Same as {@link VSRepoPrisma7Adapter.sum}, but the maximum value instead of the total. */
+    async max(field, where, options) {
+        return this.aggregate("max", field, where, options);
+    }
 }
 exports.VSRepoPrisma7Adapter = VSRepoPrisma7Adapter;

package/dist/types/prisma-repository-like.type.d.ts

@@ -2,6 +2,12 @@ import { PrismaArgLike } from "./prisma-arg-like.type";
 type AnyFn = (arg: PrismaArgLike) => Promise<any>;
 /** `count` do Prisma resolve pra um `number` (na forma simples, sem `select` de agregação). */
 type CountFn = (arg: PrismaArgLike) => Promise<number>;
+/**
+ * `aggregate` do Prisma resolve pra um objeto com uma chave por operação
+ * pedida (`_sum`/`_avg`/`_min`/`_max`/`_count`), cada uma mapeando campo ->
+ * valor agregado (`number | bigint | Decimal | null`).
+ */
+type AggregateFn = (arg: PrismaArgLike & Record<string, Record<string, boolean>>) => Promise<Record<string, Record<string, unknown> | undefined>>;
 export type PrismaRepositoryLike = {
     findFirst: AnyFn;
     findFirstOrThrow: AnyFn;
@@ -16,5 +22,6 @@ export type PrismaRepositoryLike = {
     delete: AnyFn;
     deleteMany: AnyFn;
     count: CountFn;
+    aggregate: AggregateFn;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsrepo/prisma7-adapter",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "VSRepository adapter implementation backed by Prisma 7, translating every VSRepository operation into Prisma Client calls.",
   "homepage": "https://github.com/jaobrabo123/VSRepoPrisma7Adapter#readme",
   "repository": {
@@ -49,7 +49,7 @@
   "license": "MIT",
   "peerDependencies": {
     "@prisma/client": "^7.10.0",
-    "vsrepo": "^2.0.0"
+    "vsrepo": "^2.1.0"
   },
   "dependencies": {
     "deepmerge": "^4.3.1",