@vsrepo/prisma7-adapter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Pedro Azevedo Freire Mecenas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+<div align="center">
+  <img src="https://res.cloudinary.com/ddbfifdxd/image/upload/w_200,q_auto,f_auto/v1786386427/VS_logo_TextoAbaixo_yev4tq.png" alt="VSRepository Logo" width="200"/>
+
+  <p style="margin-top: 12px;">
+    <img src="https://img.shields.io/npm/v/@vsrepo/prisma7-adapter?style=flat-square" alt="npm version"/>
+    <img src="https://img.shields.io/npm/l/@vsrepo/prisma7-adapter?style=flat-square" alt="npm license"/>
+    <img src="https://img.shields.io/npm/dt/@vsrepo/prisma7-adapter?style=flat-square" alt="npm downloads"/>
+    <img src="https://img.shields.io/badge/inspired%20by-JpaRepository-E73121?style=flat-square" alt="inspired by JpaRepository"/>
+  </p>
+</div>
+
+# VSRepoPrisma7Adapter
+
+🇧🇷 [Ler em português](./README.pt-BR.md)
+
+> ✅ **Released.** This adapter is published to npm as `@vsrepo/prisma7-adapter`, targeting [VSRepository](https://github.com/jaobrabo123/VSRepository). It's currently the only officially published adapter for v2 — adapters for other ORMs are planned but not published yet (see [Adapter status](https://github.com/jaobrabo123/VSRepository#adapter-status) in the VSRepository README).
+
+`VSRepoAdapter` implementation for [VSRepository v2](https://github.com/jaobrabo123/VSRepository) backed by [Prisma 7](https://www.prisma.io/). It translates every `VSRepository` operation into Prisma Client calls, resolving `VSRepoWhere`, `Ordering`, `select`/`relations` through dedicated parsers, and — when a `relations` config is provided — resolving relation fields on `create`/`update`/`upsert`/`merge` the same way the v1 of VSRepository used to.
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Basic usage](#basic-usage)
+- [Constructor config](#constructor-config)
+- [Relations](#relations)
+  - [The two `relations`](#the-two-relations)
+  - [`relations` in the constructor (write)](#relations-in-the-constructor-write)
+    - [`mode`](#mode)
+    - [`restriction`](#restriction)
+    - [`pk` and `nullable`](#pk-and-nullable)
+    - [How each write method resolves relations](#how-each-write-method-resolves-relations)
+  - [`relations` in method options (read)](#relations-in-method-options-read)
+- [`merge`](#merge)
+- [`createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` don't support nested writes](#createmanycreatemanyreturningupdatemanyupdatemanyreturning-dont-support-nested-writes)
+- [Transactions](#transactions)
+- [Logging](#logging)
+- [Requirements](#requirements)
+
+---
+
+## Installation
+
+```bash
+npm install vsrepo @prisma/client @vsrepo/prisma7-adapter
+```
+
+Both `vsrepo` and `@vsrepo/prisma7-adapter` are published to npm and ready to use.
+
+## Basic usage
+
+```typescript
+import { VSRepository, VSLogLevel } from "vsrepo";
+import { VSRepoPrisma7Adapter, Prisma7OrmTypes } from "@vsrepo/prisma7-adapter";
+import { Prisma, PrismaClient } from "./generated/prisma/client";
+import { prisma } from "./prisma";
+
+type User = Prisma.UserGetPayload<{ include: { posts: true } }>;
+type MyOrmTypes = Prisma7OrmTypes<PrismaClient, Prisma.TransactionClient>;
+
+class UserRepository extends VSRepository<User, string, MyOrmTypes> {
+    constructor() {
+        super({
+            adapter: new VSRepoPrisma7Adapter(prisma, {
+                tableName: "user",
+                pkName: "id",
+                relations: {
+                    posts: { mode: "otm", restriction: "add", pk: "id" },
+                },
+                logLevel: VSLogLevel.WARN,
+            }),
+            pkName: "id",
+        });
+    }
+}
+
+const userRepository = new UserRepository();
+
+const user = await userRepository.get({ id: "..." }, { relations: { posts: true } });
+```
+
+Here the `relations` you pass in the method `options` — shaped like `{ field: true }` — is transformed into a Prisma `include` by the adapter (see [`relations` in method options (read)](#relations-in-method-options-read)). If you supply `select`, the `relations`/`include` is ignored. Don't confuse it with the constructor-config `relations`, which describes how relation fields are resolved in write payloads — the difference is explained in [The two `relations`](#the-two-relations).
+
+`Prisma7OrmTypes<DB, TX>` ties `VSRepository`'s `getDbClient()`/`transaction()` return types to your real, generated Prisma types — see [Transactions](#transactions).
+
+## Constructor config
+
+```typescript
+new VSRepoPrisma7Adapter(prisma, {
+    tableName: "user", // required — the Prisma Client model/delegate name, as in `prisma.user`
+    pkName: "id",       // required — the entity's primary key field name
+    relations: { ... }, // optional — see "relations in the constructor (write)" below
+    logLevel: VSLogLevel.WARN, // optional — default: VSLogLevel.WARN
+});
+```
+
+The config is validated with [valibot](https://valibot.dev/) — an invalid `tableName`/`pkName`/`relations`/`logLevel` throws a `VSRepoPrisma7AdapterError` naming the offending field.
+
+## Relations
+
+### The two `relations`
+
+The name `relations` appears in **two different places** in the API, with **different shapes and purposes** — easy to confuse. In a nutshell:
+
+| | `relations` in the **constructor** | `relations` in **method options** |
+| --- | --- | --- |
+| Where you define it | `new VSRepoPrisma7Adapter(prisma, { relations: ... })` | `repository.get(where, { relations: ... })` — and other methods |
+| Shape | One **config object** per field: `{ mode, restriction, pk, nullable? }` | One **`true`/sub-object** per field: `{ posts: true }` |
+| Purpose | **Write** — when a `create`/`update`/`upsert`/`save`/`merge` payload contains a relation field, tells the adapter how to turn it into a Prisma nested write (`create`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) | **Read** — eager loading: which relations to fetch alongside the result (becomes a Prisma `include`) |
+| Consumed by | `parsePrismaWriteData` / `mergeEntities` (write resolvers) | `parsePrismaInclude` (via `resolveReadArg`) |
+| Depends on the other? | No — it only affects writes/`merge` | No — it works even with no `relations` in the constructor |
+
+Neither depends on the other: the method-options `relations` does eager loading even when the constructor has no `relations`, and the constructor `relations` governs write behavior even if you never pass `relations` in options. The two subsections below cover each one.
+
+### `relations` in the constructor (write)
+
+The `relations` config on the constructor describes, for each relation field of your entity, **how the adapter should resolve that field when it shows up in write payloads** (`create`/`update`/`upsert`/`save`/`merge`) — the same behavior the v1 of VSRepository had.
+
+Each relation is configured by its field name:
+
+```typescript
+relations: {
+    posts: { mode: "otm", restriction: "add", pk: "id" },
+    address: { mode: "oto", restriction: "set", pk: "id" },
+    author: { mode: "mto", restriction: "set", pk: "id", nullable: true },
+}
+```
+
+Without `relations`, every field — including relation fields — is passed straight through to Prisma's `where`/`data`/`create`/`update`, as-is. That's fine for scalar fields, but Prisma expects a very specific nested-write shape (`create`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) for relation fields, so if your entity has relations you'll usually want to configure them.
+
+#### `mode`
+
+Cardinality of the relation, from the point of view of the entity that owns the field:
+
+| `mode` | Meaning | Field shape you send |
+| --- | --- | --- |
+| `oto` | one-to-one | a single object, or `null` |
+| `mto` | many-to-one | a single object, or `null` |
+| `otm` | one-to-many | an array of objects |
+| `mtm` | many-to-many | an array of objects |
+
+#### `restriction`
+
+Controls how `save`/`update`/`upsert` handle relation items that already exist (matched by `pk`) and, for to-many relations, items that were **not** included in the payload:
+
+- **`"add"`** — only creates/connects/upserts the items you send. Existing items that aren't in the payload are left untouched.
+- **`"set"`** — same as `"add"`, but also removes what wasn't sent: for `otm` it runs a `deleteMany` on the items missing from the array; for `mtm` it resets the join (`set: []`) before reconnecting; for `oto`/`mto` sending `null` disconnects/deletes the relation (see below).
+
+#### `pk` and `nullable`
+
+- **`pk`** — the field used to identify an existing related record. An item **with** `pk` in the payload becomes a `connectOrCreate`/`upsert`; an item **without** it becomes a plain `create`.
+- **`nullable`** — only relevant for `mto`. When `true`, sending `null` for the field resolves to `disconnect` on update. For `oto` with `restriction: "set"`, sending `null` resolves to `delete` instead (an `oto` side can't just be "disconnected", the owned row is removed).
+
+#### How each write method resolves relations
+
+| Method | Relations |
+| --- | --- |
+| `create` | `create`/`connectOrCreate` only (no upsert — there's nothing to update yet) |
+| `update` / `upsert` (`update` half) / `save` (upsert branch) | Full resolution: `create`/`connectOrCreate`/`upsert`/`disconnect`/`delete`/`deleteMany`/`set`, per `mode`/`restriction` |
+| `createMany` / `createManyReturning` / `updateMany` / `updateManyReturning` | Not supported — throws a `VSRepoPrisma7AdapterError` naming the offending field if the payload contains a configured relation |
+
+### `relations` in method options (read)
+
+This is the `relations` you pass in the `options` of a `VSRepository` method (`get`, `find`, `findOne`, etc.). The shape is much simpler: an object where each relation field accepts:
+
+- `true` — load the relation as-is;
+- or another `relations` object — for nested eager loading (relations of the relation).
+
+```typescript
+const user = await userRepository.get(
+    { id: "..." },
+    {
+        relations: {
+            posts: true,                   // fetch posts along
+            author: { profile: true },     // and, inside author, its profile (nested eager loading)
+        },
+    }
+);
+```
+
+This object is turned into a Prisma `include` by the adapter (`parsePrismaInclude`). It does **not** use the constructor's `relations` config: it's purely a read-side option and works even with no `relations` in the config.
+
+The `select` and `relations` you pass in the options are turned into a Prisma `select` (`parsePrismaSelect`) and a Prisma `include` (`parsePrismaInclude`), respectively. When `select` is provided, the `include` derived from `relations` is discarded (`undefined`), because Prisma doesn't allow combining `include` and `select` in a single query. In other words, if you're already using `select`, the `relations` object becomes redundant — so it's optional. Here's the resolved logic (from `resolveReadArg`):
+
+```ts
+const prismaSelect = options.select && parsePrismaSelect(options.select);
+const prismaInclude = prismaSelect
+    ? undefined
+    : options.relations && parsePrismaInclude(options.relations);
+```
+
+## `merge`
+
+`merge(where, obj, options)` fetches the record matching `where` and returns it **deep-merged, in memory**, with `obj` — it does **not** write anything to the database. This mirrors how `merge` worked in the v1 of VSRepository: it's meant to build a full, merged entity that you then pass to `save`/`update` yourself, not to persist a partial update directly.
+
+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`.
+
+## `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`.
+
+> Note on return order: `createManyReturning` don't guarantee the returned records follow the order of the input payload (`objs`). Their result comes from a second `findMany` (re-querying the inserted/updated rows by primary key), so the order is only guaranteed when you pass `order` in the options.
+
+## Transactions
+
+**Every** method accepts `options.db` and runs its operation on the client/transaction you pass — the difference is in **how** each one treats it:
+
+- Most methods (single, one-call Prisma operations) simply run directly on `options?.db`: hand them a transaction client and the call participates in that transaction, starting nothing new.
+- `saveMany`, `updateManyReturning`, `createManyReturning` and `deleteManyReturning` need to run **more than one** Prisma operation atomically (`saveMany` saves each record individually; `updateManyReturning`/`createManyReturning` do an `updateManyAndReturn`/`createManyAndReturn` + `findMany`; `deleteManyReturning` does a `findMany` + `deleteMany`), so they go through `runTransactional`. If `options.db` is already an active transaction client, it's reused — no nested transaction is started; otherwise, a new transaction is created (on `options.db` if provided, or on the root client otherwise).
+
+A transaction client is told apart from the root `PrismaClient` by the `$on` method: Prisma's root client exposes it (for event listeners), the interactive transaction client doesn't. This is what `Prisma7ClientLike`/`Prisma7OrmTypes` encode in their types.
+
+```typescript
+await userRepository.transaction(async tx => {
+    // Every repository call made with `{ db: tx }` inside this callback
+    // shares the same transaction — including calls to `saveMany`/
+    // `updateManyReturning`/`createManyReturning`/`deleteManyReturning`, which
+    // will detect `tx` is already a transaction and run directly on it instead
+    // of nesting a new one.
+    await userRepository.save(user, { db: tx });
+    await userRepository.saveList(otherUsers, { db: tx });
+});
+```
+
+## Logging
+
+The adapter uses `VSLogger` (from `vsrepo`) internally: every method logs a `DEBUG` line with the resolved Prisma arg, and start/end performance logs (surfacing a `WARN` for slow operations). Set `logLevel` in the constructor config to control verbosity; it defaults to `VSLogLevel.WARN`.
+
+## Requirements
+
+- `vsrepo` v2
+- `@prisma/client` ^7.10.0

package/README.pt-BR.md

@@ -0,0 +1,233 @@
+<div align="center">
+  <img src="https://res.cloudinary.com/ddbfifdxd/image/upload/w_200,q_auto,f_auto/v1786386427/VS_logo_TextoAbaixo_yev4tq.png" alt="VSRepository Logo" width="200"/>
+
+  <p style="margin-top: 12px;">
+    <img src="https://img.shields.io/npm/v/@vsrepo/prisma7-adapter?style=flat-square" alt="npm version"/>
+    <img src="https://img.shields.io/npm/l/@vsrepo/prisma7-adapter?style=flat-square" alt="npm license"/>
+    <img src="https://img.shields.io/npm/dt/@vsrepo/prisma7-adapter?style=flat-square" alt="npm downloads"/>
+    <img src="https://img.shields.io/badge/inspired%20by-JpaRepository-E73121?style=flat-square" alt="inspired by JpaRepository"/>
+  </p>
+</div>
+
+# VSRepoPrisma7Adapter
+
+🇺🇸 [Read in English](./README.md)
+
+> ✅ **Lançado.** Este adapter já foi publicado no npm como `@vsrepo/prisma7-adapter`, feito para o [VSRepository](https://github.com/jaobrabo123/VSRepository). Por enquanto é o único adapter oficial publicado para a v2 — adapters para outros ORMs estão planejados, mas ainda não foram publicados (veja [Status dos adapters](https://github.com/jaobrabo123/VSRepository/blob/main/README.pt-BR.md#status-dos-adapters) no README do VSRepository).
+
+Implementação de `VSRepoAdapter` para o [VSRepository v2](https://github.com/jaobrabo123/VSRepository) usando [Prisma 7](https://www.prisma.io/). Traduz toda operação do `VSRepository` em chamadas do Prisma Client, resolvendo `VSRepoWhere`, `Ordering`, `select`/`relations` através de parsers dedicados e — quando uma config de `relations` é fornecida — resolvendo campos de relação em `create`/`update`/`upsert`/`merge` da mesma forma que a v1 do VSRepository fazia.
+
+---
+
+## Sumário
+
+- [Instalação](#instalação)
+- [Uso básico](#uso-básico)
+- [Config do construtor](#config-do-construtor)
+- [Relations](#relations)
+  - [Os dois `relations`](#os-dois-relations)
+  - [`relations` no construtor (escrita)](#relations-no-construtor-escrita)
+    - [`mode`](#mode)
+    - [`restriction`](#restriction)
+    - [`pk` e `nullable`](#pk-e-nullable)
+    - [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)
+- [`createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` não suportam nested writes](#createmanycreatemanyreturningupdatemanyupdatemanyreturning-não-suportam-nested-writes)
+- [Transactions](#transactions)
+- [Logging](#logging)
+- [Requisitos](#requisitos)
+
+---
+
+## Instalação
+
+```bash
+npm install vsrepo @prisma/client @vsrepo/prisma7-adapter
+```
+
+Tanto o `vsrepo` quanto o `@vsrepo/prisma7-adapter` já foram publicados no npm e estão prontos para uso.
+
+## Uso básico
+
+```typescript
+import { VSRepository, VSLogLevel } from "vsrepo";
+import { VSRepoPrisma7Adapter, Prisma7OrmTypes } from "@vsrepo/prisma7-adapter";
+import { Prisma, PrismaClient } from "./generated/prisma/client";
+import { prisma } from "./prisma";
+
+type User = Prisma.UserGetPayload<{ include: { posts: true } }>;
+type MyOrmTypes = Prisma7OrmTypes<PrismaClient, Prisma.TransactionClient>;
+
+class UserRepository extends VSRepository<User, string, MyOrmTypes> {
+    constructor() {
+        super({
+            adapter: new VSRepoPrisma7Adapter(prisma, {
+                tableName: "user",
+                pkName: "id",
+                relations: {
+                    posts: { mode: "otm", restriction: "add", pk: "id" },
+                },
+                logLevel: VSLogLevel.WARN,
+            }),
+            pkName: "id",
+        });
+    }
+}
+
+const userRepository = new UserRepository();
+
+const user = await userRepository.get({ id: "..." }, { relations: { posts: true } });
+```
+
+Aqui, o `relations` passado no `options` do método — com a forma `{ campo: true }` — é transformado num `include` do Prisma pelo adapter (ver [`relations` nas options (leitura)](#relations-nas-options-leitura)). Se você fornecer `select`, o `relations`/`include` é ignorado. Não confunda com o `relations` da config do construtor (que descreve como campos de relação são resolvidos em escritas) — a diferença é explicada em [Os dois `relations`](#os-dois-relations).
+
+`Prisma7OrmTypes<DB, TX>` amarra os tipos de retorno de `getDbClient()`/`transaction()` do `VSRepository` aos seus tipos reais e gerados do Prisma — ver [Transactions](#transactions).
+
+## Config do construtor
+
+```typescript
+new VSRepoPrisma7Adapter(prisma, {
+    tableName: "user", // obrigatório — nome do model/delegate do Prisma Client, como em `prisma.user`
+    pkName: "id",       // obrigatório — nome do campo de primary key da entidade
+    relations: { ... }, // opcional — ver "relations no construtor (escrita)" abaixo
+    logLevel: VSLogLevel.WARN, // opcional — default: VSLogLevel.WARN
+});
+```
+
+A config é validada com [valibot](https://valibot.dev/) — um `tableName`/`pkName`/`relations`/`logLevel` inválido lança um `VSRepoPrisma7AdapterError` apontando o campo problemático.
+
+## Relations
+
+### Os dois `relations`
+
+O nome `relations` aparece em **dois lugares diferentes** da API, com **formas e propósitos diferentes** — fácil de confundir. Em resumo:
+
+| | `relations` no **construtor** | `relations` nas **options** |
+| --- | --- | --- |
+| Onde você define | `new VSRepoPrisma7Adapter(prisma, { relations: ... })` | `repository.get(where, { relations: ... })` — e demais métodos |
+| Formato | Um objeto de **configuração** por campo: `{ mode, restriction, pk, nullable? }` | Um objeto por campo **só com `true` ou sub-objeto**: `{ posts: true }` |
+| Propósito | **Escrita** — quando um payload de `create`/`update`/`upsert`/`save`/`merge` tem campo de relação, diz como transformá-lo num nested write do Prisma (`create`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) | **Leitura** — eager loading: quais relations trazer junto no resultado (vira um `include` do Prisma) |
+| Quem consome | `parsePrismaWriteData` / `mergeEntities` (resolvers de escrita) | `parsePrismaInclude` (via `resolveReadArg`) |
+| Precisa da outra? | Não — só afeta escritas/`merge` | Não — funciona mesmo sem `relations` no construtor |
+
+Nenhum depende do outro: o `relations` das options faz eager loading de leitura mesmo quando o construtor não tem `relations`; e o `relations` do construtor governa o comportamento de escrita mesmo que você nunca passe `relations` nas options. As duas subseções abaixo detalham cada um.
+
+### `relations` no construtor (escrita)
+
+A config `relations` do construtor descreve, para cada campo de relação da entidade, **como o adapter deve resolver esse campo quando ele aparecer nos payloads de escrita** (`create`/`update`/`upsert`/`save`/`merge`) — o mesmo comportamento que a v1 do VSRepository tinha.
+
+Cada relation é configurada pelo nome do campo:
+
+```typescript
+relations: {
+    posts: { mode: "otm", restriction: "add", pk: "id" },
+    address: { mode: "oto", restriction: "set", pk: "id" },
+    author: { mode: "mto", restriction: "set", pk: "id", nullable: true },
+}
+```
+
+Sem `relations`, todo campo — incluindo campos de relação — é repassado direto pro `where`/`data`/`create`/`update` do Prisma, como está. Isso funciona bem pra campos escalares, mas o Prisma espera um formato bem específico de nested write (`create`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) pra campos de relação — então, se sua entidade tem relations, normalmente você vai querer configurá-las.
+
+#### `mode`
+
+Cardinalidade da relation, do ponto de vista da entidade dona do campo:
+
+| `mode` | Significado | Formato do campo que você envia |
+| --- | --- | --- |
+| `oto` | one-to-one | um único objeto, ou `null` |
+| `mto` | many-to-one | um único objeto, ou `null` |
+| `otm` | one-to-many | um array de objetos |
+| `mtm` | many-to-many | um array de objetos |
+
+#### `restriction`
+
+Controla como `save`/`update`/`upsert` tratam itens de relação que já existem (casados pela `pk`) e, pra relations to-many, itens que **não** vieram no payload:
+
+- **`"add"`** — só cria/conecta/faz upsert dos itens enviados. Itens já existentes que não estão no payload permanecem intocados.
+- **`"set"`** — igual a `"add"`, mas também remove o que não foi enviado: em `otm` roda um `deleteMany` nos itens que faltam no array; em `mtm` reseta o vínculo (`set: []`) antes de reconectar; em `oto`/`mto` enviar `null` desconecta/apaga a relation (ver abaixo).
+
+#### `pk` e `nullable`
+
+- **`pk`** — o campo usado pra identificar um registro relacionado já existente. Um item **com** `pk` no payload vira um `connectOrCreate`/`upsert`; um item **sem** `pk` vira um `create` simples.
+- **`nullable`** — só relevante pra `mto`. Quando `true`, enviar `null` no campo resolve pra `disconnect` no update. Pra `oto` com `restriction: "set"`, enviar `null` resolve pra `delete` (um lado `oto` não dá só pra "desconectar", a linha possuída é removida).
+
+#### Como cada método de escrita resolve relations
+
+| Método | Relations |
+| --- | --- |
+| `create` | Só `create`/`connectOrCreate` (sem upsert — ainda não existe nada pra atualizar) |
+| `update` / `upsert` (metade do `update`) / `save` (branch de upsert) | Resolução completa: `create`/`connectOrCreate`/`upsert`/`disconnect`/`delete`/`deleteMany`/`set`, conforme `mode`/`restriction` |
+| `createMany` / `createManyReturning` / `updateMany` / `updateManyReturning` | Não suportado — lança um `VSRepoPrisma7AdapterError` apontando o campo problemático se o payload tiver uma relation configurada |
+
+### `relations` nas options (leitura)
+
+Esse é o `relations` que você passa no `options` de um método do `VSRepository` (`get`, `find`, `findOne`, etc.). A forma é bem mais simples: um objeto onde cada campo de relação aceita:
+
+- `true` — carrega a relation completa;
+- ou outro objeto `relations` — para eager loading aninhado (relations da relation).
+
+```typescript
+const user = await userRepository.get(
+    { id: "..." },
+    {
+        relations: {
+            posts: true,                   // carrega os posts junto
+            author: { profile: true },     // e, dentro do author, o profile (eager loading aninhado)
+        },
+    }
+);
+```
+
+Esse objeto é transformado num `include` do Prisma pelo adapter (`parsePrismaInclude`). Ele **não** usa a config `relations` do construtor: é puramente uma opção de leitura e funciona mesmo sem `relations` na config.
+
+O `select` e o `relations` que você passa nas options são transformados num `select` do Prisma (`parsePrismaSelect`) e num `include` (`parsePrismaInclude`), respectivamente. Quando o `select` é fornecido, o `include` derivado do `relations` é descartado (fica `undefined`), porque o Prisma não permite combinar `include` e `select` na mesma query. Ou seja, se você já estiver usando `select`, o objeto `relations` vira redundante — por isso ele é facultativo. Essa é a lógica resolvida (de `resolveReadArg`):
+
+```ts
+const prismaSelect = options.select && parsePrismaSelect(options.select);
+const prismaInclude = prismaSelect
+    ? undefined
+    : options.relations && parsePrismaInclude(options.relations);
+```
+
+## `merge`
+
+`merge(where, obj, options)` busca o registro que casa com `where` e devolve ele **deep-merged, em memória**, com `obj` — ele **não** escreve nada no banco. Isso reflete exatamente como o `merge` funcionava na v1 do VSRepository: ele serve pra montar uma entidade completa e mesclada, que você depois passa pro `save`/`update`, e não pra persistir um update parcial diretamente.
+
+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.
+
+## `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`.
+
+> Nota sobre a ordem de retorno: `createManyReturning` não garante que os registros devolvidos seguem a ordem do payload de entrada (`objs`). O resultado vem de um segundo `findMany` (re-buscando as linhas inseridas/atualizadas pela primary key), então a ordem só é garantida quando você passa `order` nas options.
+
+## Transactions
+
+**Todos** os métodos aceitam `options.db` e executam a operação no client/transaction passado — a diferença está em **como** cada um o trata:
+
+- A maioria (operações de uma única chamada Prisma) roda direto em `options?.db`: você passa um transaction client e a chamada participa da transaction, sem iniciar nada novo.
+- `saveMany`, `updateManyReturning`, `createManyReturning` e `deleteManyReturning` precisam rodar **mais de uma operação** do Prisma atomicamente (`saveMany` salva cada registro individualmente; `updateManyReturning`/`createManyReturning` fazem um `updateManyAndReturn`/`createManyAndReturn` + `findMany`; `deleteManyReturning` faz um `findMany` + `deleteMany`), então passam por `runTransactional`. Se `options.db` já for um transaction client ativo, ele é reaproveitado — nenhuma transaction aninhada é criada; caso contrário, uma nova transaction é criada (em `options.db`, se fornecido, ou no client raiz caso contrário).
+
+Um transaction client é diferenciado do `PrismaClient` raiz pelo método `$on`: o client raiz do Prisma o expõe (pra event listeners), o transaction client interativo não. É isso que `Prisma7ClientLike`/`Prisma7OrmTypes` codificam nos seus tipos.
+
+```typescript
+await userRepository.transaction(async tx => {
+    // Toda chamada de repository feita com `{ db: tx }` dentro desse
+    // callback compartilha a mesma transaction — incluindo chamadas a
+    // `saveMany`/`updateManyReturning`/`createManyReturning`/`deleteManyReturning`,
+    // que vão detectar que `tx` já é uma transaction e rodar direto nele, sem
+    // aninhar uma nova.
+    await userRepository.save(user, { db: tx });
+    await userRepository.saveList(outrosUsuarios, { db: tx });
+});
+```
+
+## Logging
+
+O adapter usa o `VSLogger` (de `vsrepo`) internamente: todo método loga uma linha `DEBUG` com o arg resolvido do Prisma, além de logs de performance de início/fim (com `WARN` pra operações lentas). Configure `logLevel` na config do construtor pra controlar a verbosidade; o default é `VSLogLevel.WARN`.
+
+## Requisitos
+
+- `vsrepo` v2
+- `@prisma/client` ^7.10.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { VSRepoPrisma7Adapter } from "./prisma7.adapter";
+export type { Relation } from "./types/relation.type";
+export type { Prisma7OrmTypes } from "./types/prisma7-orm-types.type";
+export type { Prisma7ClientLike } from "./types/prisma7-client-like.type";
+export type { AdapterRelations } from "./types/adapter-relations.type";
+export type { VSRepoPrisma7AdapterConfig } from "./types/adapter-config.type";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VSRepoPrisma7Adapter = void 0;
+var prisma7_adapter_1 = require("./prisma7.adapter");
+Object.defineProperty(exports, "VSRepoPrisma7Adapter", { enumerable: true, get: function () { return prisma7_adapter_1.VSRepoPrisma7Adapter; } });

package/dist/parsers/data.parser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parser que converte um `DeepPartial<T>` (formato "cru" vindo do vsrepo) nos
+ * payloads `create`/`update` esperados pelo Prisma para escritas com relations,
+ * replicando o comportamento da v1 (`resolveCreateUpdatePayloadsWithRelations`).
+ *
+ * Sem `relations` configurado no adapter, cada campo é repassado como está —
+ * exceto `pkName`, que é omitido do `update` (não faz sentido reatribuir a PK
+ * num update parcial).
+ *
+ * Com `relations`, cada campo de relação é resolvido de acordo com seu `mode`/
+ * `restriction` (ver `Relation`):
+ *  - to-one (`oto`/`mto`) sem PK no valor enviado -> `create` (e `upsert` no
+ *    update, a não ser que `restriction: "add"`, que usa só `create`)
+ *  - to-one com PK no valor enviado               -> `connectOrCreate` (e
+ *    `upsert` no update, a não ser que `restriction: "add"`)
+ *  - to-one enviado como `null`                    -> `delete` (`oto` +
+ *    `restriction: "set"`) ou `disconnect` (`mto` + `nullable`)
+ *  - to-many (`otm`/`mtm`) — itens são separados entre "com PK" e "sem PK":
+ *    os sem PK viram `create`, os com PK viram `connectOrCreate` no create e
+ *    `upsert` no update; com `restriction: "set"`, itens de `otm` que não
+ *    vieram no array são removidos (`deleteMany`) e itens de `mtm` têm o
+ *    vínculo resetado (`set: []`) antes de reconectar
+ *
+ * Essa mesma saída `{ create, update }` é reaproveitada em todos os métodos de
+ * escrita do adapter: `create()` usa só `.create`, `update()`/`updateMany()`
+ * usam só `.update`, e `save()`/`upsert()` usam os dois.
+ */
+import { AdapterRelations } from "../types/adapter-relations.type";
+import { PlainObject } from "../types/plain-object.type";
+export interface PrismaWriteData {
+    create: PlainObject;
+    update: PlainObject;
+}
+export declare function parsePrismaWriteData<T>(obj: PlainObject, pkName: string, relations?: AdapterRelations<T>): PrismaWriteData;