vsrepo 1.4.1 → 2.0.0

package/README.md

@@ -9,139 +9,124 @@
   </p>
 </div>
 
-# VSRepository
+# VSRepository v2
 
 🇺🇸 You're reading the English version. [🇧🇷 Ler em português](./README.pt-BR.md)
 
-Repository pattern library for projects using **Prisma**, with full **TypeScript** support and automatic **type inference**.
+> ✅ **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.
 
 VSRepository lets you create strongly-typed repositories with:
 
-- Automatic **base methods**: `get`, `getOrThrow`, `getList`, `save`, `saveList`, `remove`, `removeList`, `patch`, `patchList`, `merge`, `getAll`, `total`, `has`
+- Automatic **base methods**: `get`, `getOrThrow`, `getList`, `save`, `saveList`, `remove`, `removeList`, `patch`, `merge`, `getAll`, `total`, `has`
 - **Native soft-delete**: `softRemove`, `softRemoveList`, `restore`, `restoreList`
-- **Dynamic methods** inferred from their name: `findOneByEmail`, `findManyPaginated`, `updateById`, `deleteManyByNameStartsWith`
-- Reusable **select models** for different data projections
+- **Dynamic methods** inferred from a `declare` field name via the `@DynamicMethod` decorator: `findByEmail`, `findManyByStatusPaginated`, `updateById`
+- **Raw SQL query methods** via the new `@QueryMethod` decorator, bypassing the name-parsing engine entirely
+- Ad-hoc **`select`/`relations`** per call — no more pre-declared named projections
 - **Type safety** across 100% of operations
-- Native Prisma **transactions** (automatic in `saveList` and `patchList`)
-- **Extensibility** with custom methods
-
-> 💡 Want to see all of this in practice? The repository's [`examples/`](https://github.com/jaobrabo123/VSRepository/tree/main/examples) folder has commented, runnable examples for every feature — see the [Practical examples](#practical-examples) section below.
+- Native ORM **transactions**, shared across repositories
+- An **ORM-agnostic core** — the same repository class works with any `VSRepoAdapter` implementation
 
 ---
 
 ## Table of contents
 
+- [What changed from v1](#what-changed-from-v1)
+- [Adapter status](#adapter-status)
 - [Installation](#installation)
-- [Generating the types](#generating-the-types)
 - [Basic usage](#basic-usage)
-- [Class-based approach (DynamicRepository)](#class-based-approach-dynamicrepository)
-- [NestJS integration](#nestjs-integration)
+- [Constructor options](#constructor-options)
 - [Base methods](#base-methods)
-  - [Soft-delete](#soft-delete)
-  - [Batch operations](#batch-operations)
-  - [Merge](#merge)
-  - [Configuring the base methods](#configuring-the-base-methods)
-- [Select Models](#select-models)
-  - [Raw select (options.select)](#raw-select-optionsselect)
-- [Include Models](#include-models)
-  - [Raw include (options.include)](#raw-include-optionsinclude)
-- [Required Where](#required-where)
-- [Default Ordering](#default-ordering)
-- [`see` option](#see-option)
+- [Soft-delete](#soft-delete)
+- [`select` and `relations`](#select-and-relations)
 - [Dynamic methods](#dynamic-methods)
-  - [Available prefixes](#available-prefixes)
-  - [Field filters](#field-filters)
-  - [Logical operators](#logical-operators)
-  - [Relation filters](#relation-filters)
-  - [Pagination and ordering suffixes](#pagination-and-ordering-suffixes)
-  - [Distinct](#distinct)
-  - [Method configuration](#method-configuration)
-  - [Aggregate and GroupBy](#aggregate-and-groupby)
-  - [Query Methods](#query-methods)
-- [Relations in save](#relations-in-save)
+    - [Available prefixes](#available-prefixes)
+    - [Field filters](#field-filters)
+    - [Logical operators](#logical-operators)
+    - [Relation filters](#relation-filters)
+    - [Ordering, pagination and distinct](#ordering-pagination-and-distinct)
+    - [Decorator options](#decorator-options)
+- [Query methods (raw SQL)](#query-methods-raw-sql)
+    - [Ad-hoc raw queries with `query()`](#ad-hoc-raw-queries-with-query)
 - [Transactions](#transactions)
-- [Extending a repository](#extending-a-repository)
-- [Error handling](#error-handling)
 - [Utility types](#utility-types)
-- [API Reference](#api-reference)
-- [Practical examples](#practical-examples)
-- [Contributing](#contributing)
+- [Writing your own adapter](#writing-your-own-adapter)
+- [Error handling](#error-handling)
+    - [`VSRepoAdapterError` and `AdapterErrorCode`](#vsrepoadaptererror-and-adaptererrorcode)
+- [Logging](#logging)
+- [Development](#development)
 - [Requirements](#requirements)
-- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
 
 ---
 
-## Installation
+## What changed from v1
 
-```bash
-npm i vsrepo @prisma/client
-```
+If you're coming from the [v1](./v1) code/docs, here's the short version. See each linked section for details.
 
-Generate the Prisma Client:
-
-```bash
-npx prisma generate
-```
+| Area                                         | v1                                                                                                              | v2                                                                                                                                                                                                                                   |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Database access                              | Talks to **Prisma** directly, bundled in the core package                                                       | Talks to a **`VSRepoAdapter`**; ORM support ships as separate packages (`@vsrepo/prisma7-adapter`, `@vsrepo/typeorm-adapter`, ...) instead of being bundled in the core `vsrepo` package                                             |
+| Defining a repository                        | Functional `setupVSRepo<T, M>()({...}).build(prisma)`, **or** a `DynamicRepository` class                       | A single **class-based** API: `extends VSRepository<Entity, PKType, OrmTypes>`                                                                                                                                                       |
+| Dynamic methods                              | `methods: { findByEmail: { map: true } }` config object                                                         | `@DynamicMethod()` decorator on a `declare` field                                                                                                                                                                                    |
+| Data projections                             | Named, reusable `selectModels` + `defaultSelectModel`                                                           | Ad-hoc `select`/`relations` passed per call (no named models)                                                                                                                                                                        |
+| Eager loading                                | `include`/`includeModels` (Prisma-specific)                                                                     | ORM-agnostic `relations` option                                                                                                                                                                                                      |
+| Global filters                               | `requiredWhere` (any arbitrary filter, always applied)                                                          | **Removed**; Now it only accepts `softRemoveKey` + `see: "active" \| "removed" \| "all"`                                                                                                                                             |
+| Case-insensitive filter suffix               | `Insensitive`                                                                                                   | `IgnoreCase`                                                                                                                                                                                                                         |
+| Inline ordering in method name               | Not supported (`order` had to be passed as an argument via `Ordered`/`Paginated`)                               | `OrderBy<Field>Asc`/`OrderBy<Field>Desc` chains baked directly into the method name                                                                                                                                                  |
+| Duplicate handling on `createMany`           | `SkipDuplicates` suffix                                                                                         | `IgnoreConflicts` suffix                                                                                                                                                                                                             |
+| `aggregate` / `groupBy`                      | Supported (Prisma-native passthrough)                                                                           | **Not implemented yet**                                                                                                                                                                                                              |
+| Error types                                  | `VSRepoError` + subclasses (`VSRepoConfigError`, `VSRepoBuildError`, `VSRepoExtendError`, `VSRepoRuntimeError`) | A base `VSRepoError` class with a `type: VSRepoErrorType` field (`DECORATOR`, `RESOLVER`, `DYNAMIC`, `VALIDATOR`, `BASE`, `ADAPTER`), plus a `VSRepoAdapterError` subclass carrying an `AdapterErrorCode` and the original ORM error |
+| Debug logging                                | `showWorking: true` boolean                                                                                     | `logLevel: VSLogLevel` (`DEBUG`/`INFO`/`WARN`/`ERROR`) + `logSlowThresholdMs` for slow-query warnings                                                                                                                                |
+| `vsrepo generate` CLI (type generation step) | Required before use                                                                                             | Not part of the v2 core — types come directly from your entity/ORM types                                                                                                                                                             |
+| CRUD extras                                  | `patchList`, raw `options.select`/`options.include`                                                             | `select`/`relations` are the default (always "raw"); `patch`/`merge` keep the same semantics. **`patchList` was removed** — for a batch partial update, use a `updateManyBy`/`updateManyWhere` dynamic method instead                |
 
 ---
 
-## Generating the types
-
-VSRepository needs to know the real path of your Prisma Client to generate the typings correctly.
+## Adapter status
 
-```bash
-npx vsrepo generate
-```
+VSRepository v2 is **ORM-agnostic by design**. The core package (`vsrepo`) only ships the repository class, the decorators, the name-parsing engine, error handling and logging — it does **not** ship a production adapter. Actual ORM/database support is meant to live in **separate, independently versioned packages**, one per ORM (and, where it makes sense, one per major ORM version), for example:
 
-Equivalent to:
+- `@vsrepo/prisma7-adapter`
+- `@vsrepo/prisma8-adapter`
+- `@vsrepo/typeorm-adapter`
+- `@vsrepo/drizzle-adapter`
 
-```bash
-npx vsrepo generate \
-  --output generated/vsrepo \
-  --prisma generated/prisma
-```
+The Prisma 7 adapter has now been published to npm as `@vsrepo/prisma7-adapter` — it's currently the **only** published adapter. Adapters for the other ORMs listed above (Prisma 8, TypeORM, Drizzle) are **planned**; they just haven't been published yet. Until an official `@vsrepo/*-adapter` package exists for your ORM, you're welcome to write your own for your project, and if you'd like, publish it and open a PR to help grow the ecosystem — contributions here are very welcome.
 
-**Available flags:**
+| 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. |
+| 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. |
 
-| Flag       | Alias | Default              |
-| ---------- | ----- | -------------------- |
-| `--output` | `-o`  | `generated/vsrepo`   |
-| `--prisma` | `-p`  | `generated/prisma`   |
+In short: the repository class, the `@DynamicMethod`/`@QueryMethod` decorators, the name-parsing engine, error handling and logging are all working end-to-end, and Prisma 7 support is now a released, published adapter. Official adapters for the remaining ORMs are on the roadmap and will ship as separate `@vsrepo/*-adapter` packages rather than as part of the core `vsrepo` package — but you don't have to wait for that: writing (and optionally publishing) your own adapter in the meantime is a fully supported way to use v2 today and to contribute back to the project.
 
-**Generated files:**
-
-```text
-generated/vsrepo/
-├── DynamicRepository.ts
-├── DynamicRepository.types.d.ts
-├── VSRepoError.ts
-├── VSRepoError.types.d.ts
-├── VSRepository.ts
-├── VSRepository.types.d.ts
-└── index.ts
-```
+---
 
-After generating, always import from the generated folder:
+## Installation
 
-```ts
-// CORRECT ✅
-import { setupVSRepo } from "../../generated/vsrepo";
+v2 is installed as the core package plus one adapter package for your ORM, for example:
 
-// WRONG ❌
-import { setupVSRepo } from "vsrepo";
+```bash
+npm i vsrepo @vsrepo/prisma7-adapter
 ```
 
+> `vsrepo` v2.0.0 and `@vsrepo/prisma7-adapter` are both published to npm and ready to use. For any ORM other than Prisma 7, no adapter package exists yet — install the core and write your own adapter (see [Writing your own adapter](#writing-your-own-adapter)).
+
 ---
 
 ## Basic usage
 
-### Configuring the Prisma Client
+### Implementing/choosing an adapter
 
-```ts
+```typescript
 // src/configs/db.ts
-import { PrismaClient } from '../../generated/prisma/client';
-import { PrismaPg } from '@prisma/adapter-pg';
-import 'dotenv/config';
+import { PrismaClient } from "../../generated/prisma/client";
+import { PrismaPg } from "@prisma/adapter-pg";
+import "dotenv/config";
 
 const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
 const prisma = new PrismaClient({ adapter });
@@ -151,1457 +136,857 @@ export default prisma;
 
 ### Creating a repository
 
-```ts
-// src/repositories/userRepository.ts
+```typescript
+// src/repositories/user.repository.ts
+import { VSRepository, DynamicMethod } from "vsrepo";
+import { VSRepoPrisma7Adapter } from "@vsrepo/prisma7-adapter";
 import prisma from "../configs/db";
-import { setupVSRepo } from "../../generated/vsrepo";
-import type { User } from "../../generated/prisma/client";
-
-const userRepository = setupVSRepo<User, "User">()(({
-  tableName: "user",
-  pkName: "id",
-  selectModels: {
-    public: { id: true, name: true, email: true },
-  },
-  defaultSelectModel: "public",
-}).build(prisma);
-
-export default userRepository;
-```
-
-### Using the repository
-
-```ts
-import userRepository from "./repositories/userRepository";
-
-const user = await userRepository.save({
-  name: "John",
-  email: "john@email.com",
-  password: "password",
-});
-
-const found = await userRepository.get(user.id);
-const all = await userRepository.getAll();
-
-user.name = "John Smith";
-
-await userRepository.save(user);
-await userRepository.remove(user.id);
-```
-
----
-
-## Class-based approach (DynamicRepository)
-
-If you prefer an OOP style with decorators instead of the functional `setupVSRepo` approach, VSRepository also provides `DynamicRepository` — a class you can extend with `@DynamicMethod()` decorators to define your dynamic methods.
-
-See **[README-DynamicRepo.md](./README-DynamicRepo.md)** (or the [pt-BR version](./README-DynamicRepo.pt-BR.md)) for full documentation on the class-based approach, including NestJS integration examples, decorator config, and a comparison with `setupVSRepo`.
-
----
+import type { UserGetPayload } from "../../generated/prisma/models";
 
-## NestJS integration
+type User = UserGetPayload<{ include: { address: true } }>;
 
-VSRepository can be easily integrated into NestJS projects through providers. Below is a complete example using NestJS's dependency injection pattern.
-
-### Configuring the repository as a provider
-
-```ts
-// src/modules/user/user.repository.ts
-import { Provider } from "@nestjs/common";
-import { PrismaService } from "../../database/prisma.service";
-import { UserGetPayload } from "../../../generated/prisma/models";
-import { setupVSRepo } from "../../../generated/vsrepo";
-
-const userVSRepo = setupVSRepo<
-    UserGetPayload<{ include: { profile: true } }>,
-    "User"
->()(({
-    tableName: "user",
-    pkName: "id",
-    selectModels: {
-        public: {
-            id: true,
-            email: true,
-            createdAt: true,
-            updatedAt: true,
-        },
-        auth: {
-            id: true,
-            email: true,
-            password: true,
-        },
-    },
-    defaultSelectModel: "public",
-    requiredWhere: {
-        deletedAt: null,
-    },
-    relations: {
-        profile: {
-            mode: "oto",
-            pk: "id",
-            restriction: "add",
-        },
-    },
-    methods: {
-        findAuthByEmail: {
-            map: true,
-            proxyTo: "findUniqueByEmail",
-            selectModel: "auth",
-        },
-        findByEmailEndsWith: {
-            map: true,
-        }
-    },
-});
-
-const setupUserRepository = (prisma: PrismaService) => {
-    return userVSRepo.build(prisma);
-};
-
-export type UserRepository = ReturnType<typeof setupUserRepository>;
-/* 
-The type can also be inferred using VSRepository's `RepositoryOf`, passing the `userVSRepo` type:
-
-export type UserRepository = RepositoryOf<typeof userVSRepo>;
-
-NOTE: If you use `.extend` to extend the repository or configure the base methods,
-using `ReturnType` is recommended since it's simpler to infer the type
-*/
-
-export const USER_REPOSITORY = Symbol("USER_REPOSITORY");
-
-export const UserRepositoryProvider: Provider = {
-    provide: USER_REPOSITORY,
-    inject: [PrismaService],
-    useFactory: setupUserRepository,
-};
-```
-
-### Registering the provider in the module
-
-```ts
-// src/modules/user/user.module.ts
-import { Module } from "@nestjs/common";
-import { UserRepositoryProvider } from "./user.repository";
-import { UserService } from "./user.service";
-import { UserController } from "./user.controller";
-
-@Module({
-    imports: [DatabaseModule],
-    providers: [UserRepositoryProvider, UserService],
-    controllers: [UserController],
-    exports: [UserService],
-})
-export class UserModule {}
-```
-
-### Using the repository in a service
-
-```ts
-// src/modules/user/user.service.ts
-import { Injectable, Inject } from "@nestjs/common";
-import { USER_REPOSITORY, type UserRepository } from "./user.repository";
-
-@Injectable()
-export class UserService {
-    constructor(
-        @Inject(USER_REPOSITORY)
-        private readonly userRepository: UserRepository,
-    ) {}
-
-    async getUserById(id: string) {
-        return this.userRepository.get(id);
-    }
-
-    async getUserAuthByEmail(email: string) {
-        return this.userRepository.findAuthByEmail(email);
-    }
-
-    async createUser(data: { email: string; password: string; name: string }) {
-        return this.userRepository.save({
-            email: data.email,
-            password: data.password,
-            name: data.name,
+class UserRepository extends VSRepository<User, string> {
+    constructor() {
+        super({
+            pkName: "id",
+            adapter: new VSRepoPrisma7Adapter<User>(prisma, { tableName: "user", pkName: "id" }),
+            softRemoveKey: "deletedAt",
+            defaultOrdering: { createdAt: "desc" },
         });
     }
-}
-```
 
-**Benefits of this approach:**
+    @DynamicMethod()
+    declare findByEmail: (email: string) => Promise<User[]>;
 
-- ✅ Type-safe repositories with dependency injection
-- ✅ Easy to test (mock the `USER_REPOSITORY`)
-- ✅ Isolation of persistence logic
-- ✅ Repository reuse across multiple services
-- ✅ Transaction support via `PrismaService`
-
----
-
-## Base methods
-
-When calling `.build(prisma)`, the base methods below are automatically made available:
-
-| Method                   | Description                                                                                                  |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------|
-| `get(pk)`                | Fetches a record by its primary key                                                                          |
-| `getOrThrow(pk)`         | Fetches a record by its primary key; throws `VSRepoRuntimeError` (code `"20727"`) if not found               |
-| `getList(pks)`           | Fetches multiple records from a list of primary keys                                                         |
-| `save(obj)`              | Creates or updates — if the object has a `pk` it performs an `upsert`, otherwise a `create`                  |
-| `saveList(objs)`         | Saves an array of objects in a single automatic transaction                                                  |
-| `patch(pk, obj)`         | Partially updates a record by its primary key                                                                |
-| `patchList(tuples)`      | Partially updates multiple records via an array of `[pk, obj]` tuples in an automatic transaction            |
-| `merge(pk, obj)`         | Fetches a record and deep merges it in memory — **does not persist**, returns the merged object              |
-| `remove(pk)`             | Removes a record by its primary key                                                                          |
-| `removeList(pks)`        | Removes several records by a list of primary keys — returns `{ count }`                                      |
-| `getAll()`               | Returns all records (accepts `pagination` and `order` in `options`)                                          |
-| `total()`                | Returns the total number of records                                                                          |
-| `has(pk)`                | Checks whether a record exists by its primary key — returns `boolean`                                        |
-
-All of them accept `options` as the last argument.
-
-### Soft-delete
-
-When `softRemovekName` is configured on the repository, the following additional methods become available:
-
-| Method                     | Description                                                                        |
-| -------------------------- | ---------------------------------------------------------------------------------- |
-| `softRemove(pk)`           | Marks a record as removed by filling `softRemovekName` with the current date       |
-| `softRemoveList(pks)`      | Marks multiple records as removed in batch — returns `{ count }`                   |
-| `restore(pk)`              | Restores a soft-deleted record, clearing the `softRemovekName` field               |
-| `restoreList(pks)`         | Restores multiple soft-deleted records in batch — returns `{ count }`              |
-
-```ts
-const userRepository = setupVSRepo<User, "user">()(({
-  tableName: "user",
-  pkName: "id",
-  softRemovekName: "deletedAt", // must be a DateTime field in the Prisma schema
-}).build(prisma);
-
-await userRepository.softRemove(1);
-await userRepository.restore(1);
-```
-
-> The field provided in `softRemovekName` **must** be of type `DateTime` in the Prisma schema. VSRepository validates this at `build` time and throws `VSRepoBuildError` if the type is incorrect.
-
-### Batch operations
-
-`saveList` and `patchList` automatically run all operations inside a single Prisma transaction. If any operation fails, all previous ones are rolled back.
-
-```ts
-// saveList — creates or updates multiple objects in an automatic transaction
-const users = await userRepository.saveList([
-  { name: "Mary", email: "mary@email.com" },
-  { id: 2, name: "John Updated", email: "john@email.com" },
-]);
+    @DynamicMethod()
+    declare findOneByEmail: (email: string) => Promise<User | null>;
+}
 
-// patchList — partially updates multiple records via [pk, obj] tuples
-const updated = await userRepository.patchList([
-  [1, { active: false }],
-  [2, { name: "New Name" }],
-]);
+export default new UserRepository();
 ```
 
-When you're already inside an existing transaction, pass it in `options.db`. In this case, `db` must be a `DbTransaction` (not the main client):
-
-```ts
-await prisma.$transaction(async (tx) => {
-  await userRepository.saveList([{ name: "Mary" }, { name: "Gus" }], { db: tx });
-  await userRepository.patchList([[1, { active: false }], [2, { active: true }]], { db: tx });
-});
-```
+> The core API (`VSRepository`, `VSRepoAdapter`, `DynamicMethod`, `QueryMethod`, `VSRepoError`, enums and types) is imported from the single `vsrepo` entry point. The concrete adapter comes from a **separate** package (`@vsrepo/*-adapter`). On Prisma 7, install the published [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) (its constructor takes a config object — `tableName`, `pkName`, optional `relations`/`logLevel` — as shown above). Official adapters for other ORMs are planned but not published yet; until they are, you can implement the `VSRepoAdapter` contract yourself (see [Writing your own adapter](#writing-your-own-adapter)) — and publishing it to help the project is very welcome.
 
-### Merge
+> **The third generic parameter (`OrmTypes`):** `VSRepository<Entity, PKType, OrmTypes>` accepts an optional third type parameter describing your ORM's client/transaction types, via `VSRepoOrmTypes` (`{ dbClient; dbTransaction }`). Supplying it gives you a correctly-typed `getDbClient()`, `transaction()` callback, and `db` option on every method, instead of `any`:
+> ```typescript
+> type PrismaOrmTypes = { dbClient: PrismaClient; dbTransaction: Prisma.TransactionClient };
+>
+> class UserRepository extends VSRepository<User, string, PrismaOrmTypes> {
+>     // getDbClient() now returns PrismaClient, and transaction(fn) types `tx` as Prisma.TransactionClient
+> }
+> ```
+> If omitted, it defaults to `VSRepoOrmTypes` (`dbClient`/`dbTransaction` both `any`).
 
-The `merge` method fetches a record by its PK and deeply merges (`deepmerge`) the provided object with the existing data **in memory**. It **does not persist** the changes — it returns the merged result so you can decide what to do with it.
+### Using the repository
 
-```ts
-const existing = await userRepository.get(1);
-// existing: { id: 1, name: "Mary", profile: { bio: "Hi", age: 25 } }
+```typescript
+import userRepository from "./repositories/user.repository";
 
-const merged = await userRepository.merge(1, {
-  profile: { bio: "Updated bio" },
+const user = await userRepository.save({
+    name: "Joao",
+    email: "joao@email.com",
+    password: "password",
 });
-// merged: { id: 1, name: "Mary", profile: { bio: "Updated bio", age: 25 } }
 
-// To persist, pass it to save or patch:
-await userRepository.save(merged);
-```
+const found = await userRepository.get(user.id);
+const all = await userRepository.getAll();
+const byEmail = await userRepository.findByEmail("joao@email.com");
 
-Returns `null` if the record is not found.
-
-**Merging to-many relations (`otm`/`mtm`) is done by PK, not by simple concatenation.** For to-one relations (`oto`/`mto`), `merge` performs a regular deep merge of the object. For to-many relations, each item in the sent array is matched against the existing item that has the same PK (defined in `relations[key].pk`): if the PK matches, the two objects are merged together; if it doesn't match (a new item with no counterpart), it's simply added to the list. Existing items that don't appear in the sent array are kept.
-
-```ts
-const existing = await userRepository.get(1);
-// existing: {
-//   id: 1,
-//   posts: [
-//     { id: 10, title: "Post A", published: false },
-//     { id: 11, title: "Post B", published: true },
-//   ],
-// }
-
-const merged = await userRepository.merge(1, {
-  posts: [
-    { id: 10, published: true },  // same PK (id: 10) → merges with the existing item
-    { title: "Post C" },          // no PK → added as a new item
-  ],
-});
-// merged: {
-//   id: 1,
-//   posts: [
-//     { id: 10, title: "Post A", published: true },  // merged
-//     { id: 11, title: "Post B", published: true },  // kept, wasn't in the sent array
-//     { title: "Post C" },                            // added
-//   ],
-// }
+await userRepository.patch(user.id, { name: "Joao Pedro" });
+await userRepository.remove(user.id);
 ```
 
-> Note that `merge` never removes items from a to-many relation — it only merges the ones that match by PK and adds the ones that don't. To remove items from a relation, use `save`/`patch` with `restriction: "set"` in the relation configuration.
-
-### Configuring the base methods
-
-The second argument of `.build(prisma, config)` lets you adjust the repository's global behavior and customize each base method individually through `baseMethods`.
-
-```ts
-userVSRepo.build(prisma, {
-  // Shows VSRepository's internal logs on the console (built queries, detected prefix,
-  // applied filters, etc). Great for debugging dynamic methods. Default = false.
-  showWorking: true,
+---
 
-  baseMethods: {
-    get: {
-      // Enables/disables the method on the final repository. If `false`, the method
-      // doesn't even appear in the repository's type (it's not just a runtime error). Default = true.
-      active: true,
+## Constructor options
 
-      // Select model applied by default when the method is called without `options.selectModel`.
-      // Overrides the `defaultSelectModel` from setupVSRepo for this method only.
-      defaultSelect: "public",
-    },
-    remove: {
-      active: true,
-      defaultSelect: "minimal",
-
-      // When `true`, ignores the `requiredWhere` configured in setupVSRepo for
-      // this specific method — useful when a method needs to "punch through" a
-      // global filter (e.g. multi-tenancy) in a specific case. Default = false.
-      ignoreRequiredWhere: false,
-    },
-    save: {
-      // Here only `ignoreRequiredWhere` is set — `active` and `defaultSelect`
-      // keep their defaults (true and the global `defaultSelectModel`).
-      ignoreRequiredWhere: true,
-    },
-    patch: {
-      // Only the select is overridden; the method stays active normally.
-      defaultSelect: "minimal",
-    },
-    has: {
-      active: false, // Disables 'has' (default = true) — the method disappears from the repository
-    },
-    softRemove: {
-      // Soft-delete methods follow the same options (`active`, `defaultSelect`,
-      // `ignoreRequiredWhere`). They're only available if `softRemovekName` is configured.
-      active: true,
-      defaultSelect: "minimal",
-    },
-  },
-});
-```
+`VSRepoOptions<T, K>`, passed to `super(...)` inside your repository's constructor:
 
-> Batch/aggregate methods like `removeList`, `softRemoveList`, `restoreList`, `total`, and `has` **do not** accept `defaultSelect` (they don't return a selectable record — they return `{ count }` or `boolean`). In these cases `BaseMethodConfig` is restricted to `active` and `ignoreRequiredWhere`.
+| Option               | Type               | Description                                                                                                         |
+| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `adapter`            | `VSRepoAdapter<T>` | **Required.** The adapter instance that translates repository calls into calls against the underlying ORM/database. |
+| `pkName`             | `keyof T`          | **Required.** Name of the field that represents the entity's primary key.                                           |
+| `softRemoveKey`      | `keyof T`          | Optional. When set, enables `softRemove`, `softRemoveList`, `restore` and `restoreList`.                            |
+| `defaultOrdering`    | `Ordering<T>`      | Optional. Default ordering applied automatically to queries that accept `order`, unless overridden per call.        |
+| `logLevel`           | `VSLogLevel`       | Optional. Minimum severity printed by the internal logger. Defaults to `VSLogLevel.WARN`.                           |
+| `logSlowThresholdMs` | `number`           | Optional. Duration (ms) above which a finished operation is logged as `WARN` instead of `DEBUG`. Defaults to 300ms. |
 
 ---
 
-## Select Models
-
-`selectModels` defines named, reusable data projections.
-
-```ts
-selectModels: {
-  public:   { id: true, name: true, email: true },
-  internal: { id: true, name: true, email: true, password: true },
-  minimal:  { id: true },
-},
-defaultSelectModel: "public",
-```
-
-`defaultSelectModel` defines which select is used automatically when none is specified in the call. It's recommended to always define it together with `selectModels`.
+## Base methods
 
-**Using a specific select in the call:**
+Available automatically on every `VSRepository` subclass:
 
-```ts
-const user = await userRepository.get(id, { selectModel: "minimal" });
-```
+| Method                      | Description                                                                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `get(pk, options?)`         | Fetches a record by primary key.                                                                                                     |
+| `getOrThrow(pk, options?)`  | Fetches a record by primary key, throwing if not found.                                                                              |
+| `getList(pks, options?)`    | Fetches multiple records by a list of primary keys.                                                                                  |
+| `getAll(options?)`          | Fetches all records; accepts `pagination` and `order` in `options`.                                                                  |
+| `save(obj, options?)`       | Creates or updates (upsert) a single record.                                                                                         |
+| `saveList(objs, options?)`  | Creates or updates (upsert) multiple records in one call.                                                                            |
+| `patch(pk, obj, options?)`  | Partially updates a record by primary key.                                                                                           |
+| `merge(pk, obj, options?)`  | Fetches a record and returns it deep-merged, in memory, with the given object — does **not** persist anything.                       |
+| `remove(pk, options?)`      | Deletes a record by primary key.                                                                                                     |
+| `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`.                                                                                 |
+| `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). |
 
-**Returning Prisma's default payload (without select):**
+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`).
 
-```ts
-const fullUser = await userRepository.get(id, { selectModel: false });
-```
+---
 
-### Raw `select` (`options.select`)
+## Soft-delete
 
-Besides `selectModel` (named, pre-configured in `selectModels`), you can pass a raw Prisma `select` directly in the call, without registering it beforehand on the repository.
+Soft-delete is now a **first-class, built-in concept**. Configure `softRemoveKey` once on the repository:
 
-```ts
-const user = await userRepository.get(id, {
-  select: { id: true, name: true },
+```typescript
+super({
+    pkName: "id",
+    adapter,
+    softRemoveKey: "deletedAt",
 });
 ```
 
-`options.select` accepts any valid Prisma `select` for the repository's model — it's fully typed and offers the same autocomplete/validation as calling `prisma.user.findMany({ select: ... })` directly, and the method's return type is narrowed to exactly the fields selected.
-
-**Rules and behavior:**
+This unlocks four extra methods:
 
-- **Mutually exclusive with `selectModel`, `includeModel` and `include`.** Only one of the four can be provided per call; the types enforce this — passing more than one is a compile-time error.
-- **Ad hoc, not reusable.** Unlike `selectModel`, it doesn't need to be declared in `selectModels`. Use it for one-off projections that don't justify a named select model.
-- **No `defaultSelectModel` is applied.** When `select` is provided, the default select (`defaultSelectModel`) is ignored and only the raw `select` is sent to Prisma.
+| Method                          | Effect                                |
+| ------------------------------- | ------------------------------------- |
+| `softRemove(pk, options?)`      | Sets `deletedAt` to the current date. |
+| `softRemoveList(pks, options?)` | Same, in batch — returns `{ count }`. |
+| `restore(pk, options?)`         | Sets `deletedAt` back to `null`.      |
+| `restoreList(pks, options?)`    | Same, in batch — returns `{ count }`. |
 
-```ts
-// CORRECT ✅ — raw select only
-await userRepository.get(id, { select: { id: true, name: true } });
+Every other method accepts a `see` option controlling visibility of soft-deleted rows:
 
-// WRONG ❌ — combining select with selectModel/includeModel/include is not allowed
-await userRepository.get(id, { selectModel: "public", select: { id: true } });
-await userRepository.get(id, { include: { posts: true }, select: { id: true } });
+```typescript
+await userRepository.getAll({ see: "active" }); // default — only non-deleted records
+await userRepository.getAll({ see: "removed" }); // only soft-deleted records
+await userRepository.getAll({ see: "all" }); // everything, ignoring soft-delete
 ```
 
-> **When to use `selectModel` vs. `select`:** prefer `selectModel` for projections reused across multiple calls (defined once in `selectModels`); use `select` for specific, occasional projections that don't need a name.
-
 ---
 
-## Include Models
-
-`includeModels` works similarly to `selectModels`, but instead of receiving a `select`, it receives a valid Prisma `include`.
-
-```ts
-const userRepository = setupVSRepo<User, "user">()(({
-  tableName: "user",
-  pkName: "id",
-  selectModels: {
-    public: { id: true, name: true, email: true },
-  },
-  defaultSelectModel: "public",
-  includeModels: {
-    withPosts: { posts: true },
-    withPostsAndProfile: { posts: true, profile: true },
-  },
-}).build(prisma);
-```
-
-**Using an `includeModel` in the call:**
-
-```ts
-const user = await userRepository.get(id, { includeModel: "withPosts" });
-```
-
-In this case, the default `select` (`selectModels`/`defaultSelectModel`) is ignored and only the `include` is sent to Prisma.
+## `select` and `relations`
 
-### Differences from `selectModels`
-
-- **Can only be passed in the method call**, via `options.includeModel`. There's no `defaultIncludeModel` or `defaultInclude` — there's no way to configure a default `includeModel` on the repository, unlike what happens with `defaultSelectModel`.
-- **`includeModel` and `selectModel` cannot be passed together** in the same call. If an `includeModel` is provided, any `selectModel` (including the default one) is ignored.
-
-```ts
-// CORRECT ✅ — includeModel only
-await userRepository.get(id, { includeModel: "withPosts" });
-
-// CORRECT ✅ — selectModel only
-await userRepository.get(id, { selectModel: "public" });
-
-// WRONG ❌ — combining both is not allowed
-await userRepository.get(id, { selectModel: "public", includeModel: "withPosts" });
-```
+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:
 
-### Raw `include` (`options.include`)
-
-Besides `includeModel` (named, pre-configured in `includeModels`), you can pass a raw Prisma `include` directly in the call, without registering it beforehand on the repository.
-
-```ts
+```typescript
 const user = await userRepository.get(id, {
-  include: { posts: true, profile: true },
+    select: { id: true, name: true, address: { city: true } },
 });
-```
-
-`options.include` accepts any valid `include` for the repository's Prisma model — it's fully typed and offers the same autocomplete/validation as calling `prisma.user.findMany({ include: ... })` directly.
-
-**Rules and behavior:**
-
-- **Mutually exclusive with `selectModel` and `includeModel`.** Only one of the three can be provided per call; the types enforce this — passing more than one is a compile-time error.
-- **Ad hoc, not reusable.** Unlike `includeModel`, it doesn't need to be declared in `includeModels`. Use it for one-off includes that don't justify a named model.
-- **No `selectModel` default is applied.** As with `includeModel`, when `include` is provided the select (including `defaultSelectModel`) is ignored and only the `include` is sent to Prisma.
-
-```ts
-// CORRECT ✅ — raw include only
-await userRepository.get(id, { include: { posts: true } });
-
-// WRONG ❌ — combining include with selectModel/includeModel is not allowed
-await userRepository.get(id, { selectModel: "public", include: { posts: true } });
-await userRepository.get(id, { includeModel: "withPosts", include: { posts: true } });
-```
-
-> **When to use `includeModel` vs. `include`:** prefer `includeModel` for includes reused across multiple calls (defined once in `includeModels`); use `include` for specific, occasional includes that don't need a name.
-
----
-
-## Required Where
-
-`requiredWhere` defines filters that are automatically applied to every query on the repository.
-
-```ts
-requiredWhere: { active: true },
-```
-
-Now every query will automatically include `active: true`:
 
-```ts
-// Internally: WHERE active = true
-const users = await userRepository.findMany();
-
-// Internally: WHERE email = 'john@email.com' AND active = true
-const user = await userRepository.findByEmail("john@email.com");
-```
-
-Useful for manual soft-deletes, multi-tenancy, and global filters of any kind.
-
----
-
-## Default Ordering
-
-`defaultOrdering` defines a default ordering that's automatically applied to every query that accepts `orderBy`, without needing to repeat the `order` argument on every call.
-
-```ts
-const userRepository = setupVSRepo<User, "user">()(({
-  tableName: "user",
-  pkName: "id",
-  defaultOrdering: { createdAt: "desc" },
-}).build(prisma);
-```
-
-With this, every listing query will already come ordered by `createdAt` descending:
-
-```ts
-// Internally: ORDER BY createdAt DESC
-const users = await userRepository.getAll();
-
-// Also applies to getAll with pagination
-const paginated = await userRepository.getAll({ pagination: { take: 10 } });
-```
-
-**`defaultOrdering` is ignored when:**
-
-- The method uses the `Ordered`, `OrderedAndPaginated`, or `PaginatedAndOrdered` suffix — in these cases the `order` argument passed in the call takes priority.
-- The dynamic method has `injectOrdering` configured — the method's fixed ordering takes precedence.
-
-```ts
-methods: {
-  findManyPaginatedAndOrdered: { map: true },         // order comes from the argument → defaultOrdering ignored
-  findManyByActive:            { map: true },         // no Ordered → defaultOrdering applied
-  findManyByStatus: {
-    map: true,
-    injectOrdering: { name: "asc" },                  // injectOrdering → defaultOrdering ignored
-  },
-}
+const userWithAddress = await userRepository.get(id, {
+    relations: { address: true },
+});
 ```
 
-> `defaultOrdering` accepts the same type as Prisma's native `orderBy` for the model — including arrays of chained orderings.
-
----
-
-## `see` option
+- `select` mirrors the entity's shape: scalar fields take a `boolean`; relation fields take a `boolean` or a nested `select`.
+- `relations` eagerly loads related records; each relation field takes a `boolean` or a nested `relations` object.
+- Whether `select` and `relations` can be combined depends on the adapter (see below).
 
-When `softRemovekName` is configured, every method accepts the `see` option to control the visibility of soft-deleted records:
-
-| Value       | Behavior                                                      |
-| ----------- | --------------------------------------------------------------|
-| `"active"`  | Returns only records that are **not** removed (default)       |
-| `"removed"` | Returns only removed records                                  |
-| `"all"`     | Returns all records, regardless of status                     |
-
-```ts
-// Returns only active users (default)
-const active = await userRepository.getAll();
-
-// Returns only removed users
-const removed = await userRepository.getAll({ see: "removed" });
-
-// Returns all
-const all = await userRepository.getAll({ see: "all" });
-```
-
-> The `see` option works independently of `requiredWhere` — it's applied on top of the soft-delete filter, not as a replacement for it.
+> ⚠️ **Adapter-dependent behavior for `relations`:**
+>
+> The core only forwards `MethodOptions.select` and `MethodOptions.relations` to the adapter — each adapter decides how to translate them to the underlying ORM:
+>
+> - **TypeORM (`@vsrepo/typeorm-adapter`)** — `relations` is **required** to load any relation, even when you only want a nested projection via `select`. TypeORM will not JOIN/emit the relation unless it is listed in `relations`:
+>     ```typescript
+>     // TypeORM: select alone is NOT enough
+>     await userRepository.get(id, {
+>         select: { id: true, address: { city: true } },
+>         relations: { address: true }, // ← required in TypeORM
+>     });
+>     ```
+> - **Prisma 7 (`@vsrepo/prisma7-adapter` / `VSRepoPrisma7Adapter`)** — `relations` is converted to Prisma `include` (`parsePrismaInclude`). **If `select` is present, `relations` is ignored** because Prisma does not allow `select` + `include` in the same query:
+>     ```typescript
+>     // Prisma7: relations is ignored when select exists
+>     await userRepository.get(id, {
+>         select: { id: true, name: true },
+>         relations: { address: true }, // ← ignored, include = undefined
+>     });
+>     ```
+>
+> Custom adapters may map `relations` differently — consult the adapter's documentation for the exact semantics.
 
 ---
 
 ## Dynamic methods
 
-Dynamic methods are defined in the `methods` property and have their behavior inferred from their name.
-
-```ts
-methods: {
-  findOneByEmail:     { map: true },
-  findManyPaginated:  { map: true },
-  updateById:         { map: true },
-  deleteManyByIdIn:   { map: true },
+Dynamic methods are declared as a `declare` field annotated with `@DynamicMethod()`. Their behavior — which adapter method to call, which filters to apply, and how arguments map to them — is inferred entirely from the field's **name**, following the same convention-over-configuration philosophy as v1.
+
+```typescript
+class UserRepository extends VSRepository<User, string> {
+    @DynamicMethod()
+    declare findByEmail: (email: string) => Promise<User[]>;
+
+    @DynamicMethod()
+    declare findOneByEmail: (email: string) => Promise<User | null>;
+
+    @DynamicMethod()
+    declare updateById: (id: string, data: DeepPartial<User>) => Promise<User>;
+
+    // Where-based: VSRepoWhere<T> as the first param, pagination penultimate, MethodOptions last
+    @DynamicMethod()
+    declare findWherePaginated: (
+        where: VSRepoWhere<User>,
+        pagination: Pagination,
+        options?: MethodOptions<User>,
+    ) => Promise<User[]>;
+
+    // OrderedAndPaginated: field filters, then order, then pagination, then MethodOptions
+    @DynamicMethod()
+    declare findByNameIgnoreCaseOrAgeBetweenOrderByCreatedAtAscPaginated: (
+        name: string,
+        age: [number, number],
+        order: Ordering<User>,
+        pagination: Pagination,
+        options?: MethodOptions<User>,
+    ) => Promise<User[]>;
 }
 ```
 
----
-
 ### Available prefixes
 
-The method name's prefix determines which Prisma operation will be called and which arguments are expected.
-
-| Prefix                       | Prisma operation           | Return                   | Notes                                                                                                     |
-| ---------------------------- | -------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `findOneBy`                  | `findFirst`                | `T \| null`              | Single return.                                                                                            |
-| `findBy`                     | `findMany` / `findFirst`   | `T[]` or `T \| null`     | Default is list; use `fbMode: "one"` for a single return (**deprecated**, use `findOneBy`)                |
-| `findUniqueBy`               | `findUnique`               | `T \| null`              |                                                                                                           |
-| `findUniqueOrThrowBy`        | `findUniqueOrThrow`        | `T`                      | Throws an error if not found                                                                              |
-| `findFirstBy`                | `findFirst`                | `T \| null`              | Accepts fields as filter                                                                                  |
-| `findFirstOrThrowBy`         | `findFirstOrThrow`         | `T`                      | Accepts fields as filter; throws an error if not found                                                    |
-| `findFirst`                  | `findFirst`                | `T \| null`              | No field filters; applies only `requiredWhere` and `pushWhere`                                            |
-| `findFirstOrThrow`           | `findFirstOrThrow`         | `T`                      | No field filters; applies only `requiredWhere` and `pushWhere`; throws an error if not found              |
-| `findManyBy`                 | `findMany`                 | `T[]`                    | Accepts fields as filter                                                                                  |
-| `findMany`                   | `findMany`                 | `T[]`                    | No field filters; applies only `requiredWhere` and `pushWhere`                                            |
-| `findOneWhere`               | `findFirst`                | `T \| null`              | Receives an explicit `where` object as argument                                                           |
-| `findListWhere`              | `findMany`                 | `T[]`                    | Receives an explicit `where` object as argument                                                           |
-| `existsBy`                   | `findFirst`                | `boolean`                | Returns `true` if found, `false` otherwise                                                                |
-| `existsWhere`                | `findFirst`                | `boolean`                | Receives an explicit `where` object and returns whether it exists                                         |
-| `countBy`                    | `count`                    | `number`                 | Accepts fields as filter                                                                                  |
-| `countWhere`                 | `count`                    | `number`                 | Receives an explicit `where` object as argument                                                           |
-| `count`                      | `count`                    | `number`                 | No field filters; applies only `requiredWhere` and `pushWhere`                                            |
-| `create`                     | `create`                   | `T`                      | Receives `data` as argument                                                                               |
-| `createMany`                 | `createMany`               | `{ count: number }`      | Receives `data` as argument; supports `SkipDuplicates`                                                    |
-| `createManyAndReturn`        | `createManyAndReturn`      | `T[]`                    | Receives `data` as argument; supports `SkipDuplicates`                                                    |
-| `updateBy`                   | `update`                   | `T`                      | Receives `data` as argument                                                                               |
-| `updateManyBy`               | `updateMany`               | `{ count: number }`      | Receives `data` as argument                                                                               |
-| `updateManyWhere`            | `updateMany`               | `{ count: number }`      | Receives a `where` object and a `data` object as arguments                                                |
-| `updateManyAndReturnBy`      | `updateManyAndReturn`      | `T[]`                    | Receives `data` as argument                                                                               |
-| `updateManyAndReturnWhere`   | `updateManyAndReturn`      | `T[]`                    | Receives a `where` object and a `data` object as arguments                                                |
-| `upsertBy`                   | `upsert`                   | `T`                      | Receives `update` and `create` as arguments                                                               |
-| `deleteBy`                   | `delete`                   | `T`                      |                                                                                                           |
-| `deleteManyBy`               | `deleteMany`               | `{ count: number }`      |                                                                                                           |
-| `deleteManyWhere`            | `deleteMany`               | `{ count: number }`      | Receives an explicit `where` object as argument                                                           |
-| `aggregate`                  | `aggregate`                | `Dynamic`                | Name must be exact; receives native Prisma args; ignores `selectModels`, `pushWhere`, and `requiredWhere` |
-| `groupBy`                    | `groupBy`                  | `Dynamic[]`              | Name must be exact; receives native Prisma args; ignores `selectModels`, `pushWhere`, and `requiredWhere` |
-
----
+| Prefix                     | Adapter method        | Notes                                                                                    |
+| -------------------------- | --------------------- | ---------------------------------------------------------------------------------------- |
+| `findBy`                   | `findMany`            | Field filters follow the prefix.                                                         |
+| `findOneBy`                | `findOne`             | Field filters follow the prefix; single result.                                          |
+| `findOneOrThrowBy`         | `findOneOrThrow`      | Throws if no record is found.                                                            |
+| `findOneOrThrow`           | `findOneOrThrow`      | No field filters; applies only soft-delete/`see`.                                        |
+| `findOneOrThrowWhere`      | `findOneOrThrow`      | Receives a `VSRepoWhere<T>` as the first argument.                                       |
+| `findWhere`                | `findMany`            | Receives a `VSRepoWhere<T>` as the first argument.                                       |
+| `findOneWhere`             | `findOne`             | Receives a `VSRepoWhere<T>` as the first argument.                                       |
+| `findOne`                  | `findOne`             | No field filters; applies only soft-delete/`see`.                                        |
+| `countBy`                  | `count`               | Field filters follow the prefix.                                                         |
+| `countWhere`               | `count`               | Receives a `VSRepoWhere<T>` as the first argument.                                       |
+| `count`                    | `count`               | No field filters.                                                                        |
+| `existsBy`                 | `exists`              | Returns `boolean`.                                                                       |
+| `existsWhere`              | `exists`              | Receives a `VSRepoWhere<T>` as the first argument.                                       |
+| `create`                   | `create`              | Receives `data` as argument.                                                             |
+| `createMany`               | `createMany`          | Receives `data[]` as argument; supports `IgnoreConflicts`.                               |
+| `createManyReturning`      | `createManyReturning` | Receives `data[]` as argument; supports `IgnoreConflicts`; returns the created records (`T[]`) instead of `CountResult`. |
+| `updateBy`                 | `update`              | Field filters + `data` as argument.                                                      |
+| `updateWhere`              | `update`              | Receives a `VSRepoWhere<T>` as the first argument, then `data`.                          |
+| `updateManyBy`             | `updateMany`          | Field filters + `data`.                                                                  |
+| `updateManyWhere`          | `updateMany`          | Receives a `VSRepoWhere<T>` as the first argument, then `data`.                          |
+| `updateManyReturningBy`    | `updateManyReturning` | Field filters + `data`; returns updated records.                                         |
+| `updateManyReturningWhere` | `updateManyReturning` | Receives a `VSRepoWhere<T>` as the first argument, then `data`; returns updated records. |
+| `upsertBy`                 | `upsert`              | Field filters + `create`/`update` payloads.                                              |
+| `upsertWhere`              | `upsert`              | Receives a `VSRepoWhere<T>` as the first argument, then `create`/`update` payloads.      |
+| `deleteBy`                 | `delete`              | Field filters follow the prefix.                                                         |
+| `deleteWhere`              | `delete`              | Receives a `VSRepoWhere<T>` as the first argument.                                       |
+| `deleteManyBy`             | `deleteMany`          | Field filters follow the prefix.                                                         |
+| `deleteManyWhere`          | `deleteMany`          | Receives a `VSRepoWhere<T>` as the first argument.                                       |
+| `deleteManyReturningBy`    | `deleteManyReturning` | Field filters follow the prefix; returns deleted records.                                |
+| `deleteManyReturningWhere` | `deleteManyReturning` | Receives a `VSRepoWhere<T>` as the first argument; returns deleted records.              |
+
+> `aggregate` and `groupBy` are **not implemented yet** in v2 (they existed in v1). This is planned but not currently available.
 
 ### Field filters
 
-Filters are suffixes applied to the field name inside the method. The field itself comes capitalized right after the prefix (or after `By`).
-
-| Suffix               | Prisma operator        | Argument required          |
-| -------------------- | ---------------------- | ---------------------------|
-| *(no suffix)*        | equality (`=`)         | yes                        |
-| `Not`                | `not`                  | yes                        |
-| `In`                 | `in`                   | yes (array)                |
-| `NotIn`              | `notIn`                | yes (array)                |
-| `Contains`           | `contains`             | yes                        |
-| `NotContains`        | `not.contains`         | yes                        |
-| `StartsWith`         | `startsWith`           | yes                        |
-| `NotStartsWith`      | `not.startsWith`       | yes                        |
-| `EndsWith`           | `endsWith`             | yes                        |
-| `NotEndsWith`        | `not.endsWith`         | yes                        |
-| `GreaterThan`        | `gt`                   | yes                        |
-| `GreaterThanEqual`   | `gte`                  | yes                        |
-| `LessThan`           | `lt`                   | yes                        |
-| `LessThanEqual`      | `lte`                  | yes                        |
-| `Between`            | `gte` + `lte`          | yes (tuple `[min, max]`)   |
-| `NotBetween`         | `not.gte` + `not.lte`  | yes (tuple `[min, max]`)   |
-| `IsNull`             | `null`                 | no                         |
-| `IsNotNull`          | `not: null`            | no                         |
-| `IsTrue`             | `true`                 | no                         |
-| `IsFalse`            | `false`                | no                         |
-| `Insensitive`        | `mode: 'insensitive'`  | combinator                 |
-
-`Insensitive` is a combinator and can be used together with another text filter:
-
-```ts
-findByNameContainsInsensitive    // { name: { contains: value, mode: 'insensitive' } }
-findByEmailStartsWithInsensitive // { email: { startsWith: value, mode: 'insensitive' } }
-findByNameInsensitive            // { name: { equals: value, mode: 'insensitive' } }
-```
-
-`Between` and `NotBetween` receive a **tuple `[minValue, maxValue]`**:
-
-```ts
-methods: {
-  findManyByAgeBetween:      { map: true },
-  findManyBySalaryNotBetween: { map: true },
-  findManyByCreatedAtBetween: { map: true },
-}
-
-await userRepository.findManyByAgeBetween([18, 65]);
-await userRepository.findManyBySalaryNotBetween([1000, 5000]);
-await userRepository.findManyByCreatedAtBetween([new Date("2024-01-01"), new Date("2024-12-31")]);
-```
-
-The `Optional` suffix can be added to any field to make the argument optional:
-
-```ts
-findByNameOptionalAndEmail // name is optional, email is required
+Applied as suffixes to the field name inside the method (same idea as v1, one renamed suffix):
+
+| Suffix             | Meaning                                                                                                                                                       | Argument                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| _(none)_           | equality (`=`)                                                                                                                                                | yes                                    |
+| `Not`              | negation                                                                                                                                                      | yes                                    |
+| `In`               | is one of                                                                                                                                                     | yes (array)                            |
+| `NotIn`            | is none of                                                                                                                                                    | yes (array)                            |
+| `Contains`         | substring match                                                                                                                                               | yes                                    |
+| `NotContains`      | negated substring match                                                                                                                                       | yes                                    |
+| `StartsWith`       | prefix match                                                                                                                                                  | yes                                    |
+| `NotStartsWith`    | negated prefix match                                                                                                                                          | yes                                    |
+| `EndsWith`         | suffix match                                                                                                                                                  | yes                                    |
+| `NotEndsWith`      | negated suffix match                                                                                                                                          | yes                                    |
+| `GreaterThan`      | `>`                                                                                                                                                           | yes                                    |
+| `GreaterThanEqual` | `>=`                                                                                                                                                          | yes                                    |
+| `LessThan`         | `<`                                                                                                                                                           | yes                                    |
+| `LessThanEqual`    | `<=`                                                                                                                                                          | yes                                    |
+| `Between`          | inclusive range                                                                                                                                               | yes (`[min, max]` tuple)               |
+| `NotBetween`       | outside an inclusive range                                                                                                                                    | yes (`[min, max]` tuple)               |
+| `IsNull`           | field is `null`                                                                                                                                               | no                                     |
+| `IsNotNull`        | field is not `null`                                                                                                                                           | no                                     |
+| `IsTrue`           | field is `true`                                                                                                                                               | no                                     |
+| `IsFalse`          | field is `false`                                                                                                                                              | no                                     |
+| `IgnoreCase`       | case-insensitive combinator for text filters                                                                                                                  | no _(renamed from v1's `Insensitive`)_ |
+| `Optional`         | **explicitly** marks the field's argument as optional — it's already optional by default, so this suffix is itself optional and only used to make it explicit | —                                      |
+
+```typescript
+@DynamicMethod()
+declare findByNameContainsIgnoreCase: (name: string) => Promise<User[]>;
+
+@DynamicMethod()
+declare findByAgeBetween: (age: [number, number]) => Promise<User[]>;
 ```
 
----
-
 ### Logical operators
 
-| Operator  | Usage in the name              | Example                            |
-| --------- | ------------------------------ | ---------------------------------- |
-| `And`     | between two fields             | `findOneByIdAndEmail`              |
-| `Or`      | between two fields             | `findByNameOrEmail`                |
-| `AND`     | separates a final `AND` block  | `findByEmailOrNameANDActiveStatus` |
-
-`AND` (in caps) has a specific rule:
+| Operator | Usage in the name               | Example                                             |
+| -------- | ------------------------------- | --------------------------------------------------- |
+| `And`    | between two fields              | `findOneByIdAndEmail`                               |
+| `Or`     | between two fields              | `findByNameOrEmail`                                 |
+| `AND`    | splits a final block into `AND` | `findByEmailOrNameANDActiveStatusAndAgeGreaterThan` |
 
-- Only **one** `AND` can exist per method.
-- All fields after `AND` are injected inside `AND: []`.
-- After an `AND`, there can't be an `Or`.
+`AND` (all caps) rules, same as v1: only one `AND` per method name is allowed; every field connected with `And` after it is nested inside `AND: []`; `Or` cannot appear after an `AND`.
 
-Example:
+### Relation filters
 
-```ts
-methods: {
-  findOneByIdAndEmail:   { map: true },
-  findByNameOrEmail:  { map: true },
-  findFirstByIdOrEmailAndName: { map: true },
-  findByEmailOrNameANDActiveStatusAndAgeGreaterThan: { map: true }
-}
+Filter by fields of related entities. Internally these map to the `_some`/`_every`/`_none`/`_with`/`_without` operators of `VSRepoWhere` (see [`select` and `relations`](#select-and-relations) for the eager-loading counterpart).
 
-await userRepository.findOneByIdAndEmail(1, "john@email.com");
-await userRepository.findByNameOrEmail("John", "john@email.com");
-await userRepository.findFirstByIdOrEmailAndName(1, "john@email.com", "John");
-await userRepository.findByEmailOrNameANDActiveStatusAndAgeGreaterThan("john@email.com", "John", true, 17)
-```
+| Suffix         | Meaning                                         | Restriction                                                |
+| -------------- | ----------------------------------------------- | ---------------------------------------------------------- |
+| `Some`         | at least one related record matches             | to-many relations only                                     |
+| `SomeField`    | filters within the related records              | to-many relations only                                     |
+| `Every`        | every related record matches                    | to-many relations only (needs `Field` to be a real filter) |
+| `EveryField`   | filters within the related records              | to-many relations only                                     |
+| `None`         | no related record matches                       | to-many relations only                                     |
+| `NoneField`    | filters within the related records              | to-many relations only                                     |
+| `With`         | related record exists                           | to-one relations only                                      |
+| `WithField`    | filters a field within the related record       | to-one relations only                                      |
+| `Without`      | related record does not exist                   | to-one relations only                                      |
+| `WithoutField` | negated filter on a field of the related record | to-one relations only                                      |
 
-Generates (`findOneByIdAndEmail`):
+```typescript
+@DynamicMethod()
+declare findByAddressWithCityStartsWithIgnoreCase: (city: string) => Promise<User[]>;
 
-```ts
-{
-  id: 1,
-  email: "john@email.com"
-}
+@DynamicMethod()
+declare findByProductsSome: () => Promise<User[]>;
 ```
 
-Generates (`findByNameOrEmail`):
+### Ordering, pagination and distinct
 
-```ts
-{
-  OR: [
-    { name: "John" },
-    { email: "john@email.com" }
-  ]
-}
-```
+| Suffix                                     | Effect                                                                                                                                                             |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Paginated`                                | Injects a `pagination` argument (`{ limit?, offset? }`) as the **penultimate** parameter (before the optional `MethodOptions`).                                    |
+| `Ordered`                                  | Injects an `order: Ordering<T>` argument as the **penultimate** parameter (before the optional `MethodOptions`).                                                   |
+| `OrderedAndPaginated`                      | Injects `order` as the antepenultimate, then `pagination` as the penultimate — both before `MethodOptions`.                                                        |
+| `PaginatedAndOrdered`                      | Injects `pagination` as the antepenultimate, then `order` as the penultimate — both before `MethodOptions`.                                                        |
+| `OrderBy<Field>Asc` / `OrderBy<Field>Desc` | **New in v2.** Bakes a fixed ordering directly into the method name — chain fields with `And` (e.g. `OrderByCreatedAtAscAndNameDesc`). No `order` argument needed. |
+| `Distinct<Field>And<Field>...`             | Bakes fixed `distinct` fields directly into the method name (only valid on `findBy`/`findWhere`-family methods).                                                   |
+| `IgnoreConflicts`                          | On `createMany`/`createManyReturning`, skips records that would violate a unique constraint instead of throwing. _(Renamed from v1's `SkipDuplicates`.)_           |
 
-Generates (`findFirstByIdOrEmailAndName`):
-
-```ts
-{
-  OR: [
-    { id: 1 },
-    {
-      email: "john@email.com",
-      name: "John"
-    }
-  ]
-}
-```
+> ⚠️ **Parameter order:** `pagination` and `order` are always placed **before** the optional `MethodOptions<T>` last argument. When both `order` and `pagination` are present, their relative order follows the suffix name (`OrderedAndPaginated` → order, pagination; `PaginatedAndOrdered` → pagination, order).
 
-Generates (`findByEmailOrNameANDActiveStatusAndAgeGreaterThan`):
+```typescript
+// Paginated: pagination is the penultimate param (before MethodOptions)
+@DynamicMethod()
+declare findByActiveOrderByCreatedAtDescPaginated:
+    (active: boolean, pagination: Pagination, options?: MethodOptions<User>) => Promise<User[]>;
 
-```ts
-{
-  OR: [
-    { email: "john@email.com" },
-    { name: "John" }
-  ],
-  AND: [
-    { activeStatus: true },
-    { age: { gt: 17 } }
-  ]
-}
-```
+// OrderedAndPaginated: order, then pagination, then MethodOptions
+@DynamicMethod()
+declare findByNameContainsIgnoreCaseOrderedAndPaginated:
+    (name: string, order: Ordering<User>, pagination: Pagination, options?: MethodOptions<User>) => Promise<User[]>;
 
----
+@DynamicMethod()
+declare createManyIgnoreConflicts: (data: DeepPartial<User>[]) => Promise<{ count: number }>;
 
-### Relation filters
+// createManyReturning: same as createMany, but returns the created records
+@DynamicMethod()
+declare createManyReturningIgnoreConflicts: (data: DeepPartial<User>[]) => Promise<User[]>;
 
-Allow filtering by fields of related models.
+// findOne with no filter (equivalent to findOneOrThrow with no filter, but returns null instead of throwing)
+@DynamicMethod()
+declare findOne: (options?: MethodOptions<User>) => Promise<User | null>;
+```
 
-> [!IMPORTANT]
+> ⚠️ **Precedence between `Distinct` and `OrderBy`:** when both are used in the same method name, **`Distinct` must come before `OrderBy`**:
 >
-> - **Relation typing**: For TypeScript to recognize the types of relation fields in dynamic methods, the generic entity type passed to `setupVSRepo` must include the structured relations (e.g. using Prisma's `UserGetPayload<{ include: { profile: true, posts: true } }>`).
-> - **Suffix compatibility**:
->   - The `Some`, `Every`, and `None` suffixes only work for **to-many** relations (`many-to-many` and `one-to-many`).
->   - The `With` and `Without` suffixes only work for **to-one** relations (`one-to-one` and `many-to-one`).
-
-| Relation suffix       | Prisma operator   | Note                                                  |
-| --------------------- | ----------------- | ----------------------------------------------------- |
-| `Some`                | `some: {}`        | Relation has *some* record                            |
-| `SomeField`           | `some.field`      | Filters within the relation's records                 |
-| `EveryField`          | `every.field`     | Filters within the relation's records                 |
-| `None`                | `none: {}`        | Relation has *no* records                             |
-| `NoneField`           | `none.field`      | Filters within the relation's records                 |
-| `With`                | `is: {}`          | Relation exists (not null)                            |
-| `WithField`           | `is.field`        | Filters a field within the relation                   |
-| `Without`             | `isNot: {}`       | Relation doesn't exist (is null)                      |
-| `WithoutField`        | `isNot.field`     | Filters a field within the relation with negation     |
-
-Considering `user` with a to-one relation `profile` and a to-many relation `posts`:
-
-```ts
-methods: {
-  // to-many (posts)
-  findByPostsSome:                { map: true }, // has at least one post
-  findByPostsSomeTitle:           { map: true }, // has at least one post with that title
-  findByPostsEveryPublishedIsTrue:{ map: true }, // all posts are published
-  findByPostsNone:                { map: true }, // has no posts
-  findByPostsNoneTitle:           { map: true }, // no post has that title
-
-  // to-one (profile)
-  findByProfileWith:             { map: true }, // has a profile (not null)
-  findByProfileWithBio:          { map: true }, // has a profile with that bio
-  findByProfileWithout:          { map: true }, // has no profile (is null)
-  findByProfileWithoutBio:       { map: true }, // has a profile, but with a different bio than the one provided
-}
+> ```typescript
+> @DynamicMethod()
+> declare findByActiveDistinctNameOrderByCreatedAtDesc:
+>     (active: boolean) => Promise<User[]>;
+> ```
+>
+> Putting `OrderBy` before `Distinct` (e.g. `findByActiveOrderByCreatedAtDescDistinctName`) is not a valid pattern and won't be parsed as expected.
 
-await userRepository.findByPostsSome();
-await userRepository.findByPostsSomeTitle("My first post");
-await userRepository.findByPostsEveryPublishedIsTrue();
-await userRepository.findByPostsNone();
-await userRepository.findByPostsNoneTitle("Draft");
+### Decorator options
 
-await userRepository.findByProfileWith();
-await userRepository.findByProfileWithBio("Hello, world!");
-await userRepository.findByProfileWithout();
-await userRepository.findByProfileWithoutBio("Old bio");
-```
+`@DynamicMethod<T>(options?)` accepts:
 
-Generates (`findByPostsSomeTitle`):
+| Option           | Type          | Description                                                                                                                      |
+| ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `proxyTo`        | `string`      | Redirects the method's logic to another valid dynamic-method pattern — useful for names that don't follow the naming convention. |
+| `injectOrdering` | `Ordering<T>` | Fixed ordering automatically injected, overriding the repository's `defaultOrdering`.                                            |
 
-```ts
-{
-  posts: {
-    some: { title: "My first post" }
-  }
-}
+```typescript
+@DynamicMethod<User>({ injectOrdering: { createdAt: "desc" } })
+declare findByStatus: (status: string) => Promise<User[]>;
 ```
 
-Generates (`findByPostsEveryPublishedIsTrue`):
+---
 
-```ts
-{
-  posts: {
-    every: { published: true }
-  }
-}
-```
+## Query methods (raw SQL)
 
-Generates (`findByProfileWithBio`):
+`@QueryMethod` bypasses the name-parsing engine entirely and executes a raw SQL statement through the adapter's `query()` method. Use `$1`, `$2`, ... placeholders — never interpolate values directly into the SQL string.
 
-```ts
-{
-  profile: {
-    is: { bio: "Hello, world!" }
-  }
-}
-```
-
-Generates (`findByProfileWithout`):
+```typescript
+class UserRepository extends VSRepository<User, string> {
+    @QueryMethod('SELECT * FROM "user" WHERE email = $1')
+    declare findByEmailRaw: (arg: QueryMethodArg<[email: string]>) => Promise<User[]>;
 
-```ts
-{
-  profile: {
-    isNot: {}
-  }
+    @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
+    declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
 }
 ```
 
-> `Some`, `None`, `With`, and `Without` (without a field) don't receive an argument — the whole relation is tested for the existence of records (`some`/`none`) or for being `null`/not `null` (`is`/`isNot`). The `SomeField`, `EveryField`, `NoneField`, `WithField`, and `WithoutField` variants receive the filtered field's value as an argument.
-
----
-
-### Pagination and ordering suffixes
-
-Applied at the **end** of the method name, they automatically inject the pagination and ordering arguments.
-
-| Suffix                   | Additional arguments           |
-| ------------------------ | -------------------------------|
-| `Paginated`              | `(pagination)`                 |
-| `Ordered`                | `(order)`                      |
-| `OrderedAndPaginated`    | `(order, pagination)`          |
-| `PaginatedAndOrdered`    | `(pagination, order)`          |
+| Option      | Type      | Default | Description                                                                                                                                                                          |
+| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `modifying` | `boolean` | `false` | When `true`, runs as `INSERT`/`UPDATE`/`DELETE` and the method resolves to the number of affected rows. When `false`, runs as a read query and resolves to the declared return type. |
 
-For `createMany` and `createManyAndReturn`, the `SkipDuplicates` suffix is available:
-
-| Suffix              | Effect                                     |
-| ------------------- | ------------------------------------------ |
-| `SkipDuplicates`    | Skips duplicate records during insertion   |
-
----
+Query methods accept `{ args, db? }` at the call site — `db` lets them participate in a `transaction()` block just like base and dynamic methods.
 
-### Distinct
+### Ad-hoc raw queries with `query()`
 
-The `Distinct` suffix lets you get only unique records based on one or more fields, equivalent to Prisma's `distinct` option.
+For one-off raw SQL that doesn't warrant declaring a `@QueryMethod` on the repository class, call `query()` directly — it's available on every `VSRepository` instance and goes through the same adapter's `query()` implementation under the hood:
 
-To use it, put `Distinct` in the method name (after the field filters, if any) followed by the desired fields separated by `And`. The first character of each field must be uppercase, just like in regular field filters.
-
-```ts
-methods: {
-    // Returns unique users combining "age" and "role" (no field filter)
-    findManyDistinctAgeAndRole: { map: true },
-
-    // Distinct combined with the Paginated suffix
-    findManyDistinctNamePaginated: { map: true },
-
-    // Distinct combined with a field filter (name) — filters by name and then applies distinct on role
-    findManyByNameDistinctRole: { map: true },
-},
+```typescript
+query<T = any>(query: string, options?: { args?: any[]; db?: any; modifying?: boolean }): Promise<T>;
 ```
 
-```ts
-// No arguments: the distinct fields are already fixed in the method name
-await userRepository.findManyDistinctAgeAndRole();
-
-// The pagination argument still works normally
-await userRepository.findManyDistinctNamePaginated({ take: 10, skip: 0 });
+```typescript
+const users = await userRepository.query<User[]>('SELECT * FROM "user" WHERE email = $1', {
+    args: ["maria@email.com"],
+});
 
-// The "name" field filter is still passed normally as an argument
-await userRepository.findManyByNameDistinctRole("John");
+const affectedRows = await userRepository.query<number>(
+    'UPDATE "user" SET active = true WHERE id = $1',
+    { args: ["123"], modifying: true },
+);
 ```
 
-> The fields specified after `Distinct` are resolved from the method name at build time — they **don't** become runtime arguments, unlike regular field filters.
+| Option      | Type      | Default                     | Description                                                                                                              |
+| ----------- | --------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `args`      | `any[]`   | `undefined`                 | Positional parameters injected into `$1`, `$2`, ... placeholders. Never interpolate values directly into the SQL string. |
+| `db`        | `any`     | Repository's default client | Database client or transaction to run this query in.                                                                     |
+| `modifying` | `boolean` | `false`                     | When `true`, treats the statement as `INSERT`/`UPDATE`/`DELETE`.                                                         |
 
-`Distinct` is available on prefixes that read multiple or single records: `findMany`, `findManyBy`, `findFirst`, `findFirstBy`, `findFirstOrThrow`, `findFirstOrThrowBy`, `findBy`, `findOneBy`, `findWhere`, `findOneWhere`, `findListWhere`, `existsBy`, and `existsWhere`.
+Just like base, dynamic and query methods, `query()` accepts `db` in `options` to participate in a `transaction()` block.
 
 ---
 
-### Method configuration
-
-Each entry in `methods` accepts the following options:
-
-| Option                | Type                                     | Default        | Description                                                                                                                 |
-| --------------------- | ---------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `map`                 | `boolean`                                | —              | **Required.** Defines whether the method will be exposed on the repository.                                                 |
-| `whereType`           | `'extending'` \| `'overwrite'`           | `extending`    | `extending` combines with `requiredWhere`. `overwrite` ignores `requiredWhere`.                                             |
-| `selectModel`         | `keyof SelectModels \| false`            | —              | Overrides `defaultSelectModel` for this method.                                                                             |
-| `fbMode`              | `'one'` \| `'list'`                      | `'list'`       | (**Deprecated. Use `findOneBy`**) Only for `findBy`. `'one'` returns `T \| null`; `'list'` returns `T[]`.                   |
-| `proxyTo`             | `Valid method pattern`                   | —              | Delegates the logic to another valid method pattern.                                                                        |
-| `pushWhere`           | `WhereModel<M>`                          | —              | Extra `where` added to the query in addition to `requiredWhere`.                                                            |
-| `injectOrdering`      | `OrderingModel<M>`                       | —              | Fixed ordering automatically injected into the query.                                                                       |
-| `injectPagination`    | `PaginationModel<M>`                     | —              | Fixed pagination automatically injected into the query.                                                                     |
-| `query`               | `{ value: string; modifying?: boolean }` | —              | Turns the method into a **Query Method** (raw SQL). Ignores every other option above — see [Query Methods](#query-methods). |
-
----
-
-### Aggregate and GroupBy
-
-```ts
-const userRepository = setupVSRepo<User, "user">()(({
-  tableName: "user",
-  pkName: "id",
-  methods: {
-    aggregate: { map: true },
-    groupBy: { map: true },
-  },
-}).build(prisma);
-```
-
-> [!NOTE]
-> These methods must have exactly these names (`aggregate` and `groupBy`).
-> Unlike the other dynamic methods, they receive native Prisma arguments and **ignore** the `selectModels`, `pushWhere`, and `requiredWhere` configurations.
-
----
-
-### Query Methods
-
-Query Methods let a method run **raw SQL** directly, completely bypassing the dynamic-method name parser. They're useful for complex queries (heavy joins, CTEs, database-specific functions) that aren't practical to express with the standard prefixes/suffixes.
-
-Internally, VSRepository executes the SQL through Prisma using `$queryRawUnsafe` (for reads) or `$executeRawUnsafe` (for writes), and the values in the `args` array are passed as **positional parameters** (`$1`, `$2`, ...) — the same prepared-statement technique Prisma itself uses. This means the values are never concatenated into the SQL string, which is what actually prevents SQL injection.
-
-> [!WARNING]
-> `$1`, `$2`, ... in your SQL must always represent **values** (data parameters), never column names, table names, or dynamic SQL fragments. Identifier names (columns/tables) can't be passed as a positional parameter — if your method needs to vary those, build the SQL from a fixed, known set of options in your own code, never from untrusted input.
-
-```ts
-const userRepository = setupVSRepo<User, "user">()({
-  tableName: "user",
-  pkName: "id",
-  methods: {
-    // Read query method (non-modifying)
-    findActiveUsersRaw: {
-      map: true,
-      query: {
-        value: 'SELECT * FROM "user" WHERE active = $1',
-      },
-    },
-
-    // Write query method (modifying: true)
-    deactivateUsersOlderThanRaw: {
-      map: true,
-      query: {
-        value: 'UPDATE "user" SET active = false WHERE "createdAt" < $1',
-        modifying: true,
-      },
-    },
-  },
-}).build(prisma);
-```
-
-**Calling a Query Method:**
+## Transactions
 
-Every Query Method takes a single argument shaped as `{ args: [...], db? }`:
+All methods (base, dynamic, and query) accept `options.db` to participate in a shared transaction:
 
-```ts
-// Non-modifying: returns 'any' by default, but accepts a generic to
-// infer/assert the return type right at the call site
-const activeUsers = await userRepository.findActiveUsersRaw<User[]>({
-  args: [true],
-});
+```typescript
+await userRepository.transaction(async tx => {
+    const user = await userRepository.save({ name: "Maria", email: "maria@email.com" }, { db: tx });
 
-// Modifying: always returns 'number' (count of affected rows)
-const affected = await userRepository.deactivateUsersOlderThanRaw({
-  args: [new Date("2024-01-01")],
-});
-
-// Participating in a transaction, via 'db'
-await userRepository.prisma.$transaction(async (tx) => {
-  await userRepository.deactivateUsersOlderThanRaw({
-    args: [new Date("2024-01-01")],
-    db: tx,
-  });
+    await userLogsRepository.save(
+        { action: "User created", data: { userId: user.id } },
+        { db: tx },
+    );
 });
 ```
 
-| Option        | Type      | Default | Description                                                                                                                                                                                                                               |
-| ------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`       | `string`  | —       | **Required.** Raw SQL to execute. Use `$1`, `$2`, ... for the placeholders of the values in `args`.                                                                                                                                       |
-| `modifying`   | `boolean` | `false` | When `true`, executes via `$executeRawUnsafe` and the method always resolves to `number`. When `false`, executes via `$queryRawUnsafe` and the method resolves to `TReturn` (`any` by default, inferable via a generic at the call site). |
-
-> [!NOTE]
-> Unlike the other dynamic methods, Query Methods **completely ignore** `selectModels`, `requiredWhere`, `pushWhere`, `whereType`, `injectOrdering`, `injectPagination`, and `proxyTo` — none of that applies, since there's no name parsing or `where`/`select` assembly by VSRepository. Free-form method names (outside the `findBy`, `updateBy`, etc. patterns) also **don't** require `proxyTo`.
-
-The same functionality is available in the class-based approach via the `@QueryMethod` decorator — see [README-DynamicRepo.md](./README-DynamicRepo.md#the-querymethod-decorator).
-
----
+Different repositories can share the same transaction as long as their adapters point to the same underlying ORM connection.
 
-## Relations in save
+`transaction()` accepts an optional `VSRepoTransactionOptions` as its second argument:
 
-Configure relations so that `save` and `patch` manage them automatically (`saveList` and `patchList` also manage relations automatically).
+```typescript
+import { TransactionIsolationLevel } from "vsrepo";
 
-```ts
-import type { Prisma } from "../../generated/prisma/client";
-
-type User = Prisma.userGetPayload<{
-  include: { profile: true; posts: true };
-}>;
-
-const userRepository = setupVSRepo<User, "user">()(({
-  tableName: "user",
-  pkName: "id",
-
-  relations: {
-    profile: {
-      pk: "id",
-      mode: "oto",
-      restriction: "set",
+await userRepository.transaction(
+    async tx => {
+        await userRepository.save({ name: "Maria", email: "maria@email.com" }, { db: tx });
     },
-    posts: {
-      pk: "id",
-      mode: "otm",
-      restriction: "add",
-    },
-  },
-}).build(prisma);
+    { isolationLevel: TransactionIsolationLevel.SERIALIZABLE, timeoutMs: 5000 },
+);
 ```
 
-**Relation modes:**
-
-| Mode  | Relation       |
-| ----- | -------------- |
-| `oto` | one-to-one     |
-| `otm` | one-to-many    |
-| `mto` | many-to-one    |
-| `mtm` | many-to-many   |
+| Option           | Type                       | Description                                                                    |
+| ----------------- | -------------------------- | -------------------------------------------------------------------------------- |
+| `isolationLevel` | `TransactionIsolationLevel` | Isolation level to use for the transaction. Defaults to the underlying ORM's default. |
+| `timeoutMs`       | `number`                    | Maximum time (in ms) the transaction is allowed to run before being aborted.     |
 
-**Restrictions:**
+`TransactionIsolationLevel` mirrors the standard SQL isolation levels: `READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE`. Support for a given level depends on the adapter/underlying ORM and database.
 
-| Restriction  | Behavior on update                                     |
-| ------------ | ------------------------------------------------------ |
-| `set`        | Fully replaces (removes the ones that weren't sent)    |
-| `add`        | Adds/updates without removing existing ones            |
+---
 
-> [!WARNING]
-> **`set` means different things depending on the relation's `mode` — and this can cause data loss if you're not careful.**
->
-> In relations where the related record **belongs** to the parent record (`oto` and `otm`), "removing the ones that weren't sent" means **deleting the record from the database** (`delete`/`deleteMany`). In relations where the related record is **independent** (`mto` and `mtm`), "removing" just means **unlinking** (`disconnect`/`set: []`) — the related record continues to exist in the database, it just stops pointing to the parent (or being in the join table).
->
-> | Mode | `restriction: "set"` when an item is omitted | Does the item continue to exist in the database? |
-> | ----- | ------------------------------------------------ | ----------------------------------------------------- |
-> | `oto` | Passing `null` in the field → **deletes** the related record (`delete: true`) | No |
-> | `otm` | Items outside the sent list → **deleted** (`deleteMany` with `notIn`) | No |
-> | `mto` | Passing `null` in the field (with `nullable: true`) → **unlinks** (`disconnect: true`) | Yes |
-> | `mtm` | Items outside the sent list → **unlinked** from the join table (`set: []`) | Yes |
->
-> Practical example: if `posts` is `otm` with `restriction: "set"`, a `save`/`patch` that sends the user with only 2 of the 5 existing posts will **delete the other 3 posts from the database**, not just unlink them from the user. If the expected behavior is just to unlink without deleting, use `restriction: "add"` (which never removes anything) and handle removal manually.
+## Utility types
 
-**`mto` relation with nullable:**
+Beyond the entity-shaping types covered above (`VSRepoSelect`, `VSRepoRelations`, `VSRepoWhere`), VSRepository exports a set of utility types. They show up throughout the sections above, but here's a consolidated reference. All of them are part of the public API and can be imported directly:
 
-Use `nullable` (lowercase) to allow unlinking a many-to-one relation:
+```typescript
+import type {
+    MethodOptions,
+    Pagination,
+    Ordering,
+    OrderByField,
+    SortDirection,
+    SeeMode,
+    DeepPartial,
+    CountResult,
+    QueryMethodArg,
+    KeysOfType,
+    Primitive,
+    VSRepoWhere,
+    VSRepoOrmTypes,
+    VSRepoTransactionOptions,
+    TransactionIsolationLevel,
+} from "vsrepo";
+```
+
+| 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).                                                                                           |
+| `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).                                                                                                                                  |
+| `DeepPartial<T>`                                    | Recursively makes every property of `T` optional, including nested objects and array elements.                                                                                                       | `save`, `saveList`, `patch`, `merge`, and every write method on `VSRepoAdapter`.                                                                              |
+| `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.                          |
+| `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).                                                                                                              |
+| `VSRepoTransactionOptions`                          | `{ isolationLevel?, timeoutMs? }` — options accepted as the second argument of `transaction()`.                                                                                                      | [Transactions](#transactions).                                                                                                                                |
+| `TransactionIsolationLevel`                         | Enum of standard SQL isolation levels (`READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE`) accepted by `VSRepoTransactionOptions.isolationLevel`.                              | [Transactions](#transactions).                                                                                                                                |
+
+### `DeepPartial<T>`
+
+Recursively makes all properties optional, walking into nested objects and array elements — unlike TypeScript's built-in `Partial<T>`, which only makes the top level optional:
+
+```typescript
+type User = { id: string; name: string; address: { city: string; zip: string } };
+
+const patch: DeepPartial<User> = {
+    address: { city: "São Paulo" }, // zip can be omitted; city keeps its type
+};
 
-```ts
-relations: {
-  category: {
-    pk: "id",
-    mode: "mto",
-    restriction: "set",
-    nullable: true, // allows passing null to unlink
-  },
+await userRepository.patch(id, patch);
+```
+
+### `KeysOfType<T, K>`
+
+Filters an object type down to the keys whose value matches a given type — this is what lets `pkName` accept only fields of the entity that are actually assignable to the repository's primary-key type:
+
+```typescript
+type User = { id: string; age: number; name: string };
+type StringKeys = KeysOfType<User, string>; // "id" | "name"
+```
+
+### `Ordering<T>`
+
+Accepts either a single ordering object or an array of them, applied in the order they're declared:
+
+```typescript
+const order: Ordering<User> = { createdAt: "desc" };
+const chained: Ordering<User> = [{ name: "asc" }, { createdAt: "desc" }];
+
+await userRepository.getAll({ order: chained });
+```
+
+---
+
+## Writing your own adapter
+
+Because the core is ORM-agnostic and ships without a bundled adapter, adding support for an ORM/database — whether that's a stopgap for your own project or a candidate for a future `@vsrepo/*-adapter` package — means implementing the `VSRepoAdapter<T>` abstract class:
+
+```typescript
+export abstract class VSRepoAdapter<T> {
+    abstract runInTransaction<R>(
+        fn: (tx: any) => Promise<R>,
+        options?: VSRepoTransactionOptions,
+    ): Promise<R>;
+    abstract getDbClient(): any;
+    abstract query<T = any>(query: string, options?: AdapterQueryOptions): Promise<T>;
+    abstract findOne(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T | null>;
+    abstract findOneOrThrow(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    abstract findMany(
+        where: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T> & { distinct?: (keyof T)[] },
+    ): Promise<T[]>;
+    abstract save(obj: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    abstract saveMany(objs: DeepPartial<T>[], options?: AdapterMethodOptions<T>): Promise<T[]>;
+    abstract create(objs: DeepPartial<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    abstract createMany(
+        objs: DeepPartial<T>[],
+        options?: AdapterMethodOptions<T> & { ignoreConflicts?: boolean },
+    ): Promise<CountResult>;
+    abstract createManyReturning(
+        objs: DeepPartial<T>[],
+        options?: AdapterMethodOptions<T> & { ignoreConflicts?: boolean },
+    ): Promise<T[]>;
+    abstract delete(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<T>;
+    abstract deleteMany(
+        where: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<CountResult>;
+    abstract deleteManyReturning(
+        where: VSRepoWhere<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T[]>;
+    abstract update(
+        where: VSRepoWhere<T>,
+        obj: DeepPartial<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T>;
+    abstract updateMany(
+        where: VSRepoWhere<T>,
+        obj: DeepPartial<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<CountResult>;
+    abstract updateManyReturning(
+        where: VSRepoWhere<T>,
+        obj: DeepPartial<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T[]>;
+    abstract count(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<number>;
+    abstract exists(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>): Promise<boolean>;
+    abstract merge<K>(
+        where: VSRepoWhere<T>,
+        obj: DeepPartial<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<K & T>;
+    abstract upsert(
+        where: VSRepoWhere<T>,
+        create: DeepPartial<T>,
+        update: DeepPartial<T>,
+        options?: AdapterMethodOptions<T>,
+    ): Promise<T>;
 }
 ```
 
----
+`VSRepository` never talks to the ORM directly — it only calls these methods with an already-resolved `VSRepoWhere<T>` and `AdapterMethodOptions<T>`. Once an adapter implements this contract, every base method, dynamic method, and query method works against it automatically. For a full, working implementation, see the external [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) repo.
 
-## Transactions
+### Logging from your adapter
 
-All methods accept `options.db` to participate in a transaction:
+`vsrepo` exports the same `VSLogger` class the core uses internally, so your adapter can log in the same format/style (timestamps, colored level labels, slow-operation warnings) instead of rolling its own:
 
-```ts
-await userRepository.prisma.$transaction(async (tx) => {
-  const user = await userRepository.save(
-    { name: "Mary", email: "mary@email.com", password: "password" },
-    { db: tx }
-  );
+```typescript
+import { VSLogger, VSLogLevel } from "vsrepo";
 
-  await userLogsRepository.save(
-    { action: "User registration", data: { registeredUser: user.id } },
-    { db: tx }
-  );
-});
-```
+export class MyOrmAdapter<T> extends VSRepoAdapter<T> {
+    private readonly logger = new VSLogger(VSLogLevel.WARN, "MyOrmAdapterLogger");
 
-For `saveList` and `patchList`, the `db` field must be a `DbTransaction`:
-
-```ts
-await prisma.$transaction(async (tx) => {
-  // CORRECT: tx is a DbTransaction
-  const registeredUsers = await userRepository.saveList([{ name: "Mary" }, { name: "Lucas" }], { db: tx });
-
-  await userLogsRepository.save(
-    { action: "User registration", data: { registeredUsers: registeredUsers.map(u => u.id) } },
-    { db: tx }
-  );
-});
+    async findOne(where: VSRepoWhere<T>, options?: AdapterMethodOptions<T>) {
+        const start = this.logger.startPerformLog("adapter findOne");
+        try {
+            // ... talk to the ORM ...
+            this.logger.endPerformLog(start);
+            return result;
+        } catch (err) {
+            this.logger.endPerformLog(start);
+            this.logger.logError("adapter findOne failed", err);
+            throw err;
+        }
+    }
+}
 ```
 
----
-
-## Extending a repository
-
-```ts
-const userRepository = setupVSRepo<User, "user">()(({
-  tableName: "user",
-  pkName: "id",
-  methods: {
-    findOneByEmailEndsWith: { map: true },
-  },
-})
-  .build(prisma)
-  .extend((repo) => ({
-    findActiveByDomain: async (domain: string) => {
-      return repo.findOneByEmailEndsWith(`@${domain}`);
-    },
+| Method                             | Description                                                                                      |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `new VSLogger(logLevel, name, slowThresholdMs?)` | Creates a logger; `name` prefixes every line, `slowThresholdMs` defaults to 300.                    |
+| `logDebug/logInfo/logWarn(text, obj?)` | Logs at the given level if `logLevel` allows it; `obj` is appended as pretty-printed JSON.       |
+| `logError(text, err?)`              | Logs at `ERROR`; if `err` is an `Error`, only `name`/`message`/`stack`/`cause` are logged.        |
+| `startPerformLog(operation)` / `endPerformLog(data)` | Bracket a block to log its duration, escalating to `WARN` if it exceeds `slowThresholdMs`. |
+| `getLogLevel()`                     | Returns the logger's configured `VSLogLevel`.                                                     |
 
-    activateMultiple: async (ids: string[]) => {
-      return repo.patchList(ids.map(id => [id, { active: true }]));
-    },
-  }));
-```
+This is purely a convenience for adapter authors — nothing in the core requires your adapter to use it.
 
 ---
 
 ## Error handling
 
-VSRepository throws `VSRepoError` and its subclasses in specific situations (Prisma errors are not overridden):
+v2 simplifies the error hierarchy from v1: instead of several subclasses, there's a base `VSRepoError` class carrying a `type: VSRepoErrorType`, plus a dedicated `VSRepoAdapterError` subclass (see below) for failures coming from the underlying ORM/database.
 
-```ts
-import { VSRepoError, VSRepoRuntimeError } from "../../generated/vsrepo";
+```typescript
+import { VSRepoError } from "vsrepo";
 
 try {
-  const user = await userRepository.getOrThrow("id-that-does-not-exist");
+    await userRepository.get(id);
 } catch (error) {
-  if (error instanceof VSRepoRuntimeError && error.code === "20727") {
-    console.error("Record not found");
-  } else if (error instanceof VSRepoError) {
-    console.error("Repository error:", error.message);
-  } else {
-    console.error("Error:", error.message)
-  }
+    if (error instanceof VSRepoError) {
+        console.error(`[${error.type}] ${error.message}`);
+    }
 }
 ```
 
-**Available subclasses:**
-
-| Class                   | When it's thrown                                                         |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `VSRepoConfigError`     | Invalid configuration in `setupVSRepo`                                   |
-| `VSRepoBuildError`      | Invalid method name, field type, or configuration in `build`             |
-| `VSRepoExtendError`     | Invalid argument in `extend`                                             |
-| `VSRepoDecoratorError`  | Invalid argument passed to `@DynamicMethod` or `@QueryMethod`            |
-| `VSRepoRuntimeError`    | Runtime error during an operation                                        |
-
-`VSRepoRuntimeError` has a `code: VSRepoRuntimeErrorCode` property for programmatic identification, instead of having to parse the (human-readable, and possibly localized) message:
-
-| Code | Meaning |
-| ---- | ------- |
-| `"65706"` | A required argument is missing or has an invalid shape — e.g. a missing `pk`, a `pks`/`objs`/`tuples` that isn't an array, or an `options`/`obj` that isn't a valid object. |
-| `"20727"` | No record was found for the provided primary key (`getOrThrow` when fetching the base record). |
-| `"67542"` | Validation (zod) of a method's `options`, or of a `@QueryMethod` argument, failed. |
-| `"91868"` | A relation passed to `save`/`patch`/`merge` has an invalid shape for the configured `mode`/`restriction` (e.g. `null` on a `mtm`/`otm` relation, or an array on a `oto`/`mto` relation). |
-| `"48670"` | A dynamic method (`config.methods`) was called with fewer positional arguments than its `where` fields require. |
-
----
-
-## Utility types
-
-### Client types
-
-```ts
-import type { DbClient, DbTransaction, ClientOrTransaction } from "../../generated/vsrepo";
+| `VSRepoErrorType` | Raised when                                                                                                                |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `DECORATOR`       | Invalid arguments were passed to `@DynamicMethod` or `@QueryMethod`.                                                       |
+| `RESOLVER`        | The library failed to resolve a dynamic/query method's configuration into a callable method (e.g. an unknown method name). |
+| `DYNAMIC`         | A resolved dynamic method failed at runtime (e.g. missing arguments).                                                      |
+| `VALIDATOR`       | Invalid method options or arguments were detected during validation.                                                       |
+| `BASE`            | Invalid usage of a base method (`get`, `save`, `remove`, etc).                                                             |
+| `ADAPTER`         | A `VSRepoAdapter` failed while talking to the underlying ORM/database — always thrown as `VSRepoAdapterError`.             |
 
-type DbClient            = PrismaClient;
-type DbTransaction       = Prisma.TransactionClient;
-type ClientOrTransaction = DbClient | DbTransaction;
-```
-
-### Soft-delete visibility type
+### `VSRepoAdapterError` and `AdapterErrorCode`
 
-```ts
-import type { SeeMode } from "../../generated/vsrepo";
+When an adapter talks to the underlying ORM/database and that operation fails, the adapter wraps the failure in a `VSRepoAdapterError` — a subclass of `VSRepoError` with `type: VSRepoErrorType.ADAPTER`. It carries a **stable, adapter-agnostic** `code: AdapterErrorCode` plus the raw error thrown by the ORM/driver, so callers can react to failures without depending on any single ORM's error shape:
 
-type SeeMode = "active" | "removed" | "all";
-```
+```typescript
+import { VSRepoAdapterError, AdapterErrorCode } from "vsrepo";
 
-### Types derived from the Prisma model
+try {
+    await userRepository.save({ name: "Maria" });
+} catch (error) {
+    if (error instanceof VSRepoAdapterError) {
+        console.error(`[${error.code}] ${error.message}`, error.originalError);
 
-```ts
-import type {
-  SelectModel,
-  SelectModels,
-  IncludeModel,
-  IncludeModels,
-  WhereModel,
-  OrderingModel,
-  PaginationModel,
-  ModelUpsertInput,
-  PrismaModelInputs,
-} from "../../generated/vsrepo";
+        if (error.code === AdapterErrorCode.UNIQUE_CONSTRAINT_VIOLATION) {
+            // handle a duplicate key, e.g. return a friendly message
+        }
+    }
+}
 ```
 
-### Method options types
+| Property        | Type               | Description                                                                         |
+| --------------- | ------------------ | ----------------------------------------------------------------------------------- |
+| `code`          | `AdapterErrorCode` | Stable, adapter-agnostic code classifying the failure.                              |
+| `originalError` | `unknown`          | The raw error (or `null`/`undefined`) thrown by the underlying ORM/database driver. |
+| `message`       | `string`           | Human-readable description of the adapter failure.                                  |
+| `type`          | `VSRepoErrorType`  | Always `VSRepoErrorType.ADAPTER`.                                                   |
+| `cause`         | `unknown`          | Optional root cause the error was chained from.                                     |
 
-```ts
-import type { MethodOptions, MethodOptionsModel } from "../../generated/vsrepo";
+Adapter implementations construct it directly when mapping an ORM failure:
 
-// MethodOptions<S, IM> — options passed into the repository's methods
-type Opts = MethodOptions<"public" | "minimal", "withPosts">;
+```typescript
+import { VSRepoAdapterError, AdapterErrorCode } from "vsrepo";
 
-// MethodOptionsModel<TRepo> — derived from a configured VSRepository instance
-const userVSRepo = setupVSRepo<User, "user">()(config);
-type OptsModel = MethodOptionsModel<typeof userVSRepo>;
+throw new VSRepoAdapterError(
+    "user creation failed",
+    AdapterErrorCode.UNIQUE_CONSTRAINT_VIOLATION,
+    originalError, // raw DB/driver error
+);
 ```
 
-> The second parameter of `MethodOptions` (`IM`) represents the valid keys of `includeModels`. When provided, `selectModel` and `includeModel` become mutually exclusive in the type — it's not possible to pass both in the same call.
->
-> `MethodOptions` also accepts two further generic parameters, `RI` and `RS`, for typing raw `include` and raw `select` respectively (both default to `never`, meaning they're not accepted unless explicitly typed): `MethodOptions<"public", "withPosts", "user", IncludeModel<"user">, SelectModel<"user">>`. `MethodOptionsModel`, derived directly from a configured repository, does not expose `RI`/`RS` — use `MethodOptions` directly if you need to type raw `include`/`select` options.
-
-### Configuration types
+#### `AdapterErrorCode`
 
-```ts
-import type {
-  MethodConfig,
-  RepoConfig,
-  BuildConfig,
-  RepositoryRelations,
-  ExtractRelationConfig,
-} from "../../generated/vsrepo";
-```
-
-### Built repository type
+`AdapterErrorCode` is an enum of granular, adapter-agnostic codes an adapter can raise through `VSRepoAdapterError`. They mirror the most common failures thrown by ORMs and database drivers so any ORM's errors can be mapped to the same stable code:
 
-```ts
-import type { RepositoryOf } from "../../generated/vsrepo";
+```typescript
+import { AdapterErrorCode } from "vsrepo";
 
-const userVSRepo = setupVSRepo<User, "user">()({ ... });
-type UserRepository = RepositoryOf<typeof userVSRepo>;
+console.log(AdapterErrorCode.UNIQUE_CONSTRAINT_VIOLATION); // "UNIQUE_CONSTRAINT_VIOLATION"
 ```
 
-`RepositoryOf` accepts three parameters:
+| Code                          | Meaning                                                                                                        |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `UNKNOWN`                     | Unclassified/unknown error; the fallback when no more specific code matches.                                   |
+| `MISSING_DB_CLIENT`           | Database client (or connection pool) not provided or could not be resolved.                                    |
+| `CONNECTION_FAILED`           | Could not reach/connect to the database, or an established connection was lost/terminated.                     |
+| `CONNECTION_POOL_EXHAUSTED`   | Connection pool exhausted/depleted — no connection available, all busy or the limit was reached.               |
+| `TIMEOUT`                     | Database did not respond in time; a query exceeded its allowed timeout.                                        |
+| `UNIQUE_CONSTRAINT_VIOLATION` | Unique constraint (duplicate key) violated. E.g. Postgres/SQLite `23505`, MySQL `1062`.                        |
+| `FOREIGN_KEY_VIOLATION`       | Foreign key constraint violated (referenced row missing).                                                      |
+| `NOT_NULL_VIOLATION`          | NOT NULL constraint violated.                                                                                  |
+| `CHECK_VIOLATION`             | CHECK constraint violated.                                                                                     |
+| `CONSTRAINT_VIOLATION`        | General integrity/constraint violation not covered by a more specific code.                                    |
+| `NOT_FOUND`                   | Requested record not found (e.g. a `findOneOrThrow`-style operation).                                          |
+| `INVALID_DATA`                | Field value invalid for its type/length, or a required value is missing.                                       |
+| `VALUE_TOO_LONG`              | Provided value exceeds the column/field length limit.                                                          |
+| `CONVERSION_ERROR`            | Value could not be converted/cast to the target type. E.g. Postgres `22P02`, MySQL `1366`.                     |
+| `INVALID_QUERY`               | SQL query/stored procedure is malformed or invalid.                                                            |
+| `TABLE_OR_COLUMN_NOT_FOUND`   | Referenced table/column/relation does not exist.                                                               |
+| `DEADLOCK`                    | Operation aborted by a lock timeout or deadlock between concurrent transactions.                               |
+| `LOCK_TIMEOUT`                | Could not acquire a required database lock in time.                                                            |
+| `LOCKED`                      | Record is locked and cannot be modified.                                                                       |
+| `ACCESS_DENIED`               | Current user/role does not have permission for the operation.                                                  |
+| `INVALID_CREDENTIALS`         | Invalid connection credentials (host/user/password).                                                           |
+| `ROW_NOT_ALLOWED`             | Authenticated user does not own the record / row-level security rejected it.                                   |
+| `MODEL_NOT_FOUND`             | Entity/model or table not defined/mapped in the ORM, or the adapter lacks model metadata to build the query.   |
+| `FIELD_NOT_FOUND`             | Field/column name in the data or `where` does not exist on the entity/model.                                   |
+| `TRANSACTION_CLOSED`          | Transaction used after it was committed/rolled back.                                                           |
+| `TRANSACTION_ALREADY_STARTED` | A nested transaction could not be opened (e.g. nested `transaction()` calls).                                  |
+| `TRANSACTION_CONFLICT`        | Transaction failed to commit and was rolled back.                                                              |
+| `TRANSACTION_NOT_STARTED`     | No active transaction when one was required.                                                                   |
+| `CONNECTION_CLOSED`           | Connection closed/terminated while a transaction or query was in progress.                                     |
+| `INVALID_PARTIAL`             | `merge`/`upsert`/`update` received a partial object that is invalid or missing required keys.                  |
+| `NOT_SUPPORTED`               | Unsupported feature/operation requested from the adapter (e.g. raw `query()` not supported).                   |
+| `INVALID_ADAPTER_CONFIG`      | Adapter configuration invalid or incomplete (missing required options, or options with an invalid type/value). |
+| `INTERNAL`                    | Internal adapter bug or unrecoverable state; should rarely be used — prefer a more specific code.              |
 
-```ts
-type RepositoryOf<TRepo, C extends BuildConfig | undefined = undefined, E = unknown>
-```
+#### `VSRepoError` vs. raw ORM errors
 
-### `save` and `patch` payload types
+Non-adapter usage/config mistakes throw the base `VSRepoError`. Failures raised _by the underlying ORM_ while an adapter method runs are **wrapped** in `VSRepoAdapterError` (classified by an `AdapterErrorCode`, with the original error preserved in `originalError`) instead of propagating raw — this is what makes callers independent of any specific ORM's error shape.
 
-```ts
-import type { SaveObject, PatchObject } from "../../generated/vsrepo";
+---
 
-const userVSRepo = setupVSRepo<User, "user">()(({
-  tableName: "user",
-  pkName: "id",
-  relations: {
-    profile: { pk: "id", mode: "oto", restriction: "set" },
-  },
-});
+## Logging
 
-type UserSavePayload  = SaveObject<Prisma.UserCreateInput, typeof userVSRepo>;
-type UserPatchPayload = PatchObject<Prisma.UserUpdateInput, typeof userVSRepo>;
-```
+Every repository has an internal logger, configured via `logLevel` and `logSlowThresholdMs` on the constructor options:
 
----
+```typescript
+import { VSLogLevel } from "vsrepo";
 
-## API Reference
-
-### `setupVSRepo<T, M>()(config)`
-
-```ts
-setupVSRepo<TPayload, TTableName>()({
-  tableName: Uncapitalize<M>;                     // Table name in Prisma
-  pkName: keyof T;                                // Primary key name
-  softRemovekName?: keyof T & string;             // DateTime field for soft-delete
-  selectModels?: SelectModels<M>;                 // Named data projections (select)
-  defaultSelectModel?: keyof SM;                  // Select applied by default
-  includeModels?: IncludeModels<M>;               // Named data projections (include) — no default, only in the call
-  requiredWhere?: WhereModel<M>;                  // Always-applied filters
-  defaultOrdering?: OrderingModel<M>;             // Default ordering for queries without Ordered/injectOrdering
-  relations?: RepositoryRelations<T>;             // Relation configuration
-  methods?: Record<string, MethodConfig<M, SM>>;  // Dynamic methods
+super({
+    pkName: "id",
+    adapter,
+    logLevel: VSLogLevel.DEBUG,
+    logSlowThresholdMs: 200,
 });
 ```
 
-### `.build(prisma, config?)`
-
-```ts
-vsRepo.build(prisma, {
-  showWorking?: boolean;   // Shows internal logs on the console (default = false)
-
-  baseMethods?: {
-    // Methods that can use a defaultSelect
-    get?:             { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    getOrThrow?:      { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    getList?:         { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    remove?:          { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    save?:            { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    saveList?:        { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    patch?:           { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    patchList?:       { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    merge?:           { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    getAll?:          { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    softRemove?:      { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-    restore?:         { active?: boolean; defaultSelect?: string; ignoreRequiredWhere?: boolean };
-
-    // Methods that do NOT accept defaultSelect
-    removeList?:      { active?: boolean; ignoreRequiredWhere?: boolean };
-    softRemoveList?:  { active?: boolean; ignoreRequiredWhere?: boolean };
-    restoreList?:     { active?: boolean; ignoreRequiredWhere?: boolean };
-    total?:           { active?: boolean; ignoreRequiredWhere?: boolean };
-    has?:             { active?: boolean; ignoreRequiredWhere?: boolean };
-  };
-});
-```
+| Level            | Meaning                                                                                               |
+| ---------------- | ----------------------------------------------------------------------------------------------------- |
+| `DEBUG`          | Verbose internal details, including every resolved query — very useful for debugging dynamic methods. |
+| `INFO`           | High-level lifecycle events, such as repository initialization.                                       |
+| `WARN` (default) | Recoverable issues and slow operations (see `logSlowThresholdMs`, defaults to 300ms).                 |
+| `ERROR`          | Failures raised while executing an operation.                                                         |
 
-### `.extend(fn)`
+---
 
-```ts
-repo.extend((repo) => ({
-  myMethod: () => { ... }
-}));
-```
+## Development
 
----
+The v2 core is built and packed from this branch as a standard npm package:
 
-## Practical examples
-
-Besides this README, the repository has an **[`examples/`](https://github.com/jaobrabo123/VSRepository/tree/main/examples)** folder with practical, commented, ready-to-run examples — it's the best place to see VSRepository being used in real scenarios.
-
-```text
-examples/
-├── prisma.ts             # PrismaClient instance used by the examples
-├── repositories.ts       # Repository configuration (User, Address, Product) with setupVSRepo
-└── tests/
-    ├── base-methods.test.ts       # Base methods: get, save, patch, remove, getAll, total, has...
-    ├── relations.test.ts          # How to configure and use relations in save/patch and in filters
-    ├── required-where.test.ts     # How requiredWhere is automatically applied to queries
-    ├── dynamic-methods.test.ts    # Prefixes, field filters, logical operators, and pagination/ordering
-    ├── transactions.test.ts       # Transactions with options.db and instance access via repository.prisma
-    ├── soft-delete.test.ts        # Soft-delete: softRemove, softRemoveList, restore, restoreList and SeeMode
-    └── batch-methods.test.ts      # Batch operations: getList, saveList, patchList and merge
-```
+```bash
+# 1. Install dependencies
+pnpm install
 
-Each file in `tests/` is an independent, runnable script (via `tsx`) that demonstrates a specific set of features, with `console.log` at each step so you can follow the result in the terminal. The folder itself has a [README](https://github.com/jaobrabo123/VSRepository/blob/main/examples/README.md) explaining the suggested reading order, how to set up the environment, and how to run the tests.
+# 2. Compile the TypeScript sources into dist/ (removes a previous dist/ first)
+pnpm build
 
----
+# 3. (Optional) Inspect what would be published without writing a tarball
+npm pack --dry-run
 
-## Contributing
+# 4. Produce the installable tarball (runs `prepack` -> `pnpm build` automatically)
+npm pack
 
-Contributions are welcome! If you found a bug, have an improvement idea, or want to help with the documentation, feel free to get involved (**[GitHub Repository](https://github.com/jaobrabo123/VSRepository)**):
+# 5. Consume it locally in another project
+npm install ../path/to/vsrepo-1.4.0.tgz
+```
 
-1. **Fork** the project.
-2. Create a new branch with your change: `git checkout -b fixing-bug`.
-3. Push to your branch: `git push origin fixing-bug`.
-4. Open a **Pull Request**.
+Notes:
 
-To report issues or suggest new features, open an **Issue**.
+- `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 core is ORM-agnostic and has no `@prisma/client` peer dependency.
 
 ---
 
 ## Requirements
 
-- Node.js 18+ (ESM)
-- Prisma
-- TypeScript (optional, but strongly recommended)
-- `"moduleResolution": "bundler"` or `"nodenext"` in tsconfig
-
-Recommended `tsconfig.json`:
+- Node.js 18+
+- TypeScript, with **legacy/experimental decorators** enabled (required by `@DynamicMethod`/`@QueryMethod`):
 
 ```json
 {
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "skipLibCheck": true,
-    "lib": ["ES2020"]
-  }
+    "compilerOptions": {
+        "experimentalDecorators": true
+    }
 }
 ```
 
----
-
-## Troubleshooting
-
-**Generic types not inferred** — Check that `strict: true` and `moduleResolution: "bundler"` or `"nodenext"` are set in `tsconfig.json`.
-
-**Dynamic method doesn't exist at runtime** — The field referenced in the method name must exist in the Prisma model. E.g.: `findByEmail` requires the model to have an `email` field.
-
-**`proxyTo` required** — Names outside the standard patterns (e.g. `searchByEmail`) aren't parsed directly. Use `proxyTo: "findByEmail"` in these cases.
+- `reflect-metadata` (bundled as a dependency, imported internally — you don't need to import it yourself)
+- At least one working `VSRepoAdapter` for your database — on Prisma 7, install the published [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) (see [Adapter status](#adapter-status)); official adapters for other ORMs are planned but not published yet, so for now this means writing your own (see [Writing your own adapter](#writing-your-own-adapter)) — and if you publish it, contributing it back to the project is welcome
 
-**Select model returns unexpected fields** — Check that the select model defines exactly the fields your TypeScript type expects.
-
-**`selectModel`, `includeModel` and `include` together in the same call** — Not allowed. Only one of the three can be provided per call: if `includeModel` or `include` is provided, the `select` (including `defaultSelectModel`) is ignored and only the `include` is sent to Prisma.
-
-**`includeModel` doesn't appear as a default repository option** — This is expected. Unlike `defaultSelectModel`, there's no `defaultIncludeModel`/`defaultInclude`. An `includeModel` can only be set in the method call, via `options.includeModel`. A raw, ad hoc include can be set via `options.include`, without needing to be registered in `includeModels`.
+---
 
-**`softRemovekName` throws an error at build** — The provided field must be of type `DateTime` in the Prisma schema. Types like `Boolean` or `String` are not accepted.
+## Contributing
 
-**`defaultOrdering` isn't being applied** — Check whether the method uses the `Ordered`, `OrderedAndPaginated`, or `PaginatedAndOrdered` suffix, and whether it has `injectOrdering` configured. Both take priority over the default ordering.
+Contributions are welcome, especially towards finishing the Prisma and TypeORM adapters! (**[GitHub repository](https://github.com/jaobrabo123/VSRepository)**):
 
-**`Distinct` suffix not recognized** — `Distinct` is only resolved on read prefixes (`findMany`, `findFirst`, `findBy`, `existsBy`, etc). In methods like `count`, `createMany`, `updateMany`, or `deleteMany` the suffix is ignored.
+1. **Fork** the project.
+2. Create a branch off `v2` for your change: `git checkout -b v2-my-change`.
+3. Push your branch: `git push origin v2-my-change`.
+4. Open a **Pull Request** against `v2`.
 
-**`saveList`/`patchList` with invalid `db`** — The `db` field in these methods only accepts a `DbTransaction` (the return of `prisma.$transaction`), not the main client. Passing the `PrismaClient` directly will cause unexpected behavior.
+To report issues or suggest features, open an **Issue**.