vsrepo 1.3.6 → 1.3.8

package/README-DynamicRepo.md

@@ -0,0 +1,625 @@
+# DynamicRepository (Class-based approach)
+
+🇺🇸 You're reading the English version. [🇧🇷 Ler em português](./README-DynamicRepo.pt-BR.md)
+
+VSRepository offers two ways to create repositories: the functional `setupVSRepo` approach and the OOP `DynamicRepository` class-based approach. This document covers the class-based approach using `DynamicRepository` and the `@DynamicMethod` decorator.
+
+> For the functional approach, see the main [README.md](./README.md).
+
+## Table of contents
+
+- [When to use DynamicRepository](#when-to-use-dynamicrepository)
+- [Requirements](#requirements)
+- [Creating a class](#creating-a-class)
+- [The @DynamicMethod decorator](#the-dynamicmethod-decorator)
+- [Decorator config options](#decorator-config-options)
+- [The @QueryMethod decorator](#the-querymethod-decorator)
+- [Base methods](#base-methods)
+- [Working with relations](#working-with-relations)
+- [Transactions](#transactions)
+- [Working with includes](#working-with-includes)
+- [DynamicMethodOptions](#dynamicmethodoptions)
+- [NestJS integration](#nestjs-integration)
+- [API Reference](#api-reference)
+- [Differences from setupVSRepo](#differences-from-setupvsrepo)
+
+---
+
+## When to use DynamicRepository
+
+Use `DynamicRepository` when you prefer an **OOP style with decorators** over the functional `setupVSRepo` approach. Key characteristics:
+
+- Methods are defined as `declare` fields with `@DynamicMethod()` decorators
+- The repository is a class you can extend and inject via dependency injection
+- `selectModels` and `includeModels` are **not supported** (use raw `select`/`include` via `DynamicMethodOptions` instead)
+- Base methods are always active (no `active` toggle per method)
+- The repository is built automatically in the constructor (no explicit `.build()` call)
+
+---
+
+## Requirements
+
+`DynamicRepository` relies on TypeScript's legacy decorators, so your project's `tsconfig.json` must have:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
+}
+```
+
+`reflect-metadata` is already a dependency of `vsrepo` and is imported internally — you don't need to import it yourself.
+
+Without `experimentalDecorators: true`, `@DynamicMethod()` will fail to compile (or silently fail to register the method at runtime, depending on your build tool).
+
+---
+
+## Creating a class
+
+Extend `DynamicRepository` with four generic parameters:
+
+```typescript
+import {
+    DynamicRepository,
+    DynamicMethod,
+    DynamicMethodOptions,
+    PaginationModel,
+} from "../../generated/vsrepo";
+import type { Prisma } from "../../generated/prisma/client";
+import { PrismaClient } from "../../generated/prisma/client";
+
+type User = Prisma.UserGetPayload<{
+    include: { address: true; posts: true };
+}>;
+
+class UserRepository extends DynamicRepository<
+    User,        // Entity type (with relations included)
+    "User",      // Prisma model name
+    string,      // Primary key type
+    { address: true; posts: true }  // Which fields are relations (flags)
+> {
+    constructor(prisma: PrismaClient) {
+        super(prisma, {
+            tableName: "user",
+            pkName: "id",
+            relations: {
+                address: { mode: "oto", pk: "id", restriction: "set" },
+                posts: { mode: "otm", pk: "id", restriction: "add" },
+            },
+            requiredWhere: { active: true },
+            build: {
+                showWorking: false,
+                baseMethods: {
+                    save: { ignoreRequiredWhere: true },
+                },
+            },
+        });
+    }
+}
+```
+
+**Generic parameters:**
+
+| Parameter                 | Description                                                                                                                                                           |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TEntity`                 | The full entity type, including any relations you want available                                                                                                      |
+| `UName`                   | The Prisma model name as a string literal (capitalized, e.g. `"User"`)                                                                                                |
+| `VPKType`                 | The type of the primary key (`string`, `number`, etc.)                                                                                                                |
+| `WRelations` *(optional)* | An object flags indicating which fields are relations (e.g. `{ address: true }`). Only needed if you plan to configure the repository's relations — omit it otherwise |
+
+---
+
+## The @DynamicMethod decorator
+
+Declare dynamic methods as class fields using `declare` and decorate them with `@DynamicMethod()`:
+
+```typescript
+class UserRepository extends DynamicRepository<User, "User", string> {
+    // Simple dynamic method - name determines behavior
+    @DynamicMethod()
+    declare findByEmail: (email: string) => Promise<User | null>;
+
+    // With decorator config
+    @DynamicMethod<"User">({ proxyTo: "findMany", pushWhere: { active: false } })
+    declare findDisabled: () => Promise<User[]>;
+
+    // Proxy to another method
+    @DynamicMethod<"User">({ proxyTo: "findOneByEmail", whereType: "overwrite" })
+    declare findInternalByEmail: (email: string) => Promise<User | null>;
+}
+```
+
+The method **name** determines the behavior (same rules as the functional approach). The decorator config object adjusts that behavior.
+
+> **Important:** Always use `declare` (not a regular property) for decorated fields. The decorator provides runtime metadata; the `declare` keyword tells TypeScript the property exists without emitting initialization code.
+
+---
+
+## Decorator config options
+
+The `@DynamicMethod<M>()` decorator accepts an optional config object:
+
+```typescript
+@DynamicMethod<"User">({
+    proxyTo: "findByEmail",                   // Delegate to another method pattern
+    whereType: "overwrite",                   // "extending" (default) or "overwrite"
+    pushWhere: { active: false },             // Extra where clause
+    injectOrdering: [{ name: "asc" }],        // Fixed ordering
+    injectPagination: { skip: 0, take: 10 },  // Fixed pagination
+})
+```
+
+| Option             | Type                         | Description                                                                                                       |
+| ------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `proxyTo`          | `string`                     | Delegates to another valid method pattern (e.g. `"findOneByEmail"`)                                               |
+| `whereType`        | `"extending" \| "overwrite"` | `extending` combines with `requiredWhere`; `overwrite` ignores it                                                 |
+| `pushWhere`        | `WhereModel<M>`              | Extra `where` clause added on top of `requiredWhere`                                                              |
+| `injectOrdering`   | `OrderingModel<M>`           | Fixed ordering injected into the query                                                                            |
+| `injectPagination` | `PaginationModel<M>`         | Fixed pagination injected into the query                                                                          |
+| `fbMode`           | `"one" \| "list"`            | **Deprecated.** Only relevant for `findBy`-prefixed methods. Use `findOneBy` instead if you want a single result. |
+
+---
+
+## The @QueryMethod decorator
+
+`@QueryMethod` declares a **raw SQL query method** on a `declare` class field, completely bypassing the name-based method parser used by `@DynamicMethod`. It's useful for complex queries (heavy joins, CTEs, database-specific functions) that aren't practical to express through the standard prefixes/suffixes.
+
+Under the hood, the SQL is executed through Prisma using `$queryRawUnsafe` (reads) or `$executeRawUnsafe` (writes), and the values passed in `args` are injected as **positional parameters** (`$1`, `$2`, ...) — the same prepared-statement technique Prisma itself uses. Values are never concatenated into the SQL string, which is what actually prevents SQL injection.
+
+```typescript
+class UserRepository extends DynamicRepository<User, "User", string> {
+    // Read query method (non-modifying) — return type comes from the field declaration
+    @QueryMethod('SELECT * FROM "user" WHERE email = $1')
+    declare findByEmailRaw: (arg: QueryMethodArg<[email: string]>) => Promise<User[]>;
+
+    // Write query method — must always resolve to 'number'
+    @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
+    declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+}
+
+const userRepository = new UserRepository(prisma, { tableName: "user", pkName: "id" });
+
+const users = await userRepository.findByEmailRaw({ args: ["joao@email.com"] });
+const affected = await userRepository.activateUser({ args: ["1"] });
+```
+
+> [!WARNING]
+> `$1`, `$2`, ... must always represent **values**, never column/table names or dynamic SQL fragments. Identifier names can't be passed as a positional parameter — if a method needs to vary those, build the SQL from a fixed, known set of options in your own code, never from untrusted input.
+
+Since `@QueryMethod` skips name parsing, there's no automatic type inference for the field: the method's parameter and return types come entirely from how you `declare` the field. Use `QueryMethodArg<T>` to type the single `{ args, db? }` argument the method receives.
+
+| Option                 | Type      | Default | Description                                                                                                                                  |
+| ---------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value` (1st argument) | `string`  | —       | **Required.** Raw SQL to execute. Use `$1`, `$2`, ... for the `args` placeholders.                                                           |
+| `options.modifying`    | `boolean` | `false` | When `true`, runs via `$executeRawUnsafe`; the field must be declared to return `Promise<number>`. When `false`, runs via `$queryRawUnsafe`. |
+
+> [!NOTE]
+> `@QueryMethod` ignores every other dynamic-method concept — `requiredWhere`, `pushWhere`, `whereType`, `selectModels`/`includeModels`, `injectOrdering`, `injectPagination`. None of it applies here.
+
+---
+
+## Base methods
+
+All `DynamicRepository` instances automatically include these methods:
+
+| Method                | Description                                                                                              |
+| --------------------- | -------------------------------------------------------------------------------------------------------- |
+| `get(pk)`             | Fetch a record by primary key                                                                            |
+| `getOrThrow(pk)`      | Fetch by PK, throws if not found                                                                         |
+| `getList(pks)`        | Fetch multiple records by PKs                                                                            |
+| `save(obj)`           | Create or upsert a record                                                                                |
+| `saveList(objs)`      | Batch save in an automatic transaction                                                                   |
+| `patch(pk, obj)`      | Partial update by PK                                                                                     |
+| `patchList(tuples)`   | Batch partial update via `[pk, obj]` tuples                                                              |
+| `merge(pk, obj)`      | Fetch and deep-merge in memory (does not persist)                                                        |
+| `remove(pk)`          | Delete a record by PK                                                                                    |
+| `removeList(pks)`     | Batch delete by PKs                                                                                      |
+| `getAll()`            | Fetch all records (respects `requiredWhere`). Accepts `pagination` and `order` in `options` — see below  |
+| `total()`             | Count all records                                                                                        |
+| `has(pk)`             | Check if a record exists                                                                                 |
+| `softRemove(pk)`      | Soft-delete (requires `softRemovekName` config)                                                          |
+| `softRemoveList(pks)` | Batch soft-delete                                                                                        |
+| `restore(pk)`         | Restore soft-deleted record                                                                              |
+| `restoreList(pks)`    | Batch restore                                                                                            |
+
+All methods accept an optional `options` argument based on `DynamicMethodOptions` (`db`, `see`, `include`, `select`), but a few methods narrow it further:
+
+- **`getAll`** additionally accepts `pagination?: PaginationOptions` and `order?: OrderingModel<UName>` (falls back to `defaultOrdering` when omitted).
+- **`saveList` / `patchList`** omit `include` and `select`, and `db` only accepts a `DbTransaction` (the return of `prisma.$transaction`) — not the plain Prisma client.
+- **`removeList`, `total`, `has`** omit `include` and `select`.
+- **`softRemove`, `restore`** omit `see` (soft-delete visibility doesn't apply to the record being changed).
+- **`softRemoveList`, `restoreList`** omit `see`, `include`, and `select`.
+
+```typescript
+// getAll with pagination and ordering
+const page = await userRepository.getAll({
+    pagination: { skip: 0, take: 20 },
+    order: { createdAt: "desc" },
+});
+```
+
+---
+
+## Working with relations
+
+Configure relations in the constructor so `save` and `patch` manage them automatically:
+
+```typescript
+class UserRepository extends DynamicRepository<
+    User, "User", string,
+    { address: true; posts: true }
+> {
+    constructor(prisma: PrismaClient) {
+        super(prisma, {
+            tableName: "user",
+            pkName: "id",
+            relations: {
+                address: { mode: "oto", pk: "id", restriction: "set" },
+                posts: { mode: "otm", pk: "id", restriction: "add" },
+            },
+        });
+    }
+}
+```
+
+The fourth generic parameter (`WRelations`) is **optional** — it's only needed when you're configuring relations for the repository. When provided, it must flag which fields are relations. This ensures `DynamicSaveInput` and `DynamicPatchInput` resolve those fields into their nested Prisma create/update payload shapes. If your repository doesn't manage any relations, you can simply omit this parameter.
+
+**Relation modes:** `oto` (one-to-one), `otm` (one-to-many), `mto` (many-to-one), `mtm` (many-to-many).
+
+**Restrictions:** `set` (replace all) or `add` (add/update without removing).
+
+See the main [README.md](./README.md#relations-in-save) for full details on relation behavior.
+
+---
+
+## Transactions
+
+All methods accept `{ db: tx }` to participate in a transaction:
+
+```typescript
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.save(
+        { name: "Mary", email: "mary@email.com", password: "password" },
+        { db: tx }
+    );
+
+    await postRepository.save(
+        { title: "First Post", authorId: user.id },
+        { db: tx }
+    );
+});
+```
+
+Access the Prisma client via `repository.prisma`.
+
+---
+
+## Working with includes
+
+`DynamicRepository` does not support `includeModels` (named presets), but you can use raw Prisma `include` via `DynamicMethodOptions`:
+
+```typescript
+// Include address only
+const user = await userRepository.get(id, {
+    include: { address: true },
+});
+
+// Nested include
+const userFull = await userRepository.get(id, {
+    include: {
+        address: true,
+        posts: { include: { tags: true } },
+    },
+});
+
+// Works on any method that accepts options
+const all = await userRepository.getAll({
+    include: { posts: true },
+});
+```
+
+---
+
+## DynamicMethodOptions
+
+Every base method and every decorated dynamic method accepts an optional second argument of type `DynamicMethodOptions`. This object has four optional fields:
+
+```typescript
+type DynamicMethodOptions<TName extends PrismaModelName> = {
+    db?: ClientOrTransaction;          // Prisma client or transaction
+    see?: "active" | "removed" | "all"; // Soft-delete visibility
+    include?: IncludeModel<TName>;      // Raw Prisma include
+    select?: SelectModel<TName>;        // Raw Prisma select
+};
+```
+
+> `include` and `select` are mutually exclusive. Unlike the functional `setupVSRepo` API, `DynamicRepository`'s simpler options type doesn't enforce this at compile time — passing both raises a `VSRepoRuntimeError` at runtime.
+
+### `db` — Using a transaction
+
+Pass `{ db: tx }` to route a single method call inside an existing transaction:
+
+```typescript
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.save(
+        { name: "Mary", email: "mary@email.com", password: "password" },
+        { db: tx },
+    );
+
+    await postRepository.save(
+        { title: "First Post", authorId: user.id },
+        { db: tx },
+    );
+});
+```
+
+You can also use the transaction for reads:
+
+```typescript
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.get(id, { db: tx });
+    const total = await userRepository.total({ db: tx });
+});
+```
+
+### `see` — Soft-delete visibility
+
+If `softRemovekName` is configured, the `see` field controls which records are visible:
+
+| Value                | Behavior                        |
+| -------------------- | ------------------------------- |
+| `"active"` (default) | Only non-deleted records        |
+| `"removed"`          | Only soft-deleted records       |
+| `"all"`              | Both active and deleted records |
+
+```typescript
+// Fetch only soft-deleted users
+const deleted = await userRepository.getAll({ see: "removed" });
+
+// Fetch all users including soft-deleted
+const all = await userRepository.getAll({ see: "all" });
+
+// Restore a soft-deleted user by fetching it first
+const [removed] = await userRepository.getAll({ see: "removed", include: { address: true } });
+```
+
+### `include` — Raw Prisma include
+
+Use `include` to eagerly load relations in any method call. This is the equivalent of `includeModels` in the functional approach, but with raw Prisma include syntax:
+
+```typescript
+// Simple include
+const user = await userRepository.get(id, {
+    include: { address: true },
+});
+
+// Nested include
+const userFull = await userRepository.get(id, {
+    include: {
+        address: true,
+        posts: { include: { author: true } },
+    },
+});
+
+// Works on dynamic methods too
+const admin = await userRepository.findAdminByEmail(email, {
+    include: { address: true, posts: true },
+});
+```
+
+### `select` — Raw Prisma select
+
+Use `select` to project a specific set of fields in any method call. This is the equivalent of `selectModels` in the functional approach, but with raw Prisma select syntax:
+
+```typescript
+// Simple select
+const user = await userRepository.get(id, {
+    select: { id: true, email: true },
+});
+
+// Works on dynamic methods too
+const admin = await userRepository.findAdminByEmail(email, {
+    select: { id: true, email: true },
+});
+```
+
+> Because `DynamicRepository` has no `selectModels`/`selectedModel`-driven type narrowing, the return type stays `TEntity` regardless of the `select` passed — the runtime result will only contain the selected fields, but TypeScript won't narrow it for you. Cast or destructure as needed.
+
+### Combining options
+
+`db` and `see` can be freely combined with either `include` or `select` (but not both `include` and `select` together):
+
+```typescript
+// Inside a transaction, fetch a user with relations, including soft-deleted
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.get(id, {
+        db: tx,
+        see: "all",
+        include: { address: true, posts: true },
+    });
+});
+```
+
+---
+
+## NestJS integration
+
+`DynamicRepository` works naturally with NestJS dependency injection.
+
+### Repository provider
+
+```typescript
+// src/modules/user/user.repository.ts
+import { Injectable } from "@nestjs/common";
+import { PrismaService } from "../../database/prisma.service";
+import { DynamicRepository, DynamicMethod, DynamicMethodOptions } from "../../../generated/vsrepo";
+
+type User = /* Prisma UserGetPayload with relations */;
+
+@Injectable()
+class UserRepository extends DynamicRepository<User, "User", string, { profile: true }> {
+    constructor(prisma: PrismaService) {
+        super(prisma, {
+            tableName: "user",
+            pkName: "id",
+            relations: {
+                profile: { mode: "oto", pk: "id", restriction: "add" },
+            },
+            build: {
+                baseMethods: {
+                    save: { ignoreRequiredWhere: true },
+                },
+            },
+        });
+    }
+
+    @DynamicMethod()
+    declare findByEmail: (email: string, options?: DynamicMethodOptions<"User">) => Promise<User | null>;
+}
+
+```
+
+### Registering the module
+
+```typescript
+// src/modules/user/user.module.ts
+import { Module } from "@nestjs/common";
+import { UserRepository } from "./user.repository";
+import { UserService } from "./user.service";
+import { UserController } from "./user.controller";
+
+@Module({
+    providers: [UserRepository, UserService],
+    controllers: [UserController],
+    exports: [UserService],
+})
+export class UserModule {}
+```
+
+### Using in a service
+
+```typescript
+// src/modules/user/user.service.ts
+import { Injectable, Inject } from "@nestjs/common";
+import { UserRepository } from "./user.repository";
+
+@Injectable()
+export class UserService {
+    constructor(
+        private readonly userRepository: UserRepository,
+    ) {}
+
+    async getUserById(id: string) {
+        return this.userRepository.get(id);
+    }
+
+    async getUserAuthByEmailWithProfile(email: string) {
+        return this.userRepository.findByEmail(email, { include: { profile: true } });
+    }
+
+    async createUser(data: { email: string; password: string; name: string }) {
+        return this.userRepository.save({
+            email: data.email,
+            password: data.password,
+            name: data.name,
+        });
+    }
+}
+```
+
+---
+
+## API Reference
+
+### `DynamicRepository<TEntity, UName, VPKType, WRelations>`
+
+```typescript
+abstract class DynamicRepository<
+    TEntity extends object,
+    UName extends PrismaModelName,
+    VPKType,
+    WRelations extends Partial<Record<keyof TEntity, true>> | undefined = undefined,
+>
+```
+
+> `WRelations` is optional (defaults to `undefined`) and only needs to be provided when you're configuring the repository's relations.
+
+**Constructor:**
+
+```typescript
+constructor(prisma: DbClient, config: DynamicRepositoryConstructorConfig<TEntity, UName>)
+```
+
+### DynamicRepositoryConstructorConfig
+
+| Property             | Type                           | Description                    |
+| -------------------- | ------------------------------ | ------------------------------ |
+| `tableName`          | `Uncapitalize<UName>`          | Table name in Prisma           |
+| `pkName`             | `keyof TEntity`                | Primary key field              |
+| `softRemovekName?`   | `keyof TEntity`                | DateTime field for soft-delete |
+| `requiredWhere?`     | `WhereModel<UName>`            | Global filters                 |
+| `defaultOrdering?`   | `OrderingModel<UName>`         | Default ordering               |
+| `relations?`         | `RepositoryRelations<TEntity>` | Relation configuration         |
+| `build?`             | `DynamicRepositoryBuildConfig` | Build-time options             |
+
+### DynamicRepositoryBuildConfig
+
+| Property       | Type                                                | Description                           |
+| -------------- | --------------------------------------------------- | ------------------------------------- |
+| `showWorking?` | `boolean`                                           | Show internal logs (default: `false`) |
+| `baseMethods?` | `Record<string, { ignoreRequiredWhere?: boolean }>` | Per-method config                     |
+
+### @DynamicMethod\<M>(config?)
+
+```typescript
+function DynamicMethod<M extends PrismaModelName>(
+    config?: DynamicMethodConfig<M>,
+): PropertyDecorator;
+```
+
+### DynamicMethodOptions\<TName>
+
+| Property   | Type                             | Description                    |
+| ---------- | -------------------------------- | ------------------------------ |
+| `db?`      | `ClientOrTransaction`            | Database client or transaction |
+| `see?`     | `"active" \| "removed" \| "all"` | Soft-delete visibility         |
+| `include?` | `IncludeModel<TName>`            | Raw Prisma include             |
+| `select?`  | `SelectModel<TName>`             | Raw Prisma select              |
+
+### @QueryMethod(value, options?)
+
+```typescript
+function QueryMethod(value: string, options?: QueryMethodOptions): PropertyDecorator;
+```
+
+### QueryMethodArg\<T>
+
+| Property | Type                  | Description                                                                |
+| -------- | --------------------- | -------------------------------------------------------------------------- |
+| `args`   | `T` (tuple)           | Positional parameters injected into the SQL placeholders (`$1`, `$2`, ...) |
+| `db?`    | `ClientOrTransaction` | Transaction client to run this query in                                    |
+
+### QueryMethodOptions
+
+| Property     | Type      | Default | Description                                                                                                           |
+| ----------   | --------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `modifying?` | `boolean` | `false` | `true` executes via `$executeRawUnsafe` (field must return `Promise<number>`); `false` executes via `$queryRawUnsafe` |
+
+---
+
+## Differences from setupVSRepo
+
+| Aspect                  | `setupVSRepo`                          | `DynamicRepository`                                   |
+| ----------------------- | -------------------------------------- | ----------------------------------------------------- |
+| **Style**               | Functional / curried                   | OOP / class-based                                     |
+| **Methods defined via** | `methods` config object                | `@DynamicMethod()` decorators                         |
+| **selectModels**        | Supported                              | Not supported                                         |
+| **includeModels**       | Supported                              | Not supported                                         |
+| **Default select**      | `defaultSelectModel` config            | Not available                                         |
+| **Build step**          | Explicit `.build(prisma)`              | Automatic in constructor                              |
+| **Base method toggles** | `active`, `defaultSelect` per method   | Always active, no defaultSelect                       |
+| **Prisma instance**     | Passed at `.build()` time              | Passed to `super()` in constructor                    |
+| **Extensibility**       | `.extend()` method                     | Class inheritance                                     |
+| **Raw includes**        | Via `options.include`                  | Via `DynamicMethodOptions.include`                    |
+| **Raw selects**         | Via `options.select` (type-narrowed)   | Via `DynamicMethodOptions.select` (not type-narrowed) |

package/README-DynamicRepo.pt-BR.md

@@ -0,0 +1,625 @@
+# DynamicRepository (Abordagem baseada em classes)
+
+🇧🇷 Você está lendo a versão em português. [🇺🇸 Read in English](./README-DynamicRepo.md)
+
+O VSRepository oferece duas formas de criar repositórios: a abordagem funcional `setupVSRepo` e a abordagem OOP baseada em classes `DynamicRepository`. Este documento cobre a abordagem baseada em classes usando `DynamicRepository` e o decorator `@DynamicMethod`.
+
+> Para a abordagem funcional, veja o [README.pt-BR.md](./README.pt-BR.md) principal.
+
+## Sumário
+
+- [Quando usar o DynamicRepository](#quando-usar-o-dynamicrepository)
+- [Requisitos](#requisitos)
+- [Criando uma classe](#criando-uma-classe)
+- [O decorator @DynamicMethod](#o-decorator-dynamicmethod)
+- [Opções de configuração do decorator](#opções-de-configuração-do-decorator)
+- [O decorator @QueryMethod](#o-decorator-querymethod)
+- [Métodos base](#métodos-base)
+- [Trabalhando com relações](#trabalhando-com-relações)
+- [Transações](#transações)
+- [Trabalhando com includes](#trabalhando-com-includes)
+- [DynamicMethodOptions](#dynamicmethodoptions)
+- [Integração com NestJS](#integração-com-nestjs)
+- [Referência da API](#referência-da-api)
+- [Diferenças em relação ao setupVSRepo](#diferenças-em-relação-ao-setupvsrepo)
+
+---
+
+## Quando usar o DynamicRepository
+
+Use `DynamicRepository` quando preferir um **estilo OOP com decorators** em vez da abordagem funcional `setupVSRepo`. Características principais:
+
+- Métodos são definidos como campos `declare` com decorators `@DynamicMethod()`
+- O repositório é uma classe que você pode estender e injetar via injeção de dependência
+- `selectModels` e `includeModels` **não são suportados** (use `select`/`include` brutos via `DynamicMethodOptions`)
+- Os métodos base estão sempre ativos (sem toggle `active` por método)
+- O repositório é construído automaticamente no construtor (sem chamada explícita a `.build()`)
+
+---
+
+## Requisitos
+
+`DynamicRepository` depende dos decorators legados do TypeScript, então o `tsconfig.json` do seu projeto precisa ter:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
+}
+```
+
+`reflect-metadata` já é uma dependência do `vsrepo` e é importado internamente — você não precisa importá-lo manualmente.
+
+Sem `experimentalDecorators: true`, o `@DynamicMethod()` não vai compilar (ou vai falhar silenciosamente ao registrar o método em tempo de execução, dependendo da sua ferramenta de build).
+
+---
+
+## Criando uma classe
+
+Estenda `DynamicRepository` com quatro parâmetros genéricos:
+
+```typescript
+import {
+    DynamicRepository,
+    DynamicMethod,
+    DynamicMethodOptions,
+    PaginationModel,
+} from "../../generated/vsrepo";
+import type { Prisma } from "../../generated/prisma/client";
+import { PrismaClient } from "../../generated/prisma/client";
+
+type User = Prisma.UserGetPayload<{
+    include: { address: true; posts: true };
+}>;
+
+class UserRepository extends DynamicRepository<
+    User,        // Tipo da entidade (com relações incluídas)
+    "User",      // Nome do modelo no Prisma
+    string,      // Tipo da chave primária
+    { address: true; posts: true }  // Quais campos são relações (flags)
+> {
+    constructor(prisma: PrismaClient) {
+        super(prisma, {
+            tableName: "user",
+            pkName: "id",
+            relations: {
+                address: { mode: "oto", pk: "id", restriction: "set" },
+                posts: { mode: "otm", pk: "id", restriction: "add" },
+            },
+            requiredWhere: { active: true },
+            build: {
+                showWorking: false,
+                baseMethods: {
+                    save: { ignoreRequiredWhere: true },
+                },
+            },
+        });
+    }
+}
+```
+
+**Parâmetros genéricos:**
+
+| Parâmetro                 | Descrição                                                                                                                                                                              |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TEntity`                 | O tipo completo da entidade, incluindo as relações que você quer disponíveis                                                                                                           |
+| `UName`                   | O nome do modelo no Prisma como string literal (capitalizado, ex.: `"User"`)                                                                                                           |
+| `VPKType`                 | O tipo da chave primária (`string`, `number`, etc.)                                                                                                                                    |
+| `WRelations` *(opcional)* | Um objeto de flags indicando quais campos são relações (ex.: `{ address: true }`). Só é necessário se você for configurar as relações do repository — caso contrário, pode ser omitido |
+
+---
+
+## O decorator @DynamicMethod
+
+Declare métodos dinâmicos como campos de classe usando `declare` e decore-os com `@DynamicMethod()`:
+
+```typescript
+class UserRepository extends DynamicRepository<User, "User", string> {
+    // Método dinâmico simples - o nome determina o comportamento
+    @DynamicMethod()
+    declare findByEmail: (email: string) => Promise<User | null>;
+
+    // Com configuração do decorator
+    @DynamicMethod<"User">({ proxyTo: "findMany", pushWhere: { active: false } })
+    declare findDisabled: () => Promise<User[]>;
+
+    // Proxy para outro método
+    @DynamicMethod<"User">({ proxyTo: "findOneByEmail", whereType: "overwrite" })
+    declare findInternalByEmail: (email: string) => Promise<User | null>;
+}
+```
+
+O **nome** do método determina o comportamento (mesmas regras da abordagem funcional). O objeto de configuração do decorator ajusta esse comportamento.
+
+> **Importante:** Sempre use `declare` (não uma propriedade comum) para campos decorados. O decorator fornece metadados em tempo de execução; a palavra-chave `declare` informa ao TypeScript que a propriedade existe sem emitir código de inicialização.
+
+---
+
+## Opções de configuração do decorator
+
+O decorator `@DynamicMethod<M>()` aceita um objeto de configuração opcional:
+
+```typescript
+@DynamicMethod<"User">({
+    proxyTo: "findByEmail",                   // Delega para outro padrão de método
+    whereType: "overwrite",                   // "extending" (padrão) ou "overwrite"
+    pushWhere: { active: false },             // Cláusula where extra
+    injectOrdering: [{ name: "asc" }],        // Ordenação fixa
+    injectPagination: { skip: 0, take: 10 },  // Paginação fixa
+})
+```
+
+| Opção              | Tipo                         | Descrição                                                                                                                      |
+| ------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `proxyTo`          | `string`                     | Delega para outro padrão de método válido (ex.: `"findOneByEmail"`)                                                            |
+| `whereType`        | `"extending" \| "overwrite"` | `extending` combina com `requiredWhere`; `overwrite` o ignora                                                                  |
+| `pushWhere`        | `WhereModel<M>`              | Cláusula `where` extra adicionada além do `requiredWhere`                                                                      |
+| `injectOrdering`   | `OrderingModel<M>`           | Ordenação fixa injetada na query                                                                                               |
+| `injectPagination` | `PaginationModel<M>`         | Paginação fixa injetada na query                                                                                               |
+| `fbMode`           | `"one" \| "list"`            | **Deprecated.** Relevante apenas para métodos com prefixo `findBy`. Use `findOneBy` em vez disso se quiser um resultado único. |
+
+---
+
+## O decorator @QueryMethod
+
+`@QueryMethod` declara um **método de SQL bruto** em um campo de classe com `declare`, contornando totalmente o parser de nomes usado por `@DynamicMethod`. É útil para consultas complexas (joins pesados, CTEs, funções específicas do banco) que não são práticas de expressar com os prefixos/sufixos padrão.
+
+Por baixo dos panos, a SQL é executada via Prisma usando `$queryRawUnsafe` (leitura) ou `$executeRawUnsafe` (escrita), e os valores passados em `args` são injetados como **parâmetros posicionais** (`$1`, `$2`, ...) — a mesma técnica de *prepared statements* usada pelo próprio Prisma. Os valores nunca são concatenados na string SQL, o que é o que efetivamente previne SQL Injection.
+
+```typescript
+class UserRepository extends DynamicRepository<User, "User", string> {
+    // Query method de leitura (não-modifying) — o tipo de retorno vem da declaração do campo
+    @QueryMethod('SELECT * FROM "user" WHERE email = $1')
+    declare findByEmailRaw: (arg: QueryMethodArg<[email: string]>) => Promise<User[]>;
+
+    // Query method de escrita — deve sempre resolver para 'number'
+    @QueryMethod('UPDATE "user" SET active = true WHERE id = $1', { modifying: true })
+    declare activateUser: (arg: QueryMethodArg<[id: string]>) => Promise<number>;
+}
+
+const userRepository = new UserRepository(prisma, { tableName: "user", pkName: "id" });
+
+const usuarios = await userRepository.findByEmailRaw({ args: ["joao@email.com"] });
+const afetados = await userRepository.activateUser({ args: ["1"] });
+```
+
+> [!WARNING]
+> `$1`, `$2`, ... devem sempre representar **valores**, nunca nomes de colunas/tabelas ou trechos de SQL dinâmicos. Nomes de identificadores não podem ser passados como parâmetro posicional — se um método precisar variar isso, monte a SQL a partir de um conjunto fixo e conhecido de opções no seu próprio código, nunca a partir de entrada não confiável.
+
+Como `@QueryMethod` pula o parsing de nome, não há inferência automática de tipos para o campo: os tipos de parâmetro e retorno do método vêm inteiramente de como você declara o campo com `declare`. Use `QueryMethodArg<T>` para tipar o único argumento `{ args, db? }` recebido pelo método.
+
+| Opção                  | Tipo      | Padrão  | Descrição                                                                                                                                               |
+| ---------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value` (1º argumento) | `string`  | —       | **Obrigatório.** SQL bruto a ser executado. Use `$1`, `$2`, ... para os placeholders de `args`.                                                         |
+| `options.modifying`    | `boolean` | `false` | Quando `true`, executa via `$executeRawUnsafe`; o campo deve ser declarado retornando `Promise<number>`. Quando `false`, executa via `$queryRawUnsafe`. |
+
+> [!NOTE]
+> `@QueryMethod` ignora todos os outros conceitos de método dinâmico — `requiredWhere`, `pushWhere`, `whereType`, `selectModels`/`includeModels`, `injectOrdering`, `injectPagination`. Nada disso se aplica aqui.
+
+---
+
+## Métodos base
+
+Todas as instâncias de `DynamicRepository` incluem automaticamente estes métodos:
+
+| Método                | Descrição                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `get(pk)`             | Busca um registro pela chave primária                                                                         |
+| `getOrThrow(pk)`      | Busca pela PK, lança erro se não encontrado                                                                   |
+| `getList(pks)`        | Busca múltiplos registros pelas PKs                                                                           |
+| `save(obj)`           | Cria ou faz upsert de um registro                                                                             |
+| `saveList(objs)`      | Salva em lote em uma transação automática                                                                     |
+| `patch(pk, obj)`      | Atualização parcial pela PK                                                                                   |
+| `patchList(tuples)`   | Atualização parcial em lote via tuplas `[pk, obj]`                                                            |
+| `merge(pk, obj)`      | Busca e faz deep-merge em memória (não persiste)                                                              |
+| `remove(pk)`          | Apaga um registro pela PK                                                                                     |
+| `removeList(pks)`     | Apaga em lote pelas PKs                                                                                       |
+| `getAll()`            | Busca todos os registros (respeita `requiredWhere`). Aceita `pagination` e `order` em `options` — veja abaixo |
+| `total()`             | Conta todos os registros                                                                                      |
+| `has(pk)`             | Verifica se um registro existe                                                                                |
+| `softRemove(pk)`      | Soft-delete (requer configuração de `softRemovekName`)                                                        |
+| `softRemoveList(pks)` | Soft-delete em lote                                                                                           |
+| `restore(pk)`         | Restaura registro com soft-delete                                                                             |
+| `restoreList(pks)`    | Restauração em lote                                                                                           |
+
+Todos os métodos aceitam um argumento opcional `options` baseado em `DynamicMethodOptions` (`db`, `see`, `include`, `select`), mas alguns métodos restringem esse tipo:
+
+- **`getAll`** aceita adicionalmente `pagination?: PaginationOptions` e `order?: OrderingModel<UName>` (usa `defaultOrdering` quando omitido).
+- **`saveList` / `patchList`** omitem `include` e `select`, e `db` só aceita uma `DbTransaction` (o retorno de `prisma.$transaction`) — não o client Prisma comum.
+- **`removeList`, `total`, `has`** omitem `include` e `select`.
+- **`softRemove`, `restore`** omitem `see` (a visibilidade de soft-delete não se aplica ao registro sendo alterado).
+- **`softRemoveList`, `restoreList`** omitem `see`, `include` e `select`.
+
+```typescript
+// getAll com paginação e ordenação
+const page = await userRepository.getAll({
+    pagination: { skip: 0, take: 20 },
+    order: { createdAt: "desc" },
+});
+```
+
+---
+
+## Trabalhando com relações
+
+Configure as relações no construtor para que `save` e `patch` as gerenciem automaticamente:
+
+```typescript
+class UserRepository extends DynamicRepository<
+    User, "User", string,
+    { address: true; posts: true }
+> {
+    constructor(prisma: PrismaClient) {
+        super(prisma, {
+            tableName: "user",
+            pkName: "id",
+            relations: {
+                address: { mode: "oto", pk: "id", restriction: "set" },
+                posts: { mode: "otm", pk: "id", restriction: "add" },
+            },
+        });
+    }
+}
+```
+
+O quarto parâmetro genérico (`WRelations`) é **opcional** — só é necessário quando você for configurar as relações do repository. Quando fornecido, ele deve sinalizar quais campos são relações. Isso garante que `DynamicSaveInput` e `DynamicPatchInput` resolvam esses campos para o formato de payload aninhado de create/update do Prisma. Se o seu repository não gerenciar nenhuma relação, você pode simplesmente omitir esse parâmetro.
+
+**Modos de relação:** `oto` (um-para-um), `otm` (um-para-muitos), `mto` (muitos-para-um), `mtm` (muitos-para-muitos).
+
+**Restrições:** `set` (substitui tudo) ou `add` (adiciona/atualiza sem remover).
+
+Veja o [README.pt-BR.md](./README.pt-BR.md#relações-no-save) principal para todos os detalhes sobre o comportamento das relações.
+
+---
+
+## Transações
+
+Todos os métodos aceitam `{ db: tx }` para participar de uma transação:
+
+```typescript
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.save(
+        { name: "Mary", email: "mary@email.com", password: "password" },
+        { db: tx }
+    );
+
+    await postRepository.save(
+        { title: "First Post", authorId: user.id },
+        { db: tx }
+    );
+});
+```
+
+Acesse o client do Prisma via `repository.prisma`.
+
+---
+
+## Trabalhando com includes
+
+`DynamicRepository` não suporta `includeModels` (presets nomeados), mas você pode usar um `include` bruto do Prisma via `DynamicMethodOptions`:
+
+```typescript
+// Incluir apenas address
+const user = await userRepository.get(id, {
+    include: { address: true },
+});
+
+// Include aninhado
+const userFull = await userRepository.get(id, {
+    include: {
+        address: true,
+        posts: { include: { tags: true } },
+    },
+});
+
+// Funciona em qualquer método que aceite options
+const all = await userRepository.getAll({
+    include: { posts: true },
+});
+```
+
+---
+
+## DynamicMethodOptions
+
+Todo método base e todo método dinâmico decorado aceita um segundo argumento opcional do tipo `DynamicMethodOptions`. Esse objeto tem quatro campos opcionais:
+
+```typescript
+type DynamicMethodOptions<TName extends PrismaModelName> = {
+    db?: ClientOrTransaction;          // Client ou transação do Prisma
+    see?: "active" | "removed" | "all"; // Visibilidade do soft-delete
+    include?: IncludeModel<TName>;      // Include bruto do Prisma
+    select?: SelectModel<TName>;        // Select bruto do Prisma
+};
+```
+
+> `include` e `select` são mutuamente exclusivos. Diferente da API funcional `setupVSRepo`, o tipo de options mais simples do `DynamicRepository` não garante isso em tempo de compilação — passar os dois gera um `VSRepoRuntimeError` em tempo de execução.
+
+### `db` — Usando uma transação
+
+Passe `{ db: tx }` para direcionar uma única chamada de método para dentro de uma transação existente:
+
+```typescript
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.save(
+        { name: "Mary", email: "mary@email.com", password: "password" },
+        { db: tx },
+    );
+
+    await postRepository.save(
+        { title: "First Post", authorId: user.id },
+        { db: tx },
+    );
+});
+```
+
+Você também pode usar a transação para leituras:
+
+```typescript
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.get(id, { db: tx });
+    const total = await userRepository.total({ db: tx });
+});
+```
+
+### `see` — Visibilidade do soft-delete
+
+Se `softRemovekName` estiver configurado, o campo `see` controla quais registros ficam visíveis:
+
+| Valor               | Comportamento                    |
+| ------------------- | -------------------------------- |
+| `"active"` (padrão) | Apenas registros não removidos   |
+| `"removed"`         | Apenas registros com soft-delete |
+| `"all"`             | Registros ativos e removidos     |
+
+```typescript
+// Busca apenas usuários com soft-delete
+const deleted = await userRepository.getAll({ see: "removed" });
+
+// Busca todos os usuários, incluindo os com soft-delete
+const all = await userRepository.getAll({ see: "all" });
+
+// Restaura um usuário com soft-delete buscando-o primeiro
+const [removed] = await userRepository.getAll({ see: "removed", include: { address: true } });
+```
+
+### `include` — Include bruto do Prisma
+
+Use `include` para carregar relações de forma antecipada (eager loading) em qualquer chamada de método. É o equivalente ao `includeModels` da abordagem funcional, mas com a sintaxe bruta de include do Prisma:
+
+```typescript
+// Include simples
+const user = await userRepository.get(id, {
+    include: { address: true },
+});
+
+// Include aninhado
+const userFull = await userRepository.get(id, {
+    include: {
+        address: true,
+        posts: { include: { author: true } },
+    },
+});
+
+// Também funciona em métodos dinâmicos
+const admin = await userRepository.findAdminByEmail(email, {
+    include: { address: true, posts: true },
+});
+```
+
+### `select` — Select bruto do Prisma
+
+Use `select` para projetar um conjunto específico de campos em qualquer chamada de método. É o equivalente ao `selectModels` da abordagem funcional, mas com a sintaxe bruta de select do Prisma:
+
+```typescript
+// Select simples
+const user = await userRepository.get(id, {
+    select: { id: true, email: true },
+});
+
+// Também funciona em métodos dinâmicos
+const admin = await userRepository.findAdminByEmail(email, {
+    select: { id: true, email: true },
+});
+```
+
+> Como o `DynamicRepository` não tem estreitamento de tipo orientado por `selectModels`/`selectedModel`, o tipo de retorno permanece `TEntity` independentemente do `select` passado — o resultado em tempo de execução conterá apenas os campos selecionados, mas o TypeScript não vai estreitar isso para você. Faça cast ou desestruture conforme necessário.
+
+### Combinando opções
+
+`db` e `see` podem ser combinados livremente com `include` ou `select` (mas não com os dois juntos):
+
+```typescript
+// Dentro de uma transação, busca um usuário com relações, incluindo os com soft-delete
+await userRepository.prisma.$transaction(async (tx) => {
+    const user = await userRepository.get(id, {
+        db: tx,
+        see: "all",
+        include: { address: true, posts: true },
+    });
+});
+```
+
+---
+
+## Integração com NestJS
+
+`DynamicRepository` funciona naturalmente com a injeção de dependência do NestJS.
+
+### Provider do repositório
+
+```typescript
+// src/modules/user/user.repository.ts
+import { Injectable } from "@nestjs/common";
+import { PrismaService } from "../../database/prisma.service";
+import { DynamicRepository, DynamicMethod, DynamicMethodOptions } from "../../../generated/vsrepo";
+
+type User = /* Prisma UserGetPayload com relações */;
+
+@Injectable()
+class UserRepository extends DynamicRepository<User, "User", string, { profile: true }> {
+    constructor(prisma: PrismaService) {
+        super(prisma, {
+            tableName: "user",
+            pkName: "id",
+            relations: {
+                profile: { mode: "oto", pk: "id", restriction: "add" },
+            },
+            build: {
+                baseMethods: {
+                    save: { ignoreRequiredWhere: true },
+                },
+            },
+        });
+    }
+
+    @DynamicMethod()
+    declare findByEmail: (email: string, options?: DynamicMethodOptions<"User">) => Promise<User | null>;
+}
+
+```
+
+### Registrando o módulo
+
+```typescript
+// src/modules/user/user.module.ts
+import { Module } from "@nestjs/common";
+import { UserRepository } from "./user.repository";
+import { UserService } from "./user.service";
+import { UserController } from "./user.controller";
+
+@Module({
+    providers: [UserRepository, UserService],
+    controllers: [UserController],
+    exports: [UserService],
+})
+export class UserModule {}
+```
+
+### Usando em um service
+
+```typescript
+// src/modules/user/user.service.ts
+import { Injectable, Inject } from "@nestjs/common";
+import { UserRepository } from "./user.repository";
+
+@Injectable()
+export class UserService {
+    constructor(
+        private readonly userRepository: UserRepository,
+    ) {}
+
+    async getUserById(id: string) {
+        return this.userRepository.get(id);
+    }
+
+    async getUserAuthByEmailWithProfile(email: string) {
+        return this.userRepository.findByEmail(email, { include: { profile: true } });
+    }
+
+    async createUser(data: { email: string; password: string; name: string }) {
+        return this.userRepository.save({
+            email: data.email,
+            password: data.password,
+            name: data.name,
+        });
+    }
+}
+```
+
+---
+
+## Referência da API
+
+### `DynamicRepository<TEntity, UName, VPKType, WRelations>`
+
+```typescript
+abstract class DynamicRepository<
+    TEntity extends object,
+    UName extends PrismaModelName,
+    VPKType,
+    WRelations extends Partial<Record<keyof TEntity, true>> | undefined = undefined,
+>
+```
+
+> `WRelations` é opcional (o padrão é `undefined`) e só precisa ser informado quando você for configurar as relações do repository.
+
+**Construtor:**
+
+```typescript
+constructor(prisma: DbClient, config: DynamicRepositoryConstructorConfig<TEntity, UName>)
+```
+
+### DynamicRepositoryConstructorConfig
+
+| Propriedade          | Tipo                           | Descrição                       |
+| -------------------- | ------------------------------ | ------------------------------- |
+| `tableName`          | `Uncapitalize<UName>`          | Nome da tabela no Prisma        |
+| `pkName`             | `keyof TEntity`                | Campo da chave primária         |
+| `softRemovekName?`   | `keyof TEntity`                | Campo DateTime para soft-delete |
+| `requiredWhere?`     | `WhereModel<UName>`            | Filtros globais                 |
+| `defaultOrdering?`   | `OrderingModel<UName>`         | Ordenação padrão                |
+| `relations?`         | `RepositoryRelations<TEntity>` | Configuração de relações        |
+| `build?`             | `DynamicRepositoryBuildConfig` | Opções de build                 |
+
+### DynamicRepositoryBuildConfig
+
+| Propriedade    | Tipo                                                | Descrição                             |
+| -------------- | --------------------------------------------------- | ------------------------------------- |
+| `showWorking?` | `boolean`                                           | Exibe logs internos (padrão: `false`) |
+| `baseMethods?` | `Record<string, { ignoreRequiredWhere?: boolean }>` | Configuração por método               |
+
+### @DynamicMethod\<M>(config?)
+
+```typescript
+function DynamicMethod<M extends PrismaModelName>(
+    config?: DynamicMethodConfig<M>,
+): PropertyDecorator;
+```
+
+### DynamicMethodOptions\<TName>
+
+| Propriedade | Tipo                             | Descrição                             |
+| ----------- | -------------------------------- | ------------------------------------- |
+| `db?`       | `ClientOrTransaction`            | Client ou transação do banco de dados |
+| `see?`      | `"active" \| "removed" \| "all"` | Visibilidade do soft-delete           |
+| `include?`  | `IncludeModel<TName>`            | Include bruto do Prisma               |
+| `select?`   | `SelectModel<TName>`             | Select bruto do Prisma                |
+
+### @QueryMethod(value, options?)
+
+```typescript
+function QueryMethod(value: string, options?: QueryMethodOptions): PropertyDecorator;
+```
+
+### QueryMethodArg\<T>
+
+| Propriedade | Tipo                  | Descrição                                                                  |
+| ----------- | --------------------- | -------------------------------------------------------------------------- |
+| `args`      | `T` (tupla)           | Parâmetros posicionais injetados nos placeholders da SQL (`$1`, `$2`, ...) |
+| `db?`       | `ClientOrTransaction` | Client de transação para executar essa query                               |
+
+### QueryMethodOptions
+
+| Propriedade  | Tipo      | Padrão  | Descrição                                                                                                               |
+|------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `modifying?` | `boolean` | `false` | `true` executa via `$executeRawUnsafe` (o campo deve retornar `Promise<number>`); `false` executa via `$queryRawUnsafe` |
+
+---
+
+## Diferenças em relação ao setupVSRepo
+
+| Aspecto                    | `setupVSRepo`                                    | `DynamicRepository`                                           |
+| -------------------------- | ------------------------------------------------ | ------------------------------------------------------------- |
+| **Estilo**                 | Funcional / curried                              | OOP / baseado em classes                                      |
+| **Métodos definidos via**  | Objeto de configuração `methods`                 | Decorators `@DynamicMethod()`                                 |
+| **selectModels**           | Suportado                                        | Não suportado                                                 |
+| **includeModels**          | Suportado                                        | Não suportado                                                 |
+| **Select padrão**          | Configuração `defaultSelectModel`                | Não disponível                                                |
+| **Etapa de build**         | `.build(prisma)` explícito                       | Automático no construtor                                      |
+| **Toggles de método base** | `active`, `defaultSelect` por método             | Sempre ativo, sem defaultSelect                               |
+| **Instância do Prisma**    | Passada no `.build()`                            | Passada para `super()` no construtor                          |
+| **Extensibilidade**        | Método `.extend()`                               | Herança de classe                                             |
+| **Includes brutos**        | Via `options.include`                            | Via `DynamicMethodOptions.include`                            |
+| **Selects brutos**         | Via `options.select` (com estreitamento de tipo) | Via `DynamicMethodOptions.select` (sem estreitamento de tipo) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vsrepo",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "A repository pattern library for Prisma",
   "homepage": "https://github.com/jaobrabo123/VSRepository#readme",
   "repository": {
@@ -34,7 +34,11 @@
   "type": "commonjs",
   "files": [
     "dist",
-    "scripts"
+    "scripts",
+    "README.md",
+    "README.pt-BR.md",
+    "README-DynamicRepo.md",
+    "README-DynamicRepo.pt-BR.md"
   ],
   "bin": {
     "vsrepo": "scripts/configure-prisma-import.mjs"

package/scripts/configure-prisma-import.mjs

@@ -236,16 +236,29 @@ for (const file of tsFiles) {
   console.log(`Gerado: ${path.relative(workspaceRoot, targetFile)}`);
 }
 
-// Copia o README.md do pacote VSRepository para o diretório de output, se existir
-// const readmeSource = path.join(packageRoot, 'README.md');
-// const readmeTarget = path.join(outputDir, 'README.md');
-
-// if (fs.existsSync(readmeSource)) {
-//   fs.copyFileSync(readmeSource, readmeTarget);
-//   console.log(`Gerado: ${path.relative(workspaceRoot, readmeTarget)}`);
-// } else {
-//   console.warn(`README.md do VSRepository nao encontrado em: ${path.relative(workspaceRoot, readmeSource)}. Ignorando a copia.`);
-// }
+// Copia os READMEs da raiz do PACOTE vsrepo (nao do projeto do consumidor)
+// para a pasta 'docs' do diretório de output.
+const readmeFiles = [
+  'README.md',
+  'README.pt-BR.md',
+  'README-DynamicRepo.md',
+  'README-DynamicRepo.pt-BR.md',
+];
+
+const readmeOutputDir = path.join(outputDir, 'docs');
+fs.mkdirSync(readmeOutputDir, { recursive: true });
+
+for (const fileName of readmeFiles) {
+  const readmeSource = path.join(packageRoot, fileName);
+  const readmeTarget = path.join(readmeOutputDir, fileName);
+
+  if (fs.existsSync(readmeSource)) {
+    fs.copyFileSync(readmeSource, readmeTarget);
+    console.log(`Gerado: ${path.relative(workspaceRoot, readmeTarget)}`);
+  } else {
+    console.warn(`README nao encontrado no pacote em: ${readmeSource}. Ignorando a copia.`);
+  }
+}
 
 console.log('\nVSRepository gerado com tipagem do Prisma.');
 console.log(`Output: ${path.relative(workspaceRoot, outputDir)}`);