vsrepo 1.4.2 → 2.1.0

package/README-DynamicRepo.md

@@ -1,625 +0,0 @@
-# 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) |