vsrepo 1.3.3 → 1.3.4

package/README.md

@@ -4,6 +4,8 @@
 ![NPM License](https://img.shields.io/npm/l/vsrepo?style=flat-square)
 ![NPM Downloads](https://img.shields.io/npm/dt/vsrepo?style=flat-square)
 
+🇺🇸 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**.
 
 VSRepository lets you create strongly-typed repositories with:
@@ -34,6 +36,7 @@ VSRepository lets you create strongly-typed repositories with:
   - [Configuring the base methods](#configuring-the-base-methods)
 - [Select Models](#select-models)
 - [Include Models](#include-models)
+  - [Raw include (options.include)](#raw-include-optionsinclude)
 - [Required Where](#required-where)
 - [Default Ordenation](#default-ordenation)
 - [`see` option](#see-option)
@@ -46,6 +49,7 @@ VSRepository lets you create strongly-typed repositories with:
   - [Distinct](#distinct)
   - [Method configuration](#method-configuration)
   - [Aggregate and GroupBy](#aggregate-and-groupby)
+  - [Query Methods](#query-methods)
 - [Relations in save](#relations-in-save)
 - [Transactions](#transactions)
 - [Extending a repository](#extending-a-repository)
@@ -181,7 +185,7 @@ await userRepository.remove(user.id);
 
 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)** for full documentation on the class-based approach, including NestJS integration examples, decorator config, and a comparison with `setupVSRepo`.
+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`.
 
 ---
 
@@ -572,6 +576,35 @@ await userRepository.get(id, { selectModel: "public" });
 await userRepository.get(id, { selectModel: "public", includeModel: "withPosts" });
 ```
 
+### 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
+const user = await userRepository.get(id, {
+  include: { posts: true, profile: 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
@@ -1022,6 +1055,7 @@ Each entry in `methods` accepts the following options:
 | `pushWhere`           | `WhereModel<M>`                    | —              | Extra `where` added to the query in addition to `requiredWhere`.                                                   |
 | `injectOrdenation`    | `OrdenationModel<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). |
 
 ---
 
@@ -1044,6 +1078,77 @@ const userRepository = setupVSRepo<User, "user">()(({
 
 ---
 
+### 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:**
+
+Every Query Method takes a single argument shaped as `{ args: [...], db? }`:
+
+```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],
+});
+
+// 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,
+  });
+});
+```
+
+| 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`, `injectOrdenation`, `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).
+
+---
+
 ## Relations in save
 
 Configure relations so that `save` and `patch` manage them automatically (`saveList` and `patchList` also manage relations automatically).
@@ -1438,9 +1543,9 @@ Recommended `tsconfig.json`:
 
 **Select model returns unexpected fields** — Check that the select model defines exactly the fields your TypeScript type expects.
 
-**`selectModel` and `includeModel` together in the same call** — Not allowed. Choose one or the other: if `includeModel` is provided, the `select` (including `defaultSelectModel`) is ignored and only the `include` is sent to Prisma.
+**`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`.
+**`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.